@braedonsaunders/appkit-desk 0.8.0 → 0.10.0

package/README.md

@@ -112,6 +112,19 @@ 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.canPause(deskId)` reports whether a resident desk supports in-memory
+pause. Cloud Hypervisor supports `await host.pause(deskId)` and
+`await host.resume(deskId)`; other backends can decline it. A paused desk keeps
+its handle, capacity slot, running jobs and original lease and idle deadlines.
+Guest requests are rejected while paused; requests already in flight fail with
+unknown fate. A guest connection lost during the pause reconnects on resume.
+An active handover prevents pause. Suspend and shutdown resume the desk before
+trimming and syncing. Lifecycle operations, including lease sweeps, serialize
+per desk. If a control operation fails and the VM state cannot be confirmed,
+the desk remains fenced; retry `resume` after the control socket is available.
+Existing guest service streams remain open, but cannot make progress while the
+VM is paused.
+
 `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.
@@ -247,6 +260,26 @@ The default iptables chain prefix is `desk`. Existing deployments using the `bh`
 
 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.
 
+`freePageReporting: true` on `host.start` configures a zero-size
+virtio-balloon with free-page reporting on a Cloud Hypervisor cold boot. It
+requires guest driver support; the snapshot retains its original device
+configuration. Reporting frees host memory when the guest reports unused pages;
+it does not promise a particular snapshot size. Virtualization.framework does
+not support this option.
+
+With Cloud Hypervisor v54 or later, `memoryRestoreMode: 'copyonwrite'` opts in
+to file-backed restore alongside `parkWithMemory: true`. The parked snapshot is
+atomically renamed to a unique source and its parent directory synced before
+the VMM starts, so it cannot be replayed after the disk changes. The source is
+kept unchanged until the VMM exits, then removed. A host crash or failed stop can
+leave a `*.snapshot.source-*` directory; only remove it after verifying that no
+VMM maps it. Restore failures can leave one too. The source contains guest RAM
+and needs the same protection as a parked snapshot. Copy-on-write restore refuses virtio-fs shares, including shares recorded in
+a parked snapshot. Cloud Hypervisor can fall back to eager copying for other
+incompatible memory or devices. Separate reflinked
+files do not share page-cache identity, and this option does not create cloned
+template guests or promise incremental snapshots.
+
 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:
@@ -257,7 +290,77 @@ DESK_CHECK_IMAGE_ROOT=/data/desk-image DESK_CHECK_BASE_IMAGE=/data/desk-image/ba
 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.
+Set `DESK_CHECK_COW=1` to exercise copy-on-write snapshot restore and `DESK_CHECK_BALLOON=1` to check the guest virtio-balloon driver. 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 resident pause and resume, and 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. Set `DESK_CHECK_VIRTIOFSD` to a `virtiofsd` binary to also check a read-only share: the guest mounts it, a write fails, and a file held open across the park reads back after the restore.
+
+## Host directory shares
+
+A desk can mount host directories over virtio-fs. Pass `shares` to
+`host.start` (or `buildDeskLaunchPlan`):
+
+```ts
+const desk = await host.start({
+  deskId: 'agent-7',
+  baseImage: '/data/agent-disks/base.img',
+  overlayPath: '/data/agent-disks/overlays/agent-7.img',
+  shares: [
+    { tag: 'tools', path: '/srv/desk-tools', readOnly: true },
+    { tag: 'build', path: '/srv/builds/agent-7', readOnly: false },
+  ],
+})
+await desk.exec({ command: '/bin/sh', args: ['-c', 'mkdir -p /opt/tools && mount -t virtiofs tools /opt/tools'] })
+```
+
+A `tag` is 1–36 lowercase letters, digits or hyphens, starting with a letter or
+digit, and unique within the desk; it is the name the guest mounts. `path` is an
+absolute path to an existing host directory. `readOnly` is required. A read-only
+share is enforced by the host's file server, so remounting it read-write in the
+guest does not make it writable. The guest kernel needs virtio-fs
+(`CONFIG_VIRTIO_FS`; Debian's cloud kernels ship it as the `virtiofs` module).
+
+On Cloud Hypervisor, each share is served by its own `virtiofsd` (the Rust
+implementation, 1.13 or later). `virtiofsdPath` on the host options names the
+binary; without it the first `virtiofsd` on `PATH` is used, then
+`/usr/libexec/virtiofsd`. A desk without shares does not need `virtiofsd`. Each
+daemon runs as the launcher identity with:
+
+```sh
+virtiofsd --socket-path=<runtimeDir>/desk-<deskId>.<tag>.fs.sock --shared-dir=<path> \
+  --sandbox=<namespace|chroot> --cache=auto \
+  --migration-mode=find-paths --migration-on-error=guest-error [--readonly]
+```
+
+and the VMM gets `--fs tag=<tag>,socket=<socket>` with its memory as
+`size=<n>M,shared=on`, which vhost-user devices require; a desk without shares
+keeps private memory. `--cache=auto` lets the guest cache for about a second,
+so files the host changes under a share appear in running guests.
+`virtiofsdSandbox` picks how the daemon confines itself to the directory:
+`namespace` (the default) needs CAP_SYS_ADMIN when the launcher is root and
+unprivileged user namespaces otherwise; `chroot` needs root and suits a
+container that cannot create namespaces. Both prevent symlink escapes. The
+backend starts every daemon and waits for its socket before starting the VMM,
+on a boot and on a restore, and stops the daemons after the VMM. A daemon that
+exits while its VMM runs stops the VMM, so the desk is lost rather than left
+with a share that no longer answers. `virtiofsd` also exits when its VMM
+disconnects. The share socket path must fit in 107 bytes.
+
+On Virtualization.framework, each share is a
+`VZVirtioFileSystemDeviceConfiguration` with a `VZSingleDirectoryShare`, and the
+framework enforces `readOnly`. `virtiofsdPath` and `virtiofsdSandbox` are
+refused there. When Virtualization.framework reports that a configuration
+cannot be saved, the desk parks by shutting down, as for any other device.
+
+Parking keeps a desk's shares with its memory. The backend records them in
+`shares.json` beside the snapshot, and a restore uses that record instead of the
+start options: a snapshot holds its devices, so a share added since joins the
+desk at its next cold boot (`host.shutdown` forces one), and a backend refuses a
+restore plan whose shares differ from the record. A recorded share whose
+directory no longer exists fails the restore; the host discards the snapshot,
+cold boots with the current shares, and reports it in `lastError`. A snapshot
+holds no share contents. On Cloud Hypervisor it carries each daemon's state,
+which the new daemon loads on restore by reopening every file and directory the
+guest held by its path, so open files survive. Paths are the link: a file the
+host unlinks or moves while the desk is parked returns errors to the guest for
+that file only, and a file the host puts at its path is the one the guest gets.
 
 ## macOS Virtualization.framework backend
 
@@ -313,3 +416,18 @@ For clients that require a local TCP URL, `await listenDeskPort(desk, port)`
 returns a loopback-only `{ host, port, close }` listener. Each incoming
 connection opens a guest stream through `desk.connect`; call `close()` when the
 lease ends to close the listener and its connections.
+
+Cloud Hypervisor backends can opt into `serviceVsock: true` when their guest image provides
+vsock service listeners. `DeskHandle.connect(port)` then opens that vsock port using the
+Cloud Hypervisor socket handshake. The default remains TCP for existing guest images.
+
+## Immutable image attachments
+
+On Cloud Hypervisor, `DeskStartOptions.readOnlyAttachments` accepts an ordered list of
+`{ path, sha256, kind }`, where `kind` is `block` or `pmem` and `sha256` is the
+lowercase SHA-256 of the image. Block devices are attached read-only; pmem uses
+`discard_writes=on`, so guest writes do not persist. The caller must keep each file
+and its path immutable and available for as long as a desk or its snapshot uses it.
+AppKit hashes each image on start and records the attachment list with the snapshot;
+restore refuses a changed list before resuming. Virtualization.framework rejects
+attachments. Device support and filesystem mount options depend on the guest kernel.

package/backend.d.ts

@@ -99,6 +99,9 @@ export interface DeskMachine {
      * `DeskError` when the guest refuses or does not answer.
      */
     connect?(port: number): Promise<Duplex>;
+    /** Optional resident pause and resume. Callers must serialize these with lifecycle operations. */
+    pause?(): Promise<void>;
+    resume?(): Promise<void>;
     /** Stop the VM. Idempotent; resolves once the VMM process has exited. */
     shutdown(): Promise<void>;
     /**
@@ -122,7 +125,7 @@ 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
+     * The snapshot must no longer be available for replay by this point. 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
@@ -184,6 +187,12 @@ export interface CloudHypervisorBackendOptions {
     reconnectRetryDelayMs?: number;
     killGraceMs?: number;
     guestAgentPort?: number;
+    /** Use guest-provided vsock service bridges for DeskHandle.connect. Opt in only when the image provides them. */
+    serviceVsock?: boolean;
+    /** Whether a share daemon's socket exists yet; injectable for tests. */
+    pathExists?: (path: string) => boolean;
+    /** Removes a stale share socket before its daemon starts; injectable for tests. */
+    removeFile?: (path: string) => Promise<void>;
 }
 export declare function createCloudHypervisorBackend(options?: CloudHypervisorBackendOptions): DeskBackend;
 /**
@@ -196,7 +205,9 @@ export declare function createCloudHypervisorBackend(options?: CloudHypervisorBa
  * 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>;
+export type VmmApiCall = (socketPath: string, path: string, body?: Record<string, unknown>, method?: 'PUT' | 'GET') => Promise<void | string>;
+/** Reconcile an ambiguous command failure against the VMM before releasing the fence. */
+export declare function setVmmState(call: VmmApiCall, socketPath: string, desired: 'Paused' | 'Running'): 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":"AAYA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EACL,SAAS,EAAkC,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,KAAK,oBAAoB,EAC/G,MAAM,QAAQ,CAAA;AACf,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEjE;;;;;;;;;;GAUG;AACH,qBAAa,2BAA4B,SAAQ,SAAS;IACxD,SAAkB,IAAI,EAAE,MAAM,CAAgC;CAC/D;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IACE,KAAK,EAAE,aAAa,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAA;IAClB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAA;CACnB,GACD;IACE,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAEL,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAClF;;;;;;;;OAQG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IACnE;;;;;;;OAOG;IACH,kBAAkB,CAAC,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IACjF;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACvC,kGAAkG;IAClG,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACvB,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB,yEAAyE;IACzE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACzB;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1C;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAA;IACpC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CACxE;AAED,MAAM,MAAM,mBAAmB,GAAG,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IAAE,QAAQ,CAAC,EAAE,oBAAoB,CAAA;CAAE,KACzC,YAAY,CAAA;AAEjB,MAAM,WAAW,6BAA6B;IAC5C,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,mBAAmB,CAAA;IAC9B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAA;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAA;IAC1B;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,MAAM,CAAA;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,iEAAiE;IACjE,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,iHAAiH;IACjH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,wEAAwE;IACxE,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAA;IACtC,mFAAmF;IACnF,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7C;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,GAAE,6BAAkC,GAC1C,WAAW,CAwMb;AASD;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,KACnB,OAAO,CAAC,IAAI,GAAG,MAAM,CAAC,CAAA;AAE3B,yFAAyF;AACzF,wBAAsB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAWpH;AAqED,2EAA2E;AAC3E,eAAO,MAAM,sBAAsB,EAAE,WAEpC,CAAA"}

package/backend.js

@@ -1,8 +1,10 @@
 import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
 import { request as httpRequest } from 'node:http';
 import { GUEST_AGENT_VSOCK_PORT } from './protocol.js';
-import { DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_CONNECT_RETRY_DELAY_MS, DEFAULT_HANDSHAKE_TIMEOUT_MS, DEFAULT_RECONNECT_WINDOW_MS, DEFAULT_RECONNECT_RETRY_DELAY_MS, DEFAULT_KILL_GRACE_MS, RECONNECT_BACKOFF_CEILING, connectWithRetry, createGuestMachine, defaultLauncher, defaultConnect, drainOutput, watchExit, terminate, runToCompletion, errorMessage, } from './machine.js';
-import { DeskError } from './plan.js';
+import { DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_CONNECT_RETRY_DELAY_MS, DEFAULT_HANDSHAKE_TIMEOUT_MS, DEFAULT_RECONNECT_WINDOW_MS, DEFAULT_RECONNECT_RETRY_DELAY_MS, DEFAULT_KILL_GRACE_MS, RECONNECT_BACKOFF_CEILING, connectWithRetry, createGuestMachine, attemptHandshake, defaultLauncher, defaultConnect, drainOutput, watchExit, terminate, runToCompletion, errorMessage, assertShareManifest, writeShareManifest, } from './machine.js';
+import { DeskError, } from './plan.js';
 /**
  * A request that was in flight when the guest connection dropped.
  *
@@ -31,6 +33,63 @@ 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;
+    const pathExists = options.pathExists ?? existsSync;
+    const removeFile = options.removeFile ?? ((path) => rm(path, { force: true }));
+    /**
+     * Start one `virtiofsd` per share and wait until every socket exists.
+     *
+     * The VMM connects to these at boot and at restore alike, so they come up
+     * first. A stale socket is removed beforehand, or its presence would read as
+     * a daemon that is listening. Existence is the readiness signal rather than
+     * a probe connection, because `virtiofsd` serves exactly one connection and
+     * exits when it closes; the moment between bind and listen is covered by
+     * Cloud Hypervisor retrying a refused vhost-user connect.
+     */
+    async function startShareDaemons(plan) {
+        const daemons = [];
+        const stop = async () => {
+            await Promise.all(daemons.map((daemon) => terminate(daemon.child, daemon.exit, killGraceMs)));
+        };
+        try {
+            for (const share of plan.shares) {
+                await removeFile(share.socketPath);
+                const child = launcher(share.daemon.command, share.daemon.args, { identity: plan.launcherIdentity });
+                daemons.push({ tag: share.tag, child, exit: watchExit(child), log: drainOutput(child) });
+            }
+            const deadline = now() + connectTimeoutMs;
+            for (;;) {
+                const exited = daemons.find((daemon) => daemon.exit.done);
+                if (exited) {
+                    const said = exited.log.tail();
+                    throw new DeskError(`virtiofsd for share ${exited.tag} exited before it listened${said === '' ? '.' : `: ${said}`}`);
+                }
+                const waiting = plan.shares.filter((share) => !pathExists(share.socketPath));
+                if (waiting.length === 0)
+                    break;
+                if (now() >= deadline) {
+                    throw new DeskError(`virtiofsd did not create ${waiting.map((share) => share.socketPath).join(', ')} in ${connectTimeoutMs}ms.`);
+                }
+                // A held timer: the wait is bounded by the deadline, and nothing else may be keeping
+                // the process alive while a daemon starts.
+                await new Promise((resolvePromise) => setTimeout(resolvePromise, connectRetryDelayMs));
+            }
+        }
+        catch (error) {
+            await stop();
+            throw error;
+        }
+        return {
+            stop,
+            // The VMM cannot serve a share whose daemon is gone; neither can it be
+            // handed a new one mid-run. So a daemon that dies stops the VMM, and the
+            // desk is lost loudly instead of hanging every guest access to the share.
+            supervise: (vmm, vmmExit) => {
+                for (const daemon of daemons) {
+                    void daemon.exit.promise.then(() => terminate(vmm, vmmExit, killGraceMs));
+                }
+            },
+        };
+    }
     async function boot(plan, hooks) {
         if (plan.hypervisor !== 'cloud-hypervisor')
             throw new DeskError('Cloud Hypervisor requires a cloud-hypervisor plan.');
@@ -42,12 +101,38 @@ export function createCloudHypervisorBackend(options = {}) {
                 identity: plan.launcherIdentity,
             }), `overlay creation for desk ${plan.deskId}`);
         }
+        if (plan.snapshot.restoring) {
+            try {
+                await assertShareManifest(plan.snapshot.dir, plan.shares);
+            }
+            catch (error) {
+                throw new DeskError(`Desk ${plan.deskId} could not be restored from ${plan.snapshot.dir}: ${errorMessage(error)}`);
+            }
+        }
+        let shares;
+        try {
+            shares = await startShareDaemons(plan);
+        }
+        catch (error) {
+            throw new DeskError(`Desk ${plan.deskId} could not start its shares: ${errorMessage(error)}`);
+        }
         const child = launcher(plan.vmm.command, plan.vmm.args, { identity: plan.launcherIdentity });
         const log = drainOutput(child);
         const exit = watchExit(child);
+        shares.supervise(child, exit);
+        // The VMM first: a daemon outliving it is harmless, while a daemon stopped
+        // under a running VMM is a share failing in the guest.
+        const stop = async () => {
+            try {
+                await terminate(child, exit, killGraceMs);
+            }
+            finally {
+                await shares.stop();
+            }
+        };
         // 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
+        // prove the restore finished, let the caller invalidate replay while the
         // guest still cannot write, then start it.
         if (plan.snapshot.restoring) {
             try {
@@ -56,7 +141,7 @@ export function createCloudHypervisorBackend(options = {}) {
                 await vmmApi(plan.api.socketPath, '/api/v1/vm.resume');
             }
             catch (error) {
-                await terminate(child, exit, killGraceMs);
+                await stop();
                 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}`);
@@ -76,7 +161,7 @@ export function createCloudHypervisorBackend(options = {}) {
             });
         }
         catch (error) {
-            await terminate(child, exit, killGraceMs);
+            await stop();
             const said = log.tail();
             const detail = said === '' ? '' : ` The VMM said: ${said}`;
             throw error instanceof DeskError
@@ -107,23 +192,47 @@ export function createCloudHypervisorBackend(options = {}) {
             now,
             idFactory,
             requestTimeoutMs,
-            stop: () => terminate(child, exit, killGraceMs),
+            ...(options.serviceVsock ? { connect: (port) => {
+                    if (!Number.isInteger(port) || port < 1 || port > 65535)
+                        throw new DeskError('Guest port must be between 1 and 65535.');
+                    return attemptHandshake(connect, plan.vsock.socketPath, port, handshakeTimeoutMs);
+                } } : {}),
+            stop,
+            pause: () => setVmmState(vmmApi, plan.api.socketPath, 'Paused'),
+            resume: () => setVmmState(vmmApi, plan.api.socketPath, 'Running'),
             park: async (snapshotDir) => {
                 try {
                     await vmmApi(plan.api.socketPath, '/api/v1/vm.pause');
                     await vmmApi(plan.api.socketPath, '/api/v1/vm.snapshot', { destination_url: `file://${snapshotDir}` });
+                    await writeShareManifest(snapshotDir, plan.shares);
                 }
                 finally {
-                    await terminate(child, exit, killGraceMs);
+                    await stop();
                 }
             },
         });
     }
     return { boot };
 }
+/** Reconcile an ambiguous command failure against the VMM before releasing the fence. */
+export async function setVmmState(call, socketPath, desired) {
+    try {
+        await call(socketPath, desired === 'Paused' ? '/api/v1/vm.pause' : '/api/v1/vm.resume');
+    }
+    catch (error) {
+        try {
+            const response = await call(socketPath, '/api/v1/vm.info', undefined, 'GET');
+            const info = typeof response === 'string' ? JSON.parse(response) : null;
+            if (info && typeof info === 'object' && 'state' in info && info.state === desired)
+                return;
+        }
+        catch { /* State is unknown: preserve the original failure and the request fence. */ }
+        throw error;
+    }
+}
 const vmmApi = async (socketPath, path, body, method = 'PUT') => {
     const payload = body === undefined ? undefined : Buffer.from(JSON.stringify(body), 'utf8');
-    await new Promise((resolve, reject) => {
+    return await new Promise((resolve, reject) => {
         const request = httpRequest({
             socketPath,
             path,
@@ -139,7 +248,7 @@ const vmmApi = async (socketPath, path, body, method = 'PUT') => {
             response.on('end', () => {
                 const status = response.statusCode ?? 0;
                 if (status >= 200 && status < 300) {
-                    resolve();
+                    resolve(Buffer.concat(chunks).toString('utf8'));
                     return;
                 }
                 const said = Buffer.concat(chunks).toString('utf8').trim().slice(0, 400);

package/backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from 'node:crypto'\nimport { request as httpRequest } from 'node:http'\nimport { GUEST_AGENT_VSOCK_PORT } from './protocol'\nimport {\n  DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_CONNECT_RETRY_DELAY_MS,\n  DEFAULT_HANDSHAKE_TIMEOUT_MS, DEFAULT_RECONNECT_WINDOW_MS, DEFAULT_RECONNECT_RETRY_DELAY_MS,\n  DEFAULT_KILL_GRACE_MS, RECONNECT_BACKOFF_CEILING, connectWithRetry, createGuestMachine,\n  defaultLauncher, defaultConnect, drainOutput, watchExit, terminate, runToCompletion, errorMessage,\n  type ExitWatcher,\n} from './machine'\n/**\n * The backend port.\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` on Linux or\n * `createVirtualizationBackend` on an Apple silicon Mac, whose process glue is\n * deliberately thin because everything that can be pure lives in the plan\n * builder, the protocol module, and the shared guest channel.\n */\nimport type { ChildProcess } from 'node:child_process'\nimport type { Duplex } from 'node:stream'\nimport { DeskError, type DeskHypervisor, type DeskLaunchPlan, type DeskLauncherIdentity } from './plan'\nimport type { GuestCommand, GuestEventMessage } 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  /**\n   * Open a TCP stream from the host to `port` on the guest.\n   *\n   * Optional: a backend whose guest has a routable address (Cloud Hypervisor's\n   * TAP) leaves this out and the host dials the guest address directly. A\n   * backend whose guest sits behind a userspace NAT (Virtualization.framework)\n   * provides it, because there is no address on the Mac to dial. Rejects with\n   * `DeskError` when the guest refuses or does not answer.\n   */\n  connect?(port: number): Promise<Duplex>\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  /**\n   * Which hypervisor this backend boots, and so which plan the host builds\n   * for it. Absent means Cloud Hypervisor.\n   */\n  readonly hypervisor?: DeskHypervisor\n  /**\n   * The binary the backend launches — the VMM or the helper — for readiness\n   * reporting. Optional; `verifyDeskHost` falls back to its own option.\n   */\n  readonly vmmPath?: string\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\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 (plan.hypervisor !== 'cloud-hypervisor') throw new DeskError('Cloud Hypervisor requires a cloud-hypervisor plan.')\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 createGuestMachine({\n      deskId: plan.deskId,\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      stop: () => terminate(child, exit, killGraceMs),\n      park: async (snapshotDir) => {\n        try {\n          await vmmApi(plan.api.socketPath, '/api/v1/vm.pause')\n          await vmmApi(plan.api.socketPath, '/api/v1/vm.snapshot', { destination_url: `file://${snapshotDir}` })\n        } finally {\n          await terminate(child, exit, killGraceMs)\n        }\n      },\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 = {\n  boot: (plan, hooks) => createCloudHypervisorBackend().boot(plan, hooks),\n}\n"]}
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from 'node:crypto'\nimport { existsSync } from 'node:fs'\nimport { rm } from 'node:fs/promises'\nimport { request as httpRequest } from 'node:http'\nimport { GUEST_AGENT_VSOCK_PORT } from './protocol'\nimport {\n  DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_CONNECT_RETRY_DELAY_MS,\n  DEFAULT_HANDSHAKE_TIMEOUT_MS, DEFAULT_RECONNECT_WINDOW_MS, DEFAULT_RECONNECT_RETRY_DELAY_MS,\n  DEFAULT_KILL_GRACE_MS, RECONNECT_BACKOFF_CEILING, connectWithRetry, createGuestMachine, attemptHandshake,\n  defaultLauncher, defaultConnect, drainOutput, watchExit, terminate, runToCompletion, errorMessage,\n  assertShareManifest, writeShareManifest, type ExitWatcher,\n} from './machine'\n/**\n * The backend port.\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` on Linux or\n * `createVirtualizationBackend` on an Apple silicon Mac, whose process glue is\n * deliberately thin because everything that can be pure lives in the plan\n * builder, the protocol module, and the shared guest channel.\n */\nimport type { ChildProcess } from 'node:child_process'\nimport type { Duplex } from 'node:stream'\nimport {\n  DeskError, type CloudHypervisorLaunchPlan, type DeskHypervisor, type DeskLaunchPlan, type DeskLauncherIdentity,\n} from './plan'\nimport type { GuestCommand, GuestEventMessage } 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  /**\n   * Open a TCP stream from the host to `port` on the guest.\n   *\n   * Optional: a backend whose guest has a routable address (Cloud Hypervisor's\n   * TAP) leaves this out and the host dials the guest address directly. A\n   * backend whose guest sits behind a userspace NAT (Virtualization.framework)\n   * provides it, because there is no address on the Mac to dial. Rejects with\n   * `DeskError` when the guest refuses or does not answer.\n   */\n  connect?(port: number): Promise<Duplex>\n  /** Optional resident pause and resume. Callers must serialize these with lifecycle operations. */\n  pause?(): Promise<void>\n  resume?(): Promise<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   * The snapshot must no longer be available for replay by this point. 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  /**\n   * Which hypervisor this backend boots, and so which plan the host builds\n   * for it. Absent means Cloud Hypervisor.\n   */\n  readonly hypervisor?: DeskHypervisor\n  /**\n   * The binary the backend launches — the VMM or the helper — for readiness\n   * reporting. Optional; `verifyDeskHost` falls back to its own option.\n   */\n  readonly vmmPath?: string\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  /** Use guest-provided vsock service bridges for DeskHandle.connect. Opt in only when the image provides them. */\n  serviceVsock?: boolean\n  /** Whether a share daemon's socket exists yet; injectable for tests. */\n  pathExists?: (path: string) => boolean\n  /** Removes a stale share socket before its daemon starts; injectable for tests. */\n  removeFile?: (path: string) => Promise<void>\n}\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  const pathExists = options.pathExists ?? existsSync\n  const removeFile = options.removeFile ?? ((path: string) => rm(path, { force: true }))\n\n  /**\n   * Start one `virtiofsd` per share and wait until every socket exists.\n   *\n   * The VMM connects to these at boot and at restore alike, so they come up\n   * first. A stale socket is removed beforehand, or its presence would read as\n   * a daemon that is listening. Existence is the readiness signal rather than\n   * a probe connection, because `virtiofsd` serves exactly one connection and\n   * exits when it closes; the moment between bind and listen is covered by\n   * Cloud Hypervisor retrying a refused vhost-user connect.\n   */\n  async function startShareDaemons(plan: CloudHypervisorLaunchPlan): Promise<ShareDaemons> {\n    const daemons: { tag: string; child: ChildProcess; exit: ExitWatcher; log: { tail: () => string } }[] = []\n    const stop = async () => {\n      await Promise.all(daemons.map((daemon) => terminate(daemon.child, daemon.exit, killGraceMs)))\n    }\n    try {\n      for (const share of plan.shares) {\n        await removeFile(share.socketPath)\n        const child = launcher(share.daemon.command, share.daemon.args, { identity: plan.launcherIdentity })\n        daemons.push({ tag: share.tag, child, exit: watchExit(child), log: drainOutput(child) })\n      }\n      const deadline = now() + connectTimeoutMs\n      for (;;) {\n        const exited = daemons.find((daemon) => daemon.exit.done)\n        if (exited) {\n          const said = exited.log.tail()\n          throw new DeskError(`virtiofsd for share ${exited.tag} exited before it listened${said === '' ? '.' : `: ${said}`}`)\n        }\n        const waiting = plan.shares.filter((share) => !pathExists(share.socketPath))\n        if (waiting.length === 0) break\n        if (now() >= deadline) {\n          throw new DeskError(\n            `virtiofsd did not create ${waiting.map((share) => share.socketPath).join(', ')} in ${connectTimeoutMs}ms.`,\n          )\n        }\n        // A held timer: the wait is bounded by the deadline, and nothing else may be keeping\n        // the process alive while a daemon starts.\n        await new Promise<void>((resolvePromise) => setTimeout(resolvePromise, connectRetryDelayMs))\n      }\n    } catch (error) {\n      await stop()\n      throw error\n    }\n    return {\n      stop,\n      // The VMM cannot serve a share whose daemon is gone; neither can it be\n      // handed a new one mid-run. So a daemon that dies stops the VMM, and the\n      // desk is lost loudly instead of hanging every guest access to the share.\n      supervise: (vmm, vmmExit) => {\n        for (const daemon of daemons) {\n          void daemon.exit.promise.then(() => terminate(vmm, vmmExit, killGraceMs))\n        }\n      },\n    }\n  }\n\n  async function boot(plan: DeskLaunchPlan, hooks?: DeskBootHooks): Promise<DeskMachine> {\n    if (plan.hypervisor !== 'cloud-hypervisor') throw new DeskError('Cloud Hypervisor requires a cloud-hypervisor plan.')\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    if (plan.snapshot.restoring) {\n      try {\n        await assertShareManifest(plan.snapshot.dir, plan.shares)\n      } catch (error) {\n        throw new DeskError(`Desk ${plan.deskId} could not be restored from ${plan.snapshot.dir}: ${errorMessage(error)}`)\n      }\n    }\n\n    let shares: ShareDaemons\n    try {\n      shares = await startShareDaemons(plan)\n    } catch (error) {\n      throw new DeskError(`Desk ${plan.deskId} could not start its shares: ${errorMessage(error)}`)\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    shares.supervise(child, exit)\n    // The VMM first: a daemon outliving it is harmless, while a daemon stopped\n    // under a running VMM is a share failing in the guest.\n    const stop = async () => {\n      try {\n        await terminate(child, exit, killGraceMs)\n      } finally {\n        await shares.stop()\n      }\n    }\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 invalidate replay 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 stop()\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 stop()\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 createGuestMachine({\n      deskId: plan.deskId,\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      ...(options.serviceVsock ? { connect: (port: number) => {\n        if (!Number.isInteger(port) || port < 1 || port > 65535) throw new DeskError('Guest port must be between 1 and 65535.')\n        return attemptHandshake(connect, plan.vsock.socketPath, port, handshakeTimeoutMs)\n      } } : {}),\n      stop,\n      pause: () => setVmmState(vmmApi, plan.api.socketPath, 'Paused'),\n      resume: () => setVmmState(vmmApi, plan.api.socketPath, 'Running'),\n      park: async (snapshotDir) => {\n        try {\n          await vmmApi(plan.api.socketPath, '/api/v1/vm.pause')\n          await vmmApi(plan.api.socketPath, '/api/v1/vm.snapshot', { destination_url: `file://${snapshotDir}` })\n          await writeShareManifest(snapshotDir, plan.shares)\n        } finally {\n          await stop()\n        }\n      },\n    })\n  }\n\n  return { boot }\n}\n\ninterface ShareDaemons {\n  /** Stop every daemon; resolves once all have exited. */\n  stop: () => Promise<void>\n  /** Stop the VMM if any daemon exits while it runs. */\n  supervise: (vmm: ChildProcess, vmmExit: ExitWatcher) => void\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 | string>\n\n/** Reconcile an ambiguous command failure against the VMM before releasing the fence. */\nexport async function setVmmState(call: VmmApiCall, socketPath: string, desired: 'Paused' | 'Running'): Promise<void> {\n  try {\n    await call(socketPath, desired === 'Paused' ? '/api/v1/vm.pause' : '/api/v1/vm.resume')\n  } catch (error) {\n    try {\n      const response = await call(socketPath, '/api/v1/vm.info', undefined, 'GET')\n      const info: unknown = typeof response === 'string' ? JSON.parse(response) : null\n      if (info && typeof info === 'object' && 'state' in info && info.state === desired) return\n    } catch { /* State is unknown: preserve the original failure and the request fence. */ }\n    throw error\n  }\n}\n\nconst vmmApi: VmmApiCall = async (socketPath, path, body, method = 'PUT') => {\n  const payload = body === undefined ? undefined : Buffer.from(JSON.stringify(body), 'utf8')\n  return await new Promise<string>((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(Buffer.concat(chunks).toString('utf8'))\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 = {\n  boot: (plan, hooks) => createCloudHypervisorBackend().boot(plan, hooks),\n}\n"]}