@phnx-labs/agents-cli 1.22.117 → 1.22.119

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.2' },
 };
 /** 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/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.d.ts

@@ -64,7 +64,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 32;
+export declare const SHIM_SCHEMA_VERSION = 33;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.

package/dist/lib/installations/shims.js

@@ -271,7 +271,7 @@ async function promptConflictStrategy(conflictInfos) {
 // v32 — every config-dir pin (claude, grok, opencode, kimi, muse, copilot) yields to
 //        an account-slot launch (AGENTS_EXEC_HOME from `agents run`), so a slot run
 //        reads and writes its own slot home instead of the shared version home.
-export const SHIM_SCHEMA_VERSION = 32;
+export const SHIM_SCHEMA_VERSION = 33;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -306,7 +306,14 @@ function shellQuote(value) {
  * versions.ts (which reads bare filenames via `fs.readdirSync` and so never
  * had the full-path-match bug).
  */
-const GROK_RESOLVE_BINARY_FN = `_resolve_grok_binary() {
+const GROK_RESOLVE_BINARY_FN = `_resolve_grok_current() {
+  local target
+  target=$(readlink -f "$1/bin/grok" 2>/dev/null) || return 0
+  [ -f "$target" ] && [ -x "$target" ] || return 0
+  [ "$(wc -c < "$target" 2>/dev/null || echo 0)" -ge 1000000 ] || return 0
+  printf '%s\\n' "$target"
+}
+_resolve_grok_binary() {
   local dir="$1" version_hint="$2"
   local candidate base size mtime
   for candidate in "$dir"/grok-*; do
@@ -569,12 +576,20 @@ ${GROK_RESOLVE_BINARY_FN}
   # Check the versioned home first — this is where the binary lands when the
   # installer runs with GROK_HOME set (i.e. via the shim or a correct
   # \`agents add grok\`), or when grok self-updates from within the shim.
+  # \`bin/grok\` is grok's own current-release pointer, kept by its updater in
+  # both layouts (\`bin/grok -> ../downloads/grok-<v>-<arch>\` and the newer
+  # \`bin/grok -> grok-<v>\`); \`grok update\` never touches downloads/ in the
+  # newer one, so scanning downloads/ alone keeps exec'ing a dead release.
+  BINARY=$(_resolve_grok_current "$VERSION_DIR/home/.grok")
   GROK_DOWNLOADS="$VERSION_DIR/home/.grok/downloads"
-  if [ -d "$GROK_DOWNLOADS" ]; then
+  if [ -z "$BINARY" ] && [ -d "$GROK_DOWNLOADS" ]; then
     BINARY=$(_resolve_grok_binary "$GROK_DOWNLOADS" "$VERSION")
   fi
   # Fall back to the global grok home (binary installed without GROK_HOME set,
   # e.g. an earlier \`agents add grok@latest\` before this resolution fix).
+  if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
+    BINARY=$(_resolve_grok_current "$HOME/.grok")
+  fi
   if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
     GROK_DOWNLOADS="$HOME/.grok/downloads"
     if [ -d "$GROK_DOWNLOADS" ]; then
@@ -1300,12 +1315,15 @@ export AGENT_CLI_CREDENTIAL_STORE="file"
         ? `# Grok ships its native binary in the versioned home's .grok/downloads (or,
 # for pre-fix installs, the global ~/.grok/downloads), not node_modules.
 ${GROK_RESOLVE_BINARY_FN}
+BINARY=$(_resolve_grok_current "${versionDir}/home/.grok")
 GROK_DOWNLOADS="${versionDir}/home/.grok/downloads"
-BINARY=""
-if [ -d "$GROK_DOWNLOADS" ]; then
+if [ -z "$BINARY" ] && [ -d "$GROK_DOWNLOADS" ]; then
   BINARY=$(_resolve_grok_binary "$GROK_DOWNLOADS" "${version}")
 fi
 # Fall back to the global grok home (binary installed without GROK_HOME set).
+if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
+  BINARY=$(_resolve_grok_current "$AGENTS_REAL_HOME/.grok")
+fi
 if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
   GROK_GLOBAL_DOWNLOADS="$AGENTS_REAL_HOME/.grok/downloads"
   if [ -d "$GROK_GLOBAL_DOWNLOADS" ]; then
@@ -2189,15 +2207,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

package/dist/lib/installations/store.d.ts

@@ -118,6 +118,15 @@ export declare function getVersionDir(agent: AgentId, version: string): string;
  * Returns null (fail loud, never guess) when nothing survives the size filter.
  */
 export declare function resolveGrokFallbackBinary(downloadsDir: string): string | null;
+/**
+ * Grok's own current-release pointer, `<grokHome>/bin/grok`, resolved to the
+ * real binary, or null when absent or not a real binary. Grok's updater keeps
+ * it current in both of its layouts (`bin/grok -> ../downloads/grok-<v>-<arch>`
+ * and the newer `bin/grok -> grok-<v>`, which never touches downloads/), so it
+ * is the only location that tracks `grok update`. Mirrors the shim's
+ * `_resolve_grok_current`.
+ */
+export declare function resolveGrokCurrentBinary(grokHome: string): string | null;
 /**
  * Get the binary path for a specific agent version.
  */

package/dist/lib/installations/store.js

@@ -339,12 +339,36 @@ export function resolveGrokFallbackBinary(downloadsDir) {
     }
     return best ? path.join(downloadsDir, best.name) : null;
 }
+/**
+ * Grok's own current-release pointer, `<grokHome>/bin/grok`, resolved to the
+ * real binary, or null when absent or not a real binary. Grok's updater keeps
+ * it current in both of its layouts (`bin/grok -> ../downloads/grok-<v>-<arch>`
+ * and the newer `bin/grok -> grok-<v>`, which never touches downloads/), so it
+ * is the only location that tracks `grok update`. Mirrors the shim's
+ * `_resolve_grok_current`.
+ */
+export function resolveGrokCurrentBinary(grokHome) {
+    try {
+        const target = fs.realpathSync(path.join(grokHome, 'bin', 'grok'));
+        const stat = fs.statSync(target);
+        if (!stat.isFile() || stat.size < MIN_GROK_BINARY_BYTES)
+            return null;
+        fs.accessSync(target, fs.constants.X_OK);
+        return target;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Get the binary path for a specific agent version.
  */
 export function getBinaryPath(agent, version) {
     const agentConfig = AGENTS[agent];
     if (agent === 'grok') {
+        const current = resolveGrokCurrentBinary(path.join(getVersionHomePath(agent, version), '.grok'));
+        if (current)
+            return current;
         const grokDownloads = path.join(getVersionHomePath(agent, version), '.grok', 'downloads');
         // The directory token is the stable installation/account label. A
         // self-updating slot may carry a newer vendor release, whose binary keeps

package/dist/lib/installations/update.js

@@ -6,7 +6,7 @@ import { getBinaryPath, invalidateInstalledVersionsCache, invalidateLiveVersionC
 import { assertValidRelease, selectUpdateStrategy, } from './strategies.js';
 import { listInstallations, readInstallation, recordRelease, writeInstallation } from './store.js';
 import { effectiveUpdatePolicy, isAutoUpdateEnabledForAgent } from './update-policy.js';
-import { isInstallationLikelyActive } from './active-check.js';
+import { describeInstallationActivity, formatInUseDeferral } from './active-check.js';
 import { installationLockTarget, INSTALLATION_LOCK_OPTIONS } from './installation-lock.js';
 /**
  * Move one frozen installation to a new vendor release, preserving its identity.
@@ -88,18 +88,21 @@ async function runUpdateInstallation(agent, requestedInstallation, options) {
         return { installation, strategy: strategy.id, fromRelease: installation.releaseVersion, toRelease: target,
             unchanged: true, deferred: 'Update cancelled or automatic update policy changed.', alsoUpdated: [] };
     }
-    if (strategy.transactional && await isInstallationLikelyActive(installation)) {
-        options.onProgress?.(`${AGENTS[agent].name}@${installation.label} looks active right now (a process or launch lease); `
-            + `not staging release ${target}.`);
-        return {
-            installation,
-            strategy: strategy.id,
-            fromRelease: installation.releaseVersion,
-            toRelease: target,
-            unchanged: true,
-            deferred: 'Account home is in use; retry after its sessions finish.',
-            alsoUpdated: [],
-        };
+    if (strategy.transactional) {
+        const activity = await describeInstallationActivity(installation);
+        if (activity.active) {
+            const name = `${AGENTS[agent].name}@${installation.label}`;
+            options.onProgress?.(`${name} looks active right now; not staging release ${target}.`);
+            return {
+                installation,
+                strategy: strategy.id,
+                fromRelease: installation.releaseVersion,
+                toRelease: target,
+                unchanged: true,
+                deferred: formatInUseDeferral(name, activity),
+                alsoUpdated: [],
+            };
+        }
     }
     let staged = null;
     try {
@@ -179,7 +182,8 @@ async function runUpdateInstallation(agent, requestedInstallation, options) {
         // identical pre-stage check above for why this cannot be opt-in: a launch
         // that starts AFTER that first check but before this swap is exactly the
         // window this closes.
-        if (options.shouldCancel?.() || (strategy.transactional && await isInstallationLikelyActive(installation))) {
+        const lateActivity = strategy.transactional ? await describeInstallationActivity(installation) : null;
+        if (options.shouldCancel?.() || lateActivity?.active) {
             options.onProgress?.(`${AGENTS[agent].name}@${installation.label} looks active now (a process or launch lease appeared while `
                 + `${staged.release} was staging); not committing it.`);
             return {
@@ -188,7 +192,9 @@ async function runUpdateInstallation(agent, requestedInstallation, options) {
                 fromRelease: installation.releaseVersion,
                 toRelease: staged.release,
                 unchanged: true,
-                deferred: 'Update cancelled or the account home became active.',
+                deferred: lateActivity?.active
+                    ? formatInUseDeferral(`${AGENTS[agent].name}@${installation.label}`, lateActivity)
+                    : 'Update cancelled while the release was being prepared.',
                 alsoUpdated: [],
             };
         }