@phnx-labs/agents-cli 1.22.46 → 1.22.47

package/dist/lib/fleet/remote-login.js

@@ -33,7 +33,7 @@ import { planFleetTargets } from '../devices/fleet.js';
 import { assertValidSshTarget, shellQuote, sshExecAsync } from '../ssh-exec.js';
 import { machineId } from '../session/sync/config.js';
 import { ptyRequest } from '../pty-client.js';
-import { openUrl } from '../open-url.js';
+import { showUrl } from '../open-url.js';
 import { readAuthHealthCache, } from '../auth-health.js';
 import { FLEET_LOGIN_FLOWS, KEYCHAIN_BOUND_ON_MAC, } from './auth-sync.js';
 /**
@@ -500,8 +500,13 @@ export async function runFleetLogin(opts = {}) {
     if (!opts.json) {
         console.log(`Dashboard: ${dashUrl}`);
     }
-    if (opts.open !== false)
-        openUrl(dashUrl);
+    if (opts.open !== false) {
+        const shown = await showUrl(dashUrl);
+        if (shown.via === 'none') {
+            console.error('Could not open a browser — open this yourself:');
+            console.error(`  ${dashUrl}`);
+        }
+    }
     const driver = opts.driver ?? defaultPtyDriver();
     const remotable = pending.filter((p) => p.remotable);
     const driveOne = async (p) => {

package/dist/lib/fleet/types.d.ts

@@ -80,6 +80,23 @@ export interface FleetManifest {
      * machine's local device registry and is never committed.
      */
     discovery?: Record<string, 'approved' | 'ignored'>;
+    /**
+     * Tailnet node names the user dismissed from auto-discovery, with who
+     * dismissed each and when. Lives here rather than in a per-device doc because
+     * a dismissed node is deliberately NOT a device — it never enters the
+     * registry, so it has no per-device folder. Syncs fleet-wide with the rest of
+     * `agents.yaml`, so a dismissal on one box stops the suggestion on every box.
+     */
+    ignored?: IgnoredDeviceEntry[];
+}
+/** One dismissal record in {@link FleetManifest.ignored}. */
+export interface IgnoredDeviceEntry {
+    /** Tailscale node name the user dismissed. */
+    name: string;
+    /** ISO-8601 timestamp of the dismissal. */
+    ignoredAt: string;
+    /** machineId() of the box the dismissal was made on. */
+    ignoredOn: string;
 }
 /**
  * A device's desired state after merging defaults with its override and

package/dist/lib/harness/adapter.d.ts

@@ -28,6 +28,7 @@
  */
 import type { AgentId, Mode } from '../types.js';
 import type { JobConfig } from '../scheduling/routines.js';
+import type { ConfiguredDeviceRole } from '../device-config.js';
 /**
  * Context for the exec-time config-env pin (mapping A, exec.ts side). The caller
  * resolves the interactive/version facts once; the adapter only expresses the
@@ -42,6 +43,16 @@ export interface ExecConfigEnvCtx {
     versionHome: string | null;
     /** resolveInteractive(options) — computed once by the caller. */
     interactive: boolean;
+    /**
+     * The role marked on THIS machine (worker | personal | undefined), resolved
+     * once by the caller from selfConfiguredDeviceRole(). A `personal` device is
+     * the user's own interactive box: it holds a real per-version login and the
+     * credential decision MUST defer to it for EVERY run — interactive OR headless
+     * — never the worker-only setup-token (RUSH-2395). Injected as a plain value
+     * (not imported) to keep the adapter import-leaf. Absent/undefined is treated
+     * as non-personal (worker-equivalent).
+     */
+    deviceRole?: ConfiguredDeviceRole;
     /**
      * claude-account-token's resolveClaudeSetupToken, injected. The adapters MUST
      * stay import-leaf: claude-account-token pulls in the secrets stack, which

package/dist/lib/harness/adapters/claude.js

@@ -26,35 +26,49 @@ export const claudeAdapter = {
         }
         // The `auth` bundle's setup-token exists so a run with NO human present
         // authenticates without the Touch-ID-gated login item — usage probes,
-        // routines, dispatched runs (claude-account-token.ts). An interactive run
-        // has a human at the TTY, and their own per-version login is the credential
-        // they established and expect; overriding it made `/status` report
-        // `Auth token: CLAUDE_CODE_OAUTH_TOKEN` on a personal machine and took every
-        // hand-driven session off that login. macOS cannot cheaply confirm a home's
-        // login first (probing the Keychain raises an authorization sheet per
-        // installed version on the `agents run` hot path — agents.ts
-        // `isClaudeCredentialFileBlank`), so interactive simply defers to Claude
-        // Code, which prompts a present human to log in if the login is missing.
-        if (ctx.interactive) {
-            // Drop an INHERITED copy of OUR OWN setup-token: an interactive launch from
-            // inside a headless agent's shell inherits that agent's injected value via
-            // sanitizeProcessEnv(process.env) and would keep authenticating as it.
-            // Matched by VALUE, so a token the user exported deliberately is a different
-            // string and is left alone (#2383). This is NARROWER than the non-interactive
-            // path below, which overwrites-or-deletes unconditionally and never inspects
-            // the inherited value — a DIFFERENT account's inherited setup-token passing
-            // through this equality check is the adjacent hole RUSH-2360 leaves as
-            // follow-up (it does not silently run on a *shared, rotating* token, which is
-            // what caused the RUSH-1822 logout storm).
+        // routines, dispatched runs (claude-account-token.ts). It is a WORKER
+        // credential. Two kinds of run defer to the per-version login instead:
+        //
+        //   1. An interactive run: a human is at the TTY, and their per-version login
+        //      is the credential they established and expect. Overriding it made
+        //      `/status` report `Auth token: CLAUDE_CODE_OAUTH_TOKEN` on a personal
+        //      machine and took every hand-driven session off that login.
+        //   2. ANY run on a `personal` device — the user's own interactive box (zion),
+        //      marked `config.role: personal`. That box holds a real per-version login
+        //      and is the single origin of it, so every run there — interactive TUI OR
+        //      a headless one-shot like `agents run claude "fix the bug"` — MUST use
+        //      that login, not the setup-token. Gating on run mode ALONE
+        //      (resolveInteractive = "this opens a TUI", NOT "a human is present")
+        //      sent a headless run on the laptop onto the setup-token and hijacked the
+        //      login. Keying the credential on DEVICE ROLE is the fix — RUSH-2395.
+        //
+        // macOS cannot cheaply confirm a home's login first (probing the Keychain
+        // raises an authorization sheet per installed version on the `agents run` hot
+        // path — agents.ts `isClaudeCredentialFileBlank`), so this path defers to
+        // Claude Code, which reads its own ACL-trusted login item without a prompt and
+        // asks a present human to log in only if the login is missing.
+        const personalDevice = ctx.deviceRole === 'personal';
+        if (ctx.interactive || personalDevice) {
+            // Drop an INHERITED copy of OUR OWN setup-token: a launch from inside a
+            // headless agent's shell inherits that agent's injected value via
+            // sanitizeProcessEnv(process.env) and would keep authenticating as it,
+            // overriding the login this branch is protecting. Matched by VALUE, so a
+            // token the user exported deliberately is a different string and is left
+            // alone (#2383). This is NARROWER than the worker path below, which
+            // overwrites-or-deletes unconditionally and never inspects the inherited
+            // value — a DIFFERENT account's inherited setup-token passing through this
+            // equality check is the adjacent hole RUSH-2360 leaves as follow-up (it does
+            // not silently run on a *shared, rotating* token, which is what caused the
+            // RUSH-1822 logout storm).
             if (setupToken && result.CLAUDE_CODE_OAUTH_TOKEN === setupToken) {
                 delete result.CLAUDE_CODE_OAUTH_TOKEN;
             }
         }
         else {
-            // Non-interactive (routines, dispatched, provisioned box): mirror the routines
-            // path (`runner.ts:1017-1021`) UNCONDITIONALLY. Inject the per-account
-            // setup-token when one resolves — it replaces any ambient shared value
-            // inherited from the launcher. When NONE resolves, STRIP the ambient
+            // Headless run on a NON-personal device (worker, dispatched, provisioned
+            // box): mirror the routines path (`runner.ts`) UNCONDITIONALLY. Inject the
+            // per-account setup-token when one resolves — it replaces any ambient shared
+            // value inherited from the launcher. When NONE resolves, STRIP the ambient
             // CLAUDE_CODE_OAUTH_TOKEN so a run on a provisioned box can never silently
             // authenticate as the shared, rotating token an earlier version of this path
             // let through — the RUSH-1822 fleet-wide-logout hazard, tracked by RUSH-2360.

package/dist/lib/harness/adapters/codex.js

@@ -63,21 +63,19 @@ fi
 exec "$BINARY"${launchArgs} "$@"`;
     },
     execModeArgs(ctx) {
-        const policyMode = ctx.resolvedMode === 'plan' || ctx.resolvedMode === 'skip' ? ctx.resolvedMode : 'edit';
         const writableRoots = [
             ...codexEditWritableRoots(ctx.cwd),
             ...ctx.addDirs,
         ];
-        return codexPolicyArgs(policyMode, writableRoots);
+        return codexPolicyArgs(ctx.resolvedMode, writableRoots);
     },
     routineModeArgs(cmd, ctx) {
-        const policyMode = ctx.mode === 'plan' || ctx.mode === 'skip' ? ctx.mode : 'edit';
         const routineRoots = (ctx.config.allow?.dirs ?? []).map((dir) => {
             if (dir.startsWith('-')) {
                 throw new Error(`allow.dirs entries must not start with '-': ${JSON.stringify(dir)}`);
             }
             return dir.replace(/^~/, os.homedir());
         });
-        cmd.push(...codexPolicyArgs(policyMode, [...codexEditWritableRoots(), ...routineRoots]));
+        cmd.push(...codexPolicyArgs(ctx.mode, [...codexEditWritableRoots(), ...routineRoots]));
     },
 };

package/dist/lib/hooks/cache.js

@@ -275,6 +275,14 @@ def should_fire():
             if not tn or tn not in allowed:
                 return False
 
+    v = m.get("permission_mode")
+    if v is not None:
+        allowed = arr(v)
+        if allowed:
+            pm = inp.get("permission_mode") or inp.get("permissionMode")
+            if pm and pm not in allowed:
+                return False
+
     v = m.get("tool_args_match")
     if v is not None:
         ta = inp.get("tool_args")

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

@@ -20,6 +20,9 @@ export interface HookInput {
     tool_name?: string;
     tool_args?: unknown;
     cwd?: string;
+    permission_mode?: string;
+    /** Grok-style camelCase spelling of permission_mode. */
+    permissionMode?: string;
 }
 export declare function isSafeHookRegex(source: string): boolean;
 /**

package/dist/lib/hooks/match.js

@@ -131,6 +131,31 @@ export function shouldFire(matches, input) {
                 return false;
         }
     }
+    if (matches.permission_mode !== undefined) {
+        const allowed = arrayOf(matches.permission_mode);
+        if (allowed.length > 0) {
+            // Fail-open on absence: only some harnesses (Claude Code) report the
+            // live mode. An input with no mode field passes; an explicit value not
+            // in the allowed list skips.
+            const mode = input.permission_mode || input.permissionMode;
+            if (mode && !allowed.includes(mode))
+                return false;
+        }
+    }
+    if (matches.permission_mode_not !== undefined) {
+        const denied = arrayOf(matches.permission_mode_not);
+        if (denied.length > 0) {
+            // The negative form exists because the positive one cannot express
+            // "everywhere except plan" without enumerating every other mode — and an
+            // enumeration silently stops firing the moment a harness adds or renames
+            // one, which for a guard means it quietly stops guarding. Naming the mode
+            // to skip keeps every unknown mode firing, so the failure direction is
+            // "ran unnecessarily", never "did not run".
+            const mode = input.permission_mode || input.permissionMode;
+            if (mode && denied.includes(mode))
+                return false;
+        }
+    }
     if (matches.tool_args_match !== undefined) {
         const serialized = typeof input.tool_args === 'string'
             ? input.tool_args

package/dist/lib/hosts/passthrough.js

@@ -28,6 +28,7 @@ import { resolveRemoteOsSync } from './remote-os.js';
 // 6–7× cheaper graph (RUSH-2374 proposal 2).
 import { machineId } from '../machine-id.js';
 import { isDeviceAuto, resolveDeviceAffinity } from '../smart-launch.js';
+import { isDeviceInteractive, resolveInteractiveDevice, interactiveUnsetError, } from '../devices/interactive-host.js';
 import { flagValue, hasHostRoutingFlag } from './routing-flag.js';
 import { loadDevices } from '../devices/registry.js';
 import { isSelfHost } from '../devices/self-host.js';
@@ -527,6 +528,21 @@ export async function maybeRunOnHost(command, allArgs, opts) {
         process.stderr.write(chalk.gray(`[agents] device=auto → ${plan.host}\n`));
         hostName = plan.host;
     }
+    // `interactive` is the second affinity sentinel: the box the human sits at
+    // (`interactive.host`). Resolved here, ahead of the isSelfHost check below, for
+    // the same reason `auto` is — a pin naming THIS machine must run locally rather
+    // than self-SSH. It never falls back to the local box when unset: rendering to
+    // a screen nobody is watching is the exact failure the sentinel prevents.
+    if (isDeviceInteractive(hostName)) {
+        const pinned = resolveInteractiveDevice();
+        if (!pinned) {
+            process.stderr.write(`${interactiveUnsetError()}\n`);
+            process.exitCode = 1;
+            return true;
+        }
+        process.stderr.write(chalk.gray(`[agents] device=interactive → ${pinned}\n`));
+        hostName = pinned;
+    }
     // Running against your own machine is just a local run — skip the SSH round-trip.
     // Match EVERY identity the box answers to (short id, loopback, tailscale
     // dnsName), not just machineId() — a `--device <self-dnsName>` used to slip past a

package/dist/lib/hosts/registry.js

@@ -27,6 +27,7 @@ import { resolveRemoteOsSync } from './remote-os.js';
 import { loadDevices } from '../devices/registry.js';
 import { resolveDeviceProfile } from '../devices/resolve-profile.js';
 import { isDeviceAuto, resolveDeviceAffinity } from '../smart-launch.js';
+import { isDeviceInteractive, resolveInteractiveDevice, interactiveUnsetError, } from '../devices/interactive-host.js';
 import { localMachineId } from '../session/origin-machine.js';
 // Re-export so existing importers (tests, commands) keep their path; the class
 // itself lives in types.ts so providers can throw it without a circular import.
@@ -161,6 +162,12 @@ export async function matchHost(name, opts = {}) {
     // returning nothing — callers that already special-case "target is this
     // machine" (teams add/create, the passthrough self-host check) then treat it as
     // local exactly as they would if the user had typed the local name.
+    if (isDeviceInteractive(name)) {
+        const pinned = resolveInteractiveDevice();
+        if (!pinned)
+            throw new Error(interactiveUnsetError());
+        name = pinned;
+    }
     if (isDeviceAuto(name)) {
         const plan = (opts.resolveAuto ?? (() => resolveDeviceAffinity({})))();
         const picked = plan.host ?? normalizeHost(localMachineId());

package/dist/lib/menubar/install-menubar.d.ts

@@ -370,6 +370,19 @@ export interface PidStaleness {
  * PREVIOUS binary — the exact condition `restartMenubarHelperAfterSwap` exists
  * to fix. Millisecond epoch timestamps in, so the truth table is unit-testable
  * without a live process or filesystem.
+ *
+ * The two timestamps do not have the same resolution. `pidStartTimeMs` parses
+ * `ps -o lstart`, which prints whole SECONDS, while the bundle mtime carries
+ * sub-second precision — and the restart this check exists to detect happens
+ * within a second of the swap that triggered it. A raw `<` therefore called a
+ * healthy just-restarted helper stale on essentially every upgrade: measured on
+ * zion at 1.22.46, pid start 1787441353000 vs bundle mtime 1787441353700, 700ms
+ * apart inside one second, reported as "running the OLD binary" and surfaced as
+ * `accessibilityHintNeeded` — telling the user to re-grant Accessibility after
+ * an upgrade that had already restarted the helper correctly. So the bundle
+ * mtime is truncated to the same whole second `ps` reports before comparing: a
+ * pid that started in the swap's own second is fresh, and a genuinely stale pid
+ * (a full second or more older) is still caught.
  */
 export declare function isMenubarProcessStaleAgainstBundle(pidStartedAtMs: number, bundleMtimeMs: number): boolean;
 /**

package/dist/lib/menubar/install-menubar.js

@@ -602,8 +602,19 @@ export function mayInstallMenubarHelper(opts) {
     // No owner recorded yet (fresh or pre-`AGENTS_ENTRY` plist) — adopt it.
     if (!opts.plistEntry)
         return true;
+    // The recorded owner's entry path is gone from disk, so this install may adopt
+    // the helper — but a non-Developer-ID (ad-hoc/dev) source may NOT seize a
+    // healthy install this way. Recopying an ad-hoc bundle over the Developer-ID
+    // one poisons the shared Accessibility grant (an ad-hoc signature fails the
+    // grant's stored code requirement, so macOS revokes it and re-prompts on the
+    // next paste) and Gatekeeper then rejects the result as "damaged" (RUSH-2134).
+    // This does not strand a genuinely broken helper: escape (1) above
+    // (helperExecMissing / needsDevIdHeal) already lets ANY source repair a
+    // missing-or-ad-hoc install, so refusing here only declines to re-point the
+    // plist of a helper that is already present and working — the menu bar keeps
+    // running, nothing deadlocks.
     if (!opts.ownerEntryExists)
-        return true; // the recorded owner is gone
+        return opts.sourceIsDeveloperId;
     if (opts.installedVersion && opts.currentVersion) {
         const versionOrder = compareVersions(opts.currentVersion, opts.installedVersion);
         if (versionOrder > 0)
@@ -990,9 +1001,22 @@ export function getMenubarStatus() {
  * PREVIOUS binary — the exact condition `restartMenubarHelperAfterSwap` exists
  * to fix. Millisecond epoch timestamps in, so the truth table is unit-testable
  * without a live process or filesystem.
+ *
+ * The two timestamps do not have the same resolution. `pidStartTimeMs` parses
+ * `ps -o lstart`, which prints whole SECONDS, while the bundle mtime carries
+ * sub-second precision — and the restart this check exists to detect happens
+ * within a second of the swap that triggered it. A raw `<` therefore called a
+ * healthy just-restarted helper stale on essentially every upgrade: measured on
+ * zion at 1.22.46, pid start 1787441353000 vs bundle mtime 1787441353700, 700ms
+ * apart inside one second, reported as "running the OLD binary" and surfaced as
+ * `accessibilityHintNeeded` — telling the user to re-grant Accessibility after
+ * an upgrade that had already restarted the helper correctly. So the bundle
+ * mtime is truncated to the same whole second `ps` reports before comparing: a
+ * pid that started in the swap's own second is fresh, and a genuinely stale pid
+ * (a full second or more older) is still caught.
  */
 export function isMenubarProcessStaleAgainstBundle(pidStartedAtMs, bundleMtimeMs) {
-    return pidStartedAtMs < bundleMtimeMs;
+    return pidStartedAtMs < Math.floor(bundleMtimeMs / 1000) * 1000;
 }
 /** Wall-clock start time of a live pid via `ps`, or null if it can't be read. */
 function pidStartTimeMs(pid) {

package/dist/lib/open-url.d.ts

@@ -1,2 +1,60 @@
-/** Best-effort: open a URL in the user's default browser. Never throws. */
-export declare function openUrl(url: string): void;
+/** Where a "show the human this" call actually landed. */
+export type ShowOutcome = {
+    via: 'profile';
+    profile: string;
+    tabId?: string;
+} | {
+    via: 'os';
+    command: string;
+} | {
+    via: 'none';
+    reason: string;
+};
+export interface ShowOptions {
+    /**
+     * Force the OS default handler, ignoring `browser.viewer`. This is the
+     * The programmatic escape hatch, for a caller that must use the user's own
+     * browser regardless of configuration. There is deliberately no CLI flag for
+     * it: `agents config set browser.viewer os` is the user-facing control.
+     */
+    osBrowser?: boolean;
+    /** Explicit profile override, ahead of `browser.viewer`. */
+    profile?: string;
+    /** Injected opener so the OS branch is testable without spawning anything. */
+    spawnOpen?: (cmd: string, args: string[]) => boolean;
+}
+/**
+ * Launch a detached opener and report whether it actually started.
+ *
+ * Detection without blocking, which is the whole trick here. A bare detached
+ * `spawn` cannot tell success from "xdg-open is not installed" — it does not
+ * throw for a missing binary, it emits `error` asynchronously — so the failure
+ * branches of every caller were dead. But `spawnSync` is not the answer either:
+ * it waits for the child's whole lifetime, and `devices lease` opens a console
+ * and then immediately prompts for a pasted key, so a blocking open would stall
+ * that prompt behind the browser.
+ *
+ * Racing `spawn` against `error` gives both: Node emits `spawn` as soon as the
+ * child is successfully created (measured: 1ms, and it does NOT wait for exit),
+ * and `error` for ENOENT. We unref on success so the opener outlives us.
+ */
+export declare function trySpawn(cmd: string, args: string[]): Promise<boolean>;
+/**
+ * Decide the viewer for this call. Exported for its own test — this is the one
+ * place the policy lives.
+ *
+ * Every fall back to the OS handler prints one stderr line naming why. A silent
+ * downgrade here is what made the original bug invisible for so long: the user
+ * had configured a profile and had no way to see that it was being ignored.
+ */
+export declare function resolveViewer(opts?: ShowOptions): Promise<'os' | {
+    profile: string;
+}>;
+/** Show a URL to the human at this machine. Never throws. */
+export declare function showUrl(url: string, opts?: ShowOptions): Promise<ShowOutcome>;
+/**
+ * Show a local file. Browser-renderable kinds go through {@link showUrl}; every
+ * other kind goes to the OS default APP, which for a screenshot or a recording
+ * is the right viewer.
+ */
+export declare function showFile(filePath: string, opts?: ShowOptions): Promise<ShowOutcome>;

package/dist/lib/open-url.js

@@ -1,19 +1,174 @@
 /**
- * Open a URL in the user's default browser, cross-platform. Best-effort and
- * detached — never throws and never blocks the caller. Shared by `agents devices lease`
- * (Hetzner console) and `agents fleet login` (the local login dashboard).
+ * The one place that decides WHERE a URL or file is shown to the human.
+ *
+ * Two browsers exist on a machine like this: the OS default handler, and the
+ * profile `agents browser` drives. They are not interchangeable. The configured
+ * profile is where the fleet's logins accumulate — `agents browser profiles
+ * logins` lists them — so a page opened there is a page the user is already
+ * signed in for, and a login acquired there is inherited by every later agent.
+ * The OS handler has none of that.
+ *
+ * Before this seam existed, `agents browser navigate` honoured the configured
+ * profile and nothing else did: `fleet login`, `devices lease`, `feedback`, and
+ * the browser-session artifact opener each shelled straight to `open`/`xdg-open`,
+ * so every one of them landed in whatever the OS handler happened to be. This
+ * module replaces all of those call sites; do not add a sixth raw `open`.
+ *
+ * Never throws. A viewer that cannot be reached degrades to the OS handler with
+ * one stderr line naming the reason, and a total failure returns `via: 'none'`
+ * so the caller can print the URL rather than silently doing nothing.
  */
 import { spawn } from 'child_process';
-/** Best-effort: open a URL in the user's default browser. Never throws. */
-export function openUrl(url) {
-    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
-    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+import * as path from 'path';
+import { pathToFileURL } from 'url';
+/**
+ * Extensions a CDP tab renders at least as well as the OS default app.
+ *
+ * Deliberately narrow. `sessions-list.ts` EXT_KIND covers .png/.jpg/.webp/.pdf/
+ * .webm, and for those Preview and QuickTime are the better viewer — routing a
+ * screenshot into a browser tab is a downgrade, not a fix.
+ */
+const BROWSER_RENDERABLE = new Set(['.html', '.htm', '.svg', '.xhtml']);
+async function osOpen(target, spawnOpen) {
+    const candidates = process.platform === 'darwin'
+        ? [['open', [target]]]
+        : process.platform === 'win32'
+            ? // `start` treats a lone quoted first argument as the window TITLE, so the
+                // empty title placeholder is required before the target. The three copies
+                // of this that predated the seam disagreed on it ('' vs '""').
+                [['cmd', ['/c', 'start', '', target]]]
+            : [
+                ['xdg-open', [target]],
+                ['gnome-open', [target]],
+            ];
+    for (const [cmd, args] of candidates) {
+        if (spawnOpen) {
+            if (spawnOpen(cmd, args))
+                return { via: 'os', command: cmd };
+            continue;
+        }
+        if (await trySpawn(cmd, args))
+            return { via: 'os', command: cmd };
+    }
+    return { via: 'none', reason: 'no working OS opener on this platform' };
+}
+/**
+ * Launch a detached opener and report whether it actually started.
+ *
+ * Detection without blocking, which is the whole trick here. A bare detached
+ * `spawn` cannot tell success from "xdg-open is not installed" — it does not
+ * throw for a missing binary, it emits `error` asynchronously — so the failure
+ * branches of every caller were dead. But `spawnSync` is not the answer either:
+ * it waits for the child's whole lifetime, and `devices lease` opens a console
+ * and then immediately prompts for a pasted key, so a blocking open would stall
+ * that prompt behind the browser.
+ *
+ * Racing `spawn` against `error` gives both: Node emits `spawn` as soon as the
+ * child is successfully created (measured: 1ms, and it does NOT wait for exit),
+ * and `error` for ENOENT. We unref on success so the opener outlives us.
+ */
+export function trySpawn(cmd, args) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(ok);
+        };
+        try {
+            const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+            child.on('error', () => done(false));
+            child.on('spawn', () => {
+                child.unref();
+                done(true);
+            });
+        }
+        catch {
+            done(false);
+        }
+    });
+}
+/**
+ * Decide the viewer for this call. Exported for its own test — this is the one
+ * place the policy lives.
+ *
+ * Every fall back to the OS handler prints one stderr line naming why. A silent
+ * downgrade here is what made the original bug invisible for so long: the user
+ * had configured a profile and had no way to see that it was being ignored.
+ */
+export async function resolveViewer(opts = {}) {
+    if (opts.osBrowser)
+        return 'os';
+    const { getConfigValue } = await import('./device-config.js');
+    const configured = opts.profile ?? (getConfigValue('browser.viewer').value || undefined);
+    // Unset means "follow the profile agents drive" — the whole point is that a
+    // machine with a configured browser stops leaking pages to the OS handler.
+    const { getConfiguredDefaultProfileName, resolveProfileRef, getProfile, isProfileLaunchableHere } = await import('./browser/profiles.js');
+    const name = configured ?? getConfiguredDefaultProfileName();
+    if (!name)
+        return 'os';
+    if (name === 'os')
+        return 'os';
+    let resolved;
     try {
-        const p = spawn(cmd, args, { stdio: 'ignore', detached: true });
-        p.on('error', () => { });
-        p.unref();
+        resolved = await resolveProfileRef(name);
+    }
+    catch (err) {
+        console.error(`[viewer] ${name}: ${err instanceof Error ? err.message : String(err)} — using the OS browser.`);
+        return 'os';
+    }
+    if (!resolved) {
+        console.error(`[viewer] "${name}" does not resolve to a profile — using the OS browser.`);
+        return 'os';
     }
-    catch {
-        /* best-effort */
+    const profile = await getProfile(resolved);
+    if (!profile) {
+        console.error(`[viewer] profile "${resolved}" is not configured — using the OS browser.`);
+        return 'os';
+    }
+    if (profile.browser === 'arc') {
+        // Arc exposes no CDP page targets and crashes on tab creation, so it can be
+        // a configured profile but never a drivable viewer.
+        console.error(`[viewer] "${resolved}" is Arc, which cannot be driven — using the OS browser.`);
+        return 'os';
+    }
+    if (!isProfileLaunchableHere(profile)) {
+        console.error(`[viewer] "${resolved}" cannot launch on this machine — using the OS browser.`);
+        return 'os';
+    }
+    return { profile: resolved };
+}
+/** Show a URL to the human at this machine. Never throws. */
+export async function showUrl(url, opts = {}) {
+    const viewer = await resolveViewer(opts);
+    if (viewer === 'os')
+        return osOpen(url, opts.spawnOpen);
+    try {
+        const { sendIPCRequest } = await import('./browser/ipc.js');
+        // Deliberately does NOT auto-start the browser daemon. Showing a page is a
+        // side errand — `devices lease` opens a console and immediately prompts for
+        // a pasted key — so blocking that on a daemon cold start is a surprising
+        // multi-second stall. Daemon already up: use the viewer. Not up: the OS
+        // handler is the fast, correct answer.
+        const response = await sendIPCRequest({ action: 'show', url, profile: viewer.profile }, { autoStartDaemon: false });
+        if (response.ok)
+            return { via: 'profile', profile: viewer.profile, tabId: response.tabId };
+        console.error(`[viewer] ${viewer.profile}: ${response.error} — using the OS browser.`);
+    }
+    catch (err) {
+        console.error(`[viewer] ${viewer.profile}: ${err instanceof Error ? err.message : String(err)} — using the OS browser.`);
+    }
+    return osOpen(url, opts.spawnOpen);
+}
+/**
+ * Show a local file. Browser-renderable kinds go through {@link showUrl}; every
+ * other kind goes to the OS default APP, which for a screenshot or a recording
+ * is the right viewer.
+ */
+export async function showFile(filePath, opts = {}) {
+    if (!BROWSER_RENDERABLE.has(path.extname(filePath).toLowerCase())) {
+        return osOpen(filePath, opts.spawnOpen);
     }
+    return showUrl(pathToFileURL(filePath).href, opts);
 }

package/dist/lib/refresh-coordinator.d.ts

@@ -15,7 +15,7 @@ export interface RefreshLeaseOptions<T> {
  * Serialize refresh work across every agents-cli process on this device.
  *
  * In-process promise maps only protect one Node process. Factory, the daemon,
- * `agents view`, and `agents usage` are separate processes, so they need an
+ * and `agents view` are separate processes, so they need an
  * OS-visible lease. The result is re-read after lock acquisition: a waiter
  * consumes the winner's publication and never calls the provider a second
  * time. `proper-lockfile` supplies heartbeat + stale-owner recovery while an

package/dist/lib/refresh-coordinator.js

@@ -18,7 +18,7 @@ function lockTarget(scope, key) {
  * Serialize refresh work across every agents-cli process on this device.
  *
  * In-process promise maps only protect one Node process. Factory, the daemon,
- * `agents view`, and `agents usage` are separate processes, so they need an
+ * and `agents view` are separate processes, so they need an
  * OS-visible lease. The result is re-read after lock acquisition: a waiter
  * consumes the winner's publication and never calls the provider a second
  * time. `proper-lockfile` supplies heartbeat + stale-owner recovery while an