@phnx-labs/agents-cli 1.22.45 → 1.22.47

package/dist/lib/identity/client.js

@@ -0,0 +1,106 @@
+/**
+ * The ONE place agents-cli talks to its account backend (Phoenix ID).
+ *
+ * Why a seam at all: the removed Prix-coupled layer (RUSH-2581) had no single
+ * entry point — the backend URL was hardcoded in five files and the session
+ * token was re-read from `~/.rush/user.yaml` by seven separate functions, so
+ * re-pointing identity meant editing a dozen call sites and rewriting error
+ * strings scattered through the tree. This module is the correction: one base
+ * URL, one token reader, one HTTP funnel, one error type. Commands import from
+ * here and nothing else.
+ *
+ * The shape mirrors the seams this repo already proved elsewhere —
+ * `SyncBackend` (`lib/secrets/sync-backend.ts`) and `CloudProvider`
+ * (`lib/cloud/types.ts`) — so a second identity backend, if one is ever
+ * needed, is a swap here rather than a sweep across commands.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getRuntimeStateDir } from '../state.js';
+/**
+ * Where the account backend lives. Config, never a literal at a call site.
+ *
+ * The default is the deployed Phoenix ID Worker. It is a `workers.dev` URL
+ * rather than a vanity hostname because no custom domain is attached yet — and
+ * a default naming an unregistered domain is worse than an ugly one: every
+ * `agents auth login` would fail DNS with nothing to point at.
+ */
+export const PHOENIX_ID_BASE = process.env.PHOENIX_ID_BASE ?? 'https://phoenix-id.muqsitnawaz.workers.dev';
+/** Our own session file. agents-cli never reads another product's credentials. */
+export function sessionFilePath() {
+    return path.join(getRuntimeStateDir(), 'phoenix-session.json');
+}
+export function readSession() {
+    try {
+        const raw = fs.readFileSync(sessionFilePath(), 'utf-8');
+        const parsed = JSON.parse(raw);
+        return parsed.access_token ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSession(session) {
+    const file = sessionFilePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(session, null, 2), { mode: 0o600 });
+}
+export function clearSession() {
+    try {
+        fs.rmSync(sessionFilePath(), { force: true });
+    }
+    catch {
+        // Already gone: logging out twice is not an error.
+    }
+}
+/** An error carrying the server's status and message, so callers can branch on it. */
+export class PhoenixApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'PhoenixApiError';
+    }
+}
+/** The single HTTP funnel. Every request to the account backend goes through here. */
+export async function phoenixRequest(method, route, opts = {}) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (opts.auth !== false) {
+        const token = opts.token ?? readSession()?.access_token;
+        if (!token)
+            throw new PhoenixApiError("Not signed in. Run 'agents auth login'.", 401);
+        headers.Authorization = `Bearer ${token}`;
+    }
+    let response;
+    try {
+        response = await fetch(`${PHOENIX_ID_BASE}${route}`, {
+            method,
+            headers,
+            body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 15_000),
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new PhoenixApiError(`Could not reach the account service (${detail}).`, 0);
+    }
+    if (response.status === 204)
+        return undefined;
+    const text = await response.text();
+    let payload = null;
+    if (text) {
+        try {
+            payload = JSON.parse(text);
+        }
+        catch {
+            payload = null;
+        }
+    }
+    if (!response.ok) {
+        const message = payload && typeof payload === 'object' && 'error' in payload
+            ? String(payload.error)
+            : `${response.status} ${response.statusText}`;
+        throw new PhoenixApiError(message, response.status);
+    }
+    return payload;
+}

package/dist/lib/identity/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Phoenix ID — the typed surface commands use. Every route the account backend
+ * exposes is a function here; no command builds a URL or reads a token itself.
+ */
+import { type PhoenixSession } from './client.js';
+export { PHOENIX_ID_BASE, PhoenixApiError, clearSession, readSession, sessionFilePath, writeSession, type PhoenixSession, } from './client.js';
+export interface DeviceAuthorization {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+}
+export interface WhoAmI {
+    userId: string;
+    email: string;
+    valid: true;
+}
+/**
+ * RFC 8628 poll outcomes. `pending` and `slow_down` are normal states of a
+ * login in progress, not failures — the server signals them through the error
+ * body, and this is where that wire detail stops.
+ */
+export type DevicePoll = {
+    status: 'authorized';
+    access_token: string;
+    user: {
+        email: string;
+        id: string;
+    };
+} | {
+    status: 'pending';
+} | {
+    status: 'slow_down';
+} | {
+    status: 'expired';
+} | {
+    status: 'denied';
+};
+export declare function startDeviceAuthorization(): Promise<DeviceAuthorization>;
+export declare function pollDeviceToken(deviceCode: string): Promise<DevicePoll>;
+export declare function fetchWhoAmI(token?: string): Promise<WhoAmI>;
+export interface SpaceSummary {
+    id: string;
+    slug: string;
+    name: string;
+    organization_id: string | null;
+    owner_user_id: string;
+    invite_code?: string;
+    user_role: 'owner' | 'admin' | 'member';
+    created_at: string;
+}
+export interface SpaceMember {
+    user_id: string;
+    email: string;
+    name?: string;
+    avatar_url?: string;
+    role: 'owner' | 'admin' | 'member';
+    joined_at: string;
+}
+export interface SpaceInvite {
+    id: string;
+    space_id: string;
+    email: string;
+    role: 'admin' | 'member';
+    invite_code: string;
+    created_at: string;
+}
+export type CreateInviteResult = {
+    invited: true;
+    email: string;
+    role: string;
+    member_added: true;
+} | {
+    invited: true;
+    email: string;
+    role: string;
+    invite_code: string;
+    member_added: false;
+};
+export declare const listSpaces: () => Promise<SpaceSummary[]>;
+export declare const createSpace: (input: {
+    name: string;
+    slug: string;
+}) => Promise<SpaceSummary>;
+export declare const getSpace: (id: string) => Promise<SpaceSummary>;
+export declare const listSpaceMembers: (id: string) => Promise<SpaceMember[]>;
+export declare const createSpaceInvite: (id: string, input: {
+    email: string;
+    role: "admin" | "member";
+}) => Promise<CreateInviteResult>;
+export declare const listSpaceInvites: (id: string) => Promise<SpaceInvite[]>;
+export declare const revokeSpaceInvite: (id: string, inviteId: string) => Promise<{
+    revoked: true;
+}>;
+export declare const updateSpaceMemberRole: (id: string, userId: string, role: "admin" | "member") => Promise<{
+    user_id: string;
+    role: string;
+    updated: true;
+}>;
+export declare const removeSpaceMember: (id: string, userId: string) => Promise<void>;
+export declare const deleteSpace: (id: string) => Promise<void>;
+export interface Subscription {
+    tierName?: string;
+    [key: string]: unknown;
+}
+export declare const fetchSubscription: (agent?: string) => Promise<Subscription>;
+/** `Design Team` → `design-team`; the slug a space gets when the user gives only a name. */
+export declare function slugify(name: string): string;
+/** Resolve a space by id, slug, or name from a list the caller already fetched. */
+export declare function resolveSpaceFromList(spaces: SpaceSummary[], ref?: string): SpaceSummary | null;
+/** Resolve a member by email or user id from a list the caller already fetched. */
+export declare function resolveMemberFromList(members: SpaceMember[], ref: string): SpaceMember | null;
+export type { PhoenixSession as Session };

package/dist/lib/identity/index.js

@@ -0,0 +1,82 @@
+/**
+ * Phoenix ID — the typed surface commands use. Every route the account backend
+ * exposes is a function here; no command builds a URL or reads a token itself.
+ */
+import { phoenixRequest, PhoenixApiError } from './client.js';
+export { PHOENIX_ID_BASE, PhoenixApiError, clearSession, readSession, sessionFilePath, writeSession, } from './client.js';
+export function startDeviceAuthorization() {
+    return phoenixRequest('POST', '/api/v1/auth/device/authorization', {
+        auth: false,
+        body: {},
+    });
+}
+export async function pollDeviceToken(deviceCode) {
+    try {
+        return await phoenixRequest('POST', '/api/v1/auth/device/token', {
+            auth: false,
+            body: {
+                grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+                device_code: deviceCode,
+            },
+        });
+    }
+    catch (err) {
+        if (!(err instanceof PhoenixApiError))
+            throw err;
+        // The server encodes poll state in the error body (RFC 8628 §3.5).
+        if (err.message.includes('authorization_pending'))
+            return { status: 'pending' };
+        if (err.message.includes('slow_down'))
+            return { status: 'slow_down' };
+        if (err.message.includes('expired_token'))
+            return { status: 'expired' };
+        if (err.message.includes('access_denied'))
+            return { status: 'denied' };
+        throw err;
+    }
+}
+export function fetchWhoAmI(token) {
+    return phoenixRequest('GET', '/api/v1/auth/me', { token });
+}
+export const listSpaces = () => phoenixRequest('GET', '/api/v1/spaces');
+export const createSpace = (input) => phoenixRequest('POST', '/api/v1/spaces', { body: input });
+export const getSpace = (id) => phoenixRequest('GET', `/api/v1/spaces/${encodeURIComponent(id)}`);
+export const listSpaceMembers = (id) => phoenixRequest('GET', `/api/v1/spaces/${encodeURIComponent(id)}/members`);
+export const createSpaceInvite = (id, input) => phoenixRequest('POST', `/api/v1/spaces/${encodeURIComponent(id)}/invites`, {
+    body: input,
+});
+export const listSpaceInvites = (id) => phoenixRequest('GET', `/api/v1/spaces/${encodeURIComponent(id)}/invites`);
+export const revokeSpaceInvite = (id, inviteId) => phoenixRequest('DELETE', `/api/v1/spaces/${encodeURIComponent(id)}/invites/${encodeURIComponent(inviteId)}`);
+export const updateSpaceMemberRole = (id, userId, role) => phoenixRequest('PATCH', `/api/v1/spaces/${encodeURIComponent(id)}/members/${encodeURIComponent(userId)}`, {
+    body: { role },
+});
+export const removeSpaceMember = (id, userId) => phoenixRequest('DELETE', `/api/v1/spaces/${encodeURIComponent(id)}/members/${encodeURIComponent(userId)}`);
+export const deleteSpace = (id) => phoenixRequest('DELETE', `/api/v1/spaces/${encodeURIComponent(id)}`);
+export const fetchSubscription = (agent = 'agents-cli') => phoenixRequest('GET', `/api/v1/billing/subscription?agent=${encodeURIComponent(agent)}`);
+// ─── Helpers shared by the commands ──────────────────────────────────────────
+/** `Design Team` → `design-team`; the slug a space gets when the user gives only a name. */
+export function slugify(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 63);
+}
+/** Resolve a space by id, slug, or name from a list the caller already fetched. */
+export function resolveSpaceFromList(spaces, ref) {
+    if (!ref)
+        return spaces.length === 1 ? spaces[0] : null;
+    const needle = ref.trim().toLowerCase();
+    return (spaces.find((s) => s.id === ref) ??
+        spaces.find((s) => s.slug.toLowerCase() === needle) ??
+        spaces.find((s) => s.name.toLowerCase() === needle) ??
+        null);
+}
+/** Resolve a member by email or user id from a list the caller already fetched. */
+export function resolveMemberFromList(members, ref) {
+    const needle = ref.trim().toLowerCase();
+    return (members.find((m) => m.user_id === ref) ??
+        members.find((m) => m.email.toLowerCase() === needle) ??
+        null);
+}

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/probe.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Async probe capturing stdout. Rejects on spawn error, non-zero exit, or
+ * timeout — matching the `execFileAsync` contract the version probe had — and
+ * reaps the probe's whole process group on every settle path.
+ */
+export declare function probeCapture(cmd: string, args: string[], timeoutMs: number): Promise<{
+    stdout: string;
+}>;