@phnx-labs/agents-cli 1.20.77 → 1.20.78

package/dist/commands/sessions.js

@@ -26,7 +26,7 @@ import { gatherRemoteActive, NO_FANOUT_ENV } from '../lib/session/remote-active.
 import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
 import { stringWidth, truncateToWidth, padToWidth, terminalWidth } from '../lib/session/width.js';
 import { inferSessionState } from '../lib/session/state.js';
-import { discoverSessions, countSessionsInScope, resolveSessionById, isCompleteSessionId, searchContentIndex, getSessionRoots } from '../lib/session/discover.js';
+import { discoverSessions, countSessionsInScope, resolveSessionById, isCompleteSessionId, looksLikeSessionId, searchContentIndex, getSessionRoots } from '../lib/session/discover.js';
 import { findSessionsById } from '../lib/session/db.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
@@ -813,15 +813,18 @@ export function remoteHostsToDial(hosts, self) {
     return hosts.filter(h => hostToken(h) !== self);
 }
 /**
- * Render the unified active-session view, grouped by machine. With no `--host`,
- * local sessions come from `getActiveSessions()` and (unless `--local`) the
- * registered online devices from `ag devices` are folded in over SSH. An
- * explicit `--host`/`--device` list SCOPES the view to exactly those machines —
- * the local machine is included only when it is itself named — so `--host` is a
- * filter, not an addition (matching the non-`--active` listing path). A tip is
- * shown when there are no other machines to include.
+ * The fleet-wide live-session set behind every `--active` surface. Local sessions
+ * come from `getActiveSessions()` and (unless `--local`) the registered online
+ * devices from `ag devices` are folded in over SSH. An explicit `--host`/`--device`
+ * list SCOPES the sweep to exactly those machines — the local machine is included
+ * only when it is itself named — so `--host` is a filter, not an addition.
+ *
+ * This is the single gather: the static renderer AND the interactive browser both
+ * call it, so the browser can never disagree with `--active --json` about which
+ * sessions are live (it used to call the local-only `getActiveSessions()` directly
+ * and silently hid every remote session).
  */
-async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
+export async function gatherActiveSessions(opts = {}) {
     const self = machineId();
     // An explicit --host/--device list scopes the view: seed local sessions only
     // when no hosts are named, or when this machine is one of the named targets.
@@ -841,6 +844,17 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
             merged = dedupeByMachineSession([...local, ...remote.sessions]);
         }
     }
+    return { sessions: merged, remoteDeviceCount };
+}
+/**
+ * Render the unified active-session view, grouped by machine. Scoping and the
+ * fleet sweep live in {@link gatherActiveSessions}; this owns the presentation
+ * (the `--waiting` gate, JSON, and the grouped table). A tip is shown when there
+ * are no other machines to include.
+ */
+async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
+    const self = machineId();
+    const { sessions: merged, remoteDeviceCount } = await gatherActiveSessions(opts);
     // --waiting: only sessions blocked on the user. Exits non-zero when any are
     // present so a supervising agent or hook can poll it as a gate.
     const sessions = waitingOnly ? merged.filter(s => s.status === 'input_required') : merged;
@@ -1023,6 +1037,7 @@ async function sessionsAction(query, options) {
                 agent: options.agent,
                 host: options.host,
                 since: options.since,
+                all: options.all,
             }), { local: options.local === true, hosts: options.host });
             return;
         }
@@ -1104,7 +1119,7 @@ async function sessionsAction(query, options) {
     // When the user explicitly asks to render (via mode flag), resolve the
     // query globally so sessions outside the default cwd/30d window are found.
     if (wantsRender && searchQuery) {
-        await renderOneSession(searchQuery, mode, { agent: options.agent, project: options.project, filter: filterOpts, redact: options.redact });
+        await renderOneSession(searchQuery, mode, { agent: options.agent, project: options.project, filter: filterOpts, redact: options.redact, local: options.local, hosts: options.host });
         return;
     }
     // Interactive picker loads a deep pool but shows only recent sessions
@@ -1171,19 +1186,34 @@ async function sessionsAction(query, options) {
         // Smart ID routing: a bare query that resolves to one session renders
         // directly. If nothing matches in the scoped window and the query looks
         // like a session ID, widen to global scope (incl. Claude /resume history).
-        if (searchQuery) {
+        //
+        // Exception: a PEER answering a parent's `--json` locate sweep
+        // (AGENTS_SESSIONS_LOCAL=1) must return the SessionMeta[] ROW for the id, not
+        // render its transcript — the sweep parses an array (parseRemoteList). So when
+        // we are that peer and --json is set, skip the single-session short-circuit and
+        // fall through to the array-emitting --json block below.
+        const answeringJsonSweep = options.json === true && process.env[NO_FANOUT_ENV] === '1';
+        if (searchQuery && !answeringJsonSweep) {
             const idMatches = resolveSessionById(sessions, searchQuery);
             if (idMatches.length === 1) {
                 await renderSession(idMatches[0], mode, filterOpts, options);
                 return;
             }
             if (idMatches.length === 0 && looksLikeSessionId(searchQuery)) {
-                await renderOneSession(searchQuery, mode, { agent: options.agent, project: options.project, filter: filterOpts, redact: options.redact });
+                await renderOneSession(searchQuery, mode, { agent: options.agent, project: options.project, filter: filterOpts, redact: options.redact, local: options.local, hosts: options.host });
                 return;
             }
         }
         if (options.json) {
-            const filtered = searchQuery ? filterSessionsByQuery(sessions, searchQuery) : sessions;
+            // An id-shaped query resolves by id ONLY — the same rule the render path
+            // uses (resolveSessionQuery). Without this a `--json <uuid>` (as issued by
+            // the fleet locate sweep, which runs `sessions <uuid> --json --local` on
+            // each peer) would fall to FTS content search and return every transcript
+            // that merely MENTIONS the id, defeating exact remote resolution. A genuine
+            // search phrase keeps the ranked metadata+content path.
+            const filtered = searchQuery
+                ? resolveSessionQuery(sessions, searchQuery).matches
+                : sessions;
             process.stdout.write(serializeSessionsJson(filtered));
             return;
         }
@@ -1271,15 +1301,6 @@ async function sessionsAction(query, options) {
         process.exit(1);
     }
 }
-/** Whether a query should route to the single-session render rather than the
- * listing. The hex-ish test catches a bare id prefix; `isCompleteSessionId`
- * additionally catches the prefixed whole ids (`session_…`, `ses_…`) that the
- * hex test rejects — without it those never reach the id-only resolution and
- * still content-search. */
-function looksLikeSessionId(query) {
-    const trimmed = query.trim();
-    return /^[0-9a-f-]{6,}$/i.test(trimmed) || isCompleteSessionId(trimmed);
-}
 function teamTag(session) {
     const origin = session.teamOrigin;
     if (!origin)
@@ -1725,7 +1746,23 @@ export function pickerColumnsFor(sessions) {
         showTicket: sessions.some((s) => ticketLabel(s) !== ''),
     };
 }
-export function formatPickerLabel(s, query, cols = {}, ssh) {
+/** Width of the host-program column (`tmux→ghostty` is the long realistic case). */
+const PICKER_HOST_W = 14;
+/**
+ * Which program a live session is running in, for the picker's host column: the
+ * immediate host app (`codium`, `ghostty`, `tmux`, `iterm`, …) and — when a tmux
+ * session is currently being watched through a different app — the app it is
+ * viewed in, as `tmux→ghostty`. A tmux session with no attached client stays a
+ * bare `tmux`, which is exactly "running detached". Empty when the session has no
+ * resolvable host (cloud rows, an unreadable process env).
+ */
+export function liveHostLabel(a) {
+    if (!a?.host)
+        return '';
+    const viewer = a.viewingIn?.app;
+    return viewer && viewer !== a.host ? `${a.host}→${viewer}` : a.host;
+}
+export function formatPickerLabel(s, query, cols = {}, ssh, host = '') {
     const agentColor = colorAgent(s.agent);
     const when = formatRelativeTime(s.lastActivity ?? s.timestamp);
     const project = s.project || '-';
@@ -1750,18 +1787,29 @@ export function formatPickerLabel(s, query, cols = {}, ssh) {
     const ticketCell = cols.showTicket
         ? chalk.blue(padRight(truncate(ticketLabel(s) || '-', TICKET_W), TICKET_W + 1))
         : '';
+    // Which terminal/editor the session runs in — a tab in Ghostty vs a VS Code
+    // panel vs a detached tmux pane is the thing you need to know to go find it.
+    const hostCell = cols.showHost
+        ? chalk.gray(padRight(truncate(host || '-', PICKER_HOST_W - 1), PICKER_HOST_W))
+        : '';
     // The picker prepends a gutter (cursor, plus a checkbox in multi-select mode);
     // reserve it, plus the conditional columns, so the topic shrinks to fit and
     // rows never wrap.
     const gutter = cols.gutter ?? 2;
     const machineColW = cols.showMachine ? machineW : 0;
     const ticketW = cols.showTicket ? TICKET_W + 1 : 0;
+    const hostW = cols.showHost ? PICKER_HOST_W : 0;
     const wtW = wt ? stringWidth(wt) + 1 : 0;
-    const topicW = Math.max(16, terminalWidth() - gutter - (10 + 9 + 8 + 16) - machineColW - ticketW - wtW - sshW - stringWidth(when) - 1);
-    return (chalk.white(padRight(s.shortId, 10)) +
+    const topicW = Math.max(16, terminalWidth() - gutter - (10 + 9 + 8 + 16) - machineColW - hostW - ticketW - wtW - sshW - stringWidth(when) - 1);
+    return (
+    // Truncated, not just padded: an indexed shortId is always 8 chars, but a
+    // live row with no session id is named by its pid or cloud task, which can
+    // run past the column and shunt every later column out of alignment.
+    chalk.white(padRight(truncate(s.shortId, 9), 10)) +
         agentColor(padRight(truncate(s.agent, 8), 9)) +
         chalk.yellow(padRight(truncate(versionStr, 7), 8)) +
         machineCell +
+        hostCell +
         chalk.cyan(padRight(truncate(project, 14), 16)) +
         sshSeg +
         renderTopicCell(label, topic, query, topicW, topicW) +
@@ -1827,7 +1875,25 @@ function warnNoPeerTarget(machine, session) {
     console.log(chalk.yellow(`Session ${session.shortId} lives on ${machine}, which isn't a reachable device right now.`));
     console.log(chalk.gray(`Register/wake it (ag devices), or run there: agents ssh ${machine}`));
 }
+/**
+ * Row-id prefix for a live session whose agent has not reported a session id yet
+ * (a booting harness, a queued teammate). The browser lists these so nothing live
+ * is hidden, but they address no transcript — {@link isIdlessLiveRow} is what the
+ * pick handler checks before trying to read or resume one.
+ */
+export const LIVE_ROW_PREFIX = 'live:';
+export function isIdlessLiveRow(s) {
+    return s.id.startsWith(LIVE_ROW_PREFIX);
+}
 export async function handlePickedSession(picked) {
+    // A live row with no session id has no transcript to open and no id to resume
+    // by; say where the process is instead of dead-ending on an unreadable path.
+    if (isIdlessLiveRow(picked.session)) {
+        const where = picked.session.machine ? ` on ${picked.session.machine}` : '';
+        console.log(chalk.yellow(`This session hasn't reported a session id yet — nothing to open${where}.`));
+        console.log(chalk.gray(`Watch for it with: agents sessions --active${picked.session.machine ? ` --host ${picked.session.machine}` : ''}`));
+        return;
+    }
     // A session on another machine is read/resumed ON that machine over SSH — its
     // transcript and agent binary live there. Both actions execute on the peer
     // (not a local `--host` hop, which would discover locally and dead-end for a
@@ -2403,6 +2469,21 @@ async function renderOneSession(query, mode, scope) {
                 }
             }
             else if (byId) {
+                // Not on this machine. A UUID names ONE session, so before giving up ask
+                // the fleet — the session may live only on a peer (the whole point of
+                // RUSH-2024). Skip the sweep when the caller pinned --local, or when we
+                // are ourselves a peer answering a parent's sweep (AGENTS_SESSIONS_LOCAL),
+                // so a locate never recurses. On a single remote hit we hand rendering to
+                // that peer; a multi-host hit surfaces the conflict; a miss keeps the
+                // local not-found message. No FTS fallback either way.
+                if (shouldFanOutForId(query, scope.local)) {
+                    const outcome = await resolveSessionAcrossFleet(query, mode, scope.hosts);
+                    if (outcome === 'rendered')
+                        return;
+                    if (outcome === 'conflict')
+                        process.exit(1);
+                    // 'not-found' falls through to the local message below.
+                }
                 notFoundByIdMessage(query).forEach(l => console.error(l));
                 process.exit(1);
             }
@@ -2441,6 +2522,123 @@ async function renderOneSession(query, mode, scope) {
         process.exit(1);
     }
 }
+/**
+ * Whether a missed local id lookup should widen to a cross-machine sweep.
+ *
+ * Gate (all must hold):
+ *   - the query is id-shaped (`looksLikeSessionId`) — only an identifier resolves
+ *     across the fleet; a search phrase never does.
+ *   - not `--local` — the caller opted out of cross-machine lookup (deterministic
+ *     local behavior for scripts, RUSH-2024 acceptance: "--local still restricts").
+ *   - `AGENTS_SESSIONS_LOCAL` is unset — we are not ourselves a peer answering a
+ *     parent's sweep, so a locate can never recurse (RUSH-2024: avoid double-fan-out).
+ *
+ * Pure + exported so the gate is unit-tested without driving discovery / SSH.
+ */
+export function shouldFanOutForId(query, local) {
+    if (local === true)
+        return false;
+    if (process.env[NO_FANOUT_ENV] === '1')
+        return false;
+    return looksLikeSessionId(query);
+}
+/** The render-mode flag a peer's `agents sessions <id>` must carry so the remote
+ * summary matches the mode the user asked for. `summary` is the peer's default,
+ * so it needs no flag; the others map 1:1 to a CLI flag. */
+function modeFlag(mode) {
+    if (mode === 'markdown')
+        return '--markdown';
+    if (mode === 'json')
+        return '--json';
+    return undefined; // summary — the peer's default render
+}
+/** Group a fleet sweep's rows to the DISTINCT machines that hold the id. Each
+ * peer answered `sessions <id> --json --local`, which (post-fix) id-resolves and
+ * so returns the matching row(s); a peer with a synced MIRROR of the same id can
+ * emit more than one row, so we keep the first per machine. Rows the peer somehow
+ * returned that do NOT match the id (defensive against version skew) are dropped
+ * so a stray content hit can never masquerade as an exact resolution. */
+export function fleetHitsById(rows, id) {
+    const q = id.trim().toLowerCase();
+    const byMachine = new Map();
+    for (const s of rows) {
+        const machine = s.machine;
+        if (!machine)
+            continue; // an untagged row can't be routed back to a peer
+        if (s.id?.toLowerCase() !== q)
+            continue; // exact id only — never a content hit
+        if (!byMachine.has(machine))
+            byMachine.set(machine, s);
+    }
+    return Array.from(byMachine.entries()).map(([machine, session]) => ({ machine, session }));
+}
+/**
+ * Locate a full session id across the online fleet and render it from the machine
+ * that holds it. The local disk already missed; this fans `sessions <id> --json
+ * --all` out to every registered online peer (or the explicit `hosts` set),
+ * groups the rows to distinct machines, then:
+ *
+ *   - exactly one machine  → delegate rendering to that peer via `runOnPeer`
+ *     (its transcript and agent binary live there — a local `--host` hop would
+ *     re-discover locally and dead-end), returning `'rendered'`.
+ *   - more than one machine → print the conflict with machine labels so the user
+ *     can disambiguate with `--device <host>`, returning `'conflict'`.
+ *   - none                 → `'not-found'`, letting the caller print the local
+ *     "no session on this machine" message.
+ *
+ * No fuzzy/content fallback: the sweep forwards a UUID, each peer id-resolves it,
+ * and `fleetHitsById` drops anything that isn't an exact id match.
+ */
+export async function resolveSessionAcrossFleet(id, mode, hosts, deps = { gatherRemoteList, runOnPeer }) {
+    const spinner = isInteractiveTerminal() ? ora('Searching the fleet...').start() : null;
+    let hits;
+    try {
+        // Force whole-index scope (--all): the peer runs in its SSH-login home dir,
+        // whose cwd would otherwise silently narrow the lookup and hide the row.
+        // --json so each peer answers a parseable array; --local so it answers for
+        // itself and never re-fans-out (belt-and-suspenders with the parent's
+        // AGENTS_SESSIONS_LOCAL, which remote-list also sets on the peer).
+        const forwarded = ['sessions', id, '--json', '--all', '--local'];
+        const { sessions } = await deps.gatherRemoteList(forwarded, hosts);
+        hits = fleetHitsById(sessions, id);
+    }
+    catch {
+        // A fan-out failure is not an exact resolution — treat as not-found so the
+        // caller prints the honest local message rather than a half-answer.
+        hits = [];
+    }
+    finally {
+        spinner?.stop();
+    }
+    if (hits.length === 0)
+        return 'not-found';
+    if (hits.length > 1) {
+        console.error(chalk.red(`Session ${id} exists on multiple machines:`));
+        for (const h of hits) {
+            const s = h.session;
+            const label = s.label ?? s.topic ?? '';
+            console.error(chalk.cyan(`  ${h.machine}`) + chalk.gray(`  ${s.agent}${s.version ? ` ${s.version}` : ''}  ${label}`));
+        }
+        console.error(chalk.gray(`Pick one with: agents sessions ${id} --device <host>`));
+        return 'conflict';
+    }
+    const { machine } = hits[0];
+    // Render the remote summary by re-running `sessions <id>` ON the peer. --local
+    // keeps that render on the peer (it owns the transcript); the mode flag matches
+    // the mode the user asked for. No TTY: a summary/markdown/json render is a
+    // one-shot capture, not an interactive resume.
+    const peerArgs = ['sessions', id, '--local'];
+    const flag = modeFlag(mode);
+    if (flag)
+        peerArgs.push(flag);
+    const result = await deps.runOnPeer(peerArgs, machine);
+    if (result === 'no-target') {
+        console.error(chalk.red(`Session ${id} is on ${machine}, but it is not a reachable registered device.`));
+        console.error(chalk.gray('Register it with `agents devices` or run the command on that machine.'));
+        return 'conflict'; // a definitive answer (found, un-renderable) — do NOT fall to the local not-found line
+    }
+    return 'rendered';
+}
 /** Register the `agents sessions` command with all its options and help text. */
 export function registerSessionsCommands(program) {
     const sessionsCmd = program
@@ -2455,7 +2653,7 @@ export function registerSessionsCommands(program) {
         .option('--antigravity', 'Shorthand for --agent antigravity')
         .option('--grok', 'Shorthand for --agent grok')
         .option('--opencode', 'Shorthand for --agent opencode')
-        .option('--all', 'Include sessions from every directory (not just current project)')
+        .option('--all', 'Widen every non-status filter to "all": every directory (not just this project) and all time (no window cap). Status filters like --active still compose; -a/--device/--since still narrow their axis.')
         .option('--unmanaged', "Also show sessions from your own ~/.<agent> installs (hidden once agents-cli manages that agent)")
         .option('--teams', 'Include team-spawned sessions (hidden by default)')
         .option('--routine', 'Show only sessions archived from routine runs')

package/dist/commands/ssh.js

@@ -37,6 +37,7 @@ import { fanOutDevices, fleetHealthSkip, planFleetTargets, remoteFleetTargets, r
 import { fleetCapacity, fmtBytes, headroom, } from '../lib/devices/health.js';
 import { buildFleetHealthReport, renderFleetMatrix, renderFleetSummary, renderFleetWarnings, } from '../lib/devices/health-report.js';
 import { loadFleetStats, readStatsCache } from '../lib/devices/stats-cache.js';
+import { collectLocalFleetInventory } from '../lib/devices/fleet-inventory.js';
 import { checkSyncStatus, countOrphans } from '../lib/drift.js';
 import { checkAllClis } from '../lib/teams/agents.js';
 import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
@@ -321,6 +322,9 @@ function localHealthRow(self, stats) {
         clis: checkAllClis(),
         sync: checkSyncStatus(process.cwd()),
         orphans: countOrphans(),
+        // Local baseline inventory for cross-device divergence (RUSH-2027) — the
+        // yardstick every remote box is compared against.
+        inventory: collectLocalFleetInventory(process.cwd()),
     };
 }
 async function probeRemoteHealth(target) {
@@ -344,6 +348,10 @@ async function probeRemoteHealth(target) {
         // so the Auth column is current without a prior fleet-wide `fleet ping`.
         // Older remotes that don't emit it fall back to this host's cache below.
         auth: parsed.auth,
+        // Harness inventory (resources / agent versions / repo state) for
+        // cross-device divergence detection (RUSH-2027). Undefined on an older CLI
+        // that doesn't emit the `fleet` field — the comparator skips it.
+        inventory: parsed.fleet,
     };
 }
 async function runFleetStatus(opts) {
@@ -416,7 +424,7 @@ async function runFleetStatus(opts) {
             row.lastSeen = profile.tailscale?.lastSeen ?? profile.reachability?.checkedAt;
         }
     }
-    const report = buildFleetHealthReport(rows);
+    const report = buildFleetHealthReport(rows, new Date(), { self });
     if (opts.json) {
         console.log(JSON.stringify(report, null, 2));
     }

package/dist/index.js

@@ -960,12 +960,10 @@ if (brandDisabled.size > 0) {
 if (!helpOrVersionRequested) {
     // Run update check before parsing so the upgrade notice/prompt precedes output.
     await checkForUpdates();
-    // Surface any "behind upstream" notices from the previous detached sync, then
-    // fire-and-forget the next background sync. System repo gets a real fast-forward
+    // Fire-and-forget the background sync. System repo gets a real fast-forward
     // pull (read-only locally, safe). User repo and extras get fetch-only + a
-    // status marker that we'll print on the *next* invocation.
-    const { spawnDetachedSync, printPendingUpdateNotices } = await import('./lib/auto-pull.js');
-    printPendingUpdateNotices();
+    // status marker that `agents doctor` surfaces as a repo-behind warning.
+    const { spawnDetachedSync } = await import('./lib/auto-pull.js');
     spawnDetachedSync();
 }
 // First-run experience: no args + no config yet + TTY -> launch interactive setup.

package/dist/lib/agents.d.ts

@@ -265,27 +265,6 @@ export declare function __resetAntigravityKeychainCacheForTest(): void;
  * Sync, no Keychain, no network — safe on the `agents run` hot path.
  */
 export declare function isClaudeCredentialFileBlank(base: string, platform?: NodeJS.Platform): boolean;
-/**
- * Whether a Claude version home holds its OWN on-disk credential — a non-blank
- * `.claude/.credentials.json` (the store Claude Code writes on login off macOS)
- * or a `.claude/.oauth_token` file (the keychain-less shim fallback, shims.ts).
- *
- * RUSH-1979: the routines daemon injects one ambient `CLAUDE_CODE_OAUTH_TOKEN`
- * (RUSH-1759) so a token-less default account still authenticates. But Claude —
- * and the Linux shim's own `-z CLAUDE_CODE_OAUTH_TOKEN` guard — both prefer that
- * env var over a pinned account's config dir, so when balanced rotation pins a
- * specific account's `CLAUDE_CONFIG_DIR` the ambient token shadows it: the pool
- * is inert and every fire 401s on the one stale token. A routine spawn drops the
- * ambient token when the pinned account has its own credential (this returns
- * true) so the account authenticates itself; when it does not (the RUSH-1759
- * default), the injected token is kept.
- *
- * Off-darwin only, mirroring {@link isClaudeCredentialFileBlank}: on macOS the
- * login Keychain is the canonical store and probing it raises an auth sheet, and
- * there the daemon injects no token to shadow (broker-only, usually absent), so
- * returning false changes nothing. Sync, no Keychain, no network.
- */
-export declare function claudeHomeHasOwnCredential(base: string, platform?: NodeJS.Platform): boolean;
 export declare function getAccountInfo(agentId: AgentId, home?: string): Promise<AccountInfo>;
 /**
  * Determine when the agent was last used by checking session file mtimes,

package/dist/lib/agents.js

@@ -1404,43 +1404,6 @@ export function isClaudeCredentialFileBlank(base, platform = process.platform) {
         return false;
     }
 }
-/**
- * Whether a Claude version home holds its OWN on-disk credential — a non-blank
- * `.claude/.credentials.json` (the store Claude Code writes on login off macOS)
- * or a `.claude/.oauth_token` file (the keychain-less shim fallback, shims.ts).
- *
- * RUSH-1979: the routines daemon injects one ambient `CLAUDE_CODE_OAUTH_TOKEN`
- * (RUSH-1759) so a token-less default account still authenticates. But Claude —
- * and the Linux shim's own `-z CLAUDE_CODE_OAUTH_TOKEN` guard — both prefer that
- * env var over a pinned account's config dir, so when balanced rotation pins a
- * specific account's `CLAUDE_CONFIG_DIR` the ambient token shadows it: the pool
- * is inert and every fire 401s on the one stale token. A routine spawn drops the
- * ambient token when the pinned account has its own credential (this returns
- * true) so the account authenticates itself; when it does not (the RUSH-1759
- * default), the injected token is kept.
- *
- * Off-darwin only, mirroring {@link isClaudeCredentialFileBlank}: on macOS the
- * login Keychain is the canonical store and probing it raises an auth sheet, and
- * there the daemon injects no token to shadow (broker-only, usually absent), so
- * returning false changes nothing. Sync, no Keychain, no network.
- */
-export function claudeHomeHasOwnCredential(base, platform = process.platform) {
-    if (platform === 'darwin')
-        return false;
-    if (fs.existsSync(path.join(base, '.claude', '.oauth_token')))
-        return true;
-    try {
-        const raw = fs.readFileSync(path.join(base, '.claude', '.credentials.json'), 'utf-8');
-        const oauth = JSON.parse(raw).claudeAiOauth;
-        if (!oauth)
-            return false;
-        const nonEmpty = (v) => typeof v === 'string' && v.trim().length > 0;
-        return nonEmpty(oauth.accessToken) || nonEmpty(oauth.refreshToken);
-    }
-    catch {
-        return false;
-    }
-}
 export async function getAccountInfo(agentId, home) {
     const base = home || os.homedir();
     const empty = {

package/dist/lib/auto-pull.d.ts

@@ -2,12 +2,13 @@
  * Background sync for tracked git repos:
  *   - System repo (~/.agents/.system/) is read-only locally — fast-forward auto-pull is safe.
  *   - User repo (~/.agents/) and enabled extras may have local commits, so we only
- *     `git fetch` and write a status marker. Next CLI invocation surfaces a one-line
- *     notice if upstream is ahead. Pulling is left to the user via `agents repo pull`.
+ *     `git fetch` and write a status marker. `agents doctor` surfaces these markers
+ *     as a "Repo updates" section instead of printing to stderr on every command.
+ *     Pulling is left to the user via `agents repo pull`.
  *
  * Public API:
- *   spawnDetachedSync()           — fire-and-forget; never blocks the foreground command.
- *   printPendingUpdateNotices()   — synchronous; reads markers and prints + consumes them.
+ *   spawnDetachedSync()      — fire-and-forget; never blocks the foreground command.
+ *   readRepoBehindMarkers()  — synchronous; reads markers without consuming them.
  */
 /** Per-repo lock file path. mtime acts as a recency check. */
 export declare function lockFilePath(alias: string): string;
@@ -24,8 +25,15 @@ export interface FetchStatusMarker {
 /** Spawn the detached worker. No-op when AGENTS_NO_AUTOPULL=1 is set. */
 export declare function spawnDetachedSync(): void;
 /**
- * Read any pending status markers and print one-line notices for repos that
- * are behind upstream. Markers are deleted after printing so notices don't
- * repeat on every invocation. Synchronous, cheap (small JSON files).
+ * Read all current status markers and return those where the local repo is
+ * behind upstream. Markers are NOT deleted — they persist until the next
+ * background fetch overwrites them with fresh data.
+ *
+ * Synchronous, cheap (small JSON files). Used by `agents doctor` to surface
+ * repo-behind warnings in one place instead of printing to stderr on every
+ * command.
+ *
+ * @param fetchDir - Override the fetch state dir (for tests). Defaults to the
+ *   production getFetchCacheDir() path.
  */
-export declare function printPendingUpdateNotices(): void;
+export declare function readRepoBehindMarkers(fetchDir?: string): FetchStatusMarker[];

package/dist/lib/auto-pull.js

@@ -2,12 +2,13 @@
  * Background sync for tracked git repos:
  *   - System repo (~/.agents/.system/) is read-only locally — fast-forward auto-pull is safe.
  *   - User repo (~/.agents/) and enabled extras may have local commits, so we only
- *     `git fetch` and write a status marker. Next CLI invocation surfaces a one-line
- *     notice if upstream is ahead. Pulling is left to the user via `agents repo pull`.
+ *     `git fetch` and write a status marker. `agents doctor` surfaces these markers
+ *     as a "Repo updates" section instead of printing to stderr on every command.
+ *     Pulling is left to the user via `agents repo pull`.
  *
  * Public API:
- *   spawnDetachedSync()           — fire-and-forget; never blocks the foreground command.
- *   printPendingUpdateNotices()   — synchronous; reads markers and prints + consumes them.
+ *   spawnDetachedSync()      — fire-and-forget; never blocks the foreground command.
+ *   readRepoBehindMarkers()  — synchronous; reads markers without consuming them.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -57,21 +58,29 @@ export function spawnDetachedSync() {
     }
 }
 /**
- * Read any pending status markers and print one-line notices for repos that
- * are behind upstream. Markers are deleted after printing so notices don't
- * repeat on every invocation. Synchronous, cheap (small JSON files).
+ * Read all current status markers and return those where the local repo is
+ * behind upstream. Markers are NOT deleted — they persist until the next
+ * background fetch overwrites them with fresh data.
+ *
+ * Synchronous, cheap (small JSON files). Used by `agents doctor` to surface
+ * repo-behind warnings in one place instead of printing to stderr on every
+ * command.
+ *
+ * @param fetchDir - Override the fetch state dir (for tests). Defaults to the
+ *   production getFetchCacheDir() path.
  */
-export function printPendingUpdateNotices() {
-    const dir = fetchStateDir();
+export function readRepoBehindMarkers(fetchDir) {
+    const dir = fetchDir ?? fetchStateDir();
     if (!fs.existsSync(dir))
-        return;
+        return [];
     let entries = [];
     try {
         entries = fs.readdirSync(dir);
     }
     catch {
-        return;
+        return [];
     }
+    const result = [];
     for (const name of entries) {
         if (!name.endsWith('.status.json'))
             continue;
@@ -81,25 +90,11 @@ export function printPendingUpdateNotices() {
             marker = JSON.parse(fs.readFileSync(file, 'utf-8'));
         }
         catch {
-            try {
-                fs.unlinkSync(file);
-            }
-            catch { /* ignore */ }
             continue;
         }
-        if (!marker || marker.behind <= 0) {
-            try {
-                fs.unlinkSync(file);
-            }
-            catch { /* ignore */ }
+        if (!marker || marker.behind <= 0)
             continue;
-        }
-        const repoLabel = marker.alias === 'user' ? '~/.agents/' : marker.alias;
-        process.stderr.write(`agents-cli: ${repoLabel} is ${marker.behind} commit${marker.behind === 1 ? '' : 's'} ` +
-            `behind ${marker.branch} — run 'agents repo pull ${marker.alias}' to update.\n`);
-        try {
-            fs.unlinkSync(file);
-        }
-        catch { /* ignore */ }
+        result.push(marker);
     }
+    return result;
 }