@skrr-ai/cli 0.1.8

package/dist/lib/login.js

@@ -0,0 +1,495 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cliLogin = cliLogin;
+exports.cliLoginWithRefreshToken = cliLoginWithRefreshToken;
+/**
+ * login.ts — Phase H.0 for the Sky CLI.
+ *
+ * Replaces the device-code-as-default login path with the PKCE
+ * localhost-callback flow (RFC 7636). Device-code stays as the
+ * fallback for SSH, `--device-code`, `OVERSKY_FORCE_DEVICE_CODE=1`,
+ * or a server that doesn't support the new endpoints yet.
+ *
+ * Mirrors `daemon/src/auth.ts:loginInteractive` deliberately — the
+ * decision tree, fallback behaviour, and error handling all ship as
+ * one reviewed substrate. Divergence would reintroduce the "daemon
+ * does SSH-aware fallback but CLI doesn't" class of bug the roadmap
+ * is explicitly trying to prevent (docs/daemon-auth-roadmap.md H.0).
+ *
+ * CLI differences vs daemon:
+ *   - Scope is always `'cli'` (the issued JWT is REST-only; the
+ *     WebSocket handshake refuses it).
+ *   - No headless guard: a CLI command is only reached when the user
+ *     invoked it from a shell; `isNonInteractive()` catches the CI
+ *     case and prints a useful error instead of hanging the process.
+ *   - Persistence goes through `auth-storage.writeToBackend()` so
+ *     tokens land in Keychain on macOS / `cli-auth.json` elsewhere.
+ */
+const node_child_process_1 = require("node:child_process");
+const auth_core_1 = require("@skrr-ai/auth-core");
+const auth_storage_1 = require("./auth-storage");
+const config_1 = require("./config");
+const device_id_1 = require("./device-id");
+const ssh_detect_1 = require("./ssh-detect");
+const device_code_1 = require("./device-code");
+const device_identity_1 = require("./device-identity");
+const oauthLogin_1 = require("./oauthLogin");
+const daemonBroker_1 = require("./daemonBroker");
+/**
+ * Top-level dispatcher. Picks PKCE localhost vs device-code per the
+ * decision tree in the roadmap and persists the result.
+ */
+async function cliLogin(opts = {}) {
+    const cfg = (0, config_1.loadConfig)();
+    const serverUrl = (opts.serverUrl ?? cfg.baseURL).replace(/\/+$/, '');
+    const scope = opts.scope ?? 'cli';
+    // Persist the cliId on first login so future refreshes present a
+    // stable device identity. Same invariant as the device-code-only
+    // path this supersedes.
+    const cliId = cfg.cliId ?? (0, device_id_1.generateCliId)();
+    if (!cfg.cliId) {
+        (0, config_1.saveConfig)({ ...cfg, cliId });
+    }
+    const envForce = isTruthy(process.env.OVERSKY_FORCE_DEVICE_CODE);
+    const ssh = (0, ssh_detect_1.detectSshSession)();
+    // --- Daemon-as-broker pre-flight ---------------------------------------
+    // When the local `oversky` daemon is already authenticated for this user
+    // on this machine, the cleanest UX is no second browser flow at all:
+    // ask the daemon to broker a sibling cli-scope refresh family via its
+    // loopback HTTP endpoint, persist via writeToBackend(), and we're done.
+    //
+    // Honored ESCAPE HATCHES — broker is skipped when:
+    //   - opts.forceDeviceCode (explicit `--device-code` flag)
+    //   - OVERSKY_FORCE_DEVICE_CODE=1 (explicit env override)
+    //   - OVERSKY_SKIP_DAEMON_BROKER=1 (operator opt-out, e.g. debugging
+    //     the PKCE flow itself or testing fall-through behavior)
+    //
+    // The broker fires BEFORE the `isNonInteractive` check on purpose:
+    // headless boxes with an already-authed daemon are exactly the case
+    // where this matters most. A failed broker call still hits the
+    // headless guard below.
+    const skipBroker = opts.forceDeviceCode || envForce || isTruthy(process.env.OVERSKY_SKIP_DAEMON_BROKER);
+    if (!skipBroker) {
+        const brokerResult = await (0, daemonBroker_1.attemptDaemonBrokerLoginAndPersist)({
+            cliId,
+            // Pass the CLI's currently-configured baseURL so the broker can
+            // refuse to mint against the wrong server. When the daemon's
+            // serverUrl differs (e.g. daemon at localhost:3080, skrr at
+            // https://oversky.ai), the broker returns base_url_mismatch and
+            // we surface a clear hint instead of silently minting a token
+            // the next skrr command would 401 on.
+            baseURL: serverUrl,
+        });
+        if (brokerResult.ok) {
+            console.log('');
+            console.log('  Authorized via the local oversky daemon (no browser needed).');
+            return {
+                token: brokerResult.accessToken,
+                refreshToken: brokerResult.refreshToken,
+                ...(typeof brokerResult.accessExpiresAt === 'number'
+                    ? { expiresAt: brokerResult.accessExpiresAt }
+                    : typeof brokerResult.accessExpiresAt === 'string'
+                        ? { expiresAt: Date.parse(brokerResult.accessExpiresAt) }
+                        : {}),
+                ...(typeof brokerResult.refreshExpiresAt === 'number'
+                    ? { refreshExpiresAt: brokerResult.refreshExpiresAt }
+                    : typeof brokerResult.refreshExpiresAt === 'string'
+                        ? { refreshExpiresAt: Date.parse(brokerResult.refreshExpiresAt) }
+                        : {}),
+                flow: 'daemon-broker',
+            };
+        }
+        // `ci_token_refused` is the one broker failure we surface rather
+        // than fall through: the daemon is bootstrapped from a CI token,
+        // and PKCE won't help (CI envs are non-interactive anyway). Other
+        // broker failures — missing bootstrap, network blip, server 5xx —
+        // silently fall through to PKCE / device-code below.
+        if (brokerResult.reason === 'ci_token_refused') {
+            throw new Error('The local oversky daemon is bootstrapped from a CI token, which cannot broker an interactive CLI login. ' +
+                'Use `skrr create-token --name <name>` to mint a long-lived CI credential directly, ' +
+                'or run `skrr login` on a machine where the daemon was authenticated interactively.');
+        }
+        // `base_url_mismatch` is a configuration drift the user can resolve
+        // explicitly; print a one-line hint so they're not surprised when
+        // the PKCE flow opens a browser to a different URL than the
+        // daemon. Continues to PKCE below — that's the right fallback for
+        // "I'm logging into a different server than the daemon".
+        if (brokerResult.reason === 'base_url_mismatch' && brokerResult.daemonServerUrl) {
+            console.log('');
+            console.log(`  The local oversky daemon is logged in to ${brokerResult.daemonServerUrl}, but skrr is configured for ${serverUrl}.`);
+            console.log(`  Skipping the daemon-broker handoff. Run \`skrr login --base-url ${brokerResult.daemonServerUrl}\` to use the daemon instead.`);
+        }
+    }
+    if ((0, ssh_detect_1.isNonInteractive)()) {
+        throw new Error('skrr login requires an interactive terminal or an SSH session. ' +
+            'For CI, use `skrr create-token` and set OVERSKY_TOKEN=osk_ci_...');
+    }
+    // --- Decision tree (first match wins) ---
+    if (opts.forceDeviceCode) {
+        return runDeviceCode(serverUrl, cliId, 'user_requested', ssh);
+    }
+    if (envForce) {
+        return runDeviceCode(serverUrl, cliId, 'env_force', ssh);
+    }
+    if (ssh.detected) {
+        // Device-code's "open this URL on your laptop" UX is the correct
+        // move under SSH — the localhost callback would bind on the remote
+        // host where the user's browser can't reach.
+        return runDeviceCode(serverUrl, cliId, 'ssh_detected', ssh);
+    }
+    const pinnedPort = parseLoginPort(opts.port, process.env.OVERSKY_LOGIN_PORT);
+    try {
+        return await runLocalhost({
+            serverUrl,
+            scope,
+            cliId,
+            port: pinnedPort,
+            deviceName: opts.deviceName,
+        });
+    }
+    catch (err) {
+        // Retry-on-ephemeral-port: pinned ports are user-explicit (firewall
+        // allowlist). If that pinned port is in use, try ephemeral once
+        // before falling back to device-code.
+        if (err instanceof CliLocalhostFlowError &&
+            err.reason === 'bind_failed' &&
+            pinnedPort !== undefined &&
+            pinnedPort !== 0) {
+            console.log(`  Localhost port ${pinnedPort} unavailable — retrying on an ephemeral port.`);
+            try {
+                return await runLocalhost({
+                    serverUrl,
+                    scope,
+                    cliId,
+                    port: 0,
+                    deviceName: opts.deviceName,
+                });
+            }
+            catch (err2) {
+                return await fallbackOnLocalhostFailure(err2, serverUrl, cliId, ssh);
+            }
+        }
+        return await fallbackOnLocalhostFailure(err, serverUrl, cliId, ssh);
+    }
+}
+/**
+ * L13 (CC-A-7) — non-interactive login from a refresh token.
+ *
+ * When `skrr login` runs with `OVERSKY_REFRESH_TOKEN` in the environment,
+ * skip every interactive flow and exchange the refresh token for a fresh
+ * (access, refresh) pair via `POST /api/daemons/token/refresh`. The
+ * rotated pair is persisted via the same `writeToBackend()` path PKCE
+ * and device-code use, so a follow-up `sky <command>` finds it in the
+ * normal place (Keychain on macOS, `cli-auth.json` elsewhere).
+ *
+ * Use case: "I rebuilt my server and need to restore CLI auth from
+ * 1Password / a backup, with no human at a browser." Containers, cron
+ * provisioning, Ansible playbooks, EC2 init scripts.
+ *
+ * Why a paired backup (refresh + cliId), not refresh alone:
+ *   skrr's refresh route rejects a token presented under a daemonId
+ *   that doesn't match the row's binding — that mismatch is what makes
+ *   the family-reuse detector useful (a stolen refresh token replayed
+ *   under a different cliId looks different, and the detector can react).
+ *   CC's analog (CLAUDE_CODE_OAUTH_REFRESH_TOKEN) accepts the refresh
+ *   alone because their device-binding is softer; we keep ours strict
+ *   and ask the operator to back up the pair. See
+ *   docs/daemon-auth-cc-deep-comparison-2026-04-24.md L13 for the full
+ *   reasoning.
+ *
+ * Caller is responsible for surfacing the resulting token's source name
+ * to operators — `formatCredentialSource` renders 'env-token' for the
+ * raw OVERSKY_TOKEN slot, but this function persists into the storage
+ * backend, so a subsequent `skrr whoami` will report 'macOS Keychain' /
+ * 'auth.json' rather than 'OVERSKY_REFRESH_TOKEN'. That's the right
+ * outcome — the refresh token has been consumed and replaced.
+ */
+async function cliLoginWithRefreshToken(opts) {
+    const cfg = (0, config_1.loadConfig)();
+    const serverUrl = (opts.serverUrl ?? cfg.baseURL).replace(/\/+$/, '');
+    // Persist the cliId BEFORE the exchange so subsequent commands have
+    // device identity even if the network call fails halfway through and
+    // the operator retries. The refresh exchange itself is idempotent on
+    // the server side (rotation is the unit of retry); writing the cliId
+    // up-front never causes a server-state mismatch.
+    if (cfg.cliId !== opts.cliId) {
+        (0, config_1.saveConfig)({ ...cfg, cliId: opts.cliId });
+    }
+    let pair;
+    try {
+        pair = await (0, auth_core_1.refreshDaemonToken)(serverUrl, opts.refreshToken, opts.cliId, {
+            origin: refreshTokenLoginOrigin(),
+            // L11 Phase 3 — pair the refresh-token bootstrap with a device
+            // proof so the server's lenient/enforcing middleware sees the
+            // CLI as the same physical machine the daemon enrolled.
+            signRequestProof: device_identity_1.signServerRequest,
+        });
+    }
+    catch (err) {
+        if (err instanceof auth_core_1.PermanentAuthFailure) {
+            // Refresh row is gone (revoked, expired, family-reuse-detected,
+            // wrong cliId) — no amount of retry will help. Surface the typed
+            // error so the command layer can render an actionable message.
+            throw err;
+        }
+        if (err instanceof auth_core_1.TransientAuthFailure) {
+            throw err;
+        }
+        throw err;
+    }
+    // CLI scope always receives a non-null JWT (TokenPair.accessToken is
+    // `string | null` only because daemon-scope responses post Stage-E #1
+    // step 4 ship opaque-only). Narrow defensively so a server bug surfaces
+    // here instead of as a downstream "undefined token" mystery.
+    if (pair.accessToken === null) {
+        throw new auth_core_1.TransientAuthFailure('Refresh response did not include a CLI access token (server returned null accessToken).');
+    }
+    const accessToken = pair.accessToken;
+    (0, auth_storage_1.writeToBackend)({
+        token: accessToken,
+        ...(pair.accessExpiresAt !== undefined ? { expiresAt: pair.accessExpiresAt } : {}),
+        refreshToken: pair.refreshToken,
+        ...(pair.refreshExpiresAt !== undefined ? { refreshExpiresAt: pair.refreshExpiresAt } : {}),
+    }, { serverOrigin: serverUrl, clearReauth: true });
+    return {
+        token: accessToken,
+        refreshToken: pair.refreshToken,
+        expiresAt: pair.accessExpiresAt,
+        refreshExpiresAt: pair.refreshExpiresAt,
+        flow: 'refresh-token',
+    };
+}
+function refreshTokenLoginOrigin() {
+    // Keep the origin distinguishable in server-side audit logs so an
+    // operator can trace "this rotation came from an env-var-driven
+    // bootstrap, not the running daemon's scheduler." Mirrors the format
+    // refresh.ts uses for its own scheduled rotations.
+    let version = '0.0.0';
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports -- defensive lazy-load of package.json
+        version = require('../../package.json').version ?? '0.0.0';
+    }
+    catch {
+        /* keep default */
+    }
+    return `sky/${version} (cli login --refresh-token)`;
+}
+/**
+ * Typed wrapper for `runOAuthLogin` failures so the cliLogin dispatcher
+ * can decide between user-decision errors (re-throw to surface) and
+ * environmental errors (silently fall back to device-code).
+ */
+class CliLocalhostFlowError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'CliLocalhostFlowError';
+        this.reason = reason;
+    }
+}
+async function runLocalhost(args) {
+    if (args.scope !== 'cli') {
+        // SKY today only mints `scope: 'cli'` via the new OAuth flow.
+        // `scope: 'daemon'` is reserved for one-shot daemon-token mints
+        // (not wired). Surface as configuration error rather than silently
+        // mismapping to the cli path.
+        throw new CliLocalhostFlowError('invalid_scope', `runLocalhost called with unsupported scope='${args.scope}'`);
+    }
+    // The new orchestrator handles the full flow and persists tokens
+    // internally. We just translate its structured result into the
+    // `CliLoginResult` shape callers expect.
+    const result = await (0, oauthLogin_1.runOAuthLogin)({
+        apiUrl: args.serverUrl,
+        port: args.port,
+        cliId: args.cliId,
+    });
+    if (!result.ok) {
+        throw new CliLocalhostFlowError(result.error ?? 'network', `OAuth localhost login failed: ${result.error ?? 'unknown'}`);
+    }
+    if (!result.token) {
+        // Server contract violation — token presence is asserted by the
+        // CLI mint branch in api/server/routes/oauthFlow.js.
+        throw new CliLocalhostFlowError('network', 'OAuth login completed without an access_token (server contract violation)');
+    }
+    return {
+        token: result.token,
+        refreshToken: result.refreshToken,
+        expiresAt: result.expiresAt ? result.expiresAt.getTime() : undefined,
+        refreshExpiresAt: result.refreshExpiresAt,
+        flow: 'localhost',
+    };
+}
+/**
+ * Decide whether a localhost-flow failure should silently fall back to
+ * device-code or surface to the user.
+ *
+ * User-decision errors (state mismatch / cancelled / explicit deny) and
+ * configuration errors (invalid_scope / invalid_client) are re-thrown so
+ * the caller sees them. Everything else — bind, timeout, network — is
+ * environmental and the right action is the device-code fallback.
+ */
+async function fallbackOnLocalhostFailure(err, serverUrl, cliId, ssh) {
+    if (err instanceof CliLocalhostFlowError) {
+        if (err.reason === 'access_denied' || err.reason === 'cancelled') {
+            console.error('  Authorization declined.');
+            throw err;
+        }
+        if (err.reason === 'invalid_scope' || err.reason === 'invalid_client') {
+            // Configuration / server error — a different flow won't fix it.
+            console.error(`  ${err.message}`);
+            throw err;
+        }
+        const reason = mapOAuthReasonToDeviceCodeReason(err.reason);
+        return runDeviceCode(serverUrl, cliId, reason, ssh, err.message);
+    }
+    // Unknown error class — defensive fallback.
+    const errorMessage = err instanceof Error ? err.message : err ? String(err) : undefined;
+    return runDeviceCode(serverUrl, cliId, 'unknown', ssh, errorMessage);
+}
+function mapOAuthReasonToDeviceCodeReason(reason) {
+    switch (reason) {
+        case 'bind_failed':
+            return 'bind_failed';
+        case 'timeout':
+            return 'timeout';
+        case 'network':
+            return 'network';
+        case 'invalid_grant':
+            // PKCE/code mismatch is environmental from the user's POV (timeouts,
+            // intermediate-proxy mangling). Try device-code rather than abort.
+            return 'network';
+        default:
+            return 'unknown';
+    }
+}
+async function runDeviceCode(serverUrl, cliId, reason, ssh, errorMessage) {
+    console.log('');
+    renderDeviceCodePrologue({ reason, ssh, errorMessage });
+    // ADD-CLI7 — dead `try { ... } catch (err) { throw err; }` wrapper
+    // removed. The previous shape added nothing beyond a plain await;
+    // keeping it invited confusion about whether an error-handling
+    // strategy was pending. `startDeviceCode` is allowed to throw and
+    // the caller has its own recovery logic.
+    const start = await (0, device_code_1.startDeviceCode)(serverUrl, cliId);
+    console.log('  To finish signing in, open this URL on a machine with a browser:');
+    console.log(`    ${start.verificationUrl}`);
+    console.log('');
+    console.log(`  If prompted, confirm the code:  ${start.code}`);
+    console.log('');
+    // Best-effort local open — under SSH this typically no-ops, and we've
+    // already shown the URL explicitly. Keeps parity with the daemon.
+    if (!ssh.detected) {
+        openBrowserPlatform(start.verificationUrl);
+    }
+    console.log('  Waiting for approval — this command will continue automatically.');
+    let cancelled = false;
+    const onSigint = () => {
+        cancelled = true;
+    };
+    process.on('SIGINT', onSigint);
+    let approved;
+    try {
+        approved = await (0, device_code_1.pollDeviceCode)(serverUrl, start.code, {
+            shouldContinue: () => !cancelled,
+        });
+    }
+    finally {
+        process.off('SIGINT', onSigint);
+    }
+    (0, auth_storage_1.writeToBackend)({
+        token: approved.token,
+        ...(approved.expiresAt !== undefined ? { expiresAt: approved.expiresAt } : {}),
+        ...(approved.refreshToken
+            ? {
+                refreshToken: approved.refreshToken,
+                ...(approved.refreshExpiresAt !== undefined
+                    ? { refreshExpiresAt: approved.refreshExpiresAt }
+                    : {}),
+            }
+            : {}),
+    }, { serverOrigin: serverUrl, clearReauth: true });
+    console.log('  ✓ Authorized.');
+    return {
+        token: approved.token,
+        refreshToken: approved.refreshToken,
+        expiresAt: approved.expiresAt,
+        refreshExpiresAt: approved.refreshExpiresAt,
+        flow: 'device-code',
+    };
+}
+function renderDeviceCodePrologue(args) {
+    const headline = headlineFor(args.reason);
+    console.log(`  ${headline}`);
+    if (args.ssh.detected) {
+        console.log('  SSH session detected — open the URL below on your LOCAL browser, not the remote host.');
+        if (args.ssh.agentForwarded) {
+            console.log('  (ssh-agent forwarding is active; no port-forward needed.)');
+        }
+    }
+    if (args.errorMessage) {
+        const truncated = args.errorMessage.length > 200 ? args.errorMessage.slice(0, 197) + '...' : args.errorMessage;
+        console.log(`  Underlying error: ${truncated}`);
+    }
+    console.log('');
+}
+function headlineFor(reason) {
+    switch (reason) {
+        case 'user_requested':
+            return 'Using device-code (explicitly requested).';
+        case 'env_force':
+            return 'Using device-code (OVERSKY_FORCE_DEVICE_CODE=1).';
+        case 'ssh_detected':
+            return 'Using device-code (SSH session detected).';
+        case 'feature_disabled':
+            return 'Using device-code — server does not support localhost callback.';
+        case 'bind_failed':
+            return 'Using device-code — could not bind a localhost port for the callback.';
+        case 'timeout':
+            return 'Using device-code — localhost callback timed out waiting for approval.';
+        case 'malformed':
+            return 'Using device-code — localhost callback received a malformed response.';
+        case 'network':
+            return 'Using device-code — a network error interrupted the localhost flow.';
+        case 'unknown':
+            return 'Using device-code as a fallback.';
+    }
+}
+// ---------------------------------------------------------------------
+// Platform browser opener + helpers
+// ---------------------------------------------------------------------
+function openBrowserPlatform(url) {
+    // execFile (no shell) so the URL can't inject arbitrary flags.
+    const platform = process.platform;
+    if (platform === 'darwin') {
+        (0, node_child_process_1.execFile)('open', [url], () => {
+            /* ignore */
+        });
+    }
+    else if (platform === 'win32') {
+        (0, node_child_process_1.execFile)('rundll32', ['url.dll,FileProtocolHandler', url], () => {
+            /* ignore */
+        });
+    }
+    else {
+        (0, node_child_process_1.execFile)('xdg-open', [url], () => {
+            /* ignore */
+        });
+    }
+}
+function parseLoginPort(flagValue, envValue) {
+    if (typeof flagValue === 'number' && Number.isFinite(flagValue) && flagValue >= 0) {
+        return flagValue;
+    }
+    if (typeof envValue === 'string' && envValue.length > 0) {
+        const n = Number.parseInt(envValue, 10);
+        if (Number.isFinite(n) && n >= 0 && n <= 65_535)
+            return n;
+    }
+    return undefined;
+}
+function isTruthy(v) {
+    if (typeof v !== 'string')
+        return false;
+    const l = v.toLowerCase();
+    return l === '1' || l === 'true' || l === 'yes';
+}

package/dist/lib/machines.d.ts

@@ -0,0 +1,131 @@
+/**
+ * machines.ts — request client for `/api/machines`.
+ *
+ * ## Why this file exists
+ *
+ * The machine control plane (`api/server/routes/machines.js`, `MachineService`)
+ * shipped with four endpoints and exactly one consumer: the browser's Harnesses
+ * page, which builds the URLs inline in `client/src/data-provider/Harnesses/`.
+ * Nothing in `packages/data-provider` or this package referenced `/api/machines`
+ * at all, so a headless operator — or a locally-run coding agent, which is the
+ * thing most likely to be ASKED about the machine it is running on — could not
+ * list, inspect, rename, or disconnect a machine.
+ *
+ * `skrr harnesses list` even prints a `MACHINE` column of truncated uuids with no
+ * command that resolves one.
+ *
+ * ## A machine is one level DOWN from a harness
+ *
+ * `skrr harnesses` lists PAIRS: `(machine, provider)`. A laptop with Claude Code,
+ * Codex and Gemini installed is three harness rows and one machine. This topic
+ * is the aggregate those rows hang off — see
+ * `docs/architecture/engine-harness-sandbox-vocabulary-2026-08-16.md`.
+ *
+ * ## No create, no delete
+ *
+ * Deliberately mirroring the router: a local machine is connected by installing
+ * a daemon and removed by `disconnect` (you are revoking skrr's access, not
+ * destroying a computer), and a hosted machine's lifecycle belongs to the
+ * MachineLease product flow. `disconnect` is a POST to an explicit action rather
+ * than a DELETE for exactly that reason.
+ *
+ * ## Inline path literals
+ *
+ * `domain-api-parity` resolves a command to an endpoint by reading these
+ * strings. A helper that assembles the URL is opaque to it, so the endpoint
+ * would read as unreachable and get allow-listed — a check going green on an
+ * assertion it never made.
+ */
+export type MachineIdentityKind = 'runtime-lease' | 'machine-uuid' | 'stable-daemon' | 'daemon' | 'virtual-product' | 'harness';
+export interface MachineHarnessRow {
+    id: string;
+    name: string;
+    provider: string;
+    status: 'online' | 'offline';
+    authStatus?: string;
+    lastSeenAt: string | null;
+    daemonId: string | null;
+    /**
+     * A newer registration of the same provider on this machine replaced this
+     * row. Rows are keyed per daemonId, and daemonId changes when the same daemon
+     * is started a different way, so these accumulate and never come back online.
+     * Excluded from machine status; still returned so a surface can show or reap
+     * them.
+     */
+    superseded?: boolean;
+}
+export interface Machine {
+    id: string;
+    identityKind: MachineIdentityKind;
+    name: string;
+    status: 'online' | 'offline' | 'degraded';
+    machineUuid: string | null;
+    stableDaemonId: string | null;
+    daemonId: string | null;
+    platform: string | null;
+    arch: string | null;
+    lastSeenAt: string | null;
+    onlineHarnessCount: number;
+    /**
+     * Optional because the CLI is versioned independently of the server it points
+     * at: a deployment older than this field simply omits it.
+     */
+    supersededHarnessCount?: number;
+    harnesses: MachineHarnessRow[];
+    preferences: {
+        name?: string;
+        description?: string;
+        tags?: string[];
+    };
+    lease: Record<string, unknown> | null;
+    controls: {
+        canDisconnect: boolean;
+        canRename: boolean;
+        canTag: boolean;
+        canPause: boolean;
+        canResume: boolean;
+        canTerminate: boolean;
+    };
+}
+/** The user-editable slice. Identities, capabilities and lifecycle are not. */
+export interface MachinePreferencesPatch {
+    name?: string;
+    description?: string;
+    tags?: string[];
+}
+/**
+ * How many of a machine's harnesses still represent a capability it has.
+ *
+ * The denominator of "N online" has to count the same population the numerator
+ * does. `onlineHarnessCount` is computed server-side AFTER supersession, so
+ * dividing it by every row printed `7/23` next to a status of `online` — the
+ * ratio contradicting the word beside it, and the user unable to tell whether
+ * 16 harnesses were down.
+ *
+ * A superseded row is one the same machine replaced with a newer registration
+ * for the same provider (see MachineService.markSupersededHarnesses). It can
+ * never come back online under a daemon id nothing uses any more, so counting
+ * it as a missing capability is what made these machines read `degraded`
+ * forever before the server-side fix.
+ *
+ * Three sources, in order of directness, because the CLI is versioned
+ * independently of the server it points at: the per-row flag, then the total,
+ * then every row — an older deployment that sends neither still gets the old
+ * behaviour rather than a wrong number.
+ */
+export declare function liveHarnessCount(machine: Machine | undefined): number;
+export declare function listMachines(): Promise<Machine[]>;
+export declare function getMachine(machineId: string): Promise<Machine | null>;
+export declare function updateMachine(machineId: string, patch: MachinePreferencesPatch): Promise<Machine | null>;
+export declare function disconnectMachine(machineId: string): Promise<Record<string, unknown> | null>;
+/**
+ * Resolve a user-supplied reference to exactly one machine.
+ *
+ * A machine is addressable by several ids (`id`, `machineUuid`,
+ * `stableDaemonId`, `daemonId`) and `skrr harnesses list` prints a TRUNCATED
+ * uuid, so the id a user has to hand is often a prefix of the one the API
+ * wants. Resolving here keeps every command accepting the same references, and
+ * makes an ambiguous prefix an error rather than a silent pick of the first
+ * match.
+ */
+export declare function resolveMachineRef(machines: Machine[], ref: string): Machine;