windows-development-sandbox 1.7.0 → 1.9.0

package/dist/host/native.js

@@ -27,8 +27,9 @@ export function nativeScript(name, args = []) {
     ];
 }
 /**
- * <storage>\bin\HostTools-<hash of its sources>.exe, compiled with the .NET Framework csc the first time; null when it
- * cannot be built (no csc, a compile error): the caller then runs the PowerShell fallback.
+ * <storage>\bin\<hash of its sources>\HostTools.exe, compiled with the .NET Framework csc the first time; null when it
+ * cannot be built (no csc, a compile error): the caller then runs the PowerShell fallback. A plain name and full file
+ * properties (AssemblyInfo.cs), so antivirus software does not take a nameless, random-looking exe for malware.
  */
 export function hostToolsExe(storageRoot) {
     refuseInSelfTest('build HostTools.exe');
@@ -47,15 +48,33 @@ export function hostToolsExe(storageRoot) {
     const hash = crypto.createHash('sha256');
     for (const file of sources)
         hash.update(fs.readFileSync(file));
-    const exe = path.join(storageRoot, 'bin', 'HostTools-' + hash.digest('hex').slice(0, 12) + '.exe');
+    const bin = path.join(storageRoot, 'bin');
+    const exe = path.join(bin, hash.digest('hex').slice(0, 12), 'HostTools.exe');
     if (fs.existsSync(exe))
         return exe;
     if (!fs.existsSync(SYSTEM.csc()))
         return null;
     fs.mkdirSync(path.dirname(exe), { recursive: true });
+    removeOldHostTools(bin, path.dirname(exe));
     const result = spawnSync(SYSTEM.csc(), ['/nologo', '/optimize', '/target:exe', '/out:' + exe, ...sources], {
         windowsHide: true,
         timeout: 120000,
     });
     return result.status === 0 && fs.existsSync(exe) ? exe : null;
 }
+/** Earlier builds: HostTools-<hash>.exe files and other <hash> folders in bin (best effort: one in use stays). */
+function removeOldHostTools(bin, keep) {
+    for (const entry of fs.readdirSync(bin, { withFileTypes: true })) {
+        const full = path.join(bin, entry.name);
+        const old = (entry.isFile() && /^HostTools-[0-9a-f]{12}\.exe$/i.test(entry.name)) ||
+            (entry.isDirectory() && /^[0-9a-f]{12}$/i.test(entry.name) && full !== keep);
+        if (!old)
+            continue;
+        try {
+            fs.rmSync(full, { recursive: true, force: true });
+        }
+        catch {
+            // Still running (keep-awake of another sandbox): removed by a later build.
+        }
+    }
+}

package/dist/host/profile/claude-login.js

@@ -3,6 +3,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { assertTestWritable } from '../test-guard.js';
+import { hostDataFolder, hostDataRoot } from '../storage/index.js';
 import { assertNoLinks, fail, fileExists, isLink, removeLink, tryReadJson, writeJson } from '../../core/util/index.js';
 const MAX_LOGIN_BYTES = 1024 * 1024;
 /** .claude.json holds per-project state and can be large; still capped so a hostile file cannot exhaust memory. */
@@ -10,7 +11,7 @@ export const MAX_STATE_BYTES = 256 * 1024 * 1024;
 /** Caches tied to an account (Claude deletes these on /logout). */
 const ACCOUNT_CACHES = ['remote-settings.json', 'policy-limits.json', 'policy-limits.json.stamp.json'];
 export function sandboxClaudeDir(dataPath) {
-    return path.join(dataPath, 'state', 'claude');
+    return path.join(hostDataFolder(dataPath, 'state'), 'claude');
 }
 export function emailOf(oauthAccount) {
     const email = oauthAccount?.emailAddress;
@@ -32,7 +33,7 @@ export function readLogin(claudeDir, globalStateFile) {
 }
 /** The sandbox's Claude login files (refuses when the data folder holds a link on the way). */
 export function sandboxLogin(dataPath) {
-    assertNoLinks(dataPath, sandboxClaudeDir(dataPath));
+    assertNoLinks(hostDataRoot(dataPath), sandboxClaudeDir(dataPath));
     return {
         claudeDir: sandboxClaudeDir(dataPath),
         globalStateFile: path.join(sandboxClaudeDir(dataPath), '.claude.json'),

package/dist/host/sandbox/contained-deps.d.ts

@@ -0,0 +1,2 @@
+import { type ContainedDeps } from '../storage/index.js';
+export declare function realContainedDeps(storageRoot: string, maxGb: number): ContainedDeps;

package/dist/host/sandbox/contained-deps.js

@@ -0,0 +1,17 @@
+// The real wiring of contained storage on this PC: the permission-prompt scripts, protectPrivateFolder for new
+// folders, your SID, and whether a sandbox runs. Lives here (not in host/storage) so storage never imports the
+// sandbox or sharing folders, which import storage. The self-test never reaches a disk through it: the disk port
+// refuses there.
+import { ScriptDiskPort } from '../storage/index.js';
+import { currentUserSid, protectPrivateFolder } from '../sharing/index.js';
+import { isSandboxRunning } from './platform.js';
+export function realContainedDeps(storageRoot, maxGb) {
+    return {
+        storageRoot,
+        maxGb,
+        protect: (dir) => protectPrivateFolder(dir),
+        userSid: currentUserSid,
+        port: new ScriptDiskPort(),
+        sandboxRunning: isSandboxRunning,
+    };
+}

package/dist/host/sandbox/index.d.ts

@@ -1,6 +1,8 @@
 export * from './platform.js';
 export * from './probe.js';
+export * from './tasklist.js';
 export * from './host-claude.js';
 export * from './doctor.js';
 export * from './window.js';
 export * from './wsb-cli.js';
+export * from './contained-deps.js';

package/dist/host/sandbox/index.js

@@ -1,6 +1,8 @@
 export * from './platform.js';
 export * from './probe.js';
+export * from './tasklist.js';
 export * from './host-claude.js';
 export * from './doctor.js';
 export * from './window.js';
 export * from './wsb-cli.js';
+export * from './contained-deps.js';

package/dist/host/sandbox/platform.d.ts

@@ -5,6 +5,8 @@ import type { SandboxOwner } from '../sharing/owner.js';
  */
 export declare function insideSandbox(): boolean;
 export declare const GUEST_DATA_DIR = "C:\\AgentData";
+/** Whether a Windows Sandbox program is in this process list (tasklist /NH /FO CSV output). */
+export declare function sandboxInTasklist(tasklist: string): boolean;
 export declare function isSandboxRunning(): boolean;
 export declare function sandboxFeatureInstalled(): boolean;
 /** `owner`: whose sandbox runs, when the caller knows (host/sharing); it makes the message say who started it. */

package/dist/host/sandbox/platform.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { SYSTEM } from '../../shared/system.js';
+import { readTasklist } from './tasklist.js';
 import { refuseInSelfTest } from '../test-guard.js';
 import { fail, fileExists, isWin, sleep } from '../../core/util/index.js';
 import { launchBlocked } from '../sharing/rules.js';
@@ -20,18 +21,17 @@ export function insideSandbox() {
         fs.existsSync('C:\\AgentData\\run'));
 }
 export const GUEST_DATA_DIR = 'C:\\AgentData';
+/** Whether a Windows Sandbox program is in this process list (tasklist /NH /FO CSV output). */
+export function sandboxInTasklist(tasklist) {
+    const out = tasklist.toLowerCase();
+    return SANDBOX_PROCESSES.some((image) => out.includes('"' + image.toLowerCase() + '"'));
+}
 export function isSandboxRunning() {
     if (!isWin)
         return false;
     if (insideSandbox())
         return true;
-    const result = spawnSync(SYSTEM.tasklist(), ['/NH', '/FO', 'CSV'], {
-        encoding: 'utf8',
-        windowsHide: true,
-        timeout: HELPER_TIMEOUT_MS,
-    });
-    const out = (result.stdout ?? '').toLowerCase();
-    return SANDBOX_PROCESSES.some((image) => out.includes('"' + image.toLowerCase() + '"'));
+    return sandboxInTasklist(readTasklist());
 }
 export function sandboxFeatureInstalled() {
     return isWin && fileExists(path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32', 'WindowsSandbox.exe'));

package/dist/host/sandbox/tasklist.d.ts

@@ -0,0 +1,13 @@
+/** Runs tasklist: the real one, or what a test put in its place. */
+export interface TasklistRunners {
+    sync(): string;
+    async(): Promise<string>;
+}
+/** Replaces how tasklist runs (tests count the calls); no argument puts the real one back. */
+export declare function useTasklistRunners(replacement?: TasklistRunners): void;
+/** While set, a synchronous read returns this copy (undefined: none yet, run tasklist). Null removes it. */
+export declare function useTasklistCache(read: (() => string | undefined) | null): void;
+/** The process list now: the cached copy when the menu keeps one, else a run of tasklist the caller waits for. */
+export declare function readTasklist(): string;
+/** The process list from a run of tasklist that does not block the program (the menu's background refresh). */
+export declare function readTasklistAsync(): Promise<string>;

package/dist/host/sandbox/tasklist.js

@@ -0,0 +1,47 @@
+// The process list (`tasklist /NH /FO CSV`) that "is the sandbox running?" and "whose is it?" come from. Commands
+// ask it synchronously. The menu cannot wait for a child process on every key, so it keeps a copy fresh in the
+// background (readTasklistAsync) and installs it with useTasklistCache: until then, and after it is removed, every
+// question runs tasklist itself.
+import { spawn, spawnSync } from 'node:child_process';
+import { SYSTEM } from '../../shared/system.js';
+/** The longest tasklist may take before it counts as stuck. */
+const TASKLIST_TIMEOUT_MS = 15000;
+const ARGS = ['/NH', '/FO', 'CSV'];
+const REAL_RUNNERS = {
+    sync: () => spawnSync(SYSTEM.tasklist(), ARGS, { encoding: 'utf8', windowsHide: true, timeout: TASKLIST_TIMEOUT_MS }).stdout ??
+        '',
+    async: () => new Promise((resolve) => {
+        let out = '';
+        const child = spawn(SYSTEM.tasklist(), ARGS, { windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
+        const timer = setTimeout(() => child.kill(), TASKLIST_TIMEOUT_MS);
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => (out += chunk));
+        // A tasklist that cannot start or is killed counts as an empty list, like the synchronous one.
+        child.on('error', () => {
+            clearTimeout(timer);
+            resolve('');
+        });
+        child.on('close', () => {
+            clearTimeout(timer);
+            resolve(out);
+        });
+    }),
+};
+let runners = REAL_RUNNERS;
+let cache = null;
+/** Replaces how tasklist runs (tests count the calls); no argument puts the real one back. */
+export function useTasklistRunners(replacement = REAL_RUNNERS) {
+    runners = replacement;
+}
+/** While set, a synchronous read returns this copy (undefined: none yet, run tasklist). Null removes it. */
+export function useTasklistCache(read) {
+    cache = read;
+}
+/** The process list now: the cached copy when the menu keeps one, else a run of tasklist the caller waits for. */
+export function readTasklist() {
+    return cache?.() ?? runners.sync();
+}
+/** The process list from a run of tasklist that does not block the program (the menu's background refresh). */
+export function readTasklistAsync() {
+    return runners.async();
+}

package/dist/host/secrets/launch-secrets.js

@@ -11,7 +11,8 @@ export function writeSecrets(dataPath, id, secrets) {
         !Object.keys(secrets.harnessSpecEnvironment ?? {}).length &&
         !Object.keys(secrets.projectHarnessEnvironment ?? {}).length &&
         !secrets.claudeCredentials &&
-        !secrets.vpn;
+        !secrets.vpn &&
+        !secrets.wireguardConfig;
     if (empty)
         return null;
     const run = new RunDir(dataPath);

package/dist/host/sharing/current.js

@@ -3,18 +3,14 @@ import os from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { SYSTEM } from '../../shared/system.js';
 import { insideSandbox } from '../sandbox/platform.js';
+import { readTasklist } from '../sandbox/tasklist.js';
 import { activeDir } from './machine-paths.js';
 import { ActiveRecords } from './active-record.js';
 import { parseTasklist, whoOwnsSandbox } from './owner.js';
 const HELPER_TIMEOUT_MS = 15000;
 /** The rows of `tasklist /NH /FO CSV`: every process of every session (standard users may see these). */
 export function listProcesses() {
-    const run = spawnSync(SYSTEM.tasklist(), ['/NH', '/FO', 'CSV'], {
-        encoding: 'utf8',
-        windowsHide: true,
-        timeout: HELPER_TIMEOUT_MS,
-    });
-    return parseTasklist(run.stdout ?? '');
+    return parseTasklist(readTasklist());
 }
 /** The Windows session this process runs in (0 = services, 1 = the first signed-in user ...), or null when unknown. */
 export function sessionOf(rows, pid = process.pid) {

package/dist/host/storage/contained/check.d.ts

@@ -0,0 +1,9 @@
+import type { ProviderCheck } from '../providers/types.js';
+export interface ContainedFacts {
+    readonly windows: boolean;
+    readonly insideSandbox: boolean;
+    readonly diskpartPresent: boolean;
+    readonly powershellPresent: boolean;
+}
+export declare function containedFacts(): ContainedFacts;
+export declare function containedAvailability(facts?: ContainedFacts): ProviderCheck;

package/dist/host/storage/contained/check.js

@@ -0,0 +1,37 @@
+// Can contained storage run on this PC? Windows, diskpart present, and not inside a Windows Sandbox (a sandbox has no
+// Virtual Disk Service, and a nested one would only mount inside itself).
+import fs from 'node:fs';
+import { isWin } from '../../../core/util/index.js';
+import { SYSTEM, system32 } from '../../../shared/system.js';
+import { insideSandbox } from '../../sandbox/platform.js';
+export function containedFacts() {
+    return {
+        windows: isWin,
+        insideSandbox: insideSandbox(),
+        diskpartPresent: isWin && fs.existsSync(system32('diskpart.exe')),
+        powershellPresent: isWin && fs.existsSync(SYSTEM.powershell()),
+    };
+}
+export function containedAvailability(facts = containedFacts()) {
+    const reasons = [];
+    const fixes = [];
+    if (!facts.windows) {
+        reasons.push('Contained storage needs Windows (it uses disk images).');
+        fixes.push('Set storage.contained to "off".');
+    }
+    else {
+        if (facts.insideSandbox) {
+            reasons.push('This is inside a Windows Sandbox: disk images cannot be mounted here.');
+            fixes.push('Run the command on your PC, not in a sandbox.');
+        }
+        if (!facts.diskpartPresent) {
+            reasons.push('diskpart.exe was not found in Windows\\System32.');
+            fixes.push('Repair Windows (sfc /scannow) or set storage.contained to "off".');
+        }
+        if (!facts.powershellPresent) {
+            reasons.push('Windows PowerShell 5.1 was not found.');
+            fixes.push('Repair Windows or set storage.contained to "off".');
+        }
+    }
+    return { available: reasons.length === 0, reasons, fixes };
+}

package/dist/host/storage/contained/contained-storage.d.ts

@@ -0,0 +1,66 @@
+import { type ContainedPaths } from './layout.js';
+import type { DiskPort } from './disk-port.js';
+import { type ContainedDiagnosis, type MountReality } from './state.js';
+export interface ContainedDeps {
+    readonly storageRoot: string;
+    readonly maxGb: number;
+    /** Makes a NEW, empty folder private (protectPrivateFolder). Never called on a folder that holds files. */
+    readonly protect: (dir: string) => void;
+    readonly userSid: () => string;
+    readonly port: DiskPort;
+    readonly sandboxRunning: () => boolean;
+    readonly alive?: (pid: number) => boolean;
+    /** The volume of a folder (stat.dev): a mounted image is another volume than the folder it is mounted in. */
+    readonly deviceOf?: (dir: string) => number;
+}
+export interface HolderId {
+    readonly id: string;
+    readonly pid: number;
+}
+export interface ReleaseResult {
+    readonly dismounted: boolean;
+    /** Why it stayed mounted (or could not be dismounted), when it did. */
+    readonly note?: string;
+}
+export declare class ContainedStorage {
+    private readonly deps;
+    readonly set: string;
+    readonly paths: ContainedPaths;
+    private readonly stateFile;
+    private readonly alive;
+    constructor(deps: ContainedDeps, set: string);
+    imageExists(): boolean;
+    /** Holders of this set that still run. */
+    liveHolders(): number;
+    recordedMounted(): boolean;
+    reality(): Promise<MountReality>;
+    diagnose(): Promise<ContainedDiagnosis>;
+    /**
+     * Makes sure the image is mounted at its folder (creating it when `create` is set and no image exists yet), records
+     * the holder and returns the mount folder, ready with the folders of the data set inside it.
+     */
+    acquire(holder: HolderId, o?: {
+        readonly create?: boolean;
+    }): Promise<string>;
+    private mountForHolder;
+    private withHolder;
+    /** The record knows this set as mounted (the watcher only holds a mount that exists). */
+    isRecorded(): boolean;
+    /** Adds a holder to a mount that is recorded as mounted (the background watcher); false when nothing is mounted. */
+    hold(holder: HolderId): boolean;
+    /** Lets go; dismounts when nobody else holds it and no sandbox runs. Never throws: a stuck mount is for doctor. */
+    release(id: string): Promise<ReleaseResult>;
+    dismountIfIdle(): Promise<ReleaseResult>;
+    /**
+     * Deletes the image file (what `storage contained off` offers last, after the files were moved out). Only an image
+     * that is not mounted and not attached; never through a link. The folders around it stay.
+     */
+    deleteImage(): Promise<void>;
+    /** Doctor/repair: the record says mounted, nothing is (clears the record; no permission prompt needed). */
+    clearRecord(): void;
+    private requireOk;
+    /** A mounted image is another volume than its folder; the same id would mean writes land on this PC's own disk. */
+    private assertReallyMounted;
+    /** The folders the image needs on this PC. Only folders this call creates are made private, never one with files. */
+    private ensureFolders;
+}

package/dist/host/storage/contained/contained-storage.js

@@ -0,0 +1,168 @@
+// One data set's contained storage: make sure its image is mounted for a launch (creating it the first time), keep the
+// record of who holds the mount, and dismount when the last holder lets go and no sandbox runs. Disks are only touched
+// through the DiskPort; folders only in the places the layout names.
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertNoLinks, fail } from '../../../core/util/index.js';
+import { assertTestWritable } from '../../test-guard.js';
+import { CONTAINED_FOLDERS, containedPaths } from './layout.js';
+import { addHolder, diagnose, markMounted, processAlive, pruneHolders, removeHolder, setStateOf, StateFile, } from './state.js';
+const deviceOfDefault = (dir) => fs.statSync(dir).dev;
+export class ContainedStorage {
+    deps;
+    set;
+    paths;
+    stateFile;
+    alive;
+    constructor(deps, set) {
+        this.deps = deps;
+        this.set = set;
+        this.paths = containedPaths(deps.storageRoot, set);
+        this.alive = deps.alive ?? processAlive;
+        this.stateFile = new StateFile(this.paths, this.alive);
+    }
+    imageExists() {
+        return fs.existsSync(this.paths.image);
+    }
+    /** Holders of this set that still run. */
+    liveHolders() {
+        return setStateOf(this.stateFile.read(), this.set).holders.filter((h) => this.alive(h.pid)).length;
+    }
+    recordedMounted() {
+        return setStateOf(this.stateFile.read(), this.set).mounted;
+    }
+    reality() {
+        return this.deps.port.reality(this.paths);
+    }
+    async diagnose() {
+        const reality = await this.reality();
+        return diagnose({
+            state: setStateOf(this.stateFile.read(), this.set),
+            reality,
+            live: this.liveHolders(),
+            sandboxRunning: this.deps.sandboxRunning(),
+        });
+    }
+    /**
+     * Makes sure the image is mounted at its folder (creating it when `create` is set and no image exists yet), records
+     * the holder and returns the mount folder, ready with the folders of the data set inside it.
+     */
+    async acquire(holder, o = {}) {
+        this.ensureFolders();
+        // Others that run now vouch for a mount that is there; this holder is recorded first, so a watcher that is just
+        // finishing cannot dismount between the check and the use.
+        const others = this.liveHolders();
+        this.stateFile.update((s) => this.withHolder(s, holder));
+        try {
+            return await this.mountForHolder(others > 0, o.create === true);
+        }
+        catch (e) {
+            this.stateFile.update((s) => pruneHolders(removeHolder(s, this.set, holder.id), this.set, this.alive));
+            throw e;
+        }
+    }
+    async mountForHolder(vouched, create) {
+        const { paths } = this;
+        const before = await this.reality();
+        const mountedAlready = vouched && this.recordedMounted() && before.mountIsMountPoint;
+        if (!mountedAlready) {
+            if (!before.imageExists && !create)
+                fail('The contained storage image is missing: ' + paths.image, 'Run sandbox storage contained on to make it again, or sandbox storage contained off to go back to folders.');
+            const outcome = await this.deps.port.mount({
+                paths,
+                maxGb: this.deps.maxGb,
+                create: !before.imageExists,
+                userSid: this.deps.userSid(),
+            });
+            this.requireOk(outcome, 'mount');
+        }
+        this.assertReallyMounted();
+        for (const name of CONTAINED_FOLDERS)
+            fs.mkdirSync(path.join(paths.mount, name), { recursive: true });
+        this.stateFile.update((s) => markMounted(s, this.set, true));
+        return paths.mount;
+    }
+    withHolder(state, holder) {
+        return addHolder(pruneHolders(state, this.set, this.alive), this.set, {
+            ...holder,
+            since: new Date().toISOString(),
+        });
+    }
+    /** The record knows this set as mounted (the watcher only holds a mount that exists). */
+    isRecorded() {
+        return this.recordedMounted();
+    }
+    /** Adds a holder to a mount that is recorded as mounted (the background watcher); false when nothing is mounted. */
+    hold(holder) {
+        if (!this.recordedMounted())
+            return false;
+        this.stateFile.update((s) => this.withHolder(s, holder));
+        return true;
+    }
+    /** Lets go; dismounts when nobody else holds it and no sandbox runs. Never throws: a stuck mount is for doctor. */
+    async release(id) {
+        this.stateFile.update((s) => pruneHolders(removeHolder(s, this.set, id), this.set, this.alive));
+        return this.dismountIfIdle();
+    }
+    async dismountIfIdle() {
+        if (this.liveHolders() > 0)
+            return { dismounted: false, note: 'another command still uses it' };
+        if (this.deps.sandboxRunning())
+            return { dismounted: false, note: 'a sandbox is running' };
+        try {
+            // Nothing mounted: no permission prompt for nothing.
+            if (!(await this.reality()).mountIsMountPoint) {
+                if (this.recordedMounted())
+                    this.clearRecord();
+                return { dismounted: false, note: 'it was not mounted' };
+            }
+            const outcome = await this.deps.port.dismount({ paths: this.paths, userSid: this.deps.userSid() });
+            if (!outcome.ok)
+                return { dismounted: false, note: outcome.message };
+            this.stateFile.update((s) => markMounted(s, this.set, false));
+            return { dismounted: true };
+        }
+        catch (e) {
+            return { dismounted: false, note: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    /**
+     * Deletes the image file (what `storage contained off` offers last, after the files were moved out). Only an image
+     * that is not mounted and not attached; never through a link. The folders around it stay.
+     */
+    async deleteImage() {
+        assertTestWritable(this.paths.image);
+        const reality = await this.reality();
+        if (reality.mountIsMountPoint || reality.attached === true)
+            fail('The image is still mounted.', 'Dismount it first (sandbox repair), then try again.');
+        assertNoLinks(this.paths.storageRoot, this.paths.image);
+        fs.rmSync(this.paths.image, { force: true });
+        if (fs.existsSync(this.paths.image))
+            fail('The image could not be deleted: ' + this.paths.image, 'Close programs that use it.');
+    }
+    /** Doctor/repair: the record says mounted, nothing is (clears the record; no permission prompt needed). */
+    clearRecord() {
+        this.stateFile.update((s) => markMounted(pruneHolders(s, this.set, this.alive), this.set, false));
+    }
+    requireOk(outcome, what) {
+        if (outcome.ok)
+            return;
+        fail('Could not ' + what + ' the contained storage: ' + outcome.message, 'Run sandbox doctor (it checks the image and the mount folder), or turn contained storage off with: sandbox storage contained off');
+    }
+    /** A mounted image is another volume than its folder; the same id would mean writes land on this PC's own disk. */
+    assertReallyMounted() {
+        const deviceOf = this.deps.deviceOf ?? deviceOfDefault;
+        if (deviceOf(this.paths.mount) === deviceOf(this.paths.mountsDir))
+            fail('The disk image is not mounted at ' + this.paths.mount + ', so nothing was written there.', 'Run sandbox doctor.');
+    }
+    /** The folders the image needs on this PC. Only folders this call creates are made private, never one with files. */
+    ensureFolders() {
+        const { paths } = this;
+        for (const dir of [paths.imagesDir, paths.mountsDir, paths.mount]) {
+            if (fs.existsSync(dir))
+                continue;
+            fs.mkdirSync(dir, { recursive: true });
+            this.deps.protect(dir);
+        }
+    }
+}

package/dist/host/storage/contained/disk-port.d.ts

@@ -0,0 +1,43 @@
+import type { ContainedPaths } from './layout.js';
+import type { MountReality } from './state.js';
+export interface ScriptOutcome {
+    readonly ok: boolean;
+    readonly message: string;
+    /** mount only: the image did not exist and was made (and formatted) by this run. */
+    readonly created: boolean;
+    /** mount only: it was mounted before this run. */
+    readonly alreadyMounted: boolean;
+    readonly notes: readonly string[];
+}
+export interface MountRequest {
+    readonly paths: ContainedPaths;
+    readonly maxGb: number;
+    /** true only the first time: no image file exists yet. The script refuses to create over a file. */
+    readonly create: boolean;
+    readonly userSid: string;
+}
+export interface DismountRequest {
+    readonly paths: ContainedPaths;
+    readonly userSid: string;
+}
+export interface DiskPort {
+    mount(request: MountRequest): Promise<ScriptOutcome>;
+    dismount(request: DismountRequest): Promise<ScriptOutcome>;
+    reality(paths: ContainedPaths): Promise<MountReality>;
+}
+export interface RunResult {
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export type Runner = (file: string, args: readonly string[], timeoutMs: number) => Promise<RunResult>;
+export declare const spawnRunner: Runner;
+export declare class ScriptDiskPort implements DiskPort {
+    private readonly run;
+    constructor(run?: Runner);
+    mount(request: MountRequest): Promise<ScriptOutcome>;
+    dismount(request: DismountRequest): Promise<ScriptOutcome>;
+    reality(paths: ContainedPaths): Promise<MountReality>;
+    /** One run of an elevated script: the request goes in a file in a private temp folder, the answer comes back so. */
+    private elevated;
+}