windows-development-sandbox 1.4.0 → 1.4.3

package/dist/host/projects/registry.d.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+import { PROJECTS_GUEST, type ProjectEntry, type RootMapping } from '../../shared/paths/index.js';
+export { PROJECTS_GUEST };
+export type { ProjectEntry };
+export declare const AbsolutePathSchema: z.ZodString;
+declare const RegistryEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    host: z.ZodString;
+    guest: z.ZodString;
+    primary: z.ZodBoolean;
+    mechanism: z.ZodEnum<{
+        root: "root";
+        launch: "launch";
+        boot: "boot";
+        wsb: "wsb";
+    }>;
+    registeredAt: z.ZodString;
+}, z.core.$strict>;
+declare const RegistrySchema: z.ZodObject<{
+    launchId: z.ZodString;
+    protections: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    roots: z.ZodArray<z.ZodObject<{
+        host: z.ZodString;
+        guest: z.ZodString;
+    }, z.core.$strict>>;
+    projects: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        host: z.ZodString;
+        guest: z.ZodString;
+        primary: z.ZodBoolean;
+        mechanism: z.ZodEnum<{
+            root: "root";
+            launch: "launch";
+            boot: "boot";
+            wsb: "wsb";
+        }>;
+        registeredAt: z.ZodString;
+    }, z.core.$strict>>;
+    atBoot: z.ZodOptional<z.ZodObject<{
+        memoryMb: z.ZodNullable<z.ZodNumber>;
+        mappings: z.ZodArray<z.ZodObject<{
+            host: z.ZodString;
+            guest: z.ZodString;
+            readOnly: z.ZodBoolean;
+        }, z.core.$strict>>;
+        widened: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AtBoot = NonNullable<z.output<typeof RegistrySchema>['atBoot']>;
+export type RegistryEntry = z.output<typeof RegistryEntrySchema>;
+export type Registry = z.output<typeof RegistrySchema>;
+/** Which project of the running sandbox a folder on this PC is in, and where that folder is inside. */
+export interface ProjectHere {
+    project: RegistryEntry;
+    guestDir: string;
+}
+/** run\projects.json under the storage folder: the running sandbox's projects and roots. */
+export declare class ProjectRegistry {
+    private readonly file;
+    constructor(storageRoot: string);
+    read(): Registry | null;
+    save(registry: Registry): void;
+    /** At launch: the launch folder, the projects mapped with it, and the roots. */
+    start(o: {
+        launchId: string;
+        protections: Registry['protections'];
+        primary: RootMapping;
+        roots: RootMapping[];
+        boot: RootMapping[];
+        atBoot?: AtBoot;
+    }): RegistryEntry;
+    /**
+     * What the running sandbox booted with. A sandbox started by 1.4.0 or older has no record: it is read from the .wsb
+     * in its launch folder (host-only storage) and recorded. null when neither is there.
+     */
+    bootRecord(launchPath: string | null): AtBoot | null;
+    /** Which project of the running sandbox this folder is in, and where it is inside. */
+    here(hostDir: string): ProjectHere | null;
+    /** The running sandbox's root containing this folder, if any. */
+    rootHere(hostDir: string): RootMapping | null;
+}
+/** Reads the memory and mapped folders back from a .wsb this tool wrote (host-only launch folder; bounded). */
+export declare function parseWsbBoot(xml: string): AtBoot;

package/dist/host/projects/registry.js

@@ -0,0 +1,136 @@
+// The projects of the running sandbox, and how another folder joins it (shared/projects.ts explains the ways in).
+// Two host-only files under the storage folder, never in the data folder the sandbox can write:
+//  - run\projects.json: the running sandbox's projects, roots and machine-wide protections (written at launch, then
+//    as folders join);
+//  - known-projects.json: every folder this tool has started a project in (for projects.all and `sandbox projects`).
+// Everything about HOW a folder becomes visible is behind ProjectMapper, so the mechanisms can change independently.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { IdSchema } from '../../shared/channel/index.js';
+import { JsonFile } from '../../shared/io/index.js';
+import { guestDirFor, hubName, PROJECTS_GUEST, projectForHostDir, } from '../../shared/paths/index.js';
+export { PROJECTS_GUEST };
+export const AbsolutePathSchema = z
+    .string()
+    .max(1024)
+    .refine((p) => path.isAbsolute(p), 'must be an absolute path');
+const RegistryEntrySchema = z.strictObject({
+    name: IdSchema,
+    host: AbsolutePathSchema,
+    guest: z.string().max(1024),
+    primary: z.boolean(),
+    mechanism: z.enum(['launch', 'root', 'boot', 'wsb']),
+    registeredAt: z.string().max(64),
+});
+const RegistrySchema = z.strictObject({
+    launchId: z.string().max(64),
+    /** The running sandbox's protections (core/project-policy.ts), fixed at boot. */
+    protections: z.record(z.string(), z.union([z.boolean(), z.string()])),
+    roots: z.array(z.strictObject({ host: AbsolutePathSchema, guest: z.string().max(1024) })).max(64),
+    projects: z.array(RegistryEntrySchema).max(1024),
+    /** What the sandbox booted with that a joining project may also want (missing in registries of 1.4.0 and older). */
+    atBoot: z
+        .strictObject({
+        memoryMb: z.number().int().positive().nullable(),
+        mappings: z
+            .array(z.strictObject({ host: z.string().max(1024), guest: z.string().max(1024), readOnly: z.boolean() }))
+            .max(1024),
+        /** Boot settings turned on for a project mapped at boot (setting -> project): other projects share them. */
+        widened: z.record(z.string().max(100), z.string().max(100)),
+    })
+        .optional(),
+});
+/** run\projects.json under the storage folder: the running sandbox's projects and roots. */
+export class ProjectRegistry {
+    file;
+    constructor(storageRoot) {
+        this.file = new JsonFile(RegistrySchema, path.join(storageRoot, 'run', 'projects.json'));
+    }
+    read() {
+        return this.file.read();
+    }
+    save(registry) {
+        this.file.write(registry);
+    }
+    /** At launch: the launch folder, the projects mapped with it, and the roots. */
+    start(o) {
+        const at = new Date().toISOString();
+        const primary = {
+            name: hubName(o.primary.host, []),
+            host: o.primary.host,
+            guest: o.primary.guest,
+            primary: true,
+            mechanism: 'launch',
+            registeredAt: at,
+        };
+        const names = [primary.name];
+        const boot = o.boot.map((b) => {
+            const name = hubName(b.host, names);
+            names.push(name);
+            return { name, host: b.host, guest: b.guest, primary: false, mechanism: 'boot', registeredAt: at };
+        });
+        this.save({
+            launchId: o.launchId,
+            protections: o.protections,
+            roots: o.roots,
+            projects: [primary, ...boot],
+            ...(o.atBoot ? { atBoot: o.atBoot } : {}),
+        });
+        return primary;
+    }
+    /**
+     * What the running sandbox booted with. A sandbox started by 1.4.0 or older has no record: it is read from the .wsb
+     * in its launch folder (host-only storage) and recorded. null when neither is there.
+     */
+    bootRecord(launchPath) {
+        const registry = this.read();
+        if (!registry)
+            return null;
+        if (registry.atBoot)
+            return registry.atBoot;
+        if (!launchPath)
+            return null;
+        let xml;
+        try {
+            xml = fs.readFileSync(path.join(launchPath, 'agent.wsb'), 'utf8');
+        }
+        catch {
+            return null;
+        }
+        const atBoot = parseWsbBoot(xml);
+        try {
+            this.save({ ...registry, atBoot });
+        }
+        catch {
+            /* the record is a convenience */
+        }
+        return atBoot;
+    }
+    /** Which project of the running sandbox this folder is in, and where it is inside. */
+    here(hostDir) {
+        const project = projectForHostDir(this.read()?.projects ?? [], hostDir);
+        return project ? { project, guestDir: guestDirFor(project, hostDir) } : null;
+    }
+    /** The running sandbox's root containing this folder, if any. */
+    rootHere(hostDir) {
+        return projectForHostDir(this.read()?.roots ?? [], hostDir);
+    }
+}
+/** Reads the memory and mapped folders back from a .wsb this tool wrote (host-only launch folder; bounded). */
+export function parseWsbBoot(xml) {
+    const text = xml.slice(0, 1_000_000);
+    const unescape = (s) => s
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, '&');
+    const mappings = [
+        ...text.matchAll(/<MappedFolder><HostFolder>([^<]{1,1024})<\/HostFolder><SandboxFolder>([^<]{1,1024})<\/SandboxFolder><ReadOnly>(true|false)<\/ReadOnly><\/MappedFolder>/g),
+    ]
+        .slice(0, 1024)
+        .map((m) => ({ host: unescape(m[1]), guest: unescape(m[2]), readOnly: m[3] === 'true' }));
+    const memory = /<MemoryInMB>(\d{1,7})<\/MemoryInMB>/.exec(text);
+    return { memoryMb: memory ? Number(memory[1]) : null, mappings, widened: {} };
+}

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

@@ -0,0 +1,2 @@
+import type { Config } from '../../core/types.js';
+export declare const doctorRows: (config: Config, harnessName: string, storageRoot: string, configPath: string | null) => [string, string][];

package/dist/host/sandbox/doctor.js

@@ -0,0 +1,42 @@
+import os from 'node:os';
+import path from 'node:path';
+import { updateRestartPending } from '../life/index.js';
+import { dirExists, isWin } from '../../core/util/index.js';
+import { probeHost } from './probe.js';
+import { sandboxFeatureInstalled, isSandboxRunning } from './platform.js';
+export const doctorRows = (config, harnessName, storageRoot, configPath) => {
+    const probe = probeHost(config, harnessName);
+    return [
+        ['Config file', configPath ?? '(none; built-in defaults; create one with: sandbox config init)'],
+        ['Windows', isWin ? 'yes' : 'NO (launch needs Windows)'],
+        ['Windows Sandbox feature', sandboxFeatureInstalled() ? 'enabled' : 'NOT enabled'],
+        ['Sandbox running', isSandboxRunning() ? 'YES' : 'no'],
+        ['Free host RAM (MB)', String(Math.floor(os.freemem() / 1048576))],
+        [
+            'Update restart pending',
+            updateRestartPending()
+                ? 'YES (Windows may restart on its own and close the sandbox; restart first or pause updates)'
+                : 'no',
+        ],
+        [
+            'Keep this PC awake',
+            config.sandbox.keepAwake
+                ? 'yes, while a sandbox runs'
+                : 'no (sandbox.keepAwake is off: the PC may sleep under running agents)',
+        ],
+        [
+            'Provisioning',
+            config.provisioning.copyFromHost
+                ? 'copy from this PC' + (config.provisioning.fallbackToInstall ? ', fall back to download' : ', no fallback')
+                : 'download inside sandbox',
+        ],
+        ['Host Node (runner)', probe.nvmNode ? 'nvm ' + probe.hostNodeVersion : (probe.nodeDir ?? '(none; will download)')],
+        ['Host nvm versions', probe.nvmDir ?? '(no NVM_HOME; versions will be downloaded)'],
+        [
+            'Host ' + harnessName,
+            probe.harnessExe ? path.join(probe.harnessExe.dir, probe.harnessExe.file) : '(none; will npm install)',
+        ],
+        ['Host Git for Windows', probe.gitDir ?? '(none with bash; PortableGit will be downloaded)'],
+        ['Storage root', storageRoot + (dirExists(storageRoot) ? '' : ' (will be created)')],
+    ];
+};

package/dist/host/sandbox/host-claude.d.ts

@@ -0,0 +1 @@
+export declare const hostClaude: (storageRoot: string, personal: boolean, args: string[]) => number;

package/dist/host/sandbox/host-claude.js

@@ -0,0 +1,26 @@
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { SYSTEM } from '../../shared/system.js';
+import { refuseInSelfTest } from '../test-guard.js';
+import { commandsDir, realAgent } from '../agent-commands/index.js';
+import { ensureDir, fail } from '../../core/util/index.js';
+export const hostClaude = (storageRoot, personal, args) => {
+    refuseInSelfTest('run Claude Code on this PC');
+    // Never this tool's own forwarding command (agentCommands), which would start a sandbox instead.
+    const exe = realAgent('claude', commandsDir(storageRoot));
+    if (!exe)
+        fail('Claude Code is not installed on this PC (no claude.exe or claude.cmd on PATH).', 'Install it: npm install -g @anthropic-ai/claude-code');
+    const env = { ...process.env };
+    if (!personal) {
+        const profile = path.join(storageRoot, 'host', 'claude');
+        ensureDir(profile);
+        env.CLAUDE_CONFIG_DIR = profile;
+        console.warn('Host Claude is NOT sandboxed. Using separate profile: ' + profile + ' (pass --personal to use your normal one).');
+    }
+    const result = exe.toLowerCase().endsWith('.cmd')
+        ? spawnSync(SYSTEM.cmd(), ['/d', '/c', exe, ...args], { stdio: 'inherit', env })
+        : spawnSync(exe, args, { stdio: 'inherit', env });
+    if (result.error)
+        throw result.error;
+    return result.status ?? 1;
+};

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

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

package/dist/host/sandbox/index.js

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

package/dist/host/{platform.d.ts → sandbox/platform.d.ts}

@@ -1,6 +1,3 @@
-import type { Config, HostProbe } from '../core/types.js';
-/** What can be copied from this PC instead of downloaded inside the sandbox. */
-export declare const probeHost: (config: Config, harnessName: string) => HostProbe;
 /**
  * Running INSIDE a Windows Sandbox this tool started (its launch folder and data folder are mapped in): then the CLI
  * talks to the sandbox it is in, through C:\\AgentData and loopback, instead of looking for one on a PC.
@@ -15,5 +12,3 @@ export declare const assertCmdSafePath: (file: string) => void;
 export declare const startSandbox: (wsbPath: string) => void;
 /** Runs a detached copy of this CLI (used for the background history/claude-mem sync watcher). */
 export declare const spawnDetached: (entry: string, args: string[]) => void;
-export declare const hostClaude: (storageRoot: string, personal: boolean, args: string[]) => number;
-export declare const doctorRows: (config: Config, harnessName: string, storageRoot: string, configPath: string | null) => [string, string][];

package/dist/host/sandbox/platform.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { SYSTEM } from '../../shared/system.js';
+import { refuseInSelfTest } from '../test-guard.js';
+import { fail, fileExists, isWin } from '../../core/util/index.js';
+const SANDBOX_PROCESSES = ['WindowsSandboxClient.exe', 'WindowsSandboxRemoteSession.exe', 'WindowsSandbox.exe'];
+/**
+ * Running INSIDE a Windows Sandbox this tool started (its launch folder and data folder are mapped in): then the CLI
+ * talks to the sandbox it is in, through C:\\AgentData and loopback, instead of looking for one on a PC.
+ */
+export const insideSandbox = () => isWin &&
+    !process.env.AGENT_SANDBOX_HOST_ONLY &&
+    fs.existsSync('C:\\AgentLaunch\\session.json') &&
+    fs.existsSync('C:\\AgentData\\run');
+export const GUEST_DATA_DIR = 'C:\\AgentData';
+export const isSandboxRunning = () => {
+    if (!isWin)
+        return false;
+    if (insideSandbox())
+        return true;
+    const result = spawnSync(SYSTEM.tasklist(), ['/NH', '/FO', 'CSV'], { encoding: 'utf8', windowsHide: true });
+    const out = (result.stdout ?? '').toLowerCase();
+    return SANDBOX_PROCESSES.some((image) => out.includes('"' + image.toLowerCase() + '"'));
+};
+export const sandboxFeatureInstalled = () => isWin && fileExists(path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32', 'WindowsSandbox.exe'));
+export const assertCanLaunch = () => {
+    if (!isWin)
+        fail('Windows Sandbox only runs on Windows.', 'Use sandbox generate to only write the files.');
+    if (!sandboxFeatureInstalled())
+        fail('Windows Sandbox is not enabled on this PC.', 'Run in an admin PowerShell, then reboot: Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All  (needs Windows Pro, Enterprise or Education)');
+    if (isSandboxRunning())
+        fail('A Windows Sandbox is already running (Windows allows one at a time).', 'Attach to it with sandbox claude -t, show it with sbx-show, or shut it down with sandbox stop.');
+};
+/** cmd.exe expands %VAR% and ^ even inside quotes, and a quote ends them: such a path could run something else. */
+export const assertCmdSafePath = (file) => {
+    if (/[%"^\r\n]/.test(file))
+        fail('The storage folder path has a character that cannot be started safely: ' + file, 'Set storage.root to a folder without % " ^ in its path.');
+};
+export const startSandbox = (wsbPath) => {
+    refuseInSelfTest('start Windows Sandbox');
+    assertCmdSafePath(wsbPath);
+    const result = spawnSync(SYSTEM.cmd(), ['/d', '/c', 'start', '""', '"' + wsbPath + '"'], {
+        stdio: 'inherit',
+        windowsVerbatimArguments: true,
+    });
+    if (result.error)
+        throw result.error;
+};
+/** Runs a detached copy of this CLI (used for the background history/claude-mem sync watcher). */
+export const spawnDetached = (entry, args) => {
+    refuseInSelfTest('start background programs');
+    // cwd = the install folder: the caller's folder is the workspace, which the sandbox can write.
+    spawn(process.execPath, [entry, ...args], {
+        cwd: path.dirname(entry),
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+    }).unref();
+};

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

@@ -0,0 +1,3 @@
+import type { Config, HostProbe } from '../../core/types.js';
+/** What can be copied from this PC instead of downloaded inside the sandbox. */
+export declare const probeHost: (config: Config, harnessName: string) => HostProbe;

package/dist/host/sandbox/probe.js

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import { dirExists, fileExists, findOnPath, homeDir, isWin, realPath } from '../../core/util/index.js';
+const findHarnessExe = (config, harnessName) => {
+    const harness = config.harnesses[harnessName];
+    if (!harness?.hostExecutable)
+        return null;
+    const explicit = harness.hostDir && harness.hostDir !== 'auto' ? path.join(harness.hostDir, harness.hostExecutable) : null;
+    const found = explicit
+        ? fileExists(explicit)
+            ? explicit
+            : null
+        : (findOnPath([harness.hostExecutable]) ??
+            [path.join(homeDir(), '.local', 'bin', harness.hostExecutable)].find(fileExists) ??
+            null);
+    if (!found)
+        return null;
+    const real = realPath(found);
+    return { dir: path.dirname(real), file: path.basename(real) };
+};
+/** Git for Windows root (the folder with cmd\git.exe and bin\bash.exe), from git on PATH. */
+const findGitRoot = () => {
+    const git = findOnPath(['git.exe']);
+    if (!git)
+        return null;
+    const root = path.resolve(path.dirname(realPath(git)), '..');
+    return fileExists(path.join(root, 'bin', 'bash.exe')) ? root : null;
+};
+/** What can be copied from this PC instead of downloaded inside the sandbox. */
+export const probeHost = (config, harnessName) => {
+    const nodeDir = isWin ? path.dirname(process.execPath) : null;
+    const copy = config.provisioning.copyFromHost;
+    const nvmHome = process.env.NVM_HOME;
+    const nvmDir = copy && nvmHome && dirExists(nvmHome) ? realPath(nvmHome) : null;
+    const hasNode = (dir) => fileExists(path.join(dir, 'node.exe')) && fileExists(path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js'));
+    // One source for Node: nvm's copy of this version when there is one, otherwise the Node folder itself.
+    const nvmNode = Boolean(nvmDir && hasNode(path.join(nvmDir, process.version)));
+    return {
+        nodeDir: copy && !nvmNode && nodeDir && hasNode(nodeDir) ? realPath(nodeDir) : null,
+        harnessExe: copy ? findHarnessExe(config, harnessName) : null,
+        gitDir: copy && config.provisioning.git.enabled ? findGitRoot() : null,
+        nvmDir,
+        hostNodeVersion: process.version,
+        nvmNode,
+        volta: Boolean(process.env.VOLTA_HOME),
+        pyenv: Boolean(process.env.PYENV ?? process.env.PYENV_ROOT ?? process.env.PYENV_HOME),
+    };
+};

package/dist/host/{window.js → sandbox/window.js}

@@ -1,9 +1,9 @@
 // Headless mode: Windows Sandbox always opens its client window, so we hide it (ShowWindow SW_HIDE) as soon as it
 // appears. The VM and the logged-in session keep running; `sbx-show` brings the window back.
 import path from 'node:path';
-import { writeJsonAtomic } from '../shared/rundir.js';
-import { refuseInSelfTest } from './test-guard.js';
-import { isWin, runPowerShell, runPowerShellAsync, tryReadJson } from '../core/util.js';
+import { writeJsonAtomic } from '../../shared/io/index.js';
+import { refuseInSelfTest } from '../test-guard.js';
+import { isWin, runPowerShell, runPowerShellAsync, tryReadJson } from '../../core/util/index.js';
 const PRELUDE = `
 $ErrorActionPreference = 'Stop'
 Add-Type -Namespace AgentSandbox -Name Win -MemberDefinition @'
@@ -39,7 +39,8 @@ export const hideSandboxWindow = async (storageRoot, waitSeconds = 180) => {
     refuseInSelfTest('hide windows');
     if (!isWin)
         return false;
-    const script = PRELUDE + `
+    const script = PRELUDE +
+        `
 $hidden = New-Object System.Collections.ArrayList
 $deadline = (Get-Date).AddSeconds(${waitSeconds}); $settle = $null
 while ((Get-Date) -lt $deadline) {
@@ -61,7 +62,8 @@ export const showSandboxWindow = (storageRoot) => {
         return false;
     // Only integers go into the script, whatever the file contains.
     const recorded = (tryReadJson(stateFile(storageRoot))?.handles ?? []).filter((h) => Number.isSafeInteger(h));
-    const script = PRELUDE + `
+    const script = PRELUDE +
+        `
 $handles = @(${recorded.join(',')}) | Where-Object { [AgentSandbox.Win]::IsWindow([IntPtr]$_) }
 if (-not $handles) { $handles = Get-SandboxWindows $false }
 foreach ($h in $handles) { [void][AgentSandbox.Win]::ShowWindow([IntPtr]$h, 5); [void][AgentSandbox.Win]::ShowWindow([IntPtr]$h, 9); [void][AgentSandbox.Win]::SetForegroundWindow([IntPtr]$h) }

package/dist/host/{wsb.js → sandbox/wsb-cli.js}

@@ -9,7 +9,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { refuseInSelfTest } from './test-guard.js';
+import { refuseInSelfTest } from '../test-guard.js';
 const GUID = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i;
 const MAX_OUTPUT = 1024 * 1024;
 /** Where wsb.exe can be: the Store app's alias, then System32 (never by bare name; cwd is often the workspace). */
@@ -17,7 +17,7 @@ export const wsbCandidates = (env = process.env) => [
     env.LOCALAPPDATA ? path.join(env.LOCALAPPDATA, 'Microsoft', 'WindowsApps', 'wsb.exe') : '',
     path.join(env.SystemRoot ?? env.WINDIR ?? 'C:\\Windows', 'System32', 'wsb.exe'),
 ].filter(Boolean);
-export const findWsb = (env = process.env, exists = fs.existsSync) => process.platform === 'win32' || exists !== fs.existsSync ? wsbCandidates(env).find((p) => exists(p)) ?? null : null;
+export const findWsb = (env = process.env, exists = fs.existsSync) => process.platform === 'win32' || exists !== fs.existsSync ? (wsbCandidates(env).find((p) => exists(p)) ?? null) : null;
 // ---- parsing (pure; the tests feed it recorded output) ---------------------------------------------------------
 /** The version from `wsb --version` ("0.1.32.0", "wsb 1.2.3+abc"). */
 export const parseVersion = (out) => /\d+\.\d+(?:\.\d+){0,2}/.exec(out)?.[0] ?? null;
@@ -49,10 +49,12 @@ export const parseList = (out) => {
     };
     try {
         const parsed = JSON.parse(out);
-        const list = Array.isArray(parsed) ? parsed : Object.values(parsed).find(Array.isArray) ?? [parsed];
+        const list = Array.isArray(parsed) ? parsed : (Object.values(parsed).find(Array.isArray) ?? [parsed]);
         return list.map(fromObject).filter((s) => s !== null);
     }
-    catch { /* the table */ }
+    catch {
+        /* the table */
+    }
     return out.split(/\r?\n/).flatMap((line) => {
         const id = GUID.exec(line)?.[0];
         if (!id)
@@ -68,7 +70,14 @@ const call = (exe, args, timeoutMs = 60000) => {
     const stderr = String(r.stderr ?? '').slice(0, MAX_OUTPUT);
     if (r.error)
         return { ok: false, stdout, stderr, error: r.error.message };
-    return { ok: r.status === 0, stdout, stderr, ...(r.status === 0 ? {} : { error: (stderr || stdout).trim().split(/\r?\n/).slice(-3).join(' ') || 'exit code ' + r.status }) };
+    return {
+        ok: r.status === 0,
+        stdout,
+        stderr,
+        ...(r.status === 0
+            ? {}
+            : { error: (stderr || stdout).trim().split(/\r?\n/).slice(-3).join(' ') || 'exit code ' + r.status }),
+    };
 };
 /** The CLI and what it offers, or null on Windows versions without it. */
 export const detectWsb = (env = process.env) => {
@@ -89,13 +98,27 @@ export const runningSandboxId = (wsb) => {
     const running = all.filter((s) => !/stopped/i.test(s.status));
     if (running.length === 1)
         return { id: running[0].id };
-    return { id: null, error: running.length ? running.length + ' sandboxes are running (wsb list); cannot tell which one is ours' : 'wsb list shows no running sandbox (one started from a .wsb file may not be listed)' };
+    return {
+        id: null,
+        error: running.length
+            ? running.length + ' sandboxes are running (wsb list); cannot tell which one is ours'
+            : 'wsb list shows no running sandbox (one started from a .wsb file may not be listed)',
+    };
 };
 /** Shares a folder of this PC into the running sandbox at `sandboxPath` (read/write unless readOnly). */
 export const shareFolder = (wsb, id, hostPath, sandboxPath, readOnly = false) => {
     refuseInSelfTest('share a folder into Windows Sandbox');
     if (!GUID.test(id))
         return { ok: false, stdout: '', stderr: '', error: 'not a sandbox id: ' + id };
-    return call(wsb.exe, ['share', '--id', id, '-f', hostPath, '-s', sandboxPath, ...(readOnly ? [] : ['--allow-write'])]);
+    return call(wsb.exe, [
+        'share',
+        '--id',
+        id,
+        '-f',
+        hostPath,
+        '-s',
+        sandboxPath,
+        ...(readOnly ? [] : ['--allow-write']),
+    ]);
 };
-export const sandboxIp = (wsb, id) => (GUID.test(id) ? parseIp(call(wsb.exe, ['ip', '--id', id], 15000).stdout) : null);
+export const sandboxIp = (wsb, id) => GUID.test(id) ? parseIp(call(wsb.exe, ['ip', '--id', id], 15000).stdout) : null;

package/dist/host/{cleanup.js → storage/cleanup.js}

@@ -2,19 +2,21 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import _ from 'lodash';
-import { sizeOf } from '../core/disk.js';
-import { dirExists, isLink } from '../core/util.js';
-import { safeRemove } from '../shared/safe-remove.js';
+import { sizeOf } from '../../core/disk.js';
+import { dirExists, isLink } from '../../core/util/index.js';
+import { safeRemove } from '../../shared/io/index.js';
 const DAY = 24 * 60 * 60 * 1000;
 export const DEFAULT_PRUNE = { launchDays: 7, logDays: 14, conflictDays: 30, keep: [] };
-const ageMs = (p, now) => { try {
-    return now - fs.lstatSync(p).mtimeMs;
-}
-catch {
-    return 0;
-} };
+const ageMs = (p, now) => {
+    try {
+        return now - fs.lstatSync(p).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+};
 /** Entries of a real folder; a link in place of a folder yields nothing (it is never listed or entered). */
-const children = (dir) => (dirExists(dir) && !isLink(dir) ? fs.readdirSync(dir).map((name) => path.join(dir, name)) : []);
+const children = (dir) => dirExists(dir) && !isLink(dir) ? fs.readdirSync(dir).map((name) => path.join(dir, name)) : [];
 /**
  * Deletes, under the storage root:
  *  - launch folders older than `launchDays` (a launch folder is only used by the sandbox it started; `keep` protects the running one)
@@ -40,7 +42,11 @@ export const pruneStorage = (storageRoot, options = {}) => {
             if (ageMs(log, now) > o.logDays * DAY)
                 remove(log, 'logs');
         const runDir = path.join(data, 'run');
-        const dirs = [path.join(data, 'tools'), path.join(data, 'state'), ...(isLink(runDir) ? [] : [runDir, path.join(runDir, 'responses')])];
+        const dirs = [
+            path.join(data, 'tools'),
+            path.join(data, 'state'),
+            ...(isLink(runDir) ? [] : [runDir, path.join(runDir, 'responses')]),
+        ];
         for (const dir of dirs) {
             for (const entry of children(dir)) {
                 const name = path.basename(entry);
@@ -54,4 +60,13 @@ export const pruneStorage = (storageRoot, options = {}) => {
     }
     return result;
 };
-export const describePrune = (r) => r.launches + r.logs + r.leftovers === 0 ? 'nothing to clean' : _.compact([r.launches && r.launches + ' launch folder(s)', r.logs && r.logs + ' log(s)', r.leftovers && r.leftovers + ' leftover(s)']).join(', ') + ' removed (' + Math.round(r.bytes / 1048576) + ' MB)';
+export const describePrune = (r) => r.launches + r.logs + r.leftovers === 0
+    ? 'nothing to clean'
+    : _.compact([
+        r.launches && r.launches + ' launch folder(s)',
+        r.logs && r.logs + ' log(s)',
+        r.leftovers && r.leftovers + ' leftover(s)',
+    ]).join(', ') +
+        ' removed (' +
+        Math.round(r.bytes / 1048576) +
+        ' MB)';

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

@@ -0,0 +1,2 @@
+export * from './cleanup.js';
+export * from './state-files.js';

package/dist/host/storage/index.js

@@ -0,0 +1,2 @@
+export * from './cleanup.js';
+export * from './state-files.js';

package/dist/host/storage/state-files.d.ts

@@ -0,0 +1,4 @@
+export type StateFileSuffix = '.json' | '-audit.json' | '-forwards.json' | '-life.json' | '-mark.json' | '-repo.json' | '-repo-findings.json' | '-size.json' | '-views.json';
+/** The storage folder a data folder is in (<storage>\data\<name>); inside a sandbox it differs from the context's. */
+export declare function storageOf(dataPath: string): string;
+export declare function hostStateFile(storageRoot: string, dataPath: string, suffix: StateFileSuffix): string;

package/dist/host/storage/state-files.js

@@ -0,0 +1,10 @@
+// Host-only state of one data folder: <storage>\sync\<data name><suffix>, never in the data folder the sandbox can
+// write.
+import path from 'node:path';
+/** The storage folder a data folder is in (<storage>\data\<name>); inside a sandbox it differs from the context's. */
+export function storageOf(dataPath) {
+    return path.dirname(path.dirname(dataPath));
+}
+export function hostStateFile(storageRoot, dataPath, suffix) {
+    return path.join(storageRoot, 'sync', path.basename(dataPath) + suffix);
+}

package/dist/host/test-guard.js

@@ -1,6 +1,6 @@
 // Host side of the self-test guard (see shared/test-guard.ts): outward actions refuse, with a message the user can read.
 import { testWriteRefusal, selfTestRunning } from '../shared/test-guard.js';
-import { fail } from '../core/util.js';
+import { fail } from '../core/util/index.js';
 export { selfTestRunning };
 /** Refuses an action that reaches outside the test's own temp folder (a no-op outside the self-test). */
 export const refuseInSelfTest = (what) => {