@phnx-labs/agents-cli 1.22.113 → 1.22.115

package/dist/commands/browser.d.ts

@@ -1,7 +1,60 @@
 import { Command } from 'commander';
 import { type BrowserProfile } from '../lib/browser/profiles.js';
 import { listInstalledBrowsers } from '../lib/browser/chrome.js';
+import type { DeviceProfile } from '../lib/devices/registry.js';
 export declare function remoteStartTaskName(stdout: string, explicit?: string): string | undefined;
+/**
+ * Fetch an absolute remote file into a private local path, bounded.
+ *
+ * Bounded for real, not by a pre-flight `stat`: the byte budget is enforced on the
+ * stream as it arrives (`sshExecRawStream` + `cat`), so a file that grows between
+ * a size check and the copy — or a peer that lies about the size — still cannot
+ * spend more than the budget. `scp` could not do this; it would transfer
+ * everything before this process got a chance to refuse.
+ *
+ * The local file is written 0600 inside a 0700 directory, because a capture can
+ * show anything that was on the peer's screen and a world-readable temp path
+ * would publish it to every local user.
+ */
+/**
+ * The command that streams one file's RAW BYTES to stdout on the device's shell.
+ *
+ * Platform-correct, not one command with a portable-looking name. On Windows
+ * `cat` is an alias for `Get-Content`, which is a TEXT reader: it decodes the
+ * file, splits it into lines, and re-encodes on output — so a screenshot arrives
+ * corrupted rather than merely reordered. The .NET path opens a `FileStream` and
+ * copies it into the raw stdout handle, bypassing PowerShell's object/text
+ * pipeline entirely, which is the only way binary survives.
+ */
+export declare function remoteReadFileArgv(remotePath: string, shell: DeviceProfile['shell']): string[];
+/**
+ * Largest capture `browser show --device` will pull. A capture is a screenshot,
+ * a PDF or a short recording; anything past this is not something a viewer should
+ * stream over ssh, and the cap is what makes the transfer BOUNDED rather than
+ * "however big the peer's file happens to be".
+ */
+export declare const REMOTE_VIEW_MAX_BYTES: number;
+/**
+ * Fetch an absolute remote file into a private local path, bounded.
+ *
+ * Auth is the CANONICAL device path, not a hand-rolled ssh: `buildSshInvocation`
+ * supplies the askpass shim for a password-auth box, `-i`/`IdentitiesOnly` for an
+ * explicit identity file, and the managed known-hosts pinning. Building the ssh
+ * args here instead meant a password-auth device could not be reached at all and
+ * an explicit `identityFile` was silently ignored.
+ *
+ * Bounded for real, not by a pre-flight `stat`: the byte budget is enforced on the
+ * stream as it arrives, so a file that grows between a size check and the copy — or
+ * a peer that misreports its size — still cannot spend more than the budget.
+ *
+ * The local file is written 0600 inside a 0700 directory, because a capture can
+ * show anything that was on the peer's screen and a world-readable temp path
+ * would publish it to every local user.
+ */
+export declare function fetchRemoteFileForViewing(device: string, remotePath: string, localPath: string, opts?: {
+    maxBytes?: number;
+    timeoutMs?: number;
+}): Promise<void>;
 /**
  * The fleet browser hub this box drives by default (`browser.device`), or
  * undefined to drive locally. It is one fleet-synced value in the central

package/dist/commands/browser.js

@@ -25,7 +25,11 @@ import { withActorEnv } from '../lib/hosts/dispatch.js';
 import { streamAgentsOnHost, passthroughSshOptions, } from '../lib/hosts/passthrough.js';
 import { buildRemoteAgentsInvocation, HOST_ROUTING_SPECS, stripRoutingFlags, } from '../lib/hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
-import { sshExec, SSH_OPTS } from '../lib/ssh-exec.js';
+import { sshExec, SSH_OPTS, sshStreamWithArgs } from '../lib/ssh-exec.js';
+import { getBrowserRuntimeDir } from '../lib/state.js';
+import { buildSshInvocation, writeAskpassShim } from '../lib/devices/connect.js';
+import { resolveDeviceProfile } from '../lib/devices/resolve-profile.js';
+import { resolveDeviceTarget } from '../lib/devices/resolve-target.js';
 import { flagValue } from '../lib/hosts/routing-flag.js';
 import { browserTaskPicker } from './browser-picker.js';
 import { assertRemoteControlAllowed, isFleetRemoteInvocation } from '../lib/browser/remote-control.js';
@@ -35,7 +39,7 @@ import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { buildHar } from '../lib/browser/har.js';
 import { getCliVersion } from '../lib/version.js';
 import { runBrowserIPCStream } from '../lib/browser/stream.js';
-import { machineId } from '../lib/machine-id.js';
+import { machineId, normalizeHost } from '../lib/machine-id.js';
 import { isArcRunning } from '../lib/browser/drivers/arc.js';
 import { resolveBrowserTarget } from '../lib/browser/resolve-target.js';
 /**
@@ -179,6 +183,158 @@ export function remoteStartTaskName(stdout, explicit) {
     }
     return trimmed.split('\n').map((line) => line.trim()).find(Boolean);
 }
+/**
+ * Fetch an absolute remote file into a private local path, bounded.
+ *
+ * Bounded for real, not by a pre-flight `stat`: the byte budget is enforced on the
+ * stream as it arrives (`sshExecRawStream` + `cat`), so a file that grows between
+ * a size check and the copy — or a peer that lies about the size — still cannot
+ * spend more than the budget. `scp` could not do this; it would transfer
+ * everything before this process got a chance to refuse.
+ *
+ * The local file is written 0600 inside a 0700 directory, because a capture can
+ * show anything that was on the peer's screen and a world-readable temp path
+ * would publish it to every local user.
+ */
+/**
+ * The command that streams one file's RAW BYTES to stdout on the device's shell.
+ *
+ * Platform-correct, not one command with a portable-looking name. On Windows
+ * `cat` is an alias for `Get-Content`, which is a TEXT reader: it decodes the
+ * file, splits it into lines, and re-encodes on output — so a screenshot arrives
+ * corrupted rather than merely reordered. The .NET path opens a `FileStream` and
+ * copies it into the raw stdout handle, bypassing PowerShell's object/text
+ * pipeline entirely, which is the only way binary survives.
+ */
+export function remoteReadFileArgv(remotePath, shell) {
+    if (shell === 'powershell') {
+        // Single-quoted inside the script with pwsh's own doubling, because this whole
+        // script is ONE argv token to the outer powershell.
+        const literal = remotePath.replace(/'/g, "''");
+        return ['powershell', '-NoProfile', '-Command', [
+                '$ErrorActionPreference=' + "'Stop';",
+                `$in=[System.IO.File]::OpenRead('${literal}');`,
+                'try{$out=[System.Console]::OpenStandardOutput();$in.CopyTo($out);$out.Flush()}finally{$in.Dispose()}',
+            ].join(' ')];
+    }
+    // `--` so a path that begins with a dash is a path, not an option.
+    return ['cat', '--', remotePath];
+}
+/**
+ * Largest capture `browser show --device` will pull. A capture is a screenshot,
+ * a PDF or a short recording; anything past this is not something a viewer should
+ * stream over ssh, and the cap is what makes the transfer BOUNDED rather than
+ * "however big the peer's file happens to be".
+ */
+export const REMOTE_VIEW_MAX_BYTES = 64 * 1024 * 1024;
+/** Write a whole buffer, looping until it is all out. */
+function writeFully(handle, chunk) {
+    let offset = 0;
+    while (offset < chunk.length) {
+        // `writeSync` may write FEWER bytes than asked (a signal, a pipe boundary),
+        // and ignoring the return value silently truncated the file mid-capture.
+        const wrote = fs.writeSync(handle, chunk, offset, chunk.length - offset);
+        if (wrote <= 0)
+            throw new Error('local write made no progress');
+        offset += wrote;
+    }
+}
+/**
+ * Fetch an absolute remote file into a private local path, bounded.
+ *
+ * Auth is the CANONICAL device path, not a hand-rolled ssh: `buildSshInvocation`
+ * supplies the askpass shim for a password-auth box, `-i`/`IdentitiesOnly` for an
+ * explicit identity file, and the managed known-hosts pinning. Building the ssh
+ * args here instead meant a password-auth device could not be reached at all and
+ * an explicit `identityFile` was silently ignored.
+ *
+ * Bounded for real, not by a pre-flight `stat`: the byte budget is enforced on the
+ * stream as it arrives, so a file that grows between a size check and the copy — or
+ * a peer that misreports its size — still cannot spend more than the budget.
+ *
+ * The local file is written 0600 inside a 0700 directory, because a capture can
+ * show anything that was on the peer's screen and a world-readable temp path
+ * would publish it to every local user.
+ */
+export async function fetchRemoteFileForViewing(device, remotePath, localPath, opts = {}) {
+    const posixAbsolute = path.posix.isAbsolute(remotePath);
+    const windowsAbsolute = /^[A-Za-z]:[\\/]/.test(remotePath) || /^\\\\/.test(remotePath);
+    if (!posixAbsolute && !windowsAbsolute) {
+        throw new Error(`Remote path must be absolute: got "${remotePath}".\n`
+            + 'This machine cannot resolve the peer\'s working directory, so a relative path\n'
+            + 'would name a different file there than you meant here.');
+    }
+    // `resolveDeviceTarget` is the SAME resolver `agents ssh` uses, so it yields the
+    // full device profile — platform, shell and auth — that `buildSshInvocation`
+    // needs. `resolveHost` returns a hosts-registry `Host`, which carries none of
+    // that: with it, a password-auth device could not be reached and an explicit
+    // identityFile was silently dropped.
+    const resolved = await resolveDeviceTarget(device);
+    if (!resolved)
+        throw new Error(`Unknown device "${device}". Next: agents devices list`);
+    const profile = resolveDeviceProfile(resolved);
+    const maxBytes = opts.maxBytes ?? REMOTE_VIEW_MAX_BYTES;
+    // A POSIX device cannot read a Windows path and vice versa; saying so here beats
+    // a confusing shell error from the peer.
+    if (profile.shell === 'powershell' && posixAbsolute && !windowsAbsolute) {
+        throw new Error(`"${remotePath}" is a POSIX path but ${device} runs PowerShell. Pass the Windows path (e.g. C:\\Users\\…).`);
+    }
+    if (profile.shell !== 'powershell' && windowsAbsolute) {
+        throw new Error(`"${remotePath}" is a Windows path but ${device} is a POSIX host. Pass the absolute POSIX path.`);
+    }
+    const resolvedLocal = path.resolve(localPath);
+    const dir = path.dirname(resolvedLocal);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.chmodSync(dir, 0o700);
+    const handle = fs.openSync(resolvedLocal, 'w', 0o600);
+    let written = 0;
+    let overflow = false;
+    const controller = new AbortController();
+    try {
+        // `argv: true` is what makes a path containing a space or a quote survive —
+        // the same exact-token delivery `agents ssh --argv` exposes.
+        const { args, env } = buildSshInvocation(profile, remoteReadFileArgv(remotePath, profile.shell), writeAskpassShim(), {}, { argv: true });
+        const result = await sshStreamWithArgs({
+            args,
+            env,
+            timeoutMs: opts.timeoutMs ?? 120_000,
+            signal: controller.signal,
+            onStdout: (chunk) => {
+                if (overflow)
+                    return;
+                if (written + chunk.length > maxBytes) {
+                    overflow = true;
+                    controller.abort();
+                    return;
+                }
+                writeFully(handle, chunk);
+                written += chunk.length;
+            },
+        });
+        if (overflow) {
+            throw new Error(`Refusing to pull ${device}:${remotePath}: larger than the ${maxBytes}-byte view budget.`);
+        }
+        if (result.timedOut)
+            throw new Error(`Timed out pulling ${device}:${remotePath}.`);
+        if (result.code !== 0) {
+            const detail = result.stderr.toString('utf8').trim();
+            throw new Error(`Failed to read ${device}:${remotePath}${detail ? `: ${detail}` : ` (ssh exited ${result.code})`}`);
+        }
+        if (written === 0)
+            throw new Error(`${device}:${remotePath} is empty or was not readable.`);
+    }
+    catch (error) {
+        // Never leave a partial file behind for a viewer to open as if it were whole.
+        try {
+            fs.unlinkSync(resolvedLocal);
+        }
+        catch { /* nothing to clean */ }
+        throw error;
+    }
+    finally {
+        fs.closeSync(handle);
+    }
+}
 async function pullRemoteFile(device, remotePath, localPath) {
     const host = await resolveHost(device);
     if (!host) {
@@ -2071,8 +2227,14 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('show <url>')
-        .description('Open a URL for a human to read: goes to browser.viewer (default: browser.profile), and binds no task')
+        .description('Open a URL or local file for a human to read: goes to browser.viewer (default: browser.profile), and binds no task')
         .option('--os-browser', 'Use the OS default handler instead of the configured viewer')
+        // `--device` here names WHERE THE FILE IS, not where to open it. `show` is the
+        // one browser verb narrowly exempt from the task-routing refusal
+        // (`REJECT_DEVICE_MESSAGE`) because it binds no task and has nothing to route:
+        // it is a local viewer, so the flag can only mean "the source lives there".
+        // Every other verb still refuses `--device` — a task is bound at `start`.
+        .option('--device <name>', 'fetch the file from this device, then view it locally (absolute path only)')
         .option('--json', 'Output machine-readable JSON')
         .action(async (url, opts) => {
         // The entry point external tools need. `navigate` binds a task, which the
@@ -2083,20 +2245,48 @@ function registerTaskCommands(browser) {
         // drive letter (`C:\Users\me\plan.html`), so a real path was treated as a
         // URL. A scheme is at least two characters.
         const isLocalFile = !/^[a-z][a-z0-9+.-]+:/i.test(url);
-        const outcome = isLocalFile
-            ? await showFile(path.resolve(url), { osBrowser: opts.osBrowser })
+        let localTarget = isLocalFile ? path.resolve(url) : undefined;
+        let fetched;
+        if (opts.device) {
+            // A URL is already reachable from here, so `--device` with one is a
+            // contradiction rather than a no-op: it says the source is remote while
+            // naming something that is not a file on that peer.
+            if (!isLocalFile) {
+                console.error(`--device names the device holding a FILE, so it cannot be combined with a URL.\n  Drop --device to open ${url} here, or pass an absolute path on ${opts.device}.`);
+                process.exit(1);
+            }
+            // The peer's path, verbatim — NOT path.resolve()'d, which would rewrite it
+            // against this machine's cwd and name a different file there.
+            const remotePath = url;
+            const dir = path.join(getBrowserRuntimeDir(), 'remote-views');
+            fetched = path.join(dir, `${normalizeHost(opts.device)}-${Date.now()}-${path.basename(remotePath) || 'capture'}`);
+            try {
+                await fetchRemoteFileForViewing(opts.device, remotePath, fetched);
+            }
+            catch (error) {
+                console.error(error.message);
+                process.exit(1);
+            }
+            localTarget = fetched;
+        }
+        const outcome = localTarget
+            ? await showFile(localTarget, { osBrowser: opts.osBrowser })
             : await showUrl(url, { osBrowser: opts.osBrowser });
+        // The fetched copy is what a viewer actually opened, so it is what the
+        // caller is told about — pointing at the peer's path would name a file that
+        // is not on this machine.
+        const shown = fetched ?? url;
         if (opts.json) {
-            console.log(JSON.stringify(outcome, null, 2));
+            console.log(JSON.stringify({ ...outcome, ...(fetched ? { source: `${opts.device}:${url}`, local: fetched } : {}) }, null, 2));
         }
         else if (outcome.via === 'none') {
-            console.error(`Could not open a browser — open this yourself:\n  ${url}`);
+            console.error(`Could not open a browser — open this yourself:\n  ${shown}`);
         }
         else if (outcome.via === 'profile') {
-            console.log(`Shown in ${outcome.profile}: ${url}`);
+            console.log(`Shown in ${outcome.profile}: ${shown}`);
         }
         else {
-            console.log(`Opened in the OS default browser: ${url}`);
+            console.log(`Opened in the OS default browser: ${shown}`);
         }
         if (outcome.via === 'none')
             process.exit(1);

package/dist/commands/computer-sessions-picker.d.ts

@@ -1,5 +1,5 @@
 import { type ComputerRunRow } from '../lib/computer/sessions-list.js';
-export interface ComputerSessionsCommandOpts {
+interface ComputerSessionsCommandOpts {
     machine?: string;
     /** Row cap for the flat table only — the interactive picker is searchable
      *  and shows every row regardless (see `runComputerSessions`). */
@@ -19,3 +19,4 @@ export declare function shouldOpenInteractiveComputerSessions(opts: ComputerSess
  * split so both call sites stay in lockstep.
  */
 export declare function runComputerSessionsCommand(opts: ComputerSessionsCommandOpts): Promise<void>;
+export {};

package/dist/commands/computer.d.ts

@@ -39,6 +39,7 @@
  * own event ledger.
  */
 import { Command } from 'commander';
+import { type ComputerTargetContext } from '../lib/computer/context.js';
 /**
  * The verb catalog. Descriptions are the consumer's (they appear in
  * `agents computer --help`); flags are the engine's.
@@ -65,38 +66,32 @@ export declare function shouldBlockOffPlatform(opts: {
     device?: string;
 }): boolean;
 /**
- * Put `--device <name>` back on the argv handed to the engine.
+ * Put `--host <address>` on the argv handed to the engine.
  *
  * commander CONSUMES the `--device` it declares, so a verb that only read
  * `opts.device` forwarded an argv with no remote selector in it and the engine
  * — which selects the remote path from its own argv — ran the invocation
  * LOCALLY. That is how `setup --device win-mini` installed the macOS helper on
  * the laptop. The flag is re-inserted immediately after the verb rather than
- * appended, so a verb whose operands are variadic cannot swallow it.
+ * appended, so a verb whose operands are variadic cannot swallow it. A `--host`
+ * the caller already typed always wins — it is never overwritten (PHNX-4090).
  *
  * Pure, so the re-insertion is testable without spawning the engine.
  */
-export declare function withDeviceFlag(argv: string[], device?: string): string[];
+export declare function withHostFlag(argv: string[], host?: string): string[];
 /**
- * Forward one invocation to the engine and propagate its exit code.
- *
- * A missing standalone is the one failure agents-cli reports itself, because it
- * is the one the engine cannot: it prints the install line and exits 1. There is
- * no fallback engine to reach for — that is the point of the extraction.
+ * Resolve `--device <name>` to the `--host <address>` the engine actually
+ * speaks (PHNX-4090). A device's `computer.host` config (`agents config set
+ * devices.<name>.computer.host <address>`) wins when set — `vnc://`/`tcp://`
+ * carries no ssh identity, `ssh://` still resolves one against the fleet. With
+ * no `computer.host`, fall back to the fleet's ssh identity exactly as before
+ * (Windows-only — the tunnel this repo has always provisioned).
  */
-export declare function forwardToComputer(opts: {
-    argv: string[];
-    device?: string;
-    /** Skip recording — lifecycle verbs are not user actions. */
-    record?: boolean;
-    /** Read the engine's stdout instead of letting it reach the terminal. */
-    capture?: boolean;
-}): Promise<{
-    exitCode: number;
-    stdout: string;
+export declare function resolveDeviceHost(device: string): Promise<{
+    host: string;
+    target: ComputerTargetContext;
 }>;
 export declare function registerComputerCommand(program: Command): void;
-export declare function registerComputerSubcommands(program: Command): void;
 /**
  * Install the macOS helper through the engine. Used by the `agents setup
  * computer` wizard, which still owns the TCC hand-holding — that is a

package/dist/commands/computer.js

@@ -42,6 +42,9 @@ import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { loadComputerAllowList, loadDefaultPeers, resolveTcpEndpoint, resolveVncEndpoint, } from '../lib/computer/policy.js';
 import { buildComputerContext } from '../lib/computer/context.js';
 import { recordComputerAction } from '../lib/computer/record.js';
+import { resolveRemoteDevice } from '../lib/ssh-tunnel.js';
+import { getConfigValue } from '../lib/device-config.js';
+import { parseAddress, sshTarget } from '../lib/address.js';
 import { isComputerClientError, resolveComputerBin, runComputer, } from '../lib/computer-client.js';
 import { runComputerSessionsCommand } from './computer-sessions-picker.js';
 // Help groups — mirror `agents browser` so the mental model carries over.
@@ -99,22 +102,65 @@ export function shouldBlockOffPlatform(opts) {
     return true;
 }
 /**
- * Put `--device <name>` back on the argv handed to the engine.
+ * Put `--host <address>` on the argv handed to the engine.
  *
  * commander CONSUMES the `--device` it declares, so a verb that only read
  * `opts.device` forwarded an argv with no remote selector in it and the engine
  * — which selects the remote path from its own argv — ran the invocation
  * LOCALLY. That is how `setup --device win-mini` installed the macOS helper on
  * the laptop. The flag is re-inserted immediately after the verb rather than
- * appended, so a verb whose operands are variadic cannot swallow it.
+ * appended, so a verb whose operands are variadic cannot swallow it. A `--host`
+ * the caller already typed always wins — it is never overwritten (PHNX-4090).
  *
  * Pure, so the re-insertion is testable without spawning the engine.
  */
-export function withDeviceFlag(argv, device) {
-    if (!device)
+export function withHostFlag(argv, host) {
+    if (!host)
+        return argv;
+    if (argv.some((arg) => arg === '--host' || arg.startsWith('--host=')))
         return argv;
     const [verb, ...rest] = argv;
-    return [verb, '--device', device, ...rest];
+    return [verb, '--host', host, ...rest];
+}
+/**
+ * Resolve `--device <name>` to the `--host <address>` the engine actually
+ * speaks (PHNX-4090). A device's `computer.host` config (`agents config set
+ * devices.<name>.computer.host <address>`) wins when set — `vnc://`/`tcp://`
+ * carries no ssh identity, `ssh://` still resolves one against the fleet. With
+ * no `computer.host`, fall back to the fleet's ssh identity exactly as before
+ * (Windows-only — the tunnel this repo has always provisioned).
+ */
+export async function resolveDeviceHost(device) {
+    const configured = getConfigValue('computer.host', { device }).value;
+    if (configured) {
+        const addr = parseAddress(configured);
+        if (addr.scheme === 'vnc' || addr.scheme === 'tcp') {
+            // No ssh identity involved — the transport is RFB or a raw helper socket.
+            return { host: configured, target: { alias: device, host: addr.host, user: addr.user ?? '', hostname: addr.host, platform: addr.scheme, sshArgs: [] } };
+        }
+        // The configured address IS the connection target — an ssh:// override
+        // naming a different host/user/port than the device registry must actually
+        // take effect, not be silently replaced by the registry's own resolution.
+        // Only the ssh identity (key file flags) comes from the fleet; the target
+        // string forwarded on --host and the one recorded on fd-3 must be the same
+        // `sshTarget(addr)` the engine itself derives from that same --host value,
+        // or the engine's own context-vs-argv match (`resolveContextDevice`) misses
+        // and silently drops the identity args instead of failing loud.
+        const resolved = await resolveRemoteDevice(device, {});
+        const target = sshTarget(addr);
+        return {
+            host: configured,
+            target: { alias: device, host: target, user: addr.user ?? resolved.user, hostname: addr.host, platform: resolved.device.platform, sshArgs: resolved.identityArgs },
+        };
+    }
+    const resolved = await resolveRemoteDevice(device, {
+        expectPlatform: 'windows',
+        forWhat: '`agents computer --device` drives the Windows computer-helper daemon, so it',
+    });
+    return {
+        host: `ssh://${resolved.target}`,
+        target: { alias: device, host: resolved.target, user: resolved.user, hostname: resolved.host, platform: resolved.device.platform, sshArgs: resolved.identityArgs },
+    };
 }
 /**
  * Forward one invocation to the engine and propagate its exit code.
@@ -123,7 +169,7 @@ export function withDeviceFlag(argv, device) {
  * is the one the engine cannot: it prints the install line and exits 1. There is
  * no fallback engine to reach for — that is the point of the extraction.
  */
-export async function forwardToComputer(opts) {
+async function forwardToComputer(opts) {
     let bin;
     try {
         bin = resolveComputerBin();
@@ -136,10 +182,19 @@ export async function forwardToComputer(opts) {
         throw err;
     }
     const hostFlag = opts.argv.findIndex(arg => arg === '--host' || arg.startsWith('--host='));
-    const host = hostFlag < 0 ? undefined : (opts.argv[hostFlag].includes('=') ? opts.argv[hostFlag].slice(7) : opts.argv[hostFlag + 1]);
-    const context = await buildComputerContext({ device: opts.device, host, computerBin: bin });
+    let host = hostFlag < 0 ? undefined : (opts.argv[hostFlag].includes('=') ? opts.argv[hostFlag].slice(7) : opts.argv[hostFlag + 1]);
+    let target;
+    // A device is resolved to --host here rather than forwarded as --device: the
+    // engine has no fleet registry of its own (PHNX-4090). An explicit --host on
+    // the command line always wins over --device, so this only runs without one.
+    if (!host && opts.device) {
+        const resolved = await resolveDeviceHost(opts.device);
+        host = resolved.host;
+        target = resolved.target;
+    }
+    const context = await buildComputerContext({ device: opts.device, host, target, computerBin: bin });
     return runComputer({
-        argv: withDeviceFlag(opts.argv, opts.device),
+        argv: withHostFlag(opts.argv, host),
         context,
         capture: opts.capture,
         onEvent: opts.record === false
@@ -224,7 +279,7 @@ export function registerComputerCommand(program) {
     `,
     });
 }
-export function registerComputerSubcommands(program) {
+function registerComputerSubcommands(program) {
     registerSetupCommand(program);
     registerStartCommand(program);
     registerStopCommand(program);

package/dist/commands/config.js

@@ -15,11 +15,11 @@
 import chalk from 'chalk';
 import { AGENTS } from '../lib/agents.js';
 import { setHelpSections } from '../lib/help.js';
-import { parseConfigKey, formatAgentVersion, devicePropertyToConfigName, configKeyStorageHint, } from '../lib/config-keys.js';
+import { parseConfigKey, formatConfigKey, formatAgentVersion, devicePropertyToConfigName, configKeyStorageHint, MENUBAR_MENU_PROPERTIES, } from '../lib/config-keys.js';
 import { registerBudgetCommand } from './budget.js';
 import { resolveRunDefaults, setRunDefaultModel, setRunDefaultMode, setRunDefaultEffort, unsetRunDefault, } from '../lib/run-defaults.js';
 import { resolveTierOverride, setTierOverride, clearTierOverride } from '../lib/model-tier-overrides.js';
-import { getConfigValue, setConfigValue, unsetConfigValue, listConfig, } from '../lib/device-config.js';
+import { getConfigValue, setConfigValue, unsetConfigValue, listConfig, configKeySpec, } from '../lib/device-config.js';
 import { readMeta, updateMeta } from '../lib/state.js';
 import { MODEL_TIERS } from '../lib/model-tiers.js';
 import { machineId } from '../lib/machine-id.js';
@@ -51,6 +51,20 @@ function parseValue(key, parsed, raw) {
             return parsed.property === 'enabled' ? parseBool(raw, key) : raw.trim();
         case 'updates':
             return parseBool(raw, key);
+        case 'menubar': {
+            // The type (and enum validation) live in the device-config spec; parse the
+            // raw string to that type here so setConfigValue's assertion passes.
+            const spec = configKeySpec(formatConfigKey(parsed));
+            if (spec.type === 'bool')
+                return parseBool(raw, key);
+            if (spec.type === 'int') {
+                if (!/^\d+$/.test(raw.trim())) {
+                    throw new Error(`Config key '${key}' expects an integer, got '${raw}'.`);
+                }
+                return Number.parseInt(raw.trim(), 10);
+            }
+            return raw.trim();
+        }
         case 'device': {
             const property = parsed.property;
             switch (property) {
@@ -74,8 +88,11 @@ function parseValue(key, parsed, raw) {
                     return Number.parseInt(raw.trim(), 10);
                 case 'notes':
                     return raw.trim();
+                case 'formFactor':
+                    return raw.trim();
                 case 'browser.profile':
                 case 'browser.viewer':
+                case 'computer.host':
                     return raw.trim();
             }
             // A device property with no arm above used to fall out of the switch and
@@ -143,6 +160,10 @@ function setConfig(parsed, value) {
                 setGlobalAutoUpdateEnabled(value);
             return;
         }
+        case 'menubar': {
+            setConfigValue(formatConfigKey(parsed), value);
+            return;
+        }
         case 'device': {
             const configName = devicePropertyToConfigName(parsed.property);
             if (parsed.property === 'notes') {
@@ -217,6 +238,12 @@ function unsetConfig(parsed) {
             unsetGlobalAutoUpdateEnabled();
             return had;
         }
+        case 'menubar': {
+            const name = formatConfigKey(parsed);
+            const had = getConfigValue(name).value !== undefined;
+            unsetConfigValue(name);
+            return had;
+        }
         case 'device': {
             const configName = devicePropertyToConfigName(parsed.property);
             const had = getConfigValue(configName, { device: parsed.device }).value !== undefined;
@@ -251,6 +278,8 @@ function getConfig(parsed) {
             return getConfigValue(`summarizer.${parsed.property}`).value;
         case 'updates':
             return parsed.agent ? rawAgentAutoUpdateSetting(parsed.agent) : rawGlobalAutoUpdateSetting();
+        case 'menubar':
+            return getConfigValue(formatConfigKey(parsed)).value;
         case 'device': {
             const configName = devicePropertyToConfigName(parsed.property);
             return getConfigValue(configName, { device: parsed.device }).value;
@@ -345,6 +374,15 @@ function* listCentralConfigEntries() {
             yield { key, value, hint: configKeyStorageHint(parseConfigKey(key)) };
         }
     }
+    // AGI Menu preferences (PHNX-3999) — user scope, syncs fleet-wide. Only set
+    // keys are listed; the native menu falls back to its own defaults for the rest.
+    for (const prop of MENUBAR_MENU_PROPERTIES) {
+        const key = `menubar.menu.${prop}`;
+        const value = getConfigValue(key).value;
+        if (value !== undefined) {
+            yield { key, value, hint: configKeyStorageHint(parseConfigKey(key)) };
+        }
+    }
 }
 /** Collect device-scope config entries. */
 function* listDeviceConfigEntries(device) {
@@ -378,6 +416,9 @@ function* listDeviceConfigEntries(device) {
             case 'notes':
                 key = `${prefix}notes`;
                 break;
+            case 'formFactor':
+                key = `${prefix}formFactor`;
+                break;
             case 'browser.profile':
                 // The self device's default browser profile is already surfaced as the
                 // top-level `browser.profile` key; skip it here to avoid duplication.
@@ -391,6 +432,9 @@ function* listDeviceConfigEntries(device) {
                     continue;
                 key = `${prefix}browser.viewer`;
                 break;
+            case 'computer.host':
+                key = `${prefix}computer.host`;
+                break;
             default:
                 // A `default: continue` here silently drops any device property with no
                 // arm — which is how browser.viewer was invisible to `config list` after

package/dist/commands/daemon.d.ts

@@ -17,29 +17,6 @@
  * duplicating it.
  */
 import type { Command } from 'commander';
-import { type DaemonServiceId } from '../lib/daemon-services.js';
-/** Parse a `ps -o etime=` value (`[[dd-]hh:]mm:ss`) into elapsed seconds. */
-export declare function parseEtimeToSeconds(raw: string): number | null;
 /** Elapsed wall-clock seconds since `pid` started, or null if unavailable (best-effort, POSIX only). */
 export declare function uptimeSeconds(pid: number): number | null;
-/** One row of the roster every registered daemon service — supervisor-managed or legacy — renders in `agents daemon services`. */
-export interface DaemonServiceRow {
-    id: DaemonServiceId;
-    title: string;
-    description: string;
-    enabled: boolean;
-    /**
-     * `ServiceSupervisor`'s real lifecycle state when `supervised` is true
-     * (`idle`/`running`/`parked`/`stopped`, written cross-process via
-     * `recordSubsystemState`). A legacy `setInterval`-driven service has no such
-     * record, so its state is inferred from `enabled` + whether the daemon
-     * process is up — labelled distinctly so a reader can't mistake it for a
-     * measured value.
-     */
-    state: string;
-    supervised: boolean;
-    lastRunMs: number | null;
-    lastError: string | null;
-    consecutiveFailures: number;
-}
 export declare function registerDaemonCommand(program: Command): void;

package/dist/commands/daemon.js

@@ -254,7 +254,7 @@ function registryScopedDuplicates(processes, ownerPid) {
     return processes.filter((p) => registered.has(p.pid));
 }
 /** Parse a `ps -o etime=` value (`[[dd-]hh:]mm:ss`) into elapsed seconds. */
-export function parseEtimeToSeconds(raw) {
+function parseEtimeToSeconds(raw) {
     const m = raw.match(/^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/);
     if (!m)
         return null;