@phnx-labs/agents-cli 1.22.117 → 1.22.119

package/dist/commands/setup-preferences.js

@@ -13,9 +13,8 @@
  * partial state.
  */
 import chalk from 'chalk';
-import { listInstalledBrowsers } from '../lib/browser/chrome.js';
-import { DEFAULT_BROWSER_PROFILE_NAME, getAutoDetectedProfile, createProfile, findFreeProfilePort, getConfiguredDefaultProfileName, } from '../lib/browser/profiles.js';
-import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
+import { browserInstalled, runBrowser } from '../lib/browser-client.js';
+import { buildBrowserContext } from '../lib/browser/context.js';
 import { getConfigValue, setConfigValue } from '../lib/device-config.js';
 import { loadDevices } from '../lib/devices/registry.js';
 import { machineId } from '../lib/machine-id.js';
@@ -38,14 +37,6 @@ export function defaultInteractiveHostChoice(candidates, self = machineId()) {
         return null;
     return candidates.includes(self) ? self : candidates[0];
 }
-/**
- * The browser picker's highlighted default — the same browser auto-detect
- * would win, since `listInstalledBrowsers` returns platform priority order
- * (macOS: chrome first). null when nothing is installed.
- */
-export function defaultBrowserChoice(installed) {
-    return installed.length > 0 ? installed[0].browserType : null;
-}
 /**
  * Offer to set the interactive host when none is configured and the registry
  * has more than one macOS device. Returns true when a host was set. Silent
@@ -94,48 +85,26 @@ export async function maybePickBrowserProfile(deps = {}) {
     const interactive = deps.interactive ?? isInteractiveTerminal();
     if (!interactive)
         return false;
-    if (getConfiguredDefaultProfileName())
+    // Already chosen (by an earlier setup, `agents browser use`, or browser-cli
+    // directly) — never re-pin behind the user's back.
+    if (getConfigValue('browser.profile').value)
         return false;
-    if (await getAutoDetectedProfile())
+    // The engine owns detection and profile creation (PHNX-4101); it is optional,
+    // so skip the pick quietly when it is not installed rather than nagging.
+    if (!browserInstalled())
         return false;
-    const installed = listInstalledBrowsers();
-    if (installed.length === 0)
+    // Let the engine detect installed browsers and create a machine-local profile
+    // for each (idempotent), then open its own picker to set this machine's default.
+    const context = await buildBrowserContext();
+    const seed = await runBrowser({ argv: ['profiles', 'seed'], context });
+    if (seed.exitCode !== 0)
         return false;
-    const config = {
-        message: 'Which browser should agents drive on THIS machine?',
-        default: defaultBrowserChoice(installed) ?? SKIP,
-        choices: [
-            ...installed.map((b) => ({ name: `${b.browserType}  ${chalk.dim(b.binary)}`, value: b.browserType })),
-            { name: `None ${chalk.dim('— this box uses the fleet hub (agents config set browser.device <host>)')}`, value: SKIP },
-        ],
-    };
-    // The prompt is the only non-testable boundary here, so it is injectable —
-    // everything after (createProfile, setConfigValue) runs for real.
-    let picked;
-    if (deps.select) {
-        picked = await deps.select(config);
-    }
-    else {
-        const { select } = await import('@inquirer/prompts');
-        picked = await select(config);
-    }
-    if (picked === SKIP)
+    await runBrowser({ argv: ['use'], context });
+    const chosen = getConfigValue('browser.profile').value;
+    if (!chosen)
         return false;
-    const chosen = installed.find((b) => b.browserType === picked) ?? installed[0];
-    const freePort = await findFreeProfilePort();
-    const profile = {
-        name: DEFAULT_BROWSER_PROFILE_NAME,
-        description: `${chosen.browserType} profile (chosen during setup)`,
-        browser: chosen.browserType,
-        binary: chosen.binary,
-        endpoints: [`cdp://127.0.0.1:${freePort}`],
-        viewport: { width: DEFAULT_VIEWPORT.width, height: DEFAULT_VIEWPORT.height },
-    };
-    await createProfile(profile);
-    // The same key `agents browser use` writes (device-local).
-    setConfigValue('browser.profile', profile.name);
-    console.log(chalk.green(`Browser: '${chosen.browserType}'`) +
-        chalk.dim(` — profile "${profile.name}" is this machine's default (agents browser use to change).`));
+    console.log(chalk.green(`Browser: '${chosen}'`) +
+        chalk.dim(' — this machine\'s default (agents browser use to change).'));
     return true;
 }
 /**

package/dist/commands/setup.js

@@ -31,8 +31,7 @@ import { registerAliasCommand } from './alias.js';
 import { registerBetaCommands } from './beta.js';
 import { addUrlSchemeSubcommands } from './open.js';
 import { runPreferencesStep } from './setup-preferences.js';
-import { getConfiguredDefaultProfileName, getProfile, getAutoDetectedProfile, isProfileLaunchableHere } from '../lib/browser/profiles.js';
-import { listInstalledBrowsers } from '../lib/browser/chrome.js';
+import { browserInstalled } from '../lib/browser-client.js';
 import { probeComputerTrust } from './computer.js';
 import { loadDevices } from '../lib/devices/registry.js';
 import { getConfigValue } from '../lib/device-config.js';
@@ -269,12 +268,13 @@ export async function ensureInitialized(program) {
     await runSetup(program, { suppressFooter: true });
 }
 export async function getSetupStatus() {
-    const configuredBrowserProfile = getConfiguredDefaultProfileName();
-    const browserProfile = configuredBrowserProfile
-        ? await getProfile(configuredBrowserProfile)
-        : await getAutoDetectedProfile();
-    const browserReady = browserProfile !== null && isProfileLaunchableHere(browserProfile);
-    const installedBrowsers = listInstalledBrowsers();
+    // Browser readiness is now config + standalone presence (PHNX-4101): the engine
+    // (@phnx-labs/browser-cli) owns profile declarations and launchability, so
+    // agents-cli reads the shared default-profile key it and browser-cli both write
+    // rather than resolving a profile through a deleted in-repo engine.
+    const browserCliInstalled = browserInstalled();
+    const configuredBrowserProfile = getConfigValue('browser.profile').value;
+    const browserReady = browserCliInstalled && !!configuredBrowserProfile;
     const computerState = process.platform === 'darwin' ? (await probeComputerTrust() ? 'ready' : 'missing') : 'n/a';
     const devices = await loadDevices();
     const coreReady = isGitRepo(getAgentsDir());
@@ -286,7 +286,7 @@ export async function getSetupStatus() {
     const defaultBrowser = getConfigValue('browser.profile').value;
     return [
         { phase: 'core', state: coreReady ? 'ready' : 'missing', detail: coreReady ? 'system repo ready' : 'system repo missing' },
-        { phase: 'browser', state: browserReady ? 'ready' : 'missing', detail: browserReady ? `profile ${browserProfile.name}` : browserProfile ? `profile ${browserProfile.name} cannot launch here` : installedBrowsers.length ? 'no default profile' : 'no supported browser found' },
+        { phase: 'browser', state: browserReady ? 'ready' : 'missing', detail: browserReady ? `profile ${configuredBrowserProfile}` : !browserCliInstalled ? 'browser CLI not installed (npm i -g @phnx-labs/browser-cli)' : 'no default profile (agents setup browser)' },
         { phase: 'computer', state: computerState, detail: computerState === 'ready' ? 'helper trusted' : computerState === 'n/a' ? 'macOS local setup only' : 'helper not running or not trusted' },
         { phase: 'secrets', state: secretsReady ? 'ready' : 'missing', detail: secretsReady ? 'defaults chosen' : 'defaults not chosen' },
         { phase: 'term', state: termReady ? 'ready' : 'missing', detail: termReady ? 'installed' : 'not installed (accounts add/login spawn it)' },

package/dist/commands/ssh.js

@@ -789,7 +789,16 @@ async function runFleetPing(opts) {
     if (opts.local) {
         const { authRows: rows } = await refreshLocalFleetAuthState({ force: true });
         if (opts.json) {
-            console.log(JSON.stringify({ host: self, rows }));
+            // Per-agent launchability from the SAME run-router path the local readiness
+            // check uses (`collectRunCandidates`/`isLaunchableSignedIn`), so a consumer
+            // can tell a box that simply could not probe — a worker's setup-token box,
+            // or a headed box that spent its usage-endpoint budget, both DROP their
+            // `no_evidence` row — from a box with no credential at all. From `rows`
+            // alone the two are indistinguishable, which broke `--host` routine
+            // readiness on every worker (PHNX-4116).
+            const { collectRunCandidates } = await import('../lib/accounting/rotate.js');
+            const launchable = (await Promise.all(ALL_AGENT_IDS.map(async (agent) => (await collectRunCandidates(agent)).some((candidate) => candidate.signedIn) ? agent : null))).filter((agent) => agent !== null);
+            console.log(JSON.stringify({ host: self, rows, launchable }));
         }
         else {
             for (const line of renderAuthMatrix([{ host: self, rows }], { verbose: opts.verbose }))

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' },