windows-development-sandbox 1.9.0 → 1.11.3

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';

package/dist/host/github/deliver.d.ts

@@ -0,0 +1,13 @@
+import type { BootWant } from '../../core/local-config/index.js';
+import type { Config } from '../../core/types.js';
+import { GithubToken } from './token.js';
+/** github.shareToken is on and git access is "full" for every project this sandbox boots with. */
+export declare function githubTokenAllowed(config: Config, others?: readonly BootWant[]): boolean;
+export interface GithubDelivery {
+    /** The token for the one-shot secrets file, when it is handed over. */
+    readonly token?: string;
+    /** What to tell you about it (never the token). */
+    readonly notes: readonly string[];
+}
+/** What this launch hands over. Never throws: a token that cannot be read is a note, and the launch goes on. */
+export declare function prepareGithubToken(config: Config, storageRoot: string, store?: GithubToken, others?: readonly BootWant[]): GithubDelivery;

package/dist/host/github/deliver.js

@@ -0,0 +1,51 @@
+import { GithubToken } from './token.js';
+/** The first project (the launch's own, then the others at boot) whose git access is not "full", or null. */
+function stricterProject(config, others) {
+    if (config.provisioning.git.access !== 'full')
+        return { name: '', access: config.provisioning.git.access };
+    const other = others.find((o) => o.config.provisioning.git.access !== 'full');
+    return other ? { name: other.name, access: other.config.provisioning.git.access } : null;
+}
+/** github.shareToken is on and git access is "full" for every project this sandbox boots with. */
+export function githubTokenAllowed(config, others = []) {
+    return config.github.shareToken && stricterProject(config, others) === null;
+}
+/** What this launch hands over. Never throws: a token that cannot be read is a note, and the launch goes on. */
+export function prepareGithubToken(config, storageRoot, store, others = []) {
+    if (!config.github.shareToken)
+        return { notes: [] };
+    const stricter = stricterProject(config, others);
+    if (stricter)
+        return {
+            notes: [
+                'github.shareToken is on, but git access is "' +
+                    stricter.access +
+                    '"' +
+                    (stricter.name ? ' for ' + stricter.name + ' (also in this sandbox)' : ' in this sandbox') +
+                    ', so your GitHub token was not handed over (it needs provisioning.git.access "full").',
+            ],
+        };
+    const tokens = store ?? new GithubToken(storageRoot);
+    let token;
+    try {
+        token = tokens.read();
+    }
+    catch {
+        // The reason may come from DPAPI or a damaged file; a fixed text is enough (and can never hold the token).
+        return {
+            notes: [
+                'Your saved GitHub token could not be read (only the Windows user that saved it can), so it was not handed over. Save it again: sandbox github login',
+            ],
+        };
+    }
+    if (!token)
+        return {
+            notes: ['github.shareToken is on, but no GitHub token is saved. Save one: sandbox github login'],
+        };
+    return {
+        token,
+        notes: [
+            'Your GitHub token is handed to this sandbox (github.shareToken): the agent can read it and use it for whatever it allows.',
+        ],
+    };
+}

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

@@ -0,0 +1,2 @@
+export { GithubToken, checkGithubToken, type TokenState } from './token.js';
+export { githubTokenAllowed, prepareGithubToken, type GithubDelivery } from './deliver.js';

package/dist/host/github/index.js

@@ -0,0 +1,3 @@
+// The GitHub token for sandboxes: its encrypted store and whether a launch hands it over.
+export { GithubToken, checkGithubToken } from './token.js';
+export { githubTokenAllowed, prepareGithubToken } from './deliver.js';

package/dist/host/github/token.d.ts

@@ -0,0 +1,21 @@
+import { type GithubTokenKind } from '../../shared/github/index.js';
+import { SecretStore } from '../secrets/index.js';
+/** What the status may say about the token: never its value. */
+export type TokenState = 'none' | 'saved' | 'unreadable';
+/** The token's kind, or a refusal that says what to do (the message never holds what was typed). */
+export declare function checkGithubToken(token: string): GithubTokenKind;
+export declare class GithubToken {
+    private readonly storageRoot;
+    private readonly secrets;
+    constructor(storageRoot: string, secrets?: SecretStore);
+    private file;
+    /** Checks, encrypts and saves the token (replacing an earlier one). Returns its kind. */
+    save(token: string): GithubTokenKind;
+    /** The token, decrypted. Only the launch calls this; throws when this Windows user cannot open it. */
+    read(): string | null;
+    /** Whether a token is saved and can be decrypted by this Windows user (the value is never returned). */
+    state(): TokenState;
+    savedAt(): string | null;
+    kind(): GithubTokenKind | null;
+    remove(): boolean;
+}

package/dist/host/github/token.js

@@ -0,0 +1,74 @@
+// The GitHub token you saved for sandboxes (github.shareToken), kept encrypted with Windows DPAPI in host-only storage
+// (<storage>\github\token.json). It is read only when a sandbox starts, to hand to the sandbox in a one-shot file, and
+// is never printed, logged or returned to a surface: they only learn its state, kind and when it was saved.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { JsonFile } from '../../shared/io/index.js';
+import { GITHUB_TOKEN_KINDS, GithubTokenSchema, githubTokenKind, githubTokenProblem, } from '../../shared/github/index.js';
+import { fail } from '../../core/util/index.js';
+import { SecretStore } from '../secrets/index.js';
+const SavedSchema = z.object({
+    savedAt: z.string().max(64),
+    kind: z.enum(GITHUB_TOKEN_KINDS),
+    sealed: z.string().max(10000),
+});
+/** The token's kind, or a refusal that says what to do (the message never holds what was typed). */
+export function checkGithubToken(token) {
+    const problem = githubTokenProblem(token);
+    if (problem)
+        fail(problem.message, problem.fix);
+    return githubTokenKind(token) ?? fail('That is not a GitHub personal access token.', 'Run: sandbox github login');
+}
+export class GithubToken {
+    storageRoot;
+    secrets;
+    constructor(storageRoot, secrets = SecretStore.standard()) {
+        this.storageRoot = storageRoot;
+        this.secrets = secrets;
+    }
+    file() {
+        return new JsonFile(SavedSchema, path.join(this.storageRoot, 'github', 'token.json'));
+    }
+    /** Checks, encrypts and saves the token (replacing an earlier one). Returns its kind. */
+    save(token) {
+        const kind = checkGithubToken(token);
+        this.file().write({ savedAt: new Date().toISOString(), kind, sealed: this.secrets.sealJson({ token }) });
+        return kind;
+    }
+    /** The token, decrypted. Only the launch calls this; throws when this Windows user cannot open it. */
+    read() {
+        const saved = this.file().read();
+        if (!saved)
+            return null;
+        const value = this.secrets.openJson(saved.sealed);
+        const token = GithubTokenSchema.safeParse(value?.token);
+        if (!token.success)
+            fail('The saved GitHub token is damaged.', 'Save it again with: sandbox github login');
+        return token.data;
+    }
+    /** Whether a token is saved and can be decrypted by this Windows user (the value is never returned). */
+    state() {
+        if (!this.file().read())
+            return 'none';
+        try {
+            return this.read() ? 'saved' : 'none';
+        }
+        catch {
+            return 'unreadable';
+        }
+    }
+    savedAt() {
+        return this.file().read()?.savedAt ?? null;
+    }
+    kind() {
+        return this.file().read()?.kind ?? null;
+    }
+    remove() {
+        const file = this.file().file;
+        if (!fs.existsSync(file))
+            return false;
+        fs.rmSync(file, { force: true });
+        return true;
+    }
+}

package/dist/host/launch/generate.js

@@ -9,6 +9,7 @@ import { dirExists, ensureDir, fail, writeJson } from '../../core/util/index.js'
 import { engineFor } from '../engines/index.js';
 import { capturePersonalization, stageClaudeProfile } from '../profile/index.js';
 import { clearSecrets, writeSecrets } from '../secrets/index.js';
+import { githubTokenAllowed } from '../github/index.js';
 import { folderAttachment } from '../storage/providers/index.js';
 import { assertTestWritable } from '../test-guard.js';
 import { writeLoadSettings } from '../life/watchdog.js';
@@ -20,7 +21,7 @@ import { guestSession, logonEnv } from './session-file.js';
 import { copyRuntime, stageGitIdentity, stageHooks } from './stage.js';
 import { decideProjectToolchains } from './toolchains.js';
 import { buildLaunchPlan } from './launch-plan.js';
-import { decideMemory, GUEST, memoryNote, resolveMemoryMb } from './wsb-file.js';
+import { cappedMemoryMb, decideMemory, GUEST, memoryNote, residentNote, resolveMemoryMb } from './wsb-file.js';
 const NO_PROFILE = { hostDir: null, staged: [], skipped: [], credentials: false, secretsRemoved: [] };
 /** Moves the staged copy of this PC's Claude login out of the launch folder; its text goes in the one-shot file. */
 function takeStagedCredentials(launchPath) {
@@ -59,7 +60,9 @@ opened) {
     assertTestWritable(dataPath);
     // Checked before anything is written, so a refusal leaves nothing behind.
     const commitAvailableMb = o.commitAvailableMb ?? null;
-    const memoryMb = Math.max(resolveMemoryMb(config.sandbox, o.freeMemoryBytes, undefined, commitAvailableMb), ...others.map((p) => (typeof p.config.sandbox.memoryMb === 'number' ? p.config.sandbox.memoryMb : 0)));
+    const askedMb = Math.max(resolveMemoryMb(config.sandbox, o.freeMemoryBytes, undefined, commitAvailableMb), ...others.map((p) => (typeof p.config.sandbox.memoryMb === 'number' ? p.config.sandbox.memoryMb : 0)));
+    // Never more than this PC can keep in RAM for it, whatever was asked.
+    const memoryMb = cappedMemoryMb(askedMb, config.sandbox, Math.floor(os.totalmem() / 1048576));
     const launchId = Date.now() + '-' + crypto.randomBytes(3).toString('hex');
     const launchPath = path.join(storageRoot, 'launches', launchId);
     // Whatever must stay secret goes in a one-shot file in the data folder, never into the launch folder (the sandbox
@@ -104,6 +107,8 @@ opened) {
         ...(claudeCredentials ? { claudeCredentials } : {}),
         ...(o.vpn?.credentials ? { vpn: o.vpn.credentials } : {}),
         ...(o.vpn?.wireguardConfig ? { wireguardConfig: o.vpn.wireguardConfig } : {}),
+        // Checked again on the configs the sandbox boots with: never when a project in it has git access below "full".
+        ...(o.githubToken && githubTokenAllowed(config, others) ? { githubToken: o.githubToken } : {}),
     });
     fs.writeFileSync(path.join(launchPath, 'env.cmd'), logonEnv(session.workspace), 'utf8');
     copyRuntime(o.packageRoot, launchPath);
@@ -127,9 +132,10 @@ opened) {
         launchId,
         sessionPath,
         memoryMb,
-        memoryNote: config.sandbox.memoryMb === 'auto'
-            ? memoryNote(decideMemory(config.sandbox, Math.floor((o.freeMemoryBytes ?? os.freemem()) / 1048576), Math.floor(os.totalmem() / 1048576), commitAvailableMb))
-            : null,
+        memoryNote: residentNote(askedMb, memoryMb) ??
+            (config.sandbox.memoryMb === 'auto'
+                ? memoryNote(decideMemory(config.sandbox, Math.floor((o.freeMemoryBytes ?? os.freemem()) / 1048576), Math.floor(os.totalmem() / 1048576), commitAvailableMb))
+                : null),
         bootConfig: config,
         widened: wide.widened,
         mappings,

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

@@ -1,7 +1,7 @@
 export { generateSandbox } from './generate.js';
 export { decideProjectToolchains } from './toolchains.js';
 export { hostToolsOf, logonEnv } from './session-file.js';
-export { agentMemoryLimitMb, decideMemory, GUEST, memoryNote, resolveMemoryMb } from './wsb-file.js';
+export { cappedMemoryMb, decideMemory, GUEST, memoryNote, residentCapMb, residentNote, resolveMemoryMb, } from './wsb-file.js';
 export { GENTLE_NOTE, vgpuSource, vgpuWarning } from './risk-notes.js';
 export { buildLaunchPlan, buildWsb } from './launch-plan.js';
 export { MAX_BOOT_PROJECTS, planBootProjects, shownByRoot, type BootProjects } from './boot-projects.js';

package/dist/host/launch/index.js

@@ -1,7 +1,7 @@
 export { generateSandbox } from './generate.js';
 export { decideProjectToolchains } from './toolchains.js';
 export { hostToolsOf, logonEnv } from './session-file.js';
-export { agentMemoryLimitMb, decideMemory, GUEST, memoryNote, resolveMemoryMb } from './wsb-file.js';
+export { cappedMemoryMb, decideMemory, GUEST, memoryNote, residentCapMb, residentNote, resolveMemoryMb, } from './wsb-file.js';
 export { GENTLE_NOTE, vgpuSource, vgpuWarning } from './risk-notes.js';
 export { buildLaunchPlan, buildWsb } from './launch-plan.js';
 export { MAX_BOOT_PROJECTS, planBootProjects, shownByRoot } from './boot-projects.js';

package/dist/host/launch/session-file.js

@@ -5,7 +5,6 @@ import { resolveToolchains } from '../../core/detect/index.js';
 import { hubName, PROJECTS_GUEST, substDrives } from '../../shared/paths/index.js';
 import { hostClaudeDir } from '../profile/index.js';
 import { databaseCatalog } from './database-plan.js';
-import { agentMemoryLimitMb } from './wsb-file.js';
 import { effectiveCpuLimit } from '../../shared/memory/index.js';
 import { loadProfileOf } from './risk-notes.js';
 /** What was found on this PC to copy instead of download. */
@@ -65,7 +64,7 @@ export function guestSession(o, parts) {
         cpuLimitPercent: effectiveCpuLimit(config.sandbox.cpuLimit, loadProfileOf(config)),
         loadProfile: loadProfileOf(config),
         pageFileMb: config.sandbox.pageFileMb,
-        agentMemoryLimitMb: agentMemoryLimitMb(parts.memoryMb, config.sandbox.agentMemoryHeadroomMb),
+        agentBackstop: config.sandbox.agentMemoryHeadroomMb,
         pressureResponse: config.sandbox.pressureResponse,
         apps: config.apps,
         auditProcesses: config.audit.enabled && config.audit.processes,

package/dist/host/launch/wsb-file.d.ts

@@ -6,7 +6,7 @@ export declare const GUEST: {
     readonly mirror: "C:\\Mirror";
 };
 type SandboxSettings = Config['sandbox'];
-export type MemoryLimit = 'free' | 'share' | 'max' | 'commit';
+export type MemoryLimit = 'free' | 'share' | 'max' | 'commit' | 'resident';
 export interface MemoryDecision {
     readonly mb: number;
     /** What set the size. */
@@ -17,18 +17,22 @@ export interface MemoryDecision {
     readonly freeMb: number;
     readonly commitAvailableMb: number | null;
 }
+/**
+ * The most memory this PC can keep in RAM for the sandbox (pure): its RAM minus max(reserveHostMb, 25 %), and 2 GB
+ * more with vGPU. Windows Sandbox's memory is this PC's memory taken as needed; beyond what the PC can keep resident it
+ * is paged to this PC's disk while the sandbox pages to its own, and that is what can freeze the whole PC.
+ */
+export declare function residentCapMb(sandbox: SandboxSettings, totalMb: number): number;
+/** A fixed memoryMb above what this PC can keep resident is lowered to that (never below 4 GB). */
+export declare function cappedMemoryMb(memoryMb: number, sandbox: SandboxSettings, totalMb: number): number;
+/** The launch note when a fixed memoryMb was lowered. */
+export declare function residentNote(asked: number, given: number): string | null;
 /**
  * "auto" (pure): free RAM minus the reserve, never more than maxMemoryMb or maxMemoryPercent of the PC's total RAM,
  * and, when the PC's available commit (RAM plus paging file, what the sandbox's memory is charged against) is known,
  * never more than that minus the reserve either.
  */
 export declare function decideMemory(sandbox: SandboxSettings, freeMb: number, totalMb: number, commitAvailableMb: number | null): MemoryDecision;
-/**
- * The most memory everything the agents start may use together (pure): the sandbox's memory minus the headroom
- * ("auto" =
- * the larger of 2048 MB and 10 %), at least half of it so a tiny sandbox still works; null = no limit ("none").
- */
-export declare function agentMemoryLimitMb(memoryMb: number, headroom: SandboxSettings['agentMemoryHeadroomMb']): number | null;
 /** A plain-words note when the commit made the sandbox's memory much smaller (2 GB or more) than free RAM allowed. */
 export declare function memoryNote(decision: MemoryDecision): string | null;
 /** "auto": see decideMemory. commitAvailableMb: from HostTools memory-status (omitted = not checked). */

package/dist/host/launch/wsb-file.js

@@ -11,6 +11,34 @@ export const GUEST = {
 const MB = 1048576;
 const MIN_AUTO_MEMORY_MB = 4096;
 const roundDown = (mb) => Math.floor(mb / 1024) * 1024;
+/** GPU-PV (vGPU) needs room of its own on this PC: memory the graphics driver pins for the sandbox. */
+const VGPU_RESERVE_MB = 2048;
+/**
+ * The most memory this PC can keep in RAM for the sandbox (pure): its RAM minus max(reserveHostMb, 25 %), and 2 GB
+ * more with vGPU. Windows Sandbox's memory is this PC's memory taken as needed; beyond what the PC can keep resident it
+ * is paged to this PC's disk while the sandbox pages to its own, and that is what can freeze the whole PC.
+ */
+export function residentCapMb(sandbox, totalMb) {
+    const keep = Math.max(sandbox.reserveHostMb, Math.floor(totalMb / 4)) + (sandbox.vGpu ? VGPU_RESERVE_MB : 0);
+    return roundDown(totalMb - keep);
+}
+/** A fixed memoryMb above what this PC can keep resident is lowered to that (never below 4 GB). */
+export function cappedMemoryMb(memoryMb, sandbox, totalMb) {
+    const cap = residentCapMb(sandbox, totalMb);
+    return cap >= MIN_AUTO_MEMORY_MB && memoryMb > cap ? cap : memoryMb;
+}
+/** The launch note when a fixed memoryMb was lowered. */
+export function residentNote(asked, given) {
+    if (given >= asked)
+        return null;
+    return ('sandbox.memoryMb asks for ' +
+        asked +
+        ' MB; this PC can keep ' +
+        given +
+        ' MB in RAM for the sandbox (its RAM minus what it needs itself), so the sandbox gets ' +
+        given +
+        " MB. More would be paged to this PC's disk, which can freeze the whole PC.");
+}
 /**
  * "auto" (pure): free RAM minus the reserve, never more than maxMemoryMb or maxMemoryPercent of the PC's total RAM,
  * and, when the PC's available commit (RAM plus paging file, what the sandbox's memory is charged against) is known,
@@ -25,22 +53,12 @@ export function decideMemory(sandbox, freeMb, totalMb, commitAvailableMb) {
         ['share', shareMb],
         ['free', byFree],
         ['commit', byCommit],
+        ['resident', residentCapMb(sandbox, totalMb)],
     ];
     const lowest = candidates.reduce((a, b) => (b[1] < a[1] ? b : a));
-    const withoutCommit = roundDown(Math.min(sandbox.maxMemoryMb, shareMb, byFree));
+    const withoutCommit = roundDown(Math.min(sandbox.maxMemoryMb, shareMb, byFree, residentCapMb(sandbox, totalMb)));
     return { mb: roundDown(lowest[1]), limitedBy: lowest[0], withoutCommitMb: withoutCommit, freeMb, commitAvailableMb };
 }
-/**
- * The most memory everything the agents start may use together (pure): the sandbox's memory minus the headroom
- * ("auto" =
- * the larger of 2048 MB and 10 %), at least half of it so a tiny sandbox still works; null = no limit ("none").
- */
-export function agentMemoryLimitMb(memoryMb, headroom) {
-    if (headroom === 'none')
-        return null;
-    const keep = headroom === 'auto' ? Math.max(2048, Math.floor(memoryMb / 10)) : headroom;
-    return Math.max(Math.floor(memoryMb / 2), memoryMb - keep);
-}
 /** A plain-words note when the commit made the sandbox's memory much smaller (2 GB or more) than free RAM allowed. */
 export function memoryNote(decision) {
     if (decision.limitedBy !== 'commit' || decision.withoutCommitMb - decision.mb < 2048)

package/dist/host/life/host-memory.d.ts

@@ -10,6 +10,7 @@ export declare const HostMemorySchema: z.ZodObject<{
         fixed: "fixed";
     }>>;
     pageFileMaxMb: z.ZodCatch<z.ZodNumber>;
+    diskQueue: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
 }, z.core.$strip>;
 export type HostMemory = z.output<typeof HostMemorySchema>;
 /** The parsed answer of memory-status, or null (not Windows, unreadable, nonsense). */