windows-development-sandbox 1.4.1 → 1.5.0

package/dist/host/stops.js

@@ -1,126 +0,0 @@
-// Why the last sandbox stopped, when nobody stopped it. The background watcher writes a host-only "life" record (when
-// the sandbox started, when it was last seen running, how it ended) and keeps this PC awake while it runs
-// (sandbox.keepAwake). When the PC restarts, sleeps or crashes, the watcher stops too and the record has no end: the
-// next launch reads Windows' System log from that moment on and says what happened, and what keeps it from happening.
-import { spawn, spawnSync } from 'node:child_process';
-import path from 'node:path';
-import { z } from 'zod';
-import { SYSTEM } from '../shared/system.js';
-import { readValid, writeJsonAtomic } from '../shared/rundir.js';
-import { isWin } from '../core/util.js';
-import { refuseInSelfTest } from './test-guard.js';
-const Iso = z.string().max(40);
-const Life = z.object({
-    started: Iso, lastSeen: Iso, keepAwake: z.boolean(),
-    ended: z.object({ at: Iso, cause: z.object({ kind: z.enum(['updates', 'restart', 'crash', 'sleep', 'memory', 'sandboxCrash']), at: Iso, text: z.string().max(400) }).nullable() }).optional(),
-    reported: z.boolean().optional(),
-});
-const lifeFile = (storageRoot, dataPath) => path.join(storageRoot, 'sync', path.basename(dataPath) + '-life.json');
-export const readLife = (storageRoot, dataPath) => readValid(Life, lifeFile(storageRoot, dataPath));
-const writeLife = (storageRoot, dataPath, life) => writeJsonAtomic(lifeFile(storageRoot, dataPath), life);
-/** At launch: a fresh record (the previous one has been reported by then). */
-export const startLife = (storageRoot, dataPath, keepAwake, now = new Date()) => writeLife(storageRoot, dataPath, { started: now.toISOString(), lastSeen: now.toISOString(), keepAwake });
-/** Every minute while the sandbox runs. */
-export const beatLife = (storageRoot, dataPath, now = new Date()) => {
-    const life = readLife(storageRoot, dataPath);
-    if (life && !life.ended)
-        writeLife(storageRoot, dataPath, { ...life, lastSeen: now.toISOString() });
-};
-/** The watcher saw the sandbox close while this PC kept running: closed by you (no cause), or by sleep / low memory. */
-export const endLife = (storageRoot, dataPath, cause, now = new Date()) => {
-    const life = readLife(storageRoot, dataPath);
-    if (life && !life.ended)
-        writeLife(storageRoot, dataPath, { ...life, ended: { at: now.toISOString(), cause } });
-};
-const StopEvents = z.array(z.object({ at: Iso, id: z.number().int(), provider: z.string().max(200), process: z.string().max(400).nullable().transform((p) => p ?? '') })).max(100);
-const UPDATERS = /^(trustedinstaller|mousocoreworker|musnotification(ux)?|usoclient|wuauclt|tiworker|updateorchestrator)\.exe$/i;
-/**
- * The first event that ends a running sandbox (pure): Windows inside the sandbox crashing (Hyper-V 18590; `process`
- * holds its message with the stop code), a restart or shutdown, a crash or power loss, sleep, low memory. Switching
- * user does not end it (seen on 13 Oct 2026: the sandbox ran on after a switch).
- */
-export const explainStop = (events) => {
-    const causes = events.flatMap((e) => {
-        const p = e.provider.toLowerCase();
-        if (e.id === 1074 && p.includes('user32')) {
-            const exe = e.process.split(/[\\/]/).pop()?.replace(/\s*\(.*$/, '') ?? '';
-            return UPDATERS.test(exe)
-                ? [{ kind: 'updates', at: e.at, text: 'Windows restarted this PC to install updates' }]
-                : [{ kind: 'restart', at: e.at, text: 'this PC was restarted or shut down' + (exe ? ' (by ' + exe + ')' : '') }];
-        }
-        if ((e.id === 41 && p.includes('kernel-power')) || (e.id === 6008 && p.includes('eventlog')))
-            return [{ kind: 'crash', at: e.at, text: 'Windows stopped unexpectedly (a crash, a power cut, or the power button held down)' }];
-        if (e.id === 42 && p.includes('kernel-power'))
-            return [{ kind: 'sleep', at: e.at, text: 'this PC went to sleep or hibernated' }];
-        if (e.id === 2004 && p.includes('resource-exhaustion'))
-            return [{ kind: 'memory', at: e.at, text: 'this PC ran out of memory' }];
-        if (e.id === 18590 && p.includes('hyper-v-worker')) {
-            const code = /ErrorCode0:\s*(0x[0-9a-f]{1,8})/i.exec(e.process)?.[1];
-            const sub = /ErrorCode1:\s*(0x[0-9a-f]{1,16})/i.exec(e.process)?.[1];
-            return [{ kind: 'sandboxCrash', at: e.at, text: 'Windows inside the sandbox crashed' + (code ? ' (stop code ' + code + (sub ? ', ' + sub : '') + ')' : '') }];
-        }
-        return [];
-    });
-    return causes.sort((a, b) => Date.parse(a.at) - Date.parse(b.at))[0] ?? null;
-};
-const ADVICE = {
-    updates: 'Before leaving agents overnight, restart for pending updates first or pause them (Settings > Windows Update > Pause updates).',
-    restart: 'If that was not you, check Settings > Windows Update and Event Viewer > Windows Logs > System.',
-    crash: 'Event Viewer > Windows Logs > System has the details; a laptop also needs to stay plugged in.',
-    sleep: 'sandbox.keepAwake keeps this PC awake while a sandbox runs (closing a laptop lid still sleeps it). Check it is on, and that sleep is not forced by a policy.',
-    sandboxCrash: 'C:\\AgentData\\logs\\memory-*.log shows what used memory just before. Fewer builds at once inside the sandbox (e.g. cargo build.jobs) makes it less likely.',
-    memory: 'Give the sandbox less RAM (sandbox.maxMemoryMb, sandbox.reserveHostMb) or run fewer builds at once inside it.',
-};
-/** System log and Hyper-V events since `since` that can end a sandbox (Windows only; empty when the logs cannot be read). */
-export const readStopEvents = (since) => {
-    if (!isWin)
-        return [];
-    refuseInSelfTest('read the Windows event log');
-    const script = "$ErrorActionPreference='SilentlyContinue'; $t=[datetime]::Parse('" + since.toISOString() + "').ToLocalTime(); $e = Get-WinEvent -FilterHashtable @(@{LogName='System'; Id=1074,6008,41,42,2004; StartTime=$t}, @{LogName='Microsoft-Windows-Hyper-V-Worker-Admin'; Id=18590; StartTime=$t}) -MaxEvents 100 | ForEach-Object { [pscustomobject]@{ at=$_.TimeCreated.ToUniversalTime().ToString('o'); id=$_.Id; provider=$_.ProviderName; process=$(if ($_.Id -eq 1074) { [string]$_.Properties[0].Value } elseif ($_.Id -eq 18590) { ([string]$_.Message).Substring(0, [math]::Min(390, ([string]$_.Message).Length)) } else { '' }) } }; ConvertTo-Json -Compress -InputObject @($e)";
-    const result = spawnSync(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')], { encoding: 'utf8', windowsHide: true, timeout: 60000 });
-    try {
-        return StopEvents.parse(JSON.parse(result.stdout || '[]'));
-    }
-    catch {
-        return [];
-    }
-};
-/** Looking back from the last time the sandbox was seen running (a minute between checks, plus margin). */
-export const causeSince = (lastSeen) => explainStop(readStopEvents(new Date(Date.parse(lastSeen) - 2 * 60 * 1000)));
-const when = (iso) => new Date(iso).toLocaleString(undefined, { weekday: 'short', hour: '2-digit', minute: '2-digit' });
-/**
- * At launch: one warning when the last sandbox ended without anyone closing it (the PC restarted, crashed, slept or ran
- * out of memory), then never again for that run. `watcherAlive` = its watcher is still running (then it did not end).
- */
-export const lastStopWarning = (storageRoot, dataPath, watcherAlive, find = causeSince) => {
-    const life = readLife(storageRoot, dataPath);
-    if (!life || life.reported || watcherAlive)
-        return null;
-    writeLife(storageRoot, dataPath, { ...life, reported: true });
-    if (life.ended && !life.ended.cause)
-        return null;
-    const cause = life.ended ? life.ended.cause : find(life.lastSeen);
-    const what = cause ? cause.text + ' at ' + when(cause.at) + '. ' + ADVICE[cause.kind] : 'this PC stopped (Windows logged no reason). ' + ADVICE.crash;
-    return 'The last sandbox did not close normally: it was last seen running at ' + when(life.lastSeen) + ', and ' + what + ' Agent conversations are kept: /resume in Claude picks one up.';
-};
-// ---- Windows Update and keeping awake ----------------------------------------------------------------------------
-/** Windows has installed updates and waits to restart: it may do so on its own, outside your active hours. */
-export const updateRestartPending = () => isWin && [
-    'HKLM\\SOFTWARE\\Microsoft\\WindowsUpdate\\Auto Update\\RebootRequired',
-    'HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Component Based Servicing\\RebootPending',
-].some((key) => spawnSync(SYSTEM.reg(), ['query', key], { windowsHide: true, stdio: 'ignore', timeout: 15000 }).status === 0);
-export const UPDATE_RESTART_WARNING = 'Windows is waiting to restart for updates and may do so on its own (often overnight), which closes the sandbox. Restart first, or pause updates: Settings > Windows Update > Pause updates.';
-/**
- * sandbox.keepAwake: asks Windows not to sleep while the sandbox runs (as a video player does; the screen may still turn
- * off). A small PowerShell holds the request until `ownerPid` exits, so it never outlives the watcher.
- */
-export const keepAwake = (ownerPid) => {
-    if (!isWin)
-        return null;
-    refuseInSelfTest('keep this PC awake');
-    const script = "Add-Type -Name Power -Namespace AgentSandbox -MemberDefinition '[DllImport(\"kernel32.dll\")] public static extern uint SetThreadExecutionState(uint f);'; "
-        + '[void][AgentSandbox.Power]::SetThreadExecutionState([uint32]2147483649); Wait-Process -Id ' + Math.trunc(ownerPid) + ' -ErrorAction SilentlyContinue';
-    const child = spawn(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')], { stdio: 'ignore', windowsHide: true });
-    child.on('error', () => undefined);
-    return child;
-};

package/dist/host/terminal.d.ts

@@ -1,40 +0,0 @@
-import { z } from 'zod';
-export declare const terminalDir: (dataPath: string) => string;
-export declare const terminalExe: (dataPath: string) => string;
-/** Our own profile id, so the profile is found again (and user edits to it are kept) on later launches. */
-export declare const PWSH_PROFILE_GUID = "{5f3a6c1e-7d2b-4e8a-9c41-0b6d2a8f7e93}";
-declare const TerminalSettings: z.ZodObject<{
-    profiles: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
-        guid: z.ZodOptional<z.ZodString>;
-    }, z.core.$loose>>, z.ZodObject<{
-        list: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            guid: z.ZodOptional<z.ZodString>;
-        }, z.core.$loose>>>;
-    }, z.core.$loose>]>>;
-}, z.core.$loose>;
-/**
- * settings.json with the "PowerShell 7" profile shown when `visible`, else hidden (never deleted: a user's tweaks to it
- * survive turning pwsh off and on). Pure: returns null when nothing changes.
- */
-export declare const withPwshProfile: (settings: z.output<typeof TerminalSettings>, visible: boolean) => z.output<typeof TerminalSettings> | null;
-/**
- * Shows the PowerShell 7 profile once pwsh is installed in this data folder (and `allowed`, i.e. toolchains.pwsh is
- * not off), hides it otherwise. settings.json is written by the sandbox too: read with a size cap, through no links,
- * shape-checked, only rewritten when the profile changes; a file that does not parse is left alone.
- */
-export declare const syncPwshProfile: (dataPath: string, allowed: boolean) => void;
-export declare const ensureTerminal: (dataPath: string, refresh: boolean, options?: {
-    pwsh?: boolean;
-}) => Promise<{
-    exe: string | null;
-    message: string;
-}>;
-/** Where the sandbox finds conpty.dll + OpenConsole.exe (guest/ptyhost.ts points ptyhost at it). */
-export declare const conptyDir: (dataPath: string) => string;
-/**
- * Microsoft's newer pseudo console (the Microsoft.Windows.Console.ConPTY package: conpty.dll and OpenConsole.exe, the
- * same one Windows Terminal and VS Code use), downloaded once and verified against the SHA-512 NuGet publishes. Agent
- * sessions use it instead of the one built into Windows, which re-renders the screen and garbles it after resizes.
- */
-export declare const ensureConpty: (dataPath: string, refresh: boolean) => Promise<string>;
-export {};

package/dist/host/terminal.js

@@ -1,174 +0,0 @@
-// Windows Terminal for the sandbox window. The host downloads the portable build once into persistent storage, so
-// logon.cmd can open it the moment the sandbox logs in (no PowerShell window first).
-import fs from 'node:fs';
-import path from 'node:path';
-import { download, extractArchive, fetchJson, githubAsset, installArchive, moveIntoPlace, stagingFolder } from '../shared/download.js';
-import { safeRemove } from '../shared/safe-remove.js';
-import { assertTestWritable } from './test-guard.js';
-import { z } from 'zod';
-import { assertNoLinks, errMsg, fileExists, parseJsonc, writeJson } from '../core/util.js';
-export const terminalDir = (dataPath) => path.join(dataPath, 'tools', 'terminal');
-export const terminalExe = (dataPath) => path.join(terminalDir(dataPath), 'WindowsTerminal.exe');
-/**
- * Sandbox-friendly defaults; only written when there is no settings.json yet (first download), so edits made inside
- * the sandbox stick, also across a refresh (which keeps the settings folder).
- */
-const SETTINGS = {
-    $schema: 'https://aka.ms/terminal-profiles-schema',
-    theme: 'dark',
-    firstWindowPreference: 'defaultProfile',
-    confirmCloseAllTabs: false,
-    // New tabs pick up the PATH and variables the runner writes machine-wide after the window opened.
-    compatibility: { reloadEnvironmentVariables: true },
-    warning: { confirmCloseAllTabs: false, largePaste: false, multiLinePaste: false },
-    profiles: { defaults: { font: { face: 'Cascadia Mono' }, startingDirectory: '%AGENT_WORKSPACE%', closeOnExit: 'graceful' } },
-};
-/** Our own profile id, so the profile is found again (and user edits to it are kept) on later launches. */
-export const PWSH_PROFILE_GUID = '{5f3a6c1e-7d2b-4e8a-9c41-0b6d2a8f7e93}';
-/** pwsh.exe as the sandbox sees it (toolchains/pwsh.ts installs it to tools\pwsh). */
-const GUEST_PWSH = 'C:\\AgentData\\tools\\pwsh\\pwsh.exe';
-const MAX_SETTINGS_BYTES = 1024 * 1024;
-const TerminalSettings = z.looseObject({
-    profiles: z.union([z.array(z.looseObject({ guid: z.string().optional() })), z.looseObject({ list: z.array(z.looseObject({ guid: z.string().optional() })).optional() })]).optional(),
-});
-/**
- * settings.json with the "PowerShell 7" profile shown when `visible`, else hidden (never deleted: a user's tweaks to it
- * survive turning pwsh off and on). Pure: returns null when nothing changes.
- */
-export const withPwshProfile = (settings, visible) => {
-    const profiles = Array.isArray(settings.profiles) ? { list: settings.profiles } : { ...settings.profiles };
-    const list = [...(profiles.list ?? [])];
-    const at = list.findIndex((p) => p.guid?.toLowerCase() === PWSH_PROFILE_GUID);
-    if (at === -1 && !visible)
-        return null;
-    if (at === -1)
-        list.push({ guid: PWSH_PROFILE_GUID, name: 'PowerShell 7', commandline: '"' + GUEST_PWSH + '" -NoLogo', icon: GUEST_PWSH, hidden: false });
-    else if ((list[at].hidden === true) === !visible)
-        return null;
-    else
-        list[at] = { ...list[at], hidden: !visible };
-    return { ...settings, profiles: { ...profiles, list } };
-};
-/**
- * Shows the PowerShell 7 profile once pwsh is installed in this data folder (and `allowed`, i.e. toolchains.pwsh is
- * not off), hides it otherwise. settings.json is written by the sandbox too: read with a size cap, through no links,
- * shape-checked, only rewritten when the profile changes; a file that does not parse is left alone.
- */
-export const syncPwshProfile = (dataPath, allowed) => {
-    const file = path.join(terminalDir(dataPath), 'settings', 'settings.json');
-    assertTestWritable(file);
-    assertNoLinks(dataPath, file);
-    if (!fileExists(file) || fs.statSync(file).size > MAX_SETTINGS_BYTES)
-        return;
-    const visible = allowed && fileExists(path.join(dataPath, 'tools', 'pwsh', 'pwsh.exe'));
-    let parsed;
-    try {
-        const result = TerminalSettings.safeParse(parseJsonc(fs.readFileSync(file, 'utf8'), file));
-        if (!result.success)
-            return;
-        parsed = result.data;
-    }
-    catch {
-        return;
-    }
-    const next = withPwshProfile(parsed, visible);
-    if (next)
-        writeJson(file, next);
-};
-export const ensureTerminal = async (dataPath, refresh, options = {}) => {
-    const result = await installTerminal(dataPath, refresh);
-    if (result.exe) {
-        // The profile is a nicety: a settings problem never costs the sandbox its terminal.
-        try {
-            syncPwshProfile(dataPath, options.pwsh ?? false);
-        }
-        catch (e) {
-            return { ...result, message: result.message + ' (PowerShell 7 profile not updated: ' + errMsg(e) + ')' };
-        }
-    }
-    return result;
-};
-// ---- conpty.dll ------------------------------------------------------------------------------------------------------
-/** Where the sandbox finds conpty.dll + OpenConsole.exe (guest/ptyhost.ts points ptyhost at it). */
-export const conptyDir = (dataPath) => path.join(dataPath, 'tools', 'conpty');
-const NUGET_CONPTY = 'https://api.nuget.org/v3-flatcontainer/microsoft.windows.console.conpty/';
-const NugetVersions = z.object({ versions: z.array(z.string()) });
-const NugetLeaf = z.object({ catalogEntry: z.string().url() });
-const NugetCatalog = z.object({ packageHash: z.string(), packageHashAlgorithm: z.literal('SHA512') });
-/**
- * Microsoft's newer pseudo console (the Microsoft.Windows.Console.ConPTY package: conpty.dll and OpenConsole.exe, the
- * same one Windows Terminal and VS Code use), downloaded once and verified against the SHA-512 NuGet publishes. Agent
- * sessions use it instead of the one built into Windows, which re-renders the screen and garbles it after resizes.
- */
-export const ensureConpty = async (dataPath, refresh) => {
-    const dir = conptyDir(dataPath);
-    assertTestWritable(dir);
-    assertNoLinks(dataPath, dir);
-    if (fileExists(path.join(dir, 'conpty.dll')) && fileExists(path.join(dir, 'OpenConsole.exe')) && !refresh)
-        return 'cached';
-    const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
-    const work = stagingFolder(dir);
-    try {
-        const version = NugetVersions.parse(await fetchJson(NUGET_CONPTY + 'index.json')).versions.filter((v) => !v.includes('-')).pop();
-        if (!version)
-            throw new Error('no release found');
-        const leaf = NugetLeaf.parse(await fetchJson('https://api.nuget.org/v3/registration5-gz-semver2/microsoft.windows.console.conpty/' + version + '.json'));
-        const sha512 = Buffer.from(NugetCatalog.parse(await fetchJson(leaf.catalogEntry)).packageHash, 'base64').toString('hex');
-        const pkg = path.join(work, 'conpty.nupkg');
-        await download(NUGET_CONPTY + version + '/microsoft.windows.console.conpty.' + version + '.nupkg', pkg, { sha512 });
-        const files = { 'conpty.dll': 'runtimes/win-' + arch + '/native/conpty.dll', 'OpenConsole.exe': 'build/native/runtimes/' + arch + '/OpenConsole.exe' };
-        await extractArchive(pkg, path.join(work, 'x'), Object.values(files));
-        fs.mkdirSync(path.join(work, 'out'));
-        for (const [name, member] of Object.entries(files))
-            fs.copyFileSync(path.join(work, 'x', ...member.split('/')), path.join(work, 'out', name));
-        fs.writeFileSync(path.join(work, 'out', 'VERSION'), version);
-        moveIntoPlace(path.join(work, 'out'), dir);
-        return 'downloaded ' + version;
-    }
-    catch (e) {
-        return 'not downloaded, sessions use Windows\' own pseudo console (' + errMsg(e) + ')';
-    }
-    finally {
-        safeRemove(work, path.dirname(work));
-    }
-};
-const installTerminal = async (dataPath, refresh) => {
-    const exe = terminalExe(dataPath);
-    const dir = terminalDir(dataPath);
-    assertTestWritable(dir);
-    const settings = path.join(dir, 'settings');
-    // installArchive replaces tools\terminal: the portable settings folder waits here meanwhile (and goes back also when
-    // the download fails). One still parked from an interrupted earlier run is the one to keep.
-    const parked = path.join(dataPath, 'tools', 'terminal-settings.parked');
-    assertNoLinks(dataPath, settings);
-    assertNoLinks(dataPath, parked);
-    if (fileExists(exe) && !refresh)
-        return { exe, message: 'cached' };
-    try {
-        if (fs.existsSync(settings)) {
-            safeRemove(parked, path.dirname(parked));
-            fs.renameSync(settings, parked);
-        }
-        try {
-            const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
-            const asset = await githubAsset('microsoft/terminal', new RegExp('^Microsoft\\.WindowsTerminal_[\\d.]+_' + arch + '\\.zip$'));
-            await installArchive(asset.url, dir, { sha256: asset.sha256, locate: 'WindowsTerminal.exe', fileName: asset.name });
-            fs.writeFileSync(path.join(dir, '.portable'), '');
-            return { exe, message: 'downloaded ' + asset.name };
-        }
-        finally {
-            if (fs.existsSync(parked)) {
-                fs.mkdirSync(dir, { recursive: true });
-                safeRemove(settings, path.dirname(settings));
-                fs.renameSync(parked, settings);
-            }
-            const settingsFile = path.join(settings, 'settings.json');
-            assertNoLinks(dataPath, settingsFile);
-            if (fileExists(path.join(dir, '.portable')) && !fs.existsSync(settingsFile))
-                writeJson(settingsFile, SETTINGS);
-        }
-    }
-    catch (e) {
-        return { exe: null, message: 'download failed, the sandbox will use a plain PowerShell window (' + errMsg(e) + ')' };
-    }
-};

package/dist/host/window.d.ts

@@ -1,4 +0,0 @@
-/** Waits for the sandbox window and hides it; keeps watching briefly in case Windows re-shows it while connecting. */
-export declare const hideSandboxWindow: (storageRoot: string, waitSeconds?: number) => Promise<boolean>;
-/** Shows the sandbox window again (the ones we hid, or any hidden Windows Sandbox window). */
-export declare const showSandboxWindow: (storageRoot: string) => boolean;

package/dist/host/window.js

@@ -1,72 +0,0 @@
-// 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';
-const PRELUDE = `
-$ErrorActionPreference = 'Stop'
-Add-Type -Namespace AgentSandbox -Name Win -MemberDefinition @'
-public delegate bool EnumProc(System.IntPtr hWnd, System.IntPtr lParam);
-[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern bool EnumWindows(EnumProc cb, System.IntPtr lParam);
-[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(System.IntPtr hWnd, out uint pid);
-[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern bool IsWindowVisible(System.IntPtr hWnd);
-[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern bool IsWindow(System.IntPtr hWnd);
-[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern System.IntPtr GetWindow(System.IntPtr hWnd, uint cmd);
-[System.Runtime.InteropServices.DllImport("user32.dll", CharSet = System.Runtime.InteropServices.CharSet.Unicode)] public static extern int GetWindowText(System.IntPtr hWnd, System.Text.StringBuilder s, int n);
-[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern bool ShowWindow(System.IntPtr hWnd, int cmd);
-[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern bool SetForegroundWindow(System.IntPtr hWnd);
-'@
-function Get-SandboxWindows([bool]$visibleOnly) {
-  $pids = @(Get-Process | Where-Object { $_.ProcessName -like 'WindowsSandbox*' } | ForEach-Object { [uint32]$_.Id })
-  $found = New-Object System.Collections.ArrayList
-  if ($pids.Count -eq 0) { return $found }
-  $cb = [AgentSandbox.Win+EnumProc]{ param($h, $l)
-    $p = [uint32]0; [void][AgentSandbox.Win]::GetWindowThreadProcessId($h, [ref]$p)
-    if ($pids -contains $p -and [AgentSandbox.Win]::GetWindow($h, 4) -eq [IntPtr]::Zero) {
-      $sb = New-Object System.Text.StringBuilder 256; [void][AgentSandbox.Win]::GetWindowText($h, $sb, 256)
-      $title = $sb.ToString()
-      if ($title -like '*Sandbox*' -and (-not $visibleOnly -or [AgentSandbox.Win]::IsWindowVisible($h))) { [void]$found.Add([int64]$h) }
-    }
-    return $true }
-  [void][AgentSandbox.Win]::EnumWindows($cb, [IntPtr]::Zero)
-  return $found
-}
-`;
-const stateFile = (storageRoot) => path.join(storageRoot, 'run', 'hidden-windows.json');
-/** Waits for the sandbox window and hides it; keeps watching briefly in case Windows re-shows it while connecting. */
-export const hideSandboxWindow = async (storageRoot, waitSeconds = 180) => {
-    refuseInSelfTest('hide windows');
-    if (!isWin)
-        return false;
-    const script = PRELUDE + `
-$hidden = New-Object System.Collections.ArrayList
-$deadline = (Get-Date).AddSeconds(${waitSeconds}); $settle = $null
-while ((Get-Date) -lt $deadline) {
-  foreach ($h in (Get-SandboxWindows $true)) { [void][AgentSandbox.Win]::ShowWindow([IntPtr]$h, 0); if (-not $hidden.Contains($h)) { [void]$hidden.Add($h) } }
-  if ($hidden.Count -gt 0 -and $null -eq $settle) { $settle = (Get-Date).AddSeconds(15) }
-  if ($null -ne $settle -and (Get-Date) -gt $settle) { break }
-  Start-Sleep -Milliseconds 200
-}
-ConvertTo-Json -Compress @($hidden)`;
-    const stdout = await runPowerShellAsync(script);
-    const handles = JSON.parse(stdout.trim() || '[]').filter((h) => Number.isSafeInteger(h));
-    writeJsonAtomic(stateFile(storageRoot), { handles });
-    return handles.length > 0;
-};
-/** Shows the sandbox window again (the ones we hid, or any hidden Windows Sandbox window). */
-export const showSandboxWindow = (storageRoot) => {
-    refuseInSelfTest('show windows');
-    if (!isWin)
-        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 + `
-$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) }
-@($handles).Count`;
-    const { stdout } = runPowerShell(script, true);
-    writeJsonAtomic(stateFile(storageRoot), { handles: [] });
-    return Number(stdout.trim()) > 0;
-};

package/dist/host/wsb.d.ts

@@ -1,37 +0,0 @@
-/** Where wsb.exe can be: the Store app's alias, then System32 (never by bare name; cwd is often the workspace). */
-export declare const wsbCandidates: (env?: NodeJS.ProcessEnv) => string[];
-export declare const findWsb: (env?: NodeJS.ProcessEnv, exists?: (p: string) => boolean) => string | null;
-/** The version from `wsb --version` ("0.1.32.0", "wsb 1.2.3+abc"). */
-export declare const parseVersion: (out: string) => string | null;
-/** Subcommand names from `wsb --help` (the lines under "Commands:"). */
-export declare const parseCommands: (help: string) => string[];
-export interface WsbSandbox {
-    id: string;
-    status: string;
-}
-/** `wsb list --raw` (JSON: an array, or an object holding one) or the plain table: the sandboxes and their status. */
-export declare const parseList: (out: string) => WsbSandbox[];
-/** `wsb ip --id <id>`: the first IPv4 address in the output. */
-export declare const parseIp: (out: string) => string | null;
-export interface WsbResult {
-    ok: boolean;
-    stdout: string;
-    stderr: string;
-    error?: string;
-}
-export interface Wsb {
-    exe: string;
-    version: string | null;
-    commands: string[];
-    has: (command: string) => boolean;
-}
-/** The CLI and what it offers, or null on Windows versions without it. */
-export declare const detectWsb: (env?: NodeJS.ProcessEnv) => Wsb | null;
-/** The running sandbox's id: the only running one (with several, none is guessed). */
-export declare const runningSandboxId: (wsb: Wsb) => {
-    id: string | null;
-    error?: string;
-};
-/** Shares a folder of this PC into the running sandbox at `sandboxPath` (read/write unless readOnly). */
-export declare const shareFolder: (wsb: Wsb, id: string, hostPath: string, sandboxPath: string, readOnly?: boolean) => WsbResult;
-export declare const sandboxIp: (wsb: Wsb, id: string) => string | null;

package/dist/host/wsb.js

@@ -1,101 +0,0 @@
-// The Windows Sandbox command line (wsb.exe), Windows 11 24H2+ with the updated Windows Sandbox. Used only where it
-// adds something the .wsb file cannot: `wsb share` puts a folder into the RUNNING sandbox. Launching always stays on
-// the .wsb path, which works on every Windows version. UNTESTED: the machines this was built on predate the CLI, so
-// every call is checked and any failure falls back (the caller offers a restart instead), with the error shown.
-// Syntax from Microsoft's docs (learn.microsoft.com, "Windows Sandbox command line"):
-//   wsb start [--id <id>] [-c|--config <xml>]   wsb list [--raw]   wsb ip --id <id>   wsb stop --id <id>
-//   wsb share --id <id> -f|--host-path <host> -s|--sandbox-path <sandbox> [-w|--allow-write]
-//   wsb exec --id <id> -c <command> -r System|ExistingLogin [-d <dir>]   wsb connect --id <id>   --raw = JSON output
-import fs from 'node:fs';
-import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-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). */
-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;
-// ---- 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;
-/** Subcommand names from `wsb --help` (the lines under "Commands:"). */
-export const parseCommands = (help) => {
-    const lines = help.split(/\r?\n/);
-    const start = lines.findIndex((l) => /^\s*commands:\s*$/i.test(l));
-    if (start < 0)
-        return [];
-    const names = [];
-    for (const line of lines.slice(start + 1)) {
-        if (/^\S/.test(line) && line.trim())
-            break;
-        const m = /^\s{1,8}([a-z][a-z-]*)\b/.exec(line);
-        if (m)
-            names.push(m[1].toLowerCase());
-    }
-    return names;
-};
-/** `wsb list --raw` (JSON: an array, or an object holding one) or the plain table: the sandboxes and their status. */
-export const parseList = (out) => {
-    const fromObject = (o) => {
-        if (!o || typeof o !== 'object')
-            return null;
-        const entries = Object.entries(o);
-        const id = entries.find(([k, v]) => /^id$/i.test(k) && typeof v === 'string' && GUID.test(v))?.[1];
-        const status = entries.find(([k]) => /^(status|state)$/i.test(k))?.[1];
-        return id ? { id: GUID.exec(id)[0], status: typeof status === 'string' ? status : 'unknown' } : null;
-    };
-    try {
-        const parsed = JSON.parse(out);
-        const list = Array.isArray(parsed) ? parsed : Object.values(parsed).find(Array.isArray) ?? [parsed];
-        return list.map(fromObject).filter((s) => s !== null);
-    }
-    catch { /* the table */ }
-    return out.split(/\r?\n/).flatMap((line) => {
-        const id = GUID.exec(line)?.[0];
-        if (!id)
-            return [];
-        return [{ id, status: /\brunning\b/i.test(line) ? 'Running' : /\bstopped\b/i.test(line) ? 'Stopped' : 'unknown' }];
-    });
-};
-/** `wsb ip --id <id>`: the first IPv4 address in the output. */
-export const parseIp = (out) => /\b(?:\d{1,3}\.){3}\d{1,3}\b/.exec(out)?.[0] ?? null;
-const call = (exe, args, timeoutMs = 60000) => {
-    const r = spawnSync(exe, args, { encoding: 'utf8', windowsHide: true, timeout: timeoutMs, maxBuffer: MAX_OUTPUT });
-    const stdout = String(r.stdout ?? '').slice(0, MAX_OUTPUT);
-    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 }) };
-};
-/** The CLI and what it offers, or null on Windows versions without it. */
-export const detectWsb = (env = process.env) => {
-    const exe = findWsb(env);
-    if (!exe)
-        return null;
-    const version = parseVersion(call(exe, ['--version'], 15000).stdout);
-    const help = call(exe, ['--help'], 15000);
-    const commands = parseCommands(help.stdout + '\n' + help.stderr);
-    // An unreadable help text is not proof of anything: assume the documented commands.
-    const known = commands.length ? commands : ['start', 'list', 'exec', 'stop', 'share', 'connect', 'ip'];
-    return { exe, version, commands: known, has: (c) => known.includes(c) };
-};
-/** The running sandbox's id: the only running one (with several, none is guessed). */
-export const runningSandboxId = (wsb) => {
-    const listed = call(wsb.exe, ['list', '--raw'], 20000);
-    const all = parseList(listed.ok ? listed.stdout : call(wsb.exe, ['list'], 20000).stdout);
-    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)' };
-};
-/** 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'])]);
-};
-export const sandboxIp = (wsb, id) => (GUID.test(id) ? parseIp(call(wsb.exe, ['ip', '--id', id], 15000).stdout) : null);