windows-development-sandbox 0.0.0-stage → 1.0.5

package/dist/host/channel.js

@@ -0,0 +1,180 @@
+// Host side of the sandbox channel: follow the boot, send requests (sessions, exec, restart), and bridge this terminal
+// to a session's pseudo console. Everything read from the run folder is guest-written and treated as untrusted.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import { insideSandbox } from './platform.js';
+import { safeRemove } from '../shared/safe-remove.js';
+import { connect, DETACH_KEY, queryViewers, runTerminalClient } from '../shared/pty-client.js';
+import { listSessions, now, readResponse, readSandboxStatus, readSession, runPaths, writeJsonAtomic } from '../shared/rundir.js';
+import { assertNoLinks, fail, isLink, removeLink, safeText, sleep } from '../core/util.js';
+const BOOT_TIMEOUT_MS = 30 * 60 * 1000;
+const ipToInt = (ip) => ip.split('.').reduce((n, part) => n * 256 + Number(part), 0);
+/**
+ * True only for IPv4 addresses inside the subnet of one of this PC's Hyper-V adapters ("vEthernet ..."), which is
+ * where Windows Sandbox lives. Stops a compromised sandbox from pointing the host (and your keystrokes) anywhere else.
+ */
+export const isSandboxAddress = (ip, interfaces = os.networkInterfaces()) => {
+    if (!net.isIPv4(ip))
+        return false;
+    return Object.entries(interfaces).some(([name, list]) => /^vEthernet/i.test(name) && (list ?? []).some((i) => {
+        if (i.family !== 'IPv4' || i.internal)
+            return false;
+        const mask = ipToInt(i.netmask);
+        return mask !== 0 && (ipToInt(i.address) & mask) === (ipToInt(ip) & mask) && i.address !== ip;
+    }));
+};
+const id = () => Date.now().toString(36) + crypto.randomBytes(3).toString('hex');
+const until = async (timeoutMs, isAlive, poll, timeoutMessage) => {
+    const deadline = Date.now() + timeoutMs;
+    for (let round = 0; Date.now() < deadline; round++) {
+        const value = poll();
+        if (value !== null && value !== undefined)
+            return value;
+        if (round % 10 === 0 && !isAlive())
+            fail('Windows Sandbox closed (or is not running).', 'Start it again with sandbox claude; sandbox logs shows what happened.');
+        await sleep(500);
+    }
+    fail(timeoutMessage, 'Check what the sandbox is doing with sandbox logs -f (or sbx-show to see its window).');
+};
+/** Waits until the sandbox finished provisioning, printing each boot step. */
+export const waitForReady = (dataPath, launchId, isAlive) => {
+    let last = '';
+    return until(BOOT_TIMEOUT_MS, isAlive, () => {
+        const status = readSandboxStatus(dataPath);
+        if (!status || (launchId !== null && status.launchId !== launchId))
+            return null;
+        if (status.message !== last) {
+            console.log('  [sandbox] ' + safeText(status.message).slice(0, 300));
+            last = status.message;
+        }
+        if (status.phase === 'failed')
+            fail('The sandbox failed to start: ' + status.message, 'See sandbox logs for details; the sandbox window shows the error too (sbx-show if headless).');
+        return status.phase === 'ready' ? status : null;
+    }, 'Timed out waiting for the sandbox to finish provisioning.');
+};
+export const sendRequest = (dataPath, request) => {
+    assertNoLinks(dataPath, runPaths(dataPath).requests);
+    writeJsonAtomic(runPaths(dataPath).request(request.id), request);
+};
+export const waitForResponse = (dataPath, requestId, isAlive, timeoutMs) => until(timeoutMs, isAlive, () => {
+    const response = readResponse(dataPath, requestId);
+    if (response && !isLink(runPaths(dataPath).responses))
+        fs.rmSync(runPaths(dataPath).response(requestId), { force: true });
+    return response;
+}, 'The sandbox did not answer (its session daemon may have stopped).');
+export const requestSession = (dataPath, harness, args, cwd) => {
+    const requestId = id();
+    sendRequest(dataPath, { kind: 'session', id: requestId, harness, args, cwd, createdAt: now() });
+    return requestId;
+};
+export const waitForSession = (dataPath, sessionId, isAlive, timeoutMs = 15 * 60 * 1000) => {
+    let last = '';
+    return until(timeoutMs, isAlive, () => {
+        const session = readSession(dataPath, sessionId);
+        if (!session)
+            return null;
+        if (session.message !== last) {
+            console.log('  [session] ' + safeText(session.message).slice(0, 300));
+            last = session.message;
+        }
+        if (session.phase === 'failed')
+            fail('The agent session failed to start: ' + session.message, 'See sandbox logs for details.');
+        if (session.phase === 'exited')
+            fail('The agent exited right away (code ' + session.exitCode + ').', 'Check sandbox logs; a wrong agent argument is the usual cause.');
+        return session.phase === 'running' ? session : null;
+    }, 'Timed out waiting for the session to start.');
+};
+/** Runs a command inside the sandbox (in the workspace or a folder below it) and returns its output. */
+export const execInSandbox = async (dataPath, command, cwd, timeoutSeconds, isAlive) => {
+    const requestId = id();
+    sendRequest(dataPath, { kind: 'exec', id: requestId, command, cwd, timeoutSeconds, createdAt: now() });
+    return waitForResponse(dataPath, requestId, isAlive, (timeoutSeconds + 30) * 1000);
+};
+/** Restarts running sessions in place (they resume via the harness's resumeArguments, e.g. claude --continue). */
+export const restartSessions = async (dataPath, harness, isAlive) => {
+    const requestId = id();
+    sendRequest(dataPath, { kind: 'restart', id: requestId, harness, createdAt: now() });
+    return waitForResponse(dataPath, requestId, isAlive, 30000);
+};
+export const pingSandbox = async (dataPath, isAlive) => {
+    const requestId = id();
+    sendRequest(dataPath, { kind: 'ping', id: requestId, createdAt: now() });
+    return waitForResponse(dataPath, requestId, isAlive, 15000);
+};
+export const runningSessions = (dataPath) => listSessions(dataPath).filter((s) => s.phase === 'running');
+/** Most sessions the host will ever contact for one listing: a sandbox can write as many session files as it likes. */
+export const MAX_QUERIED_SESSIONS = 32;
+/** Running sessions of the sandbox that is running now (its launch id), newest last, capped. */
+export const currentSessions = (dataPath) => {
+    const launchId = readSandboxStatus(dataPath)?.launchId;
+    return runningSessions(dataPath).filter((s) => s.launchId === launchId).slice(-MAX_QUERIED_SESSIONS);
+};
+/** The session with this id (or id prefix), else the most recently started running one. */
+export const pickSession = (dataPath, sessionId) => {
+    const running = runningSessions(dataPath);
+    if (running.length === 0)
+        fail('No agent session is running in the sandbox.', 'Start one with sandbox claude (it opens a new session in the running sandbox).');
+    if (!sessionId)
+        return running[running.length - 1];
+    return running.find((s) => s.id === sessionId || s.id.startsWith(sessionId)) ?? fail('No running session "' + sessionId + '".', 'Running sessions: ' + running.map((s) => s.id).join(', ') + ' (sandbox sessions lists them).');
+};
+/** Where this PC may connect for a session: only addresses on its own Hyper-V network (null if there are none). */
+const hostEndpoint = (session) => {
+    // Inside the sandbox every session is on loopback; on the PC only addresses on its Hyper-V network are trusted.
+    const addresses = insideSandbox() ? ['127.0.0.1'] : session.attach?.addresses.filter((a) => isSandboxAddress(a)) ?? [];
+    return session.attach && addresses.length ? { ...session.attach, addresses } : null;
+};
+/** Who is watching a session right now (closed terminals do not count); null when it cannot be asked. */
+export const sessionViewers = (session) => {
+    const endpoint = hostEndpoint(session);
+    return endpoint ? queryViewers(endpoint) : Promise.resolve(null);
+};
+/**
+ * The newest running session of this agent in exactly this folder that no terminal on this PC is attached to, so
+ * sandbox claude -t picks it back up instead of starting another. A session that cannot answer is never reused.
+ */
+export const findUnwatchedSession = async (dataPath, harness, cwd) => {
+    const candidates = currentSessions(dataPath).filter((s) => s.harness === harness && s.cwd.toLowerCase() === cwd.toLowerCase()).reverse().slice(0, 8);
+    for (const session of candidates)
+        if ((await sessionViewers(session))?.remote === 0)
+            return session;
+    return null;
+};
+/** Bridges this terminal to a session. Returns the agent's exit code, or 0 when the user detaches. */
+export const attachTerminal = async (session) => {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        fail('--terminal / attach needs an interactive terminal.', 'Run it directly in Windows Terminal or PowerShell, not through a pipe or script.');
+    if (!session.attach)
+        fail('This session cannot be attached to: networking or attach is disabled for this sandbox.', 'Set sandbox.networking and attach.enabled to true, then start a new sandbox.');
+    const endpoint = hostEndpoint(session) ?? fail('Refusing to connect: the sandbox reported no address on this PC\'s Hyper-V (vEthernet) network (' + session.attach.addresses.join(', ') + ').', 'Use the sandbox window instead (sbx-show); if this keeps happening, run sandbox doctor.');
+    const socket = await connect(endpoint);
+    console.log('Attaching to ' + safeText(session.harness) + ' session ' + session.id + ' (' + safeText(session.cwd) + '). Detach any time with Ctrl+]');
+    await sleep(400);
+    const result = await runTerminalClient(socket, session.attach.token, { detachKey: DETACH_KEY });
+    switch (result.reason) {
+        case 'detach':
+            console.log('Detached. The session keeps running; reattach with: sandbox attach ' + session.id);
+            return 0;
+        case 'exit':
+            console.log(safeText(session.harness) + ' exited with code ' + result.exitCode + '.');
+            return result.exitCode;
+        case 'error': fail('The sandbox refused the connection: ' + result.message, 'Try sandbox attach again; the session may have restarted.');
+        default:
+            console.log('Connection to the sandbox closed.');
+            return 1;
+    }
+};
+/** Forgets status from a previous sandbox run so nothing stale is picked up. */
+export const resetRunDir = (dataPath) => {
+    const p = runPaths(dataPath);
+    // A link (planted by a sandbox) is removed itself and never followed, including `run` itself.
+    if (isLink(p.run)) {
+        removeLink(p.run);
+        return;
+    }
+    for (const target of [p.sandbox, p.requests, p.responses, p.sessions]) {
+        safeRemove(target, dataPath);
+    }
+};

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

@@ -0,0 +1,15 @@
+import type { ClaudeProfileConfig, ProfileResult } from '../core/types.js';
+import { type SecretsConfig } from './secrets.js';
+export declare const hostClaudeDir: (settings: ClaudeProfileConfig) => string;
+export declare const hostGlobalStateFile: (settings: ClaudeProfileConfig) => string;
+/**
+ * Copies SELECTED Claude settings from this PC into the launch folder. Conversation history is handled
+ * separately by history.ts (it needs path translation), and the login only travels when copyCredentials is on.
+ */
+/**
+ * What of your .claude.json the sandbox gets: everything except secrets and other projects. API keys and the account
+ * block stay on this PC (logins travel only through `sandbox account`), and of the per-project entries only
+ * this workspace's (with its MCP servers) is kept; other projects' entries can hold their MCP servers' tokens.
+ */
+export declare const sandboxGlobalState: (state: Record<string, unknown>, workspaceHost: string) => Record<string, unknown>;
+export declare const stageClaudeProfile: (settings: ClaudeProfileConfig, launchPath: string, workspaceHost: string, secrets: SecretsConfig) => ProfileResult;

package/dist/host/claude-profile.js

@@ -0,0 +1,103 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { stripMcpServers, stripSettings } from './secrets.js';
+import { dirExists, ensureDir, fileExists, homeDir, readJson, writeJson } from '../core/util.js';
+const MAX_BYTES = 250 * 1024 * 1024;
+const directorySize = (dir) => {
+    let total = 0;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        total += entry.isDirectory() ? directorySize(full) : fs.statSync(full).size;
+    }
+    return total;
+};
+const validJson = (file) => {
+    try {
+        JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const hostClaudeDir = (settings) => {
+    return settings.hostDir === 'auto' ? (process.env.CLAUDE_CONFIG_DIR ?? path.join(homeDir(), '.claude')) : settings.hostDir;
+};
+export const hostGlobalStateFile = (settings) => {
+    if (settings.globalStateFile !== 'auto')
+        return settings.globalStateFile;
+    return process.env.CLAUDE_CONFIG_DIR ? path.join(process.env.CLAUDE_CONFIG_DIR, '.claude.json') : path.join(homeDir(), '.claude.json');
+};
+/**
+ * Copies SELECTED Claude settings from this PC into the launch folder. Conversation history is handled
+ * separately by history.ts (it needs path translation), and the login only travels when copyCredentials is on.
+ */
+/**
+ * What of your .claude.json the sandbox gets: everything except secrets and other projects. API keys and the account
+ * block stay on this PC (logins travel only through `sandbox account`), and of the per-project entries only
+ * this workspace's (with its MCP servers) is kept; other projects' entries can hold their MCP servers' tokens.
+ */
+export const sandboxGlobalState = (state, workspaceHost) => {
+    const { primaryApiKey: _key, customApiKeyResponses: _responses, oauthAccount: _account, projects, ...rest } = state;
+    const same = (key) => key.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase() === workspaceHost.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+    const own = Object.entries((projects ?? {})).filter(([key]) => same(key));
+    return { ...rest, projects: Object.fromEntries(own) };
+};
+export const stageClaudeProfile = (settings, launchPath, workspaceHost, secrets) => {
+    const result = { hostDir: null, staged: [], skipped: [], credentials: false, secretsRemoved: [] };
+    if (!settings.enabled)
+        return result;
+    const hostDir = hostClaudeDir(settings);
+    result.hostDir = hostDir;
+    const target = path.join(launchPath, 'claude-profile');
+    ensureDir(target);
+    // The login file goes only through copyCredentials (a project file asking for it is flagged); include never copies it.
+    const items = settings.include.filter((name) => name.toLowerCase() !== '.credentials.json');
+    if (settings.copyCredentials)
+        items.push('.credentials.json');
+    for (const name of items) {
+        if (!/^[A-Za-z0-9._-]+$/.test(name) || name === '.' || name === '..') {
+            result.skipped.push(name + ' (invalid name)');
+            continue;
+        }
+        const source = path.join(hostDir, name);
+        const destination = path.join(target, name);
+        if (fileExists(source)) {
+            if (name.toLowerCase().endsWith('.json') && !validJson(source)) {
+                result.skipped.push(name + ' (invalid JSON on host; fix or remove it)');
+                continue;
+            }
+            // Claude's settings can carry credentials in "env" and commands that fetch them; those stay here.
+            if (/^settings(.local)?.json$/i.test(name))
+                writeJson(destination, stripSettings(readJson(source), secrets, result.secretsRemoved));
+            else
+                fs.copyFileSync(source, destination);
+        }
+        else if (dirExists(source)) {
+            if (directorySize(source) > MAX_BYTES) {
+                result.skipped.push(name + ' (over 250 MB)');
+                continue;
+            }
+            fs.cpSync(source, destination, { recursive: true, force: true });
+        }
+        else {
+            result.skipped.push(name + ' (not found)');
+            continue;
+        }
+        result.staged.push(name);
+        if (name === '.credentials.json')
+            result.credentials = true;
+    }
+    if (settings.globalStateFile !== '') {
+        const globalFile = hostGlobalStateFile(settings);
+        if (!fileExists(globalFile))
+            result.skipped.push('.claude.json (not found)');
+        else if (!validJson(globalFile))
+            result.skipped.push('.claude.json (invalid JSON on host)');
+        else {
+            writeJson(path.join(target, '.claude.json'), stripMcpServers(sandboxGlobalState(readJson(globalFile), workspaceHost), secrets, result.secretsRemoved));
+            result.staged.push('.claude.json');
+        }
+    }
+    return result;
+};

package/dist/host/cleanup.d.ts

@@ -0,0 +1,23 @@
+export interface PruneOptions {
+    launchDays: number;
+    logDays: number;
+    conflictDays: number;
+    keep: string[];
+    now?: number;
+}
+export interface PruneResult {
+    launches: number;
+    logs: number;
+    leftovers: number;
+    bytes: number;
+}
+export declare const DEFAULT_PRUNE: PruneOptions;
+/**
+ * Deletes, under the storage root:
+ *  - launch folders older than `launchDays` (a launch folder is only used by the sandbox it started; `keep` protects the running one)
+ *  - sandbox logs older than `logDays`
+ *  - interrupted downloads/copies (*.staging-*, *.incoming, *.tmp) older than a day
+ *  - claude-mem conflict copies older than `conflictDays`
+ */
+export declare const pruneStorage: (storageRoot: string, options?: Partial<PruneOptions>) => PruneResult;
+export declare const describePrune: (r: PruneResult) => string;

package/dist/host/cleanup.js

@@ -0,0 +1,66 @@
+// Keeps storage from growing forever. Runs automatically on every launch and via `sandbox clean`.
+import fs from 'node:fs';
+import { safeRemove } from '../shared/safe-remove.js';
+import path from 'node:path';
+import _ from 'lodash';
+import { dirExists, isLink } from '../core/util.js';
+const DAY = 24 * 60 * 60 * 1000;
+export const DEFAULT_PRUNE = { launchDays: 7, logDays: 14, conflictDays: 30, keep: [] };
+/** Size on disk, never following links (a sandbox-planted junction must not make us walk this PC's disk). */
+const sizeOf = (p) => {
+    try {
+        const stat = fs.lstatSync(p);
+        return stat.isDirectory() ? _.sumBy(fs.readdirSync(p), (name) => sizeOf(path.join(p, name))) : stat.isSymbolicLink() ? 0 : stat.size;
+    }
+    catch {
+        return 0;
+    }
+};
+const ageMs = (p, now) => { try {
+    return now - fs.lstatSync(p).mtimeMs;
+}
+catch {
+    return 0;
+} };
+/** Entries of a real folder; a link in place of a folder yields nothing (it is never listed or entered). */
+const children = (dir) => (dirExists(dir) && !isLink(dir) ? fs.readdirSync(dir).map((name) => path.join(dir, name)) : []);
+/**
+ * Deletes, under the storage root:
+ *  - launch folders older than `launchDays` (a launch folder is only used by the sandbox it started; `keep` protects the running one)
+ *  - sandbox logs older than `logDays`
+ *  - interrupted downloads/copies (*.staging-*, *.incoming, *.tmp) older than a day
+ *  - claude-mem conflict copies older than `conflictDays`
+ */
+export const pruneStorage = (storageRoot, options = {}) => {
+    const o = { ...DEFAULT_PRUNE, ...options };
+    const now = o.now ?? Date.now();
+    const result = { launches: 0, logs: 0, leftovers: 0, bytes: 0 };
+    const remove = (p, counter) => {
+        result.bytes += sizeOf(p);
+        safeRemove(p, storageRoot);
+        result[counter]++;
+    };
+    for (const launch of children(path.join(storageRoot, 'launches'))) {
+        if (!o.keep.includes(path.basename(launch)) && ageMs(launch, now) > o.launchDays * DAY)
+            remove(launch, 'launches');
+    }
+    for (const data of children(path.join(storageRoot, 'data'))) {
+        for (const log of children(path.join(data, 'logs')))
+            if (ageMs(log, now) > o.logDays * DAY)
+                remove(log, 'logs');
+        const runDir = path.join(data, 'run');
+        const dirs = [path.join(data, 'tools'), path.join(data, 'state'), ...(isLink(runDir) ? [] : [runDir, path.join(runDir, 'responses')])];
+        for (const dir of dirs) {
+            for (const entry of children(dir)) {
+                const name = path.basename(entry);
+                const leftover = /\.staging-[0-9a-f]+$|\.incoming$|\.tmp$/i.test(name) && ageMs(entry, now) > DAY;
+                const oldResponse = dir.endsWith('responses') && ageMs(entry, now) > DAY;
+                const oldConflict = /\.conflict-\d+$/.test(name) && ageMs(entry, now) > o.conflictDays * DAY;
+                if (leftover || oldResponse || oldConflict)
+                    remove(entry, 'leftovers');
+            }
+        }
+    }
+    return result;
+};
+export const describePrune = (r) => r.launches + r.logs + r.leftovers === 0 ? 'nothing to clean' : _.compact([r.launches && r.launches + ' launch folder(s)', r.logs && r.logs + ' log(s)', r.leftovers && r.leftovers + ' leftover(s)']).join(', ') + ' removed (' + Math.round(r.bytes / 1048576) + ' MB)';

package/dist/host/generate.d.ts

@@ -0,0 +1,15 @@
+import type { Config, GenerateOptions, Generated, ResolvedMapping } from '../core/types.js';
+export declare const GUEST: {
+    readonly launch: "C:\\AgentLaunch";
+    readonly data: "C:\\AgentData";
+    readonly hostTools: "C:\\HostTools";
+    readonly mirror: "C:\\Mirror";
+};
+export declare const resolveMemoryMb: (sandbox: Config["sandbox"], freeMemoryBytes?: number) => number;
+export declare const buildWsb: (config: Config, memoryMb: number, mappings: ResolvedMapping[]) => string;
+export declare const RUNTIME_FILES: string[];
+/** Only the identity from ~/.gitconfig: the rest can hold credentials (helpers, tokens in insteadOf URLs). */
+export declare const gitIdentity: (gitconfig: string) => string;
+export declare const generateSandbox: (o: GenerateOptions) => Generated & {
+    personalization: string;
+};

package/dist/host/generate.js

@@ -0,0 +1,185 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { assertNoGuestOverlap, userDir } from '../core/config.js';
+import { capturePersonalization } from './personalize.js';
+import { assertSafeMapping } from '../core/workspace.js';
+import { isValidGuestPath, MIRROR_ROOT, sandboxFolder, substDrives } from '../shared/guest-paths.js';
+import { hostClaudeDir, stageClaudeProfile } from './claude-profile.js';
+import { decideToolchains, resolveToolchains } from '../core/detect-toolchains.js';
+import { databaseCatalog, msvcHint, pcLanguages, planDatabases, projectEntries } from './project-scan.js';
+import { readPwshScripts, usesPwsh } from '../core/detect-pwsh.js';
+import { dirExists, ensureDir, fail, fileExists, homeDir, writeJson, xmlEscape } from '../core/util.js';
+export const GUEST = { launch: 'C:\\AgentLaunch', data: 'C:\\AgentData', hostTools: 'C:\\HostTools', mirror: MIRROR_ROOT };
+const HOOK_STAGES = ['pre-provision', 'pre-agent', 'post-agent'];
+const toggle = (value) => (value ? 'Enable' : 'Disable');
+export const resolveMemoryMb = (sandbox, freeMemoryBytes = os.freemem()) => {
+    if (sandbox.memoryMb !== 'auto')
+        return sandbox.memoryMb;
+    const freeMb = Math.floor(freeMemoryBytes / 1048576);
+    const rounded = Math.floor(Math.min(sandbox.maxMemoryMb, freeMb - sandbox.reserveHostMb) / 1024) * 1024;
+    if (rounded < 4096)
+        fail('Not enough free RAM for the sandbox (' + freeMb + ' MB free, ' + sandbox.reserveHostMb + ' MB kept for this PC).', 'Close some apps, lower sandbox.reserveHostMb, or set sandbox.memoryMb to a fixed value (>= 4096).');
+    return rounded;
+};
+export const buildWsb = (config, memoryMb, mappings) => {
+    const s = config.sandbox;
+    // Guest paths on other drive letters (F:\x) really live under C:\Mirror\F; bootstrap.ps1 substs F: onto it at boot.
+    const folders = mappings.map((m) => '<MappedFolder><HostFolder>' + xmlEscape(m.host) + '</HostFolder><SandboxFolder>' + xmlEscape(sandboxFolder(m.guest)) + '</SandboxFolder><ReadOnly>' + String(m.readOnly) + '</ReadOnly></MappedFolder>').join('');
+    return '<Configuration>'
+        + '<MemoryInMB>' + memoryMb + '</MemoryInMB>'
+        + '<vGPU>' + toggle(s.vGpu) + '</vGPU>'
+        + '<Networking>' + toggle(s.networking) + '</Networking>'
+        + '<ClipboardRedirection>' + toggle(s.clipboard) + '</ClipboardRedirection>'
+        + '<AudioInput>' + toggle(s.audioInput) + '</AudioInput>'
+        + '<VideoInput>' + toggle(s.videoInput) + '</VideoInput>'
+        + '<PrinterRedirection>' + toggle(s.printerRedirection) + '</PrinterRedirection>'
+        + '<ProtectedClient>' + toggle(s.protectedClient) + '</ProtectedClient>'
+        + '<MappedFolders>' + folders + '</MappedFolders>'
+        + '<LogonCommand><Command>' + xmlEscape(GUEST.launch + '\\sandbox\\logon.cmd') + '</Command></LogonCommand>'
+        + '</Configuration>';
+};
+const collectMappings = (o, launchPath) => {
+    const { config, dataPath, workspaceHost, harnessName } = o.run;
+    assertGuestPath(config.guestWorkspace, 'guestWorkspace');
+    const mappings = [
+        { host: launchPath, guest: GUEST.launch, readOnly: true },
+        { host: dataPath, guest: GUEST.data, readOnly: false },
+        { host: workspaceHost, guest: config.guestWorkspace, readOnly: config.readOnly },
+    ];
+    for (const m of config.mappings) {
+        const host = m.host;
+        assertGuestPath(m.guest, 'mappings[].guest for ' + host);
+        if (!dirExists(host)) {
+            if (m.optional) {
+                console.warn('Skipping optional mapping (folder not found): ' + host);
+                continue;
+            }
+            fail('A mapped folder does not exist: ' + host, 'Create it, fix the path in your config, or mark the mapping "optional": true.');
+        }
+        assertSafeMapping(host, o.packageRoot, o.run.storageRoot);
+        mappings.push({ host, guest: m.guest, readOnly: m.readOnly });
+    }
+    const { probe } = o;
+    if (probe.nodeDir)
+        mappings.push({ host: probe.nodeDir, guest: GUEST.hostTools + '\\node', readOnly: true });
+    if (probe.harnessExe && harnessName !== 'none')
+        mappings.push({ host: probe.harnessExe.dir, guest: GUEST.hostTools + '\\agents\\' + harnessName, readOnly: true });
+    if (probe.gitDir)
+        mappings.push({ host: probe.gitDir, guest: GUEST.hostTools + '\\git', readOnly: true });
+    if (probe.nvmDir)
+        mappings.push({ host: probe.nvmDir, guest: GUEST.hostTools + '\\nvm', readOnly: true });
+    assertNoGuestOverlap(mappings);
+    // Same check on where the folders really are (F:\x and C:\Mirror\F\x are one place).
+    assertNoGuestOverlap(mappings.map((m) => ({ guest: sandboxFolder(m.guest) })));
+    return mappings;
+};
+/** The schema checks this already; the host re-checks what goes into the .wsb and the subst list anyway. */
+const assertGuestPath = (guest, what) => {
+    if (!isValidGuestPath(guest))
+        fail(what + ' is not a usable sandbox folder: ' + guest, 'Use a folder under C:\\ (not Windows, Program Files, Users, AgentData, Mirror, ...) or on drive D: to Z:, e.g. C:\\Assets or F:\\SteamLibrary\\steamapps\\common\\Game.');
+};
+/** Package hooks first, then ~/.agent-sandbox/hooks (same file name = user's wins), then --script / "scripts". */
+const stageHooks = (packageRoot, launchPath, scripts) => {
+    for (const stage of HOOK_STAGES) {
+        const target = path.join(launchPath, 'hooks', stage);
+        ensureDir(target);
+        for (const source of [path.join(packageRoot, 'hooks', stage), path.join(userDir(), 'hooks', stage)]) {
+            if (dirExists(source))
+                fs.cpSync(source, target, { recursive: true, force: true });
+        }
+    }
+    scripts.forEach((script, index) => {
+        if (!fileExists(script))
+            fail('Script file not found: ' + script, 'Check the --script path.');
+        fs.copyFileSync(script, path.join(launchPath, 'hooks', 'pre-agent', '90-extra-' + index + '-' + path.basename(script)));
+    });
+};
+export const RUNTIME_FILES = ['main.js', 'daemon.js', 'view.js', 'gitguard.js', 'db.js'];
+/** The bundled sandbox runtime (dist/runtime: one self-contained file per entry point) and the sandbox/ scripts. */
+const copyRuntime = (packageRoot, launchPath) => {
+    const runtime = path.join(packageRoot, 'dist', 'runtime');
+    const missing = RUNTIME_FILES.filter((f) => !fileExists(path.join(runtime, f)));
+    if (missing.length)
+        fail('The sandbox runtime is missing from ' + runtime + ' (' + missing.join(', ') + ').', 'Rebuild it: npm run build (or reinstall the package).');
+    ensureDir(path.join(launchPath, 'runtime'));
+    for (const file of RUNTIME_FILES)
+        fs.copyFileSync(path.join(runtime, file), path.join(launchPath, 'runtime', file));
+    fs.writeFileSync(path.join(launchPath, 'package.json'), '{ "type": "module" }\n', 'utf8');
+    fs.cpSync(path.join(packageRoot, 'sandbox'), path.join(launchPath, 'sandbox'), { recursive: true });
+};
+/** Only the identity from ~/.gitconfig: the rest can hold credentials (helpers, tokens in insteadOf URLs). */
+export const gitIdentity = (gitconfig) => {
+    const values = {};
+    let section = '';
+    for (const line of gitconfig.split(/\r?\n/)) {
+        const header = /^\s*\[([^\]]+)\]/.exec(line);
+        if (header) {
+            section = header[1].trim().toLowerCase();
+            continue;
+        }
+        const pair = /^\s*(name|email)\s*=\s*(.*?)\s*$/i.exec(line);
+        if (section === 'user' && pair && !/[\r\n]/.test(pair[2]))
+            values[pair[1].toLowerCase()] = pair[2].replace(/^"(.*)"$/, '$1');
+    }
+    const lines = Object.entries(values).map(([k, v]) => '\t' + k + ' = ' + v);
+    return lines.length ? '[user]\n' + lines.join('\n') + '\n' : '';
+};
+export const generateSandbox = (o) => {
+    const { config, dataPath, workspaceHost, harnessName, storageRoot } = o.run;
+    const harness = harnessName === 'none' ? null : config.harnesses[harnessName] ?? 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.');
+    // Checked before anything is written, so a refusal leaves nothing behind.
+    const memoryMb = resolveMemoryMb(config.sandbox, o.freeMemoryBytes);
+    const launchId = Date.now() + '-' + crypto.randomBytes(3).toString('hex');
+    const launchPath = path.join(storageRoot, 'launches', launchId);
+    ensureDir(launchPath);
+    ensureDir(dataPath);
+    const mappings = collectMappings(o, launchPath);
+    const profile = harnessName === 'claude' ? stageClaudeProfile(config.claudeProfile, launchPath, workspaceHost, config.secrets) : { hostDir: null, staged: [], skipped: [], credentials: false, secretsRemoved: [] };
+    const gitconfig = path.join(homeDir(), '.gitconfig');
+    const identity = fileExists(gitconfig) ? gitIdentity(fs.readFileSync(gitconfig, 'utf8')) : '';
+    if (identity) {
+        ensureDir(path.join(launchPath, 'home'));
+        fs.writeFileSync(path.join(launchPath, 'home', '.gitconfig'), identity, 'utf8');
+    }
+    const personalization = config.personalization.enabled ? capturePersonalization(launchPath) : 'disabled';
+    const databases = o.databases ?? planDatabases(config.databases, workspaceHost);
+    const msvcScript = config.toolchains.msvc.enabled === 'auto' ? msvcHint(workspaceHost) : undefined;
+    const pwshScript = config.toolchains.pwsh.enabled === 'auto' ? usesPwsh(readPwshScripts(workspaceHost)) : null;
+    const toolchainDecisions = decideToolchains(config.toolchains, projectEntries(workspaceHost), o.pcLanguages ?? pcLanguages(), { ...(msvcScript ? { msvc: msvcScript } : {}), ...(pwshScript ? { pwsh: pwshScript } : {}) });
+    const session = {
+        launchId,
+        project: path.basename(workspaceHost),
+        workspace: config.guestWorkspace,
+        workspaceHost,
+        harnessName,
+        harness,
+        harnessArguments: o.harnessArgs,
+        persistAgentState: config.storage.persistAgentState,
+        networking: config.sandbox.networking,
+        headless: config.sandbox.headless,
+        network: config.network,
+        provisioning: config.provisioning,
+        // "auto" is decided here, so the guest and the launch table agree.
+        toolchains: resolveToolchains(config.toolchains, toolchainDecisions),
+        databases,
+        databaseCatalog: databaseCatalog(config.databases),
+        versions: o.run.versions,
+        attach: config.attach,
+        hooks: config.hooks,
+        hostTools: { node: Boolean(o.probe.nodeDir), nodeVersion: o.probe.nodeDir || o.probe.nvmNode ? o.probe.hostNodeVersion.replace(/^v/, '') : null, harnessExecutable: o.probe.harnessExe?.file ?? null, git: Boolean(o.probe.gitDir), nvm: Boolean(o.probe.nvmDir), volta: Boolean(o.probe.volta), pyenv: Boolean(o.probe.pyenv) },
+        claudeProfile: { overwrite: config.claudeProfile.overwrite, items: profile.staged, credentials: profile.credentials, hostConfigDir: profile.hostDir ?? hostClaudeDir(config.claudeProfile), syncClaudeMem: config.claudeProfile.syncClaudeMem },
+        personalization: fs.existsSync(path.join(launchPath, 'personalize', 'personalize.reg')),
+        substDrives: substDrives(mappings.map((m) => m.guest)),
+    };
+    const sessionPath = path.join(launchPath, 'session.json');
+    writeJson(sessionPath, session);
+    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');
+    return { wsbPath, launchPath, launchId, sessionPath, memoryMb, mappings, profile, personalization, databases, toolchains: toolchainDecisions };
+};

package/dist/host/personalize.d.ts

@@ -0,0 +1,10 @@
+export interface RegValue {
+    key: string;
+    name: string;
+    kind: string;
+    value: string | number | string[];
+}
+/** Formats captured values as a .reg file (UTF-16 friendly text; written as UTF-16LE with BOM). */
+export declare const toRegFile: (values: RegValue[]) => string;
+/** Writes personalize.reg (+ the wallpaper image) into `<launch>\personalize`. Returns a short summary. */
+export declare const capturePersonalization: (launchPath: string) => string;