@phnx-labs/agents-cli 1.22.74 → 1.22.75

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 1.22.75
+
+- **Account labels are per-harness, and survive a daemon publish (PHNX-3887).** One
+  identity signed into several harnesses can now carry the SAME label on each —
+  `claude#icloud`, `codex#icloud`, and `grok#icloud` all resolve to that harness's own
+  login, instead of the first-labelled harness squatting the name and forcing prefixes
+  (`cxicloud`, `gkicloud`) on the rest. Uniqueness is scoped to `(agent, label)`;
+  provider accounts, selected by bare name via `--account`, stay globally unique, and a
+  duplicate label within one harness is still refused. Separately, `agents accounts
+  label` wrote version-scoped rows into the central `agents.yaml` as a plain file write
+  with no commit, so the daemon's `publish <device> daemon state` tick — which committed
+  only the per-device doc and then rebased `--autostash` over the dirty central file —
+  silently destroyed them: every box lost its account labels on its next publish. The
+  publish now commits `agents.yaml` alongside the device doc, so labels persist and
+  actually sync fleet-wide as `accounts label --help` already promised. Source:
+  `cli/src/lib/account-registry.ts`, `cli/src/lib/fleet-shared-repo-sync.ts`.
+
+- **Keep one daemon alive across concurrent stop/start (PHNX-3941).** Prevent a replacement daemon from exiting while stop holds the lifecycle lock, so concurrent stop/start cannot leave zero instances, and extend real-boot supervisor-wiring coverage to all 20 services. Source: `cli/src/lib/daemon/daemon.ts`.
+
+- **`agents computer` can now drive a Linux GUI desktop over VNC/RFB (PHNX-3948).**
+  A third computer backend joins the macOS (Accessibility) and Windows (UIA) native
+  helpers — this one speaks the RFB/VNC protocol directly to an x11vnc/Xvnc server, so
+  a headless Linux desktop (or an LXD container exposing x11vnc on the host's Tailscale
+  IP) becomes drivable with no per-box native helper install. Select it with
+  `agents computer --vnc <host:port>` (port defaults to 5901; password via
+  `--vnc-password` or `COMPUTER_HELPER_VNC_PASSWORD`), then use the same verbs as the
+  other backends: `screenshot`, `click`, `right-click`, `type`, `type-text`, `key`,
+  `scroll`, `wait`. It is coordinate-based — RFB carries a framebuffer and pointer/key
+  events, not an accessibility tree — so the AX-tree verbs (`describe`, `get-text`,
+  `ax-action`, element-id targeting) and `launch` fail loud with a clear message rather
+  than silently no-op'ing. VNC authentication uses a bundled pure-JS DES (Node 24's
+  OpenSSL 3 keeps DES in the off-by-default legacy provider). Source:
+  `cli/src/lib/computer/rfb-client.ts`, `cli/src/lib/computer/des.ts`,
+  `cli/src/lib/computer/computer-rpc.ts`, `cli/src/commands/computer.ts`.
+
 ## 1.22.74
 
 - **Launching an agent no longer dirties your tracked `.gitignore` (PHNX-3718).**

package/README.md

@@ -1756,7 +1756,7 @@ Agents are defined in [src/lib/agents.ts](cli/src/lib/agents.ts) -- each is a co
 |---|---|
 | [`cli`](cli) | **The CLI** (this README) — version management, config sync, sessions, teams, cloud, browser, computer, secrets. |
 | [phnx-labs/agi-ext](https://github.com/phnx-labs/agi-ext) | **AGI EXT** — the VS Code extension (agent terminals as tabs + the Fleet dashboard). Moved to its own repo (RUSH-3189); separate product, own publish identity. |
-| [`native/computer-mac`](native/computer-mac) · [`native/computer-win`](native/computer-win) | Native backends behind `agents computer` — Swift (macOS Accessibility + screen capture) and C#/.NET (Windows UI Automation). |
+| [`native/computer-mac`](native/computer-mac) · [`native/computer-win`](native/computer-win) | Native backends behind `agents computer` — Swift (macOS Accessibility + screen capture) and C#/.NET (Windows UI Automation). A third, install-free backend drives a **Linux GUI desktop over VNC/RFB**: `agents computer --vnc <host:port> screenshot` (coordinate-based — screenshot/click/type/key/scroll against any x11vnc/Xvnc server). |
 | [`packages/session-tracker`](packages/session-tracker) | The `SessionStart` hook that writes live-session state **AGI EXT** reads back (agi-ext `src/core/liveSession.ts`) — not the CLI, which reads transcripts. |
 
 ## Contributing

package/dist/commands/computer.d.ts

@@ -10,6 +10,7 @@ import { resolveHelperExec, resolveSocketPath } from '../lib/computer/computer-r
 export declare function shouldBlockOffPlatform(opts: {
     platform: NodeJS.Platform;
     tcpConfigured: boolean;
+    vncConfigured?: boolean;
     device?: string;
 }): boolean;
 /**

package/dist/commands/computer.js

@@ -3,7 +3,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { registerCommandGroups } from '../lib/help.js';
-import { openComputerClient, resolveHelperApp, resolveHelperExec, resolveSocketPath, resolveLogPath, resolvePolicyPath, resolvePeersPath, resolveTcpEndpoint, loadComputerAllowList, loadDefaultPeers, writeComputerPolicy, writeComputerPeers, } from '../lib/computer/computer-rpc.js';
+import { openComputerClient, resolveHelperApp, resolveHelperExec, resolveSocketPath, resolveLogPath, resolvePolicyPath, resolvePeersPath, resolveTcpEndpoint, resolveVncEndpoint, loadComputerAllowList, loadDefaultPeers, writeComputerPolicy, writeComputerPeers, } from '../lib/computer/computer-rpc.js';
 import { setupRemoteHelper, startRemoteTunnel, stopRemoteHelper, hydrateRemoteEnvFromState, readRemoteState, resolveRemoteDevice, REMOTE_TASK_NAME, WIN_HELPER_EXE, } from '../lib/computer/ssh-tunnel.js';
 import { sshExec } from '../lib/ssh-exec.js';
 import { encodePowershell } from '../lib/hosts/remote-cmd.js';
@@ -41,6 +41,8 @@ export function shouldBlockOffPlatform(opts) {
         return false;
     if (opts.tcpConfigured)
         return false; // remote (Windows) daemon over a tunnel
+    if (opts.vncConfigured)
+        return false; // RFB/VNC desktop (Linux GUI over the wire)
     if (opts.device)
         return false; // remote path resolves its own endpoint
     return true;
@@ -84,20 +86,37 @@ export function reconcileScreenshotExt(outPath, buf) {
 export function registerComputerCommand(program) {
     const computer = program
         .command('computer')
-        .description('Drive macOS apps via Accessibility, or a remote Windows device with --device — list, screenshot, click, type')
+        .description('Drive macOS apps via Accessibility, a Linux GUI desktop with --vnc, or a remote Windows device with --device — screenshot, click, type')
+        // A VNC/RFB desktop is driven over the wire (--vnc host:port, e.g. an x11vnc
+        // server on a headless Linux box or an LXD container). Set it before the gate.
+        .option('--vnc <host:port>', 'Drive a GUI desktop over VNC/RFB (x11vnc/Xvnc; port defaults to 5901) instead of a native helper')
+        .option('--vnc-password <password>', 'VNC password for --vnc (or set COMPUTER_HELPER_VNC_PASSWORD)')
         // The whole subsystem is macOS Accessibility / TCC for LOCAL driving. Off
-        // macOS it still works against a remote daemon (COMPUTER_HELPER_TCP set, or
-        // a `--device <name>` invocation). Fail fast with a clear message only when
-        // neither remote path is available, instead of a downstream launchctl error.
+        // macOS it still works against a remote daemon (COMPUTER_HELPER_TCP set, a
+        // --vnc desktop, or a `--device <name>` invocation). Fail fast with a clear
+        // message only when no remote path is available, instead of a downstream error.
         .hook('preAction', async (_thisCommand, actionCommand) => {
-        const device = actionCommand.opts().device;
+        const globals = actionCommand.optsWithGlobals();
+        // --vnc selects the RFB transport for every verb under this command.
+        if (globals.vnc) {
+            process.env.COMPUTER_HELPER_VNC = globals.vnc;
+            if (globals.vncPassword)
+                process.env.COMPUTER_HELPER_VNC_PASSWORD = globals.vncPassword;
+        }
+        const device = globals.device;
         // Verbs with --device reconnect to the tunnel `start --device` recorded;
         // this sets COMPUTER_HELPER_TCP so the shared client picks the TCP transport.
         if (device && !REMOTE_LIFECYCLE.has(actionCommand.name())) {
             hydrateRemoteEnvFromState(device);
         }
-        if (shouldBlockOffPlatform({ platform: process.platform, tcpConfigured: resolveTcpEndpoint() != null, device })) {
+        if (shouldBlockOffPlatform({
+            platform: process.platform,
+            tcpConfigured: resolveTcpEndpoint() != null,
+            vncConfigured: resolveVncEndpoint() != null,
+            device,
+        })) {
             console.error('agents computer: macOS only for local driving — it uses the macOS Accessibility API.');
+            console.error('For a Linux GUI desktop over VNC: `agents computer --vnc <host:port> screenshot`.');
             console.error('For a remote Windows device: register it with `agents devices`, then use --device (or set COMPUTER_HELPER_TCP).');
             process.exit(1);
         }

package/dist/lib/account-registry.js

@@ -187,11 +187,32 @@ function nativeRowsForNameOrId(meta, name) {
         return [];
     return nativeIdentityRows(meta, found.agent, found.identityKey);
 }
-function assertUniqueUnifiedName(name, meta, doc, exceptIds) {
+/**
+ * Native label names are unique per HARNESS, not globally (PHNX-3887).
+ *
+ * One human identity is commonly signed into several harnesses —
+ * `muqsitnawaz@icloud.com` is a claude login AND a codex login AND a grok login.
+ * A global namespace let whichever harness was labelled first squat the good
+ * name, forcing prefixed junk (`cxicloud`, `gkicloud`) on the rest. Nothing is
+ * actually ambiguous at the point of use: the selector is `<harness>#<label>`,
+ * and `findUnifiedAccount` already disambiguates via `preferAgent`.
+ *
+ * Pass `agent` to scope the check to that harness. Omit it for management
+ * lookups with no harness in hand (rename/remove), which keep the old
+ * fleet-wide check so a rename cannot collide with an unrelated harness's row.
+ *
+ * Provider (non-native) accounts stay globally unique — they are selected by
+ * bare name via `--account`, with no harness to scope them by.
+ */
+function assertUniqueUnifiedName(name, meta, doc, exceptIds, agent) {
     const needle = name.toLowerCase();
-    const nativeHits = listNativeAccounts(meta).filter(account => account.id === name || account.name.toLowerCase() === needle || account.identityLabel?.toLowerCase() === needle);
-    if (nativeHits.some(account => !exceptIds?.has(account.id)))
-        throw new Error(`Account '${name}' already exists.`);
+    const nativeHits = listNativeAccounts(meta).filter(account => (agent === undefined || account.agent === agent)
+        && (account.id === name || account.name.toLowerCase() === needle || account.identityLabel?.toLowerCase() === needle));
+    if (nativeHits.some(account => !exceptIds?.has(account.id))) {
+        throw new Error(agent === undefined
+            ? `Account '${name}' already exists.`
+            : `Account '${name}' already exists for the ${agent} harness.`);
+    }
     // Same laziness as findUnifiedAccount: a native row that already owns this
     // name (even one we are mutating) means we never open the provider store.
     if (nativeHits.length > 0)
@@ -203,7 +224,7 @@ function assertUniqueUnifiedName(name, meta, doc, exceptIds) {
 export function addNativeAccount(name, agent, identityKey, identityLabel, scope) {
     assertNativeLabel(name);
     const meta = readMeta();
-    assertUniqueUnifiedName(name, meta);
+    assertUniqueUnifiedName(name, meta, undefined, undefined, agent);
     const duplicate = listNativeAccounts(meta).find(account => account.agent === agent && account.identityKey === identityKey);
     if (duplicate)
         throw new Error(`This ${agent} login is already named '${duplicate.name}'.`);
@@ -240,7 +261,7 @@ export function labelNativeAccount(agent, identityKey, identityLabel, label, sco
     assertNativeLabel(resolvedLabel);
     const meta = readMeta();
     const matches = nativeIdentityRows(meta, agent, identityKey);
-    assertUniqueUnifiedName(resolvedLabel, meta, undefined, new Set(matches.map(account => account.id)));
+    assertUniqueUnifiedName(resolvedLabel, meta, undefined, new Set(matches.map(account => account.id)), agent);
     if (matches.length === 0)
         return addNativeAccount(resolvedLabel, agent, identityKey, identityLabel, scope);
     // Sweep every row for this identity (PHNX-3206), routing the whole sweep to the

package/dist/lib/computer/computer-rpc.d.ts

@@ -25,10 +25,15 @@ export declare function resolveTcpEndpoint(): {
     port: number;
     token: string | null;
 } | null;
+export declare function resolveVncEndpoint(): {
+    host: string;
+    port: number;
+    password: string;
+} | null;
 export declare function openComputerClient(): ComputerClient;
 export declare const RPC_TIMEOUT_MS = 30000;
 export declare function resolveRpcTimeoutMs(env: string | undefined): number;
 export declare function describeTransport(): {
-    kind: 'socket' | 'stdio' | 'tcp' | 'none';
+    kind: 'socket' | 'stdio' | 'tcp' | 'vnc' | 'none';
     path: string | null;
 };

package/dist/lib/computer/computer-rpc.js

@@ -17,6 +17,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { getHelpersDir, getLogsDir, getUserPermissionsDir, getPermissionsDir } from '../state.js';
+import { RfbClient, parseVncEndpoint } from './rfb-client.js';
 // Resolve the socket path used by the launchd-managed daemon. Internal
 // scratch — lives under getHelpersDir() (~/.agents/.cache/helpers/),
 // matching browser.sock.
@@ -209,11 +210,28 @@ export function resolveTcpEndpoint() {
     const token = process.env.COMPUTER_HELPER_TOKEN;
     return { host: hostPart || '127.0.0.1', port, token: token && token.length > 0 ? token : null };
 }
+// Resolve the VNC/RFB endpoint for driving a remote GUI desktop over the RFB
+// protocol (an x11vnc/Xvnc server — e.g. a headless Linux desktop or an LXD
+// container exposing x11vnc on the host's Tailscale IP). COMPUTER_HELPER_VNC is
+// "host:port" (port defaults to 5901); COMPUTER_HELPER_VNC_PASSWORD is the VNC
+// password. Unlike the native helpers this transport carries a framebuffer, not
+// an accessibility tree, so it is coordinate-based (see rfb-client.ts).
+export function resolveVncEndpoint() {
+    const parsed = parseVncEndpoint(process.env.COMPUTER_HELPER_VNC);
+    if (!parsed)
+        return null;
+    return { ...parsed, password: process.env.COMPUTER_HELPER_VNC_PASSWORD ?? '' };
+}
 // Pick the best transport. Precedence:
-//   1. COMPUTER_HELPER_TCP -> the Windows daemon over a (tunneled) TCP port.
-//   2. the macOS launchd socket if it exists.
-//   3. spawning the helper as a subprocess (legacy/dev fallback).
+//   1. COMPUTER_HELPER_VNC  -> an RFB/VNC desktop (Linux GUI over the wire).
+//   2. COMPUTER_HELPER_TCP  -> the Windows daemon over a (tunneled) TCP port.
+//   3. the macOS launchd socket if it exists.
+//   4. spawning the helper as a subprocess (legacy/dev fallback).
 export function openComputerClient() {
+    const vnc = resolveVncEndpoint();
+    if (vnc) {
+        return new RfbClient(vnc.host, vnc.port, vnc.password);
+    }
     const tcp = resolveTcpEndpoint();
     if (tcp) {
         return new TcpClient(tcp.host, tcp.port, tcp.token);
@@ -415,6 +433,8 @@ class StdioClient extends BaseClient {
 // .app) must not be told "no transport". `path` is null: the endpoint is an
 // env-configured host:port, not an on-disk path.
 export function describeTransport() {
+    if (resolveVncEndpoint())
+        return { kind: 'vnc', path: null };
     if (resolveTcpEndpoint())
         return { kind: 'tcp', path: null };
     const sockPath = resolveSocketPath();

package/dist/lib/computer/des.d.ts

@@ -0,0 +1 @@
+export declare function desEncryptBlock(key8: Buffer, block8: Buffer): Buffer;

package/dist/lib/computer/des.js

@@ -0,0 +1,114 @@
+// Minimal, dependency-free single-block DES (ECB) — used only for VNC
+// authentication's challenge/response. Node 24 ships OpenSSL 3, whose DES lives
+// in the legacy provider that is off by default, so `createCipheriv('des-ecb')`
+// throws `digital envelope routines::unsupported`. VNC clients have always
+// bundled their own DES for exactly this reason. This is a textbook FIPS-46 DES
+// implementation over bit arrays — verified against the standard test vector in
+// des.test.ts. It encrypts one 8-byte block; VNC auth encrypts the two halves
+// of the 16-byte challenge independently (see rfb-client.ts).
+const IP = [
+    58, 50, 42, 34, 26, 18, 10, 2, 60, 52, 44, 36, 28, 20, 12, 4,
+    62, 54, 46, 38, 30, 22, 14, 6, 64, 56, 48, 40, 32, 24, 16, 8,
+    57, 49, 41, 33, 25, 17, 9, 1, 59, 51, 43, 35, 27, 19, 11, 3,
+    61, 53, 45, 37, 29, 21, 13, 5, 63, 55, 47, 39, 31, 23, 15, 7,
+];
+const FP = [
+    40, 8, 48, 16, 56, 24, 64, 32, 39, 7, 47, 15, 55, 23, 63, 31,
+    38, 6, 46, 14, 54, 22, 62, 30, 37, 5, 45, 13, 53, 21, 61, 29,
+    36, 4, 44, 12, 52, 20, 60, 28, 35, 3, 43, 11, 51, 19, 59, 27,
+    34, 2, 42, 10, 50, 18, 58, 26, 33, 1, 41, 9, 49, 17, 57, 25,
+];
+const E = [
+    32, 1, 2, 3, 4, 5, 4, 5, 6, 7, 8, 9, 8, 9, 10, 11, 12, 13, 12, 13, 14, 15, 16, 17,
+    16, 17, 18, 19, 20, 21, 20, 21, 22, 23, 24, 25, 24, 25, 26, 27, 28, 29, 28, 29, 30, 31, 32, 1,
+];
+const P = [
+    16, 7, 20, 21, 29, 12, 28, 17, 1, 15, 23, 26, 5, 18, 31, 10,
+    2, 8, 24, 14, 32, 27, 3, 9, 19, 13, 30, 6, 22, 11, 4, 25,
+];
+const PC1 = [
+    57, 49, 41, 33, 25, 17, 9, 1, 58, 50, 42, 34, 26, 18, 10, 2, 59, 51, 43, 35, 27, 19, 11, 3, 60, 52, 44, 36,
+    63, 55, 47, 39, 31, 23, 15, 7, 62, 54, 46, 38, 30, 22, 14, 6, 61, 53, 45, 37, 29, 21, 13, 5, 28, 20, 12, 4,
+];
+const PC2 = [
+    14, 17, 11, 24, 1, 5, 3, 28, 15, 6, 21, 10, 23, 19, 12, 4, 26, 8, 16, 7, 27, 20, 13, 2,
+    41, 52, 31, 37, 47, 55, 30, 40, 51, 45, 33, 48, 44, 49, 39, 56, 34, 53, 46, 42, 50, 36, 29, 32,
+];
+const SHIFTS = [1, 1, 2, 2, 2, 2, 2, 2, 1, 2, 2, 2, 2, 2, 2, 1];
+const SBOX = [
+    [14, 4, 13, 1, 2, 15, 11, 8, 3, 10, 6, 12, 5, 9, 0, 7, 0, 15, 7, 4, 14, 2, 13, 1, 10, 6, 12, 11, 9, 5, 3, 8, 4, 1, 14, 8, 13, 6, 2, 11, 15, 12, 9, 7, 3, 10, 5, 0, 15, 12, 8, 2, 4, 9, 1, 7, 5, 11, 3, 14, 10, 0, 6, 13],
+    [15, 1, 8, 14, 6, 11, 3, 4, 9, 7, 2, 13, 12, 0, 5, 10, 3, 13, 4, 7, 15, 2, 8, 14, 12, 0, 1, 10, 6, 9, 11, 5, 0, 14, 7, 11, 10, 4, 13, 1, 5, 8, 12, 6, 9, 3, 2, 15, 13, 8, 10, 1, 3, 15, 4, 2, 11, 6, 7, 12, 0, 5, 14, 9],
+    [10, 0, 9, 14, 6, 3, 15, 5, 1, 13, 12, 7, 11, 4, 2, 8, 13, 7, 0, 9, 3, 4, 6, 10, 2, 8, 5, 14, 12, 11, 15, 1, 13, 6, 4, 9, 8, 15, 3, 0, 11, 1, 2, 12, 5, 10, 14, 7, 1, 10, 13, 0, 6, 9, 8, 7, 4, 15, 14, 3, 11, 5, 2, 12],
+    [7, 13, 14, 3, 0, 6, 9, 10, 1, 2, 8, 5, 11, 12, 4, 15, 13, 8, 11, 5, 6, 15, 0, 3, 4, 7, 2, 12, 1, 10, 14, 9, 10, 6, 9, 0, 12, 11, 7, 13, 15, 1, 3, 14, 5, 2, 8, 4, 3, 15, 0, 6, 10, 1, 13, 8, 9, 4, 5, 11, 12, 7, 2, 14],
+    [2, 12, 4, 1, 7, 10, 11, 6, 8, 5, 3, 15, 13, 0, 14, 9, 14, 11, 2, 12, 4, 7, 13, 1, 5, 0, 15, 10, 3, 9, 8, 6, 4, 2, 1, 11, 10, 13, 7, 8, 15, 9, 12, 5, 6, 3, 0, 14, 11, 8, 12, 7, 1, 14, 2, 13, 6, 15, 0, 9, 10, 4, 5, 3],
+    [12, 1, 10, 15, 9, 2, 6, 8, 0, 13, 3, 4, 14, 7, 5, 11, 10, 15, 4, 2, 7, 12, 9, 5, 6, 1, 13, 14, 0, 11, 3, 8, 9, 14, 15, 5, 2, 8, 12, 3, 7, 0, 4, 10, 1, 13, 11, 6, 4, 3, 2, 12, 9, 5, 15, 10, 11, 14, 1, 7, 6, 0, 8, 13],
+    [4, 11, 2, 14, 15, 0, 8, 13, 3, 12, 9, 7, 5, 10, 6, 1, 13, 0, 11, 7, 4, 9, 1, 10, 14, 3, 5, 12, 2, 15, 8, 6, 1, 4, 11, 13, 12, 3, 7, 14, 10, 15, 6, 8, 0, 5, 9, 2, 6, 11, 13, 8, 1, 4, 10, 7, 9, 5, 0, 15, 14, 2, 3, 12],
+    [13, 2, 8, 4, 6, 15, 11, 1, 10, 9, 3, 14, 5, 0, 12, 7, 1, 15, 13, 8, 10, 3, 7, 4, 12, 5, 6, 11, 0, 14, 9, 2, 7, 11, 4, 1, 9, 12, 14, 2, 0, 6, 10, 13, 15, 3, 5, 8, 2, 1, 14, 7, 4, 10, 8, 13, 15, 12, 9, 0, 3, 5, 6, 11],
+];
+function bytesToBits(buf) {
+    const bits = [];
+    for (let i = 0; i < buf.length; i++) {
+        for (let b = 7; b >= 0; b--)
+            bits.push((buf[i] >> b) & 1);
+    }
+    return bits;
+}
+function bitsToBytes(bits) {
+    const out = Buffer.alloc(bits.length / 8);
+    for (let i = 0; i < out.length; i++) {
+        let byte = 0;
+        for (let b = 0; b < 8; b++)
+            byte = (byte << 1) | bits[i * 8 + b];
+        out[i] = byte;
+    }
+    return out;
+}
+function permute(bits, table) {
+    return table.map((pos) => bits[pos - 1]);
+}
+function keySchedule(key8) {
+    const keyBits = bytesToBits(key8);
+    const pc1 = permute(keyBits, PC1);
+    let c = pc1.slice(0, 28);
+    let d = pc1.slice(28, 56);
+    const subkeys = [];
+    for (let round = 0; round < 16; round++) {
+        const s = SHIFTS[round];
+        c = c.slice(s).concat(c.slice(0, s));
+        d = d.slice(s).concat(d.slice(0, s));
+        subkeys.push(permute(c.concat(d), PC2));
+    }
+    return subkeys;
+}
+function feistel(r, subkey) {
+    const expanded = permute(r, E);
+    const xored = expanded.map((bit, i) => bit ^ subkey[i]);
+    const out = [];
+    for (let box = 0; box < 8; box++) {
+        const chunk = xored.slice(box * 6, box * 6 + 6);
+        const row = (chunk[0] << 1) | chunk[5];
+        const col = (chunk[1] << 3) | (chunk[2] << 2) | (chunk[3] << 1) | chunk[4];
+        const val = SBOX[box][row * 16 + col];
+        for (let b = 3; b >= 0; b--)
+            out.push((val >> b) & 1);
+    }
+    return permute(out, P);
+}
+// Encrypt one 8-byte block with DES-ECB under an 8-byte key.
+export function desEncryptBlock(key8, block8) {
+    if (key8.length !== 8)
+        throw new Error(`des key must be 8 bytes, got ${key8.length}`);
+    if (block8.length !== 8)
+        throw new Error(`des block must be 8 bytes, got ${block8.length}`);
+    const subkeys = keySchedule(key8);
+    const bits = permute(bytesToBits(block8), IP);
+    let l = bits.slice(0, 32);
+    let r = bits.slice(32, 64);
+    for (let round = 0; round < 16; round++) {
+        const f = feistel(r, subkeys[round]);
+        const next = l.map((bit, i) => bit ^ f[i]);
+        l = r;
+        r = next;
+    }
+    return bitsToBytes(permute(r.concat(l), FP));
+}

package/dist/lib/computer/rfb-client.d.ts

@@ -0,0 +1,53 @@
+import type { ComputerClient, RPCResponse } from './computer-rpc.js';
+export declare function mirrorByte(b: number): number;
+export declare function vncAuthResponse(challenge: Buffer, password: string): Buffer;
+export declare function buildPixelFormat(): Buffer;
+export declare function encodeSetPixelFormat(pf: Buffer): Buffer;
+export declare function encodeSetEncodings(encodings: number[]): Buffer;
+export declare function encodeFbUpdateRequest(incremental: boolean, x: number, y: number, w: number, h: number): Buffer;
+export declare function encodePointerEvent(buttonMask: number, x: number, y: number): Buffer;
+export declare function encodeKeyEvent(down: boolean, keysym: number): Buffer;
+export declare function keysymForChar(ch: string): number;
+export declare function keysymForKeyName(name: string): number | null;
+export declare function parseKeyCombo(combo: string): {
+    modifiers: number[];
+    key: number;
+};
+export declare function encodePng(rgb: Buffer, width: number, height: number): Buffer;
+export interface ServerInit {
+    width: number;
+    height: number;
+    name: string;
+}
+export declare function scrollButtonsFor(dx: number, dy: number): {
+    vButton: number;
+    hButton: number;
+};
+export declare const MAX_RFB_STRING_LEN: number;
+export declare function parseVncEndpoint(raw: string | undefined): {
+    host: string;
+    port: number;
+} | null;
+export declare class RfbClient implements ComputerClient {
+    private host;
+    private port;
+    private password;
+    private sock;
+    private reader;
+    private ready;
+    private info;
+    private closed;
+    constructor(host: string, port: number, password: string);
+    private write;
+    private readLenString;
+    private handshake;
+    private teardown;
+    private withTimeout;
+    private captureScreen;
+    private sendClick;
+    private sendScroll;
+    private typeText;
+    private pressCombo;
+    call(method: string, params?: Record<string, unknown>): Promise<RPCResponse>;
+    close(): Promise<void>;
+}

package/dist/lib/computer/rfb-client.js

@@ -0,0 +1,562 @@
+// RFB (VNC) transport for `agents computer` — drive a remote GUI desktop over
+// the RFB protocol instead of a native Accessibility/UIA daemon.
+//
+// This is the third computer backend, sitting behind the same ComputerClient
+// interface as the macOS Unix-socket helper and the Windows TCP helper. It
+// speaks RFB 3.8 directly to an x11vnc/Xvnc server (e.g. a headless Linux
+// desktop, or an LXD container exposing x11vnc on the host's Tailscale IP), so
+// no per-box native helper install is needed — the display is driven over the
+// same VNC stream a human would watch.
+//
+// It is COORDINATE-BASED: RFB carries a framebuffer and pointer/key events, not
+// an accessibility tree. So it implements the observe verb `screenshot` and the
+// interact verbs `click`/`right-click`/`type`/`type-text`/`key`/`scroll`/`wait`;
+// the AX-tree verbs (`describe`/`get-text`/`ax-action`/element-id targeting) and
+// app lifecycle (`launch`/`apps` beyond the synthetic desktop target) have no RFB
+// equivalent and FAIL LOUD with a clear message rather than a silent no-op.
+//
+// Wire format note: unlike the JSON-RPC transports, there is no line-delimited
+// RPC on the wire here — `call(method, params)` translates a computer RPC verb
+// into RFB protocol messages and shapes the reply to match what the command
+// layer expects from the native helpers (e.g. screenshot -> { image_data, width,
+// height }).
+import { createConnection } from 'net';
+import { deflateSync, crc32 } from 'zlib';
+import { desEncryptBlock } from './des.js';
+// ---------------------------------------------------------------------------
+// Pure protocol helpers (exported for unit tests — no socket needed)
+// ---------------------------------------------------------------------------
+// VNC DES auth mangles the key by reversing the bit order of each byte. This is
+// a historical quirk of the reference implementation, not real DES.
+export function mirrorByte(b) {
+    let r = 0;
+    for (let i = 0; i < 8; i++)
+        r |= ((b >> i) & 1) << (7 - i);
+    return r & 0xff;
+}
+// Compute the 16-byte VNC-auth response: DES-ECB encrypt the server's 16-byte
+// challenge with the (bit-mirrored, 8-byte, null-padded) password as the key.
+export function vncAuthResponse(challenge, password) {
+    if (challenge.length !== 16)
+        throw new Error(`vnc challenge must be 16 bytes, got ${challenge.length}`);
+    const key = Buffer.alloc(8, 0);
+    const pw = Buffer.from(password, 'latin1');
+    for (let i = 0; i < 8 && i < pw.length; i++)
+        key[i] = mirrorByte(pw[i]);
+    // VNC encrypts the two 8-byte halves of the challenge as independent ECB
+    // blocks under the same key.
+    return Buffer.concat([
+        desEncryptBlock(key, challenge.subarray(0, 8)),
+        desEncryptBlock(key, challenge.subarray(8, 16)),
+    ]);
+}
+// 32bpp true-color, little-endian, R@16 G@8 B@0 — so a pixel's 4 wire bytes are
+// [B, G, R, x] and RGB extraction is buf[i+2], buf[i+1], buf[i].
+export function buildPixelFormat() {
+    const pf = Buffer.alloc(16, 0);
+    pf[0] = 32; // bits-per-pixel
+    pf[1] = 24; // depth
+    pf[2] = 0; // big-endian-flag (little-endian)
+    pf[3] = 1; // true-color-flag
+    pf.writeUInt16BE(255, 4); // red-max
+    pf.writeUInt16BE(255, 6); // green-max
+    pf.writeUInt16BE(255, 8); // blue-max
+    pf[10] = 16; // red-shift
+    pf[11] = 8; // green-shift
+    pf[12] = 0; // blue-shift
+    return pf;
+}
+export function encodeSetPixelFormat(pf) {
+    const msg = Buffer.alloc(4 + 16);
+    msg[0] = 0; // SetPixelFormat
+    pf.copy(msg, 4);
+    return msg;
+}
+export function encodeSetEncodings(encodings) {
+    const msg = Buffer.alloc(4 + encodings.length * 4);
+    msg[0] = 2; // SetEncodings
+    msg.writeUInt16BE(encodings.length, 2);
+    encodings.forEach((e, i) => msg.writeInt32BE(e, 4 + i * 4));
+    return msg;
+}
+export function encodeFbUpdateRequest(incremental, x, y, w, h) {
+    const msg = Buffer.alloc(10);
+    msg[0] = 3; // FramebufferUpdateRequest
+    msg[1] = incremental ? 1 : 0;
+    msg.writeUInt16BE(x, 2);
+    msg.writeUInt16BE(y, 4);
+    msg.writeUInt16BE(w, 6);
+    msg.writeUInt16BE(h, 8);
+    return msg;
+}
+export function encodePointerEvent(buttonMask, x, y) {
+    const msg = Buffer.alloc(6);
+    msg[0] = 5; // PointerEvent
+    msg[1] = buttonMask & 0xff;
+    msg.writeUInt16BE(Math.max(0, Math.round(x)), 2);
+    msg.writeUInt16BE(Math.max(0, Math.round(y)), 4);
+    return msg;
+}
+export function encodeKeyEvent(down, keysym) {
+    const msg = Buffer.alloc(8);
+    msg[0] = 4; // KeyEvent
+    msg[1] = down ? 1 : 0;
+    msg.writeUInt32BE(keysym >>> 0, 4);
+    return msg;
+}
+// X11 keysyms for the named keys an agent actually presses.
+const NAMED_KEYSYMS = {
+    return: 0xff0d, enter: 0xff0d, tab: 0xff09, escape: 0xff1b, esc: 0xff1b,
+    backspace: 0xff08, delete: 0xffff, del: 0xffff, space: 0x0020,
+    home: 0xff50, end: 0xff57, pageup: 0xff55, pagedown: 0xff56,
+    left: 0xff51, up: 0xff52, right: 0xff53, down: 0xff54, insert: 0xff63,
+    f1: 0xffbe, f2: 0xffbf, f3: 0xffc0, f4: 0xffc1, f5: 0xffc2, f6: 0xffc3,
+    f7: 0xffc4, f8: 0xffc5, f9: 0xffc6, f10: 0xffc7, f11: 0xffc8, f12: 0xffc9,
+};
+const MODIFIER_KEYSYMS = {
+    shift: 0xffe1, ctrl: 0xffe3, control: 0xffe3,
+    alt: 0xffe9, option: 0xffe9, opt: 0xffe9,
+    cmd: 0xffeb, command: 0xffeb, super: 0xffeb, meta: 0xffeb, win: 0xffeb,
+};
+// A single printable character -> its keysym. Latin-1 maps 1:1; anything else
+// uses the Unicode-plane keysym (0x01000000 + codepoint).
+export function keysymForChar(ch) {
+    const cp = ch.codePointAt(0) ?? 0;
+    if (cp >= 0x20 && cp <= 0xff)
+        return cp;
+    return 0x01000000 + cp;
+}
+export function keysymForKeyName(name) {
+    const k = name.trim().toLowerCase();
+    if (k in NAMED_KEYSYMS)
+        return NAMED_KEYSYMS[k];
+    if ([...name].length === 1)
+        return keysymForChar(name);
+    return null;
+}
+// Parse "ctrl+a" / "cmd+shift+t" / "Return" into modifier keysyms + a key keysym.
+export function parseKeyCombo(combo) {
+    const parts = combo.split('+').map((p) => p.trim()).filter(Boolean);
+    if (parts.length === 0)
+        throw new Error(`empty key combo: "${combo}"`);
+    const keyPart = parts[parts.length - 1];
+    const modParts = parts.slice(0, -1);
+    const modifiers = [];
+    for (const m of modParts) {
+        const ks = MODIFIER_KEYSYMS[m.toLowerCase()];
+        if (ks == null)
+            throw new Error(`unknown modifier "${m}" in "${combo}"`);
+        modifiers.push(ks);
+    }
+    const key = keysymForKeyName(keyPart);
+    if (key == null)
+        throw new Error(`unknown key "${keyPart}" in "${combo}"`);
+    return { modifiers, key };
+}
+// Minimal PNG encoder (color-type 2, RGB, 8-bit, no interlace). rgb is
+// width*height*3 bytes, row-major. Uses zlib for IDAT and zlib.crc32 for chunk
+// CRCs — no external dependency, deterministic, unit-testable.
+export function encodePng(rgb, width, height) {
+    const stride = width * 3;
+    // Prepend a per-scanline filter byte (0 = none).
+    const raw = Buffer.alloc(height * (stride + 1));
+    for (let y = 0; y < height; y++) {
+        raw[y * (stride + 1)] = 0;
+        rgb.copy(raw, y * (stride + 1) + 1, y * stride, y * stride + stride);
+    }
+    const idat = deflateSync(raw);
+    const chunk = (type, data) => {
+        const len = Buffer.alloc(4);
+        len.writeUInt32BE(data.length, 0);
+        const typeBuf = Buffer.from(type, 'latin1');
+        const crc = Buffer.alloc(4);
+        crc.writeUInt32BE(crc32(Buffer.concat([typeBuf, data])) >>> 0, 0);
+        return Buffer.concat([len, typeBuf, data, crc]);
+    };
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr[8] = 8; // bit depth
+    ihdr[9] = 2; // color type RGB
+    ihdr[10] = 0; // compression
+    ihdr[11] = 0; // filter
+    ihdr[12] = 0; // interlace
+    const sig = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    return Buffer.concat([sig, chunk('IHDR', ihdr), chunk('IDAT', idat), chunk('IEND', Buffer.alloc(0))]);
+}
+// Map scroll deltas to VNC wheel buttons. The `--dy` contract is "negative =
+// down" (honored by the macOS CGEvent and Windows MOUSEEVENTF_WHEEL backends by
+// passing dy straight through); `--dx` negative = left. RFB/X11 wheel buttons:
+// 4 = up, 5 = down, 6 = left, 7 = right. Pure + unit-tested so the direction
+// contract can't silently invert (it did, pre-review).
+export function scrollButtonsFor(dx, dy) {
+    return {
+        vButton: dy < 0 ? 5 : dy > 0 ? 4 : 0,
+        hButton: dx < 0 ? 6 : dx > 0 ? 7 : 0,
+    };
+}
+// Guard on any length-prefixed string the server frames (name, failure reason,
+// ServerCutText). A broken/hostile server sending a huge length would otherwise
+// make us wait indefinitely for bytes that never come; fail loud instead.
+export const MAX_RFB_STRING_LEN = 1 << 20; // 1 MiB
+// ---------------------------------------------------------------------------
+// Async socket reader — serve exact-length reads off a streamed connection.
+// ---------------------------------------------------------------------------
+class ByteReader {
+    buf = Buffer.alloc(0);
+    want = null;
+    error = null;
+    push(chunk) {
+        this.buf = Buffer.concat([this.buf, chunk]);
+        this.pump();
+    }
+    fail(err) {
+        this.error = err;
+        if (this.want) {
+            const w = this.want;
+            this.want = null;
+            // Reject via a sentinel-length read; the awaiting read() rejects below.
+            w.resolve(Buffer.alloc(0));
+        }
+    }
+    pump() {
+        if (this.want && this.buf.length >= this.want.n) {
+            const { n, resolve } = this.want;
+            this.want = null;
+            const out = this.buf.subarray(0, n);
+            this.buf = this.buf.subarray(n);
+            resolve(out);
+        }
+    }
+    read(n) {
+        if (this.error)
+            return Promise.reject(this.error);
+        return new Promise((resolve, reject) => {
+            this.want = {
+                n,
+                resolve: (b) => {
+                    if (this.error)
+                        reject(this.error);
+                    else
+                        resolve(b);
+                },
+            };
+            this.pump();
+        });
+    }
+}
+export function parseVncEndpoint(raw) {
+    if (!raw || raw.length === 0)
+        return null;
+    const idx = raw.lastIndexOf(':');
+    const host = idx >= 0 ? raw.slice(0, idx) : raw;
+    const portStr = idx >= 0 ? raw.slice(idx + 1) : '5901';
+    const port = Number(portStr);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535)
+        return null;
+    return { host: host || '127.0.0.1', port };
+}
+const RPC_TIMEOUT_MS = 30_000;
+// The one synthetic target the VNC backend exposes: the whole desktop. Lets the
+// screenshot command's list_apps->pickTarget->pid flow resolve without change
+// (`active: true` is what pickTarget's frontmost-app default selects).
+const DESKTOP_APP = { pid: 1, bundle_id: 'desktop', name: 'Desktop', active: true };
+export class RfbClient {
+    host;
+    port;
+    password;
+    sock = null;
+    reader = new ByteReader();
+    ready;
+    info = null;
+    closed = false;
+    constructor(host, port, password) {
+        this.host = host;
+        this.port = port;
+        this.password = password;
+        this.ready = this.handshake();
+    }
+    write(b) {
+        if (!this.sock)
+            throw new Error('vnc socket not connected');
+        this.sock.write(b);
+    }
+    // Read a U32-length-prefixed latin1 string, capped so a bogus length can't
+    // wedge us waiting for bytes that never arrive.
+    async readLenString(what) {
+        const len = (await this.reader.read(4)).readUInt32BE(0);
+        if (len > MAX_RFB_STRING_LEN)
+            throw new Error(`vnc ${what} length ${len} exceeds ${MAX_RFB_STRING_LEN}`);
+        return (await this.reader.read(len)).toString('latin1');
+    }
+    async handshake() {
+        await new Promise((resolve, reject) => {
+            const sock = createConnection({ host: this.host, port: this.port }, () => resolve());
+            sock.on('data', (c) => this.reader.push(c));
+            sock.on('error', (e) => {
+                this.closed = true;
+                this.reader.fail(e);
+                reject(e);
+            });
+            sock.on('close', () => {
+                this.closed = true;
+                this.reader.fail(new Error('vnc connection closed'));
+            });
+            this.sock = sock;
+        });
+        // 1. ProtocolVersion: server sends "RFB 003.00x\n", we answer 3.8.
+        const serverVersion = (await this.reader.read(12)).toString('latin1');
+        if (!serverVersion.startsWith('RFB '))
+            throw new Error(`not an RFB server (got "${serverVersion.trim()}")`);
+        this.write(Buffer.from('RFB 003.008\n', 'latin1'));
+        // 2. Security types (3.7+): count, then that many U8 types.
+        const nTypes = (await this.reader.read(1))[0];
+        if (nTypes === 0) {
+            const reason = await this.readLenString('failure reason');
+            throw new Error(`vnc server refused connection: ${reason}`);
+        }
+        const types = [...(await this.reader.read(nTypes))];
+        // Prefer VNC auth (2); accept None (1).
+        let chosen;
+        if (types.includes(2))
+            chosen = 2;
+        else if (types.includes(1))
+            chosen = 1;
+        else
+            throw new Error(`no supported vnc security type (server offered ${types.join(',')})`);
+        this.write(Buffer.from([chosen]));
+        if (chosen === 2) {
+            const challenge = await this.reader.read(16);
+            if (!this.password)
+                throw new Error('vnc server requires a password; set COMPUTER_HELPER_VNC_PASSWORD or --vnc-password');
+            const response = vncAuthResponse(challenge, this.password);
+            this.write(response);
+        }
+        // 3. SecurityResult (always present in 3.8).
+        const result = (await this.reader.read(4)).readUInt32BE(0);
+        if (result !== 0) {
+            // 3.8 sends a reason string on failure.
+            let reason = 'authentication failed';
+            try {
+                reason = await this.readLenString('auth failure reason');
+            }
+            catch { /* some servers just drop the connection instead */ }
+            throw new Error(`vnc auth failed: ${reason}`);
+        }
+        // 4. ClientInit (shared = 1) -> ServerInit.
+        this.write(Buffer.from([1]));
+        const head = await this.reader.read(4 + 16 + 4);
+        const width = head.readUInt16BE(0);
+        const height = head.readUInt16BE(2);
+        const nameLen = head.readUInt32BE(20);
+        if (nameLen > MAX_RFB_STRING_LEN)
+            throw new Error(`vnc desktop name length ${nameLen} exceeds ${MAX_RFB_STRING_LEN}`);
+        const name = (await this.reader.read(nameLen)).toString('latin1');
+        // Pin our pixel format + advertise only Raw so decode is simple + correct.
+        this.write(encodeSetPixelFormat(buildPixelFormat()));
+        this.write(encodeSetEncodings([0]));
+        this.info = { width, height, name };
+        return this.info;
+    }
+    // Tear the connection down for good: reject any pending read, destroy the
+    // socket, and mark closed so every later call fails loud. Idempotent.
+    teardown(message) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.reader.fail(new Error(message));
+        this.sock?.destroy();
+    }
+    // A timed-out RFB read cannot be recovered: the awaited bytes may still land
+    // later and would be misread as the NEXT request's reply, permanently
+    // desyncing the stream. So a timeout tears the whole connection down rather
+    // than leaving a pending read for the next call to silently overwrite.
+    withTimeout(p, label) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                const msg = `vnc ${label} timed out after ${RPC_TIMEOUT_MS}ms`;
+                this.teardown(msg);
+                reject(new Error(msg));
+            }, RPC_TIMEOUT_MS);
+            p.then((v) => { clearTimeout(timer); resolve(v); }, (e) => { clearTimeout(timer); reject(e); });
+        });
+    }
+    // Request the full framebuffer and assemble it into an RGB buffer, then PNG.
+    async captureScreen() {
+        const info = this.info;
+        this.write(encodeFbUpdateRequest(false, 0, 0, info.width, info.height));
+        const rgb = Buffer.alloc(info.width * info.height * 3);
+        // Read messages until a FramebufferUpdate covering the frame is assembled.
+        // We requested a single non-incremental full-frame update, so one
+        // FramebufferUpdate message carries all rectangles.
+        for (;;) {
+            const msgType = (await this.reader.read(1))[0];
+            if (msgType === 0) {
+                await this.reader.read(1); // padding
+                const nRects = (await this.reader.read(2)).readUInt16BE(0);
+                for (let r = 0; r < nRects; r++) {
+                    const rh = await this.reader.read(12);
+                    const rx = rh.readUInt16BE(0);
+                    const ry = rh.readUInt16BE(2);
+                    const rw = rh.readUInt16BE(4);
+                    const rHt = rh.readUInt16BE(6);
+                    const enc = rh.readInt32BE(8);
+                    if (enc !== 0)
+                        throw new Error(`vnc server used unsupported encoding ${enc} (only Raw was advertised)`);
+                    const pixels = await this.reader.read(rw * rHt * 4);
+                    for (let y = 0; y < rHt; y++) {
+                        for (let x = 0; x < rw; x++) {
+                            const src = (y * rw + x) * 4;
+                            const dstX = rx + x;
+                            const dstY = ry + y;
+                            if (dstX >= info.width || dstY >= info.height)
+                                continue;
+                            const dst = (dstY * info.width + dstX) * 3;
+                            rgb[dst] = pixels[src + 2]; // R
+                            rgb[dst + 1] = pixels[src + 1]; // G
+                            rgb[dst + 2] = pixels[src]; // B
+                        }
+                    }
+                }
+                break;
+            }
+            else if (msgType === 2) {
+                // Bell — no body.
+            }
+            else if (msgType === 3) {
+                // ServerCutText: 3 padding + U32 length + text (discarded).
+                await this.reader.read(3);
+                await this.readLenString('server cut text');
+            }
+            else {
+                throw new Error(`unexpected vnc server message type ${msgType}`);
+            }
+        }
+        return { image_data: encodePng(rgb, info.width, info.height).toString('base64'), width: info.width, height: info.height };
+    }
+    sendClick(x, y, button, count) {
+        const mask = 1 << (button - 1);
+        for (let i = 0; i < Math.max(1, count); i++) {
+            this.write(encodePointerEvent(0, x, y)); // move
+            this.write(encodePointerEvent(mask, x, y)); // press
+            this.write(encodePointerEvent(0, x, y)); // release
+        }
+    }
+    sendScroll(x, y, dx, dy, count) {
+        const notches = Math.max(1, count || Math.max(Math.abs(dx), Math.abs(dy)) || 1);
+        const { vButton, hButton } = scrollButtonsFor(dx, dy);
+        for (const button of [vButton, hButton]) {
+            if (!button)
+                continue;
+            const mask = 1 << (button - 1);
+            for (let i = 0; i < notches; i++) {
+                this.write(encodePointerEvent(mask, x, y));
+                this.write(encodePointerEvent(0, x, y));
+            }
+        }
+    }
+    typeText(text) {
+        for (const ch of text) {
+            const ks = keysymForChar(ch);
+            this.write(encodeKeyEvent(true, ks));
+            this.write(encodeKeyEvent(false, ks));
+        }
+    }
+    pressCombo(combo) {
+        const { modifiers, key } = parseKeyCombo(combo);
+        for (const m of modifiers)
+            this.write(encodeKeyEvent(true, m));
+        this.write(encodeKeyEvent(true, key));
+        this.write(encodeKeyEvent(false, key));
+        for (const m of [...modifiers].reverse())
+            this.write(encodeKeyEvent(false, m));
+    }
+    async call(method, params = {}) {
+        if (this.closed)
+            return { id: null, error: { code: 'vnc_closed', message: 'vnc connection closed' } };
+        try {
+            await this.withTimeout(this.ready, 'handshake');
+            const x = Number(params.x ?? 0);
+            const y = Number(params.y ?? 0);
+            switch (method) {
+                case 'list_apps':
+                    return { id: null, result: { apps: [DESKTOP_APP] } };
+                case 'screenshot': {
+                    if (params.list)
+                        return { id: null, result: { windows: [] } };
+                    const shot = await this.withTimeout(this.captureScreen(), 'screenshot');
+                    return { id: null, result: shot };
+                }
+                case 'click':
+                    this.sendClick(x, y, 1, Number(params.count ?? 1));
+                    return { id: null, result: { ok: true } };
+                case 'right_click':
+                    this.sendClick(x, y, 3, Number(params.count ?? 1));
+                    return { id: null, result: { ok: true } };
+                case 'scroll':
+                    this.sendScroll(x, y, Number(params.dx ?? 0), Number(params.dy ?? 0), Number(params.count ?? 0));
+                    return { id: null, result: { ok: true } };
+                case 'type': {
+                    if (params.x != null && params.y != null)
+                        this.sendClick(x, y, 1, 1);
+                    if (params.text != null)
+                        this.typeText(String(params.text));
+                    if (params.commit)
+                        this.pressCombo('Return');
+                    return { id: null, result: { ok: true } };
+                }
+                case 'type_text':
+                    if (params.text != null)
+                        this.typeText(String(params.text));
+                    if (params.commit)
+                        this.pressCombo('Return');
+                    return { id: null, result: { ok: true } };
+                case 'key':
+                    for (const combo of String(params.keys ?? '').split(',').map((s) => s.trim()).filter(Boolean)) {
+                        this.pressCombo(combo);
+                    }
+                    return { id: null, result: { ok: true } };
+                case 'focus_window':
+                case 'set_focus':
+                    // No window manager control over RFB; the desktop is the target.
+                    return { id: null, result: { ok: true } };
+                case 'wait': {
+                    const ms = Number(params.duration_ms ?? 0);
+                    if (ms > 0)
+                        await new Promise((r) => setTimeout(r, Math.min(ms, RPC_TIMEOUT_MS)));
+                    return { id: null, result: { ok: true } };
+                }
+                case 'describe':
+                case 'get_text':
+                case 'ax_action':
+                    return { id: null, error: { code: 'unsupported_over_vnc', message: `'${method}' needs an accessibility tree; the VNC backend is coordinate-based. Use screenshot + click/type by coordinate.` } };
+                case 'launch_app':
+                    return { id: null, error: { code: 'unsupported_over_vnc', message: 'launch is not available over VNC; open the app from the desktop UI with click/type.' } };
+                default:
+                    return { id: null, error: { code: 'unknown_method', message: `vnc backend has no method '${method}'` } };
+            }
+        }
+        catch (e) {
+            return { id: null, error: { code: 'vnc_error', message: e.message } };
+        }
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const sock = this.sock;
+        if (!sock)
+            return;
+        sock.end();
+        // Await real teardown (like TcpClient.close), but never hang on it.
+        await new Promise((resolve) => {
+            let done = false;
+            const fin = () => { if (!done) {
+                done = true;
+                resolve();
+            } };
+            sock.once('close', fin);
+            setTimeout(fin, 2000);
+        });
+    }
+}

package/dist/lib/daemon/auth-sync-service.js

@@ -32,6 +32,9 @@ export class AuthSyncService extends BasePeriodicService {
             ctx.log('WARN', `auth-sync: ${transport.skipped}`);
         if (transport.error)
             ctx.log('WARN', `auth-sync: shared-store transport: ${transport.error}`);
+        if (transport.untrackedBackedUp?.length) {
+            ctx.log('WARN', `auth-sync: backed up ${transport.untrackedBackedUp.length} untracked shared-store collision(s) to ${transport.untrackedBackupDir}: ${transport.untrackedBackedUp.join(', ')}`);
+        }
         if (!transport.success)
             return;
         const result = await syncReservedAuthBundle();

package/dist/lib/daemon/daemon.js

@@ -271,7 +271,7 @@ function acquireStartLock() {
  */
 const STOP_LOCK_WAIT_MS = 10_000;
 const STOP_LOCK_POLL_MS = 50;
-function acquireStopLock() {
+function acquireLifecycleLock() {
     const deadline = Date.now() + STOP_LOCK_WAIT_MS;
     for (;;) {
         const release = acquireStartLock();
@@ -481,14 +481,13 @@ export function isDaemonRunning() {
  * liveness check and the write.
  */
 export function claimDaemonInstance() {
-    const release = acquireStartLock();
-    // acquireStartLock() returns null only when another __daemon-run currently
-    // holds the O_EXCL lock — a dead holder's lock is reclaimed and retried inside
-    // acquireStartLock, so null means a *live* claimer is mid-claim. Bail rather
-    // than run the read-evict-write unlocked: otherwise two first-start processes
-    // could each see no pid file (before either writes one) and both claim,
-    // running the concurrent JobScheduler this guard exists to prevent. The live
-    // claimer we bailed for becomes the singleton, so last-wins still holds.
+    // A stop owns this same lock through teardown. Waiting here is load-bearing:
+    // returning false while stopDaemon() holds it lets this replacement exit 0,
+    // then the stop completes with no singleton left alive. The bounded lifecycle
+    // acquisition also preserves concurrent-start serialization: after the first
+    // claimer publishes its pid, the waiter takes the lock and performs the normal
+    // last-wins takeover rather than ever running the read-evict-write unlocked.
+    const release = acquireLifecycleLock();
     if (!release)
         return false;
     try {
@@ -2205,7 +2204,7 @@ export function findSurvivingStateDirDaemons(exclude) {
  * never reports success on an unverified stop.
  */
 export function stopDaemon() {
-    const releaseLock = acquireStopLock();
+    const releaseLock = acquireLifecycleLock();
     if (!releaseLock) {
         return {
             ok: false,

package/dist/lib/daemon/usage-sync-service.js

@@ -48,6 +48,9 @@ export class UsageSyncService extends BasePeriodicService {
             ctx.log('WARN', `usage-sync: ${transport.skipped}`);
         if (transport.error)
             ctx.log('WARN', `usage-sync: shared-store transport: ${transport.error}`);
+        if (transport.untrackedBackedUp?.length) {
+            ctx.log('WARN', `usage-sync: backed up ${transport.untrackedBackedUp.length} untracked shared-store collision(s) to ${transport.untrackedBackupDir}: ${transport.untrackedBackedUp.join(', ')}`);
+        }
         if (!transport.success)
             return;
         const consumed = consumeUsageSnapshotsFromSharedStore();

package/dist/lib/daemon-webhooks.js

@@ -18,6 +18,7 @@ import * as yaml from 'yaml';
 import { exec } from 'child_process';
 import { getDaemonConfigDir, getRuntimeStateDir } from './state.js';
 import { atomicWriteFileSync } from './fs-atomic.js';
+import { closeServerBounded } from './secrets/agent.js';
 import { readAndResolveBundleEnv } from './secrets/bundles.js';
 import { startWebhookServer, createFileDeliveryStore, waitForListening } from './triggers/webhook.js';
 import { buildFunnelUpCommand, FUNNEL_PORTS } from './funnel.js';
@@ -195,8 +196,13 @@ export async function startHostedWebhookReceivers(opts) {
                     log('WARN', `webhook ${webhook.source}:${webhook.event} dispatch failed after ack: ${err.message}`);
                 },
             });
+            const sockets = new Set();
+            server.on('connection', (socket) => {
+                sockets.add(socket);
+                socket.once('close', () => sockets.delete(socket));
+            });
             await waitForListening(server);
-            servers.push(server);
+            servers.push({ server, sockets });
             log('INFO', `webhook receiver bound on 127.0.0.1:${port} (bundle ${receiver.bundle})`);
             if (receiver.funnel)
                 reconcileFunnel(receiver.funnel.publicPort, port, log);
@@ -210,6 +216,13 @@ export async function startHostedWebhookReceivers(opts) {
     }
     return {
         count: servers.length,
-        close: () => Promise.all(servers.map((s) => new Promise((resolve) => s.close(() => resolve())))).then(() => undefined),
+        close: () => Promise.all(servers.map(async ({ server, sockets }) => {
+            // Stop accepting first, then force every persistent HTTP connection
+            // closed so keep-alive cannot hold daemon shutdown open indefinitely.
+            const closing = closeServerBounded(server);
+            for (const socket of sockets)
+                socket.destroy();
+            await closing;
+        })).then(() => undefined),
     };
 }

package/dist/lib/fleet-shared-repo-sync.d.ts

@@ -21,6 +21,18 @@ export interface FleetSharedRepoSyncResult {
     timedOut: boolean;
     skipped: string | null;
     error: string | null;
+    /**
+     * Untracked working-tree files that collided with origin and were dropped
+     * (byte-identical to origin) before rebasing. See clearCollidingUntracked.
+     */
+    untrackedCleared?: number;
+    /**
+     * Untracked working-tree files that collided with origin, differed from it,
+     * and were moved to untrackedBackupDir before rebasing.
+     */
+    untrackedBackedUp?: string[];
+    /** Directory the differing untracked collisions were moved to, if any. */
+    untrackedBackupDir?: string;
 }
 /** Run one real process asynchronously with a hard wall-clock/process-tree bound. */
 export declare function runBoundedProcess(command: string, args: string[], options: {

package/dist/lib/fleet-shared-repo-sync.js

@@ -161,6 +161,72 @@ function retainedAutostash(stashList, objectId) {
         ref: null,
     };
 }
+/**
+ * `git rebase` checks out its base (origin/<branch>) and aborts when an
+ * untracked working-tree file would be overwritten by a file that origin
+ * tracks. `--autostash` only sets aside *tracked* changes, so these untracked
+ * collisions wedge the rebase on every sync and the device silently falls
+ * hundreds of commits behind — the fleet-wide drift root cause (PHNX-3923).
+ *
+ * In this shared-state repo an untracked file that also exists on origin is a
+ * stale local snapshot: the canonical copy is on origin and every device
+ * republishes its own state (this device's own owned file is already committed
+ * before we get here, so it is tracked and never appears below). Drop the ones
+ * byte-identical to origin (lossless) and move any that differ into a backup
+ * dir beside the repo root — outside the repo's tracked tree, so the move
+ * cannot create a fresh collision — so nothing is silently destroyed. Then let
+ * the rebase check out origin's version. A file we cannot clear is left in
+ * place; the rebase may still abort, no worse than today and never losing data.
+ */
+async function clearCollidingUntracked(git, root, branch) {
+    const others = await git(['ls-files', '--others', '--exclude-standard', '-z']);
+    if (others.code !== 0)
+        return { error: others };
+    const relPaths = others.stdout.split('\0').filter(Boolean);
+    let cleared = 0;
+    const backedUp = [];
+    let backupDir = null;
+    for (const rel of relPaths) {
+        // rev-parse doubles as the "does origin track this path" test (non-zero =
+        // absent) — only paths origin tracks are overwritten by the rebase checkout.
+        const originHash = await git(['rev-parse', `origin/${branch}:${rel}`]);
+        if (originHash.code !== 0 || !originHash.stdout.trim())
+            continue;
+        const abs = path.join(root, rel);
+        // Byte-exact identity via git blob SHAs. Comparing UTF-8-decoded strings
+        // would collapse distinct invalid bytes to U+FFFD and could delete
+        // non-identical content. `--no-filters` hashes the raw on-disk bytes (no
+        // clean/autocrlf normalization), so `identical` is true only when the local
+        // bytes exactly equal origin's stored blob — never a filter-normalized
+        // near-match. A hash-object failure (unreadable / vanished under a
+        // concurrent writer) means "leave it in place".
+        const localHash = await git(['hash-object', '--no-filters', '--', abs]);
+        if (localHash.code !== 0 || !localHash.stdout.trim())
+            continue;
+        const identical = originHash.stdout.trim() === localHash.stdout.trim();
+        try {
+            if (identical) {
+                fs.rmSync(abs, { force: true });
+                cleared++;
+            }
+            else {
+                if (!backupDir) {
+                    // A sibling of the repo root: outside the tracked tree (so the move
+                    // cannot create a fresh collision) yet colocated for easy recovery.
+                    backupDir = path.join(`${root}-fleet-sync-backups`, String(Date.now()));
+                }
+                const dest = path.join(backupDir, rel);
+                fs.mkdirSync(path.dirname(dest), { recursive: true });
+                fs.renameSync(abs, dest);
+                backedUp.push(rel);
+            }
+        }
+        catch {
+            // Could not clear this collision; leave it in place.
+        }
+    }
+    return { cleared, backedUp, backupDir };
+}
 async function performFleetSharedRepoSync(root, device, timeoutMs) {
     if (!fs.existsSync(path.join(root, '.git'))) {
         return {
@@ -201,29 +267,57 @@ async function performFleetSharedRepoSync(root, device, timeoutMs) {
     }
     const ownedFile = fleetSharedStatePath(device, root);
     const relativeOwnedFile = path.relative(root, ownedFile).split(path.sep).join('/');
+    // The central `agents.yaml` is fleet-shared state too — `agents accounts label`
+    // writes version-scoped native account rows there (lib/state.ts writeMetaUnlocked),
+    // as a plain file write with no commit. Publishing only the per-device file and
+    // then `rebase --autostash`-ing over a dirty central file silently destroyed
+    // those labels: every box lost its account labels on its next daemon publish
+    // (PHNX-3887). Commit it alongside the device doc so the rebase carries the
+    // rows instead of stashing them, which is also what `accounts label --help`
+    // already promises ("labels live on the central account rows in agents.yaml,
+    // which repo push/pull already syncs fleet-wide").
+    const centralFile = path.join(root, 'agents.yaml');
+    const publishPaths = [relativeOwnedFile];
+    if (fs.existsSync(centralFile))
+        publishPaths.push('agents.yaml');
+    const existingPaths = publishPaths.filter(rel => fs.existsSync(path.join(root, rel)));
     let committed = false;
-    if (fs.existsSync(ownedFile)) {
-        const status = await git(['status', '--porcelain=v1', '--', relativeOwnedFile]);
+    if (existingPaths.length > 0) {
+        const status = await git(['status', '--porcelain=v1', '--', ...existingPaths]);
         if (status.code !== 0)
             return failure('git status', status);
         if (status.stdout.trim()) {
-            const add = await git(['add', '--', relativeOwnedFile]);
+            const add = await git(['add', '--', ...existingPaths]);
             if (add.code !== 0)
                 return failure('git add', add);
             const commit = await git([
                 '-c', 'commit.gpgsign=false',
                 'commit', '--no-verify', '-m', `chore(devices): publish ${device} daemon state`,
-                '--', relativeOwnedFile,
+                '--', ...existingPaths,
             ]);
             if (commit.code !== 0)
                 return failure('git commit', commit);
             committed = true;
         }
     }
+    let untrackedCleared = 0;
+    const untrackedBackedUp = [];
+    let untrackedBackupDir;
     for (let attempt = 1; attempt <= FLEET_SHARED_REPO_PUSH_ATTEMPTS; attempt++) {
         const fetch = await git(['fetch', 'origin']);
         if (fetch.code !== 0)
             return { ...failure('git fetch', fetch), committed };
+        // Untracked files that origin tracks would abort the rebase's checkout
+        // (autostash only covers tracked changes). Clear them first — this is the
+        // fleet-drift root cause (PHNX-3923).
+        const reconcile = await clearCollidingUntracked(git, root, branch);
+        if ('error' in reconcile) {
+            return { ...failure('git ls-files --others', reconcile.error), committed };
+        }
+        untrackedCleared += reconcile.cleared;
+        untrackedBackedUp.push(...reconcile.backedUp);
+        if (reconcile.backupDir)
+            untrackedBackupDir = reconcile.backupDir;
         // Keep enough of the same wall-clock bound available to remove a botched
         // autostash pop from the operator's live checkout before returning.
         const rebase = await git(['rebase', '--autostash', `origin/${branch}`], FLEET_SHARED_REPO_REBASE_CLEANUP_RESERVE_MS);
@@ -283,6 +377,9 @@ async function performFleetSharedRepoSync(root, device, timeoutMs) {
                 timedOut: false,
                 skipped: null,
                 error: null,
+                untrackedCleared,
+                untrackedBackedUp,
+                untrackedBackupDir,
             };
         }
         if (attempt === FLEET_SHARED_REPO_PUSH_ATTEMPTS || !isPushRace(push)) {

package/dist/lib/session/remote/remote-list.d.ts

@@ -124,6 +124,8 @@ export declare function resolvePeerTarget(machine: string): Promise<{
  * error, timeout, version-skewed peer with no `--json` preview envelope.
  */
 export declare function fetchPeerPreviewDigest(sessionId: string, machine: string, timeoutMs?: number): Promise<unknown | undefined>;
+/** Parse the JSON envelope returned by `sessions preview --json`. */
+export declare function parsePeerPreviewDigest(parsed: unknown): unknown | undefined;
 /**
  * Run `agents <args>` ON a peer over SSH, attached to this terminal (inherited
  * stdio). `args` is the full arg vector after the binary — callers pass e.g.

package/dist/lib/session/remote/remote-list.js

@@ -554,6 +554,10 @@ export async function fetchPeerPreviewDigest(sessionId, machine, timeoutMs = PEE
     catch {
         return undefined;
     }
+    return parsePeerPreviewDigest(parsed);
+}
+/** Parse the JSON envelope returned by `sessions preview --json`. */
+export function parsePeerPreviewDigest(parsed) {
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
         return undefined;
     const preview = parsed.preview;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.74",
+  "version": "1.22.75",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",