@braedonsaunders/appkit-desk 0.5.1 → 0.7.0

package/README.md

@@ -112,6 +112,12 @@ stops, the disk persists, applications cold-start on `resume`. Keep-alive jobs
 die with the lease, and their termination is recorded as `job_exit` so no
 process ever runs where an operator cannot see it.
 
+`host.shutdown(deskId)` is a restart, not a destroy: a resident desk is synced
+and shut down instead of parked, a parked desk's memory snapshot is discarded,
+and the overlay stays, so the next `start` or `resume` cold boots from disk.
+Use it when a desk must come back fresh — new memory or vCPU settings, or a
+guest wedged in a way a resume would bring straight back.
+
 Residency is bounded by a hard capacity cap. Starts beyond the cap queue FIFO
 rather than overcommitting host memory. `host.stats()` reports
 `{ resident, queued, capacity, suspended, lastStartedAt, lastSuspendedAt,
@@ -179,7 +185,8 @@ append-only record that cannot be edited afterward.
 
 `onEvent` receives a closed union — `shell_command`, `app_launch`, `click`,
 `type`, `key`, `scroll`, `drag`, `window_focus`, `screen_open`,
-`screen_close`, `handover_begin`, `handover_end`, `job_start`, `job_exit` —
+`screen_close`, `handover_begin`, `handover_end`, `job_start`, `job_exit`,
+`snapshot_cpu_fallback` —
 each stamped with `deskId` and an ISO timestamp. The union is defined here so
 the consumer's ledger and this package agree on the taxonomy; persistence is
 entirely the consumer's concern.
@@ -231,3 +238,23 @@ masking boundary changes.
 Do not fall back to unconfined execution when this package reports an
 unsupported host. A deployment without KVM loses the desk ability entirely —
 the same fail-closed posture as the rest of AppKit.
+
+## Routed guest networking and TCP services
+
+`deskNetworkIdentity(index)` returns a deterministic TAP name and MAC address. `createDeskNetwork({ gateway, dns, egress, chainPrefix?, allowHostPorts?, prefixLength?, runner?, enableForwarding? })` provides routed point-to-point TAP setup. Set `egress: { mode: 'open' }` to masquerade guest-originated IPv4 traffic for arbitrary TCP and UDP; IPv6 traffic on the TAP is blocked with `ip6tables` so it cannot bypass host isolation; new inbound forwarded connections are dropped. Set `egress: { mode: 'proxied', httpProxyPort, httpsProxyPort }` to transparently redirect HTTP and HTTPS to proxy listeners, pin DNS to the supplied resolver, and drop other guest egress. The proxy supplies destination policy. Both modes drop new connections to host services, except TCP and UDP ports explicitly listed in `allowHostPorts` on the gateway address; proxied mode also permits its proxy listeners. Established replies to host-initiated guest connections are accepted.
+
+The default iptables chain prefix is `desk`. Existing deployments using the `bh` chains must supply `chainPrefix: 'bh'` to retain those names during a rolling upgrade and avoid orphaning the old rules. `ensure({ tap, guest })` must finish before boot; `teardown({ tap, guest })` removes its rules and TAP after the VM stops. Configure Linux IPv4 forwarding, NET_ADMIN, `ip`, and `iptables` in the host namespace; open mode also requires `ip6tables`. When changing egress modes, tear down the old mode before installing the new one. `configureGuest(desk, { tap, guest })` configures the guest interface, route, and resolver through exec. `syncDeskGuestClock(desk, now?)` sets the guest clock after wake. Failures are reported to the caller. Operations on one TAP are serialized within the network instance; use one instance per namespace. Rule replacement uses multiple iptables commands and is not atomic: call `ensure` before the VM starts, and do not refresh rules on a live TAP.
+
+Supply `network: { tapDevice, macAddress, guestAddress }` to `host.start`, then `await desk.connect(port)` returns a Node `Duplex` TCP stream to the guest. The caller owns the stream; suspension closes it. A service must listen on the guest interface, and its protocol and authentication remain the application's responsibility. `connectGuest` on host options injects a dialer for testing.
+
+With `parkWithMemory`, new snapshots carry a host CPU signature. A changed signature skips restore and cold boots; Cloud Hypervisor's specific incompatible-CPUID restore error also triggers a cold boot. These outcomes increment `stats().snapshotCpuFallbacks`, set `lastSnapshotCpuFallback`, and emit `snapshot_cpu_fallback`, rather than setting `lastError`. Existing snapshots without a signature are attempted normally. Signatures are conservative CPU identity and feature fingerprints, not a guarantee of CPUID compatibility; a cold boot loses the parked process state. Keep snapshots and their overlays together.
+
+For a disposable real-host check, provide a guest image with the desk agent and Python 3, Cloud Hypervisor, KVM, and a free TAP name and IP pair. Run from the repository root in the target network namespace with privileges to manage TAP and iptables:
+
+```sh
+DESK_CHECK_TAP=dsk9001 DESK_CHECK_GUEST=172.30.0.2 DESK_CHECK_GATEWAY=172.30.0.1 \
+DESK_CHECK_IMAGE_ROOT=/data/desk-image DESK_CHECK_BASE_IMAGE=/data/desk-image/base.img \
+DESK_CHECK_TMPDIR=/data/tmp pnpm --filter @braedonsaunders/appkit-desk exec tsx scripts/check-kvm.mts
+```
+
+Set `DESK_CHECK_KERNEL_CMDLINE` for images that require a custom root device. The check creates and removes a disposable VM, overlay, snapshot, TAP and firewall rules. It verifies a guest HTTP stream before and after memory restore; it does not verify the proxy or cross-CPU migration. Choose addresses that do not overlap existing routes.

package/backend.d.ts

@@ -90,9 +90,40 @@ export interface DeskMachine {
     onConnectionChange?(listener: (change: DeskConnectionChange) => void): () => void;
     /** Stop the VM. Idempotent; resolves once the VMM process has exited. */
     shutdown(): Promise<void>;
+    /**
+     * Park the VM with its memory, so resuming continues the process tree.
+     *
+     * Optional: a backend with no snapshot facility simply does not offer it, and
+     * the host falls back to `shutdown()`. Pauses the guest, writes a snapshot to
+     * `snapshotDir`, then stops the VMM — and resolves only once all three have
+     * happened, because a caller that believed a snapshot exists when it does not
+     * would later refuse to boot the desk at all.
+     *
+     * The caller is responsible for quiescing the guest filesystem first. A paused
+     * guest still holds dirty pages that exist only in the snapshot, so a disk
+     * parked without a prior `sync` is consistent only *with that snapshot* —
+     * which matters the moment the snapshot is discarded.
+     */
+    park?(snapshotDir: string): Promise<void>;
+}
+export interface DeskBootHooks {
+    /**
+     * Called on a restore, after the snapshot has been read back and before the
+     * guest is allowed to run.
+     *
+     * This is the window in which the snapshot must be destroyed. A memory image
+     * is valid only against the disk it was taken with, so once the guest resumes
+     * and writes, any surviving snapshot describes a past that no longer matches —
+     * and replaying it later would corrupt the desk. Restoring paused and
+     * invalidating here is what makes that impossible rather than unlikely.
+     *
+     * Throwing aborts the restore: the VM is stopped and the caller is free to
+     * cold boot, which is safe because a paused guest has written nothing.
+     */
+    onRestored?: () => Promise<void>;
 }
 export interface DeskBackend {
-    boot(plan: DeskLaunchPlan): Promise<DeskMachine>;
+    boot(plan: DeskLaunchPlan, hooks?: DeskBootHooks): Promise<DeskMachine>;
 }
 export type DeskProcessLauncher = (command: string, args: readonly string[], options: {
     identity?: DeskLauncherIdentity;
@@ -134,6 +165,17 @@ export interface CloudHypervisorBackendOptions {
     guestAgentPort?: number;
 }
 export declare function createCloudHypervisorBackend(options?: CloudHypervisorBackendOptions): DeskBackend;
+/**
+ * Cloud Hypervisor's control plane: HTTP/1.1 over the `--api-socket` Unix
+ * socket. The plan has always created that socket; until now nothing spoke to
+ * it, because stopping a VM needed nothing more than killing the process.
+ *
+ * Pausing and snapshotting do need it, and `ch-remote` — the tool that usually
+ * does this — is not in the runner image. Writing the two requests by hand is a
+ * smaller change than adding a binary to the image, and keeps the whole
+ * lifecycle inside one process that already owns the socket path.
+ */
+export type VmmApiCall = (socketPath: string, path: string, body?: Record<string, unknown>, method?: 'PUT' | 'GET') => Promise<void>;
 /** The default backend: real Cloud Hypervisor over a real vsock socket. */
 export declare const cloudHypervisorBackend: DeskBackend;
 //# sourceMappingURL=backend.d.ts.map

package/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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"}

package/backend.js

@@ -11,6 +11,7 @@
  */
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
+import { request as httpRequest } from 'node:http';
 import { createConnection } from 'node:net';
 import { Buffer } from 'node:buffer';
 import { DeskError } from './plan.js';
@@ -58,7 +59,7 @@ export function createCloudHypervisorBackend(options = {}) {
     const reconnectRetryDelayMs = options.reconnectRetryDelayMs ?? DEFAULT_RECONNECT_RETRY_DELAY_MS;
     const killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
     const guestAgentPort = options.guestAgentPort ?? GUEST_AGENT_VSOCK_PORT;
-    async function boot(plan) {
+    async function boot(plan, hooks) {
         if (platform !== 'linux') {
             throw new DeskError(`The AppKit desk requires Linux; received ${platform}.`);
         }
@@ -70,6 +71,23 @@ export function createCloudHypervisorBackend(options = {}) {
         const child = launcher(plan.vmm.command, plan.vmm.args, { identity: plan.launcherIdentity });
         const log = drainOutput(child);
         const exit = watchExit(child);
+        // A restored guest comes back PAUSED (see the `resume=false` reasoning in
+        // the plan). Three things have to happen in this order and nowhere else:
+        // prove the restore finished, let the caller destroy the snapshot while the
+        // guest still cannot write, then start it.
+        if (plan.snapshot.restoring) {
+            try {
+                await waitForVmm(vmmApi, plan.api.socketPath, { now, exited: exit, timeoutMs: connectTimeoutMs });
+                await hooks?.onRestored?.();
+                await vmmApi(plan.api.socketPath, '/api/v1/vm.resume');
+            }
+            catch (error) {
+                await terminate(child, exit, killGraceMs);
+                const said = log.tail();
+                const detail = said === '' ? '' : ` The VMM said: ${said}`;
+                throw new DeskError(`Desk ${plan.deskId} could not be restored from ${plan.snapshot.dir}: ${errorMessage(error)}${detail}`);
+            }
+        }
         let stream;
         try {
             stream = await connectWithRetry({
@@ -117,10 +135,73 @@ export function createCloudHypervisorBackend(options = {}) {
             idFactory,
             requestTimeoutMs,
             killGraceMs,
+            apiSocketPath: plan.api.socketPath,
+            vmmApi,
         });
     }
     return { boot };
 }
+const vmmApi = async (socketPath, path, body, method = 'PUT') => {
+    const payload = body === undefined ? undefined : Buffer.from(JSON.stringify(body), 'utf8');
+    await new Promise((resolve, reject) => {
+        const request = httpRequest({
+            socketPath,
+            path,
+            method,
+            headers: {
+                ...(payload ? { 'content-type': 'application/json', 'content-length': String(payload.length) } : {}),
+            },
+        }, (response) => {
+            // CH answers 204 with no body on success. Drain regardless: an unread
+            // response keeps the socket open and the next call queues behind it.
+            const chunks = [];
+            response.on('data', (chunk) => chunks.push(chunk));
+            response.on('end', () => {
+                const status = response.statusCode ?? 0;
+                if (status >= 200 && status < 300) {
+                    resolve();
+                    return;
+                }
+                const said = Buffer.concat(chunks).toString('utf8').trim().slice(0, 400);
+                reject(new DeskError(`${path} returned ${status}${said === '' ? '' : `: ${said}`}`));
+            });
+        });
+        request.on('error', (error) => reject(new DeskError(`${path} failed: ${errorMessage(error)}`)));
+        if (payload)
+            request.write(payload);
+        request.end();
+    });
+};
+/**
+ * Wait until the VMM answers its control socket.
+ *
+ * On a restore this is also the only honest signal that the snapshot was read
+ * back: Cloud Hypervisor creates the API socket early but does not serve
+ * `vm.info` until it holds a VM, so a successful call means the restore
+ * completed rather than merely that the process started. A VMM that exits
+ * instead — a corrupt snapshot, a config the host can no longer satisfy — stops
+ * the wait immediately rather than burning the whole timeout.
+ */
+async function waitForVmm(call, socketPath, options) {
+    const deadline = options.now() + options.timeoutMs;
+    const retryDelayMs = options.retryDelayMs ?? 50;
+    let lastFailure = 'it never answered';
+    for (;;) {
+        if (options.exited.done)
+            throw new DeskError(`the VMM exited before it served its control socket`);
+        try {
+            await call(socketPath, '/api/v1/vm.info', undefined, 'GET');
+            return;
+        }
+        catch (error) {
+            lastFailure = errorMessage(error);
+        }
+        if (options.now() >= deadline) {
+            throw new DeskError(`the VMM did not answer ${socketPath} in ${options.timeoutMs}ms: ${lastFailure}`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+    }
+}
 /** The default backend: real Cloud Hypervisor over a real vsock socket. */
 export const cloudHypervisorBackend = createCloudHypervisorBackend();
 /**
@@ -323,6 +404,34 @@ function createMachine(options) {
             close(new DeskError(`Desk ${deskId} is shutting down.`), true);
             await terminate(child, exit, killGraceMs);
         },
+        async park(snapshotDir) {
+            // Close the guest channel FIRST. Pausing a VM strands whatever was in
+            // flight on the vsock, and a reconnect attempt against a paused guest
+            // would burn the whole reconnect window before giving up — so the channel
+            // is made terminal before the VM stops answering, exactly as shutdown
+            // does it.
+            close(new DeskError(`Desk ${deskId} is being parked.`), true);
+            try {
+                await options.vmmApi(options.apiSocketPath, '/api/v1/vm.pause');
+                await options.vmmApi(options.apiSocketPath, '/api/v1/vm.snapshot', {
+                    // Three slashes: `file://` plus an absolute path. CH rejects a
+                    // destination_url it cannot parse, and the directory must already
+                    // exist — it writes the config and memory files into it.
+                    destination_url: `file://${snapshotDir}`,
+                });
+            }
+            catch (error) {
+                // The VM is paused and there is no usable snapshot, which is the one
+                // state nothing downstream can interpret. Stop the VMM so the desk is
+                // plainly off, and say why — the caller falls back to a cold boot, and
+                // the disk is still consistent because the guest was synced before this.
+                await terminate(child, exit, killGraceMs);
+                throw error instanceof DeskError
+                    ? new DeskError(`Desk ${deskId} could not be parked with its memory: ${error.message}`)
+                    : new DeskError(`Desk ${deskId} could not be parked with its memory: ${errorMessage(error)}`);
+            }
+            await terminate(child, exit, killGraceMs);
+        },
     };
 }
 /**

package/backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The backend port and its default Cloud Hypervisor implementation.\n *\n * `DeskBackend` is the seam that keeps the package testable without a\n * hypervisor: the host asks a backend to boot a `DeskLaunchPlan` and gets a\n * `DeskMachine` — a request/response channel to the in-guest agent plus an\n * event subscription. CI and non-KVM developer machines inject an in-memory\n * fake; production uses `cloudHypervisorBackend`, whose process-spawning glue\n * is deliberately thin because everything that can be pure lives in the plan\n * builder and the protocol module.\n */\nimport { spawn, type ChildProcess } from 'node:child_process'\nimport { randomUUID } from 'node:crypto'\nimport { createConnection } from 'node:net'\nimport { Buffer } from 'node:buffer'\nimport type { Duplex } from 'node:stream'\nimport { DeskError, type DeskLaunchPlan, type DeskLauncherIdentity } from './plan'\nimport {\n  encodeFrame,\n  FrameDecoder,\n  GUEST_AGENT_VSOCK_PORT,\n  parseHostBoundMessage,\n  type GuestCommand,\n  type GuestEventMessage,\n  type HostBoundMessage,\n} from './protocol'\n\n/**\n * A request that was in flight when the guest connection dropped.\n *\n * Distinct from a plain `DeskError` because the caller's next move is\n * different: this request may ALREADY HAVE RUN. The frame reached the guest,\n * and whether the guest executed it before the channel went away is not\n * knowable from the host. An `exec` may have sent mail; a `click` may have\n * landed. So the transport refuses to guess — it names the ambiguity and lets\n * the caller decide whether the operation is safe to repeat. Anything that\n * rejects with a plain `DeskError` instead never reached the guest at all.\n */\nexport class DeskRequestFateUnknownError extends DeskError {\n  override readonly name: string = 'DeskRequestFateUnknownError'\n}\n\n/**\n * What happened to the transport underneath a machine.\n *\n * `reconnected` means the host lost the guest channel mid-lease and got it\n * back; the desk is usable again. It is NOT a promise that the guest is\n * unchanged — see the note on `onConnectionChange`. `lost` means it will not\n * come back on this VM and the desk needs a fresh boot.\n */\nexport type DeskConnectionChange =\n  | {\n      state: 'reconnected'\n      deskId: string\n      /** How the previous connection went away. */\n      reason: string\n      /** Wall-clock time the desk spent with no channel to its guest. */\n      downtimeMs: number\n      /** Reconnects this machine has survived, including this one. */\n      reconnects: number\n    }\n  | {\n      state: 'lost'\n      deskId: string\n      /** Why it is gone for good: the VMM exited, or the window ran out. */\n      reason: string\n    }\n\n/** A booted microVM as the host sees it: one desk, one guest-agent channel. */\nexport interface DeskMachine {\n  readonly deskId: string\n  /**\n   * Send one request to the in-guest agent and await its correlated result.\n   *\n   * Rejects with `DeskError` when the guest reports an error, the request\n   * times out, or the connection is gone for good — in that last case the\n   * request never left the host, so repeating it is safe.\n   *\n   * A connection lost mid-lease is re-established rather than fatal: a call\n   * that arrives while that is happening WAITS for it instead of failing.\n   * A call that was already in flight when the channel dropped rejects with\n   * `DeskRequestFateUnknownError`, because the host cannot tell whether the\n   * guest ran it.\n   */\n  request(command: GuestCommand, options?: { timeoutMs?: number }): Promise<unknown>\n  /**\n   * Subscribe to unsolicited guest events (job exits, frames, focus changes).\n   *\n   * Subscriptions belong to the machine, not to the socket under it, so they\n   * survive a reconnect. What does NOT survive is the guest's own capture\n   * state: a guest agent that restarted has no screen, no frame encoder and\n   * no video encoder, and a subscriber will simply stop receiving. Watch\n   * `onConnectionChange` to notice.\n   */\n  subscribe(listener: (event: GuestEventMessage) => void): () => void\n  /**\n   * Watch the transport under this machine.\n   *\n   * Optional: a backend whose channel cannot drop has nothing to report. The\n   * default backend reports every reconnect, because a reconnect that leaves\n   * no trace turns a guest agent restarting every few minutes into a desk that\n   * misbehaves for reasons nobody can find.\n   */\n  onConnectionChange?(listener: (change: DeskConnectionChange) => void): () => void\n  /** Stop the VM. Idempotent; resolves once the VMM process has exited. */\n  shutdown(): Promise<void>\n}\n\nexport interface DeskBackend {\n  boot(plan: DeskLaunchPlan): Promise<DeskMachine>\n}\n\nexport type DeskProcessLauncher = (\n  command: string,\n  args: readonly string[],\n  options: { identity?: DeskLauncherIdentity },\n) => ChildProcess\n\nexport interface CloudHypervisorBackendOptions {\n  /** Spawns the VMM and image tooling; injectable for tests. */\n  launcher?: DeskProcessLauncher\n  /** Opens the host side of the vsock Unix socket; injectable for tests. */\n  connect?: (socketPath: string) => Duplex\n  platform?: NodeJS.Platform\n  /**\n   * Clock behind every connect and reconnect deadline. Injectable for the same\n   * reason `DeskHostOptions.now` is: a test drives a window to its end by\n   * moving the clock, rather than sleeping for it and hoping the machine it\n   * runs on is fast enough.\n   */\n  now?: () => number\n  idFactory?: () => string\n  requestTimeoutMs?: number\n  connectTimeoutMs?: number\n  connectRetryDelayMs?: number\n  /** Bound on a single handshake attempt; see attemptHandshake. */\n  handshakeTimeoutMs?: number\n  /**\n   * How long a machine keeps trying to get its guest channel back after an\n   * unexpected drop before declaring the desk lost. Bounded on purpose: the\n   * VMM is still alive so a reconnect is cheap and usually fast, but retrying\n   * forever against a guest that is never coming back is worse than failing.\n   */\n  reconnectWindowMs?: number\n  /**\n   * First delay between reconnect attempts. It doubles toward a ceiling, so\n   * this is the fast first poll rather than the steady rate. Separate from\n   * `connectRetryDelayMs`, which is sized for a guest that is still cold\n   * booting; here the guest was up a moment ago.\n   */\n  reconnectRetryDelayMs?: number\n  killGraceMs?: number\n  guestAgentPort?: number\n}\n\nconst DEFAULT_REQUEST_TIMEOUT_MS = 30_000\nconst DEFAULT_CONNECT_TIMEOUT_MS = 20_000\nconst DEFAULT_CONNECT_RETRY_DELAY_MS = 100\nconst DEFAULT_HANDSHAKE_TIMEOUT_MS = 5_000\nconst DEFAULT_RECONNECT_WINDOW_MS = 30_000\nconst DEFAULT_RECONNECT_RETRY_DELAY_MS = 250\n/**\n * How far the reconnect delay is allowed to double. A guest agent that systemd\n * is restarting is not helped by being hammered four times a second for the\n * whole window, and an unbounded doubling would spend most of the window\n * asleep after two failures.\n */\nconst RECONNECT_BACKOFF_CEILING = 8\nconst DEFAULT_KILL_GRACE_MS = 2_000\nconst HANDSHAKE_LINE_LIMIT = 128\n\nexport function createCloudHypervisorBackend(\n  options: CloudHypervisorBackendOptions = {},\n): DeskBackend {\n  const launcher = options.launcher ?? defaultLauncher\n  const connect = options.connect ?? defaultConnect\n  const platform = options.platform ?? process.platform\n  const now = options.now ?? Date.now\n  const idFactory = options.idFactory ?? randomUUID\n  const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS\n  const connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS\n  const connectRetryDelayMs = options.connectRetryDelayMs ?? DEFAULT_CONNECT_RETRY_DELAY_MS\n  const handshakeTimeoutMs = options.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS\n  const reconnectWindowMs = options.reconnectWindowMs ?? DEFAULT_RECONNECT_WINDOW_MS\n  const reconnectRetryDelayMs = options.reconnectRetryDelayMs ?? DEFAULT_RECONNECT_RETRY_DELAY_MS\n  const killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS\n  const guestAgentPort = options.guestAgentPort ?? GUEST_AGENT_VSOCK_PORT\n\n  async function boot(plan: DeskLaunchPlan): Promise<DeskMachine> {\n    if (platform !== 'linux') {\n      throw new DeskError(`The AppKit desk requires Linux; received ${platform}.`)\n    }\n    if (plan.overlay.create) {\n      await runToCompletion(\n        launcher(plan.overlay.create.command, plan.overlay.create.args, {\n          identity: plan.launcherIdentity,\n        }),\n        `overlay creation for desk ${plan.deskId}`,\n      )\n    }\n\n    const child = launcher(plan.vmm.command, plan.vmm.args, { identity: plan.launcherIdentity })\n    const log = drainOutput(child)\n    const exit = watchExit(child)\n    let stream: Duplex\n    try {\n      stream = await connectWithRetry({\n        connect,\n        now,\n        socketPath: plan.vsock.socketPath,\n        port: guestAgentPort,\n        timeoutMs: connectTimeoutMs,\n        retryDelayMs: connectRetryDelayMs,\n        attemptTimeoutMs: handshakeTimeoutMs,\n        exited: exit,\n      })\n    } catch (error) {\n      await terminate(child, exit, killGraceMs)\n      const said = log.tail()\n      const detail = said === '' ? '' : ` The VMM said: ${said}`\n      throw error instanceof DeskError\n        ? new DeskError(`${error.message}${detail}`)\n        : new DeskError(\n            `Could not reach the guest agent for desk ${plan.deskId}: ${errorMessage(error)}${detail}`,\n          )\n    }\n    return createMachine({\n      deskId: plan.deskId,\n      child,\n      exit,\n      stream,\n      // The same path the first connection took, deliberately: a reconnect\n      // that skipped confirmGuest would adopt the very hollow handshake the\n      // boot path learned not to trust.\n      reconnect: (abandoned) =>\n        connectWithRetry({\n          connect,\n          now,\n          socketPath: plan.vsock.socketPath,\n          port: guestAgentPort,\n          timeoutMs: reconnectWindowMs,\n          retryDelayMs: reconnectRetryDelayMs,\n          maxRetryDelayMs: reconnectRetryDelayMs * RECONNECT_BACKOFF_CEILING,\n          attemptTimeoutMs: handshakeTimeoutMs,\n          exited: exit,\n          exitedMessage: `the VMM for desk ${plan.deskId} exited.`,\n          abandoned,\n        }),\n      reconnectWindowMs,\n      now,\n      idFactory,\n      requestTimeoutMs,\n      killGraceMs,\n    })\n  }\n\n  return { boot }\n}\n\n/** The default backend: real Cloud Hypervisor over a real vsock socket. */\nexport const cloudHypervisorBackend: DeskBackend = createCloudHypervisorBackend()\n\n/**\n * The machine, and the small state machine that keeps it connected.\n *\n * A vsock channel is not a fact the host learns once at boot — the transport\n * can lie about being connected, and it can go away mid-lease for reasons that\n * have nothing to do with the desk being unusable: the guest agent restarts,\n * the socat bridge drops, a transient vsock error, the guest wedges for a\n * moment. Treating any of those as terminal stranded the desk for the rest of\n * its lease with a perfectly healthy guest behind it, answering every call\n * with \"no longer connected\". So a live connection is something this machine\n * RE-ESTABLISHES:\n *\n *   live ──unexpected drop──▶ reconnecting ──confirmed guest──▶ live\n *     │                            │\n *     │                            └──window exhausted / VMM exited──▶ closed\n *     └──shutdown(), VMM already exited, protocol violation───────────▶ closed\n *\n * `closed` is terminal. Nothing reconnects out of it, which is what makes\n * `shutdown()` and a dead VMM final rather than the start of a retry loop.\n */\nfunction createMachine(options: {\n  deskId: string\n  child: ChildProcess\n  exit: ExitWatcher\n  stream: Duplex\n  /** Re-establishes the channel; resolves only once a guest has answered. */\n  reconnect: (abandoned: () => boolean) => Promise<Duplex>\n  reconnectWindowMs: number\n  now: () => number\n  idFactory: () => string\n  requestTimeoutMs: number\n  killGraceMs: number\n}): DeskMachine {\n  const { deskId, child, exit, now, idFactory, requestTimeoutMs, killGraceMs, reconnectWindowMs } =\n    options\n  const pending = new Map<\n    string,\n    { resolve: (result: unknown) => void; reject: (error: Error) => void; timer: NodeJS.Timeout }\n  >()\n  // Listeners live on the machine rather than on the socket, so a reconnect\n  // re-points the data path at the new stream and every subscriber keeps\n  // working without re-registering.\n  const listeners = new Set<(event: GuestEventMessage) => void>()\n  const watchers = new Set<(change: DeskConnectionChange) => void>()\n  let stream = options.stream\n  let state: 'live' | 'reconnecting' | 'closed' = 'live'\n  let reconnects = 0\n  let reconnecting: Promise<void> | null = null\n\n  function failAll(error: Error): void {\n    for (const entry of pending.values()) {\n      clearTimeout(entry.timer)\n      entry.reject(error)\n    }\n    pending.clear()\n  }\n\n  function announce(change: DeskConnectionChange): void {\n    for (const watcher of [...watchers]) watcher(change)\n  }\n\n  function close(error: DeskError, intentional: boolean): void {\n    if (state === 'closed') return\n    state = 'closed'\n    failAll(error)\n    stream.destroy()\n    // A desk the consumer asked to stop is not news; one that stopped on its\n    // own is the thing an operator needs to be told about.\n    if (!intentional) announce({ state: 'lost', deskId, reason: error.message })\n  }\n\n  function attach(next: Duplex): void {\n    stream = next\n    // Each connection decodes with its OWN decoder: a frame the drop cut in\n    // half must never be completed by the first bytes of its replacement.\n    const decoder = new FrameDecoder()\n    const current = () => stream === next && state !== 'closed'\n    const onData = (chunk: Buffer): void => {\n      if (!current()) return\n      let values: unknown[]\n      try {\n        values = decoder.push(chunk)\n      } catch (error) {\n        close(\n          new DeskError(`Guest agent protocol violation on desk ${deskId}: ${errorMessage(error)}`),\n          false,\n        )\n        return\n      }\n      for (const value of values) {\n        let message: HostBoundMessage\n        try {\n          message = parseHostBoundMessage(value)\n        } catch (error) {\n          close(\n            new DeskError(`Guest agent sent a malformed message on desk ${deskId}: ${errorMessage(error)}`),\n            false,\n          )\n          return\n        }\n        if ('id' in message) {\n          const entry = pending.get(message.id)\n          if (!entry) continue\n          pending.delete(message.id)\n          clearTimeout(entry.timer)\n          if (message.ok) entry.resolve(message.result)\n          else entry.reject(new DeskError(`Guest agent error on desk ${deskId}: ${message.error}`))\n        } else {\n          for (const listener of [...listeners]) listener(message)\n        }\n      }\n    }\n    next.on('data', onData)\n    next.once('close', () => {\n      drop(next, `the guest agent connection closed on desk ${deskId}`)\n    })\n    next.once('error', (error: Error) => {\n      drop(next, `the guest agent connection failed on desk ${deskId}: ${error.message}`)\n    })\n  }\n\n  function drop(from: Duplex, reason: string): void {\n    if (state !== 'live' || from !== stream) return\n    from.destroy()\n    if (exit.done) {\n      // A dead VMM is not a connection problem. There is no guest to get back\n      // to, and retrying against it forever only delays the fresh boot the\n      // desk actually needs.\n      close(new DeskError(`Desk ${deskId} is no longer connected: the VMM exited (${reason}).`), false)\n      return\n    }\n    state = 'reconnecting'\n    const lostAt = now()\n    // In-flight requests CANNOT be silently retried. Each of their frames\n    // already reached the guest, and whether the guest ran it before the\n    // channel went away is not knowable from here: an `exec` may have sent\n    // mail, a `click` may have landed. Replaying a side-effecting operation to\n    // paper over a blip is the wrong kind of resilience, so every one of them\n    // is told its fate is unknown and the caller decides.\n    failAll(\n      new DeskRequestFateUnknownError(\n        `Desk ${deskId} lost its guest agent connection while this request was in flight `\n          + `(${reason}); the guest may or may not have run it.`,\n      ),\n    )\n    reconnecting = restore(reason, lostAt)\n  }\n\n  /** Always resolves: callers await it to learn the outcome, not to be thrown at. */\n  async function restore(reason: string, lostAt: number): Promise<void> {\n    let next: Duplex\n    try {\n      next = await options.reconnect(() => state !== 'reconnecting')\n    } catch (error) {\n      close(\n        new DeskError(\n          `Desk ${deskId} lost its guest agent connection and could not get it back: ${errorMessage(error)}`,\n        ),\n        false,\n      )\n      return\n    }\n    if (state !== 'reconnecting') {\n      // shutdown() won the race while the replacement socket was coming up.\n      next.destroy()\n      return\n    }\n    attach(next)\n    state = 'live'\n    reconnects += 1\n    announce({ state: 'reconnected', deskId, reason, downtimeMs: now() - lostAt, reconnects })\n  }\n\n  attach(options.stream)\n\n  return {\n    deskId,\n    async request(command, requestOptions = {}) {\n      // A call that lands mid-reconnect waits for it rather than failing on\n      // the spot: the guest is usually back within seconds, and telling a\n      // caller a desk is gone when it is about to be fine is the bug this\n      // machine exists to end. The wait is bounded by the same window the\n      // reconnect itself is.\n      const waitUntil = now() + reconnectWindowMs\n      while (state === 'reconnecting') {\n        const attempt = reconnecting\n        if (!attempt || now() >= waitUntil) break\n        await attempt\n      }\n      if (state !== 'live') {\n        // This one never left the host, so — unlike a request that was in\n        // flight when the channel dropped — repeating it is safe.\n        throw new DeskError(`Desk ${deskId} is no longer connected.`)\n      }\n      const id = idFactory()\n      const timeoutMs = requestOptions.timeoutMs ?? requestTimeoutMs\n      const target = stream\n      return await new Promise<unknown>((resolvePromise, rejectPromise) => {\n        const timer = setTimeout(() => {\n          pending.delete(id)\n          rejectPromise(new DeskError(`Guest request ${command.op} timed out on desk ${deskId}.`))\n        }, timeoutMs)\n        timer.unref()\n        pending.set(id, { resolve: resolvePromise, reject: rejectPromise, timer })\n        target.write(encodeFrame({ ...command, id }))\n      })\n    },\n    subscribe(listener) {\n      listeners.add(listener)\n      return () => {\n        listeners.delete(listener)\n      }\n    },\n    onConnectionChange(listener) {\n      watchers.add(listener)\n      return () => {\n        watchers.delete(listener)\n      }\n    },\n    async shutdown() {\n      // Terminal by construction: `closed` is the state the reconnect loop\n      // checks, so an explicit shutdown can never be followed by a reconnect.\n      close(new DeskError(`Desk ${deskId} is shutting down.`), true)\n      await terminate(child, exit, killGraceMs)\n    },\n  }\n}\n\ninterface ExitWatcher {\n  done: boolean\n  promise: Promise<void>\n}\n\n/**\n * Read the VMM's stdout and stderr, and keep only the last few kilobytes.\n *\n * This is not for logging — it is load-bearing. The child is spawned with\n * both streams as PIPES, and a pipe nobody reads fills after about 64KB, at\n * which point the VMM BLOCKS on its next write. Cloud Hypervisor logs while\n * it runs, so an unread pipe freezes the guest partway through boot: the\n * process is alive, the disk is untouched, and the guest agent never reaches\n * vsock. Every symptom points at the image and none of them are its fault.\n *\n * Draining costs nothing and buys the tail of what the VMM said, which is the\n * difference between \"the VMM exited\" and knowing why.\n */\nfunction drainOutput(child: ChildProcess, limit = 8 * 1024): { tail: () => string } {\n  let buffered = ''\n  const absorb = (chunk: unknown) => {\n    buffered += String(chunk)\n    if (buffered.length > limit) buffered = buffered.slice(buffered.length - limit)\n  }\n  child.stdout?.on('data', absorb)\n  child.stderr?.on('data', absorb)\n  // A pipe that errors must not take the process down with it.\n  child.stdout?.on('error', () => undefined)\n  child.stderr?.on('error', () => undefined)\n  return { tail: () => buffered.trim() }\n}\n\nfunction watchExit(child: ChildProcess): ExitWatcher {\n  const watcher: ExitWatcher = { done: false, promise: Promise.resolve() }\n  watcher.promise = new Promise<void>((resolvePromise) => {\n    const settle = () => {\n      watcher.done = true\n      resolvePromise()\n    }\n    child.once('exit', settle)\n    child.once('error', settle)\n  })\n  return watcher\n}\n\nasync function terminate(child: ChildProcess, exit: ExitWatcher, killGraceMs: number): Promise<void> {\n  if (exit.done) return\n  child.kill('SIGTERM')\n  const forceKill = setTimeout(() => {\n    if (!exit.done) child.kill('SIGKILL')\n  }, killGraceMs)\n  forceKill.unref()\n  await exit.promise\n  clearTimeout(forceKill)\n}\n\nfunction runToCompletion(child: ChildProcess, label: string): Promise<void> {\n  return new Promise<void>((resolvePromise, rejectPromise) => {\n    let stderr = ''\n    child.stderr?.on('data', (chunk) => {\n      stderr += String(chunk)\n    })\n    child.once('error', (error) => {\n      rejectPromise(new DeskError(`${label} failed to start: ${error.message}`))\n    })\n    child.once('exit', (code, signal) => {\n      if (code === 0) {\n        resolvePromise()\n        return\n      }\n      const detail = stderr.trim()\n      rejectPromise(\n        new DeskError(\n          `${label} exited with code ${code ?? 'unknown'}`\n            + `${signal ? ` (${signal})` : ''}${detail ? `: ${detail}` : '.'}`,\n        ),\n      )\n    })\n  })\n}\n\n/**\n * Cloud Hypervisor exposes guest vsock ports through a host Unix socket with\n * a line-oriented preamble: the client writes `CONNECT <port>\\n` and the VMM\n * answers `OK <assigned>\\n` before the byte stream becomes the guest\n * connection. The VMM creates the socket during boot, so connection attempts\n * retry until the deadline.\n *\n * The same loop serves the first connection and every later reconnect, so a\n * reconnect gets `confirmGuest` too — a mid-lease reconnect that trusted the\n * banner would re-adopt exactly the hollow stream the boot path learned not to.\n */\nasync function connectWithRetry(options: {\n  connect: (socketPath: string) => Duplex\n  now: () => number\n  socketPath: string\n  port: number\n  timeoutMs: number\n  retryDelayMs: number\n  /** Ceiling the delay doubles toward; omitted keeps the delay constant. */\n  maxRetryDelayMs?: number\n  attemptTimeoutMs: number\n  exited: ExitWatcher\n  /** A dead VMM means something different at boot than it does mid-lease. */\n  exitedMessage?: string\n  /** Stops the loop early when the caller no longer wants the connection. */\n  abandoned?: () => boolean\n}): Promise<Duplex> {\n  const deadline = options.now() + options.timeoutMs\n  let lastFailure = 'the guest agent never answered'\n  let retryDelayMs = options.retryDelayMs\n  while (options.now() <= deadline) {\n    if (options.exited.done) {\n      throw new DeskError(options.exitedMessage ?? 'The VMM exited before the guest agent came up.')\n    }\n    if (options.abandoned?.() === true) {\n      throw new DeskError('the connection attempt was abandoned.')\n    }\n    try {\n      const stream = await attemptHandshake(\n        options.connect,\n        options.socketPath,\n        options.port,\n        options.attemptTimeoutMs,\n      )\n      try {\n        await confirmGuest(stream, options.attemptTimeoutMs)\n      } catch (error) {\n        stream.destroy()\n        throw error\n      }\n      return stream\n    } catch (error) {\n      lastFailure = errorMessage(error)\n    }\n    await delay(retryDelayMs)\n    if (options.maxRetryDelayMs !== undefined) {\n      retryDelayMs = Math.min(retryDelayMs * 2, options.maxRetryDelayMs)\n    }\n  }\n  throw new DeskError(\n    `Timed out connecting to the guest agent at ${options.socketPath}: ${lastFailure}`,\n  )\n}\n\n/**\n * One handshake attempt, which MUST settle.\n *\n * Cloud Hypervisor accepts a connection on the vsock socket whether or not\n * anything in the guest is listening on the port, and when nothing is it may\n * answer nothing at all: no reply, no error, no close. Without a deadline of\n * its own this promise then never settles — and because the caller awaits it\n * inside the retry loop, the loop stops iterating, the overall deadline is\n * never re-checked, and the boot hangs forever rather than failing. That is\n * indistinguishable from a wedged host and it is why every attempt is bounded\n * here as well as in aggregate.\n */\n/**\n * Prove a guest is behind the handshake by asking it something.\n *\n * Cloud Hypervisor answers `CONNECT <port>` with `OK` whether or not anything\n * in the guest is listening on that port, and only closes the socket a moment\n * later when it finds nobody there. A caller that trusts the banner therefore\n * \"connects\" to a guest that is still booting, gets a closed stream seconds\n * later, and — because a closed machine is not retried — leaves the desk dead\n * for as long as it is leased, with a healthy guest sitting behind it. So the\n * handshake is not the test; a reply is.\n */\nasync function confirmGuest(stream: Duplex, timeoutMs: number): Promise<void> {\n  const decoder = new FrameDecoder()\n  await new Promise<void>((resolvePromise, rejectPromise) => {\n    let settled = false\n    const finish = (error?: Error) => {\n      if (settled) return\n      settled = true\n      clearTimeout(timer)\n      stream.off('data', onData)\n      stream.off('close', onClose)\n      stream.off('error', finish)\n      if (error) rejectPromise(error)\n      else resolvePromise()\n    }\n    const timer = setTimeout(\n      () => finish(new DeskError('the guest agent did not answer the first request.')),\n      timeoutMs,\n    )\n    timer.unref?.()\n    const onClose = () =>\n      finish(new DeskError('the connection closed before the guest agent answered.'))\n    const onData = (chunk: Buffer) => {\n      let values: unknown[]\n      try {\n        values = decoder.push(chunk)\n      } catch (error) {\n        finish(error instanceof Error ? error : new Error(String(error)))\n        return\n      }\n      for (const value of values) {\n        // Anything at all proves a guest is there; the reply is parsed for\n        // real by the machine once it owns the stream.\n        if (value && typeof value === 'object') {\n          finish()\n          return\n        }\n      }\n    }\n    stream.on('data', onData)\n    stream.once('close', onClose)\n    stream.once('error', finish)\n    stream.write(encodeFrame({ id: 'hello', op: 'ping' }))\n  })\n}\n\nfunction attemptHandshake(\n  connect: (socketPath: string) => Duplex,\n  socketPath: string,\n  port: number,\n  attemptTimeoutMs: number,\n): Promise<Duplex> {\n  return new Promise<Duplex>((resolvePromise, rejectPromise) => {\n    let stream: Duplex\n    try {\n      stream = connect(socketPath)\n    } catch (error) {\n      rejectPromise(error instanceof Error ? error : new Error(String(error)))\n      return\n    }\n    let banner = ''\n    let settled = false\n    const timer = setTimeout(() => {\n      fail(new DeskError('vsock handshake went unanswered.'))\n    }, attemptTimeoutMs)\n    // An unref'd timer must not hold the process open on its own.\n    timer.unref?.()\n    const fail = (error: Error) => {\n      if (settled) return\n      settled = true\n      clearTimeout(timer)\n      stream.destroy()\n      rejectPromise(error)\n    }\n    const onData = (chunk: Buffer) => {\n      banner += chunk.toString('latin1')\n      const newline = banner.indexOf('\\n')\n      if (newline === -1) {\n        if (banner.length > HANDSHAKE_LINE_LIMIT) {\n          fail(new DeskError('vsock handshake reply exceeded the line limit.'))\n        }\n        return\n      }\n      const line = banner.slice(0, newline)\n      const rest = banner.slice(newline + 1)\n      stream.off('data', onData)\n      stream.off('error', fail)\n      if (!line.startsWith('OK ')) {\n        fail(new DeskError(`vsock handshake was refused: ${line}`))\n        return\n      }\n      settled = true\n      clearTimeout(timer)\n      if (rest.length > 0) stream.unshift(Buffer.from(rest, 'latin1'))\n      resolvePromise(stream)\n    }\n    stream.on('data', onData)\n    stream.once('error', fail)\n    // A close before the banner is a refusal, not a hang.\n    stream.once('close', () => fail(new DeskError('vsock handshake closed before a reply.')))\n    stream.write(`CONNECT ${port}\\n`)\n  })\n}\n\nfunction defaultLauncher(\n  command: string,\n  args: readonly string[],\n  options: { identity?: DeskLauncherIdentity },\n): ChildProcess {\n  return spawn(command, [...args], {\n    stdio: ['ignore', 'pipe', 'pipe'],\n    uid: options.identity?.uid,\n    gid: options.identity?.gid,\n  })\n}\n\nfunction defaultConnect(socketPath: string): Duplex {\n  return createConnection(socketPath)\n}\n\nfunction delay(ms: number): Promise<void> {\n  return new Promise<void>((resolvePromise) => {\n    const timer = setTimeout(resolvePromise, ms)\n    timer.unref()\n  })\n}\n\nfunction errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error)\n}\n"]}
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The backend port and its default Cloud Hypervisor implementation.\n *\n * `DeskBackend` is the seam that keeps the package testable without a\n * hypervisor: the host asks a backend to boot a `DeskLaunchPlan` and gets a\n * `DeskMachine` — a request/response channel to the in-guest agent plus an\n * event subscription. CI and non-KVM developer machines inject an in-memory\n * fake; production uses `cloudHypervisorBackend`, whose process-spawning glue\n * is deliberately thin because everything that can be pure lives in the plan\n * builder and the protocol module.\n */\nimport { spawn, type ChildProcess } from 'node:child_process'\nimport { randomUUID } from 'node:crypto'\nimport { request as httpRequest } from 'node:http'\nimport { createConnection } from 'node:net'\nimport { Buffer } from 'node:buffer'\nimport type { Duplex } from 'node:stream'\nimport { DeskError, type DeskLaunchPlan, type DeskLauncherIdentity } from './plan'\nimport {\n  encodeFrame,\n  FrameDecoder,\n  GUEST_AGENT_VSOCK_PORT,\n  parseHostBoundMessage,\n  type GuestCommand,\n  type GuestEventMessage,\n  type HostBoundMessage,\n} from './protocol'\n\n/**\n * A request that was in flight when the guest connection dropped.\n *\n * Distinct from a plain `DeskError` because the caller's next move is\n * different: this request may ALREADY HAVE RUN. The frame reached the guest,\n * and whether the guest executed it before the channel went away is not\n * knowable from the host. An `exec` may have sent mail; a `click` may have\n * landed. So the transport refuses to guess — it names the ambiguity and lets\n * the caller decide whether the operation is safe to repeat. Anything that\n * rejects with a plain `DeskError` instead never reached the guest at all.\n */\nexport class DeskRequestFateUnknownError extends DeskError {\n  override readonly name: string = 'DeskRequestFateUnknownError'\n}\n\n/**\n * What happened to the transport underneath a machine.\n *\n * `reconnected` means the host lost the guest channel mid-lease and got it\n * back; the desk is usable again. It is NOT a promise that the guest is\n * unchanged — see the note on `onConnectionChange`. `lost` means it will not\n * come back on this VM and the desk needs a fresh boot.\n */\nexport type DeskConnectionChange =\n  | {\n      state: 'reconnected'\n      deskId: string\n      /** How the previous connection went away. */\n      reason: string\n      /** Wall-clock time the desk spent with no channel to its guest. */\n      downtimeMs: number\n      /** Reconnects this machine has survived, including this one. */\n      reconnects: number\n    }\n  | {\n      state: 'lost'\n      deskId: string\n      /** Why it is gone for good: the VMM exited, or the window ran out. */\n      reason: string\n    }\n\n/** A booted microVM as the host sees it: one desk, one guest-agent channel. */\nexport interface DeskMachine {\n  readonly deskId: string\n  /**\n   * Send one request to the in-guest agent and await its correlated result.\n   *\n   * Rejects with `DeskError` when the guest reports an error, the request\n   * times out, or the connection is gone for good — in that last case the\n   * request never left the host, so repeating it is safe.\n   *\n   * A connection lost mid-lease is re-established rather than fatal: a call\n   * that arrives while that is happening WAITS for it instead of failing.\n   * A call that was already in flight when the channel dropped rejects with\n   * `DeskRequestFateUnknownError`, because the host cannot tell whether the\n   * guest ran it.\n   */\n  request(command: GuestCommand, options?: { timeoutMs?: number }): Promise<unknown>\n  /**\n   * Subscribe to unsolicited guest events (job exits, frames, focus changes).\n   *\n   * Subscriptions belong to the machine, not to the socket under it, so they\n   * survive a reconnect. What does NOT survive is the guest's own capture\n   * state: a guest agent that restarted has no screen, no frame encoder and\n   * no video encoder, and a subscriber will simply stop receiving. Watch\n   * `onConnectionChange` to notice.\n   */\n  subscribe(listener: (event: GuestEventMessage) => void): () => void\n  /**\n   * Watch the transport under this machine.\n   *\n   * Optional: a backend whose channel cannot drop has nothing to report. The\n   * default backend reports every reconnect, because a reconnect that leaves\n   * no trace turns a guest agent restarting every few minutes into a desk that\n   * misbehaves for reasons nobody can find.\n   */\n  onConnectionChange?(listener: (change: DeskConnectionChange) => void): () => void\n  /** Stop the VM. Idempotent; resolves once the VMM process has exited. */\n  shutdown(): Promise<void>\n  /**\n   * Park the VM with its memory, so resuming continues the process tree.\n   *\n   * Optional: a backend with no snapshot facility simply does not offer it, and\n   * the host falls back to `shutdown()`. Pauses the guest, writes a snapshot to\n   * `snapshotDir`, then stops the VMM — and resolves only once all three have\n   * happened, because a caller that believed a snapshot exists when it does not\n   * would later refuse to boot the desk at all.\n   *\n   * The caller is responsible for quiescing the guest filesystem first. A paused\n   * guest still holds dirty pages that exist only in the snapshot, so a disk\n   * parked without a prior `sync` is consistent only *with that snapshot* —\n   * which matters the moment the snapshot is discarded.\n   */\n  park?(snapshotDir: string): Promise<void>\n}\n\nexport interface DeskBootHooks {\n  /**\n   * Called on a restore, after the snapshot has been read back and before the\n   * guest is allowed to run.\n   *\n   * This is the window in which the snapshot must be destroyed. A memory image\n   * is valid only against the disk it was taken with, so once the guest resumes\n   * and writes, any surviving snapshot describes a past that no longer matches —\n   * and replaying it later would corrupt the desk. Restoring paused and\n   * invalidating here is what makes that impossible rather than unlikely.\n   *\n   * Throwing aborts the restore: the VM is stopped and the caller is free to\n   * cold boot, which is safe because a paused guest has written nothing.\n   */\n  onRestored?: () => Promise<void>\n}\n\nexport interface DeskBackend {\n  boot(plan: DeskLaunchPlan, hooks?: DeskBootHooks): Promise<DeskMachine>\n}\n\nexport type DeskProcessLauncher = (\n  command: string,\n  args: readonly string[],\n  options: { identity?: DeskLauncherIdentity },\n) => ChildProcess\n\nexport interface CloudHypervisorBackendOptions {\n  /** Spawns the VMM and image tooling; injectable for tests. */\n  launcher?: DeskProcessLauncher\n  /** Opens the host side of the vsock Unix socket; injectable for tests. */\n  connect?: (socketPath: string) => Duplex\n  platform?: NodeJS.Platform\n  /**\n   * Clock behind every connect and reconnect deadline. Injectable for the same\n   * reason `DeskHostOptions.now` is: a test drives a window to its end by\n   * moving the clock, rather than sleeping for it and hoping the machine it\n   * runs on is fast enough.\n   */\n  now?: () => number\n  idFactory?: () => string\n  requestTimeoutMs?: number\n  connectTimeoutMs?: number\n  connectRetryDelayMs?: number\n  /** Bound on a single handshake attempt; see attemptHandshake. */\n  handshakeTimeoutMs?: number\n  /**\n   * How long a machine keeps trying to get its guest channel back after an\n   * unexpected drop before declaring the desk lost. Bounded on purpose: the\n   * VMM is still alive so a reconnect is cheap and usually fast, but retrying\n   * forever against a guest that is never coming back is worse than failing.\n   */\n  reconnectWindowMs?: number\n  /**\n   * First delay between reconnect attempts. It doubles toward a ceiling, so\n   * this is the fast first poll rather than the steady rate. Separate from\n   * `connectRetryDelayMs`, which is sized for a guest that is still cold\n   * booting; here the guest was up a moment ago.\n   */\n  reconnectRetryDelayMs?: number\n  killGraceMs?: number\n  guestAgentPort?: number\n}\n\nconst DEFAULT_REQUEST_TIMEOUT_MS = 30_000\nconst DEFAULT_CONNECT_TIMEOUT_MS = 20_000\nconst DEFAULT_CONNECT_RETRY_DELAY_MS = 100\nconst DEFAULT_HANDSHAKE_TIMEOUT_MS = 5_000\nconst DEFAULT_RECONNECT_WINDOW_MS = 30_000\nconst DEFAULT_RECONNECT_RETRY_DELAY_MS = 250\n/**\n * How far the reconnect delay is allowed to double. A guest agent that systemd\n * is restarting is not helped by being hammered four times a second for the\n * whole window, and an unbounded doubling would spend most of the window\n * asleep after two failures.\n */\nconst RECONNECT_BACKOFF_CEILING = 8\nconst DEFAULT_KILL_GRACE_MS = 2_000\nconst HANDSHAKE_LINE_LIMIT = 128\n\nexport function createCloudHypervisorBackend(\n  options: CloudHypervisorBackendOptions = {},\n): DeskBackend {\n  const launcher = options.launcher ?? defaultLauncher\n  const connect = options.connect ?? defaultConnect\n  const platform = options.platform ?? process.platform\n  const now = options.now ?? Date.now\n  const idFactory = options.idFactory ?? randomUUID\n  const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS\n  const connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS\n  const connectRetryDelayMs = options.connectRetryDelayMs ?? DEFAULT_CONNECT_RETRY_DELAY_MS\n  const handshakeTimeoutMs = options.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS\n  const reconnectWindowMs = options.reconnectWindowMs ?? DEFAULT_RECONNECT_WINDOW_MS\n  const reconnectRetryDelayMs = options.reconnectRetryDelayMs ?? DEFAULT_RECONNECT_RETRY_DELAY_MS\n  const killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS\n  const guestAgentPort = options.guestAgentPort ?? GUEST_AGENT_VSOCK_PORT\n\n  async function boot(plan: DeskLaunchPlan, hooks?: DeskBootHooks): Promise<DeskMachine> {\n    if (platform !== 'linux') {\n      throw new DeskError(`The AppKit desk requires Linux; received ${platform}.`)\n    }\n    if (plan.overlay.create) {\n      await runToCompletion(\n        launcher(plan.overlay.create.command, plan.overlay.create.args, {\n          identity: plan.launcherIdentity,\n        }),\n        `overlay creation for desk ${plan.deskId}`,\n      )\n    }\n\n    const child = launcher(plan.vmm.command, plan.vmm.args, { identity: plan.launcherIdentity })\n    const log = drainOutput(child)\n    const exit = watchExit(child)\n\n    // A restored guest comes back PAUSED (see the `resume=false` reasoning in\n    // the plan). Three things have to happen in this order and nowhere else:\n    // prove the restore finished, let the caller destroy the snapshot while the\n    // guest still cannot write, then start it.\n    if (plan.snapshot.restoring) {\n      try {\n        await waitForVmm(vmmApi, plan.api.socketPath, { now, exited: exit, timeoutMs: connectTimeoutMs })\n        await hooks?.onRestored?.()\n        await vmmApi(plan.api.socketPath, '/api/v1/vm.resume')\n      } catch (error) {\n        await terminate(child, exit, killGraceMs)\n        const said = log.tail()\n        const detail = said === '' ? '' : ` The VMM said: ${said}`\n        throw new DeskError(\n          `Desk ${plan.deskId} could not be restored from ${plan.snapshot.dir}: ${errorMessage(error)}${detail}`,\n        )\n      }\n    }\n\n    let stream: Duplex\n    try {\n      stream = await connectWithRetry({\n        connect,\n        now,\n        socketPath: plan.vsock.socketPath,\n        port: guestAgentPort,\n        timeoutMs: connectTimeoutMs,\n        retryDelayMs: connectRetryDelayMs,\n        attemptTimeoutMs: handshakeTimeoutMs,\n        exited: exit,\n      })\n    } catch (error) {\n      await terminate(child, exit, killGraceMs)\n      const said = log.tail()\n      const detail = said === '' ? '' : ` The VMM said: ${said}`\n      throw error instanceof DeskError\n        ? new DeskError(`${error.message}${detail}`)\n        : new DeskError(\n            `Could not reach the guest agent for desk ${plan.deskId}: ${errorMessage(error)}${detail}`,\n          )\n    }\n    return createMachine({\n      deskId: plan.deskId,\n      child,\n      exit,\n      stream,\n      // The same path the first connection took, deliberately: a reconnect\n      // that skipped confirmGuest would adopt the very hollow handshake the\n      // boot path learned not to trust.\n      reconnect: (abandoned) =>\n        connectWithRetry({\n          connect,\n          now,\n          socketPath: plan.vsock.socketPath,\n          port: guestAgentPort,\n          timeoutMs: reconnectWindowMs,\n          retryDelayMs: reconnectRetryDelayMs,\n          maxRetryDelayMs: reconnectRetryDelayMs * RECONNECT_BACKOFF_CEILING,\n          attemptTimeoutMs: handshakeTimeoutMs,\n          exited: exit,\n          exitedMessage: `the VMM for desk ${plan.deskId} exited.`,\n          abandoned,\n        }),\n      reconnectWindowMs,\n      now,\n      idFactory,\n      requestTimeoutMs,\n      killGraceMs,\n      apiSocketPath: plan.api.socketPath,\n      vmmApi,\n    })\n  }\n\n  return { boot }\n}\n\n/**\n * Cloud Hypervisor's control plane: HTTP/1.1 over the `--api-socket` Unix\n * socket. The plan has always created that socket; until now nothing spoke to\n * it, because stopping a VM needed nothing more than killing the process.\n *\n * Pausing and snapshotting do need it, and `ch-remote` — the tool that usually\n * does this — is not in the runner image. Writing the two requests by hand is a\n * smaller change than adding a binary to the image, and keeps the whole\n * lifecycle inside one process that already owns the socket path.\n */\nexport type VmmApiCall = (\n  socketPath: string,\n  path: string,\n  body?: Record<string, unknown>,\n  method?: 'PUT' | 'GET',\n) => Promise<void>\n\nconst vmmApi: VmmApiCall = async (socketPath, path, body, method = 'PUT') => {\n  const payload = body === undefined ? undefined : Buffer.from(JSON.stringify(body), 'utf8')\n  await new Promise<void>((resolve, reject) => {\n    const request = httpRequest(\n      {\n        socketPath,\n        path,\n        method,\n        headers: {\n          ...(payload ? { 'content-type': 'application/json', 'content-length': String(payload.length) } : {}),\n        },\n      },\n      (response) => {\n        // CH answers 204 with no body on success. Drain regardless: an unread\n        // response keeps the socket open and the next call queues behind it.\n        const chunks: Buffer[] = []\n        response.on('data', (chunk: Buffer) => chunks.push(chunk))\n        response.on('end', () => {\n          const status = response.statusCode ?? 0\n          if (status >= 200 && status < 300) {\n            resolve()\n            return\n          }\n          const said = Buffer.concat(chunks).toString('utf8').trim().slice(0, 400)\n          reject(new DeskError(`${path} returned ${status}${said === '' ? '' : `: ${said}`}`))\n        })\n      },\n    )\n    request.on('error', (error) => reject(new DeskError(`${path} failed: ${errorMessage(error)}`)))\n    if (payload) request.write(payload)\n    request.end()\n  })\n}\n\n/**\n * Wait until the VMM answers its control socket.\n *\n * On a restore this is also the only honest signal that the snapshot was read\n * back: Cloud Hypervisor creates the API socket early but does not serve\n * `vm.info` until it holds a VM, so a successful call means the restore\n * completed rather than merely that the process started. A VMM that exits\n * instead — a corrupt snapshot, a config the host can no longer satisfy — stops\n * the wait immediately rather than burning the whole timeout.\n */\nasync function waitForVmm(\n  call: VmmApiCall,\n  socketPath: string,\n  options: { now: () => number; exited: ExitWatcher; timeoutMs: number; retryDelayMs?: number },\n): Promise<void> {\n  const deadline = options.now() + options.timeoutMs\n  const retryDelayMs = options.retryDelayMs ?? 50\n  let lastFailure = 'it never answered'\n  for (;;) {\n    if (options.exited.done) throw new DeskError(`the VMM exited before it served its control socket`)\n    try {\n      await call(socketPath, '/api/v1/vm.info', undefined, 'GET')\n      return\n    } catch (error) {\n      lastFailure = errorMessage(error)\n    }\n    if (options.now() >= deadline) {\n      throw new DeskError(`the VMM did not answer ${socketPath} in ${options.timeoutMs}ms: ${lastFailure}`)\n    }\n    await new Promise((resolve) => setTimeout(resolve, retryDelayMs))\n  }\n}\n\n/** The default backend: real Cloud Hypervisor over a real vsock socket. */\nexport const cloudHypervisorBackend: DeskBackend = createCloudHypervisorBackend()\n\n/**\n * The machine, and the small state machine that keeps it connected.\n *\n * A vsock channel is not a fact the host learns once at boot — the transport\n * can lie about being connected, and it can go away mid-lease for reasons that\n * have nothing to do with the desk being unusable: the guest agent restarts,\n * the socat bridge drops, a transient vsock error, the guest wedges for a\n * moment. Treating any of those as terminal stranded the desk for the rest of\n * its lease with a perfectly healthy guest behind it, answering every call\n * with \"no longer connected\". So a live connection is something this machine\n * RE-ESTABLISHES:\n *\n *   live ──unexpected drop──▶ reconnecting ──confirmed guest──▶ live\n *     │                            │\n *     │                            └──window exhausted / VMM exited──▶ closed\n *     └──shutdown(), VMM already exited, protocol violation───────────▶ closed\n *\n * `closed` is terminal. Nothing reconnects out of it, which is what makes\n * `shutdown()` and a dead VMM final rather than the start of a retry loop.\n */\nfunction createMachine(options: {\n  deskId: string\n  child: ChildProcess\n  exit: ExitWatcher\n  stream: Duplex\n  /** Re-establishes the channel; resolves only once a guest has answered. */\n  reconnect: (abandoned: () => boolean) => Promise<Duplex>\n  reconnectWindowMs: number\n  now: () => number\n  idFactory: () => string\n  requestTimeoutMs: number\n  killGraceMs: number\n  /** Cloud Hypervisor's control socket, for pause and snapshot. */\n  apiSocketPath: string\n  vmmApi: VmmApiCall\n}): DeskMachine {\n  const { deskId, child, exit, now, idFactory, requestTimeoutMs, killGraceMs, reconnectWindowMs } =\n    options\n  const pending = new Map<\n    string,\n    { resolve: (result: unknown) => void; reject: (error: Error) => void; timer: NodeJS.Timeout }\n  >()\n  // Listeners live on the machine rather than on the socket, so a reconnect\n  // re-points the data path at the new stream and every subscriber keeps\n  // working without re-registering.\n  const listeners = new Set<(event: GuestEventMessage) => void>()\n  const watchers = new Set<(change: DeskConnectionChange) => void>()\n  let stream = options.stream\n  let state: 'live' | 'reconnecting' | 'closed' = 'live'\n  let reconnects = 0\n  let reconnecting: Promise<void> | null = null\n\n  function failAll(error: Error): void {\n    for (const entry of pending.values()) {\n      clearTimeout(entry.timer)\n      entry.reject(error)\n    }\n    pending.clear()\n  }\n\n  function announce(change: DeskConnectionChange): void {\n    for (const watcher of [...watchers]) watcher(change)\n  }\n\n  function close(error: DeskError, intentional: boolean): void {\n    if (state === 'closed') return\n    state = 'closed'\n    failAll(error)\n    stream.destroy()\n    // A desk the consumer asked to stop is not news; one that stopped on its\n    // own is the thing an operator needs to be told about.\n    if (!intentional) announce({ state: 'lost', deskId, reason: error.message })\n  }\n\n  function attach(next: Duplex): void {\n    stream = next\n    // Each connection decodes with its OWN decoder: a frame the drop cut in\n    // half must never be completed by the first bytes of its replacement.\n    const decoder = new FrameDecoder()\n    const current = () => stream === next && state !== 'closed'\n    const onData = (chunk: Buffer): void => {\n      if (!current()) return\n      let values: unknown[]\n      try {\n        values = decoder.push(chunk)\n      } catch (error) {\n        close(\n          new DeskError(`Guest agent protocol violation on desk ${deskId}: ${errorMessage(error)}`),\n          false,\n        )\n        return\n      }\n      for (const value of values) {\n        let message: HostBoundMessage\n        try {\n          message = parseHostBoundMessage(value)\n        } catch (error) {\n          close(\n            new DeskError(`Guest agent sent a malformed message on desk ${deskId}: ${errorMessage(error)}`),\n            false,\n          )\n          return\n        }\n        if ('id' in message) {\n          const entry = pending.get(message.id)\n          if (!entry) continue\n          pending.delete(message.id)\n          clearTimeout(entry.timer)\n          if (message.ok) entry.resolve(message.result)\n          else entry.reject(new DeskError(`Guest agent error on desk ${deskId}: ${message.error}`))\n        } else {\n          for (const listener of [...listeners]) listener(message)\n        }\n      }\n    }\n    next.on('data', onData)\n    next.once('close', () => {\n      drop(next, `the guest agent connection closed on desk ${deskId}`)\n    })\n    next.once('error', (error: Error) => {\n      drop(next, `the guest agent connection failed on desk ${deskId}: ${error.message}`)\n    })\n  }\n\n  function drop(from: Duplex, reason: string): void {\n    if (state !== 'live' || from !== stream) return\n    from.destroy()\n    if (exit.done) {\n      // A dead VMM is not a connection problem. There is no guest to get back\n      // to, and retrying against it forever only delays the fresh boot the\n      // desk actually needs.\n      close(new DeskError(`Desk ${deskId} is no longer connected: the VMM exited (${reason}).`), false)\n      return\n    }\n    state = 'reconnecting'\n    const lostAt = now()\n    // In-flight requests CANNOT be silently retried. Each of their frames\n    // already reached the guest, and whether the guest ran it before the\n    // channel went away is not knowable from here: an `exec` may have sent\n    // mail, a `click` may have landed. Replaying a side-effecting operation to\n    // paper over a blip is the wrong kind of resilience, so every one of them\n    // is told its fate is unknown and the caller decides.\n    failAll(\n      new DeskRequestFateUnknownError(\n        `Desk ${deskId} lost its guest agent connection while this request was in flight `\n          + `(${reason}); the guest may or may not have run it.`,\n      ),\n    )\n    reconnecting = restore(reason, lostAt)\n  }\n\n  /** Always resolves: callers await it to learn the outcome, not to be thrown at. */\n  async function restore(reason: string, lostAt: number): Promise<void> {\n    let next: Duplex\n    try {\n      next = await options.reconnect(() => state !== 'reconnecting')\n    } catch (error) {\n      close(\n        new DeskError(\n          `Desk ${deskId} lost its guest agent connection and could not get it back: ${errorMessage(error)}`,\n        ),\n        false,\n      )\n      return\n    }\n    if (state !== 'reconnecting') {\n      // shutdown() won the race while the replacement socket was coming up.\n      next.destroy()\n      return\n    }\n    attach(next)\n    state = 'live'\n    reconnects += 1\n    announce({ state: 'reconnected', deskId, reason, downtimeMs: now() - lostAt, reconnects })\n  }\n\n  attach(options.stream)\n\n  return {\n    deskId,\n    async request(command, requestOptions = {}) {\n      // A call that lands mid-reconnect waits for it rather than failing on\n      // the spot: the guest is usually back within seconds, and telling a\n      // caller a desk is gone when it is about to be fine is the bug this\n      // machine exists to end. The wait is bounded by the same window the\n      // reconnect itself is.\n      const waitUntil = now() + reconnectWindowMs\n      while (state === 'reconnecting') {\n        const attempt = reconnecting\n        if (!attempt || now() >= waitUntil) break\n        await attempt\n      }\n      if (state !== 'live') {\n        // This one never left the host, so — unlike a request that was in\n        // flight when the channel dropped — repeating it is safe.\n        throw new DeskError(`Desk ${deskId} is no longer connected.`)\n      }\n      const id = idFactory()\n      const timeoutMs = requestOptions.timeoutMs ?? requestTimeoutMs\n      const target = stream\n      return await new Promise<unknown>((resolvePromise, rejectPromise) => {\n        const timer = setTimeout(() => {\n          pending.delete(id)\n          rejectPromise(new DeskError(`Guest request ${command.op} timed out on desk ${deskId}.`))\n        }, timeoutMs)\n        timer.unref()\n        pending.set(id, { resolve: resolvePromise, reject: rejectPromise, timer })\n        target.write(encodeFrame({ ...command, id }))\n      })\n    },\n    subscribe(listener) {\n      listeners.add(listener)\n      return () => {\n        listeners.delete(listener)\n      }\n    },\n    onConnectionChange(listener) {\n      watchers.add(listener)\n      return () => {\n        watchers.delete(listener)\n      }\n    },\n    async shutdown() {\n      // Terminal by construction: `closed` is the state the reconnect loop\n      // checks, so an explicit shutdown can never be followed by a reconnect.\n      close(new DeskError(`Desk ${deskId} is shutting down.`), true)\n      await terminate(child, exit, killGraceMs)\n    },\n    async park(snapshotDir: string) {\n      // Close the guest channel FIRST. Pausing a VM strands whatever was in\n      // flight on the vsock, and a reconnect attempt against a paused guest\n      // would burn the whole reconnect window before giving up — so the channel\n      // is made terminal before the VM stops answering, exactly as shutdown\n      // does it.\n      close(new DeskError(`Desk ${deskId} is being parked.`), true)\n      try {\n        await options.vmmApi(options.apiSocketPath, '/api/v1/vm.pause')\n        await options.vmmApi(options.apiSocketPath, '/api/v1/vm.snapshot', {\n          // Three slashes: `file://` plus an absolute path. CH rejects a\n          // destination_url it cannot parse, and the directory must already\n          // exist — it writes the config and memory files into it.\n          destination_url: `file://${snapshotDir}`,\n        })\n      } catch (error) {\n        // The VM is paused and there is no usable snapshot, which is the one\n        // state nothing downstream can interpret. Stop the VMM so the desk is\n        // plainly off, and say why — the caller falls back to a cold boot, and\n        // the disk is still consistent because the guest was synced before this.\n        await terminate(child, exit, killGraceMs)\n        throw error instanceof DeskError\n          ? new DeskError(`Desk ${deskId} could not be parked with its memory: ${error.message}`)\n          : new DeskError(`Desk ${deskId} could not be parked with its memory: ${errorMessage(error)}`)\n      }\n      await terminate(child, exit, killGraceMs)\n    },\n  }\n}\n\ninterface ExitWatcher {\n  done: boolean\n  promise: Promise<void>\n}\n\n/**\n * Read the VMM's stdout and stderr, and keep only the last few kilobytes.\n *\n * This is not for logging — it is load-bearing. The child is spawned with\n * both streams as PIPES, and a pipe nobody reads fills after about 64KB, at\n * which point the VMM BLOCKS on its next write. Cloud Hypervisor logs while\n * it runs, so an unread pipe freezes the guest partway through boot: the\n * process is alive, the disk is untouched, and the guest agent never reaches\n * vsock. Every symptom points at the image and none of them are its fault.\n *\n * Draining costs nothing and buys the tail of what the VMM said, which is the\n * difference between \"the VMM exited\" and knowing why.\n */\nfunction drainOutput(child: ChildProcess, limit = 8 * 1024): { tail: () => string } {\n  let buffered = ''\n  const absorb = (chunk: unknown) => {\n    buffered += String(chunk)\n    if (buffered.length > limit) buffered = buffered.slice(buffered.length - limit)\n  }\n  child.stdout?.on('data', absorb)\n  child.stderr?.on('data', absorb)\n  // A pipe that errors must not take the process down with it.\n  child.stdout?.on('error', () => undefined)\n  child.stderr?.on('error', () => undefined)\n  return { tail: () => buffered.trim() }\n}\n\nfunction watchExit(child: ChildProcess): ExitWatcher {\n  const watcher: ExitWatcher = { done: false, promise: Promise.resolve() }\n  watcher.promise = new Promise<void>((resolvePromise) => {\n    const settle = () => {\n      watcher.done = true\n      resolvePromise()\n    }\n    child.once('exit', settle)\n    child.once('error', settle)\n  })\n  return watcher\n}\n\nasync function terminate(child: ChildProcess, exit: ExitWatcher, killGraceMs: number): Promise<void> {\n  if (exit.done) return\n  child.kill('SIGTERM')\n  const forceKill = setTimeout(() => {\n    if (!exit.done) child.kill('SIGKILL')\n  }, killGraceMs)\n  forceKill.unref()\n  await exit.promise\n  clearTimeout(forceKill)\n}\n\nfunction runToCompletion(child: ChildProcess, label: string): Promise<void> {\n  return new Promise<void>((resolvePromise, rejectPromise) => {\n    let stderr = ''\n    child.stderr?.on('data', (chunk) => {\n      stderr += String(chunk)\n    })\n    child.once('error', (error) => {\n      rejectPromise(new DeskError(`${label} failed to start: ${error.message}`))\n    })\n    child.once('exit', (code, signal) => {\n      if (code === 0) {\n        resolvePromise()\n        return\n      }\n      const detail = stderr.trim()\n      rejectPromise(\n        new DeskError(\n          `${label} exited with code ${code ?? 'unknown'}`\n            + `${signal ? ` (${signal})` : ''}${detail ? `: ${detail}` : '.'}`,\n        ),\n      )\n    })\n  })\n}\n\n/**\n * Cloud Hypervisor exposes guest vsock ports through a host Unix socket with\n * a line-oriented preamble: the client writes `CONNECT <port>\\n` and the VMM\n * answers `OK <assigned>\\n` before the byte stream becomes the guest\n * connection. The VMM creates the socket during boot, so connection attempts\n * retry until the deadline.\n *\n * The same loop serves the first connection and every later reconnect, so a\n * reconnect gets `confirmGuest` too — a mid-lease reconnect that trusted the\n * banner would re-adopt exactly the hollow stream the boot path learned not to.\n */\nasync function connectWithRetry(options: {\n  connect: (socketPath: string) => Duplex\n  now: () => number\n  socketPath: string\n  port: number\n  timeoutMs: number\n  retryDelayMs: number\n  /** Ceiling the delay doubles toward; omitted keeps the delay constant. */\n  maxRetryDelayMs?: number\n  attemptTimeoutMs: number\n  exited: ExitWatcher\n  /** A dead VMM means something different at boot than it does mid-lease. */\n  exitedMessage?: string\n  /** Stops the loop early when the caller no longer wants the connection. */\n  abandoned?: () => boolean\n}): Promise<Duplex> {\n  const deadline = options.now() + options.timeoutMs\n  let lastFailure = 'the guest agent never answered'\n  let retryDelayMs = options.retryDelayMs\n  while (options.now() <= deadline) {\n    if (options.exited.done) {\n      throw new DeskError(options.exitedMessage ?? 'The VMM exited before the guest agent came up.')\n    }\n    if (options.abandoned?.() === true) {\n      throw new DeskError('the connection attempt was abandoned.')\n    }\n    try {\n      const stream = await attemptHandshake(\n        options.connect,\n        options.socketPath,\n        options.port,\n        options.attemptTimeoutMs,\n      )\n      try {\n        await confirmGuest(stream, options.attemptTimeoutMs)\n      } catch (error) {\n        stream.destroy()\n        throw error\n      }\n      return stream\n    } catch (error) {\n      lastFailure = errorMessage(error)\n    }\n    await delay(retryDelayMs)\n    if (options.maxRetryDelayMs !== undefined) {\n      retryDelayMs = Math.min(retryDelayMs * 2, options.maxRetryDelayMs)\n    }\n  }\n  throw new DeskError(\n    `Timed out connecting to the guest agent at ${options.socketPath}: ${lastFailure}`,\n  )\n}\n\n/**\n * One handshake attempt, which MUST settle.\n *\n * Cloud Hypervisor accepts a connection on the vsock socket whether or not\n * anything in the guest is listening on the port, and when nothing is it may\n * answer nothing at all: no reply, no error, no close. Without a deadline of\n * its own this promise then never settles — and because the caller awaits it\n * inside the retry loop, the loop stops iterating, the overall deadline is\n * never re-checked, and the boot hangs forever rather than failing. That is\n * indistinguishable from a wedged host and it is why every attempt is bounded\n * here as well as in aggregate.\n */\n/**\n * Prove a guest is behind the handshake by asking it something.\n *\n * Cloud Hypervisor answers `CONNECT <port>` with `OK` whether or not anything\n * in the guest is listening on that port, and only closes the socket a moment\n * later when it finds nobody there. A caller that trusts the banner therefore\n * \"connects\" to a guest that is still booting, gets a closed stream seconds\n * later, and — because a closed machine is not retried — leaves the desk dead\n * for as long as it is leased, with a healthy guest sitting behind it. So the\n * handshake is not the test; a reply is.\n */\nasync function confirmGuest(stream: Duplex, timeoutMs: number): Promise<void> {\n  const decoder = new FrameDecoder()\n  await new Promise<void>((resolvePromise, rejectPromise) => {\n    let settled = false\n    const finish = (error?: Error) => {\n      if (settled) return\n      settled = true\n      clearTimeout(timer)\n      stream.off('data', onData)\n      stream.off('close', onClose)\n      stream.off('error', finish)\n      if (error) rejectPromise(error)\n      else resolvePromise()\n    }\n    const timer = setTimeout(\n      () => finish(new DeskError('the guest agent did not answer the first request.')),\n      timeoutMs,\n    )\n    timer.unref?.()\n    const onClose = () =>\n      finish(new DeskError('the connection closed before the guest agent answered.'))\n    const onData = (chunk: Buffer) => {\n      let values: unknown[]\n      try {\n        values = decoder.push(chunk)\n      } catch (error) {\n        finish(error instanceof Error ? error : new Error(String(error)))\n        return\n      }\n      for (const value of values) {\n        // Anything at all proves a guest is there; the reply is parsed for\n        // real by the machine once it owns the stream.\n        if (value && typeof value === 'object') {\n          finish()\n          return\n        }\n      }\n    }\n    stream.on('data', onData)\n    stream.once('close', onClose)\n    stream.once('error', finish)\n    stream.write(encodeFrame({ id: 'hello', op: 'ping' }))\n  })\n}\n\nfunction attemptHandshake(\n  connect: (socketPath: string) => Duplex,\n  socketPath: string,\n  port: number,\n  attemptTimeoutMs: number,\n): Promise<Duplex> {\n  return new Promise<Duplex>((resolvePromise, rejectPromise) => {\n    let stream: Duplex\n    try {\n      stream = connect(socketPath)\n    } catch (error) {\n      rejectPromise(error instanceof Error ? error : new Error(String(error)))\n      return\n    }\n    let banner = ''\n    let settled = false\n    const timer = setTimeout(() => {\n      fail(new DeskError('vsock handshake went unanswered.'))\n    }, attemptTimeoutMs)\n    // An unref'd timer must not hold the process open on its own.\n    timer.unref?.()\n    const fail = (error: Error) => {\n      if (settled) return\n      settled = true\n      clearTimeout(timer)\n      stream.destroy()\n      rejectPromise(error)\n    }\n    const onData = (chunk: Buffer) => {\n      banner += chunk.toString('latin1')\n      const newline = banner.indexOf('\\n')\n      if (newline === -1) {\n        if (banner.length > HANDSHAKE_LINE_LIMIT) {\n          fail(new DeskError('vsock handshake reply exceeded the line limit.'))\n        }\n        return\n      }\n      const line = banner.slice(0, newline)\n      const rest = banner.slice(newline + 1)\n      stream.off('data', onData)\n      stream.off('error', fail)\n      if (!line.startsWith('OK ')) {\n        fail(new DeskError(`vsock handshake was refused: ${line}`))\n        return\n      }\n      settled = true\n      clearTimeout(timer)\n      if (rest.length > 0) stream.unshift(Buffer.from(rest, 'latin1'))\n      resolvePromise(stream)\n    }\n    stream.on('data', onData)\n    stream.once('error', fail)\n    // A close before the banner is a refusal, not a hang.\n    stream.once('close', () => fail(new DeskError('vsock handshake closed before a reply.')))\n    stream.write(`CONNECT ${port}\\n`)\n  })\n}\n\nfunction defaultLauncher(\n  command: string,\n  args: readonly string[],\n  options: { identity?: DeskLauncherIdentity },\n): ChildProcess {\n  return spawn(command, [...args], {\n    stdio: ['ignore', 'pipe', 'pipe'],\n    uid: options.identity?.uid,\n    gid: options.identity?.gid,\n  })\n}\n\nfunction defaultConnect(socketPath: string): Duplex {\n  return createConnection(socketPath)\n}\n\nfunction delay(ms: number): Promise<void> {\n  return new Promise<void>((resolvePromise) => {\n    const timer = setTimeout(resolvePromise, ms)\n    timer.unref()\n  })\n}\n\nfunction errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error)\n}\n"]}

package/events.d.ts

@@ -104,6 +104,9 @@ export type DeskEventDetail = {
     kind: 'screen_open';
     width: number;
     height: number;
+} | {
+    kind: 'snapshot_cpu_fallback';
+    reason: 'signature_mismatch' | 'incompatible_cpuid';
 } | {
     kind: 'screen_close';
 } | {

package/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG","sourcesContent":["/**\n * The typed desk event stream and the ports a consumer supplies.\n *\n * AppKit owns the mechanism of running a desk; the consumer owns the record.\n * Every governed thing that happens on a desk is delivered to `onEvent` as one\n * member of a closed union so the consumer's append-only ledger can persist it\n * without inventing its own taxonomy. Handover boundaries additionally reach\n * the `audit` port — and, while a handover is active, they are the *only*\n * thing that reaches any port. See the masking contract on `DeskPorts`.\n */\n\nexport type DeskPointerButton = 'left' | 'middle' | 'right'\n\nexport interface DeskPoint {\n  x: number\n  y: number\n}\n\nexport interface WindowInfo {\n  id: string\n  title: string\n  appId: string | null\n}\n\n/**\n * One node of the focused application's AT-SPI accessibility tree, when the\n * application exposes one. Perception is pixels-primary; the tree is\n * opportunistic and may be `null` at any time.\n */\nexport interface A11yNode {\n  id: string\n  role: string\n  name: string | null\n  actions: readonly string[]\n  bounds: { x: number; y: number; width: number; height: number } | null\n  children: readonly A11yNode[]\n}\n\n/**\n * How the pixels of a live frame are encoded on the wire.\n *\n * Two jobs, two formats. `observe()` is always lossless PNG because it feeds a\n * model's vision and anchors coordinates, and it is asked for rarely. The\n * `frames()` stream feeds a human driving the screen: there the scarce\n * resource is bytes on the transport, not fidelity, so a lossy `jpeg` is\n * roughly an order of magnitude smaller per frame and is what makes a live\n * view feel like a remote desktop rather than a slideshow.\n */\nexport type DeskFrameFormat = 'png' | 'jpeg'\n\n/**\n * The two kinds of unit a video stream is made of.\n *\n * `init` is the header a decoder needs before it can make sense of anything —\n * for fragmented MP4, `ftyp` plus `moov`. It arrives once per encoder start and\n * a consumer that never receives it decodes nothing at all, silently. `media`\n * is one fragment of pictures. Ordering is load-bearing: init first, then media\n * from a keyframe onwards.\n */\nexport type DeskVideoChunkKind = 'init' | 'media'\n\nexport type DeskHandoverScope = 'view' | 'control'\n\nexport type DeskHandoverEndReason = 'ended' | 'expired' | 'revoked'\n\n/**\n * The closed union of recordable desk activity. The consumer's ledger stores\n * these rows; the union is defined here so the mechanism and the record agree\n * on the taxonomy without the package ever touching a database.\n */\nexport type DeskEventDetail =\n  | {\n      kind: 'shell_command'\n      command: string\n      args: readonly string[]\n      cwd: string | null\n      exitCode: number | null\n      signal: string | null\n    }\n  | { kind: 'app_launch'; appId: string; args: readonly string[] }\n  | { kind: 'click'; x: number; y: number; button: DeskPointerButton; clicks: 1 | 2 }\n  | { kind: 'type'; text: string }\n  | { kind: 'key'; combo: string }\n  | { kind: 'scroll'; x: number; y: number; dx: number; dy: number }\n  | { kind: 'drag'; from: DeskPoint; to: DeskPoint }\n  | { kind: 'window_focus'; window: WindowInfo }\n  | { kind: 'screen_open'; width: number; height: number }\n  | { kind: 'screen_close' }\n  | { kind: 'handover_begin'; actor: string | null; scope: DeskHandoverScope }\n  | { kind: 'handover_end'; actor: string | null; durationMs: number }\n  | { kind: 'job_start'; jobId: string; command: string; args: readonly string[] }\n  | { kind: 'job_exit'; jobId: string; exitCode: number | null; signal: string | null }\n\nexport type DeskEventKind = DeskEventDetail['kind']\n\nexport type DeskEvent = DeskEventDetail & { deskId: string; at: string }\n\n/**\n * Handover boundaries as the audit port sees them: who took over, under what\n * scope, and for how long — never what they typed.\n */\nexport type DeskAuditEntry =\n  | {\n      kind: 'handover_begin'\n      deskId: string\n      actor: string | null\n      scope: DeskHandoverScope\n      ttlMs: number\n      at: string\n    }\n  | {\n      kind: 'handover_end'\n      deskId: string\n      actor: string | null\n      durationMs: number\n      reason: DeskHandoverEndReason\n      at: string\n    }\n\n/**\n * Consumer-supplied policy. Absent hooks allow: the package is mechanism, and\n * a deployment that wants governance supplies it here. A hook returning\n * `false` makes the corresponding call throw before anything reaches the\n * guest.\n */\nexport interface DeskPolicyPort {\n  allowExec?(request: {\n    deskId: string\n    command: string\n    args: readonly string[]\n    keepAlive: boolean\n  }): boolean\n  allowScreen?(request: { deskId: string; width: number; height: number }): boolean\n  allowHandover?(request: {\n    deskId: string\n    scope: DeskHandoverScope\n    ttlMs: number\n  }): boolean\n}\n\n/**\n * The ports a consumer supplies to `createDeskHost`.\n *\n * Masking contract (load-bearing): while a handover is active, input events —\n * `click`, `type`, `key`, `scroll`, `drag` — and the screen-derived events\n * `window_focus` and `app_launch` never reach `onEvent`, and frames are never\n * emitted to `frames()` consumers. Only `handover_begin` and `handover_end`\n * cross the boundary, carrying actor and duration. Getting this wrong leaks\n * credentials into an append-only record.\n */\nexport interface DeskPorts {\n  policy?: DeskPolicyPort\n  onEvent: (event: DeskEvent) => void\n  audit: (entry: DeskAuditEntry) => void\n}\n"]}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG","sourcesContent":["/**\n * The typed desk event stream and the ports a consumer supplies.\n *\n * AppKit owns the mechanism of running a desk; the consumer owns the record.\n * Every governed thing that happens on a desk is delivered to `onEvent` as one\n * member of a closed union so the consumer's append-only ledger can persist it\n * without inventing its own taxonomy. Handover boundaries additionally reach\n * the `audit` port — and, while a handover is active, they are the *only*\n * thing that reaches any port. See the masking contract on `DeskPorts`.\n */\n\nexport type DeskPointerButton = 'left' | 'middle' | 'right'\n\nexport interface DeskPoint {\n  x: number\n  y: number\n}\n\nexport interface WindowInfo {\n  id: string\n  title: string\n  appId: string | null\n}\n\n/**\n * One node of the focused application's AT-SPI accessibility tree, when the\n * application exposes one. Perception is pixels-primary; the tree is\n * opportunistic and may be `null` at any time.\n */\nexport interface A11yNode {\n  id: string\n  role: string\n  name: string | null\n  actions: readonly string[]\n  bounds: { x: number; y: number; width: number; height: number } | null\n  children: readonly A11yNode[]\n}\n\n/**\n * How the pixels of a live frame are encoded on the wire.\n *\n * Two jobs, two formats. `observe()` is always lossless PNG because it feeds a\n * model's vision and anchors coordinates, and it is asked for rarely. The\n * `frames()` stream feeds a human driving the screen: there the scarce\n * resource is bytes on the transport, not fidelity, so a lossy `jpeg` is\n * roughly an order of magnitude smaller per frame and is what makes a live\n * view feel like a remote desktop rather than a slideshow.\n */\nexport type DeskFrameFormat = 'png' | 'jpeg'\n\n/**\n * The two kinds of unit a video stream is made of.\n *\n * `init` is the header a decoder needs before it can make sense of anything —\n * for fragmented MP4, `ftyp` plus `moov`. It arrives once per encoder start and\n * a consumer that never receives it decodes nothing at all, silently. `media`\n * is one fragment of pictures. Ordering is load-bearing: init first, then media\n * from a keyframe onwards.\n */\nexport type DeskVideoChunkKind = 'init' | 'media'\n\nexport type DeskHandoverScope = 'view' | 'control'\n\nexport type DeskHandoverEndReason = 'ended' | 'expired' | 'revoked'\n\n/**\n * The closed union of recordable desk activity. The consumer's ledger stores\n * these rows; the union is defined here so the mechanism and the record agree\n * on the taxonomy without the package ever touching a database.\n */\nexport type DeskEventDetail =\n  | {\n      kind: 'shell_command'\n      command: string\n      args: readonly string[]\n      cwd: string | null\n      exitCode: number | null\n      signal: string | null\n    }\n  | { kind: 'app_launch'; appId: string; args: readonly string[] }\n  | { kind: 'click'; x: number; y: number; button: DeskPointerButton; clicks: 1 | 2 }\n  | { kind: 'type'; text: string }\n  | { kind: 'key'; combo: string }\n  | { kind: 'scroll'; x: number; y: number; dx: number; dy: number }\n  | { kind: 'drag'; from: DeskPoint; to: DeskPoint }\n  | { kind: 'window_focus'; window: WindowInfo }\n  | { kind: 'screen_open'; width: number; height: number }\n  | { kind: 'snapshot_cpu_fallback'; reason: 'signature_mismatch' | 'incompatible_cpuid' }\n  | { kind: 'screen_close' }\n  | { kind: 'handover_begin'; actor: string | null; scope: DeskHandoverScope }\n  | { kind: 'handover_end'; actor: string | null; durationMs: number }\n  | { kind: 'job_start'; jobId: string; command: string; args: readonly string[] }\n  | { kind: 'job_exit'; jobId: string; exitCode: number | null; signal: string | null }\n\nexport type DeskEventKind = DeskEventDetail['kind']\n\nexport type DeskEvent = DeskEventDetail & { deskId: string; at: string }\n\n/**\n * Handover boundaries as the audit port sees them: who took over, under what\n * scope, and for how long — never what they typed.\n */\nexport type DeskAuditEntry =\n  | {\n      kind: 'handover_begin'\n      deskId: string\n      actor: string | null\n      scope: DeskHandoverScope\n      ttlMs: number\n      at: string\n    }\n  | {\n      kind: 'handover_end'\n      deskId: string\n      actor: string | null\n      durationMs: number\n      reason: DeskHandoverEndReason\n      at: string\n    }\n\n/**\n * Consumer-supplied policy. Absent hooks allow: the package is mechanism, and\n * a deployment that wants governance supplies it here. A hook returning\n * `false` makes the corresponding call throw before anything reaches the\n * guest.\n */\nexport interface DeskPolicyPort {\n  allowExec?(request: {\n    deskId: string\n    command: string\n    args: readonly string[]\n    keepAlive: boolean\n  }): boolean\n  allowScreen?(request: { deskId: string; width: number; height: number }): boolean\n  allowHandover?(request: {\n    deskId: string\n    scope: DeskHandoverScope\n    ttlMs: number\n  }): boolean\n}\n\n/**\n * The ports a consumer supplies to `createDeskHost`.\n *\n * Masking contract (load-bearing): while a handover is active, input events —\n * `click`, `type`, `key`, `scroll`, `drag` — and the screen-derived events\n * `window_focus` and `app_launch` never reach `onEvent`, and frames are never\n * emitted to `frames()` consumers. Only `handover_begin` and `handover_end`\n * cross the boundary, carrying actor and duration. Getting this wrong leaks\n * credentials into an append-only record.\n */\nexport interface DeskPorts {\n  policy?: DeskPolicyPort\n  onEvent: (event: DeskEvent) => void\n  audit: (entry: DeskAuditEntry) => void\n}\n"]}