@phnx-labs/agents-cli 1.20.27 → 1.20.29

package/dist/lib/browser/drivers/ssh.js

@@ -4,11 +4,10 @@ import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from '../cdp.j
 import { getPortOccupant } from '../chrome.js';
 import { parseEndpointUrl } from '../profiles.js';
 import { writeProfileRuntime, clearProfileRuntime } from '../runtime-state.js';
-export function shellQuote(s) {
-    if (/^[A-Za-z0-9_./:=@%+-]+$/.test(s))
-        return s;
-    return "'" + s.replace(/'/g, "'\\''") + "'";
-}
+// shellQuote lives in the shared ssh-exec helper (single choke point); re-export
+// so existing importers of `shellQuote` from this module keep working.
+import { shellQuote } from '../../ssh-exec.js';
+export { shellQuote };
 export async function connectSSH(endpoint, profile) {
     const url = new URL(endpoint);
     if (url.protocol !== 'ssh:') {
@@ -24,6 +23,11 @@ export async function connectSSH(endpoint, profile) {
     }
     const host = parsed.host;
     const remotePort = parsed.port;
+    // `&os=windows` switches the remote-command dialect (cmd.exe launch via
+    // `start`, taskkill teardown). Anything else — including absent — is posix.
+    // The query param is the single source of truth so the driver never has to
+    // be threaded a separate per-profile field.
+    const remoteOs = (url.searchParams.get('os') || '').toLowerCase() === 'windows' ? 'windows' : 'posix';
     // Bind the tunnel to the SAME local port the user configured. Using an
     // allocated port instead made `status` print confusing rows like
     // `port 9200 (configured 10005)` and made it impossible to predict which
@@ -40,7 +44,7 @@ export async function connectSSH(endpoint, profile) {
             `Either kill that process (\`kill ${occupant.pid}\`) or change the profile's port.`);
     }
     try {
-        await ensureRemoteBrowser(user, host, profile.browser, remotePort, profile.binary);
+        await ensureRemoteBrowser(user, host, profile.browser, remotePort, remoteOs, profile.binary);
     }
     catch {
         // Browser may already be running, continue
@@ -156,28 +160,100 @@ function tryConnect(port) {
         socket.on('error', reject);
     });
 }
-async function ensureRemoteBrowser(user, host, browserType, port, customBinary) {
-    const browserPaths = {
-        chrome: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-        comet: '/Applications/Comet.app/Contents/MacOS/Comet',
-        chromium: '/Applications/Chromium.app/Contents/MacOS/Chromium',
-        brave: '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
-        edge: '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
-    };
-    let browserPath;
+// macOS .app launchers — the historical POSIX table.
+const POSIX_BROWSER_PATHS = {
+    chrome: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    comet: '/Applications/Comet.app/Contents/MacOS/Comet',
+    chromium: '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    brave: '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+    edge: '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+};
+// Windows App Paths registry keys per browser. CreateProcess (used by WMI
+// Win32_Process.Create) does not honor App Paths the way ShellExecute/`start`
+// does, so the launch script resolves the real `.exe` path from this registry
+// key at runtime — covering both Program Files and Program Files (x86)
+// installs without hardcoding (or guessing) the location.
+const WIN_BROWSER_APPPATH = {
+    chrome: 'chrome.exe',
+    chromium: 'chrome.exe',
+    brave: 'brave.exe',
+    edge: 'msedge.exe',
+};
+/** Single-quote a string for embedding inside a PowerShell literal. */
+function psSingleQuote(s) {
+    return "'" + s.replace(/'/g, "''") + "'";
+}
+/**
+ * Wrap a PowerShell script as a `-EncodedCommand` invocation. Base64 of the
+ * UTF-16LE bytes is a single quote-free token, so it rides through Node spawn
+ * → Windows sshd → cmd.exe with zero escaping hazards (hand-quoted
+ * `powershell -Command "…"` is fragile the moment a path or URL is involved).
+ */
+export function encodePowerShell(script) {
+    const b64 = Buffer.from(script, 'utf16le').toString('base64');
+    return `powershell -NoProfile -EncodedCommand ${b64}`;
+}
+/**
+ * The PowerShell that launches the browser on a Windows remote. Two hard
+ * requirements shaped this:
+ *   1. The browser must OUTLIVE the ssh session. Windows OpenSSH terminates
+ *      the session's job tree on disconnect, which reaps both `start /B` and
+ *      `Start-Process` children (verified against a real box). WMI
+ *      `Win32_Process.Create` spawns under the WMI provider service instead,
+ *      so the process survives after we drop the ssh connection and reconnect
+ *      over the CDP tunnel.
+ *   2. A distinct `--user-data-dir` so a fresh instance bound to the debugging
+ *      port comes up even when the user already has Edge open.
+ * CreateProcess ignores App Paths, so we resolve the real `.exe` from the
+ * registry at runtime rather than relying on a bare `msedge` name.
+ */
+export function buildWindowsLaunchScript(browserType, port, customBinary) {
+    let exeExpr;
     if (customBinary) {
-        browserPath = customBinary;
+        exeExpr = psSingleQuote(customBinary);
     }
     else if (browserType === 'custom') {
         throw new Error('browser: custom requires a binary path in the profile');
     }
     else {
-        browserPath = browserPaths[browserType];
-        if (!browserPath) {
-            throw new Error(`Unknown browser type: ${browserType}`);
+        const exeKey = WIN_BROWSER_APPPATH[browserType];
+        if (!exeKey)
+            throw new Error(`Unknown browser type for windows remote: ${browserType}`);
+        exeExpr =
+            `(Get-ItemProperty 'HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\${exeKey}').'(default)'`;
+    }
+    // Keep the `--remote-allow-origins=http://127.0.0.1:${port}` literal in
+    // source — a test asserts CDP is never opened to `*`.
+    return [
+        `$exe = ${exeExpr}`,
+        `$cl = '"' + $exe + '" --remote-debugging-port=${port}` +
+            ` --remote-allow-origins=http://127.0.0.1:${port}` +
+            ` --disable-background-timer-throttling --user-data-dir="' + $env:TEMP + '\\agents-browser-${port}"'`,
+        `Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{ CommandLine = $cl } | Out-Null`,
+    ].join('; ');
+}
+/** The PowerShell that kills whatever holds the CDP port on a Windows remote. */
+export function buildWindowsKillScript(port) {
+    return (`Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue ` +
+        `| ForEach-Object { Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue }`);
+}
+/**
+ * Build the remote command that launches the browser detached with a CDP port.
+ * POSIX backgrounds the `.app` binary with `… &`; Windows resolves the exe and
+ * spawns it via WMI (encoded PowerShell) so it survives the ssh session.
+ */
+export function buildLaunchCmd(remoteOs, browserType, port, customBinary) {
+    if (remoteOs === 'windows') {
+        return encodePowerShell(buildWindowsLaunchScript(browserType, port, customBinary));
+    }
+    const browserPath = customBinary ?? POSIX_BROWSER_PATHS[browserType];
+    if (!browserPath) {
+        if (browserType === 'custom') {
+            throw new Error('browser: custom requires a binary path in the profile');
         }
+        throw new Error(`Unknown browser type for posix remote: ${browserType}`);
     }
-    const remoteCmd = [
+    return [
         shellQuote(browserPath),
         `--remote-debugging-port=${port}`,
         shellQuote(`--remote-allow-origins=http://127.0.0.1:${port}`),
@@ -185,6 +261,20 @@ async function ensureRemoteBrowser(user, host, browserType, port, customBinary)
         `--user-data-dir=/tmp/agents-browser-${port}`,
         '</dev/null >/dev/null 2>&1 &',
     ].join(' ');
+}
+/**
+ * Build the remote command that kills whatever holds the CDP port.
+ * POSIX uses `lsof`+`kill`; Windows uses encoded PowerShell
+ * (Get-NetTCPConnection → Stop-Process).
+ */
+export function buildKillCmd(remoteOs, port) {
+    if (remoteOs === 'windows') {
+        return encodePowerShell(buildWindowsKillScript(port));
+    }
+    return `pids=$(lsof -ti ${shellQuote(`:${port}`)} 2>/dev/null); [ -z "$pids" ] || kill -9 $pids 2>/dev/null || true`;
+}
+async function ensureRemoteBrowser(user, host, browserType, port, remoteOs, customBinary) {
+    const remoteCmd = buildLaunchCmd(remoteOs, browserType, port, customBinary);
     return new Promise((resolve, reject) => {
         const child = spawn('ssh', [
             `${user}@${host}`,
@@ -200,12 +290,11 @@ async function ensureRemoteBrowser(user, host, browserType, port, customBinary)
         }, 2000);
     });
 }
-export async function restartRemoteBrowser(user, host, browserType, port, customBinary) {
+export async function restartRemoteBrowser(user, host, browserType, port, remoteOs, customBinary) {
     // Kill any process using the remote debugging port
-    const killCmd = `pids=$(lsof -ti ${shellQuote(`:${port}`)} 2>/dev/null); [ -z "$pids" ] || kill -9 $pids 2>/dev/null || true`;
-    await runSSHCommand(user, host, killCmd);
+    await runSSHCommand(user, host, buildKillCmd(remoteOs, port));
     await sleep(500);
-    await ensureRemoteBrowser(user, host, browserType, port, customBinary);
+    await ensureRemoteBrowser(user, host, browserType, port, remoteOs, customBinary);
     await sleep(1500);
 }
 function runSSHCommand(user, host, cmd) {

package/dist/lib/browser/profiles.js

@@ -194,6 +194,27 @@ function hasSshEndpoint(endpoints) {
         }
     });
 }
+/**
+ * True when any endpoint is an `ssh://…?os=windows` target — i.e. the browser
+ * lives on a remote Windows host. Such a profile's binary (`msedge.exe`) will
+ * never exist on this Mac, so create-time local-binary validation must be
+ * skipped; the binary is resolved on the remote at connect time instead.
+ */
+function hasRemoteWindowsEndpoint(endpoints) {
+    const targets = Array.isArray(endpoints)
+        ? endpoints
+        : Object.values(endpoints).map((preset) => preset.target);
+    return targets.some((target) => {
+        try {
+            const url = new URL(target);
+            return (url.protocol === 'ssh:' &&
+                (url.searchParams.get('os') || '').toLowerCase() === 'windows');
+        }
+        catch {
+            return false;
+        }
+    });
+}
 export async function createProfile(profile) {
     const meta = readMeta();
     if (meta.browser?.[profile.name]) {
@@ -220,7 +241,13 @@ export async function createProfile(profile) {
     // error ("Comet not installed at /Applications/Comet.app") rather than
     // deferring the failure to the first task. `findBrowserPath` short-circuits
     // for browser=custom without a binary by throwing — same outcome.
-    findBrowserPath(profile.browser, profile.binary);
+    //
+    // Skip for remote-Windows profiles: the browser is `msedge.exe` on the
+    // remote box, never on this Mac, so a local lookup would always (wrongly)
+    // fail. The remote launcher resolves it at connect time via App Paths.
+    if (!hasRemoteWindowsEndpoint(profile.endpoints)) {
+        findBrowserPath(profile.browser, profile.binary);
+    }
     meta.browser = meta.browser ?? {};
     meta.browser[profile.name] = profileToConfig(profile);
     writeMeta(meta);

package/dist/lib/browser/runtime-state.js

@@ -248,20 +248,40 @@ export function reapOrphanedProcesses() {
     return { reaped, details };
 }
 function matchesCommand(pid, expectedCommand) {
+    const out = liveProcessCommand(pid);
+    if (!out)
+        return false;
+    // Match on the basename only — `/Applications/Comet.app/Contents/MacOS/Comet`
+    // vs the recorded `Comet`, vs `Google\ Chrome`, vs Windows `chrome.exe`.
+    // Case-insensitive.
+    const live = path.basename(out).toLowerCase();
+    const want = path.basename(expectedCommand).toLowerCase();
+    return live === want || live.startsWith(want) || want.startsWith(live);
+}
+/**
+ * The executable/image name the live `pid` is running, or null if it can't be
+ * determined. The process-listing API differs per OS: Windows has no `ps`, so
+ * we query `tasklist` (CSV image name in column 1); POSIX uses `ps -o comm=`.
+ */
+function liveProcessCommand(pid) {
     try {
+        if (process.platform === 'win32') {
+            const out = execFileSync('tasklist', ['/FI', `PID eq ${pid}`, '/NH', '/FO', 'CSV'], {
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim();
+            // Rows look like: "node.exe","1234","Console","1","12,345 K"
+            // A no-match prints an "INFO: No tasks..." line that won't match the regex.
+            const m = out.match(/^"([^"]+)"/);
+            return m ? m[1] : null;
+        }
         const out = execFileSync('ps', ['-p', String(pid), '-o', 'comm='], {
             encoding: 'utf-8',
             stdio: ['ignore', 'pipe', 'ignore'],
         }).trim();
-        if (!out)
-            return false;
-        // Match on the basename only — `/Applications/Comet.app/Contents/MacOS/Comet`
-        // vs the recorded `Comet`, vs `Google\ Chrome`. Case-insensitive.
-        const live = path.basename(out).toLowerCase();
-        const want = path.basename(expectedCommand).toLowerCase();
-        return live === want || live.startsWith(want) || want.startsWith(live);
+        return out || null;
     }
     catch {
-        return false;
+        return null;
     }
 }

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

@@ -7,7 +7,16 @@ export type BrowserType = 'chrome' | 'comet' | 'chromium' | 'brave' | 'edge' | '
  * Per-endpoint overrides take precedence over profile-level fields.
  */
 export interface EndpointPreset {
-    /** CDP URL — `cdp://host:port` or `ssh://host?port=N` */
+    /**
+     * CDP URL — `cdp://host:port` or `ssh://host?port=N`.
+     *
+     * For an SSH target whose remote is Windows, append `&os=windows` (e.g.
+     * `ssh://user@host?port=9222&os=windows`). The driver then speaks the
+     * Windows dialect (launch via WMI Win32_Process.Create so the browser
+     * survives the ssh session, teardown via Get-NetTCPConnection/Stop-Process)
+     * instead of the POSIX default. The query param is the single source of
+     * truth for remote-OS selection.
+     */
     target: string;
     /** Override the profile-level binary (e.g. a remote host has no local binary). */
     binary?: string;

package/dist/lib/cli-resources.js

@@ -116,7 +116,16 @@ export function parseCheckSpec(raw, defaultName) {
  * decide whether to surface or swallow the error per file.
  */
 export function parseCliManifest(contents, opts) {
-    const raw = yaml.parse(contents);
+    // Tolerant parse. A manifest may legitimately carry OS-specific strings — a
+    // Windows path like `C:\Users\...` embedded in a double-quoted YAML scalar
+    // trips YAML's escape rules (`\U` is an invalid escape) and makes the strict
+    // `yaml.parse` throw a parser error. That throw must NOT pre-empt the
+    // security validation below: the per-field allowlist checks (unsafe tokens,
+    // non-https URLs, path traversal) are the authoritative gate on a hostile
+    // manifest. parseDocument collects those escape errors instead of throwing
+    // and still recovers the scalar values, so the dangerous content reaches
+    // assertSafeCheckToken / assertNpmPackage and is rejected on its merits.
+    const raw = yaml.parseDocument(contents, { strict: false }).toJS();
     if (!raw || typeof raw !== 'object') {
         throw new Error('manifest must be a YAML object');
     }

package/dist/lib/devices/connect.d.ts

@@ -0,0 +1,34 @@
+import { type DeviceProfile } from './registry.js';
+/** Env var the askpass shim reads to know which bundle holds the password. */
+export declare const ASKPASS_BUNDLE_ENV = "AGENTS_SSH_BUNDLE";
+/** Env var the askpass shim reads to know which key in the bundle is the password. */
+export declare const ASKPASS_KEY_ENV = "AGENTS_SSH_KEY";
+/**
+ * Build the `user@host` (or bare `host`) ssh target for a device and validate
+ * it against the shared injection guard. Throws if the device has no address.
+ */
+export declare function sshTargetFor(device: DeviceProfile): string;
+/**
+ * Wrap a remote command for the device's shell. Windows devices speak
+ * PowerShell, so a bare command is run through `powershell -NoProfile
+ * -Command`; POSIX devices get the command verbatim (the remote login shell
+ * parses it). Returns undefined when no command was given (interactive login).
+ */
+export declare function wrapRemoteCommand(device: DeviceProfile, cmd: string[]): string | undefined;
+/**
+ * Build the argv (after the `ssh` program name) and the environment overlay
+ * for connecting to a device. For password auth this points `SSH_ASKPASS` at
+ * the shim and disables pubkey + the host's interactive password prompt so the
+ * shim is the only auth path. Pure (no spawn) so it is unit-testable.
+ */
+export declare function buildSshInvocation(device: DeviceProfile, cmd: string[], askpassShimPath: string): {
+    args: string[];
+    env: Record<string, string>;
+};
+/**
+ * Write (idempotently) the askpass shim — a tiny executable that re-invokes
+ * this CLI as `agents ssh __askpass`. ssh execs `SSH_ASKPASS` with no usable
+ * args, so the shim carries no secret itself; it only bridges ssh's askpass
+ * protocol back into the CLI, which then resolves the bundle.
+ */
+export declare function writeAskpassShim(): string;

package/dist/lib/devices/connect.js

@@ -0,0 +1,101 @@
+/**
+ * Connection layer for `agents ssh` — turn a device profile into a real ssh
+ * invocation, with platform-aware command wrapping and password-from-bundle
+ * auth.
+ *
+ * Auth is genuinely two first-class, non-interactive methods:
+ *  - `key`      — the system ssh agent / on-disk keys (BatchMode-friendly).
+ *  - `password` — the secret is pulled from a Keychain-backed secrets bundle
+ *                 by an askpass shim. The wrapper points `SSH_ASKPASS` at the
+ *                 shim and forces its use; ssh calls the shim, the shim calls
+ *                 back into `agents ssh __askpass`, which resolves the bundle
+ *                 via the existing `readAndResolveBundleEnv` path and prints
+ *                 the password to ssh. The password never touches argv or an
+ *                 expect buffer.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { assertValidSshTarget, shellQuote } from '../ssh-exec.js';
+import { getCacheDir } from '../state.js';
+import { hostNameFor } from './ssh-config.js';
+/** Env var the askpass shim reads to know which bundle holds the password. */
+export const ASKPASS_BUNDLE_ENV = 'AGENTS_SSH_BUNDLE';
+/** Env var the askpass shim reads to know which key in the bundle is the password. */
+export const ASKPASS_KEY_ENV = 'AGENTS_SSH_KEY';
+/**
+ * Build the `user@host` (or bare `host`) ssh target for a device and validate
+ * it against the shared injection guard. Throws if the device has no address.
+ */
+export function sshTargetFor(device) {
+    const host = hostNameFor(device);
+    if (!host) {
+        throw new Error(`Device '${device.name}' has no address (dnsName/ip). Run \`agents devices sync\` or \`agents devices add\`.`);
+    }
+    const target = device.user ? `${device.user}@${host}` : host;
+    assertValidSshTarget(target);
+    return target;
+}
+/**
+ * Wrap a remote command for the device's shell. Windows devices speak
+ * PowerShell, so a bare command is run through `powershell -NoProfile
+ * -Command`; POSIX devices get the command verbatim (the remote login shell
+ * parses it). Returns undefined when no command was given (interactive login).
+ */
+export function wrapRemoteCommand(device, cmd) {
+    if (cmd.length === 0)
+        return undefined;
+    const joined = cmd.join(' ');
+    if (device.shell === 'powershell') {
+        return `powershell -NoProfile -Command ${shellQuote(joined)}`;
+    }
+    return joined;
+}
+/**
+ * Build the argv (after the `ssh` program name) and the environment overlay
+ * for connecting to a device. For password auth this points `SSH_ASKPASS` at
+ * the shim and disables pubkey + the host's interactive password prompt so the
+ * shim is the only auth path. Pure (no spawn) so it is unit-testable.
+ */
+export function buildSshInvocation(device, cmd, askpassShimPath) {
+    const target = sshTargetFor(device);
+    const remote = wrapRemoteCommand(device, cmd);
+    const env = {};
+    const args = ['-o', 'StrictHostKeyChecking=accept-new', '-o', 'ConnectTimeout=10'];
+    if (device.auth.method === 'password') {
+        if (!device.auth.bundle) {
+            throw new Error(`Device '${device.name}' uses password auth but has no secrets bundle. Set one with \`agents devices set ${device.name} --bundle <name>\`.`);
+        }
+        env.SSH_ASKPASS = askpassShimPath;
+        env.SSH_ASKPASS_REQUIRE = 'force';
+        env[ASKPASS_BUNDLE_ENV] = device.auth.bundle;
+        env[ASKPASS_KEY_ENV] = device.auth.bundleKey ?? 'password';
+        args.push('-o', 'PreferredAuthentications=password', '-o', 'PubkeyAuthentication=no', '-o', 'NumberOfPasswordPrompts=1');
+    }
+    else {
+        args.push('-o', 'BatchMode=yes');
+    }
+    // An interactive login (no remote command) needs a real tty.
+    if (!remote)
+        args.push('-tt');
+    args.push(target);
+    if (remote)
+        args.push(remote);
+    return { args, env };
+}
+/**
+ * Write (idempotently) the askpass shim — a tiny executable that re-invokes
+ * this CLI as `agents ssh __askpass`. ssh execs `SSH_ASKPASS` with no usable
+ * args, so the shim carries no secret itself; it only bridges ssh's askpass
+ * protocol back into the CLI, which then resolves the bundle.
+ */
+export function writeAskpassShim() {
+    const dir = path.join(getCacheDir(), 'devices');
+    fs.mkdirSync(dir, { recursive: true });
+    const shimPath = path.join(dir, 'askpass.sh');
+    // process.execPath = the node/bun binary; argv[1] = this CLI's entry script.
+    const node = process.execPath;
+    const entry = process.argv[1] ?? '';
+    const body = `#!/bin/sh\n# Generated by agents-cli — bridges ssh SSH_ASKPASS back into the CLI.\nexec ${shellQuote(node)} ${shellQuote(entry)} ssh __askpass\n`;
+    fs.writeFileSync(shimPath, body, { mode: 0o700 });
+    return shimPath;
+}

package/dist/lib/devices/registry.d.ts

@@ -0,0 +1,78 @@
+/** Operating-system family of a device, used to pick the remote shell. */
+export type DevicePlatform = 'windows' | 'linux' | 'macos' | 'unknown';
+/** Remote shell dialect derived from the platform. */
+export type DeviceShell = 'powershell' | 'posix';
+/** How `agents ssh` authenticates to a device. Both are first-class, fully
+ * non-interactive: `key` uses the ssh agent / on-disk keys, `password` pulls
+ * the secret from a Keychain-backed secrets bundle via an askpass shim. */
+export type DeviceAuthMethod = 'key' | 'password';
+/** How to reach a device on the network. */
+export interface DeviceAddress {
+    /** Where the address came from: a Tailscale node, or a manual entry. */
+    via: 'tailscale' | 'manual';
+    /** Fully-qualified DNS name (Tailscale MagicDNS), without a trailing dot. */
+    dnsName?: string;
+    /** Raw IP address (IPv4 preferred). */
+    ip?: string;
+}
+/** Authentication settings for a device. */
+export interface DeviceAuth {
+    method: DeviceAuthMethod;
+    /** Secrets bundle holding the password (when method === 'password'). */
+    bundle?: string;
+    /** Key within the bundle whose value is the password. Defaults to 'password'. */
+    bundleKey?: string;
+}
+/** Last-known Tailscale reachability snapshot for a device. */
+export interface DeviceTailscale {
+    online: boolean;
+    /** True when the last handshake was a direct (non-relayed) connection. */
+    direct: boolean;
+    /** DERP relay region code (e.g. 'sfo'); empty when direct. */
+    relay?: string;
+    lastSeen?: string;
+}
+/** A single registered device. */
+export interface DeviceProfile {
+    name: string;
+    platform: DevicePlatform;
+    shell: DeviceShell;
+    user?: string;
+    address: DeviceAddress;
+    auth: DeviceAuth;
+    tailscale?: DeviceTailscale;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Map of device name to profile. */
+export type DeviceRegistry = Record<string, DeviceProfile>;
+/** Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.). */
+export declare function assertValidDeviceName(name: string): void;
+/** Map a Tailscale `OS` field to our platform enum. */
+export declare function platformFromOs(os: string | undefined): DevicePlatform;
+/** The remote shell a platform speaks. */
+export declare function shellForPlatform(platform: DevicePlatform): DeviceShell;
+/**
+ * Load all devices from the registry file. Returns an empty object only when
+ * the file does not exist. A malformed file is a hard error — silently
+ * returning {} would let the next write wipe the user's device list.
+ */
+export declare function loadDevices(): Promise<DeviceRegistry>;
+/** Get a single device profile, or null if it is not registered. */
+export declare function getDevice(name: string): Promise<DeviceProfile | null>;
+/** Fields a caller may supply when creating or updating a device. */
+export interface DeviceInput {
+    platform?: DevicePlatform;
+    user?: string;
+    address?: DeviceAddress;
+    auth?: DeviceAuth;
+    tailscale?: DeviceTailscale;
+}
+/**
+ * Create the device if absent, otherwise merge the supplied fields into the
+ * existing profile. `shell` is always re-derived from the (possibly new)
+ * platform so the two can never drift. Returns the resulting profile.
+ */
+export declare function upsertDevice(name: string, input: DeviceInput): Promise<DeviceProfile>;
+/** Remove a device. Returns false if it was not registered. */
+export declare function removeDevice(name: string): Promise<boolean>;