@phnx-labs/agents-cli 1.22.116 → 1.22.118

package/dist/lib/fleet-shared-state.js

@@ -1,11 +1,17 @@
 /**
- * Non-secret daemon state exchanged through the already fleet-synced user repo.
+ * Non-secret daemon state exchanged over SSH between fleet devices (PHNX-4116).
  *
- * Each device owns exactly one file under `~/.agents/devices/<device>/`, so
- * normal `agents repo push/pull user` merges the fleet without devices dialing
- * one another on every daemon tick. OAuth/setup-token values never belong here:
- * auth publishes only a readiness verdict; the existing encrypted SSH transport
- * remains the one path that may carry secret material.
+ * Each device owns exactly one file under `~/.agents/devices/<device>/`
+ * (`daemon-state.json`, UNTRACKED in the user repo). A device writes its OWN
+ * file locally; a PEER's file on this box is written only by the usage-sync
+ * exchange — a headed daemon dials each peer with `agents __usage-ingest
+ * --reply`, sending its own envelope on stdin and writing the peer's reply
+ * envelope here stamped with `receivedAt`. The envelope used to ride the user
+ * repo as a tracked file, which turned the shared store into 18k `chore(devices)`
+ * commits and wedged every clone behind a `git fetch` that timed out; git now
+ * carries only human-authored resources. OAuth/setup-token values never belong
+ * here: auth publishes only a readiness verdict; the existing encrypted SSH
+ * bundle push remains the one path that may carry secret material.
  */
 import * as fs from 'node:fs';
 import * as fsp from 'node:fs/promises';
@@ -23,11 +29,19 @@ export function fleetSharedStatePath(device, userAgentsDir = getUserAgentsDir())
 function isRecord(value) {
     return !!value && typeof value === 'object' && !Array.isArray(value);
 }
-function parseFleetSharedDeviceState(raw, owner) {
-    const parsed = JSON.parse(raw);
-    if (!isRecord(parsed) || parsed.version !== FLEET_SHARED_STATE_VERSION || parsed.device !== owner) {
+/**
+ * Validate an already-parsed envelope. `owner` pins the `device` field when the
+ * caller knows whose envelope this must be (a file under `devices/<owner>/`);
+ * an envelope arriving over the exchange names its own owner, so the caller
+ * passes none and checks `device` against the dialed peer afterwards.
+ */
+export function parseFleetSharedDeviceStateEnvelope(parsed, owner) {
+    if (!isRecord(parsed) || parsed.version !== FLEET_SHARED_STATE_VERSION || typeof parsed.device !== 'string' || !parsed.device) {
         throw new Error('unrecognized shared-state envelope');
     }
+    if (owner !== undefined && parsed.device !== owner)
+        throw new Error('unrecognized shared-state envelope');
+    assertValidDeviceName(parsed.device);
     const usage = parsed.usage;
     if (usage !== undefined && (!isRecord(usage) || !isRecord(usage.rows))) {
         throw new Error('unrecognized usage snapshot');
@@ -41,8 +55,18 @@ function parseFleetSharedDeviceState(raw, owner) {
     if (sessions !== undefined && (!isRecord(sessions) || !Array.isArray(sessions.rows))) {
         throw new Error('unrecognized session mirror');
     }
+    const accounts = parsed.accounts;
+    if (accounts !== undefined && (!isRecord(accounts) || !Array.isArray(accounts.rows))) {
+        throw new Error('unrecognized account verdict rows');
+    }
+    if (parsed.receivedAt !== undefined && (typeof parsed.receivedAt !== 'number' || !Number.isFinite(parsed.receivedAt))) {
+        throw new Error('unrecognized receivedAt');
+    }
     return parsed;
 }
+function parseFleetSharedDeviceState(raw, owner) {
+    return parseFleetSharedDeviceStateEnvelope(JSON.parse(raw), owner);
+}
 /**
  * Merge one daemon-owned field into this device's shared file under a real
  * inter-process lock. Stable serialization avoids dirtying the user repo when
@@ -63,6 +87,8 @@ function mergeFleetState(currentRaw, device, patch) {
         ...(patch.usage !== undefined ? { usage: patch.usage } : {}),
         ...(patch.auth !== undefined ? { auth: patch.auth } : {}),
         ...(patch.sessions !== undefined ? { sessions: patch.sessions } : {}),
+        ...(patch.accounts !== undefined ? { accounts: patch.accounts } : {}),
+        ...(patch.receivedAt !== undefined ? { receivedAt: patch.receivedAt } : {}),
         version: FLEET_SHARED_STATE_VERSION,
         device,
     };
@@ -138,3 +164,46 @@ export function readFleetSharedDeviceStates(userAgentsDir = getUserAgentsDir())
     }
     return { states, errors };
 }
+/**
+ * This device's own envelope as it stands on disk — what the usage-sync exchange
+ * sends to peers and what `__usage-ingest --reply` prints back. A device that has
+ * never published anything yields the bare `{version, device}` envelope, so a
+ * peer still learns the device exists and answered.
+ */
+export function readOwnFleetSharedDeviceState(device, userAgentsDir = getUserAgentsDir()) {
+    const file = fleetSharedStatePath(device, userAgentsDir);
+    let raw = '';
+    try {
+        raw = fs.readFileSync(file, 'utf-8');
+    }
+    catch { /* never published → bare envelope */ }
+    if (!raw.trim())
+        return { version: FLEET_SHARED_STATE_VERSION, device };
+    const state = parseFleetSharedDeviceState(raw, device);
+    // `receivedAt` is a receiver-side stamp; the owner never advertises one.
+    const { receivedAt: _receivedAt, ...own } = state;
+    return own;
+}
+/**
+ * Store a PEER's envelope, received over the SSH exchange, in that peer's file on
+ * this box, stamped with `receivedAt`. Merges field-by-field onto whatever the
+ * file already holds, so a partial envelope (a placement probe sends usage only)
+ * refreshes that field without erasing the peer's last auth verdict, session
+ * digests, or account rows. The five readers of `devices/<peer>/daemon-state.json`
+ * (usage merge, poller claims, auth verdicts, session mirror, account catalog)
+ * are unchanged by the transport swap. Async because it runs on the daemon's
+ * usage-sync tick once per peer reply: the sync lock would `sleepSync` the event
+ * loop for up to 30 s under contention (see {@link updateFleetSharedDeviceStateAsync}).
+ */
+export async function storePeerFleetSharedDeviceState(state, userAgentsDir = getUserAgentsDir(), receivedAt = Date.now()) {
+    const patch = { receivedAt };
+    if (state.usage !== undefined)
+        patch.usage = state.usage;
+    if (state.auth !== undefined)
+        patch.auth = state.auth;
+    if (state.sessions !== undefined)
+        patch.sessions = state.sessions;
+    if (state.accounts !== undefined)
+        patch.accounts = state.accounts;
+    return updateFleetSharedDeviceStateAsync(state.device, patch, userAgentsDir);
+}

package/dist/lib/fs-atomic.js

@@ -106,6 +106,21 @@ export function withFileLock(filePath, fn, opts = {}) {
         }
         catch (err) {
             lastError = err;
+            // proper-lockfile breaks stale locks with rmdir, which fails with ENOTDIR
+            // when a prior crash left a regular file instead of the expected directory.
+            // Remove the stale file so the next attempt can succeed. Match
+            // proper-lockfile's own path resolution: realpath when the option is on
+            // (the default), raw path when it is off.
+            if (err instanceof Error && err.code === 'ENOTDIR') {
+                try {
+                    const base = (opts.realpath ?? true) ? fs.realpathSync(filePath) : filePath;
+                    const lockPath = `${base}.lock`;
+                    const st = fs.statSync(lockPath);
+                    if (st.isFile())
+                        fs.unlinkSync(lockPath);
+                }
+                catch { /* best effort */ }
+            }
             if (Date.now() >= deadline)
                 break;
             const backoff = Math.min(LOCK_RETRY_MIN_MS * (attempt + 1), LOCK_RETRY_MAX_MS);
@@ -175,6 +190,16 @@ export async function withFileLockAsync(filePath, fn, opts = {}) {
         }
         catch (err) {
             lastError = err;
+            if (err instanceof Error && err.code === 'ENOTDIR') {
+                try {
+                    const base = (opts.realpath ?? true) ? fs.realpathSync(filePath) : filePath;
+                    const lockPath = `${base}.lock`;
+                    const st = fs.statSync(lockPath);
+                    if (st.isFile())
+                        fs.unlinkSync(lockPath);
+                }
+                catch { /* best effort */ }
+            }
             if (Date.now() >= deadline)
                 break;
             const backoff = Math.min(LOCK_RETRY_MIN_MS * (attempt + 1), LOCK_RETRY_MAX_MS);

package/dist/lib/harness-auth-capabilities.js

@@ -17,7 +17,6 @@ export const HARNESS_AUTH = {
     kimi: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: 'KIMI_CODE_HOME' },
     antigravity: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },
     droid: { login: null, status: null, identity: 'opaque', worker: 'api-key:FACTORY_API_KEY', slotEnv: null },
-    gemini: { login: null, status: null, identity: 'email', worker: 'none', slotEnv: null },
     copilot: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: 'COPILOT_HOME' },
     openclaw: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },
     amp: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },

package/dist/lib/helper-versions.js

@@ -41,7 +41,7 @@
  * it would claim a distribution responsibility agents-cli no longer has.
  */
 export const HELPER_RELEASES = {
-    menubar: { tagPrefix: 'menubar', floor: '1.5.0' },
+    menubar: { tagPrefix: 'menubar', floor: '1.6.1' },
 };
 /** The release tag for one helper at one version, e.g. `menubar/v1.0.0`. */
 export function helperTag(helper, version) {

package/dist/lib/hooks/cache.d.ts

@@ -45,6 +45,13 @@ export declare function generateHookShim(args: {
     cache?: HookCacheConfig | null;
     matches?: HookMatches;
     paths?: HookShimPaths;
+    /**
+     * Deny the tool call (exit 2) when the source script is missing instead of
+     * failing with 127, which every harness reads as "allow". Set for
+     * PreToolUse hooks: a guard whose script vanished (version pruned, sync
+     * rewriting the hooks dir) must not silently wave tool calls through.
+     */
+    failClosed?: boolean;
 }): string;
 /**
  * Remove a hook's shim. Called by the registrar's garbage collection when a

package/dist/lib/hooks/cache.js

@@ -119,7 +119,7 @@ export function generateHookShim(args) {
     const logsDir = args.paths?.logsDir ?? getLogsDir();
     const perfDir = args.paths?.perfDir ?? getPerfDir();
     const shimPath = resolveContainedHookShimPath(shimsDir, args.name);
-    const content = renderShim(args.name, args.scriptPath, args.cache ?? null, args.matches, { cacheDir, logsDir, perfDir });
+    const content = renderShim(args.name, args.scriptPath, args.cache ?? null, args.matches, { cacheDir, logsDir, perfDir }, args.failClosed === true);
     fs.mkdirSync(shimsDir, { recursive: true });
     let existing = null;
     if (fs.existsSync(shimPath)) {
@@ -363,7 +363,7 @@ exit "$EXIT"`;
  * a gate-only pass-through: it forwards stdin to the script and its stdout back,
  * with no cache read/write.
  */
-function renderShim(name, scriptPath, cache, matches, paths) {
+function renderShim(name, scriptPath, cache, matches, paths, failClosed = false) {
     const ttl = cache ? (typeof cache.ttl === 'number' ? cache.ttl : (parseDuration(cache.ttl) ?? 0)) : 0;
     const key = cache?.key ?? 'global';
     const prefetch = cache?.prefetch ?? 'none';
@@ -394,6 +394,7 @@ TTL=${ttl}
 PREFETCH=${q(prefetch)}
 KEY_MODE=${q(key)}
 MATCHES_JSON=${q(matchesJson)}
+FAIL_CLOSED=${failClosed ? 1 : 0}
 
 mkdir -p "$CACHE_DIR" "$LOGS_DIR" "$PERF_DIR"
 
@@ -458,6 +459,30 @@ if [ -n "$MATCHES_JSON" ]; then
     exit 0
   fi
 fi
+# A source that is not on disk cannot be executed: bash exits 127, and the
+# harnesses that share the exit-2 deny contract (Claude Code, Codex, Droid)
+# read anything else as "allow" -- a guard silently disabled. Deny instead and
+# name the repair, but only for a PreToolUse firing that the matches: gate
+# above let through: one shim serves every event a hook declares, so a
+# SessionStart or Stop leg of the same hook must not wedge a session, and a
+# fire the predicates would have skipped must not turn into a denial. Other
+# shims keep their existing path (a cached hook still serves its cache).
+if [ "$FAIL_CLOSED" = 1 ] && [ ! -f "$SOURCE" ]; then
+  _EVT="$(printf '%s' "$STDIN_PAYLOAD" | "$PY" -c 'import json, sys
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    d = {}
+print(d.get("hook_event_name") or d.get("hookEventName") or "")' 2>/dev/null || true)"
+  if [ -z "$_EVT" ] || [ "$_EVT" = PreToolUse ]; then
+    _TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    printf '{"ts":"%s","event":"hook.fire","hook":"%s","ms":0,"cache":"missing-source","exit":2}\\n' \\
+      "$_TS" "$HOOK_NAME" >>"$LOGS_DIR/events-$(date -u +%Y-%m-%d).jsonl" 2>/dev/null || true
+    printf '%s: hook source is missing (%s); refusing the tool call unchecked (fail-closed). Run: agents hooks sync\\n' \\
+      "$HOOK_NAME" "$SOURCE" >&2
+    exit 2
+  fi
+fi
 ${cache ? CACHE_TAIL : PASSTHROUGH_TAIL}
 `;
 }

package/dist/lib/hooks/install.js

@@ -363,7 +363,13 @@ function resolveHookCommand(name, hookDef, resolveScript) {
     // script when predicates don't hold) and, when `cache:` is set, layers the
     // cache/timing machinery on top; with neither, it is a pure pass-through
     // timing wrapper.
-    return toPortableCommand(generateHookShim({ name, scriptPath, cache, matches }));
+    return toPortableCommand(generateHookShim({
+        name,
+        scriptPath,
+        cache,
+        matches,
+        failClosed: hookDef.events.includes('PreToolUse'),
+    }));
 }
 /**
  * Extensions that are NEVER hooks — docs, configuration, plain data. A file

package/dist/lib/hosts/ready.d.ts

@@ -57,8 +57,19 @@ export interface ReadyProbe {
  * `$LASTEXITCODE` (no `printf`/`||`); `parseReadyProbe` keys off the sentinel
  * substring, so the missing leading newline vs the POSIX `printf '\n…'` form is
  * absorbed by its `.trim()`. Pure/exported so both branches are unit-testable.
+ *
+ * With `ingestUsage`, the probe first runs `agents __usage-ingest` on the
+ * dispatcher's daemon-state envelope, which the caller pipes to stdin
+ * (PHNX-4116): the chosen worker then holds the dispatcher's current usage
+ * numbers at dispatch instead of waiting for the next 15-minute usage-sync
+ * tick. The ingest writes nothing to stdout (only `--reply` does), so the
+ * version/sentinel/listing shape `parseReadyProbe` reads is unchanged. On
+ * Windows the `agents.ps1` shim drops ssh-piped stdin, so PowerShell reads it
+ * into a temp file and hands the verb `--from <path>`.
  */
-export declare function buildReadyProbeCommand(os?: string): string;
+export declare function buildReadyProbeCommand(os?: string, opts?: {
+    ingestUsage?: boolean;
+}): string;
 export declare function readyProbe(target: string, os?: string, extraSshArgs?: string[]): ReadyProbe;
 /** Pure parser for `readyProbe` output (unit-tested without ssh). */
 export declare function parseReadyProbe(stdout: string): ReadyProbe;
@@ -92,6 +103,12 @@ interface ViewAgentAccountEligibility {
     signedIn: boolean | undefined;
     /** At least one account can launch immediately or enter the harness login flow. */
     pickerEligible: boolean | undefined;
+    /**
+     * The remote box's own aggregate exclusion reason when it is not signed in
+     * (`runReady.reason` — e.g. `all signed_out`), for the operator-facing
+     * placement error. Undefined when ready, absent, or on an older remote CLI.
+     */
+    reason?: string;
 }
 /**
  * Read the two account gates automatic placement needs from `agents view
@@ -99,13 +116,26 @@ interface ViewAgentAccountEligibility {
  * the login flow, but it must not route to a device whose every signed-in
  * account is throttled.
  *
- * The sign-in gate reads the per-version `launchable` field — the strict
- * per-version launch truth (`isLaunchableSignedIn`) — so a remote box is judged
- * by the SAME launchability the local candidate uses (`collectRunCandidates` →
- * `isLaunchableSignedIn`), not the display `signedIn` that inherits the
- * active/global HOME login and passes a box that dies at spawn (PHNX-3466). An
- * older remote CLI omits `launchable`, so it falls back to `signedIn` — the
- * pre-fix behavior, so a rolling fleet does not regress.
+ * ONE readiness gate, computed on the box that runs (PHNX-4116). The remote box
+ * publishes `runReady` — the router's own `collectRunCandidates` →
+ * `readinessFromCandidate` verdict over its native slots AND version homes — so
+ * this reads that answer rather than re-deriving freshness here. The
+ * dispatching box re-deriving from the per-version `versions[]` list was the bug:
+ * that list enumerates version homes, misses the account slots a run picks from,
+ * and applied a 40-minute usage-freshness refusal a synced-only worker could
+ * never satisfy, turning a usage-sync lag into "no ready device" while
+ * `--device <name>` on the same box launched fine.
+ *
+ * An older remote CLI omits `runReady`; the one-release fallback derives the
+ * verdict from the per-version list the same way the pre-PHNX-4116 dispatcher
+ * did: the strict `launchable` signal (`isLaunchableSignedIn`, PHNX-3466) for
+ * sign-in, MINUS a FRESH throttle (`rate_limited`/`out_of_credits` captured
+ * within {@link USAGE_STALE_REFUSAL_MAX_AGE_MS}) or a FRESH dead auth verdict
+ * (checked within {@link AUTH_PROBE_MAX_AGE_MS}, {@link isDeadVerdict}). A stale
+ * reading is UNVERIFIED, not disqualifying (PHNX-4116/#3700), so a usage-sync
+ * lag never bars an old-CLI worker `--device <name>` would launch fine — but a
+ * throttled-but-launchable worker no longer reads `signedIn: true` and slips
+ * into `--device auto`'s pick during a rolling upgrade.
  */
 export declare function viewAgentAccountEligibility(view: string, agent: string, now?: number): ViewAgentAccountEligibility;
 export declare function viewAgentSignedIn(view: string, agent: string): boolean | undefined;

package/dist/lib/hosts/ready.js

@@ -102,15 +102,31 @@ const READY_MARKER = '@@AGENTS_READY@@';
  * `$LASTEXITCODE` (no `printf`/`||`); `parseReadyProbe` keys off the sentinel
  * substring, so the missing leading newline vs the POSIX `printf '\n…'` form is
  * absorbed by its `.trim()`. Pure/exported so both branches are unit-testable.
+ *
+ * With `ingestUsage`, the probe first runs `agents __usage-ingest` on the
+ * dispatcher's daemon-state envelope, which the caller pipes to stdin
+ * (PHNX-4116): the chosen worker then holds the dispatcher's current usage
+ * numbers at dispatch instead of waiting for the next 15-minute usage-sync
+ * tick. The ingest writes nothing to stdout (only `--reply` does), so the
+ * version/sentinel/listing shape `parseReadyProbe` reads is unchanged. On
+ * Windows the `agents.ps1` shim drops ssh-piped stdin, so PowerShell reads it
+ * into a temp file and hands the verb `--from <path>`.
  */
-export function buildReadyProbeCommand(os) {
+export function buildReadyProbeCommand(os, opts = {}) {
     if (remoteShellFor(os) === 'powershell') {
-        const script = `${POWERSHELL_PROGRESS_SILENCE}; ` +
+        const ingest = opts.ingestUsage
+            ? '$in = [Console]::In.ReadToEnd(); $tmp = $null; ' +
+                'try { $tmp = [System.IO.Path]::GetTempFileName(); [System.IO.File]::WriteAllText($tmp, $in); ' +
+                'agents __usage-ingest --from $tmp 2>$null } ' +
+                'finally { if ($tmp) { Remove-Item -LiteralPath $tmp -Force -ErrorAction SilentlyContinue } }; '
+            : '';
+        const script = `${POWERSHELL_PROGRESS_SILENCE}; ${ingest}` +
             `agents --version 2>$null; Write-Output "${READY_MARKER}"; ` +
             `agents view --json 2>$null; if ($LASTEXITCODE -ne 0) { agents list 2>$null }`;
         return `powershell -NoProfile -EncodedCommand ${encodePowershell(script)}`;
     }
-    const script = `agents --version 2>/dev/null; printf '\\n${READY_MARKER}\\n'; ` +
+    const script = `${opts.ingestUsage ? 'agents __usage-ingest 2>/dev/null; ' : ''}` +
+        `agents --version 2>/dev/null; printf '\\n${READY_MARKER}\\n'; ` +
         `agents view --json 2>/dev/null || agents list 2>/dev/null`;
     return `bash -lc ${shellQuote(script)}`;
 }
@@ -207,13 +223,26 @@ export function missingPinnedVersionMessage(hostName, agent, version, installed)
  * the login flow, but it must not route to a device whose every signed-in
  * account is throttled.
  *
- * The sign-in gate reads the per-version `launchable` field — the strict
- * per-version launch truth (`isLaunchableSignedIn`) — so a remote box is judged
- * by the SAME launchability the local candidate uses (`collectRunCandidates` →
- * `isLaunchableSignedIn`), not the display `signedIn` that inherits the
- * active/global HOME login and passes a box that dies at spawn (PHNX-3466). An
- * older remote CLI omits `launchable`, so it falls back to `signedIn` — the
- * pre-fix behavior, so a rolling fleet does not regress.
+ * ONE readiness gate, computed on the box that runs (PHNX-4116). The remote box
+ * publishes `runReady` — the router's own `collectRunCandidates` →
+ * `readinessFromCandidate` verdict over its native slots AND version homes — so
+ * this reads that answer rather than re-deriving freshness here. The
+ * dispatching box re-deriving from the per-version `versions[]` list was the bug:
+ * that list enumerates version homes, misses the account slots a run picks from,
+ * and applied a 40-minute usage-freshness refusal a synced-only worker could
+ * never satisfy, turning a usage-sync lag into "no ready device" while
+ * `--device <name>` on the same box launched fine.
+ *
+ * An older remote CLI omits `runReady`; the one-release fallback derives the
+ * verdict from the per-version list the same way the pre-PHNX-4116 dispatcher
+ * did: the strict `launchable` signal (`isLaunchableSignedIn`, PHNX-3466) for
+ * sign-in, MINUS a FRESH throttle (`rate_limited`/`out_of_credits` captured
+ * within {@link USAGE_STALE_REFUSAL_MAX_AGE_MS}) or a FRESH dead auth verdict
+ * (checked within {@link AUTH_PROBE_MAX_AGE_MS}, {@link isDeadVerdict}). A stale
+ * reading is UNVERIFIED, not disqualifying (PHNX-4116/#3700), so a usage-sync
+ * lag never bars an old-CLI worker `--device <name>` would launch fine — but a
+ * throttled-but-launchable worker no longer reads `signedIn: true` and slips
+ * into `--device auto`'s pick during a rolling upgrade.
  */
 export function viewAgentAccountEligibility(view, agent, now = Date.now()) {
     try {
@@ -221,11 +250,25 @@ export function viewAgentAccountEligibility(view, agent, now = Date.now()) {
         const row = rows.find((candidate) => candidate.agent?.toLowerCase() === agent.toLowerCase());
         if (!row)
             return { signedIn: undefined, pickerEligible: undefined };
+        const runReady = row.runReady;
+        if (runReady && typeof runReady.ready === 'boolean') {
+            // A signed-out / revoked account is picker-eligible even when not ready —
+            // launching it IS the login flow. A throttled account is not.
+            const accounts = runReady.accounts ?? [];
+            const pickerEligible = runReady.ready
+                || accounts.some((a) => a.reason === 'signed_out' || a.reason === 'revoked');
+            return {
+                signedIn: runReady.ready,
+                pickerEligible,
+                reason: runReady.ready ? undefined : runReady.reason,
+            };
+        }
+        // One-release fallback for an older remote CLI without `runReady`.
         const verdicts = (row.versions ?? []).flatMap((version) => {
             if (typeof version.signedIn !== 'boolean')
                 return [];
             // Prefer the strict per-version launch signal; fall back to the display
-            // `signedIn` for an older remote CLI that does not emit `launchable`.
+            // `signedIn` for a CLI old enough to omit `launchable` too.
             const launchable = typeof version.launchable === 'boolean' ? version.launchable : version.signedIn;
             const usageCapturedAt = version.usageCapturedAt ? Date.parse(version.usageCapturedAt) : Number.NaN;
             const usageFresh = Number.isFinite(usageCapturedAt)
@@ -240,9 +283,14 @@ export function viewAgentAccountEligibility(view, agent, now = Date.now()) {
                 && version.authVerdict !== undefined
                 && authFresh
                 && isDeadVerdict(version.authVerdict);
-            const freshnessKnown = version.usageCapturedAt !== undefined || version.authCheckedAt !== undefined;
-            const fresh = !freshnessKnown || (usageFresh && authFresh);
-            const ready = launchable && fresh && !authBlocked && !throttled;
+            // A stale usage/auth reading makes the account UNVERIFIED, not unusable:
+            // the number is ignored (`throttled`/`authBlocked` only trust a fresh one)
+            // and the remote `agents run` weights an unverified account at the floor.
+            // Refusing the whole device on a stale reading turned a fleet-wide
+            // usage-sync lag into "no healthy device can run claude" while
+            // `--device <name>` on the same box launched fine (PHNX-4116/#3700). Only a
+            // FRESH throttle or a FRESH dead auth verdict disqualifies.
+            const ready = launchable && !authBlocked && !throttled;
             return [{ ready, pickerEligible: ready || !launchable || authBlocked }];
         });
         if (verdicts.length === 0)

package/dist/lib/hosts/remote-cmd.js

@@ -109,6 +109,7 @@ export const RUN_OPTION_FORWARDING = {
     disableTmux: 'local-only',
     device: 'local-only',
     where: 'local-only', // expands into host/lease before dispatch; never re-forwarded
+    local: 'local-only', // this machine by definition — a local run never reaches the SSH boundary
     on: 'local-only',
     computer: 'local-only',
     any: 'local-only',

package/dist/lib/installations/active-check.d.ts

@@ -25,6 +25,14 @@ import type { Installation } from './types.js';
  */
 export interface ProcessSnapshot {
     listCommandLines(): Promise<string[]>;
+    /** Optional richer listing (pid, elapsed, tty) for naming a blocking process. */
+    listProcessRows?(): Promise<ProcessRow[]>;
+}
+export interface ProcessRow {
+    pid?: number;
+    elapsed?: string;
+    tty?: string;
+    args: string;
 }
 export declare const realProcessSnapshot: ProcessSnapshot;
 /**
@@ -46,3 +54,22 @@ export declare function installationLooksActive(installation: Pick<Installation,
  * update to a harness this check simply failed to observe.
  */
 export declare function isInstallationLikelyActive(installation: Pick<Installation, 'agent' | 'label'>, snapshot?: ProcessSnapshot): Promise<boolean>;
+export interface InstallationActivity {
+    active: boolean;
+    /** A launch lease is held (a launch is starting and may not be in the process table yet). */
+    lease: boolean;
+    /** Live processes naming this installation's directory, one line each. */
+    processes: string[];
+    /** The process scan failed; `active` is the fail-closed default. */
+    scanError?: string;
+}
+/**
+ * Same verdict as {@link isInstallationLikelyActive}, plus WHAT is holding the
+ * installation, so a refused update can name the session to finish instead of
+ * "in use; retry later" (PHNX-4116 follow-up: an operator on yosemite-s0 had a
+ * one-hour-old resumed session on another tty and no way to see it from the
+ * refusal).
+ */
+export declare function describeInstallationActivity(installation: Pick<Installation, 'agent' | 'label'>, snapshot?: ProcessSnapshot): Promise<InstallationActivity>;
+/** The one-line refusal an update prints for a busy installation. */
+export declare function formatInUseDeferral(name: string, activity: InstallationActivity): string;

package/dist/lib/installations/active-check.js

@@ -22,6 +22,16 @@ import { promisify } from 'util';
 import { getVersionDir } from './store.js';
 import { hasLiveLaunchLease } from './shims.js';
 const execFileAsync = promisify(execFile);
+async function listProcessRowsPosix() {
+    const { stdout } = await execFileAsync('ps', ['-Ao', 'pid=,etime=,tty=,args='], {
+        timeout: 5_000,
+        maxBuffer: 16 * 1024 * 1024,
+    });
+    return stdout.split('\n').flatMap((line) => {
+        const m = /^\s*(\d+)\s+(\S+)\s+(\S+)\s+(.*)$/.exec(line);
+        return m ? [{ pid: Number(m[1]), elapsed: m[2], tty: m[3], args: m[4] }] : [];
+    });
+}
 async function listCommandLinesPosix() {
     try {
         const { stdout } = await execFileAsync('ps', ['-Ao', 'args'], {
@@ -49,6 +59,9 @@ async function listCommandLinesWindows() {
 }
 export const realProcessSnapshot = {
     listCommandLines: () => (process.platform === 'win32' ? listCommandLinesWindows() : listCommandLinesPosix()),
+    listProcessRows: async () => (process.platform === 'win32'
+        ? (await listCommandLinesWindows()).map((args) => ({ args }))
+        : listProcessRowsPosix()),
 };
 /**
  * Does any live process reference this installation's own directory? Matches
@@ -82,3 +95,51 @@ export async function isInstallationLikelyActive(installation, snapshot = realPr
         return true;
     }
 }
+/** `ps` prints `?` (Linux), `??` (macOS) or `-` for a process with no controlling terminal. */
+const NO_TTY_MARKERS = new Set(['?', '??', '-']);
+function shortenArgs(args, versionDir) {
+    // Strip the long install path so the line reads as the command the user ran.
+    const trimmed = args.replace(versionDir, '…').replace(/\/node_modules\/\.bin\//, '/');
+    return trimmed.length > 110 ? `${trimmed.slice(0, 107)}...` : trimmed;
+}
+/**
+ * Same verdict as {@link isInstallationLikelyActive}, plus WHAT is holding the
+ * installation, so a refused update can name the session to finish instead of
+ * "in use; retry later" (PHNX-4116 follow-up: an operator on yosemite-s0 had a
+ * one-hour-old resumed session on another tty and no way to see it from the
+ * refusal).
+ */
+export async function describeInstallationActivity(installation, snapshot = realProcessSnapshot) {
+    const lease = hasLiveLaunchLease(installation.agent, installation.label);
+    const versionDir = getVersionDir(installation.agent, installation.label);
+    try {
+        const rows = snapshot.listProcessRows
+            ? await snapshot.listProcessRows()
+            : (await snapshot.listCommandLines()).map((args) => ({ args }));
+        const processes = rows
+            .filter((row) => row.args.includes(versionDir))
+            .map((row) => {
+            const meta = [row.pid !== undefined ? `pid ${row.pid}` : null, row.elapsed ? `up ${row.elapsed}` : null, row.tty && !NO_TTY_MARKERS.has(row.tty) ? row.tty : null]
+                .filter((part) => part !== null)
+                .join(', ');
+            return meta ? `${meta}: ${shortenArgs(row.args, versionDir)}` : shortenArgs(row.args, versionDir);
+        });
+        return { active: lease || processes.length > 0, lease, processes };
+    }
+    catch (err) {
+        return { active: true, lease, processes: [], scanError: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** The one-line refusal an update prints for a busy installation. */
+export function formatInUseDeferral(name, activity) {
+    if (activity.scanError)
+        return `${name}: could not confirm nothing is running (${activity.scanError}); not updating.`;
+    if (activity.processes.length > 0) {
+        const list = activity.processes.length === 1
+            ? activity.processes[0]
+            : activity.processes.map((p) => `\n    ${p}`).join('');
+        return `${name} is in use by ${activity.processes.length === 1 ? 'a running process' : `${activity.processes.length} running processes`} — ${list}. `
+            + 'Finish that session (agents sessions stop <id> for an agents session), then retry.';
+    }
+    return `${name} has a launch in flight; retry once it has started or exited.`;
+}

package/dist/lib/installations/migrate.js

@@ -17,10 +17,13 @@ import { enabledRoutineNames, replaceEnabledRoutines } from '../routine-activati
 import { evaluateActivationReadiness } from '../routine-readiness.js';
 import { migrateDeviceConfigStores } from '../devices/config-migration.js';
 import { detrackViaGitExclude } from '../project-resources.js';
-// Two constants only, never the read/write API — migrations still operate on raw
-// YAML so they never take the meta lock or prime the meta cache mid-migration.
-import { LEGACY_DEFAULT_BROWSER_PROFILE_NAME } from '../browser/profiles.js';
+// Migrations operate on raw YAML so they never take the meta lock or prime the
+// meta cache mid-migration.
 import { META_HEADER as DEVICE_META_HEADER } from '../state.js';
+/** The pre-device-scope central browser profile name this one-shot migration
+ *  folds into the device doc. Inlined (the in-repo browser engine that defined it
+ *  was removed with PHNX-4101); the legacy on-disk name is unchanged. */
+const LEGACY_DEFAULT_BROWSER_PROFILE_NAME = 'default';
 import { COMPILED_HEADER_PROJECT } from '../rules/compile.js';
 const HOME = process.env.HOME ?? os.homedir();
 const USER_DIR = path.join(HOME, '.agents');

package/dist/lib/installations/shims.js

@@ -2189,15 +2189,17 @@ export function listShimFileNames() {
 }
 /**
  * Legacy command shims that are wrong even when their baked install is alive.
- * `secrets` (PHNX-3989), `sessions` (PHNX-4012) and `computer` (PHNX-4075): the
- * shim `exec`s `agents <name>`, which is a passthrough to the STANDALONE binary —
- * so the shim re-enters itself (the 1.22.85 fork bomb). Pruned unconditionally.
+ * `secrets` (PHNX-3989), `sessions` (PHNX-4012), `computer` (PHNX-4075) and
+ * `browser` (PHNX-4101): the shim `exec`s `agents <name>`, which is a passthrough
+ * to the STANDALONE binary — so the shim re-enters itself (the 1.22.85 fork
+ * bomb) and, sitting first on PATH, shadows the real `@phnx-labs/<name>-cli`
+ * binary a user types directly. Pruned unconditionally.
  *
- * `computer` is the sharpest of the three, because agents-cli USED to publish a
- * `computer` bin of its own: a machine that installed an older CLI has a real
- * shim on PATH under the name the standalone engine now owns.
+ * `computer` and `browser` are the sharpest, because agents-cli USED to publish
+ * (`computer`) or shim (`browser`) a bin of its own: a machine that installed an
+ * older CLI has a real shim on PATH under the name the standalone engine now owns.
  */
-const LEGACY_SHIMS_ALWAYS_PRUNED = new Set(['secrets', 'sessions', 'computer', 'pty']);
+const LEGACY_SHIMS_ALWAYS_PRUNED = new Set(['secrets', 'sessions', 'computer', 'pty', 'browser']);
 /**
  * Prune a stale, orphaned shim: one that is NOT a managed agent shim and NOT a user
  * alias, whose baked `AGENTS_BIN` points at an install that no longer exists. These