@event4u/agent-switch 2.0.0 → 2.2.0

package/dist/balance.js

@@ -0,0 +1,52 @@
+/**
+ * Which account a start should use when several could: the one that would
+ * lose the most of its rest at its next reset. An account's "need" is the rest
+ * of its longest window divided by the hours until that window resets — the
+ * pace it would have to be used at to run dry exactly at the reset. Using the
+ * highest need first spreads the work so every account is spent by its reset
+ * instead of one running out while another resets unused.
+ *
+ * An account at its limit in any window (at or over its protection threshold)
+ * can't take work now and is never picked. Accounts whose needs are level
+ * (within {@link LEVEL_TOLERANCE}) are a tie the caller breaks — plain starts
+ * prefer the plain-start account, pools a member without a live session.
+ */
+const HOUR_MS = 3_600_000;
+/** A window without a reset time is assumed to reset a full week out. */
+const UNKNOWN_RESET_H = 7 * 24;
+/** Needs closer than this (relative) count as level. */
+export const LEVEL_TOLERANCE = 0.05;
+function longest(windows) {
+    const known = windows.filter((w) => typeof w.utilization === "number");
+    if (!known.length)
+        return null;
+    const withReset = known.filter((w) => w.resetsAt && !isNaN(Date.parse(w.resetsAt)));
+    if (withReset.length)
+        return withReset.reduce((a, b) => (Date.parse(b.resetsAt) > Date.parse(a.resetsAt) ? b : a));
+    return known.reduce((a, b) => (b.utilization > a.utilization ? b : a));
+}
+export function weigh(snapshot, now, thresholdPct) {
+    const capped = snapshot.windows.find((w) => typeof w.utilization === "number" && w.utilization >= thresholdPct);
+    if (capped)
+        return { usable: false, why: `at ${capped.utilization}% of its ${windowName(capped)} window (limit ${thresholdPct}%)` };
+    const w = longest(snapshot.windows);
+    if (!w)
+        return { usable: false, why: "usage unknown" };
+    const rest = Math.max(0, 100 - w.utilization);
+    const resetH = w.resetsAt && !isNaN(Date.parse(w.resetsAt)) ? Math.max(1, (Date.parse(w.resetsAt) - now) / HOUR_MS) : null;
+    return { usable: true, need: rest / (resetH ?? UNKNOWN_RESET_H), rest, resetH, window: windowName(w), key: w.key };
+}
+const WINDOW_NAME = { five_hour: "5h", seven_day: "7d", monthly: "30d" };
+/** Named by key: a window read back from the usage history carries its key as label. */
+function windowName(w) {
+    return WINDOW_NAME[w.key] ?? w.label;
+}
+export function level(a, b) {
+    const hi = Math.max(a, b);
+    return hi === 0 || Math.abs(a - b) / hi <= LEVEL_TOLERANCE;
+}
+export function describe(name, w) {
+    const reset = w.resetH == null ? "reset time unknown" : w.resetH >= 48 ? `resets in ${Math.round(w.resetH / 24)} d` : `resets in ${Math.round(w.resetH)} h`;
+    const of = w.key === "seven_day" ? "the week" : `its ${w.window} window`;
+    return `${name}: ${Math.round(w.rest)}% of ${of} left, ${reset} (${w.need.toFixed(1)} %/h to use it up)`;
+}

package/dist/browsers.js

@@ -0,0 +1,90 @@
+/**
+ * Which browser a provider's sign-in opens in. Claude Code opens its OAuth page
+ * with `$BROWSER` when set (verified against CC 2.1.312: it spawns the value as
+ * ONE executable with the URL as its only argument — `open -a X` in the
+ * variable is not run). So on macOS the choice becomes a tiny wrapper script
+ * that hands the URL to that app; on Linux the browser binary itself is the
+ * executable. Windows is not offered: nothing here has verified an override.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+const MAC = [
+    { id: "safari", name: "Safari", app: "Safari" },
+    { id: "chrome", name: "Google Chrome", app: "Google Chrome" },
+    { id: "chrome-canary", name: "Google Chrome Canary", app: "Google Chrome Canary" },
+    { id: "firefox", name: "Firefox", app: "Firefox" },
+    { id: "firefox-dev", name: "Firefox Developer Edition", app: "Firefox Developer Edition" },
+    { id: "arc", name: "Arc", app: "Arc" },
+    { id: "brave", name: "Brave", app: "Brave Browser" },
+    { id: "edge", name: "Microsoft Edge", app: "Microsoft Edge" },
+    { id: "vivaldi", name: "Vivaldi", app: "Vivaldi" },
+    { id: "opera", name: "Opera", app: "Opera" },
+    { id: "chromium", name: "Chromium", app: "Chromium" },
+    { id: "zen", name: "Zen", app: "Zen" },
+    { id: "orion", name: "Orion", app: "Orion" },
+    { id: "dia", name: "Dia", app: "Dia" },
+    { id: "librewolf", name: "LibreWolf", app: "LibreWolf" },
+];
+const LINUX = [
+    { id: "chrome", name: "Google Chrome", bins: ["google-chrome", "google-chrome-stable"] },
+    { id: "chromium", name: "Chromium", bins: ["chromium", "chromium-browser"] },
+    { id: "firefox", name: "Firefox", bins: ["firefox"] },
+    { id: "brave", name: "Brave", bins: ["brave-browser", "brave"] },
+    { id: "edge", name: "Microsoft Edge", bins: ["microsoft-edge", "microsoft-edge-stable"] },
+    { id: "vivaldi", name: "Vivaldi", bins: ["vivaldi", "vivaldi-stable"] },
+    { id: "librewolf", name: "LibreWolf", bins: ["librewolf"] },
+];
+/** The .app bundle (macOS) or binary (Linux) for a browser id; null when it is
+ *  unknown or not installed. */
+export function locateBrowser(id, deps) {
+    if (deps.platform === "darwin") {
+        const b = MAC.find((x) => x.id === id);
+        if (!b)
+            return null;
+        // macOS paths are POSIX whatever platform runs this (tests run on Windows too).
+        for (const dir of ["/Applications", path.posix.join(deps.home, "Applications")]) {
+            const app = path.posix.join(dir, `${b.app}.app`);
+            if (deps.exists(app))
+                return app;
+        }
+        return null;
+    }
+    if (deps.platform === "linux") {
+        const b = LINUX.find((x) => x.id === id);
+        for (const bin of b?.bins ?? []) {
+            const p = deps.which(bin);
+            if (p)
+                return p;
+        }
+        return null;
+    }
+    return null;
+}
+export function listBrowsers(deps) {
+    const known = deps.platform === "darwin" ? MAC : deps.platform === "linux" ? LINUX : [];
+    return known.filter((b) => locateBrowser(b.id, deps) !== null).map(({ id, name }) => ({ id, name }));
+}
+/** POSIX wrapper for `$BROWSER` that opens its URL argument in one macOS app. */
+export function browserWrapperScript(appPath) {
+    const quoted = `'${appPath.replace(/'/g, `'\\''`)}'`;
+    return `#!/bin/sh\nexec /usr/bin/open -a ${quoted} "$@"\n`;
+}
+function whichOnPath(binary) {
+    for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const p = path.join(dir, binary);
+        try {
+            fs.accessSync(p, fs.constants.X_OK);
+            if (fs.statSync(p).isFile())
+                return p;
+        }
+        catch {
+            /* not here */
+        }
+    }
+    return null;
+}
+export function defaultBrowserDeps(home) {
+    return { platform: process.platform, home, exists: (p) => fs.existsSync(p), which: whichOnPath };
+}

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/daemon.js

@@ -1,7 +1,10 @@
 /**
  * Background usage daemon — poller, cache, and (opt-in) threshold notifier.
  *
- * It polls Claude profiles for their OWN usage, appends history, detects
+ * It polls Claude and Codex profiles for their OWN usage — the active one, any
+ * with a live session, and the members of pools a folder rule targets (spaced
+ * to {@link POOL_POLL_INTERVAL_MS}, so `dir`'s pool pick has fresh numbers) —
+ * appends history, detects
  * active-profile threshold crossings, and writes `daemon-state.json` so
  * `status`/the GUI can read a fresh snapshot without hitting the API. When
  * `autoSwitch.enabled` (default OFF) it also watches every profile and, once the
@@ -10,19 +13,25 @@
  * suggestion is a convenience; the actual switch is always a user interaction
  * (see `AutoSwitchConfig`). The daemon never mutates the active profile.
  *
+ * Codex banked resets: when the active Codex profile is over the threshold and
+ * holds a reset credit, the daemon NOTIFIES that one is available (once per
+ * reset cycle). It never redeems one — that is an explicit user action
+ * (`agent-switch reset`, or the GUI's confirmed button). It also fires the
+ * per-profile protection notice (see `protection.ts`): a warning only, nothing
+ * is paused or switched.
+ *
  * The pure helpers (single-instance, poll-target selection, backoff, state
  * freshness, suggestion decision in `usage.ts`) are exported for unit testing;
  * `runDaemon` is the loop.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { ROOT, activeFor, configDir, labelFor, listProfiles, readAutoSwitch, readBinaryPath } from "./profiles.js";
+import { ROOT, activeFor, configDir, isDisabled, labelFor, listProfiles, readAutoSwitch, readBinaryPath } from "./profiles.js";
 import { profileDir } from "./profiles.js";
 import { fetchUsage, liveSessionPids } from "./api.js";
 import { defaultFreshenDeps, freshAccessToken } from "./token-freshen.js";
 import { parseUsage, detectCrossings, pickSwitchTarget, maxUtilization } from "./usage.js";
 import { readCodexUsage } from "./codex-usage.js";
-import { redeemResetCredit } from "./codex-reset.js";
 import { recordHistorySample } from "./history.js";
 import { appendNotification, markOsNotified } from "./notifications.js";
 import { readOsNotifications } from "./profiles.js";
@@ -31,6 +40,7 @@ import { listSessions, listCodexSessions, markLive } from "./sessions.js";
 import { readContext } from "./telemetry.js";
 import { readTelemetryConfig, detectContextCrossings, coalesce, } from "./notify.js";
 import { readEvents, eventFile } from "./hooks.js";
+import { protectionNotice, readProtection } from "./protection.js";
 import { execFileSync } from "node:child_process";
 /** Append an event to the shared log and, when the operator opted into
  *  daemon-side OS notifications, fire a desktop notification too — marking the
@@ -113,13 +123,23 @@ export function releaseSingleInstance(myPid, file = PIDFILE) {
     }
 }
 // ---------- poll discipline ----------
+/** How often a profile that is polled ONLY because a pool rule targets it is
+ *  refreshed. Below {@link FRESH_USAGE_MS} (10 min) so `dir` keeps seeing pool
+ *  members as fresh, yet five times sparser than the active profile's cadence —
+ *  idle pool members cost one usage read per profile every 5 minutes. */
+export const POOL_POLL_INTERVAL_MS = 5 * 60_000;
 /**
- * Which Claude profiles to poll this cycle. Normally the active one plus any
- * with a live session — never a busy-poll of idle accounts. With `watchAll`
+ * Which profiles to poll this cycle. Normally the active one plus any with a
+ * live session — never a busy-poll of idle accounts. With `watchAll`
  * (auto-switch enabled) every profile is polled, since the switch decision
- * needs each candidate's headroom. `liveCheck` is injected for testability.
+ * needs each candidate's headroom. `pooled` profiles (every enabled account:
+ * plain starts and pools are balanced across them) are added too, but only once
+ * their last capture is at least
+ * {@link POOL_POLL_INTERVAL_MS} old — that is what keeps `dir`'s pool pick on
+ * fresh numbers without polling idle accounts every minute. `liveCheck` and
+ * `lastCapturedMs` are injected for testability.
  */
-export function selectPollTargets(claudeNames, active, liveCheck, watchAll = false) {
+export function selectPollTargets(claudeNames, active, liveCheck, watchAll = false, pooled = [], lastCapturedMs = () => null, now = Date.now()) {
     if (watchAll)
         return [...claudeNames];
     const targets = new Set();
@@ -128,6 +148,13 @@ export function selectPollTargets(claudeNames, active, liveCheck, watchAll = fal
     for (const n of claudeNames)
         if (liveCheck(n))
             targets.add(n);
+    for (const n of pooled) {
+        if (!claudeNames.includes(n) || targets.has(n))
+            continue;
+        const last = lastCapturedMs(n);
+        if (last === null || now - last >= POOL_POLL_INTERVAL_MS)
+            targets.add(n);
+    }
     return [...targets];
 }
 /** Exponential backoff on consecutive failures, floored at the base interval
@@ -158,6 +185,28 @@ export function decideThresholdAction(active, polled, autoSwitch, isEligible = (
     const suggestedTarget = target && target !== active ? target : null;
     return { notify: suggestedTarget !== null, suggestedTarget };
 }
+/**
+ * The "a banked Codex reset is available" notice (D3). Pure: returns the notice
+ * when the active profile is at/over the threshold, holds a reset credit, and
+ * this reset cycle was not announced yet — else null. Redeeming stays an
+ * explicit user action (`agent-switch reset`, the GUI's confirmed button).
+ */
+export function codexResetNotice(active, snap, threshold, lastNotifiedCycle) {
+    if ((snap.resetCredits ?? 0) <= 0)
+        return null;
+    const stuck = snap.windows.find((w) => typeof w.utilization === "number" && w.utilization >= threshold);
+    if (!stuck)
+        return null;
+    const cycle = stuck.resetsAt ?? "";
+    if (lastNotifiedCycle === cycle)
+        return null;
+    return {
+        cycle,
+        title: "Codex reset available",
+        message: `codex/${active} hit ≥${threshold}% and has ${snap.resetCredits} banked reset(s). ` +
+            `Nothing was redeemed — to use one: agent-switch reset ${active} --provider codex`,
+    };
+}
 // ---------- context monitoring (own-session; Phase 3) ----------
 let _claudeVer;
 function claudeVer() {
@@ -253,12 +302,19 @@ async function snapshotFor(provider, name) {
     const raw = await fetchUsage(token);
     return raw ? parseUsage(raw) : null;
 }
-async function pollProvider(provider, state, thresholds, redeemed, log) {
-    const names = listProfiles(provider);
+async function pollProvider(provider, state, thresholds, notifiedReset, log) {
+    const names = listProfiles(provider).filter((n) => !isDisabled(provider, n));
     const active = activeFor(provider);
     const autoSwitch = readAutoSwitch(provider);
     const isLive = (n) => (provider === "claude" ? liveSessionPids(configDir("claude", n)).length > 0 : false);
-    const targets = selectPollTargets(names, active, isLive, autoSwitch.enabled);
+    // Every start without a folder rule is balanced across all enabled accounts
+    // (dir-resolve.ts), so each one needs fresh numbers — at the pool cadence.
+    const pooled = names;
+    const lastCaptured = (n) => {
+        const t = Date.parse(state.profiles[`${provider}/${n}`]?.capturedAt ?? "");
+        return isNaN(t) ? null : t;
+    };
+    const targets = selectPollTargets(names, active, isLive, autoSwitch.enabled, pooled, lastCaptured);
     let failures = 0;
     const polled = [];
     state.notifiedFetchFail = state.notifiedFetchFail ?? {};
@@ -286,6 +342,15 @@ async function pollProvider(provider, state, thresholds, redeemed, log) {
         }
         state.profiles[key] = snapshot;
         polled.push({ name, snapshot });
+        // Session protection (per profile, default on at 98 %): a warning only.
+        const pNotice = protectionNotice(key, snapshot, readProtection(provider, name), state.protectionNotified?.[key]);
+        if (pNotice) {
+            state.protectionNotified = { ...(state.protectionNotified ?? {}), [key]: pNotice.cycle };
+            log(`protection: ${pNotice.message}`);
+            // "info", not "warning": the GUI mutes warnings by default (fetch-failure
+            // noise), and a default-on protection notice must actually be seen.
+            notify({ kind: "info", title: pNotice.title, message: pNotice.message });
+        }
         recordHistorySample(path.join(profileDir(provider, name), "usage-history.json"), snapshot);
         if (name === active) {
             const prev = thresholds.get(`${provider}/${name}`) ?? {};
@@ -311,28 +376,15 @@ async function pollProvider(provider, state, thresholds, redeemed, log) {
     const activeMax = activeSnap ? maxUtilization(activeSnap) : null;
     if (activeMax === null || activeMax < autoSwitch.threshold)
         return failures; // still has headroom
-    // Codex only (banked resets are a Codex feature): redeem a reset and STAY, but
-    // AT MOST ONCE per reset cycle. We record the window's resets_at BEFORE calling,
-    // so a buggy reset that doesn't actually clear usage can never loop and burn the
-    // whole balance — it falls through to a switch SUGGESTION on the same poll's
-    // next-cycle. Redeeming still stays on the active profile.
+    // Codex only (banked resets are a Codex feature): a reset credit is scarce and
+    // redeeming it is the user's call (D3) — the daemon only says one is there,
+    // once per reset cycle, and never calls the redeem endpoint itself.
     if (provider === "codex" && activeSnap) {
-        const stuck = activeSnap.windows.find((w) => typeof w.utilization === "number" && w.utilization >= autoSwitch.threshold);
-        const cycle = stuck?.resetsAt ?? "";
-        const guardKey = `codex/${active}`;
-        if ((activeSnap.resetCredits ?? 0) > 0 && redeemed.get(guardKey) !== cycle) {
-            redeemed.set(guardKey, cycle);
-            const r = await redeemResetCredit(configDir("codex", active));
-            if (r.ok) {
-                log(`auto-switch: codex/${active} over ≥${autoSwitch.threshold}% → redeemed a reset (windows_reset=${r.windowsReset ?? "?"}); staying on ${active}`);
-                notify({
-                    kind: "success",
-                    title: "Codex reset redeemed",
-                    message: `codex/${active} hit ≥${autoSwitch.threshold}% — redeemed a banked reset and stayed on ${active}.`,
-                });
-                return failures;
-            }
-            log(`auto-switch: codex/${active} reset redeem failed (${r.reason ?? "?"}) → falling back to a switch suggestion`);
+        const notice = codexResetNotice(active, activeSnap, autoSwitch.threshold, notifiedReset.get(`codex/${active}`));
+        if (notice) {
+            notifiedReset.set(`codex/${active}`, notice.cycle);
+            log(`threshold: codex/${active} over ≥${autoSwitch.threshold}% with a banked reset available → notifying (no automatic redeem)`);
+            notify({ kind: "info", title: notice.title, message: notice.message });
         }
     }
     // Tag filter: only accounts carrying the configured label are eligible switch
@@ -361,10 +413,10 @@ async function pollProvider(provider, state, thresholds, redeemed, log) {
     }
     return failures;
 }
-async function pollOnce(state, thresholds, redeemed, log) {
+async function pollOnce(state, thresholds, notifiedReset, log) {
     let failures = 0;
     for (const provider of AUTO_PROVIDERS) {
-        failures += await pollProvider(provider, state, thresholds, redeemed, log);
+        failures += await pollProvider(provider, state, thresholds, notifiedReset, log);
     }
     state.lastPoll = new Date().toISOString();
     state.lastError = failures > 0 ? `${failures} profile(s) failed to poll` : null;
@@ -396,16 +448,15 @@ export async function runDaemon(opts = {}) {
     // Load persisted usage-window fired state so crossings do NOT re-fire after a
     // daemon restart within the same window cycle (the pre-existing in-memory gap).
     const thresholds = new Map(Object.entries(state.usageThresholds ?? {}));
-    // Anti-loop guard for the Codex reset redemption: `<provider>/<name>` → the
-    // window resets_at we last redeemed for, so we never redeem the same stuck
-    // cycle twice.
-    const redeemed = new Map();
+    // `<provider>/<name>` → the window resets_at we last announced a banked reset
+    // for, so the "reset available" notice fires once per cycle, not every poll.
+    const notifiedReset = new Map();
     let consecutiveFailures = 0;
     let cycles = 0;
     log(`started (pid ${process.pid}, base interval ${baseInterval}ms).`);
     while (running) {
         try {
-            const failures = await pollOnce(state, thresholds, redeemed, log);
+            const failures = await pollOnce(state, thresholds, notifiedReset, log);
             consecutiveFailures = failures > 0 ? consecutiveFailures + 1 : 0;
         }
         catch (err) {

package/dist/desktop-sessions.js

@@ -0,0 +1,115 @@
+/**
+ * Claude Code sessions run from Claude Desktop.
+ *
+ * Desktop keeps one metadata file per session under its data dir, filed by
+ * the signed-in account: `<data>/<kind>/<accountUuid>/<orgUuid>/local_<id>.json`
+ * with the `cliSessionId` that names the transcript. Where that transcript
+ * lives depends on the kind (measured on Claude Desktop with Claude Code
+ * 2.1.295):
+ *
+ *   - `claude-code-sessions` (the Code tab): in the DEFAULT `~/.claude/projects/`
+ *     — even when the Desktop instance belongs to an agent-switch profile.
+ *   - `local-agent-mode-sessions`: in the session's own `local_<id>/.claude/`.
+ *
+ * The transcript itself names no account, so a session is attributed through
+ * the account folder it is filed under, matched against each profile's
+ * `oauthAccount.accountUuid`. A profile's Desktop instance holding sessions of
+ * another account is signed in with that account — the caller warns about it.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readSessionHeader } from "./sessions.js";
+/** Written within this long → shown as running (Desktop leaves no pid to check). */
+export const DESKTOP_LIVE_MS = 2 * 60_000;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const KINDS = ["claude-code-sessions", "local-agent-mode-sessions"];
+function dirs(p) {
+    try {
+        return fs
+            .readdirSync(p, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function files(p) {
+    try {
+        return fs.readdirSync(p).filter((f) => f.startsWith("local_") && f.endsWith(".json"));
+    }
+    catch {
+        return [];
+    }
+}
+/** `<projects>/<any encoded cwd>/<id>.jsonl`, or null. */
+function findTranscript(projects, id) {
+    for (const d of dirs(projects)) {
+        const f = path.join(projects, d, `${id}.jsonl`);
+        if (fs.existsSync(f))
+            return f;
+    }
+    return null;
+}
+function readMeta(file) {
+    try {
+        const d = JSON.parse(fs.readFileSync(file, "utf8"));
+        return d && typeof d === "object" ? d : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function scanDesktop(opts) {
+    const rows = [];
+    const instances = [];
+    for (const inst of opts.instances) {
+        const seen = new Map();
+        for (const kind of KINDS) {
+            const base = path.join(inst.dir, kind);
+            for (const account of dirs(base).filter((d) => UUID_RE.test(d))) {
+                const profile = opts.profileOf(account);
+                seen.set(account, profile);
+                for (const org of dirs(path.join(base, account))) {
+                    const folder = path.join(base, account, org);
+                    for (const f of files(folder)) {
+                        const m = readMeta(path.join(folder, f));
+                        const id = typeof m?.cliSessionId === "string" && UUID_RE.test(m.cliSessionId) ? m.cliSessionId : null;
+                        if (!m || !id || m.isArchived === true || !profile)
+                            continue;
+                        const transcript = kind === "claude-code-sessions"
+                            ? findTranscript(path.join(opts.claudeHome, "projects"), id)
+                            : findTranscript(path.join(folder, f.slice(0, -".json".length), ".claude", "projects"), id);
+                        let st = null;
+                        try {
+                            st = transcript ? fs.statSync(transcript) : null;
+                        }
+                        catch {
+                            st = null;
+                        }
+                        const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
+                        const mtimeMs = st?.mtimeMs ?? num(m.lastActivityAt) ?? num(m.createdAt) ?? 0;
+                        const header = transcript ? readSessionHeader(transcript) : { cwd: null, summary: null };
+                        rows.push({
+                            sessionId: id,
+                            projectDir: transcript ? path.basename(path.dirname(transcript)) : "",
+                            cwd: typeof m.cwd === "string" ? m.cwd : header.cwd,
+                            summary: typeof m.title === "string" && m.title ? m.title : header.summary,
+                            mtimeMs,
+                            birthtimeMs: num(m.createdAt) ?? st?.birthtimeMs ?? mtimeMs,
+                            live: !!st && opts.now - st.mtimeMs <= DESKTOP_LIVE_MS,
+                            ...(transcript ? { file: transcript } : {}),
+                            profile,
+                            surface: "desktop-app",
+                        });
+                    }
+                }
+            }
+        }
+        const accounts = [...seen.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([accountUuid, profile]) => ({ accountUuid, profile }));
+        instances.push({ ...inst, accounts, mismatch: inst.profile !== null && accounts.some((a) => a.profile !== inst.profile) });
+    }
+    rows.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return { rows, instances };
+}

package/dist/dir-resolve.js

@@ -0,0 +1,151 @@
+/**
+ * Which profile a new session in a folder gets, and why — the logic behind
+ * `agent-switch dir` (the shell wrapper's hot path) and `dir --json`.
+ *
+ * Order: folder rule (to a profile, or to a pool) > active profile > none.
+ * A pool resolves to the member with the most headroom on FRESH cached usage.
+ * Unknown usage is never treated as free: a member whose usage is older than
+ * {@link FRESH_USAGE_MS}, missing, or who is signed out is skipped, and when no
+ * member qualifies the rule falls back to the active profile and says so. No
+ * network call happens here — only the cache the daemon / `status` already wrote.
+ * The background service (`agent-switch service`) is what keeps that cache
+ * fresh for pool members: it polls every member of a pool a folder rule targets.
+ *
+ * Live sessions: under guard `block` a member that already holds a live
+ * session is skipped (starting there would be refused). Otherwise a free member
+ * wins a headroom tie over a busy one, and a busy pick is called out.
+ */
+import { describe, level, weigh } from "./balance.js";
+import { isPoolRef, poolIdOf, parseMember } from "./pools.js";
+export const FRESH_USAGE_MS = 10 * 60_000;
+export const DEFAULT_LIMIT_PCT = 95;
+export function ago(ms) {
+    const s = Math.max(0, Math.round(ms / 1000));
+    if (s < 60)
+        return "just now";
+    const m = Math.round(s / 60);
+    if (m < 60)
+        return `${m} min ago`;
+    const h = Math.round(m / 60);
+    return h < 48 ? `${h} h ago` : `${Math.round(h / 24)} days ago`;
+}
+function fallbackToActive(i, why) {
+    if (i.active && i.exists(i.active)) {
+        why.push(`Using the active profile ${i.providerId}/${i.active}`);
+        return { name: i.active, why };
+    }
+    why.push("No active profile — the tool starts with its own default login");
+    return { name: null, why };
+}
+export function resolveForDir(i) {
+    const shown = (p) => (i.displayPath ? i.displayPath(p) : p);
+    const why = [];
+    if (i.mapping && isPoolRef(i.mapping.name)) {
+        const id = poolIdOf(i.mapping.name);
+        why.push(`Rule: folder ${shown(i.mapping.path)} → pool ${id}`);
+        const pool = i.pool(id);
+        if (!pool) {
+            why.push(`Pool ${id} no longer exists`);
+            return fallbackToActive(i, why);
+        }
+        const considered = pool.members.map(parseMember).filter((m) => m && m.provider === i.providerId);
+        if (considered.length === 0) {
+            why.push(`Pool ${id} has no ${i.providerId} profile`);
+            return fallbackToActive(i, why);
+        }
+        const best = pickBalanced(i, considered.map((m) => m.name), why, null);
+        if (!best) {
+            why.push(`No member of pool ${id} has fresh usage`);
+            why.push("Pool picks use the background service's cached usage — keep it running: agent-switch service install");
+            return fallbackToActive(i, why);
+        }
+        return { name: best, why };
+    }
+    if (i.mapping && i.exists(i.mapping.name) && i.disabled?.(i.mapping.name)) {
+        why.push(`Rule: folder ${shown(i.mapping.path)} → ${i.providerId}/${i.mapping.name}, but that account is disabled`);
+        return balancePlain(i, why);
+    }
+    if (i.mapping && i.exists(i.mapping.name)) {
+        why.push(`Rule: folder ${shown(i.mapping.path)} → ${i.providerId}/${i.mapping.name}`);
+        return { name: i.mapping.name, why };
+    }
+    if (i.mapping)
+        why.push(`Rule: folder ${shown(i.mapping.path)} → ${i.providerId}/${i.mapping.name}, but that profile is gone`);
+    return balancePlain(i, why);
+}
+/** No rule decides: balance across all profiles, or the active one when the
+ *  caller gave no profile list. */
+function balancePlain(i, why) {
+    if (!i.names)
+        return fallbackToActive(i, why);
+    const n = i.names.length;
+    why.push(`${i.mapping ? "Balancing" : "No folder rule — balancing"} across ${n} ${i.providerId} account${n === 1 ? "" : "s"} by what each would lose at its reset`);
+    const best = pickBalanced(i, i.names, why, i.active);
+    if (best)
+        return { name: best, why };
+    why.push("No account has fresh usage to weigh — using the plain-start account");
+    return fallbackToActive(i, why);
+}
+/**
+ * The candidate that would lose the most at its reset (see balance.ts), after
+ * dropping every profile that can't take work. A level tie goes to `prefer`
+ * (the plain-start account), then to one without a live session.
+ */
+function pickBalanced(i, names, why, prefer) {
+    const isLive = i.live ?? (() => false);
+    const guard = i.guard ?? "off";
+    const picks = [];
+    for (const name of names) {
+        const key = `${i.providerId}/${name}`;
+        if (!i.exists(name)) {
+            why.push(`Skipped ${key}: profile not found`);
+            continue;
+        }
+        if (i.disabled?.(name)) {
+            why.push(`Skipped ${key}: disabled`);
+            continue;
+        }
+        if (!i.signedIn(name)) {
+            why.push(`Skipped ${key}: signed out`);
+            continue;
+        }
+        const live = isLive(name);
+        if (live && guard === "block") {
+            why.push(`Skipped ${key}: already has a live session (guard: block would refuse it)`);
+            continue;
+        }
+        const u = i.usage(name);
+        if (u.capturedMs === null || !u.snapshot) {
+            why.push(`Skipped ${key}: usage unknown`);
+            continue;
+        }
+        const ageMs = i.now - u.capturedMs;
+        if (ageMs > FRESH_USAGE_MS) {
+            why.push(`Skipped ${key}: usage checked ${ago(ageMs)} (too old to trust)`);
+            continue;
+        }
+        const w = weigh(u.snapshot, i.now, i.threshold?.(name) ?? DEFAULT_LIMIT_PCT);
+        if (!w.usable) {
+            why.push(`Skipped ${key}: ${w.why}`);
+            continue;
+        }
+        picks.push({ name, w, live, ageMs });
+    }
+    if (!picks.length)
+        return null;
+    const top = picks.reduce((a, b) => (b.w.need > a.w.need ? b : a));
+    const tied = picks.filter((p) => level(p.w.need, top.w.need));
+    let chosen = top;
+    if (tied.length > 1) {
+        chosen = tied.find((p) => p.name === prefer) ?? tied.find((p) => !p.live) ?? top;
+        const keys = tied.map((p) => `${i.providerId}/${p.name}`).join(", ");
+        const by = chosen.name === prefer ? "the plain-start account" : !chosen.live && tied.some((p) => p.live) ? "the one without a live session" : "the first of them";
+        why.push(`${keys} are level (${top.w.need.toFixed(1)} %/h) — taking ${by}, ${i.providerId}/${chosen.name}`);
+    }
+    const runnerUp = picks.filter((p) => p !== chosen).reduce((a, b) => (!a || b.w.need > a.w.need ? b : a), null);
+    if (chosen.live)
+        why.push(`Note: ${i.providerId}/${chosen.name} already has a live session (guard: ${guard})`);
+    why.push(`Picked ${describe(`${i.providerId}/${chosen.name}`, chosen.w)} · usage checked ${ago(chosen.ageMs)}` +
+        (runnerUp && tied.length === 1 ? ` — ahead of ${i.providerId}/${runnerUp.name} (${runnerUp.w.need.toFixed(1)} %/h)` : ""));
+    return chosen.name;
+}