@phnx-labs/agents-cli 1.22.117 → 1.22.118

package/dist/commands/sync.js

@@ -35,8 +35,6 @@ import { Option } from 'commander';
 import chalk from 'chalk';
 import { resolveSyncPassphraseFromEnv } from '../lib/sync-passphrase.js';
 import { agentLabel, resolveAgentName, MANAGED_AGENT_IDS, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
-import { autoEvictCentralBrowserProfiles } from '../lib/browser/registry.js';
-import { shouldAutoClaimCentralProfile } from '../lib/browser/profiles.js';
 import { isVersionInstalled, syncResourcesToVersion, parseAgentSpec, resolveVersion, resolveVersionAlias, listInstalledVersions, healDanglingVersionPointers, getAvailableResources, getActuallySyncedResources, getProjectOnlyResources, getNewResources, hasNewResources, promptResourceSelection, promptNewResourceSelection, buildSelection, mergeRepoScopedSelections, listRepoNames, getVersionHomePath, } from '../lib/installations/versions.js';
 import { capableAgents } from '../lib/capabilities.js';
 import { parseHookManifest, registerHooksToSettings } from '../lib/hooks/install.js';
@@ -397,12 +395,9 @@ async function runInteractiveReconcile(opts, outLog, errLog) {
         else
             outLog(chalk.yellow(`  ! ${repo}: ${(res.error ?? 'pull failed').split('\n')[0]}`));
     }
-    // Drain the legacy central `browser:` tombstone now that the repos are pulled.
-    // Running AFTER the pull is load-bearing: it acts on a view of central that
-    // already reflects peers' drains, so it never re-claims a profile another box
-    // already migrated (which would flip that profile's kind identity->fungible).
-    // The interactive path is always non-quiet, non-json.
-    evictCentralBrowserProfilesForSync(false, false, outLog, errLog);
+    // Central browser-profile claiming is the standalone `browser` CLI's now
+    // (PHNX-4101): `browser profiles claim` / `browser profiles prune` own it.
+    // agents-cli no longer evicts central `browser:` tombstones on sync.
     // 2. One selection spanning the chosen repos.
     const selection = mergeRepoScopedSelections(repos, cwd);
     const hasResources = selection.memory === 'all' || Object.entries(selection).some(([kind, v]) => kind !== 'memory' && Array.isArray(v) && v.length > 0);
@@ -443,36 +438,6 @@ async function runInteractiveReconcile(opts, outLog, errLog) {
     if (repairHadFailures(umbrellaRepair))
         process.exitCode = 1;
 }
-/**
- * Drain the legacy central `browser:` tombstone during `agents sync` (PHNX-3315).
- * New profiles write the per-device doc, but profiles created before the
- * device-scoped store lingered in the shared top-level `agents.yaml` and churned
- * every fleet pull until someone ran `agents browser profiles claim` by hand.
- * Fold the ones THIS box can host into its device doc — host-gated, and the
- * selection is computed under the meta lock (see autoEvictCentralBrowserProfiles)
- * so it never races itself. Callers MUST invoke this AFTER the repo pull: acting
- * on a pre-pull view of central risks re-claiming a profile a peer already
- * drained, which would flip its kind identity->fungible. Non-fatal so a hiccup
- * can never wedge the sync.
- */
-function evictCentralBrowserProfilesForSync(quiet, json, outLog, errLog) {
-    try {
-        // Auto-claim ONLY remote (ssh://) tombstones — they are fungible by design,
-        // so a concurrent cross-machine double-claim is harmless. Local/cdp profiles
-        // have no per-machine ownership signal and are left central for an explicit
-        // `agents browser profiles claim` (PHNX-3315 review). See
-        // shouldAutoClaimCentralProfile.
-        const result = autoEvictCentralBrowserProfiles(shouldAutoClaimCentralProfile);
-        if (!quiet && !json && result.claimed.length > 0) {
-            outLog(chalk.gray(`  Claimed ${result.claimed.length} central browser profile(s) into this device: ${result.claimed.join(', ')}`));
-        }
-    }
-    catch (err) {
-        if (!quiet && !json) {
-            errLog(chalk.yellow(`  ! browser profile eviction skipped: ${err.message}`));
-        }
-    }
-}
 /**
  * The umbrella verb: bare `agents sync` (no agent) makes this machine current.
  * Resolves the flags + a secrets passphrase (env-only for now; tokenized auth
@@ -550,12 +515,9 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
             log: (msg) => { if (!quiet && !json)
                 outLog(chalk.gray(`  ${msg}`)); },
         });
-        // Drain the legacy central `browser:` tombstone AFTER the umbrella pull, so
-        // we act on central as converged by this sync rather than a stale pre-pull
-        // copy that could re-claim a profile a peer already migrated. Skipped under
-        // --cloud (fetch-only, no local reconcile).
-        if (!opts.cloud && !kindSelection)
-            evictCentralBrowserProfilesForSync(quiet, json, outLog, errLog);
+        // Central browser-profile claiming moved to the standalone `browser` CLI
+        // (PHNX-4101: `browser profiles claim` / `prune`), so `agents sync` no longer
+        // drains the central `browser:` tombstone.
         // Post-reconcile verification (PHNX-3186): re-read every version the reconcile
         // wrote into and confirm it now matches source. Without this the umbrella
         // printed `✓ sync: reconciled` unconditionally, the exact false-success the

package/dist/commands/teams.js

@@ -42,7 +42,6 @@ import { isPromptCancelled, isInteractiveTerminal, requireDestructiveArg, requir
 const AGENT_NAMES = {
     claude: 'Claude',
     codex: 'Codex',
-    gemini: 'Gemini',
     cursor: 'Cursor',
     opencode: 'OpenCode',
     grok: 'Grok',

package/dist/commands/update.d.ts

@@ -1,5 +1,24 @@
 import type { Command } from 'commander';
 import type { AgentId } from '../lib/types.js';
+/**
+ * Split `<agent>[@<selector>]`. The selector names an INSTALLATION — its frozen
+ * label, or the release it currently carries — never a release to install; that
+ * is `--to`. Keeping them separate is what lets `agents update claude@2.0.65
+ * --to 2.0.71` read unambiguously.
+ */
+/**
+ * `<agent>[@<installed-version>][#<account>]`. The `#<account>` form is the
+ * same selector `agents run claude#work` takes: accounts run on the harness's
+ * one managed installation (PHNX-3940), so it names WHICH login the user means
+ * and resolves to that installation. Refusing it as "Unknown agent
+ * 'claude#work'" sent operators hunting for a per-account install that does
+ * not exist.
+ */
+export declare function parseTarget(raw: string): {
+    agent: AgentId;
+    selector?: string;
+    account?: string;
+};
 /**
  * One line naming the installations a bare `agents update <agent>` did NOT
  * touch — isolated (`--isolated`) copies and legacy pre-v2 per-version homes —

package/dist/commands/update.js

@@ -3,23 +3,48 @@ import { AGENTS, formatAgentError, resolveAgentName } from '../lib/agents.js';
 import { setHelpSections } from '../lib/help.js';
 import { describeInstallation, listInstallations, planAutoUpdates, resolveInstallation, runAutoUpdatePass, selectUpdateStrategy, supportsPinnedUpdate, updateInstallation, } from '../lib/installations/index.js';
 import { resolveManagedInstallation } from '../lib/installations/index.js';
+import { findUnifiedAccount } from '../lib/account-registry.js';
+import { readMeta } from '../lib/state.js';
 /**
  * Split `<agent>[@<selector>]`. The selector names an INSTALLATION — its frozen
  * label, or the release it currently carries — never a release to install; that
  * is `--to`. Keeping them separate is what lets `agents update claude@2.0.65
  * --to 2.0.71` read unambiguously.
  */
-function parseTarget(raw) {
-    const at = raw.indexOf('@');
-    const name = at === -1 ? raw : raw.slice(0, at);
-    const selector = at === -1 ? undefined : raw.slice(at + 1).trim();
+/**
+ * `<agent>[@<installed-version>][#<account>]`. The `#<account>` form is the
+ * same selector `agents run claude#work` takes: accounts run on the harness's
+ * one managed installation (PHNX-3940), so it names WHICH login the user means
+ * and resolves to that installation. Refusing it as "Unknown agent
+ * 'claude#work'" sent operators hunting for a per-account install that does
+ * not exist.
+ */
+export function parseTarget(raw) {
+    const hash = raw.indexOf('#');
+    const spec = hash === -1 ? raw : raw.slice(0, hash);
+    const account = hash === -1 ? undefined : raw.slice(hash + 1).trim();
+    if (hash !== -1 && !account) {
+        throw new Error(`Select an account after # in '${raw}', e.g. claude#work — or just <agent>.`);
+    }
+    if (account?.includes('@')) {
+        throw new Error(`Put the installation before the account: <agent>@<installed-version>#<account>, not '${raw}'.`);
+    }
+    const at = spec.indexOf('@');
+    const name = at === -1 ? spec : spec.slice(0, at);
+    const selector = at === -1 ? undefined : spec.slice(at + 1).trim();
     if (at !== -1 && !selector) {
         throw new Error(`Missing installation in '${raw}'. Use <agent>@<installed-version>, or just <agent>.`);
     }
     const agent = resolveAgentName(name);
     if (!agent)
         throw new Error(formatAgentError(name));
-    return { agent, selector };
+    if (account) {
+        const known = findUnifiedAccount(account, readMeta(), undefined, agent);
+        if (!known) {
+            throw new Error(`Unknown ${AGENTS[agent].name} account '${account}'. See: agents accounts list ${agent}`);
+        }
+    }
+    return { agent, selector, account };
 }
 /**
  * One line naming the installations a bare `agents update <agent>` did NOT
@@ -219,7 +244,10 @@ export function registerUpdateCommand(program) {
             if (!target) {
                 throw new Error('Which agent? Use: agents update <agent>[@<installed-version>], or agents update --auto.');
             }
-            const { agent, selector } = parseTarget(target);
+            const { agent, selector, account } = parseTarget(target);
+            if (account && !options.json) {
+                console.log(chalk.gray(`  account '${account}' runs on the managed ${AGENTS[agent].name} installation; updating that.`));
+            }
             if (options.check) {
                 const plan = (await planAutoUpdates({ agents: [agent] })).filter((entry) => !selector || entry.installation.label === selector || entry.installation.releaseVersion === selector);
                 if (selector && plan.length === 0) {

package/dist/commands/view.d.ts

@@ -4,7 +4,7 @@ import type { AccountInfo } from '../lib/agents.js';
 import type { AgentId } from '../lib/types.js';
 import { type ConfiguredDeviceRole } from '../lib/device-config.js';
 import { type NativeAccountCatalogRow } from '../lib/account-catalog.js';
-import type { ResourceSection, ViewJsonAgent } from '../lib/view-types.js';
+import type { ResourceSection, ViewJsonAgent, ViewJsonRunReady } from '../lib/view-types.js';
 export type { ResourceItemJson, ResourceSection, SyncState, VersionResourcesJson, ViewJsonAgent, ViewJsonVersion } from '../lib/view-types.js';
 import { type ProfileSummary } from '../lib/profiles.js';
 import { type ByokUsageResult } from '../lib/byok-usage.js';
@@ -76,6 +76,17 @@ export declare function parseResourceSections(options: {
     resources?: string | boolean;
     detailed?: boolean;
 } & ViewSectionFilter, jsonMode: boolean): Set<ResourceSection>;
+/**
+ * The one run-readiness gate for one agent on THIS box (PHNX-4116). Runs the
+ * SAME enumeration the local router picks from — `collectRunCandidates` (native
+ * slots + version homes) through `readinessFromCandidate` — so the answer
+ * `agents view --json` publishes is exactly what a `run` here would find, and a
+ * remote `--device auto` dispatcher can read it instead of re-deriving freshness
+ * on its own box (which drifted: view.ts lists version homes, the router lists
+ * slots). Returns undefined when the agent has no candidates at all (nothing
+ * installed), so the field is simply absent rather than a misleading verdict.
+ */
+export declare function computeAgentRunReady(agentId: AgentId): Promise<ViewJsonRunReady | undefined>;
 /**
  * Collect structured info for one or more agents without rendering to the
  * terminal. Used by `--json` output and any programmatic consumer (e.g. the

package/dist/commands/view.js

@@ -39,7 +39,7 @@ import { selectUpdateStrategy } from '../lib/installations/strategies.js';
 import { isGitRepo, getGitSyncStatus } from '../lib/git.js';
 import { getCentralRulesFileName } from '../lib/rules/rules.js';
 import { composeRulesFromState } from '../lib/rules/compose.js';
-import { getConfiguredRunStrategy, isLaunchableSignedIn } from '../lib/accounting/rotate.js';
+import { getConfiguredRunStrategy, isLaunchableSignedIn, collectRunCandidates, readinessFromCandidate } from '../lib/accounting/rotate.js';
 import { resolveRunDefaults } from '../lib/run-defaults.js';
 import { resolveConfiguredModel } from '../lib/models.js';
 import { listProfiles, profileExists, profileSummary, readProfile } from '../lib/profiles.js';
@@ -1272,6 +1272,36 @@ export function parseResourceSections(options, jsonMode) {
     }
     return set;
 }
+/**
+ * The one run-readiness gate for one agent on THIS box (PHNX-4116). Runs the
+ * SAME enumeration the local router picks from — `collectRunCandidates` (native
+ * slots + version homes) through `readinessFromCandidate` — so the answer
+ * `agents view --json` publishes is exactly what a `run` here would find, and a
+ * remote `--device auto` dispatcher can read it instead of re-deriving freshness
+ * on its own box (which drifted: view.ts lists version homes, the router lists
+ * slots). Returns undefined when the agent has no candidates at all (nothing
+ * installed), so the field is simply absent rather than a misleading verdict.
+ */
+export async function computeAgentRunReady(agentId) {
+    const candidates = await collectRunCandidates(agentId);
+    if (candidates.length === 0)
+        return undefined;
+    const accounts = candidates.map((c) => {
+        const readiness = readinessFromCandidate(c);
+        const name = c.nativeAccount || c.accountLabel || c.email || c.version;
+        return { name, ready: readiness.ready, reason: readiness.ready ? 'ready' : readiness.reason };
+    });
+    const readyAccount = accounts.find((a) => a.ready);
+    let reason;
+    if (readyAccount) {
+        reason = `ready (${readyAccount.name})`;
+    }
+    else {
+        const reasons = [...new Set(accounts.map((a) => a.reason))];
+        reason = reasons.length === 1 ? `all ${reasons[0]}` : reasons.join(', ');
+    }
+    return { ready: !!readyAccount, reason, accounts };
+}
 /**
  * Collect structured info for one or more agents without rendering to the
  * terminal. Used by `--json` output and any programmatic consumer (e.g. the
@@ -1395,6 +1425,15 @@ export async function collectAgentsJson(filterAgentId, resourceSections, opts) {
     const note = secretsUnavailableNote(catalog);
     if (note)
         console.error(chalk.yellow(note)); // stderr — never corrupts --json stdout
+    // The one run-readiness gate per agent, computed off the router's own
+    // enumeration (PHNX-4116). Runs in parallel across agents; a harness with
+    // nothing installed yields undefined and the field is omitted.
+    const runReadyByAgent = new Map();
+    await Promise.all(agentsToShow.map(async (agentId) => {
+        const runReady = await computeAgentRunReady(agentId);
+        if (runReady)
+            runReadyByAgent.set(agentId, runReady);
+    }));
     const out = [];
     for (const agentId of agentsToShow) {
         const versions = byAgent.get(agentId) ?? [];
@@ -1406,7 +1445,13 @@ export async function collectAgentsJson(filterAgentId, resourceSections, opts) {
         // Project through the public JSON v2 serializer — the internal catalog row
         // (identityKey, home, installations) is not the machine contract.
         const accounts = accountListJson(catalog.native.filter((row) => row.agent === agentId), catalog.provider.filter((row) => row.harnesses.includes(agentId)), agentId).accounts;
-        out.push({ agent: agentId, versions, accounts, harnesses: harnesses.filter((h) => h.agent === agentId) });
+        out.push({
+            agent: agentId,
+            versions,
+            accounts,
+            runReady: runReadyByAgent.get(agentId),
+            harnesses: harnesses.filter((h) => h.agent === agentId),
+        });
     }
     return out;
 }

package/dist/index.js

@@ -78,10 +78,12 @@ if (process.argv[2] === '__claude-statusline') {
     const { runClaudeStatusLine } = await import('./lib/claude-statusline.js');
     process.exit(await runClaudeStatusLine());
 }
-// Fleet usage-sync receiver: a headed peer pipes its identity-keyed usage rows to
-// stdin, we merge them newest-wins into this box's cache (PHNX-3392). Above the
-// bootstrap line for the same reason as __claude-statusline — no update check, no
-// detached sync fork, and nothing writes to stdout to corrupt the caller's view.
+// Fleet usage-sync receiver: a headed peer pipes its daemon-state envelope to
+// stdin; we store it as that peer's file, merge its usage rows newest-wins into
+// this box's cache, and with `--reply` print our own envelope back (PHNX-3392,
+// PHNX-4116). Above the bootstrap line for the same reason as
+// __claude-statusline — no update check, no detached sync fork, and without
+// `--reply` nothing writes to stdout to corrupt the ready probe's view.
 if (process.argv[2] === '__usage-ingest') {
     const { runUsageIngest } = await import('./lib/accounting/usage-ingest.js');
     process.exit(await runUsageIngest());
@@ -110,9 +112,10 @@ if (process.argv[2] === '__daemon-run') {
     // stack to whatever the service manager had wired to stdout and never reaching
     // the daemon's own structured log. Route both into log() so the failure is in
     // logs.jsonl where `agents daemon logs` reads it, then exit non-zero and
-    // DELIBERATELY let the supervisor restart us — now paced by the plist's
-    // ThrottleInterval / the unit's StartLimitBurst. Swallowing here would be the
-    // worse failure: a daemon left alive with a dead subsystem.
+    // DELIBERATELY let the supervisor restart us — paced by the plist's
+    // ThrottleInterval / the unit's RestartSec, and never abandoned
+    // (StartLimitIntervalSec=0, PHNX-4116). Swallowing here would be the worse
+    // failure: a daemon left alive with a dead subsystem.
     const crash = (kind) => (err) => {
         const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
         try {
@@ -137,28 +140,102 @@ if (process.argv[2] === '__daemon-run') {
 // Lifecycle verbs (resume/stop/inject/watch/--active/--markdown) fall through.
 if (process.argv[2] === 'sessions') {
     const forwarded = process.argv.slice(3);
-    const { isReadQuery, resolveSessionsBin, invocation, SessionsClientError, SESSIONS_INSTALL_HINT, } = await import('./lib/sessions-client.js');
-    if (isReadQuery(forwarded)) {
-        const { spawnSync } = await import('node:child_process');
-        let bin = null;
-        try {
-            bin = resolveSessionsBin();
-        }
-        catch (err) {
-            // No standalone on this box: fall through to the in-repo engine below
-            // rather than refusing the query. The fast path is an optimization for a
-            // box that has `sessions` installed (skips bootstrap and the sessions
-            // module); a box without it must still answer `agents sessions --json`
-            // exactly as it did before PHNX-4012 — every worker in the fleet and
-            // every CI runner is such a box until @phnx-labs/sessions-cli is
-            // published, and refusing here turned main's full suite red.
-            if (!(err instanceof SessionsClientError && err.code === 'SESSIONS_BIN_MISSING'))
-                throw err;
-            if (process.env.AGENTS_SESSIONS_FASTPATH_HINT !== '0') {
-                process.stderr.write(`agents: standalone \`sessions\` not installed; using the in-process engine (${SESSIONS_INSTALL_HINT})\n`);
+    const { isReadQuery, usesFilterFlags, usesHostFlag, sessionsBinSupportsFilters, sessionsBinSupportsHost, planDeviceHostRead, resolveSessionsBin, invocation, SessionsClientError, SESSIONS_INSTALL_HINT, } = await import('./lib/sessions-client.js');
+    // Resolve the bin up front (a cheap PATH lookup): its presence decides whether
+    // we can route at all, and its VERSION decides whether the 0.2.0 filter flags
+    // (`--project`/`--since`/`--until`/`--sort`, `@version`, the shorthands) and the
+    // 0.2.1 `--host <target>` point-to-one remote read flag are recognized — an
+    // older `sessions` would mis-read them as FTS tokens, so those queries stay on
+    // the in-repo engine (which implements the same filters and the `--device`
+    // fan-out). The two floors are checked independently: a 0.2.0 binary takes the
+    // filters but not `--host`.
+    let bin = null;
+    try {
+        bin = resolveSessionsBin();
+    }
+    catch (err) {
+        // No standalone on this box: fall through to the in-repo engine below rather
+        // than refusing the query. The fast path is an optimization for a box that
+        // has `sessions` installed (skips bootstrap and the sessions module); a box
+        // without it must still answer `agents sessions --json` exactly as before.
+        if (!(err instanceof SessionsClientError && err.code === 'SESSIONS_BIN_MISSING'))
+            throw err;
+    }
+    const filters = bin !== null && usesFilterFlags(forwarded) ? sessionsBinSupportsFilters(bin) : false;
+    const host = bin !== null && usesHostFlag(forwarded) ? sessionsBinSupportsHost(bin) : false;
+    // PHNX-4012 local-orchestration collapse: a read query carrying `--device
+    // <name>` (and no explicit `--host`) routes through the standalone's
+    // point-to-one remote read — `sessions <read args> --host ssh://<resolved>` —
+    // instead of the in-repo `--device` peer fan-out, WHEN this box's standalone
+    // supports `--host` (>=0.2.1). `planDeviceHostRead` is pure and probes nothing,
+    // so a non-device read never pays a `sessions --version` spawn (the probe fires
+    // only after a device read is detected). If the PEER lacks the standalone the
+    // ssh `bash -lc` command-not-found surfaces as exit 127 — a CAPABILITY gate
+    // (same spirit as #3687's version gate, keyed on a specific documented signal),
+    // on which we FALL THROUGH to the in-repo `--device` fan-out below so the read
+    // still succeeds. Everything else (e.g. 255 unreachable) propagates verbatim.
+    // The in-repo fan-out is deliberately KEPT here as the path for un-upgraded
+    // peers; its eventual removal is a follow-up gated on fleet-wide 0.2.1 (a
+    // separate PHNX-4012 follow-up, see the PR body), not this PR.
+    if (bin !== null) {
+        const deviceRead = planDeviceHostRead(forwarded, { filters });
+        if (deviceRead && sessionsBinSupportsHost(bin)) {
+            let target = null;
+            try {
+                const { resolveRemoteDevice } = await import('./lib/ssh-tunnel.js');
+                target = (await resolveRemoteDevice(deviceRead.device, {})).target;
+            }
+            catch {
+                // Unknown/unresolvable device — fall through to the in-repo path, which
+                // resolves `--device` against the same fleet registry and emits the
+                // canonical error; do not duplicate that error here.
+                target = null;
+            }
+            if (target !== null) {
+                const { spawnSync } = await import('node:child_process');
+                const { command, prefix } = invocation(bin);
+                const hostArgs = [...deviceRead.readArgs, '--host', `ssh://${target}`];
+                // Capture (not `stdio: 'inherit'`) so a 127 capability miss can fall
+                // through silently instead of leaking the peer's command-not-found before
+                // the in-repo read re-answers. Reads are bounded, so buffering is fine;
+                // force color + geometry through the capture when the caller is at a real
+                // terminal and not asking for `--json`, matching the passthrough renderer.
+                const childEnv = { ...process.env };
+                if (process.stdout.isTTY && !hostArgs.includes('--json')) {
+                    if (childEnv.FORCE_COLOR === undefined)
+                        childEnv.FORCE_COLOR = '1';
+                    if (process.stdout.columns)
+                        childEnv.COLUMNS = String(process.stdout.columns);
+                    if (process.stdout.rows)
+                        childEnv.LINES = String(process.stdout.rows);
+                }
+                const res = spawnSync(command, [...prefix, ...hostArgs], {
+                    encoding: 'utf8',
+                    env: childEnv,
+                    maxBuffer: 256 * 1024 * 1024,
+                });
+                if (res.error) {
+                    process.stderr.write(`Failed to run \`sessions\`: ${res.error.message}\n`);
+                    process.exit(1);
+                }
+                // Exit 127 = the peer has no standalone `sessions` on PATH (ssh/`bash
+                // -lc` command-not-found). Fall through to the in-repo fan-out rather
+                // than surfacing a broken read.
+                if (res.status !== 127) {
+                    if (res.stdout)
+                        process.stdout.write(res.stdout);
+                    if (res.stderr)
+                        process.stderr.write(res.stderr);
+                    process.exit(res.status ?? 1);
+                }
+                // 127: fall through. `forwarded` still carries `--device`, so the
+                // `isReadQuery` check below is false and bootstrap's in-repo path answers.
             }
         }
+    }
+    if (isReadQuery(forwarded, { filters, host })) {
         if (bin) {
+            const { spawnSync } = await import('node:child_process');
             const { command, prefix } = invocation(bin);
             const res = spawnSync(command, [...prefix, ...forwarded], { stdio: 'inherit' });
             if (res.error) {
@@ -167,6 +244,10 @@ if (process.argv[2] === 'sessions') {
             }
             process.exit(res.status ?? 1);
         }
+        // A read query on a box with no standalone: hint once, then fall through.
+        if (process.env.AGENTS_SESSIONS_FASTPATH_HINT !== '0') {
+            process.stderr.write(`agents: standalone \`sessions\` not installed; using the in-process engine (${SESSIONS_INSTALL_HINT})\n`);
+        }
     }
 }
 // Full CLI: commander tree, update checks, migrations, parse. Static imports

package/dist/lib/account-capabilities.js

@@ -30,8 +30,6 @@ export const NATIVE_ACCOUNT_CAPABILITIES = {
     antigravity: { inspection: 'opaque', scope: 'device', status: 'unsupported' },
     droid: { inspection: 'opaque', scope: 'device', status: 'unsupported' },
     opencode: { inspection: 'opaque', scope: 'device', status: 'unsupported' },
-    // Discoverable in the list, but not nameable.
-    gemini: { inspection: 'email', scope: 'unsupported', status: 'discovery-only' },
     copilot: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
     openclaw: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
     amp: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },

package/dist/lib/account-catalog.d.ts

@@ -90,6 +90,19 @@ export interface NativeAccountCatalogRow {
     usageSnapshot?: UsageSnapshot | null;
     /** Raw usage fetch error, for headless/unverified labeling alongside the bars. */
     usageError?: string | null;
+    /**
+     * The token FACT for this account ON THIS BOX (PHNX-4116): the credential kind
+     * plus its file date — `sk-ant-oat01 (Sep 16)` for a Claude slot's
+     * `.claude/.oauth_token`, `api key (present)` for a provider-key harness — or
+     * `no token` when the credential file is absent. A fact, never a verdict word.
+     */
+    token: string;
+    /**
+     * The auth FACT for this account ON THIS BOX (PHNX-4116): `last used ok 12m
+     * ago` / `last auth failure 401 Sep 20 14:02` / `rate-limited until 15:00` /
+     * `not used on this box yet`, from the recorded run outcome (or a real probe).
+     */
+    lastAuth: string;
     fix: string | null;
 }
 export interface AccountDeviceVerdict {
@@ -155,6 +168,17 @@ export interface AccountListEntryJson {
     /** The live usage snapshot backing `usage`, when available — additive, not breaking. */
     usageSnapshot?: UsageSnapshot | null;
     usageError?: string | null;
+    /**
+     * The token FACT for this account on the box that emitted this JSON (PHNX-4116):
+     * `sk-ant-oat01 (Sep 16)` / `api key (present)` / `no token`. A fact, not a verdict.
+     */
+    token: string;
+    /**
+     * The auth FACT for this account on the box that emitted this JSON (PHNX-4116):
+     * `last used ok 12m ago` / `last auth failure 401 Sep 20 14:02` / `not used on
+     * this box yet`. Reflects the emitting box only; `devices[]` carries the fleet.
+     */
+    lastAuth: string;
     fix: string | null;
 }
 interface AccountListJson {
@@ -184,6 +208,14 @@ type CatalogMeta = Pick<Meta, 'accounts' | 'deviceAccounts'>;
  * silently dropped from the list nor shown as connected.
  */
 export declare function buildNativeCatalog(rows: NativeHomeRow[], meta: CatalogMeta, globalDefault?: (agent: AgentId) => string | null): NativeAccountCatalogRow[];
+/**
+ * The token FACT for a Claude account ON THIS BOX (PHNX-4116): the slot/home
+ * `.claude/.oauth_token` scheme prefix + its file date, else a present native
+ * credential, else `no token`. For non-Claude native rows it reports credential
+ * presence generically. `dir` is the slot dir when the account has one, else the
+ * local version home. A fact, never a verdict.
+ */
+export declare function readTokenFact(agent: AgentId, dir: string | null): string;
 export declare function toProviderRow(account: CredentialAccount, meta: Pick<Meta, 'accounts'>): ProviderAccountCatalogRow;
 /**
  * Wire the real collectors to the pure builder. This is the canonical
@@ -215,6 +247,12 @@ export declare const OVERVIEW_MAX_USAGE_WINDOWS = 2;
  * cannot drift.
  */
 export declare const ACCOUNT_LISTING_LEGEND = "* stale usage \u00B7 a healthy account carries no state \u00B7 identity + per-box state: agents accounts list --fleet";
+/**
+ * Colour the auth FACT by what it states (PHNX-4116): a recent success is green,
+ * a server rejection red, a throttle yellow, and "not used on this box yet" the
+ * neutral gray of a fact that carries no alarm.
+ */
+export declare function authFactNote(lastAuth: string): string;
 /** Shared text renderer used by both `accounts list` and account-first `view`. */
 export declare function renderAccountRows(rows: NativeAccountCatalogRow[], opts: {
     heading?: boolean;