windows-development-sandbox 1.7.0 → 1.10.0

package/dist/host/engines/engine.d.ts

@@ -0,0 +1,12 @@
+import type { EngineCapabilities, EngineCheck, EngineId, EnginePlan, LaunchPlan, RunningSandbox } from './types.js';
+export interface SandboxEngine {
+    readonly id: EngineId;
+    capabilities(): EngineCapabilities;
+    check(): Promise<EngineCheck>;
+    /** Pure: the engine's own files for this launch. */
+    plan(launch: LaunchPlan): EnginePlan;
+    /** Starts the sandbox from a plan whose files are written, and waits until it is up. */
+    start(plan: EnginePlan): Promise<RunningSandbox>;
+    running(): Promise<boolean>;
+    stop(): Promise<void>;
+}

package/dist/host/engines/engine.js

@@ -0,0 +1 @@
+export {};

package/dist/host/engines/hcs/check.d.ts

@@ -0,0 +1,25 @@
+import type { EngineCheck } from '../types.js';
+import { type ImageStore } from './images.js';
+/** Windows 10 1809: the first build with the Host Compute Service API (Microsoft HCS overview). */
+export declare const MIN_BUILD = 17763;
+export interface TokenGroups {
+    /** The token is an elevated member of Administrators. */
+    readonly elevatedAdministrator: boolean;
+    /** The token has Hyper-V Administrators (S-1-5-32-578). */
+    readonly hyperVAdministrators: boolean;
+}
+/** Everything the check looks at, so tests give it a fake PC. */
+export interface HcsProbes {
+    isWindows(): boolean;
+    windowsBuild(): number | null;
+    /** Whether a Windows service exists; null when that could not be told. */
+    serviceInstalled(name: string): boolean | null;
+    fileExists(file: string): boolean;
+    tokenGroups(): TokenGroups | null;
+    imageStores(): readonly ImageStore[];
+}
+export declare function checkHcs(p: HcsProbes): EngineCheck;
+/** The groups of a token from `whoami /groups /fo csv /nh`: name, type, SID, attributes per line. */
+export declare function parseWhoamiGroups(csv: string): TokenGroups;
+/** The real probes: sc.exe query, whoami, file checks. They only read. */
+export declare function realHcsProbes(): HcsProbes;

package/dist/host/engines/hcs/check.js

@@ -0,0 +1,95 @@
+// The HCS engine's check: what this PC has and lacks. Read-only: it looks (service list, files, the token's groups)
+// and answers with the reasons and the exact commands that would fix each one. It NEVER runs a fix: turning on a
+// Windows feature or adding a group member is the owner's choice (docs/design/engines.md, "Never").
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { SYSTEM, system32 } from '../../../shared/system.js';
+import { isWin } from '../../../core/util/index.js';
+import { defaultImageStores, findImage } from './images.js';
+/** Windows 10 1809: the first build with the Host Compute Service API (Microsoft HCS overview). */
+export const MIN_BUILD = 17763;
+const ENABLE = 'Enable-WindowsOptionalFeature -Online -All -FeatureName ';
+export function checkHcs(p) {
+    const reasons = [];
+    const fixes = [];
+    const need = (reason, fix) => {
+        reasons.push(reason);
+        fixes.push(fix);
+    };
+    if (!p.isWindows())
+        return { available: false, reasons: ['The HCS engine only runs on Windows.'], fixes: ['Use "windows-sandbox".'] };
+    const build = p.windowsBuild();
+    if (build !== null && build < MIN_BUILD)
+        need('Windows build ' +
+            build +
+            ' is too old: the Host Compute Service needs Windows 10 1809 (build ' +
+            MIN_BUILD +
+            ') or newer.', 'Update Windows.');
+    if (!p.fileExists(path.join(system32Dir(), 'computecore.dll')))
+        need('computecore.dll (the Host Compute Service API) is not on this PC.', 'It comes with the Windows virtualization features (not in Windows Home). In an admin PowerShell, then restart: ' +
+            ENABLE +
+            'VirtualMachinePlatform  (the owner decides: this changes Windows)');
+    if (p.serviceInstalled('vmcompute') === false)
+        need('The Hyper-V Host Compute Service (vmcompute) is not installed.', 'In an admin PowerShell, then restart: ' +
+            ENABLE +
+            'Microsoft-Hyper-V-All  (needs Windows Pro, Enterprise or Education)');
+    if (p.serviceInstalled('cexecsvc') === false)
+        need('The Windows Containers feature is not turned on (its Container Execution Agent service is missing).', 'In an admin PowerShell, then restart: ' + ENABLE + 'Containers');
+    const token = p.tokenGroups();
+    if (token && !token.elevatedAdministrator && !token.hyperVAdministrators)
+        need('This Windows user is neither an elevated Administrator nor in Hyper-V Administrators, and the Host Compute Service refuses anyone else (HCS_E_ACCESS_DENIED, https://aka.ms/hcsadmin).', 'Either start the terminal as administrator, or in an admin PowerShell add yourself, then sign out and in: net localgroup "Hyper-V Administrators" "%USERDOMAIN%\\%USERNAME%" /add');
+    const image = findImage(p.imageStores());
+    if (!image.image)
+        need('No Windows Server Core (ltsc2022) image is on this PC. ' + image.reason, 'Pull one with Docker Desktop (Windows containers mode): docker pull mcr.microsoft.com/windows/servercore:ltsc2022  - or put your own in a folder with an image.json and set AGENT_SANDBOX_HCS_IMAGE to it. This tool does not download images in this alpha.');
+    return { available: reasons.length === 0, reasons, fixes };
+}
+function system32Dir() {
+    return path.dirname(system32('x'));
+}
+/** The groups of a token from `whoami /groups /fo csv /nh`: name, type, SID, attributes per line. */
+export function parseWhoamiGroups(csv) {
+    let elevated = false;
+    let hyperV = false;
+    for (const line of csv.split(/\r?\n/)) {
+        const cells = [...line.matchAll(/"([^"]*)"/g)].map((m) => m[1]);
+        if (cells.length < 4)
+            continue;
+        const [, , sid, attributes] = cells;
+        const denyOnly = /deny only/i.test(attributes);
+        if (sid === 'S-1-5-32-544' && !denyOnly)
+            elevated = true;
+        if (sid === 'S-1-5-32-578' && !denyOnly)
+            hyperV = true;
+    }
+    return { elevatedAdministrator: elevated, hyperVAdministrators: hyperV };
+}
+const QUERY_TIMEOUT_MS = 10000;
+/** The real probes: sc.exe query, whoami, file checks. They only read. */
+export function realHcsProbes() {
+    return {
+        isWindows: () => isWin,
+        windowsBuild: () => {
+            const m = /^\d+\.\d+\.(\d+)/.exec(os.release());
+            return m ? Number(m[1]) : null;
+        },
+        serviceInstalled: (name) => {
+            const r = spawnSync(SYSTEM.sc(), ['query', name], { windowsHide: true, timeout: QUERY_TIMEOUT_MS });
+            if (r.status === 0)
+                return true;
+            return r.status === 1060 ? false : null; // 1060: the service does not exist
+        },
+        fileExists: (file) => fs.existsSync(file),
+        tokenGroups: () => {
+            const r = spawnSync(SYSTEM.whoami(), ['/groups', '/fo', 'csv', '/nh'], {
+                windowsHide: true,
+                timeout: QUERY_TIMEOUT_MS,
+                encoding: 'utf8',
+                maxBuffer: 1024 * 1024,
+            });
+            return r.status === 0 ? parseWhoamiGroups(r.stdout) : null;
+        },
+        imageStores: () => defaultImageStores(),
+    };
+}

package/dist/host/engines/hcs/documents.d.ts

@@ -0,0 +1,44 @@
+import type { LaunchPlan } from '../types.js';
+export declare const HCS_OWNER = "agent-sandbox";
+/** The Container's Windows-side folder for the agent disk's own sub-folders. */
+export declare const AGENT_DISK_FOLDERS: readonly ["tools", "state", "logs"];
+export type HcsDocument = Readonly<Record<string, unknown>>;
+/** A base image already on this PC. Layers are the folders of the image, base layer first. */
+export interface HcsImage {
+    readonly id: string;
+    /** Folders of the image layers, base first. */
+    readonly layers: readonly string[];
+    /** The base layer's UtilityVM\Files folder (the kernel and files of the utility VM). */
+    readonly utilityVmFiles: string;
+}
+export interface HcsDocumentInput {
+    readonly launch: LaunchPlan;
+    readonly image: HcsImage;
+    /** The utility VM's id; the container's is `<id>-c`. [a-zA-Z0-9._-] only. */
+    readonly id: string;
+    /** The writable layer (scratch) VHDX of this run: made before start, deleted after. */
+    readonly scratchVhdx: string;
+    /** Processors of this PC, to turn a CPU percentage into a count. */
+    readonly hostCpus: number;
+}
+export interface HcsDiskPlan {
+    readonly image: string;
+    readonly maxGb: number;
+    readonly lun: number;
+}
+export interface HcsDocuments {
+    readonly uvmId: string;
+    readonly containerId: string;
+    readonly uvm: HcsDocument;
+    readonly container: HcsDocument;
+    /** The agent disks (read-write) to create, give the utility VM access to and attach. */
+    readonly disks: readonly HcsDiskPlan[];
+    /** Things the plan asked for that this engine does not do (shown to the user). */
+    readonly notes: readonly string[];
+}
+/** A GUID made from a path, so a layer has the same id every time. [U] hcsshim names layers the same way. */
+export declare function layerGuid(folder: string): string;
+export declare function containerId(uvmId: string): string;
+/** Processors for a percentage of this PC ('none' = all of them), at least one. */
+export declare function cpuCount(limit: LaunchPlan['cpuLimit'], hostCpus: number): number;
+export declare function buildDocuments(input: HcsDocumentInput): HcsDocuments;

package/dist/host/engines/hcs/documents.js

@@ -0,0 +1,155 @@
+// Pure: the HCS compute-system documents (schema 2.x JSON) for a Hyper-V isolated Windows container, from a
+// LaunchPlan.
+//
+// Two documents, as hcsshim does it for a container with Hyper-V isolation:
+//   1. the utility VM: ComputeSystem { VirtualMachine { Chipset, ComputeTopology,
+//      Devices { Scsi, VirtualSmb, HvSocket }, GuestConnection } }
+//   2. the container inside it: ComputeSystem { HostingSystemId, HostedSystem { Container { GuestOs, Storage, Memory,
+//      MappedDirectories, HvSocket } } }
+//
+// Schema reference used (learn.microsoft.com/virtualization/api/hcs/schemareference), field names and casing taken
+// from these tables: ComputeSystem, VirtualMachine, Topology, VirtualMachine_Memory, VirtualMachine_Processor,
+// Devices, Scsi, Attachment (AttachmentType "VirtualDisk", CachingMode), VirtualSmb, VirtualSmbShare,
+// VirtualSmbShareOptions, VirtualMachine_HvSocket, HvSocketSystemConfig, Chipset, Uefi, UefiBootEntry,
+// GuestConnection, HostedSystem, Container, GuestOs, Container_Memory, Layer (PathType "VirtualSmbShareName"),
+// MappedDirectory (HostPathType), Container_HvSocket, Version.
+//
+// NOT verified (each is marked [U] where it is used, and listed in the report):
+//   - the boot entry of the utility VM and the "os" share of the base layer's UtilityVM\Files (hcsshim from memory);
+//   - the order of the layers (topmost first here);
+//   - where a SCSI disk appears inside the utility VM and how a blank VHDX becomes a formatted volume there;
+//   - the scratch layer (a writable layer VHDX made by HcsInitializeWritableLayer: not built in this phase);
+//   - that Layers / MappedDirectories may name vSMB shares by share name (the PathType values exist in the schema).
+import crypto from 'node:crypto';
+export const HCS_OWNER = 'agent-sandbox';
+/** Schema 2.1 is the first with VirtualSmb options, SCSI caching and Layer.PathType (Windows 10 1809). */
+const SCHEMA = { Major: 2, Minor: 1 };
+/** The Container's Windows-side folder for the agent disk's own sub-folders. */
+export const AGENT_DISK_FOLDERS = ['tools', 'state', 'logs'];
+const GUEST_DATA = 'C:\\AgentData';
+/** Placeholder SDDL: SYSTEM and Administrators only. [U] whether this ACL is what the host side of HvSocket needs. */
+const HVSOCKET_SDDL = 'D:P(A;;FA;;;SY)(A;;FA;;;BA)';
+/** A GUID made from a path, so a layer has the same id every time. [U] hcsshim names layers the same way. */
+export function layerGuid(folder) {
+    const h = crypto.createHash('sha1').update(folder.toLowerCase()).digest('hex');
+    return [h.slice(0, 8), h.slice(8, 12), '5' + h.slice(13, 16), '8' + h.slice(17, 20), h.slice(20, 32)].join('-');
+}
+export function containerId(uvmId) {
+    return uvmId + '-c';
+}
+/** Processors for a percentage of this PC ('none' = all of them), at least one. */
+export function cpuCount(limit, hostCpus) {
+    if (limit === 'none')
+        return Math.max(1, hostCpus);
+    return Math.min(Math.max(1, hostCpus), Math.max(1, Math.ceil((hostCpus * limit) / 100)));
+}
+const hvSocketConfig = {
+    DefaultBindSecurityDescriptor: HVSOCKET_SDDL,
+    DefaultConnectSecurityDescriptor: HVSOCKET_SDDL,
+    ServiceTable: {},
+};
+export function buildDocuments(input) {
+    const { launch, image } = input;
+    const notes = [];
+    const uvmId = input.id;
+    const baseLayers = [...image.layers].reverse(); // topmost first [U]
+    // Utility VM shares: the OS files, each image layer, then the folders shared in.
+    const shares = [
+        {
+            Name: 'os',
+            Path: image.utilityVmFiles,
+            // [U] the options hcsshim gives the OS share of a Windows utility VM.
+            Options: { ReadOnly: true, ShareRead: true, CacheIo: true, TakeBackupPrivilege: true, PseudoOplocks: true },
+        },
+    ];
+    const layers = baseLayers.map((folder, i) => {
+        const name = 'layer' + i;
+        shares.push({ Name: name, Path: folder, Options: { ReadOnly: true, ShareRead: true, NoDirectmap: true } });
+        return { Id: layerGuid(folder), Path: name, PathType: 'VirtualSmbShareName' };
+    });
+    const folderMaps = [];
+    launch.mappings.forEach((m, i) => {
+        const name = 'dir' + i;
+        // NoDirectmap on every folder shared in: no direct file mapping into the guest.
+        shares.push({ Name: name, Path: m.host, Options: { ReadOnly: m.readOnly, NoDirectmap: true } });
+        folderMaps.push({
+            HostPath: name,
+            HostPathType: 'VirtualSmbShareName',
+            ContainerPath: m.guest,
+            ReadOnly: m.readOnly,
+        });
+    });
+    // SCSI controller 0: the agent disks (read-write), then the scratch layer.
+    const disks = [];
+    const attachments = {};
+    const attach = (file, readOnly, lun) => {
+        attachments[String(lun)] = { Type: 'VirtualDisk', Path: file, ReadOnly: readOnly, CachingMode: 'Uncached' };
+    };
+    for (const a of launch.storage) {
+        if (a.kind !== 'disk')
+            continue;
+        const lun = disks.length;
+        disks.push({ image: a.image, maxGb: a.maxGb, lun });
+        attach(a.image, false, lun);
+        // [U] the disk is formatted and mounted in the utility VM at this folder (a blank VHDX is not formatted yet).
+        const volume = 'C:\\agent-disk' + lun;
+        const target = a.guest || GUEST_DATA;
+        for (const folder of AGENT_DISK_FOLDERS)
+            folderMaps.push({
+                HostPath: volume + '\\' + folder,
+                HostPathType: 'AbsolutePath',
+                ContainerPath: target + '\\' + folder,
+                ReadOnly: false,
+            });
+    }
+    attach(input.scratchVhdx, false, disks.length);
+    if (launch.networking)
+        notes.push('Networking is not available in the HCS engine yet: the sandbox has no network adapter.');
+    if (launch.devices.gpu || launch.devices.clipboard || launch.devices.audioInput || launch.devices.videoInput)
+        notes.push('GPU, clipboard, microphone and camera do not exist in the HCS engine.');
+    const uvm = {
+        Owner: HCS_OWNER,
+        SchemaVersion: SCHEMA,
+        // false on purpose: the helper exits after creating the system, which closes its handle; true would end the
+        // system at once. Leftovers are found by owner (sandbox engine clean).
+        ShouldTerminateOnLastHandleClosed: false,
+        VirtualMachine: {
+            StopOnReset: true,
+            Chipset: {
+                // [U] hcsshim's boot entry for a Windows utility VM.
+                Uefi: { BootThis: { DeviceType: 'VmbFs', DevicePath: '\\EFI\\Microsoft\\Boot\\bootmgfw.efi' } },
+            },
+            ComputeTopology: {
+                Memory: { SizeInMB: launch.memoryMb, AllowOvercommit: true },
+                Processor: { Count: cpuCount(launch.cpuLimit, input.hostCpus) },
+            },
+            Devices: {
+                Scsi: { '0': { Attachments: attachments } },
+                VirtualSmb: { Shares: shares },
+                // Placeholder: the control channel's service ids are added when the guest side exists.
+                HvSocket: { HvSocketConfig: hvSocketConfig },
+                // No NetworkAdapters: no network by default.
+            },
+            GuestConnection: {},
+        },
+    };
+    const container = {
+        Owner: HCS_OWNER,
+        SchemaVersion: SCHEMA,
+        ShouldTerminateOnLastHandleClosed: false,
+        HostingSystemId: uvmId,
+        HostedSystem: {
+            SchemaVersion: SCHEMA,
+            Container: {
+                GuestOs: { HostName: 'agent-sandbox' },
+                // [U] Path is the scratch layer's folder as the utility VM sees it.
+                Storage: { Layers: layers, Path: 'C:\\scratch' },
+                Memory: { SizeInMB: launch.memoryMb },
+                MappedDirectories: folderMaps,
+                HvSocket: { Config: hvSocketConfig },
+                // No Networking section: no endpoint.
+            },
+        },
+    };
+    return { uvmId, containerId: containerId(uvmId), uvm, container, disks, notes };
+}

package/dist/host/engines/hcs/engine.d.ts

@@ -0,0 +1,39 @@
+import type { SandboxEngine } from '../engine.js';
+import type { EngineCapabilities, EngineCheck, EnginePlan, LaunchPlan, RunningSandbox } from '../types.js';
+import { type HcsProbes } from './check.js';
+import { type HcsImage } from './documents.js';
+import { HcsHelper } from './helper.js';
+export declare const HCS_CAPABILITIES: EngineCapabilities;
+export declare const HCS_ALPHA_MESSAGE = "The HCS engine is in alpha and starting it is not enabled yet; see docs/design/engines.md";
+export declare const HCS_FLAG = "AGENT_SANDBOX_HCS_EXPERIMENTAL";
+/** Starting is allowed only with the owner's flag, and never inside the self-test. */
+export declare function hcsStartEnabled(env: NodeJS.ProcessEnv, selfTest: boolean): boolean;
+export interface HcsEngineDeps {
+    readonly helper?: HcsHelper;
+    readonly env?: NodeJS.ProcessEnv;
+    /** Inside the self-test, starting is refused whatever the flag says. */
+    readonly selfTest?: () => boolean;
+    readonly hostCpus?: () => number;
+    readonly exists?: (file: string) => boolean;
+}
+export declare class HcsEngine implements SandboxEngine {
+    private readonly image;
+    private readonly probes;
+    private readonly storageRoot;
+    private readonly deps;
+    readonly id = "hcs";
+    /** `image` and `probes` come from the check (see HcsEngine.open); `storageRoot` is where HcsHost.exe is built. */
+    constructor(image: HcsImage | null, probes: HcsProbes, storageRoot: string, deps?: HcsEngineDeps);
+    /** The engine for this PC when its check passes; otherwise a clear stop with the check's reasons and fixes. */
+    static open(storageRoot: string, probes?: HcsProbes, deps?: HcsEngineDeps): Promise<HcsEngine>;
+    capabilities(): EngineCapabilities;
+    check(): Promise<EngineCheck>;
+    plan(launch: LaunchPlan): EnginePlan;
+    private helper;
+    start(plan: EnginePlan): Promise<RunningSandbox>;
+    private tryTerminate;
+    /** Ours: the compute systems the helper lists with our owner name. */
+    private ours;
+    running(): Promise<boolean>;
+    stop(): Promise<void>;
+}

package/dist/host/engines/hcs/engine.js

@@ -0,0 +1,171 @@
+// The HCS engine (alpha): a Hyper-V isolated Windows container for agents, behind the SandboxEngine interface.
+// plan() is pure and tested; start() is DISABLED until the owner's go/no-go test (docs/design/engines.md) has passed
+// on a real PC.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { z } from 'zod';
+import { fail, UserError } from '../../../core/util/index.js';
+import { selfTestRunning } from '../../test-guard.js';
+import { checkHcs, realHcsProbes } from './check.js';
+import { buildDocuments, HCS_OWNER } from './documents.js';
+import { HcsHelper, hcsHostExe } from './helper.js';
+import { findImage } from './images.js';
+export const HCS_CAPABILITIES = {
+    desktop: false,
+    gpu: false,
+    clipboard: false,
+    audio: false,
+    video: false,
+    printers: false,
+    liveFolderAdd: true,
+    attachedDisks: true,
+    multipleInstances: true,
+    hvsocket: true,
+};
+export const HCS_ALPHA_MESSAGE = 'The HCS engine is in alpha and starting it is not enabled yet; see docs/design/engines.md';
+export const HCS_FLAG = 'AGENT_SANDBOX_HCS_EXPERIMENTAL';
+/** Starting is allowed only with the owner's flag, and never inside the self-test. */
+export function hcsStartEnabled(env, selfTest) {
+    return env[HCS_FLAG] === '1' && !selfTest;
+}
+const PlanFileSchema = z.object({
+    version: z.literal(1),
+    uvmId: z.string().regex(/^agent-sandbox-[A-Za-z0-9._-]{1,100}$/),
+    containerId: z.string().regex(/^agent-sandbox-[A-Za-z0-9._-]{1,100}$/),
+    uvmFile: z.string(),
+    containerFile: z.string(),
+    scratchVhdx: z.string(),
+    disks: z.array(z.object({ image: z.string(), maxGb: z.number().int().min(1).max(4096), lun: z.number().int() })),
+    logonCommand: z.string(),
+    notes: z.array(z.string()),
+});
+const SystemListSchema = z.array(z.object({ Id: z.string(), Owner: z.string().optional() }).passthrough());
+export class HcsEngine {
+    image;
+    probes;
+    storageRoot;
+    deps;
+    id = 'hcs';
+    /** `image` and `probes` come from the check (see HcsEngine.open); `storageRoot` is where HcsHost.exe is built. */
+    constructor(image, probes, storageRoot, deps = {}) {
+        this.image = image;
+        this.probes = probes;
+        this.storageRoot = storageRoot;
+        this.deps = deps;
+    }
+    /** The engine for this PC when its check passes; otherwise a clear stop with the check's reasons and fixes. */
+    static async open(storageRoot, probes = realHcsProbes(), deps = {}) {
+        const check = checkHcs(probes);
+        if (!check.available)
+            fail('The HCS engine cannot run on this PC: ' + check.reasons.join(' '), 'Fix: ' + check.fixes.join(' | '));
+        return new HcsEngine(findImage(probes.imageStores()).image, probes, storageRoot, deps);
+    }
+    capabilities() {
+        return HCS_CAPABILITIES;
+    }
+    check() {
+        return Promise.resolve(checkHcs(this.probes));
+    }
+    plan(launch) {
+        if (!this.image)
+            fail('No base image is available for the HCS engine.', 'Run: sandbox engine check hcs');
+        const slug = path.basename(launch.launchPath).replace(/[^A-Za-z0-9._-]/g, '-');
+        const dir = path.join(launch.launchPath, 'hcs');
+        const scratchVhdx = path.join(dir, 'scratch.vhdx');
+        const docs = buildDocuments({
+            launch,
+            image: this.image,
+            id: 'agent-sandbox-' + slug,
+            scratchVhdx,
+            hostCpus: (this.deps.hostCpus ?? (() => os.cpus().length))(),
+        });
+        const planFile = {
+            version: 1,
+            uvmId: docs.uvmId,
+            containerId: docs.containerId,
+            uvmFile: path.join(dir, 'uvm.json'),
+            containerFile: path.join(dir, 'container.json'),
+            scratchVhdx,
+            disks: [...docs.disks],
+            logonCommand: launch.logonCommand,
+            notes: [...docs.notes],
+        };
+        const entry = path.join(dir, 'plan.json');
+        const pretty = (v) => JSON.stringify(v, null, 2) + '\n';
+        return {
+            engine: this.id,
+            entry,
+            files: [
+                { path: planFile.uvmFile, text: pretty(docs.uvm) },
+                { path: planFile.containerFile, text: pretty(docs.container) },
+                { path: entry, text: pretty(planFile) },
+            ],
+        };
+    }
+    helper() {
+        return this.deps.helper ?? new HcsHelper(() => hcsHostExe(this.storageRoot));
+    }
+    async start(plan) {
+        const enabled = hcsStartEnabled(this.deps.env ?? process.env, (this.deps.selfTest ?? selfTestRunning)());
+        if (!enabled)
+            fail(HCS_ALPHA_MESSAGE);
+        const file = PlanFileSchema.parse(JSON.parse(fs.readFileSync(plan.entry, 'utf8')));
+        const exists = this.deps.exists ?? fs.existsSync;
+        const helper = this.helper();
+        const disks = [...file.disks.map((d) => d.image), file.scratchVhdx];
+        for (const d of file.disks)
+            if (!exists(d.image))
+                helper.createVhdx(d.image, d.maxGb);
+        // The writable layer is made by HcsInitializeWritableLayer, which this phase does not have.
+        if (!exists(file.scratchVhdx))
+            fail('The writable layer of this sandbox has not been prepared (not built yet).');
+        const created = [];
+        try {
+            for (const disk of disks)
+                helper.grantVmAccess(file.uvmId, disk);
+            helper.create(file.uvmId, fs.readFileSync(file.uvmFile, 'utf8'));
+            created.push(file.uvmId);
+            helper.start(file.uvmId);
+            helper.create(file.containerId, fs.readFileSync(file.containerFile, 'utf8'));
+            created.push(file.containerId);
+            helper.start(file.containerId);
+        }
+        catch (e) {
+            for (const id of created.reverse())
+                this.tryTerminate(helper, id);
+            throw e;
+        }
+        return { id: file.uvmId, engine: this.id, started: Date.now() };
+    }
+    tryTerminate(helper, id) {
+        try {
+            helper.terminate(id);
+        }
+        catch (e) {
+            if (!(e instanceof UserError))
+                throw e; // a system that is already gone is fine
+        }
+    }
+    /** Ours: the compute systems the helper lists with our owner name. */
+    ours(helper) {
+        const parsed = SystemListSchema.safeParse(JSON.parse(helper.enumerate().json || '[]'));
+        return parsed.success ? parsed.data.filter((s) => s.Owner === HCS_OWNER).map((s) => s.Id) : [];
+    }
+    running() {
+        try {
+            return Promise.resolve(this.ours(this.helper()).length > 0);
+        }
+        catch {
+            return Promise.resolve(false); // no helper or no service: nothing of ours can be running
+        }
+    }
+    stop() {
+        const helper = this.helper();
+        // The container goes before the machine that hosts it.
+        const ids = this.ours(helper).sort((a, b) => Number(b.endsWith('-c')) - Number(a.endsWith('-c')));
+        for (const id of ids)
+            this.tryTerminate(helper, id);
+        return Promise.resolve();
+    }
+}

package/dist/host/engines/hcs/helper.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+export declare const HcsReplySchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    hresult: z.ZodString;
+    message: z.ZodString;
+    json: z.ZodString;
+    values: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strip>;
+export type HcsReply = z.infer<typeof HcsReplySchema>;
+export interface RunResult {
+    readonly status: number | null;
+    readonly error?: string;
+}
+/** Starts the helper: replaceable in tests. */
+export type HelperRunner = (exe: string, args: readonly string[], timeoutMs: number) => RunResult;
+export declare const spawnRunner: HelperRunner;
+/** Compiles the helper's sources to `exe` with the .NET Framework csc (C# 5). False when it cannot be built. */
+export declare function buildHcsHostTo(exe: string): boolean;
+/**
+ * <storage>\bin\hcs\<hash of its sources>\HcsHost.exe, built the first time. Its own folder: HostTools' cleanup of old
+ * builds only touches twelve-digit hash folders directly in bin. Null when it cannot be built.
+ */
+export declare function hcsHostExe(storageRoot: string): string | null;
+export declare class HcsHelper {
+    private readonly exe;
+    private readonly run;
+    private readonly tempRoot;
+    /** `exe`: where HcsHost.exe is (built when asked); `tempRoot`: where the private folders for one call go. */
+    constructor(exe: () => string | null, run?: HelperRunner, tempRoot?: string);
+    /** One helper call: `args` then `--out <response>`. Returns the checked answer, whatever it says. */
+    call(args: readonly string[], request?: unknown): HcsReply;
+    /** The same, but a failed answer stops with the helper's own message. */
+    private must;
+    check(): HcsReply;
+    enumerate(): HcsReply;
+    properties(id: string): HcsReply;
+    /** `document` is the HCS JSON text; it travels as a string inside the request file. */
+    create(id: string, document: string): HcsReply;
+    start(id: string): HcsReply;
+    terminate(id: string): HcsReply;
+    grantVmAccess(vmId: string, file: string): HcsReply;
+    createVhdx(file: string, maxGb: number): HcsReply;
+}