windows-development-sandbox 1.5.0 → 1.9.0

package/dist/host/health/stale.js

@@ -0,0 +1,120 @@
+// What a closed or crashed sandbox leaves behind, and how to tell it from what is in use: records of sandboxes that are
+// gone, run files, old launch folders, background watchers with nothing to watch. These only look; the repair checks
+// remove through the safe helpers. Everything takes its folders as arguments, so tests use temp folders.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { dirExists, isLink } from '../../core/util/index.js';
+import { RunDir } from '../../shared/channel/index.js';
+const DAY = 24 * 60 * 60 * 1000;
+const SANDBOX_IMAGES = ['windowssandboxclient.exe', 'windowssandboxremotesession.exe', 'windowssandbox.exe'];
+/** A watcher this old, with its log quiet and no sandbox, is left over (a finishing one is done within minutes). */
+export const WATCHER_MIN_AGE_MS = 10 * 60 * 1000;
+export const WATCHER_LOG_QUIET_MS = 5 * 60 * 1000;
+/** Windows sessions that have a sandbox running (empty: none runs). */
+export function sandboxSessions(rows) {
+    const found = rows.filter((r) => SANDBOX_IMAGES.includes(r.image.toLowerCase()));
+    return [...new Set(found.map((r) => r.session))];
+}
+/** Sharing records whose Windows session has no sandbox running (nothing else removes them after a crash). */
+export function staleActiveRecords(records, rows) {
+    const sessions = sandboxSessions(rows);
+    return records.filter((r) => !sessions.includes(r.windowsSession));
+}
+/** What is left in <data>\run by a sandbox that is no longer running. */
+export function runStateProblems(dataPath) {
+    const run = new RunDir(dataPath);
+    const sessions = run.listSessions().filter((s) => s.phase === 'running' || s.phase === 'starting').length;
+    const found = run.scanRequests();
+    const requests = found.valid.length + found.invalid.length;
+    const phase = run.readSandboxStatus()?.phase;
+    const unfinishedBoot = phase && phase !== 'ready' ? phase : null;
+    return { sessions, requests, unfinishedBoot, any: sessions > 0 || requests > 0 || unfinishedBoot !== null };
+}
+/** Launch folders under <storage>\launches that nothing has touched for `days` days (each is a finished start). */
+export function staleLaunchFolders(storageRoot, days, now, keep = []) {
+    const dir = path.join(storageRoot, 'launches');
+    if (!dirExists(dir) || isLink(dir))
+        return [];
+    const found = [];
+    for (const name of fs.readdirSync(dir)) {
+        if (keep.includes(name))
+            continue;
+        const full = path.join(dir, name);
+        try {
+            const age = now - fs.lstatSync(full).mtimeMs;
+            if (age > days * DAY)
+                found.push({ path: full, ageDays: Math.floor(age / DAY) });
+        }
+        catch {
+            // gone while we looked
+        }
+    }
+    return found;
+}
+const PidSchema = z.coerce.number().int().positive();
+/** The history-sync watcher records in <storage>\run (watcher-<data set>.pid) with the age of each and of its log. */
+export function watcherRecords(storageRoot, now) {
+    const dir = path.join(storageRoot, 'run');
+    if (!dirExists(dir) || isLink(dir))
+        return [];
+    const age = (p) => {
+        try {
+            return now - fs.statSync(p).mtimeMs;
+        }
+        catch {
+            return null;
+        }
+    };
+    return fs
+        .readdirSync(dir)
+        .map((name) => ({ name, m: /^watcher-(.+)\.pid$/i.exec(name) }))
+        .flatMap(({ name, m }) => {
+        if (!m)
+            return [];
+        const file = path.join(dir, name);
+        let pid = null;
+        try {
+            const parsed = PidSchema.safeParse(fs.readFileSync(file, 'utf8').trim());
+            pid = parsed.success ? parsed.data : null;
+        }
+        catch {
+            return [];
+        }
+        return [
+            {
+                file,
+                pid,
+                ageMs: age(file) ?? 0,
+                logAgeMs: age(path.join(storageRoot, 'logs', 'host-sync-' + m[1] + '.log')),
+            },
+        ];
+    });
+}
+/**
+ * Watchers that run with no sandbox to watch: the process is alive and is a Node program (a recycled pid is somebody
+ * else's), no sandbox runs, and neither its record nor its log has changed for a while (a finishing watcher is spared).
+ */
+export function orphanWatchers(infos, o) {
+    if (o.running)
+        return [];
+    return infos.filter((w) => w.pid !== null &&
+        o.alive(w.pid) &&
+        o.image(w.pid)?.toLowerCase() === 'node.exe' &&
+        w.ageMs > WATCHER_MIN_AGE_MS &&
+        (w.logAgeMs === null || w.logAgeMs > WATCHER_LOG_QUIET_MS));
+}
+/** null when a small file can be created in the folder, else the reason (the file is removed again). */
+export function writeProblem(dir) {
+    const probe = path.join(dir, '.write-test-' + process.pid);
+    try {
+        fs.writeFileSync(probe, '');
+        return null;
+    }
+    catch (e) {
+        return e.code ?? String(e);
+    }
+    finally {
+        fs.rmSync(probe, { force: true });
+    }
+}

package/dist/host/health/system.d.ts

@@ -0,0 +1,37 @@
+import { type TaskRow } from '../sharing/index.js';
+/** The mandatory-level SID of an elevated (admin) token. */
+export declare const HIGH_INTEGRITY_SID = "S-1-16-12288";
+export { SHARING_GROUP } from './acl-read.js';
+export interface SystemProbe {
+    processes(): TaskRow[];
+    pidAlive(pid: number): boolean;
+    /** Ends one process (the caller has checked it is the right one). */
+    stop(pid: number): void;
+    /** The unexpanded PATH of this user or of the PC, or null when it cannot be read. */
+    registryPath(scope: 'user' | 'machine'): string | null;
+    /** Is the automatic-update task there? null when it cannot be asked. */
+    updateTaskExists(): boolean | null;
+    /** `icacls <folder>` output, or null. */
+    icacls(dir: string): string | null;
+    /** The accounts in the sharing group, or null when it cannot be read (no such group included). */
+    groupMembers(): string[] | null;
+    /** Is this SID in the token of this very process? null when whoami fails. */
+    tokenHasGroup(sid: string): boolean | null;
+    /** Does an HTTPS request to the address answer within `ms`? */
+    reachable(url: string, ms: number): Promise<boolean>;
+}
+/** The PATH value in `reg query ... /v Path` output, or null. */
+export declare function parseRegPath(text: string): string | null;
+/** The accounts listed by `net localgroup <name>`: the lines between the dashes and the closing sentence. */
+export declare function parseGroupMembers(text: string): string[] | null;
+export declare class WindowsProbe implements SystemProbe {
+    processes(): TaskRow[];
+    pidAlive(pid: number): boolean;
+    stop(pid: number): void;
+    registryPath(scope: 'user' | 'machine'): string | null;
+    updateTaskExists(): boolean | null;
+    icacls(dir: string): string | null;
+    groupMembers(): string[] | null;
+    tokenHasGroup(sid: string): boolean | null;
+    reachable(url: string, ms: number): Promise<boolean>;
+}

package/dist/host/health/system.js

@@ -0,0 +1,87 @@
+// What the health checks ask Windows (the processes, your PATH, the update task, folder permissions, the network). One
+// interface so tests give their own answers on temp folders; the real one only reads, apart from stop().
+import { spawnSync } from 'node:child_process';
+import { SYSTEM, system32 } from '../../shared/system.js';
+import { refuseInSelfTest } from '../test-guard.js';
+import { listProcesses } from '../sharing/index.js';
+import { SHARING_GROUP } from './acl-read.js';
+const HELPER_TIMEOUT_MS = 15000;
+const USER_ENVIRONMENT = 'HKCU\\Environment';
+const MACHINE_ENVIRONMENT = 'HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment';
+/** The mandatory-level SID of an elevated (admin) token. */
+export const HIGH_INTEGRITY_SID = 'S-1-16-12288';
+export { SHARING_GROUP } from './acl-read.js';
+/** The PATH value in `reg query ... /v Path` output, or null. */
+export function parseRegPath(text) {
+    const m = /^\s+Path\s+REG_(?:EXPAND_)?SZ\s+(.*)$/im.exec(text);
+    return m ? m[1].trim() : null;
+}
+/** The accounts listed by `net localgroup <name>`: the lines between the dashes and the closing sentence. */
+export function parseGroupMembers(text) {
+    const lines = text.split(/\r?\n/);
+    const start = lines.findIndex((l) => /^-{5,}\s*$/.test(l));
+    if (start < 0)
+        return null;
+    const rest = lines.slice(start + 1);
+    const end = rest.findIndex((l) => l.trim() === '' || /^\S.*\.$/.test(l.trim()));
+    return rest
+        .slice(0, end < 0 ? rest.length : end)
+        .map((l) => l.trim())
+        .filter(Boolean);
+}
+function run(exe, args) {
+    const r = spawnSync(exe, args, { encoding: 'utf8', windowsHide: true, timeout: HELPER_TIMEOUT_MS });
+    return { out: (r.stdout ?? '') + (r.stderr ?? ''), status: r.error ? null : r.status };
+}
+export class WindowsProbe {
+    processes() {
+        return listProcesses();
+    }
+    pidAlive(pid) {
+        if (!Number.isInteger(pid) || pid <= 0)
+            return false;
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (e) {
+            return e.code === 'EPERM';
+        }
+    }
+    stop(pid) {
+        refuseInSelfTest('stop programs');
+        if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid)
+            throw new Error('Not a process to stop: ' + pid);
+        process.kill(pid);
+    }
+    registryPath(scope) {
+        const r = run(SYSTEM.reg(), ['query', scope === 'user' ? USER_ENVIRONMENT : MACHINE_ENVIRONMENT, '/v', 'Path']);
+        return r.status === 0 ? parseRegPath(r.out) : null;
+    }
+    updateTaskExists() {
+        const r = run(system32('schtasks.exe'), ['/Query', '/TN', '\\WindowsDevelopmentSandbox\\Update']);
+        return r.status === null ? null : r.status === 0;
+    }
+    icacls(dir) {
+        const r = run(SYSTEM.icacls(), [dir]);
+        return r.status === 0 ? r.out : null;
+    }
+    groupMembers() {
+        const r = run(system32('net.exe'), ['localgroup', SHARING_GROUP]);
+        return r.status === 0 ? parseGroupMembers(r.out) : null;
+    }
+    tokenHasGroup(sid) {
+        const r = run(SYSTEM.whoami(), ['/groups', '/fo', 'csv', '/nh']);
+        return r.status === 0 ? r.out.includes('"' + sid + '"') : null;
+    }
+    async reachable(url, ms) {
+        try {
+            const response = await fetch(url, { method: 'HEAD', signal: AbortSignal.timeout(ms) });
+            return response.status < 500;
+        }
+        catch {
+            // Any failure (DNS, proxy, timeout) means "not reachable"; the caller words what to do.
+            return false;
+        }
+    }
+}

package/dist/host/install/copies.d.ts

@@ -0,0 +1,13 @@
+import { InstallLayout } from './layout.js';
+/** The install for everyone (%ProgramFiles%\WindowsDevelopmentSandbox), or null. */
+export declare function machineInstall(env?: NodeJS.ProcessEnv): InstallLayout | null;
+/** The install for just this user (%LOCALAPPDATA%\WindowsDevelopmentSandbox), or null. */
+export declare function userInstall(env?: NodeJS.ProcessEnv): InstallLayout | null;
+/** The installs that exist, the one for everyone first (it comes first on the PATH too). */
+export declare function managedInstalls(env?: NodeJS.ProcessEnv): InstallLayout[];
+/** Where this copy runs from, for `--version`: "all users, <folder>", "just you, <folder>", "npm copy, <folder>". */
+export declare function describeCopy(packageRoot: string): string;
+/** The line to print when this copy is not a managed install but one exists (it is hidden by this one), else null. */
+export declare function hiddenInstallLine(packageRoot: string, env?: NodeJS.ProcessEnv): string | null;
+/** hiddenInstallLine, but once per version (null afterwards). `storageRoot` holds the note that it was shown. */
+export declare function takeHiddenInstallNotice(storageRoot: string, packageRoot: string, version: string, env?: NodeJS.ProcessEnv): string | null;

package/dist/host/install/copies.js

@@ -0,0 +1,63 @@
+// Which managed installs exist on this PC, and what a copy that runs from somewhere else should say about them. A
+// managed install (<ProgramFiles or %LOCALAPPDATA%>\WindowsDevelopmentSandbox) is found from any copy of the program,
+// so an npm copy or a checkout still sees the machine install that shares sandboxes with other users.
+import path from 'node:path';
+import { z } from 'zod';
+import { fileExists } from '../../core/util/index.js';
+import { JsonFile } from '../../shared/io/index.js';
+import { InstallLayout } from './layout.js';
+const FOLDER = 'WindowsDevelopmentSandbox';
+function installAt(base, scope) {
+    if (!base || !path.isAbsolute(base))
+        return null;
+    const root = path.join(base, FOLDER);
+    if (!fileExists(path.join(root, 'active-version')) && !fileExists(path.join(root, 'install.json')))
+        return null;
+    return InstallLayout.at(root, scope);
+}
+/** The install for everyone (%ProgramFiles%\WindowsDevelopmentSandbox), or null. */
+export function machineInstall(env = process.env) {
+    return installAt(env.ProgramFiles, 'machine');
+}
+/** The install for just this user (%LOCALAPPDATA%\WindowsDevelopmentSandbox), or null. */
+export function userInstall(env = process.env) {
+    return installAt(env.LOCALAPPDATA, 'user');
+}
+/** The installs that exist, the one for everyone first (it comes first on the PATH too). */
+export function managedInstalls(env = process.env) {
+    return [machineInstall(env), userInstall(env)].filter((l) => l !== null);
+}
+/** Where this copy runs from, for `--version`: "all users, <folder>", "just you, <folder>", "npm copy, <folder>". */
+export function describeCopy(packageRoot) {
+    const layout = InstallLayout.detect(packageRoot);
+    if (layout)
+        return (layout.scope === 'machine' ? 'all users, ' : 'just you, ') + layout.root;
+    const resolved = path.resolve(packageRoot);
+    const npm = path.basename(path.dirname(resolved)).toLowerCase() === 'node_modules';
+    return (npm ? 'npm copy, ' : 'from ') + resolved;
+}
+/** The line to print when this copy is not a managed install but one exists (it is hidden by this one), else null. */
+export function hiddenInstallLine(packageRoot, env = process.env) {
+    if (InstallLayout.detect(packageRoot))
+        return null;
+    const installed = managedInstalls(env)[0];
+    if (!installed)
+        return null;
+    return ('Running the copy in ' +
+        path.resolve(packageRoot) +
+        '; the installed one in ' +
+        installed.root +
+        ' is hidden. sandbox doctor explains.');
+}
+const NoticeSchema = z.object({ version: z.string() });
+/** hiddenInstallLine, but once per version (null afterwards). `storageRoot` holds the note that it was shown. */
+export function takeHiddenInstallNotice(storageRoot, packageRoot, version, env = process.env) {
+    const line = hiddenInstallLine(packageRoot, env);
+    if (!line)
+        return null;
+    const file = new JsonFile(NoticeSchema, path.join(storageRoot, 'copy-notice.json'));
+    if (file.read()?.version === version)
+        return null;
+    file.write({ version });
+    return line;
+}

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

@@ -2,3 +2,4 @@ export { type InstallScope, InstallLayout, compareVersions, VERSION_PATTERN, NOD
 export { shimText, readBins, writeShims } from './shims.js';
 export { InstallRecordFile, InstallRecordSchema, type InstallRecord } from './install-record.js';
 export { UpdateTask } from './scheduled-task.js';
+export { machineInstall, userInstall, managedInstalls, describeCopy, hiddenInstallLine, takeHiddenInstallNotice, } from './copies.js';

package/dist/host/install/index.js

@@ -2,3 +2,4 @@ export { InstallLayout, compareVersions, VERSION_PATTERN, NODE_PATTERN } from '.
 export { shimText, readBins, writeShims } from './shims.js';
 export { InstallRecordFile, InstallRecordSchema } from './install-record.js';
 export { UpdateTask } from './scheduled-task.js';
+export { machineInstall, userInstall, managedInstalls, describeCopy, hiddenInstallLine, takeHiddenInstallNotice, } from './copies.js';

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

@@ -1,4 +1,8 @@
 import type { GenerateOptions, Generated } from '../../core/types.js';
-export declare function generateSandbox(given: GenerateOptions): Generated & {
+import { type EnginePlan, type SandboxEngine } from '../engines/index.js';
+export declare function generateSandbox(given: GenerateOptions, 
+/** The engine launch.ts opened (hcs needs a look at this PC first); Windows Sandbox when left out. */
+opened?: SandboxEngine): Generated & {
     personalization: string;
+    enginePlan: EnginePlan;
 };

package/dist/host/launch/generate.js

@@ -3,19 +3,37 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import os from 'node:os';
 import { widenForProjects } from '../../core/local-config/index.js';
 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 { folderAttachment } from '../storage/providers/index.js';
 import { assertTestWritable } from '../test-guard.js';
+import { writeLoadSettings } from '../life/watchdog.js';
+import { loadProfileOf } from './risk-notes.js';
 import { planBootProjects } from './boot-projects.js';
 import { planDatabases } from './database-plan.js';
 import { collectMappings } from './mappings.js';
 import { guestSession, logonEnv } from './session-file.js';
 import { copyRuntime, stageGitIdentity, stageHooks } from './stage.js';
 import { decideProjectToolchains } from './toolchains.js';
-import { buildWsb, resolveMemoryMb } from './wsb-file.js';
+import { buildLaunchPlan } from './launch-plan.js';
+import { decideMemory, GUEST, memoryNote, resolveMemoryMb } from './wsb-file.js';
 const NO_PROFILE = { hostDir: null, staged: [], skipped: [], credentials: false, secretsRemoved: [] };
-export function generateSandbox(given) {
+/** 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) {
+    const file = path.join(launchPath, 'claude-profile', '.credentials.json');
+    if (!fs.existsSync(file))
+        return undefined;
+    const text = fs.readFileSync(file, 'utf8');
+    fs.rmSync(file, { force: true });
+    return text;
+}
+export function generateSandbox(given, 
+/** The engine launch.ts opened (hcs needs a look at this PC first); Windows Sandbox when left out. */
+opened) {
     // Several projects at boot: the sandbox also gets what the others want and you allowed (core/local-config).
     const others = given.bootWants?.projects ?? [];
     const boot = planBootProjects({
@@ -33,37 +51,85 @@ export function generateSandbox(given) {
             fail('Unknown agent: ' + harnessName, 'Configured agents: ' + Object.keys(config.harnesses).join(', ')));
     if (!dirExists(workspaceHost))
         fail('The workspace folder does not exist: ' + workspaceHost, 'cd into the project first.');
+    // An engine or storage kind that cannot work yet stops the launch here, before anything is written.
+    const engine = opened ?? engineFor(config);
+    if (config.storage.contained !== 'off' && !o.dataMappings)
+        fail('Contained storage was not prepared for this launch.', 'Launch with sandbox launch (it mounts the image first).');
     assertTestWritable(storageRoot);
     assertTestWritable(dataPath);
     // Checked before anything is written, so a refusal leaves nothing behind.
-    const memoryMb = Math.max(resolveMemoryMb(config.sandbox, o.freeMemoryBytes), ...others.map((p) => (typeof p.config.sandbox.memoryMb === 'number' ? p.config.sandbox.memoryMb : 0)));
+    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 launchId = Date.now() + '-' + crypto.randomBytes(3).toString('hex');
     const launchPath = path.join(storageRoot, 'launches', launchId);
-    ensureDir(launchPath);
+    // Whatever must stay secret goes in a one-shot file in the data folder, never into the launch folder (the sandbox
+    // maps it read-only and it is kept for days). Leftovers of earlier launches go first.
     ensureDir(dataPath);
+    clearSecrets(storageRoot, dataPath);
+    ensureDir(launchPath);
     const mappingNotes = [];
     const mappings = collectMappings(o, launchPath, boot, mappingNotes);
     const profile = harnessName === 'claude'
         ? stageClaudeProfile(config.claudeProfile, launchPath, workspaceHost, config.secrets)
         : NO_PROFILE;
+    // This PC's Claude login leaves the launch folder for the one-shot file (with the agent environment and VPN login).
+    const claudeCredentials = takeStagedCredentials(launchPath);
     stageGitIdentity(launchPath);
     const personalization = config.personalization.enabled ? capturePersonalization(launchPath) : 'disabled';
     const databases = o.databases ?? planDatabases(config.databases, workspaceHost);
     const toolchains = decideProjectToolchains(o);
-    const session = guestSession(o, { launchId, launchPath, harness, boot, mappings, profile, databases, toolchains });
+    if (o.vpn?.profile) {
+        ensureDir(path.join(launchPath, 'vpn'));
+        fs.writeFileSync(path.join(launchPath, 'vpn', 'server.ovpn'), o.vpn.profile, 'utf8');
+    }
+    const session = guestSession(o, {
+        launchId,
+        launchPath,
+        harness,
+        boot,
+        mappings,
+        profile,
+        databases,
+        toolchains,
+        memoryMb,
+    });
     const sessionPath = path.join(launchPath, 'session.json');
     writeJson(sessionPath, session);
+    writeLoadSettings(storageRoot, dataPath, {
+        profile: loadProfileOf(config),
+        reserveHostMb: config.sandbox.reserveHostMb,
+    });
+    writeSecrets(dataPath, launchId, {
+        ...(harness && Object.keys(harness.environment).length ? { harnessEnvironment: harness.environment } : {}),
+        ...(claudeCredentials ? { claudeCredentials } : {}),
+        ...(o.vpn?.credentials ? { vpn: o.vpn.credentials } : {}),
+        ...(o.vpn?.wireguardConfig ? { wireguardConfig: o.vpn.wireguardConfig } : {}),
+    });
     fs.writeFileSync(path.join(launchPath, 'env.cmd'), logonEnv(session.workspace), 'utf8');
     copyRuntime(o.packageRoot, launchPath);
     stageHooks(o.packageRoot, launchPath, o.run.scripts);
-    const wsbPath = path.join(launchPath, 'agent.wsb');
-    fs.writeFileSync(wsbPath, buildWsb(config, memoryMb, mappings), 'utf8');
+    const enginePlan = engine.plan(buildLaunchPlan({
+        config,
+        memoryMb,
+        mappings,
+        launchPath,
+        storage: o.dataMappings
+            ? o.dataMappings.map((m) => ({ kind: 'folder', host: m.host, guest: m.guest, readOnly: m.readOnly }))
+            : [folderAttachment({ dataPath, guest: GUEST.data })],
+    }));
+    for (const file of enginePlan.files)
+        fs.writeFileSync(file.path, file.text, 'utf8');
+    const wsbPath = enginePlan.entry;
     return {
         wsbPath,
+        enginePlan,
         launchPath,
         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,
         bootConfig: config,
         widened: wide.widened,
         mappings,

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

@@ -1,7 +1,9 @@
 export { generateSandbox } from './generate.js';
 export { decideProjectToolchains } from './toolchains.js';
 export { hostToolsOf, logonEnv } from './session-file.js';
-export { GUEST, buildWsb, resolveMemoryMb } from './wsb-file.js';
+export { agentMemoryLimitMb, decideMemory, GUEST, memoryNote, 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';
 export { databaseCatalog, planDatabases } from './database-plan.js';
 export { msvcHint, projectEntries, readProjectFiles, uvHint } from './project-scan.js';

package/dist/host/launch/index.js

@@ -1,7 +1,9 @@
 export { generateSandbox } from './generate.js';
 export { decideProjectToolchains } from './toolchains.js';
 export { hostToolsOf, logonEnv } from './session-file.js';
-export { GUEST, buildWsb, resolveMemoryMb } from './wsb-file.js';
+export { agentMemoryLimitMb, decideMemory, GUEST, memoryNote, 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';
 export { databaseCatalog, planDatabases } from './database-plan.js';
 export { msvcHint, projectEntries, readProjectFiles, uvHint } from './project-scan.js';

package/dist/host/launch/launch-plan.d.ts

@@ -0,0 +1,13 @@
+import type { Config, ResolvedMapping } from '../../core/types.js';
+import { type LaunchPlan } from '../engines/index.js';
+import type { StorageAttachment } from '../storage/providers/index.js';
+export interface LaunchPlanInput {
+    readonly config: Config;
+    readonly memoryMb: number;
+    readonly mappings: readonly ResolvedMapping[];
+    readonly launchPath: string;
+    readonly storage: readonly StorageAttachment[];
+}
+export declare function buildLaunchPlan(input: LaunchPlanInput): LaunchPlan;
+/** The .wsb text for these settings (the Windows Sandbox engine's file, without writing it). */
+export declare function buildWsb(config: Config, memoryMb: number, mappings: readonly ResolvedMapping[]): string;

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

@@ -0,0 +1,26 @@
+import { wsbText } from '../engines/index.js';
+import { GUEST } from './wsb-file.js';
+export function buildLaunchPlan(input) {
+    const s = input.config.sandbox;
+    return {
+        launchPath: input.launchPath,
+        memoryMb: input.memoryMb,
+        cpuLimit: s.cpuLimit,
+        networking: s.networking,
+        devices: {
+            gpu: s.vGpu,
+            clipboard: s.clipboard,
+            audioInput: s.audioInput,
+            videoInput: s.videoInput,
+            printers: s.printerRedirection,
+            protectedClient: s.protectedClient,
+        },
+        mappings: input.mappings,
+        logonCommand: GUEST.launch + '\\sandbox\\boot\\logon.cmd',
+        storage: input.storage,
+    };
+}
+/** The .wsb text for these settings (the Windows Sandbox engine's file, without writing it). */
+export function buildWsb(config, memoryMb, mappings) {
+    return wsbText(buildLaunchPlan({ config, memoryMb, mappings, launchPath: GUEST.launch, storage: [] }));
+}

package/dist/host/launch/mappings.js

@@ -6,6 +6,7 @@ import { assertSafeMapping } from '../../core/safe-paths.js';
 import { dirExists, errMsg, fail, isInsideOrEqual, UserError } from '../../core/util/index.js';
 import { shownByRoot } from './boot-projects.js';
 import { deriveGuest, isValidGuestPath, guestConflict, guestFix, PROJECTS_GUEST, sandboxFolder, tidyGuestPath, } from '../../shared/paths/index.js';
+import { dataMapping } from '../storage/providers/index.js';
 import { GUEST } from './wsb-file.js';
 import { guestGitDir, planView } from '../workspace-view/index.js';
 /**
@@ -23,7 +24,7 @@ export function collectMappings(o, launchPath, boot = { roots: [], projects: [],
     const inRoot = !view && shownByRoot(boot.roots, workspaceHost, config.guestWorkspace);
     const mappings = [
         { host: launchPath, guest: GUEST.launch, readOnly: true },
-        { host: dataPath, guest: GUEST.data, readOnly: false },
+        ...(o.dataMappings ?? [dataMapping({ dataPath, guest: GUEST.data })]),
         ...(inRoot
             ? []
             : [{ host: view ? view.options.view : workspaceHost, guest: config.guestWorkspace, readOnly: config.readOnly }]),

package/dist/host/launch/risk-notes.d.ts

@@ -0,0 +1,10 @@
+import type { Config } from '../../core/types.js';
+import type { LoadProfile } from '../../shared/memory/index.js';
+/** The stricter load profile applies whenever vGPU is on, from any source. */
+export declare function loadProfileOf(config: Config): LoadProfile;
+/** Where vGpu being on comes from, for the sentence below: your own settings, or a project file you allowed. */
+export declare function vgpuSource(yourSettingOn: boolean): string;
+/** The vGPU warning (pure). `source` is vgpuSource(...) or "your settings". */
+export declare function vgpuWarning(source: string): string;
+/** The launch note that goes with the vGPU warning: what the tool does about it by itself. */
+export declare const GENTLE_NOTE = "vGPU is on: the sandbox runs gentler so this PC stays responsive.";

package/dist/host/launch/risk-notes.js

@@ -0,0 +1,18 @@
+// Plain-words warnings about settings that can take the whole PC down, shown at launch, by doctor and in crash reports.
+/** The stricter load profile applies whenever vGPU is on, from any source. */
+export function loadProfileOf(config) {
+    return config.sandbox.vGpu ? 'gentle' : 'normal';
+}
+/** Where vGpu being on comes from, for the sentence below: your own settings, or a project file you allowed. */
+export function vgpuSource(yourSettingOn) {
+    return yourSettingOn ? 'your settings' : "this project's .sandbox-config.json, which you allowed";
+}
+/** The vGPU warning (pure). `source` is vgpuSource(...) or "your settings". */
+export function vgpuWarning(source) {
+    return ('vGPU is on (from ' +
+        source +
+        "): the sandbox uses this PC's graphics card. With some graphics drivers, heavy use can freeze the whole PC. " +
+        'Turn it off unless a program in the sandbox needs the GPU (the mesa toolchain gives software OpenGL without it).');
+}
+/** The launch note that goes with the vGPU warning: what the tool does about it by itself. */
+export const GENTLE_NOTE = 'vGPU is on: the sandbox runs gentler so this PC stays responsive.';

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

@@ -10,6 +10,8 @@ export interface SessionParts {
     readonly profile: ProfileResult;
     readonly databases: DatabasePlan[];
     readonly toolchains: Generated['toolchains'];
+    /** The sandbox's memory (MB), for the agents' memory limit. */
+    readonly memoryMb: number;
 }
 /** What was found on this PC to copy instead of download. */
 export declare function hostToolsOf(probe: HostProbe): GuestSession['hostTools'];

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

@@ -5,6 +5,9 @@ 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. */
 export function hostToolsOf(probe) {
     return {
@@ -32,7 +35,8 @@ export function guestSession(o, parts) {
         roots: [...parts.boot.roots, ...parts.boot.projects].map((r) => r.guest),
         ...(o.autoSession === false ? { autoSession: false } : {}),
         harnessName,
-        harness: parts.harness,
+        // The environment (it may hold API keys) travels in a one-shot file in <data>\secrets, never in this file.
+        harness: parts.harness ? { ...parts.harness, environment: {} } : null,
         harnessArguments: o.harnessArgs,
         persistAgentState: config.storage.persistAgentState,
         networking: config.sandbox.networking,
@@ -47,6 +51,7 @@ export function guestSession(o, parts) {
         attach: config.attach,
         hooks: config.hooks,
         downloads: config.downloads,
+        ...(o.vpn ? { vpn: o.vpn.session } : {}),
         hostTools: hostToolsOf(o.probe),
         claudeProfile: {
             overwrite: config.claudeProfile.overwrite,
@@ -57,12 +62,16 @@ export function guestSession(o, parts) {
         },
         personalization: fs.existsSync(path.join(parts.launchPath, 'personalize', 'personalize.reg')),
         substDrives: substDrives(parts.mappings.map((m) => m.guest)),
-        cpuLimitPercent: config.sandbox.cpuLimit === 'none' ? null : config.sandbox.cpuLimit,
+        cpuLimitPercent: effectiveCpuLimit(config.sandbox.cpuLimit, loadProfileOf(config)),
+        loadProfile: loadProfileOf(config),
         pageFileMb: config.sandbox.pageFileMb,
+        agentMemoryLimitMb: agentMemoryLimitMb(parts.memoryMb, config.sandbox.agentMemoryHeadroomMb),
+        pressureResponse: config.sandbox.pressureResponse,
         apps: config.apps,
         auditProcesses: config.audit.enabled && config.audit.processes,
         agentHomes: Object.assign({}, ...Object.values(config.harnesses).map((h) => h.home?.env ?? {})),
         agentProfileDirs: Object.fromEntries(Object.entries(config.harnesses).flatMap(([name, h]) => h.home?.profileDirs?.length ? [[name, h.home.profileDirs]] : [])),
+        agents: Object.fromEntries(Object.entries(config.harnesses).map(([name, h]) => [name, { ...h, environment: {} }])),
     };
 }
 /**