windows-development-sandbox 1.10.0 → 1.11.3

package/dist/guest/toolchains/languages/node.js

@@ -129,6 +129,15 @@ const activate = async (version) => {
     fs.rmSync(NVM_SYMLINK, { recursive: true, force: true });
     fs.symlinkSync(path.join(NVM_HOME, 'v' + version), NVM_SYMLINK, 'junction');
 };
+/**
+ * Playwright works in every sandbox without setup: the browsers `npx playwright install` downloads go in the tools
+ * folder, so they last between sandboxes, and its MCP server (and `channel: 'msedge'` in tests) uses Edge, the one
+ * browser Windows Sandbox always has (Chrome is not there).
+ */
+const PLAYWRIGHT_VARS = () => ({
+    PLAYWRIGHT_BROWSERS_PATH: tool('ms-playwright'),
+    PLAYWRIGHT_MCP_BROWSER: 'msedge',
+});
 export async function setupNode(env, versions, config) {
     if (dryRun) {
         log('(dry run) would provision nvm and Node ' + versions.node.spec + ' (from ' + versions.node.source + ')');
@@ -162,7 +171,7 @@ export async function setupNode(env, versions, config) {
             warn('Node ' + version + ' from this PC: ' + errMsg(e));
         }
     }
-    Object.assign(env.vars, { NVM_HOME, NVM_SYMLINK });
+    Object.assign(env.vars, { NVM_HOME, NVM_SYMLINK, ...PLAYWRIGHT_VARS() });
     // At boot, nvm's symlink selects the version. A project added later must not switch it under the sessions already
     // running: its own version's folder goes first on its sessions' PATH instead.
     if (duringSession())
@@ -172,6 +181,7 @@ export async function setupNode(env, versions, config) {
         env.prepend.push(NVM_HOME, NVM_SYMLINK);
     }
     env.summary.push('node: ' + main + ' (from ' + versions.node.source + ', switch with nvm use)');
+    env.summary.push("playwright: ready (Edge; browsers it downloads are kept; in tests use channel: 'msedge')");
     await packageManagers(env, config, main);
 }
 /** Global npm packages (per Node version, like nvm keeps them) and pnpm/yarn through corepack. */

package/dist/guest/toolchains/native/rust-extras.js

@@ -7,7 +7,7 @@ import { execOutput } from '../../runtime/process.js';
 import { ensureCompiled } from '../../runtime/csc.js';
 import { arch, tool } from '../tool-env.js';
 import { wanted } from '../detect.js';
-import { cargoJobs } from '../../../shared/memory/index.js';
+import { cargoJobs, linkSlotsFor } from '../../../shared/memory/index.js';
 /**
  * Where cargo builds: shared with the PC's target\, one on the sandbox's disk, or a path. "separate" sets no variable:
  * the cargo shim (sandbox/csharp/CargoShim.cs) gives every checkout its own target\sandbox, so git worktrees of several
@@ -41,7 +41,7 @@ export function linkGate(env, rust, host) {
     const gate = path.join(mkdirp(tool('shims')), 'linkgate.exe');
     fs.copyFileSync(ensureCompiled('linkgate'), gate);
     const memoryGb = os.totalmem() / 1024 ** 3;
-    const slots = rust.linkSlots === 'auto' ? Math.max(2, Math.min(4, Math.floor(memoryGb / 8))) : rust.linkSlots;
+    const slots = rust.linkSlots === 'auto' ? linkSlotsFor(memoryGb) : rust.linkSlots;
     env.vars.AGENT_LINK_SLOTS = String(slots);
     env.vars.AGENT_REAL_LINKER = gcc;
     env.vars.CARGO_TARGET_X86_64_PC_WINDOWS_GNU_LINKER = gate;

package/dist/guest/toolchains/tools/cli.d.ts

@@ -3,6 +3,14 @@ import { type CliSettings } from '../catalogue.js';
 import { type ToolEnv } from '../tool-env.js';
 /** gh keeps `gh auth login` here, under the agent state (persists like Claude's login; never copied from the PC). */
 export declare function ghConfigDir(): string;
+/**
+ * gh's folder for the token the host handed over (github.shareToken): on the sandbox's own disk, so it is gone with the
+ * sandbox and never reaches the persistent state other sandboxes and projects share. The boot creates it only when a
+ * token arrived; while it exists, every gh setup (later projects too) points GH_CONFIG_DIR at it.
+ */
+export declare function deliveredGhConfigDir(): string;
+/** gh.exe where the catalogue installs it. */
+export declare function ghExePath(): string;
 /**
  * Installs the tools toolchains.cli asks for. Settings still "auto" here (normally the host decides) use the same
  * rules on the workspace as the host would. The gh rule is enforced here again, whatever the host sent.

package/dist/guest/toolchains/tools/cli.js

@@ -2,7 +2,7 @@
 // `openssl` shim onto the copy Git for Windows already ships.
 import fs from 'node:fs';
 import path from 'node:path';
-import { dryRun } from '../../runtime/paths.js';
+import { dryRun, localDir } from '../../runtime/paths.js';
 import { exists, mkdirp } from '../../runtime/fs.js';
 import { log, warn } from '../../runtime/log.js';
 import { stateDir } from '../../runtime/session.js';
@@ -16,9 +16,23 @@ import { ensureCompiled } from '../../runtime/csc.js';
 export function ghConfigDir() {
     return path.join(stateDir, 'gh');
 }
+/**
+ * gh's folder for the token the host handed over (github.shareToken): on the sandbox's own disk, so it is gone with the
+ * sandbox and never reaches the persistent state other sandboxes and projects share. The boot creates it only when a
+ * token arrived; while it exists, every gh setup (later projects too) points GH_CONFIG_DIR at it.
+ */
+export function deliveredGhConfigDir() {
+    return path.join(localDir, 'gh-token');
+}
+/** gh.exe where the catalogue installs it. */
+export function ghExePath() {
+    const entry = CLI_TOOLS.find((t) => t.name === 'gh');
+    const dir = tool('cli', 'gh');
+    return path.join(entry?.subdir ? path.join(dir, entry.subdir) : dir, entry?.exe ?? 'gh.exe');
+}
 const toolVars = {
     gh: () => ({
-        GH_CONFIG_DIR: mkdirp(ghConfigDir()),
+        GH_CONFIG_DIR: exists(deliveredGhConfigDir()) ? deliveredGhConfigDir() : mkdirp(ghConfigDir()),
         GH_NO_UPDATE_NOTIFIER: '1',
         GH_NO_EXTENSION_UPDATE_NOTIFIER: '1',
     }),

package/dist/guest/vpn/openvpn.d.ts

@@ -5,5 +5,10 @@ export declare function openvpnDownload(arch?: string): {
     sha256: string;
     url: string;
 };
+/**
+ * Windows Sandbox cannot answer WMI questions about services (a class whose provider is missing), and installers that
+ * ask (OpenVPN's MSI does) fail with 1603: the dead class is removed first (repair-wmi-services.ps1). Never throws.
+ */
+export declare function repairServiceQueries(): void;
 /** Installs OpenVPN unless it is there; returns the path of openvpn.exe. Throws with the reason when it cannot. */
 export declare function ensureOpenVpn(): Promise<string>;

package/dist/guest/vpn/openvpn.js

@@ -8,7 +8,8 @@ import { downloader, spawnAsync } from '../../shared/download/index.js';
 import { SYSTEM } from '../../shared/system.js';
 import { dryRun, isWin, toolsDir } from '../runtime/paths.js';
 import { exists, mkdirp } from '../runtime/fs.js';
-import { log } from '../runtime/log.js';
+import { log, warn } from '../runtime/log.js';
+import { scriptOutput } from '../runtime/process.js';
 import { OPENVPN_MSI } from '../../shared/vpn/download.js';
 /** Where the MSI puts the program. */
 export function openvpnExe(env = process.env) {
@@ -18,6 +19,17 @@ export function openvpnDownload(arch = process.arch) {
     const entry = arch === 'arm64' ? OPENVPN_MSI.arm64 : OPENVPN_MSI.x64;
     return { ...entry, url: OPENVPN_MSI.base + entry.file };
 }
+/**
+ * Windows Sandbox cannot answer WMI questions about services (a class whose provider is missing), and installers that
+ * ask (OpenVPN's MSI does) fail with 1603: the dead class is removed first (repair-wmi-services.ps1). Never throws.
+ */
+export function repairServiceQueries() {
+    const did = scriptOutput('repair-wmi-services.ps1');
+    if (did === 'removed')
+        log('VPN: repaired the Windows service queries installers use (a Windows Sandbox gap).');
+    else if (did !== 'absent' && did !== 'kept')
+        warn('VPN: could not check the Windows service queries installers use.');
+}
 const hasHash = (file, sha256) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') === sha256;
 /** Installs OpenVPN unless it is there; returns the path of openvpn.exe. Throws with the reason when it cannot. */
 export async function ensureOpenVpn() {
@@ -33,6 +45,7 @@ export async function ensureOpenVpn() {
         log('VPN: downloading OpenVPN ' + OPENVPN_MSI.version + ' (about 6 MB)');
         await downloader.file(dl.url, msi, dl.sha256);
     }
+    repairServiceQueries();
     log('VPN: installing OpenVPN');
     const logFile = path.join(toolsDir, 'downloads', 'openvpn-install.log');
     const code = await spawnAsync(SYSTEM.msiexec(), ['/i', msi, '/qn', '/norestart', '/l*v', logFile], {

package/dist/guest/vpn/vpn.js

@@ -4,6 +4,7 @@
 // warns.
 import dns from 'node:dns';
 import fs from 'node:fs';
+import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 import { now } from '../../shared/channel/run-dir.js';
@@ -13,7 +14,7 @@ import { assertSafeWireguard, renderWireguard, routesEverything, wireguardEndpoi
 import { isIPv4 } from '../../shared/network/firewall-rules.js';
 import { killSwitchCommands, tunnelCommands } from '../../shared/vpn/kill-switch.js';
 import { errMsg } from '../../core/util/errors.js';
-import { run as netsh } from '../network/firewall.js';
+import { longPath, run as netsh } from '../network/firewall.js';
 import { dryRun, isWin, launchDir, run } from '../runtime/paths.js';
 import { log, warn } from '../runtime/log.js';
 import { session } from '../runtime/session.js';
@@ -74,6 +75,27 @@ async function publicAddress() {
     }
 }
 const hasAdapter = (ip) => Object.values(os.networkInterfaces()).some((list) => (list ?? []).some((i) => i.address === ip));
+/** Well-known public addresses a direct connection is tried to, to see that the kill switch holds. */
+const PROBE_TARGETS = ['1.1.1.1', '8.8.8.8', '9.9.9.9'];
+const PROBE_TIMEOUT_MS = 3000;
+function connects(ip, port) {
+    return new Promise((resolve) => {
+        const socket = net.connect({ host: ip, port });
+        const done = (ok) => {
+            socket.destroy();
+            resolve(ok);
+        };
+        socket.setTimeout(PROBE_TIMEOUT_MS, () => done(false));
+        socket.once('connect', () => done(true));
+        socket.once('error', () => done(false));
+    });
+}
+/** True when a direct connection out (before the tunnel exists) fails: the kill switch holds. */
+async function directConnectionBlocked(servers) {
+    const targets = PROBE_TARGETS.filter((ip) => !servers.some((s) => s.ip === ip));
+    const results = await Promise.all(targets.map((ip) => connects(ip, 443)));
+    return !results.some(Boolean);
+}
 /** The whole step. Returns true when the tunnel is up. */
 export async function setupVpn(secrets, ptyHostExe) {
     const vpn = session.vpn;
@@ -81,11 +103,24 @@ export async function setupVpn(secrets, ptyHostExe) {
         return true;
     const killSwitch = vpn.killSwitch;
     let blocked = false;
-    const block = (servers) => {
-        if (isWin && !dryRun)
-            netsh(killSwitchCommands(servers, ptyHostExe));
-        blocked = true;
-        log('VPN: kill switch on: nothing leaves the sandbox except through the tunnel.');
+    /** A direct connection was tried after the kill switch and failed: only then is the sandbox said to be offline. */
+    let held = false;
+    const block = async (servers) => {
+        if (!isWin || dryRun) {
+            blocked = held = true;
+            return;
+        }
+        try {
+            netsh(killSwitchCommands(servers, ptyHostExe ? longPath(ptyHostExe) : null));
+        }
+        finally {
+            blocked = true;
+            held = await directConnectionBlocked(servers);
+        }
+        if (held)
+            log('VPN: kill switch on: nothing leaves the sandbox except through the tunnel (checked).');
+        else
+            warn('VPN: the kill switch did not hold: a direct connection still got out. If the tunnel drops, traffic leaves through your normal connection.');
     };
     setVpnStatus('starting', 'Starting the VPN');
     try {
@@ -103,7 +138,7 @@ export async function setupVpn(secrets, ptyHostExe) {
             if (killSwitch && !routesEverything(config))
                 warn('VPN: AllowedIPs does not include 0.0.0.0/0: with the kill switch on, only the tunnel traffic can leave the sandbox.');
             if (killSwitch)
-                block(servers);
+                await block(servers);
             if (dryRun || !isWin) {
                 log('(dry run) would start the WireGuard tunnel ' + vpn.server);
                 setVpnStatus('off', 'dry run');
@@ -129,7 +164,7 @@ export async function setupVpn(secrets, ptyHostExe) {
             if (servers.length === 0)
                 throw new Error('the VPN server addresses could not be found');
             if (killSwitch)
-                block(servers);
+                await block(servers);
             if (dryRun || !isWin) {
                 log('(dry run) would start the VPN tunnel to ' + vpn.server);
                 setVpnStatus('off', 'dry run');
@@ -149,7 +184,10 @@ export async function setupVpn(secrets, ptyHostExe) {
             throw new Error('the tunnel reported it was up, but no network adapter with its address appeared');
         const publicIp = await publicAddress();
         log('VPN: up' + (publicIp ? ' (the sandbox appears as ' + publicIp + ')' : '') + '.');
-        setVpnStatus('up', 'The tunnel is up', publicIp ? { publicIp } : {});
+        setVpnStatus('up', 'The tunnel is up', {
+            ...(publicIp ? { publicIp } : {}),
+            ...(killSwitch ? { killSwitchHeld: held } : {}),
+        });
         return true;
     }
     catch (e) {
@@ -157,18 +195,19 @@ export async function setupVpn(secrets, ptyHostExe) {
         // Without the kill switch the sandbox keeps its normal connection: the rest of the boot goes on, with a warning.
         try {
             if (killSwitch && !blocked)
-                block([]);
+                await block([]);
         }
         catch (blockError) {
             warn('VPN: could not close the network after the failure: ' + errMsg(blockError));
         }
-        const text = 'VPN failed: ' +
-            reason +
-            (killSwitch
+        // "No internet" is said only when a direct connection was tried and failed.
+        const after = !killSwitch
+            ? ' The kill switch is off, so this sandbox is using your normal connection.'
+            : held
                 ? ' The kill switch is on, so this sandbox has NO internet access.'
-                : ' The kill switch is off, so this sandbox is using your normal connection.');
-        warn(text);
-        setVpnStatus('failed', reason);
+                : ' The kill switch could NOT close the network, so this sandbox is ONLINE through your normal connection, without the VPN.';
+        warn('VPN failed: ' + reason + after);
+        setVpnStatus('failed', reason, killSwitch ? { killSwitchHeld: held } : {});
         return false;
     }
 }

package/dist/guest/vpn/wireguard.js

@@ -14,6 +14,7 @@ import { handshakeDone, serviceRunning } from '../../shared/vpn/wireguard.js';
 import { dryRun, isWin, toolsDir } from '../runtime/paths.js';
 import { exists, mkdirp } from '../runtime/fs.js';
 import { log } from '../runtime/log.js';
+import { repairServiceQueries } from './openvpn.js';
 /** The tunnel's name: the config file is sandbox.conf and the Windows service WireGuardTunnel$sandbox. */
 export const WIREGUARD_TUNNEL = 'sandbox';
 export function wireguardDir(env = process.env) {
@@ -41,6 +42,7 @@ export async function ensureWireguard() {
         log('VPN: downloading WireGuard ' + WIREGUARD_MSI.version + ' (about 3 MB)');
         await downloader.file(dl.url, msi, dl.sha256);
     }
+    repairServiceQueries();
     log('VPN: installing WireGuard');
     const logFile = path.join(toolsDir, 'downloads', 'wireguard-install.log');
     // DO_NOT_LAUNCH: the installer would otherwise start the manager window.

package/dist/host/channel/attach.d.ts

@@ -18,4 +18,5 @@ export declare function findUnwatchedSession(dataPath: string, harness: string,
 /** Bridges this terminal to a session. Returns the agent's exit code, or 0 when the user detaches. */
 export declare function attachTerminal(session: SessionStatus, o?: {
     clipboardWrites?: boolean;
+    confirmCtrlC?: boolean;
 }): Promise<number>;

package/dist/host/channel/attach.js

@@ -74,6 +74,7 @@ export async function attachTerminal(session, o = {}) {
     const result = await runTerminalClient(socket, session.attach.token, {
         detachKey: DETACH_KEY,
         clipboardWrites: o.clipboardWrites,
+        confirmCtrlC: o.confirmCtrlC,
     });
     switch (result.reason) {
         case 'detach':

package/dist/host/channel/channel.d.ts

@@ -47,7 +47,7 @@ export declare class SandboxChannel {
     /** Restarts running sessions in place (they resume via the harness's resumeArguments, e.g. claude --continue). */
     restart(harness: string | null, cwd?: string): Promise<GuestResponse>;
     /** The PC is low on memory or CPU: the sandbox slows its builds down for `seconds`. Never waits for an answer. */
-    pressure(reason: string, seconds: number): void;
+    pressure(reason: string, seconds: number, level?: 'slow' | 'severe'): void;
     ping(): Promise<GuestResponse>;
     runningSessions(): SessionStatus[];
     /** Running sessions of the sandbox that is running now (its launch id), newest last, capped. */

package/dist/host/channel/channel.js

@@ -180,8 +180,8 @@ export class SandboxChannel {
         return this.waitForResponse(requestId, 30000);
     }
     /** The PC is low on memory or CPU: the sandbox slows its builds down for `seconds`. Never waits for an answer. */
-    pressure(reason, seconds) {
-        this.send({ kind: 'pressure', id: newId(), reason, seconds, createdAt: now() });
+    pressure(reason, seconds, level = 'slow') {
+        this.send({ kind: 'pressure', id: newId(), reason, seconds, level, createdAt: now() });
     }
     async ping() {
         const requestId = newId();

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

@@ -19,6 +19,7 @@ export interface HcsProbes {
     imageStores(): readonly ImageStore[];
 }
 export declare function checkHcs(p: HcsProbes): EngineCheck;
+export declare function system32Dir(): string;
 /** The groups of a token from `whoami /groups /fo csv /nh`: name, type, SID, attributes per line. */
 export declare function parseWhoamiGroups(csv: string): TokenGroups;
 /** The real probes: sc.exe query, whoami, file checks. They only read. */

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

@@ -45,7 +45,7 @@ export function checkHcs(p) {
         need('No Windows Server Core (ltsc2022) image is on this PC. ' + image.reason, 'Pull one with Docker Desktop (Windows containers mode): docker pull mcr.microsoft.com/windows/servercore:ltsc2022  - or put your own in a folder with an image.json and set AGENT_SANDBOX_HCS_IMAGE to it. This tool does not download images in this alpha.');
     return { available: reasons.length === 0, reasons, fixes };
 }
-function system32Dir() {
+export function system32Dir() {
     return path.dirname(system32('x'));
 }
 /** The groups of a token from `whoami /groups /fo csv /nh`: name, type, SID, attributes per line. */

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

@@ -32,7 +32,7 @@ export declare class HcsEngine implements SandboxEngine {
     private helper;
     start(plan: EnginePlan): Promise<RunningSandbox>;
     private tryTerminate;
-    /** Ours: the compute systems the helper lists with our owner name. */
+    /** Ours: the compute systems the helper lists with our owner name and this Windows user's id prefix. */
     private ours;
     running(): Promise<boolean>;
     stop(): Promise<void>;

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

@@ -9,7 +9,7 @@ import { fail, UserError } from '../../../core/util/index.js';
 import { selfTestRunning } from '../../test-guard.js';
 import { checkHcs, realHcsProbes } from './check.js';
 import { buildDocuments, HCS_OWNER } from './documents.js';
-import { HcsHelper, hcsHostExe } from './helper.js';
+import { HcsHelper, hcsHostExe, isMySystemId, userSystemPrefix } from './helper.js';
 import { findImage } from './images.js';
 export const HCS_CAPABILITIES = {
     desktop: false,
@@ -76,7 +76,7 @@ export class HcsEngine {
         const docs = buildDocuments({
             launch,
             image: this.image,
-            id: 'agent-sandbox-' + slug,
+            id: userSystemPrefix() + slug,
             scratchVhdx,
             hostCpus: (this.deps.hostCpus ?? (() => os.cpus().length))(),
         });
@@ -147,10 +147,12 @@ export class HcsEngine {
                 throw e; // a system that is already gone is fine
         }
     }
-    /** Ours: the compute systems the helper lists with our owner name. */
+    /** Ours: the compute systems the helper lists with our owner name and this Windows user's id prefix. */
     ours(helper) {
         const parsed = SystemListSchema.safeParse(JSON.parse(helper.enumerate().json || '[]'));
-        return parsed.success ? parsed.data.filter((s) => s.Owner === HCS_OWNER).map((s) => s.Id) : [];
+        return parsed.success
+            ? parsed.data.filter((s) => s.Owner === HCS_OWNER && isMySystemId(s.Id)).map((s) => s.Id)
+            : [];
     }
     running() {
         try {

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

@@ -1,4 +1,13 @@
 import { z } from 'zod';
+/** Whether an id has the shape of the ones this tool gives its compute systems. */
+export declare function isOurSystemId(id: string): boolean;
+/**
+ * The start of the ids this Windows user's sandboxes get: the Owner is the same for everyone, so on a PC shared with
+ * other users this tag is what keeps one user from listing or stopping another's compute systems.
+ */
+export declare function userSystemPrefix(user?: string, domain?: string): string;
+/** One of this tool's ids, given by this Windows user. */
+export declare function isMySystemId(id: string): boolean;
 export declare const HcsReplySchema: z.ZodObject<{
     ok: z.ZodBoolean;
     hresult: z.ZodString;
@@ -16,6 +25,8 @@ export type HelperRunner = (exe: string, args: readonly string[], timeoutMs: num
 export declare const spawnRunner: HelperRunner;
 /** Compiles the helper's sources to `exe` with the .NET Framework csc (C# 5). False when it cannot be built. */
 export declare function buildHcsHostTo(exe: string): boolean;
+/** HcsHost.exe when it was built already (never builds it): a PC that never used HCS has none. */
+export declare function builtHcsHostExe(storageRoot: string): string | null;
 /**
  * <storage>\bin\hcs\<hash of its sources>\HcsHost.exe, built the first time. Its own folder: HostTools' cleanup of old
  * builds only touches twelve-digit hash folders directly in bin. Null when it cannot be built.

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

@@ -15,6 +15,26 @@ const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
 const CALL_TIMEOUT_MS = 240000;
 /** Only ids this tool gives its compute systems (HcsHost.exe refuses any other, and checks the Owner too). */
 const SAFE_ID = /^agent-sandbox-[A-Za-z0-9._-]{1,100}$/;
+/** Whether an id has the shape of the ones this tool gives its compute systems. */
+export function isOurSystemId(id) {
+    return SAFE_ID.test(id);
+}
+/**
+ * The start of the ids this Windows user's sandboxes get: the Owner is the same for everyone, so on a PC shared with
+ * other users this tag is what keeps one user from listing or stopping another's compute systems.
+ */
+export function userSystemPrefix(user = os.userInfo().username, domain = process.env.USERDOMAIN ?? '') {
+    const tag = crypto
+        .createHash('sha256')
+        .update((domain + '\\' + user).toLowerCase())
+        .digest('hex')
+        .slice(0, 8);
+    return 'agent-sandbox-' + tag + '-';
+}
+/** One of this tool's ids, given by this Windows user. */
+export function isMySystemId(id) {
+    return isOurSystemId(id) && id.startsWith(userSystemPrefix());
+}
 export const HcsReplySchema = z.object({
     ok: z.boolean(),
     hresult: z.string().max(16),
@@ -51,12 +71,22 @@ export function buildHcsHostTo(exe) {
     const r = spawnSync(SYSTEM.csc(), ['/nologo', '/optimize', '/target:exe', '/r:System.Web.Extensions.dll', '/out:' + exe, ...sources], { windowsHide: true, timeout: 120000 });
     return r.status === 0 && fs.existsSync(exe);
 }
+/** HcsHost.exe when it was built already (never builds it): a PC that never used HCS has none. */
+export function builtHcsHostExe(storageRoot) {
+    const exe = hcsHostPath(storageRoot);
+    return exe && fs.existsSync(exe) ? exe : null;
+}
 /**
  * <storage>\bin\hcs\<hash of its sources>\HcsHost.exe, built the first time. Its own folder: HostTools' cleanup of old
  * builds only touches twelve-digit hash folders directly in bin. Null when it cannot be built.
  */
 export function hcsHostExe(storageRoot) {
     refuseInSelfTest('build HcsHost.exe');
+    const exe = hcsHostPath(storageRoot);
+    return exe && (fs.existsSync(exe) || buildHcsHostTo(exe)) ? exe : null;
+}
+/** Where HcsHost.exe is (or would be built): named by the hash of its sources. Null without the sources. */
+function hcsHostPath(storageRoot) {
     const dir = nativeFile('csharp', 'HcsHost');
     const hash = crypto.createHash('sha256');
     try {
@@ -69,8 +99,7 @@ export function hcsHostExe(storageRoot) {
     catch {
         return null; // no sources
     }
-    const exe = path.join(storageRoot, 'bin', 'hcs', hash.digest('hex').slice(0, 12), 'HcsHost.exe');
-    return fs.existsSync(exe) || buildHcsHostTo(exe) ? exe : null;
+    return path.join(storageRoot, 'bin', 'hcs', hash.digest('hex').slice(0, 12), 'HcsHost.exe');
 }
 /** A path argument: absolute, not an option. Nothing else reaches the helper's command line. */
 function pathArg(value, what) {

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

@@ -0,0 +1,42 @@
+import { type HcsProbes } from './check.js';
+import { HcsHelper } from './helper.js';
+export interface LeftoverSystem {
+    readonly id: string;
+    /** Container or VirtualMachine (the utility VM). */
+    readonly kind: string;
+    readonly state: string;
+    /** When it was created (ISO text), when HCS says. */
+    readonly since: string | null;
+}
+export type LeftoverLook = {
+    readonly available: true;
+    readonly systems: readonly LeftoverSystem[];
+} | {
+    readonly available: false;
+    readonly reason: string;
+};
+export interface LeftoverOutcome {
+    readonly id: string;
+    readonly stopped: boolean;
+    /** Why not, in plain words. */
+    readonly problem?: string;
+}
+/** What the look runs on: replaceable by tests (probes of a pretend PC, a fake helper). */
+export interface LeftoverDeps {
+    readonly probes: HcsProbes;
+    /** The helper, or null when HcsHost.exe was never built (then nothing of ours can be running). Never builds it. */
+    helper(storageRoot: string): HcsHelper | null;
+}
+export declare const LEFTOVER_DEPS: {
+    current: LeftoverDeps | null;
+};
+/**
+ * The compute systems of ours that exist now. Never builds HcsHost.exe: a PC that never used HCS has none, and
+ * nothing of ours can be running there.
+ */
+export declare function lookForLeftovers(storageRoot: string): LeftoverLook;
+/**
+ * Stops the named systems, containers before the utility VM that hosts them. Each id is looked up again first: one that
+ * is not one of ours (or is gone) never reaches the helper; the helper checks the Owner with HCS itself once more.
+ */
+export declare function stopLeftovers(storageRoot: string, ids: readonly string[]): LeftoverOutcome[];

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

@@ -0,0 +1,101 @@
+// HCS compute systems this tool left running (a crashed command: they are created to outlive their handle). Only
+// systems with our id prefix AND our Owner are ever listed or stopped; HcsHost.exe checks both again before it
+// terminates one. Nothing here runs unless the PC has the Host Compute Service.
+import path from 'node:path';
+import { z } from 'zod';
+import { errMsg, fail } from '../../../core/util/index.js';
+import { realHcsProbes, system32Dir } from './check.js';
+import { HCS_OWNER } from './documents.js';
+import { HcsHelper, builtHcsHostExe, isMySystemId } from './helper.js';
+export const LEFTOVER_DEPS = { current: null };
+function realDeps() {
+    return {
+        probes: realHcsProbes(),
+        helper: (root) => {
+            const exe = builtHcsHostExe(root);
+            return exe ? new HcsHelper(() => exe) : null;
+        },
+    };
+}
+const SystemListSchema = z.array(z
+    .object({
+    Id: z.string().max(300),
+    SystemType: z.string().max(100).optional(),
+    Owner: z.string().max(300).optional(),
+    State: z.string().max(100).optional(),
+    CreateTimestamp: z.string().max(100).optional(),
+})
+    .passthrough());
+/** The reason HCS cannot be there at all, or null. Looks only (service list, one file). */
+function noHcsReason(p) {
+    if (!p.isWindows())
+        return 'HCS only exists on Windows.';
+    if (!p.fileExists(path.join(system32Dir(), 'computecore.dll')) || p.serviceInstalled('vmcompute') === false)
+        return 'The Host Compute Service is not on this PC.';
+    return null;
+}
+/** Ours only: the id has our prefix and the system names us as its Owner. Anything else is never shown or touched. */
+function ownedSystems(helper) {
+    let list;
+    try {
+        list = JSON.parse(helper.enumerate().json || '[]');
+    }
+    catch (e) {
+        if (e instanceof SyntaxError)
+            return fail('The Host Compute Service answered with something that is not JSON.');
+        throw e;
+    }
+    const parsed = SystemListSchema.safeParse(list);
+    if (!parsed.success)
+        return [];
+    return parsed.data
+        .filter((s) => s.Owner === HCS_OWNER && isMySystemId(s.Id))
+        .map((s) => ({
+        id: s.Id,
+        kind: s.SystemType ?? 'unknown',
+        state: s.State ?? 'unknown',
+        since: s.CreateTimestamp && !Number.isNaN(Date.parse(s.CreateTimestamp)) ? s.CreateTimestamp : null,
+    }));
+}
+/**
+ * The compute systems of ours that exist now. Never builds HcsHost.exe: a PC that never used HCS has none, and
+ * nothing of ours can be running there.
+ */
+export function lookForLeftovers(storageRoot) {
+    const deps = LEFTOVER_DEPS.current ?? realDeps();
+    const none = noHcsReason(deps.probes);
+    if (none)
+        return { available: false, reason: none };
+    try {
+        const helper = deps.helper(storageRoot);
+        if (!helper)
+            return { available: true, systems: [] };
+        return { available: true, systems: ownedSystems(helper) };
+    }
+    catch (e) {
+        return { available: false, reason: 'The Host Compute Service could not be asked: ' + errMsg(e) };
+    }
+}
+/**
+ * Stops the named systems, containers before the utility VM that hosts them. Each id is looked up again first: one that
+ * is not one of ours (or is gone) never reaches the helper; the helper checks the Owner with HCS itself once more.
+ */
+export function stopLeftovers(storageRoot, ids) {
+    const deps = LEFTOVER_DEPS.current ?? realDeps();
+    const helper = deps.helper(storageRoot);
+    if (!helper)
+        return ids.map((id) => ({ id, stopped: false, problem: 'HcsHost.exe is not available.' }));
+    const now = ownedSystems(helper);
+    const wanted = [...ids].sort((a, b) => Number(b.endsWith('-c')) - Number(a.endsWith('-c')));
+    return wanted.map((id) => {
+        if (!now.some((s) => s.id === id))
+            return { id, stopped: false, problem: 'it is gone, or it is not one of ours' };
+        try {
+            helper.terminate(id);
+            return { id, stopped: true };
+        }
+        catch (e) {
+            return { id, stopped: false, problem: errMsg(e) };
+        }
+    });
+}

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

@@ -5,3 +5,4 @@ export { WindowsSandboxEngine } from './windows-sandbox/engine.js';
 export { wsbText } from './windows-sandbox/wsb-text.js';
 export { HcsEngine, HCS_CAPABILITIES, hcsStartEnabled } from './hcs/engine.js';
 export { checkHcs, realHcsProbes, type HcsProbes } from './hcs/check.js';
+export { lookForLeftovers, stopLeftovers, LEFTOVER_DEPS, type LeftoverDeps, type LeftoverLook, type LeftoverOutcome, type LeftoverSystem, } from './hcs/leftovers.js';

package/dist/host/engines/index.js

@@ -3,3 +3,4 @@ export { WindowsSandboxEngine } from './windows-sandbox/engine.js';
 export { wsbText } from './windows-sandbox/wsb-text.js';
 export { HcsEngine, HCS_CAPABILITIES, hcsStartEnabled } from './hcs/engine.js';
 export { checkHcs, realHcsProbes } from './hcs/check.js';
+export { lookForLeftovers, stopLeftovers, LEFTOVER_DEPS, } from './hcs/leftovers.js';