windows-development-sandbox 1.7.0 → 1.9.0

package/dist/cli/commands/launch/launch.js

@@ -3,13 +3,15 @@
 // restart that adds it is offered (restart.ts).
 import path from 'node:path';
 import _ from 'lodash';
-import { generateSandbox } from '../../../host/launch/index.js';
+import { openEngine } from '../../../host/engines/index.js';
+import { containedMappings, containedPaths, providerFor, setNameOf, } from '../../../host/storage/index.js';
+import { generateSandbox, GUEST, vgpuSource, vgpuWarning } from '../../../host/launch/index.js';
 import { findSecretFiles } from '../../../host/profile/index.js';
 import { RepoGuardStore } from '../../../host/guard/index.js';
 import { hostPublicIp, prepareVpn, readVpnLine, vpnNotes } from '../../../host/vpn/index.js';
-import { assertCanLaunch, isSandboxRunning, spawnDetached, startSandbox, confirmSandboxStarted, probeHost, hideSandboxWindow, } from '../../../host/sandbox/index.js';
+import { assertCanLaunch, isSandboxRunning, spawnDetached, probeHost, hideSandboxWindow, realContainedDeps, } from '../../../host/sandbox/index.js';
 import { KnownProjects, ProjectRegistry } from '../../../host/projects/index.js';
-import { LifeRecord, SessionLedger } from '../../../host/life/index.js';
+import { LifeRecord, pageFileRisk, readHostMemory, SessionLedger, takePageFileHint } from '../../../host/life/index.js';
 import { isWithin } from '../../../shared/paths/index.js';
 import { watcherRunning } from '../../../sync/index.js';
 import { protectionsOf } from '../../../core/local-config/index.js';
@@ -118,11 +120,39 @@ class Launcher {
     }
     /** One sandbox for this folder: resolve, prepare, write the launch files, then (unless generate) start it. */
     async launchHere() {
-        const { ctx, generateOnly, extras } = this;
+        const { ctx, generateOnly } = this;
         const run = await this.resolve();
         const { config } = run;
+        // An engine or storage kind that is not available yet stops here, before anything is prepared.
+        const engine = await openEngine(config);
+        const provider = providerFor(config, config.storage.contained === 'off'
+            ? {}
+            : { contained: realContainedDeps(ctx.storageRoot, config.storage.containedMaxGb) });
         if (!generateOnly)
             assertCanLaunch(isSandboxRunning() ? runningOwner() : undefined);
+        // Contained storage: the image is mounted now (before anything reads or writes the data set), and let go of again
+        // when the launch fails before the sandbox starts. The background watcher holds it from then on.
+        const dataMappings = await this.prepareStorage(provider, run);
+        try {
+            return await this.launchPrepared(run, engine, dataMappings);
+        }
+        catch (e) {
+            await provider.release();
+            throw e;
+        }
+    }
+    /** The data set's mappings from a contained-storage provider (mounting it), or undefined for plain folders. */
+    async prepareStorage(provider, run) {
+        if (provider.id === 'folder')
+            return undefined;
+        if (this.generateOnly)
+            return containedMappings(run.dataPath, containedPaths(run.storageRoot, setNameOf(run.dataPath)).mount, GUEST.data);
+        console.log('Mounting the contained storage (Windows asks for permission when it is not mounted yet)...');
+        return [...(await provider.prepare({ dataPath: run.dataPath, guest: GUEST.data })).mappings];
+    }
+    async launchPrepared(run, engine, dataMappings) {
+        const { ctx, generateOnly, extras } = this;
+        const { config } = run;
         if (!generateOnly && !extras.extraProjects)
             await maybeAddRoot(ctx, run);
         const prepared = generateOnly ? null : await prepare(ctx, run);
@@ -136,8 +166,11 @@ class Launcher {
                 sandboxRunning: isSandboxRunning(),
                 base: run.workspaceHost,
             });
+        // This PC's commit (RAM plus paging file) bounds the sandbox's memory as much as free RAM does.
+        const hostMemory = generateOnly ? null : readHostMemory(ctx.storageRoot);
         const generated = generateSandbox({
             packageRoot: ctx.packageRoot,
+            ...(hostMemory ? { commitAvailableMb: hostMemory.commitAvailableMb } : {}),
             run,
             harnessArgs: this.options.passthrough,
             probe: probeHost(config, run.harnessName),
@@ -145,10 +178,18 @@ class Launcher {
             autoSession: extras.autoSession,
             bootWants: bootWants.wants,
             ...(vpn ? { vpn } : {}),
-        });
+            ...(dataMappings ? { dataMappings } : {}),
+        }, engine);
         const notes = [...run.notes, ...bootWants.notes, ...generated.projects.notes, ...generated.mappingNotes];
         for (const note of notes)
             console.log(note);
+        if (generated.memoryNote)
+            console.log(c.yellow(generated.memoryNote));
+        if (generated.bootConfig.sandbox.vGpu)
+            console.log(c.yellow(vgpuWarning(vgpuSource(ctx.loaded.config.sandbox.vGpu))));
+        const risk = hostMemory ? pageFileRisk(hostMemory, generated.memoryMb) : null;
+        if (risk && takePageFileHint(ctx.storageRoot))
+            console.log(c.yellow(risk.text));
         this.warnSecretFiles(run);
         for (const line of vpnNotes(config.vpn))
             console.log(c.yellow(line));
@@ -159,8 +200,7 @@ class Launcher {
         const reopen = extras.extraProjects ? [] : await sessionsToResume(ctx, run);
         this.record(run, generated);
         this.share(generated);
-        startSandbox(generated.wsbPath);
-        await confirmSandboxStarted(generated.wsbPath);
+        await engine.start(generated.enginePlan);
         this.startWatcher();
         if (reopen.length)
             await this.reopenAfterBoot(generated.launchId, reopen);

package/dist/cli/commands/launch/prepare.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { AccountStore } from '../../../host/profile/index.js';
 import { SandboxChannel } from '../../../host/channel/index.js';
-import { describePrune, pruneStorage } from '../../../host/storage/index.js';
+import { describePrune, hostDataFolder, pruneStorage } from '../../../host/storage/index.js';
 import { RepoGuardStore, readDataSize, saveMarkedProjects } from '../../../host/guard/index.js';
 import { ensureConpty, ensureTerminal } from '../../../host/tools/index.js';
 import { planView, viewSkipped, saveActiveViews, WorkspaceView } from '../../../host/workspace-view/index.js';
@@ -16,7 +16,7 @@ import { firstStartNotice, pendingDownloads } from './first-start.js';
 import { LifeRecord, UPDATE_RESTART_WARNING, updateRestartPending } from '../../../host/life/index.js';
 /** Nothing has been installed into this data set yet: the first start downloads every toolchain once. */
 export function firstBoot(dataPath) {
-    return !fs.existsSync(path.join(dataPath, 'tools', 'resolved-versions.json'));
+    return !fs.existsSync(path.join(hostDataFolder(dataPath, 'tools'), 'resolved-versions.json'));
 }
 /** The first-start heads-up (also when this project needs tools not downloaded yet), or null. */
 export function firstBootNotice(dataPath, generated) {
@@ -27,7 +27,7 @@ export function firstBootNotice(dataPath, generated) {
             .map(([name]) => name),
         ...generated.databases.map((d) => d.database),
     ];
-    return firstStartNotice(firstBoot(dataPath), pendingDownloads(wanted, (dir) => fs.existsSync(path.join(dataPath, 'tools', dir))));
+    return firstStartNotice(firstBoot(dataPath), pendingDownloads(wanted, (dir) => fs.existsSync(path.join(hostDataFolder(dataPath, 'tools'), dir))));
 }
 function syncSummary(config, dataPath, workspaceHost) {
     try {

package/dist/cli/commands/launch/running.js

@@ -17,7 +17,8 @@ const SESSION_START_MS = 60 * 60 * 1000;
 export function attachHere(ctx, session) {
     if (ctx.loaded.config.attach.autoHide && !insideSandbox())
         void hideSandboxWindow(ctx.storageRoot, 120).catch(() => false);
-    return attachTerminal(session);
+    // A copy in the agent reaches this PC's clipboard only when sandbox.clipboard already shares it with the sandbox.
+    return attachTerminal(session, { clipboardWrites: ctx.loaded.config.sandbox.clipboard });
 }
 /** The sandbox writes sandbox.json a few seconds into its boot; a second launch right after the first waits for it. */
 export async function runningSandboxStatus(dataPath) {

package/dist/cli/commands/launch/summary.d.ts

@@ -1,8 +1,10 @@
 import type { Generated, ResolvedRun } from '../../../core/types.js';
+import type { EnginePlan } from '../../../host/engines/index.js';
 import type { Prepared } from './prepare.js';
 /** What generateSandbox returned. */
 export type GeneratedSandbox = Generated & {
     readonly personalization: string;
+    readonly enginePlan: EnginePlan;
 };
 /** The launch summary rows, in the order they are printed. */
 export declare function launchSummary(run: ResolvedRun, generated: GeneratedSandbox, prepared: Prepared | null): string[][];

package/dist/cli/commands/maintenance/config-share.d.ts

@@ -0,0 +1,12 @@
+import { type ImportPlan } from '../../menu/settings/index.js';
+import type { Context } from '../context.js';
+/** The file `config export` writes when none is named. */
+export declare const DEFAULT_EXPORT = "sandbox-settings.json";
+/** Writes the settings that differ from the defaults (no secrets, no storage, no paths unless asked) to `file`. */
+export declare function writeExport(ctx: Context, file: string, withPaths: boolean, overwrite: boolean): string[];
+/** Reads a shared file and plans the import. Fails with the reason when it cannot be read. */
+export declare function readImport(ctx: Context, file: string): ImportPlan;
+/** Writes the planned changes to your settings file (comments stay); returns how many settings changed. */
+export declare function applyImport(ctx: Context, plan: ImportPlan): number;
+export declare function exportCommand(ctx: Context, file: string | undefined): number;
+export declare function importCommand(ctx: Context, file: string | undefined): Promise<number>;

package/dist/cli/commands/maintenance/config-share.js

@@ -0,0 +1,80 @@
+// `sandbox config export` and `import`: your settings as a shareable .json, and a shared file read back in.
+import fs from 'node:fs';
+import path from 'node:path';
+import { askRequired } from '../../../core/prompt.js';
+import { fail, safeText, writeJson } from '../../../core/util/index.js';
+import { c } from '../../output/index.js';
+import { ConfigFile } from '../../../app/features/settings/index.js';
+import { diffText, exportSettings, planImport, skippedLine } from '../../menu/settings/index.js';
+/** The file `config export` writes when none is named. */
+export const DEFAULT_EXPORT = 'sandbox-settings.json';
+/** A shared file is a few KB; anything bigger is not one. */
+const MAX_BYTES = 1024 * 1024;
+/** Writes the settings that differ from the defaults (no secrets, no storage, no paths unless asked) to `file`. */
+export function writeExport(ctx, file, withPaths, overwrite) {
+    const target = path.resolve(file);
+    if (!overwrite && fs.existsSync(target))
+        fail(target + ' exists already.', 'Pick another name, or delete it first.');
+    const { data, skipped } = exportSettings(ctx.loaded.config, withPaths);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    writeJson(target, data);
+    return skipped.map(skippedLine);
+}
+/** Reads a shared file and plans the import. Fails with the reason when it cannot be read. */
+export function readImport(ctx, file) {
+    const source = path.resolve(file);
+    if (!fs.existsSync(source))
+        fail('There is no file ' + source + '.', 'Give the path of a file made by sandbox config export.');
+    if (fs.statSync(source).size > MAX_BYTES)
+        fail(source + ' is too big to be a settings file.');
+    const plan = planImport(fs.readFileSync(source, 'utf8'), ctx.loaded.config);
+    if (plan.problems.length)
+        fail(source + ' is not valid settings:\n  ' + plan.problems.map(safeText).join('\n  '), 'Nothing was changed. Fix the file, or export a new one with: sandbox config export');
+    return plan;
+}
+/** Writes the planned changes to your settings file (comments stay); returns how many settings changed. */
+export function applyImport(ctx, plan) {
+    const outcome = ConfigFile.user(ctx.loaded.configPath).setMany(plan.changes);
+    if (typeof outcome === 'object')
+        fail('Could not import: ' + outcome.problems.join('; '), 'Nothing was written. Your settings are unchanged.');
+    return plan.changes.length;
+}
+export function exportCommand(ctx, file) {
+    const target = file ?? DEFAULT_EXPORT;
+    const skipped = writeExport(ctx, target, ctx.options.withPaths, false);
+    console.log('Wrote ' + path.resolve(target) + ' (only what differs from the defaults).');
+    if (skipped.length) {
+        console.log('Left out:');
+        for (const line of skipped)
+            console.log('  ' + line);
+    }
+    if (!ctx.options.withPaths && skipped.some((s) => s.includes('folder or file')))
+        console.log("Keep this PC's folders and files in the file with --with-paths.");
+    return 0;
+}
+export async function importCommand(ctx, file) {
+    if (!file)
+        fail('Which file?', 'Usage: sandbox config import <file>');
+    const plan = readImport(ctx, file);
+    if (plan.skipped.length) {
+        console.log('Not imported (never taken from a file):');
+        for (const s of plan.skipped)
+            console.log('  ' + safeText(skippedLine(s)));
+    }
+    if (!plan.changes.length) {
+        console.log('Nothing to change: your settings already match the file.');
+        return 0;
+    }
+    console.log('This would change ' + plan.changes.length + ' setting' + (plan.changes.length === 1 ? '' : 's') + ':');
+    for (const line of diffText(plan.lines))
+        console.log('  ' + safeText(line));
+    const yes = ctx.options.yes ||
+        (await askRequired('Change your settings like this?', 'Add --yes to change them without asking.'));
+    if (!yes) {
+        console.log('Nothing was changed.');
+        return 0;
+    }
+    const n = applyImport(ctx, plan);
+    console.log(c.green('Imported ' + n + ' setting' + (n === 1 ? '' : 's') + '.') + ' New sandboxes use them.');
+    return 0;
+}

package/dist/cli/commands/maintenance/config.js

@@ -2,7 +2,6 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import _ from 'lodash';
 import { DEFAULTS, userConfigPath, userDir } from '../../../core/config/index.js';
 import { redactSecrets } from '../../../core/schema/index.js';
 import { allowedAnswer, allowStorePath, applyOverrides, describeOverrides, isTrusted, LOCAL_CONFIG_NAME, loosenedRequests, normalizeOverrides, OUTSIDE_FOLDER, outsideKey, outsideMappings, readLocalConfig, trustStorePath, } from '../../../core/local-config/index.js';
@@ -11,9 +10,8 @@ import { askChoice } from '../../../core/prompt.js';
 import { dirExists, fail, safeText, writeJson } from '../../../core/util/index.js';
 import { system32 } from '../../../shared/system.js';
 import { refuseInSelfTest } from '../../../host/test-guard.js';
-import { closest } from '../../validate.js';
 import { c, nextStep, table } from '../../output/index.js';
-import { ConfigFile } from '../../menu/settings/index.js';
+import { exportCommand, importCommand } from './config-share.js';
 /** The settings file exists already: open it, start over, or leave it (no terminal: say how). */
 async function existingFile(file) {
     return askChoice(file + ' exists already.', [
@@ -43,79 +41,6 @@ async function initConfig() {
     nextStep("sandbox config schema   (editor help in every project's .sandbox-config.json)");
     return 0;
 }
-/** The setting a key names, as the schema knows it; an unknown key says what is close. */
-function settingNode(key) {
-    const root = ConfigFile.user(null).schema;
-    const keyPath = key.split('.');
-    let node = root;
-    for (const part of keyPath)
-        node = node?.child(part);
-    if (node)
-        return { path: keyPath, node };
-    const known = root.leaves().map((l) => l.key.join('.'));
-    const hint = closest(key, known);
-    return fail('There is no setting "' + key + '".' + (hint ? ' Did you mean ' + hint + '?' : ''), 'Settings are named like sandbox.memoryMb. See them all with: sandbox config show');
-}
-/** What was typed for a setting as the value it stands for: true/false/on/off, a number, JSON, or plain text. */
-function settingValue(node, text) {
-    const word = text.trim().toLowerCase();
-    if (node.type === 'string')
-        return text;
-    if (node.type === 'boolean' || node.options.some((o) => o.type === 'boolean')) {
-        if (['true', 'on', 'yes'].includes(word))
-            return true;
-        if (['false', 'off', 'no'].includes(word))
-            return false;
-    }
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        // Not JSON: a bare word such as auto or a path is the text itself.
-        return node.type === 'array' ? text.split(',').map((t) => t.trim()) : text;
-    }
-}
-/** What a setting accepts, in words: its fixed values, a number and its range, true or false. */
-function allowedText(node) {
-    const values = node.choiceValues.map((v) => String(v));
-    const open = node.openOption ?? (node.type === 'number' ? node : undefined);
-    const range = (n) => (n.rangeText() ? ' (' + n.rangeText() + ')' : '');
-    const more = open ? (open.type === 'number' ? 'a number' + range(open) : 'text') : '';
-    if (node.type === 'boolean')
-        return 'Use true or false.';
-    const parts = [...values, ...(more ? [more] : [])];
-    return parts.length ? 'Allowed: ' + parts.join(', or ') + '.' : 'Check the value.';
-}
-function setSettingCommand(ctx, key, text) {
-    if (!key || text === undefined)
-        fail('Which setting and value?', 'Usage: sandbox config set <setting> <value>');
-    const { path: keyPath, node } = settingNode(key);
-    if (node.isSection)
-        fail('"' + key + '" is a group of settings.', 'Set one of them, e.g. ' + node.leaves(keyPath)[0]?.key.join('.'));
-    const value = settingValue(node, text);
-    const problem = node.check(value);
-    if (problem !== true) {
-        fail('"' + text + '" does not work for ' + key + ': ' + problem, allowedText(node));
-    }
-    const outcome = ConfigFile.user(ctx.loaded.configPath).set(keyPath, value);
-    if (typeof outcome === 'object')
-        fail('Could not change ' + key + ': ' + outcome.problems.join('; '), 'Nothing was written.');
-    console.log(key +
-        ' is ' +
-        JSON.stringify(_.get(redactSecrets(_.set({}, keyPath, value)), keyPath)) +
-        (outcome === 'unchanged' ? ' (it was already)' : '') +
-        '.');
-    return 0;
-}
-function getSettingCommand(ctx, key) {
-    if (!key)
-        fail('Which setting?', 'Usage: sandbox config get <setting>   (all of them: sandbox config show)');
-    const { path: keyPath } = settingNode(key);
-    // Secret values (an agent's API keys) are never printed.
-    const value = _.get(redactSecrets(ctx.loaded.config), keyPath);
-    console.log(typeof value === 'string' ? value : JSON.stringify(value, null, 2));
-    return 0;
-}
 /**
  * VS Code setting that maps every .sandbox-config.json (and the user config) to the local schema files, so project
  * files need no "$schema" line and nothing is fetched from the internet (remote schemas need trusting).
@@ -208,7 +133,8 @@ function previewFolders(ctx, dir, filePath, overrides) {
     }
 }
 export function config(ctx) {
-    const [action = 'summary', key, value] = ctx.options.positionals;
+    // get, set, reset and list are the settings feature's operations (cli/operations runs them before this).
+    const [action = 'summary', key] = ctx.options.positionals;
     switch (action) {
         case 'summary':
             table([
@@ -233,15 +159,15 @@ export function config(ctx) {
         case 'show':
             console.log(JSON.stringify(redactSecrets(ctx.loaded.config), null, 2));
             return 0;
-        case 'get':
-            return getSettingCommand(ctx, key);
-        case 'set':
-            return setSettingCommand(ctx, key, value);
+        case 'export':
+            return exportCommand(ctx, key);
+        case 'import':
+            return importCommand(ctx, key);
         case 'schema':
             return printSchemaSettings();
         case 'check':
             return checkLocalConfig(ctx);
         default:
-            fail('Unknown config action "' + action + '".', 'Use one of: sandbox config show | get | set | path | init | schema | check');
+            fail('Unknown config action "' + action + '".', 'Use one of: sandbox config show | list | get | set | reset | path | init | schema | check | export | import');
     }
 }

package/dist/cli/commands/maintenance/logs.js

@@ -1,6 +1,20 @@
 import { sleep } from '../../../core/util/index.js';
+import { newestCrashReport } from '../../../host/life/index.js';
 import { LogsService } from '../../services/index.js';
+/** The newest crash report (written by the background sync when the sandbox or this PC went down). */
+function printCrashReport(ctx) {
+    const report = newestCrashReport(ctx.storageRoot);
+    if (!report) {
+        console.log('No crash report yet: no sandbox has ended in a crash since this was installed.');
+        return 0;
+    }
+    console.log('== ' + report.file + ' ==');
+    console.log(report.text);
+    return 0;
+}
 export async function logs(ctx) {
+    if (ctx.options.crash)
+        return printCrashReport(ctx);
     const service = new LogsService(ctx);
     const file = service.newest();
     console.log('== ' + file + ' ==');

package/dist/cli/commands/registry.js

@@ -2,10 +2,11 @@ import { launch } from './launch/index.js';
 import { setup } from './setup/index.js';
 import { data } from './data/index.js';
 import { storage } from './storage/index.js';
-import { attach, db, exec, hide, restart, sessions, show, status, stop } from './sessions/index.js';
+import { attach, db, exec } from './sessions/index.js';
 import { account } from './accounts.js';
 import { projects } from './projects/index.js';
 import { audit, claudeHost, clean, config, doctor, hostCommand, logs, migrate, sync, watcher, } from './maintenance/index.js';
+import { engine } from './engine.js';
 import { resume } from './resume.js';
 import { agentCommandsCommand } from './agent-commands.js';
 import { vpn } from './vpn.js';
@@ -14,16 +15,10 @@ export const HANDLERS = {
     launch: (ctx) => launch(ctx),
     generate: (ctx) => launch(ctx, true),
     attach: attach,
-    sessions: sessions,
-    status: status,
     exec: exec,
     'agent-commands': agentCommandsCommand,
     db: db,
-    restart: restart,
     resume: resume,
-    stop: stop,
-    show: show,
-    hide: hide,
     account: account,
     projects: projects,
     sync: sync,
@@ -36,6 +31,7 @@ export const HANDLERS = {
     setup: setup,
     data: data,
     storage: storage,
+    engine: engine,
     'host-claude': claudeHost,
     host: hostCommand,
     _watch: watcher,

package/dist/cli/commands/repair/checks/contained.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from '../types.js';
+export declare const CONTAINED_CHECKS: Check[];

package/dist/cli/commands/repair/checks/contained.js

@@ -0,0 +1,139 @@
+// Contained storage (beta): the image is there, what the record says is mounted matches what is really mounted, and
+// the folders around the image are private. A mount left behind (a sandbox that ended without letting go, a crash) is
+// dismounted here, which needs the Windows permission prompt.
+import fs from 'node:fs';
+import { isWin } from '../../../../core/util/index.js';
+import { parseIcacls, privacyProblems, SHARING_GROUP } from '../../../../host/health/index.js';
+import { realContainedDeps } from '../../../../host/sandbox/index.js';
+import { protectPrivateFolder } from '../../../../host/sharing/index.js';
+import { containedAvailability, ContainedStorage, containedPaths } from '../../../../host/storage/index.js';
+import { ok } from './common.js';
+function storageOf(env) {
+    const { config } = env.ctx.loaded;
+    return new ContainedStorage(realContainedDeps(env.storageRoot, config.storage.containedMaxGb), config.storage.dataName);
+}
+/** Only when contained storage is on, or an image or a record of one exists. */
+const inUse = (env) => {
+    if (!isWin)
+        return false;
+    const { config } = env.ctx.loaded;
+    const paths = containedPaths(env.storageRoot, config.storage.dataName);
+    return config.storage.contained === 'vhdx' || fs.existsSync(paths.image) || fs.existsSync(paths.stateFile);
+};
+export const CONTAINED_CHECKS = [
+    {
+        id: 'data-contained',
+        group: 'Data folder',
+        name: 'Contained storage',
+        checking: 'the contained storage image (beta)',
+        applies: inUse,
+        timeoutMs: 60_000,
+        run: async (env) => {
+            const wanted = env.ctx.loaded.config.storage.contained === 'vhdx';
+            const available = containedAvailability();
+            if (!available.available)
+                return wanted
+                    ? {
+                        status: 'needs-you',
+                        detail: 'storage.contained is "vhdx", but ' + available.reasons.join(' '),
+                        means: 'A launch cannot mount the image on this PC.',
+                        fix: available.fixes.join(' '),
+                    }
+                    : {
+                        status: 'skipped',
+                        detail: 'an image exists, but this PC cannot look at it: ' + available.reasons.join(' '),
+                    };
+            const storage = storageOf(env);
+            const diagnosis = await storage.diagnose();
+            switch (diagnosis.kind) {
+                case 'image-missing':
+                    return wanted
+                        ? {
+                            status: 'needs-you',
+                            detail: 'the image is missing: ' + storage.paths.image,
+                            means: 'A launch stops until it is there (the tools, state and logs in it are gone with it).',
+                            fix: 'Restore the file, or run: sandbox storage contained off (and then on again for a new, empty image).',
+                        }
+                        : ok('no image (contained storage is off)');
+                case 'in-use':
+                    return ok('mounted, in use by a running sandbox');
+                case 'stale-mount':
+                    return {
+                        status: 'needs-you',
+                        detail: 'the image is still mounted at ' + storage.paths.mount + ', and nothing uses it',
+                        means: 'It stays attached to this PC until it is dismounted; a launch would reuse it.',
+                        plan: 'dismount the image (Windows asks for permission)',
+                        data: 'dismount',
+                    };
+                case 'stale-state':
+                    return {
+                        status: 'warn',
+                        detail: 'the record says the image is mounted, but it is not',
+                        means: 'Nothing is wrong with the image; the record is out of date.',
+                        plan: 'correct the record',
+                        data: 'record',
+                    };
+                default:
+                    return ok('not mounted' + (wanted ? '' : ' (contained storage is off; the image is kept)'));
+            }
+        },
+        fix: async (env, finding) => {
+            const storage = storageOf(env);
+            if (finding.data === 'record') {
+                storage.clearRecord();
+                return { done: 'corrected the record' };
+            }
+            const result = await storage.dismountIfIdle();
+            if (!result.dismounted)
+                throw new Error('Could not dismount the image: ' + (result.note ?? 'unknown reason'));
+            return { done: 'dismounted the image' };
+        },
+        needsIdle: 'fix',
+    },
+    {
+        id: 'data-contained-privacy',
+        group: 'Data folder',
+        name: 'Contained storage folders',
+        checking: 'who can open the contained storage folders',
+        applies: inUse,
+        run: (env) => {
+            const { config } = env.ctx.loaded;
+            const paths = containedPaths(env.storageRoot, config.storage.dataName);
+            // While mounted, the mount folder shows the image's own root, and nothing is changed under a mount point.
+            if (env.running)
+                return ok('a sandbox is running; not looked at now');
+            const loose = [];
+            for (const dir of [paths.imagesDir, paths.mountsDir, paths.mount]) {
+                if (!fs.existsSync(dir))
+                    continue;
+                const text = env.system.icacls(dir);
+                if (text === null)
+                    return { status: 'skipped', detail: 'could not read the permissions of ' + dir };
+                const problems = privacyProblems(parseIcacls(text, dir), SHARING_GROUP);
+                if (problems.length > 0)
+                    loose.push(dir + ' (' + problems.join(', ') + ')');
+            }
+            if (loose.length === 0)
+                return ok('private (you, SYSTEM and administrators)');
+            return {
+                status: 'warn',
+                detail: 'open to more than you: ' + loose.join('; '),
+                means: 'Other users of this PC could open the image or the folders it is mounted in.',
+                plan: 'make them private',
+                data: 'private',
+            };
+        },
+        fix: (env) => {
+            const { config } = env.ctx.loaded;
+            const paths = containedPaths(env.storageRoot, config.storage.dataName);
+            // Never with an image mounted below: a folder with files is walked, and a mount point must not be.
+            if (env.running)
+                throw new Error('a sandbox is running; run repair again once it is closed');
+            for (const dir of [paths.imagesDir, paths.mountsDir, paths.mount])
+                if (fs.existsSync(dir))
+                    protectPrivateFolder(dir);
+            return { done: 'made the folders private' };
+        },
+        needsIdle: 'fix',
+    },
+];

package/dist/cli/commands/repair/checks/hcs.d.ts

@@ -0,0 +1,7 @@
+import { type HcsProbes } from '../../../../host/engines/index.js';
+import type { Check } from '../types.js';
+/** Replaceable by tests: the probes the row looks through. */
+export declare const HCS_PROBES: {
+    current: HcsProbes | null;
+};
+export declare const HCS_CHECKS: Check[];

package/dist/cli/commands/repair/checks/hcs.js

@@ -0,0 +1,28 @@
+// The HCS engine (alpha), only when sandbox.engine is "hcs": can this PC run it. Looks only; the fixes are commands for
+// you to run (they change Windows), never run by repair.
+import { checkHcs, realHcsProbes } from '../../../../host/engines/index.js';
+import { ok } from './common.js';
+const hcsInUse = (env) => env.ctx.loaded.config.sandbox.engine === 'hcs';
+/** Replaceable by tests: the probes the row looks through. */
+export const HCS_PROBES = { current: null };
+export const HCS_CHECKS = [
+    {
+        id: 'hcs-engine',
+        group: 'Sandbox',
+        name: 'HCS engine (alpha)',
+        checking: 'the HCS engine',
+        applies: hcsInUse,
+        timeoutMs: 60000,
+        run: () => {
+            const check = checkHcs(HCS_PROBES.current ?? realHcsProbes());
+            if (check.available)
+                return ok('this PC can run it (starting it is not enabled yet in this alpha)');
+            return {
+                status: 'needs-you',
+                detail: check.reasons.length + ' thing(s) missing: ' + check.reasons[0],
+                means: check.reasons.join(' '),
+                fix: check.fixes.join('  |  '),
+            };
+        },
+    },
+];

package/dist/cli/commands/repair/checks/index.js

@@ -1,5 +1,7 @@
 import { AGENT_CHECKS } from './agents.js';
+import { CONTAINED_CHECKS } from './contained.js';
 import { DATA_CHECKS } from './data.js';
+import { HCS_CHECKS } from './hcs.js';
 import { INSTALL_CHECKS } from './install.js';
 import { MACHINE_CHECKS } from './machine.js';
 import { NETWORK_CHECKS } from './network.js';
@@ -12,8 +14,10 @@ export const ALL_CHECKS = [
     ...INSTALL_CHECKS,
     ...MACHINE_CHECKS,
     ...DATA_CHECKS,
+    ...CONTAINED_CHECKS,
     ...SETTINGS_CHECKS,
     ...SANDBOX_CHECKS,
+    ...HCS_CHECKS,
     ...AGENT_CHECKS,
     ...NETWORK_CHECKS,
     ...VPN_CHECKS,