@braedonsaunders/appkit-desk 0.9.0 → 0.11.0

package/host.js

@@ -8,9 +8,9 @@
  * emission to the consumer's ports, and the handover masking contract. It
  * never touches a database and knows nothing about tenants or approvals.
  */
-import { existsSync } from 'node:fs';
+import { createReadStream, existsSync } from 'node:fs';
 import { execFile } from 'node:child_process';
-import { mkdir, readFile, rm, statfs, writeFile } from 'node:fs/promises';
+import { mkdir, open, readFile, rename, rm, statfs, writeFile } from 'node:fs/promises';
 import { arch, cpus, release, tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
@@ -20,6 +20,8 @@ import { buildDeskLaunchPlan, cleanDeskId, DEFAULT_KVM_PATH, DEFAULT_VMM_PATH, D
 import { cloudHypervisorBackend, } from './backend.js';
 import { readShareManifest } from './machine.js';
 import { parseCapabilities, parseClipboardText, parseExecResult, parseHandoverBegun, parseJobStarted, parseObservation, } from './protocol.js';
+/** Capability marker for the fenced template lifecycle and mapping proof. */
+export const DESK_TEMPLATE_VERSION = 3;
 export const DEFAULT_CAPACITY = 4;
 export const DEFAULT_IDLE_SUSPEND_MS = 5 * 60_000;
 export const DEFAULT_LEASE_MS = 15 * 60_000;
@@ -62,6 +64,21 @@ export function createDeskHost(options) {
     const deviceExists = options.deviceExists ?? existsSync;
     const removeOverlay = options.removeOverlay ?? ((path) => rm(path, { force: true }));
     const parkWithMemory = options.parkWithMemory ?? false;
+    if (options.strictMemoryRestore && !parkWithMemory)
+        throw new DeskError('Strict memory restore requires parkWithMemory.');
+    if (options.memoryRestoreMode && (!parkWithMemory || backend.hypervisor === 'virtualization')) {
+        throw new DeskError('Copy-on-write restore requires Cloud Hypervisor and parkWithMemory.');
+    }
+    const retireSnapshot = options.retireSnapshot ?? (async (from, to) => {
+        await rename(from, to);
+        const directory = await open(dirname(from), 'r');
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+    });
     const makeSnapshotDir = options.makeSnapshotDir ?? ((path) => mkdir(path, { recursive: true }).then(() => undefined));
     const removeSnapshot = options.removeSnapshot ?? ((path) => rm(path, { recursive: true, force: true }));
     const freeBytes = options.freeBytes ?? defaultFreeBytes;
@@ -92,6 +109,7 @@ export function createDeskHost(options) {
     const queue = [];
     let occupied = 0;
     let nextCid = positiveInteger(options.cidBase ?? DEFAULT_CID_BASE, 'cidBase');
+    const cidOwners = new Map();
     let lastStartedAt = null;
     let lastSuspendedAt = null;
     let lastError = null;
@@ -125,7 +143,7 @@ export function createDeskHost(options) {
         record.lastActivityAt = now();
     }
     function requireMachine(record, epoch) {
-        if (record.status !== 'resident' || record.epoch !== epoch || !record.machine) {
+        if (record.status !== 'resident' || record.paused || record.epoch !== epoch || !record.machine) {
             throw new DeskError(`Desk ${record.deskId} is not resident; resume it first.`);
         }
         return record.machine;
@@ -280,9 +298,46 @@ export function createDeskHost(options) {
     function snapshotDirFor(overlayPath, deskId) {
         return join(dirname(overlayPath), `${deskId}.snapshot`);
     }
-    async function teardown(record, keepMemory = true) {
+    function strictMemory(start) {
+        return Boolean(options.strictMemoryRestore || start.strictMemoryRestore || start.template
+            || (start.memoryRestoreMode ?? options.memoryRestoreMode) === 'ondemand');
+    }
+    async function clearRestoreMarker(snapshotDir) {
+        await rm(`${snapshotDir}.restore-pending`, { force: true });
+        const parent = await open(dirname(snapshotDir), 'r');
+        try {
+            await parent.sync();
+        }
+        finally {
+            await parent.close();
+        }
+    }
+    async function teardown(record, keepMemory = true, hooks) {
+        let sidecarFailed = false;
+        if (hooks) {
+            const supplied = hooks;
+            hooks = { ...supplied, onPausedError: error => { sidecarFailed = true; supplied.onPausedError?.(error); } };
+        }
+        if (record.status === 'suspending' && record.machine) {
+            // A previous stop failed. Keep the overlay fenced until a retry confirms
+            // the VMM has exited; never boot another VM or delete it underneath one.
+            await record.machine.shutdown();
+            await removeSnapshot(snapshotDirFor(record.startOptions.overlayPath, record.deskId));
+            record.machine = null;
+            record.status = 'suspended';
+            occupied -= 1;
+            lastSuspendedAt = iso(now());
+            drainQueue();
+            return true;
+        }
         if (record.status !== 'resident')
             return false;
+        // Resume before issuing trim, sync, or handover commands. On failure leave
+        // the resident record intact and fenced so the caller can retry.
+        if (record.paused) {
+            await record.machine.resume();
+            record.paused = false;
+        }
         await endHandover(record, 'revoked');
         for (const stop of [...record.streamStops])
             stop();
@@ -330,24 +385,108 @@ export function createDeskHost(options) {
             // it is flushed exactly as a park is.
             if (parking || !keepMemory)
                 await syncGuest(record, machine);
+            if (hooks && (!parking || !machine.supportsPausedParkHook)) {
+                try {
+                    hooks.onPausedError?.(new DeskError('Paused park hooks are unavailable'));
+                }
+                catch { /* preserve memory */ }
+                hooks = undefined;
+            }
             try {
                 if (parking) {
                     const snapshotDir = snapshotDirFor(record.startOptions.overlayPath, record.deskId);
                     await makeSnapshotDir(snapshotDir);
-                    await machine.park(snapshotDir);
+                    // Persist attachment identity before the VMM can produce a complete
+                    // snapshot. A crash must never leave attached VM state with no record.
+                    if (record.startOptions.readOnlyAttachments?.length) {
+                        const manifest = join(snapshotDir, 'attachments.json');
+                        const file = await open(manifest, 'wx', 0o600);
+                        try {
+                            await file.writeFile(JSON.stringify(record.startOptions.readOnlyAttachments));
+                            await file.sync();
+                        }
+                        finally {
+                            await file.close();
+                        }
+                        const directory = await open(snapshotDir, 'r');
+                        try {
+                            await directory.sync();
+                        }
+                        finally {
+                            await directory.close();
+                        }
+                    }
+                    if (hooks?.beforePark) {
+                        try {
+                            await hooks.beforePark(machine);
+                        }
+                        catch (error) {
+                            try {
+                                hooks.onPausedError?.(error);
+                            }
+                            catch { /* preserve memory */ }
+                            ;
+                            hooks = undefined;
+                        }
+                    }
+                    await machine.park(snapshotDir, hooks);
                     const signature = await (options.cpuSignature ?? hostCpuSignature)();
                     await (options.writeSnapshotSignature ?? writeSnapshotSignature)(snapshotDir, signature);
+                    if (strictMemory(record.startOptions) || (hooks?.onParked && !sidecarFailed)) {
+                        for (const name of ['config.json', 'state.json', 'memory-ranges', 'appkit-cpu-signature']) {
+                            const file = await open(join(snapshotDir, name), 'r');
+                            try {
+                                await file.sync();
+                            }
+                            finally {
+                                await file.close();
+                            }
+                        }
+                        const directory = await open(snapshotDir, 'r');
+                        try {
+                            await directory.sync();
+                        }
+                        finally {
+                            await directory.close();
+                        }
+                        const parent = await open(dirname(snapshotDir), 'r');
+                        try {
+                            await parent.sync();
+                        }
+                        finally {
+                            await parent.close();
+                        }
+                        if (strictMemory(record.startOptions))
+                            await clearRestoreMarker(snapshotDir);
+                    }
+                    if (hooks?.onParked && !sidecarFailed) {
+                        try {
+                            await hooks.onParked(snapshotDir);
+                        }
+                        catch (error) {
+                            try {
+                                hooks.onPausedError?.(error);
+                            }
+                            catch { /* preserve memory */ }
+                        }
+                    }
                 }
                 else {
                     await machine.shutdown();
                 }
             }
             catch (error) {
-                // `park` stops the VMM on its own way out, so the desk is down either
-                // way; what is lost is the memory, not the desk. Leave nothing behind
-                // that a later boot would try to restore from.
+                // Preparation can fail before park is called, so confirm the VMM is
+                // down even when park itself normally stops on failure.
                 lastError = errorMessage(error);
-                if (parking) {
+                try {
+                    await machine.shutdown();
+                }
+                catch (stopError) {
+                    record.machine = machine;
+                    throw new DeskError(`Desk ${record.deskId} could not stop after teardown failed: ${errorMessage(stopError)}`);
+                }
+                if (parking && !strictMemory(record.startOptions)) {
                     await removeSnapshot(snapshotDirFor(record.startOptions.overlayPath, record.deskId)).catch(() => undefined);
                 }
             }
@@ -416,11 +555,35 @@ export function createDeskHost(options) {
         // as whatever the overlay copy fails with.
         await admitDisk(startOptions.overlayPath);
         const snapshotDir = snapshotDirFor(startOptions.overlayPath, deskId);
+        const strictRestore = strictMemory(startOptions);
+        const restoreMode = startOptions.template ? 'copyonwrite' : startOptions.memoryRestoreMode ?? options.memoryRestoreMode;
+        if ((strictRestore || restoreMode) && (!parkWithMemory || backend.hypervisor === 'virtualization'))
+            throw new DeskError('Strict or copy-on-write restore requires Cloud Hypervisor and parkWithMemory.');
+        if (strictRestore && existsSync(`${snapshotDir}.restore-pending`)) {
+            throw new DeskError(`Desk ${deskId} has an interrupted memory restore; operator recovery is required.`);
+        }
         // The SAME cid for both attempts below. A restored VM's snapshotted config
         // names its vsock and tap, and a cold-boot retry that renumbered them would
         // come up on a different tap than the one the egress rules were put on.
-        const cid = nextCid++;
-        const initramfsPath = resolveInitramfsPath();
+        let cid;
+        if (startOptions.vsockCid !== undefined) {
+            cid = startOptions.vsockCid;
+            if (!Number.isSafeInteger(cid) || cid < 3 || cid > 0xfffffffe)
+                throw new DeskError('Invalid guest vsock CID.');
+            const owner = cidOwners.get(cid);
+            if (owner !== undefined && owner !== deskId)
+                throw new DeskError('Guest vsock CID is already assigned.');
+        }
+        else {
+            while (cidOwners.has(nextCid))
+                nextCid++;
+            cid = nextCid++;
+            if (cid > 0xfffffffe)
+                throw new DeskError('Guest vsock CID space exhausted.');
+        }
+        cidOwners.set(cid, deskId);
+        const initramfsPath = startOptions.initramfsPath ?? resolveInitramfsPath();
+        let restoreDir = snapshotDir;
         const planFor = (restore, shares = startOptions.shares) => buildDeskLaunchPlan({
             deskId,
             hypervisor: backend.hypervisor ?? 'cloud-hypervisor',
@@ -429,26 +592,28 @@ export function createDeskHost(options) {
                 : { virtiofsdPath: options.virtiofsdPath, virtiofsdSandbox: options.virtiofsdSandbox }),
             vmmPath: options.vmmPath,
             kvmPath: options.kvmPath,
-            kernelPath,
+            kernelPath: startOptions.kernelPath ?? kernelPath,
             ...(initramfsPath === undefined ? {} : { initramfsPath }),
             baseImagePath: startOptions.baseImage,
             overlayPath: startOptions.overlayPath,
             memoryMb: startOptions.memoryMb,
+            freePageReporting: startOptions.freePageReporting,
             vcpus: startOptions.vcpus,
             vsockCid: cid,
             runtimeDir: options.runtimeDir,
             tapDevice: startOptions.network?.tapDevice,
             macAddress: startOptions.network?.macAddress,
             shares,
+            readOnlyAttachments: startOptions.readOnlyAttachments,
             // Forward the host's cmdline only when set; otherwise the plan falls
             // back to DEFAULT_KERNEL_CMDLINE.
             ...(kernelCmdline === undefined ? {} : { kernelCmdline }),
             launcherIdentity: options.launcherIdentity,
-            snapshotDir,
-            ...(restore ? { restore: true } : {}),
-        }, { pathExists, deviceExists, ...(options.isDirectory ? { isDirectory: options.isDirectory } : {}) });
+            snapshotDir: restore ? restoreDir : snapshotDir,
+            ...(restore ? { restore: true, ...(restoreMode ? { memoryRestoreMode: restoreMode } : {}) } : {}),
+        }, { pathExists: (path) => Boolean(startOptions.template && path === dirname(startOptions.overlayPath)) || pathExists(path), deviceExists, ...(options.isDirectory ? { isDirectory: options.isDirectory } : {}) });
         const restorePlan = async () => {
-            const parked = await (options.readSnapshotShares ?? readShareManifest)(snapshotDir);
+            const parked = await (options.readSnapshotShares ?? readShareManifest)(restoreDir);
             try {
                 return planFor(true, parked);
             }
@@ -456,34 +621,159 @@ export function createDeskHost(options) {
                 throw new DeskError(`its restore, with the shares it was parked with, could not be planned: ${errorMessage(error)}`);
             }
         };
+        // Verify bytes, not just the caller's label, before the VMM can map them.
+        for (const image of startOptions.readOnlyAttachments ?? []) {
+            const hash = createHash('sha256');
+            for await (const chunk of createReadStream(image.path))
+                hash.update(chunk);
+            if (hash.digest('hex') !== image.sha256)
+                throw new DeskError(`Read-only attachment digest mismatch: ${image.path}`);
+        }
+        let initializeTemplate = false;
+        if (startOptions.template) {
+            if (!strictRestore || restoreMode !== 'copyonwrite' || backend.hypervisor === 'virtualization') {
+                throw new DeskError('Template forks require strict Cloud Hypervisor copy-on-write restore.');
+            }
+            const childDir = dirname(startOptions.overlayPath);
+            const prepared = join(childDir, '.prepared');
+            const initialized = join(childDir, '.initialized');
+            if (existsSync(initialized) && !existsSync(snapshotDir))
+                throw new DeskError('Template descendant has no saved memory; recovery is required.');
+            if (existsSync(initialized))
+                await startOptions.template.verifyResume(planFor(true));
+            if (!existsSync(initialized)) {
+                await startOptions.template.holdFence();
+                if (!existsSync(prepared)) {
+                    if (existsSync(startOptions.overlayPath) || existsSync(snapshotDir))
+                        throw new DeskError('Incomplete template fork needs recovery.');
+                    await startOptions.template.prepare(planFor(false));
+                }
+                if (await readFile(prepared, 'utf8') !== '1\n' || !existsSync(startOptions.overlayPath) || !existsSync(snapshotDir))
+                    throw new DeskError('Template fork was not prepared completely.');
+                const planned = planFor(true);
+                if (planned.hypervisor !== 'cloud-hypervisor')
+                    throw new DeskError('Template fork requires Cloud Hypervisor.');
+                const savedConfig = JSON.parse(await readFile(join(snapshotDir, 'config.json'), 'utf8'));
+                if (savedConfig.disks?.[0]?.path !== startOptions.overlayPath || savedConfig.net?.[0]?.tap !== planned.tap.device
+                    || savedConfig.net?.[0]?.mac?.toLowerCase() !== planned.tap.mac.toLowerCase()
+                    || savedConfig.vsock?.cid !== planned.vsock.cid || savedConfig.vsock.socket !== planned.vsock.socketPath
+                    || savedConfig.memory?.size !== planned.memoryMb * 1024 * 1024 || savedConfig.cpus?.boot_vcpus !== planned.vcpus) {
+                    throw new DeskError('Prepared template device or resource identity does not match its launch plan.');
+                }
+                await startOptions.template.verifyPrepared(planned);
+                initializeTemplate = true;
+            }
+        }
         let resuming = parkWithMemory && pathExists(snapshotDir);
+        if (initializeTemplate && !resuming)
+            throw new DeskError('A template fork requires its prepared snapshot.');
+        // Shared guest memory, required by virtio-fs, makes Cloud Hypervisor fall
+        // back to eager restore. Reject before retiring the snapshot or cold booting.
+        if (restoreMode) {
+            if (startOptions.shares?.length)
+                throw new DeskError('Copy-on-write or on-demand restore cannot be combined with virtio-fs shares.');
+            if (resuming && (await (options.readSnapshotShares ?? readShareManifest)(snapshotDir)).length) {
+                throw new DeskError('The parked snapshot has virtio-fs shares and cannot use copy-on-write or on-demand restore.');
+            }
+        }
         if (resuming) {
+            let savedAttachments;
+            try {
+                savedAttachments = JSON.parse(await readFile(join(snapshotDir, 'attachments.json'), 'utf8'));
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                savedAttachments = [];
+            }
+            if (JSON.stringify(savedAttachments) !== JSON.stringify(startOptions.readOnlyAttachments ?? [])) {
+                throw new DeskError('Snapshot read-only attachment identity does not match; restore requires the original images.');
+            }
             const saved = await (options.readSnapshotSignature ?? readSnapshotSignature)(snapshotDir);
+            if (strictRestore && saved === null)
+                throw new DeskError(`Desk ${deskId} snapshot has no CPU identity.`);
             if (saved !== null && saved !== await (options.cpuSignature ?? hostCpuSignature)()) {
+                if (strictRestore)
+                    throw new DeskError(`Desk ${deskId} snapshot CPU identity does not match.`);
                 await removeSnapshot(snapshotDir);
                 resuming = false;
                 recordCpuFallback(deskId, 'signature_mismatch');
             }
         }
+        if (strictRestore) {
+            const marker = await open(`${snapshotDir}.restore-pending`, 'wx', 0o600);
+            try {
+                await marker.writeFile('restore in progress\n');
+                await marker.sync();
+            }
+            finally {
+                await marker.close();
+            }
+            const parent = await open(dirname(snapshotDir), 'r');
+            try {
+                await parent.sync();
+            }
+            finally {
+                await parent.close();
+            }
+        }
+        // Retire before starting the VMM: after a crash the old name can never be
+        // replayed against a disk the guest may have changed. The retired file is
+        // private backing memory, not a restorable snapshot.
+        if (resuming && restoreMode) {
+            restoreDir = `${snapshotDir}.source-${randomUUID()}`;
+            await retireSnapshot(snapshotDir, restoreDir);
+        }
         let machine;
         try {
+            const launchPlan = resuming ? await restorePlan() : planFor(false);
+            if (resuming && (startOptions.template || (startOptions.strictMemoryRestore && restoreMode === 'copyonwrite')))
+                launchPlan.snapshot.requirePrivateMemoryMapping = true;
             machine = resuming
-                ? await backend.boot(await restorePlan(), {
-                    // The guest is restored and PAUSED here. Destroying the snapshot in
-                    // this window is what stops a memory image ever outliving the disk
-                    // state it belongs to. If it fails the restore is abandoned rather
-                    // than resumed, because resuming would leave both alive at once.
-                    onRestored: () => removeSnapshot(snapshotDir),
+                ? await backend.boot(launchPlan, {
+                    // Eager restore removes the parked snapshot before resume. A CoW
+                    // source was already retired durably before the VMM started.
+                    onRestored: restoreMode ? async () => { } : () => removeSnapshot(snapshotDir),
                 })
-                : await backend.boot(planFor(false));
+                : await backend.boot(launchPlan);
+            if (initializeTemplate && startOptions.template) {
+                try {
+                    await startOptions.template.initialize(machine, launchPlan);
+                    const initialized = await open(join(dirname(startOptions.overlayPath), '.initialized'), 'wx', 0o600);
+                    try {
+                        await initialized.writeFile('1\n');
+                        await initialized.sync();
+                    }
+                    finally {
+                        await initialized.close();
+                    }
+                    const directory = await open(dirname(startOptions.overlayPath), 'r');
+                    try {
+                        await directory.sync();
+                    }
+                    finally {
+                        await directory.close();
+                    }
+                    await startOptions.template.releaseFence();
+                }
+                catch (error) {
+                    await machine.shutdown();
+                    throw error;
+                }
+            }
         }
         catch (error) {
             if (resuming) {
+                if (strictRestore) {
+                    lastError = `Desk ${deskId} memory restore failed: ${errorMessage(error)}`;
+                    throw new DeskError(lastError);
+                }
                 // A snapshot that will not come back is worse than no snapshot: it makes
                 // the desk unbootable for as long as it sits there. Drop it and cold
                 // boot. Safe by construction — the guest never ran, so the disk is
                 // exactly as the pre-park sync left it.
                 const why = errorMessage(error);
+                resuming = false;
                 await removeSnapshot(snapshotDir);
                 if (isIncompatibleCpuSnapshotError(error))
                     recordCpuFallback(deskId, 'incompatible_cpuid');
@@ -499,12 +789,31 @@ export function createDeskHost(options) {
                     : new DeskError(`Desk ${deskId} failed to boot: ${errorMessage(error)}`);
             }
         }
+        if (resuming && restoreMode) {
+            // The mapping remains file-backed until the VMM has exited. Never remove
+            // it after a failed stop; leaking it is safer than invalidating a live VM.
+            const restored = machine;
+            const stop = restored.shutdown.bind(restored);
+            const park = restored.park?.bind(restored);
+            const releaseSource = async () => {
+                try {
+                    await removeSnapshot(restoreDir);
+                }
+                catch (error) {
+                    lastError = `Snapshot source cleanup failed for ${deskId}: ${errorMessage(error)}`;
+                }
+            };
+            restored.shutdown = async () => { await stop(); await releaseSource(); };
+            if (park)
+                restored.park = async (dir, hooks) => { await park(dir, hooks); await releaseSource(); };
+        }
         let record = records.get(deskId);
         if (!record) {
             record = {
                 deskId,
                 startOptions,
                 status: 'resident',
+                paused: false,
                 machine,
                 epoch: 1,
                 leaseDeadline: 0,
@@ -523,6 +832,7 @@ export function createDeskHost(options) {
         else {
             record.startOptions = startOptions;
             record.status = 'resident';
+            record.paused = false;
             record.machine = machine;
             record.epoch += 1;
             record.jobs = new Map();
@@ -769,22 +1079,28 @@ export function createDeskHost(options) {
         return {
             deskId: record.deskId,
             renewLease(ms) {
-                requireMachine(record, epoch);
+                // Renewing a lease is host-side and remains valid during resident pause.
+                if (record.status !== 'resident' || record.epoch !== epoch || !record.machine) {
+                    throw new DeskError(`Desk ${record.deskId} is not resident; resume it first.`);
+                }
                 record.leaseDeadline = now() + positiveInteger(ms, 'ms');
                 touch(record);
                 armTimer(record);
             },
-            async connect(port) {
+            async connect(port, choice) {
                 requireMachine(record, epoch);
                 if (!Number.isInteger(port) || port < 1 || port > 65535)
                     throw new DeskError('Guest TCP port must be between 1 and 65535.');
                 const machine = requireMachine(record, epoch);
                 const address = record.startOptions.network?.guestAddress;
-                if (!machine.connect && (!address || isIP(address) !== 4))
+                const useVsock = choice?.transport === 'vsock' || (choice?.transport !== 'tcp' && !!machine.connect);
+                if (useVsock && !machine.connect)
+                    throw new DeskError('This backend has no service vsock connector.');
+                if (!useVsock && (!address || isIP(address) !== 4))
                     throw new DeskError('A guest IPv4 address is required to connect to a desk port.');
                 touch(record);
                 try {
-                    const stream = machine.connect ? await machine.connect(port) : await (options.connectGuest ?? connectGuestTcp)(address, port);
+                    const stream = useVsock ? await machine.connect(port) : await (options.connectGuest ?? connectGuestTcp)(address, port);
                     try {
                         requireMachine(record, epoch);
                     }
@@ -1162,29 +1478,61 @@ export function createDeskHost(options) {
         const deskId = cleanDeskId(startOptions.deskId);
         return serializeLifecycle(deskId, async () => {
             const existing = records.get(deskId);
-            if (existing?.status === 'resident' && existing.handle)
+            if (existing?.status === 'suspending')
+                throw new DeskError(`Desk ${deskId} has not stopped; retry suspend first.`);
+            if (existing?.status === 'resident' && existing.handle) {
+                if (existing.paused) {
+                    await existing.machine.resume();
+                    existing.paused = false;
+                }
                 return existing.handle;
+            }
             return admit(() => boot(deskId, { ...startOptions, deskId }));
         });
     }
+    function canPause(deskId) {
+        const record = records.get(cleanDeskId(deskId));
+        return record?.status === 'resident' && typeof record.machine?.pause === 'function' && typeof record.machine?.resume === 'function';
+    }
+    async function pause(deskId) {
+        const id = cleanDeskId(deskId);
+        await serializeLifecycle(id, async () => {
+            const record = records.get(id);
+            if (!record || record.status !== 'resident' || !canPause(id))
+                throw new DeskError(`Desk ${id} cannot be paused.`);
+            if (record.paused)
+                return;
+            if (record.screen?.handover)
+                throw new DeskError(`Desk ${id} has an active handover.`);
+            record.paused = true;
+            await record.machine.pause();
+        });
+    }
     async function resume(deskId) {
         const id = cleanDeskId(deskId);
         return serializeLifecycle(id, async () => {
             const record = records.get(id);
             if (!record)
                 throw new DeskError(`Unknown desk: ${deskId}`);
-            if (record.status === 'resident' && record.handle)
+            if (record.status === 'suspending')
+                throw new DeskError(`Desk ${id} has not stopped; retry suspend first.`);
+            if (record.status === 'resident' && record.handle) {
+                if (record.paused) {
+                    await record.machine.resume();
+                    record.paused = false;
+                }
                 return record.handle;
+            }
             return admit(() => boot(record.deskId, record.startOptions));
         });
     }
-    async function suspend(deskId) {
+    async function suspend(deskId, hooks) {
         const id = cleanDeskId(deskId);
         await serializeLifecycle(id, async () => {
             const record = records.get(id);
             if (!record)
                 return;
-            await teardown(record);
+            await teardown(record, true, hooks);
         });
     }
     async function shutdown(deskId) {
@@ -1197,7 +1545,10 @@ export function createDeskHost(options) {
             // A desk parked earlier still has its memory image on disk; dropping it is
             // what makes the next boot cold. The overlay is untouched — only `destroy`
             // may remove it.
-            await removeSnapshot(snapshotDirFor(record.startOptions.overlayPath, record.deskId));
+            const snapshot = snapshotDirFor(record.startOptions.overlayPath, record.deskId);
+            await removeSnapshot(snapshot);
+            if (strictMemory(record.startOptions))
+                await clearRestoreMarker(snapshot);
         });
     }
     /**
@@ -1296,7 +1647,7 @@ export function createDeskHost(options) {
             lastSnapshotCpuFallback,
         };
     }
-    return { start, resume, suspend, shutdown, destroy, stats, sweep };
+    return { start, canPause, pause, resume, suspend, shutdown, destroy, stats, sweep };
 }
 /**
  * Whether the overlay directory's filesystem can make reflink clones.