windows-development-sandbox 0.0.0-stage → 1.1.0

package/dist/host/generate.js

@@ -0,0 +1,98 @@
+// Writes a launch folder for one sandbox: session.json (what the guest needs to know), the bundled runtime, hooks, the
+// staged Claude settings and the .wsb file that starts Windows Sandbox. The pieces live in launch/.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { decideToolchains, resolveToolchains } from '../core/detect-toolchains.js';
+import { readPwshScripts, usesPwsh } from '../core/detect-pwsh.js';
+import { dirExists, ensureDir, fail, writeJson } from '../core/util.js';
+import { substDrives } from '../shared/guest-paths.js';
+import { PROJECTS_GUEST, hubName } from '../shared/projects.js';
+import { planBootProjects } from './launch/projects.js';
+import { hostClaudeDir, stageClaudeProfile } from './claude-profile.js';
+import { databaseCatalog, planDatabases } from './database-plan.js';
+import { collectMappings } from './launch/mappings.js';
+import { copyRuntime, stageGitIdentity, stageHooks } from './launch/stage.js';
+import { buildWsb, resolveMemoryMb } from './launch/wsb.js';
+import { capturePersonalization } from './personalize.js';
+import { pcLanguages } from './pc-scan.js';
+import { msvcHint, projectEntries } from './project-scan.js';
+import { assertTestWritable } from './test-guard.js';
+const NO_PROFILE = { hostDir: null, staged: [], skipped: [], credentials: false, secretsRemoved: [] };
+/** Which toolchains the project needs ("auto" settings follow the project's files and what this PC has). */
+export const decideProjectToolchains = (o) => {
+    const { config, workspaceHost } = o.run;
+    const msvcScript = config.toolchains.msvc.enabled === 'auto' ? msvcHint(workspaceHost) : undefined;
+    const pwshScript = config.toolchains.pwsh.enabled === 'auto' ? usesPwsh(readPwshScripts(workspaceHost)) : null;
+    const hints = { ...(msvcScript ? { msvc: msvcScript } : {}), ...(pwshScript ? { pwsh: pwshScript } : {}) };
+    return decideToolchains(config.toolchains, projectEntries(workspaceHost), o.pcLanguages ?? pcLanguages(), hints);
+};
+/** What was found on this PC to copy instead of download. */
+const hostToolsOf = (probe) => ({
+    node: Boolean(probe.nodeDir),
+    nodeVersion: probe.nodeDir || probe.nvmNode ? probe.hostNodeVersion.replace(/^v/, '') : null,
+    harnessExecutable: probe.harnessExe?.file ?? null,
+    git: Boolean(probe.gitDir),
+    nvm: Boolean(probe.nvmDir),
+    volta: Boolean(probe.volta),
+    pyenv: Boolean(probe.pyenv),
+});
+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.');
+    assertTestWritable(storageRoot);
+    assertTestWritable(dataPath);
+    // 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 boot = planBootProjects({ run: o.run, packageRoot: o.packageRoot, extraProjects: o.extraProjects, knownProjects: o.knownProjects });
+    const mappings = collectMappings(o, launchPath, boot);
+    const profile = harnessName === 'claude' ? stageClaudeProfile(config.claudeProfile, launchPath, workspaceHost, config.secrets) : NO_PROFILE;
+    stageGitIdentity(launchPath);
+    const personalization = config.personalization.enabled ? capturePersonalization(launchPath) : 'disabled';
+    const databases = o.databases ?? planDatabases(config.databases, workspaceHost);
+    const toolchainDecisions = decideProjectToolchains(o);
+    const session = {
+        launchId,
+        project: path.basename(workspaceHost),
+        projectId: hubName(workspaceHost, []),
+        workspace: config.guestWorkspace,
+        workspaceHost,
+        projectsDir: PROJECTS_GUEST,
+        roots: boot.roots.map((r) => r.guest),
+        ...(o.autoSession === false ? { autoSession: false } : {}),
+        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,
+        downloads: config.downloads,
+        hostTools: hostToolsOf(o.probe),
+        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)),
+        cpuLimitPercent: config.sandbox.cpuLimit === 'none' ? null : config.sandbox.cpuLimit,
+    };
+    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, projects: boot };
+};

package/dist/host/join.d.ts

@@ -0,0 +1,28 @@
+import type { ResolvedRun } from '../core/types.js';
+import { type ProjectSpecT } from '../shared/schema.js';
+import { type ProjectMapper, type RegistryEntry } from './projects.js';
+/** The launch folder of the running sandbox (host-only storage; its id comes from the guest, so it is checked). */
+export declare const runningLaunchPath: (storageRoot: string, dataPath: string) => string | null;
+/** What a session or command from this folder needs: where it is inside, and (for another project) its spec. */
+export interface Joined {
+    project: RegistryEntry;
+    guestDir: string;
+    spec: ProjectSpecT | null;
+    run: ResolvedRun | null;
+    notes: string[];
+}
+/** The project spec the guest provisions from (scans the project folder like a launch does). */
+export declare const projectSpec: (run: ResolvedRun, entry: RegistryEntry, hooks: boolean) => ProjectSpecT;
+/**
+ * Makes `hostDir` usable in the running sandbox. The launch folder (or a folder below it) needs nothing; any other
+ * folder is resolved with `resolve` (the caller's resolveRun, with the approval prompt), checked, and registered.
+ */
+export declare const joinRunning: (o: {
+    storageRoot: string;
+    dataPath: string;
+    packageRoot: string;
+    hostDir: string;
+    wsbShare: boolean;
+    resolve: (projectRoot: string) => Promise<ResolvedRun>;
+    mapper?: ProjectMapper;
+}) => Promise<Joined>;

package/dist/host/join.js

@@ -0,0 +1,76 @@
+// Joining the running sandbox from another folder. The folder's run is resolved exactly as a fresh launch would
+// resolve it (its approved .sandbox-config.json, versions, toolchain detection, database plan), checked against the
+// running sandbox's machine-wide protections, made visible inside (host/projects.ts: a project root, a project
+// mapped at boot, or wsb share) and described to the guest, which provisions what is missing before its session.
+// When none of those can make it visible, NeedsRestart reaches the caller, which offers a restart.
+import fs from 'node:fs';
+import path from 'node:path';
+import { checkJoin, protectionsOf } from '../core/project-policy.js';
+import { resolveToolchains } from '../core/detect-toolchains.js';
+import { assertNoLinks, fail } from '../core/util.js';
+import { Id } from '../shared/schema.js';
+import { readSandboxStatus } from '../shared/rundir.js';
+import { syncProjectIn } from '../sync/watcher.js';
+import { planDatabases } from './database-plan.js';
+import { decideProjectToolchains } from './generate.js';
+import { projectHere, projectMapper, readRegistry, rememberProject, rootHere } from './projects.js';
+import { stageScripts } from './launch/stage.js';
+import { addRepoSnapshot } from './repo-guard.js';
+/** The launch folder of the running sandbox (host-only storage; its id comes from the guest, so it is checked). */
+export const runningLaunchPath = (storageRoot, dataPath) => {
+    const launchId = readSandboxStatus(dataPath)?.launchId;
+    if (!launchId || !/^\d+-[0-9a-f]{6}$/.test(launchId) || readRegistry(storageRoot)?.launchId !== launchId)
+        return null;
+    const launchPath = path.join(storageRoot, 'launches', launchId);
+    assertNoLinks(storageRoot, launchPath);
+    return fs.existsSync(path.join(launchPath, 'session.json')) ? launchPath : null;
+};
+/** The project spec the guest provisions from (scans the project folder like a launch does). */
+export const projectSpec = (run, entry, hooks) => {
+    const { config } = run;
+    const toolchains = resolveToolchains(config.toolchains, decideProjectToolchains({ run }));
+    const harness = run.harnessName === 'none' ? null : config.harnesses[run.harnessName];
+    return {
+        name: Id.parse(entry.name), workspace: entry.guest, workspaceHost: entry.host, toolchains, versions: run.versions,
+        databases: planDatabases(config.databases, run.workspaceHost).slice(0, 8),
+        harnesses: harness ? { [run.harnessName]: harness } : {},
+        hooks,
+    };
+};
+/**
+ * Makes `hostDir` usable in the running sandbox. The launch folder (or a folder below it) needs nothing; any other
+ * folder is resolved with `resolve` (the caller's resolveRun, with the approval prompt), checked, and registered.
+ */
+export const joinRunning = async (o) => {
+    const here = projectHere(o.storageRoot, o.hostDir);
+    if (here?.project.primary)
+        return { ...here, spec: null, run: null, notes: [] };
+    const registry = readRegistry(o.storageRoot) ?? fail('The running sandbox was started by an older version, so it cannot take another folder.', 'Stop it (sandbox stop) and start it again.');
+    // A folder below a project already in the sandbox uses that project; anything else becomes a project of its own.
+    const root = here?.project.host ?? path.resolve(o.hostDir);
+    const run = await o.resolve(root);
+    const check = checkJoin(registry.protections, protectionsOf(run.config));
+    if (check.stricter.length) {
+        fail('This project needs stricter protection than the running sandbox has, and those settings are machine-wide:\n  ' + check.stricter.join('\n  '), 'Its sessions cannot get them without changing them for the sessions already running. Stop the sandbox (sandbox stop) and start it from ' + root + '.');
+    }
+    const mapper = o.mapper ?? projectMapper({ storageRoot: o.storageRoot, packageRoot: o.packageRoot, wsbShare: o.wsbShare });
+    // Guarded from now on. A folder the sandbox could already write (inside a root, or mapped at boot) and that has no
+    // snapshot from the launch gets an empty one: what is there now may have been planted, so it counts as new.
+    // Anything else is snapshotted before it becomes visible.
+    addRepoSnapshot(o.dataPath, root, { empty: Boolean(here) || Boolean(rootHere(o.storageRoot, root)) });
+    const entry = mapper.register(root);
+    rememberProject(o.storageRoot, entry.host);
+    const launchPath = runningLaunchPath(o.storageRoot, o.dataPath);
+    // Your hooks in ~/.agent-sandbox/hooks ran at boot (once per sandbox); the project's own scripts ("scripts" in its
+    // .sandbox-config.json, --script) run before its first agent. The launch folder is read-only for the sandbox, but
+    // this side can still add them to it.
+    const hooks = Boolean(launchPath) && run.scripts.length > 0;
+    if (launchPath && hooks)
+        stageScripts(path.join(launchPath, 'projects', entry.name, 'hooks', 'pre-agent'), run.scripts);
+    try {
+        syncProjectIn(o.dataPath, { hostWorkspace: entry.host, guestWorkspace: entry.guest });
+    }
+    catch { /* history is a convenience; never block the session */ }
+    const notes = [...run.notes, ...check.looser.map((l) => 'The running sandbox is stricter: ' + l + '.')];
+    return { project: entry, guestDir: here ? here.guestDir : entry.guest, spec: projectSpec(run, entry, hooks), run, notes };
+};

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

@@ -0,0 +1,3 @@
+import type { GenerateOptions, ResolvedMapping } from '../../core/types.js';
+import type { BootProjects } from './projects.js';
+export declare const collectMappings: (o: GenerateOptions, launchPath: string, boot?: BootProjects) => ResolvedMapping[];

package/dist/host/launch/mappings.js

@@ -0,0 +1,50 @@
+import { assertNoGuestOverlap } from '../../core/config.js';
+import { assertSafeMapping } from '../../core/safe-paths.js';
+import { dirExists, fail } from '../../core/util.js';
+import { isValidGuestPath, sandboxFolder } from '../../shared/guest-paths.js';
+import { GUEST } from './wsb.js';
+export const collectMappings = (o, launchPath, boot = { roots: [], projects: [], notes: [] }) => {
+    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 });
+    }
+    // Project roots and other projects, so they can join the running sandbox without a restart (launch/projects.ts).
+    for (const m of [...boot.roots, ...boot.projects]) {
+        assertGuestPath(m.guest, 'project folder for ' + m.host);
+        mappings.push({ host: m.host, guest: m.guest, readOnly: false });
+    }
+    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/dist/host/launch/projects.d.ts

@@ -0,0 +1,15 @@
+import type { ResolvedRun } from '../../core/types.js';
+import { type RootMapping } from '../../shared/projects.js';
+/** More folders than this would make the .wsb (and every boot) unwieldy; the rest join with a restart later. */
+export declare const MAX_BOOT_PROJECTS = 48;
+export interface BootProjects {
+    roots: RootMapping[];
+    projects: RootMapping[];
+    notes: string[];
+}
+export declare const planBootProjects: (o: {
+    run: ResolvedRun;
+    packageRoot: string;
+    extraProjects?: string[];
+    knownProjects?: string[];
+}) => BootProjects;

package/dist/host/launch/projects.js

@@ -0,0 +1,56 @@
+// Which folders besides the launch folder are mapped so other projects can join without a restart: the project
+// roots (projects.roots), projects carried over by a restart that added one, and with projects.all every project
+// started before (except projects.exclude). Every one passes the same checks as a launch folder.
+import path from 'node:path';
+import { assertSafeMapping, assertSafeWorkspace } from '../../core/safe-paths.js';
+import { dirExists, errMsg, fail } from '../../core/util.js';
+import { isWithin, planProjectMappings } from '../../shared/projects.js';
+import { allProjectsToMap, readKnown } from '../projects.js';
+/** More folders than this would make the .wsb (and every boot) unwieldy; the rest join with a restart later. */
+export const MAX_BOOT_PROJECTS = 48;
+export const planBootProjects = (o) => {
+    const { config, workspaceHost, storageRoot } = o.run;
+    const notes = [];
+    const safe = (folder) => {
+        try {
+            assertSafeWorkspace(folder, o.packageRoot, storageRoot);
+            assertSafeMapping(folder, o.packageRoot, storageRoot);
+            return null;
+        }
+        catch (e) {
+            return errMsg(e);
+        }
+    };
+    const roots = [];
+    for (const root of config.projects.roots.map((r) => path.resolve(r))) {
+        if (!dirExists(root)) {
+            notes.push('Project root not found, skipped: ' + root);
+            continue;
+        }
+        const refusal = safe(root);
+        if (refusal)
+            fail('projects.roots: ' + refusal, 'Use a folder that holds your projects, e.g. F:\\Code (not a drive, your profile or a system folder).');
+        if (!roots.some((r) => isWithin(r, root)))
+            roots.push(root);
+    }
+    const known = o.knownProjects ?? readKnown(storageRoot).map((k) => k.host);
+    const wanted = [...(o.extraProjects ?? []), ...(config.projects.all ? allProjectsToMap(known, { primary: workspaceHost, roots, exclude: config.projects.exclude }) : [])];
+    const projects = [];
+    for (const folder of wanted.map((p) => path.resolve(p))) {
+        if (isWithin(workspaceHost, folder) || roots.some((r) => isWithin(r, folder)) || projects.some((p) => isWithin(p, folder) || isWithin(folder, p)))
+            continue;
+        if (!dirExists(folder))
+            continue;
+        const refusal = safe(folder);
+        if (refusal) {
+            notes.push('Not mapped: ' + refusal);
+            continue;
+        }
+        if (projects.length >= MAX_BOOT_PROJECTS) {
+            notes.push('More than ' + MAX_BOOT_PROJECTS + ' projects: the rest are not mapped (a project root holds any number).');
+            break;
+        }
+        projects.push(folder);
+    }
+    return { ...planProjectMappings(roots, projects, Boolean(o.run.mirror)), notes };
+};

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

@@ -0,0 +1,11 @@
+/** Package hooks first, then ~/.agent-sandbox/hooks (same file name = user's wins), then --script / "scripts". */
+export declare const stageHooks: (packageRoot: string, launchPath: string, scripts: string[]) => void;
+/** --script / "scripts" files, run before the agent in this order. */
+export declare const stageScripts: (target: string, scripts: string[]) => void;
+export declare const RUNTIME_FILES: string[];
+/** The bundled sandbox runtime (dist/runtime: one self-contained file per entry point) and the sandbox/ scripts. */
+export declare const copyRuntime: (packageRoot: string, launchPath: string) => void;
+/** Only the identity from ~/.gitconfig: the rest can hold credentials (helpers, tokens in insteadOf URLs). */
+export declare const gitIdentity: (gitconfig: string) => string;
+/** Writes this PC's git name and email to home\.gitconfig in the launch folder (nothing when there are none). */
+export declare const stageGitIdentity: (launchPath: string) => void;

package/dist/host/launch/stage.js

@@ -0,0 +1,66 @@
+// What is copied into the launch folder (C:\AgentLaunch inside the sandbox): hooks, the bundled runtime, the git identity.
+import fs from 'node:fs';
+import path from 'node:path';
+import { userDir } from '../../core/config.js';
+import { dirExists, ensureDir, fail, fileExists, homeDir } from '../../core/util.js';
+const HOOK_STAGES = ['pre-provision', 'pre-agent', 'post-agent'];
+/** Package hooks first, then ~/.agent-sandbox/hooks (same file name = user's wins), then --script / "scripts". */
+export 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 });
+        }
+    }
+    stageScripts(path.join(launchPath, 'hooks', 'pre-agent'), scripts);
+};
+/** --script / "scripts" files, run before the agent in this order. */
+export const stageScripts = (target, scripts) => {
+    ensureDir(target);
+    scripts.forEach((script, index) => {
+        if (!fileExists(script))
+            fail('Script file not found: ' + script, 'Check the --script path.');
+        fs.copyFileSync(script, path.join(target, '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. */
+export 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' : '';
+};
+/** Writes this PC's git name and email to home\.gitconfig in the launch folder (nothing when there are none). */
+export const stageGitIdentity = (launchPath) => {
+    const gitconfig = path.join(homeDir(), '.gitconfig');
+    const identity = fileExists(gitconfig) ? gitIdentity(fs.readFileSync(gitconfig, 'utf8')) : '';
+    if (!identity)
+        return;
+    ensureDir(path.join(launchPath, 'home'));
+    fs.writeFileSync(path.join(launchPath, 'home', '.gitconfig'), identity, 'utf8');
+};

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

@@ -0,0 +1,10 @@
+import type { Config, 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";
+};
+/** "auto": free RAM minus the reserve, but never more than maxMemoryMb or maxMemoryPercent of the PC's total RAM. */
+export declare const resolveMemoryMb: (sandbox: Config["sandbox"], freeMemoryBytes?: number, totalMemoryBytes?: number) => number;
+export declare const buildWsb: (config: Config, memoryMb: number, mappings: ResolvedMapping[]) => string;

package/dist/host/launch/wsb.js

@@ -0,0 +1,34 @@
+// The .wsb file Windows Sandbox starts from: memory, devices and the folders mapped in.
+import os from 'node:os';
+import { fail, xmlEscape } from '../../core/util.js';
+import { MIRROR_ROOT, sandboxFolder } from '../../shared/guest-paths.js';
+export const GUEST = { launch: 'C:\\AgentLaunch', data: 'C:\\AgentData', hostTools: 'C:\\HostTools', mirror: MIRROR_ROOT };
+const toggle = (value) => (value ? 'Enable' : 'Disable');
+/** "auto": free RAM minus the reserve, but never more than maxMemoryMb or maxMemoryPercent of the PC's total RAM. */
+export const resolveMemoryMb = (sandbox, freeMemoryBytes = os.freemem(), totalMemoryBytes = os.totalmem()) => {
+    if (sandbox.memoryMb !== 'auto')
+        return sandbox.memoryMb;
+    const freeMb = Math.floor(freeMemoryBytes / 1048576);
+    const shareMb = Math.floor((totalMemoryBytes / 1048576) * sandbox.maxMemoryPercent / 100);
+    const rounded = Math.floor(Math.min(sandbox.maxMemoryMb, shareMb, 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>';
+};

package/dist/host/pc-scan.d.ts

@@ -0,0 +1,6 @@
+import { type Database } from '../core/detect-databases.js';
+import { type AutoToolchain } from '../core/detect-toolchains.js';
+/** Languages this PC has (their commands on PATH; Windows' Store stubs for python do not count). */
+export declare const pcLanguages: () => AutoToolchain[];
+/** Database services installed on this PC (names from the service control manager; nothing is started or changed). */
+export declare const hostDatabases: () => Database[];

package/dist/host/pc-scan.js

@@ -0,0 +1,37 @@
+// What this PC has installed (languages on PATH, MSVC for Rust, database services), so `auto` settings can follow it.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pcHasPwsh } from '../core/detect-pwsh.js';
+import { databasesFromServices } from '../core/detect-databases.js';
+import { AUTO_TOOLCHAINS } from '../core/detect-toolchains.js';
+import { captureOutput, isWin } from '../core/util.js';
+import { system32 } from '../shared/system.js';
+/** This PC builds Rust with MSVC: rustup's default host is *-msvc (read from rustup's settings; nothing is run). */
+const msvcRust = () => {
+    const settings = path.join(process.env.RUSTUP_HOME ?? path.join(os.homedir(), '.rustup'), 'settings.toml');
+    try {
+        return /default_host_triple\s*=\s*"[^"]*-msvc"/.test(fs.readFileSync(settings, 'utf8').slice(0, 64 * 1024));
+    }
+    catch {
+        return false;
+    }
+};
+/** Languages this PC has (their commands on PATH; Windows' Store stubs for python do not count). */
+export const pcLanguages = () => {
+    const dirs = (process.env.PATH ?? '').split(path.delimiter).filter((d) => d && !/WindowsApps/i.test(d));
+    const has = (...names) => dirs.some((d) => names.some((n) => fs.existsSync(path.join(d, n))));
+    const found = {
+        python: has('python.exe', 'py.exe'), rust: has('cargo.exe', 'rustc.exe'), cpp: has('gcc.exe', 'g++.exe', 'cl.exe', 'clang.exe'),
+        msvc: msvcRust(), pwsh: pcHasPwsh(), dotnet: has('dotnet.exe'), go: has('go.exe'), java: has('java.exe', 'javac.exe'), ruby: has('ruby.exe'), php: has('php.exe'), deno: has('deno.exe'),
+    };
+    return AUTO_TOOLCHAINS.filter((t) => found[t]);
+};
+/** Database services installed on this PC (names from the service control manager; nothing is started or changed). */
+export const hostDatabases = () => {
+    if (!isWin)
+        return [];
+    const output = captureOutput(system32('sc.exe'), ['query', 'type=', 'service', 'state=', 'all'], { timeout: 10000 });
+    const names = [...output.matchAll(/^SERVICE_NAME:\s*(.+)$/gm)].map((m) => m[1].trim());
+    return databasesFromServices(names);
+};

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;

package/dist/host/personalize.js

@@ -0,0 +1,97 @@
+// Captures the look of this desktop (theme, accent colour, taskbar, Explorer options, wallpaper, mouse/keyboard,
+// regional formats) from HKCU as a .reg file the sandbox imports at logon. Only an allow-list of values is read.
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensureDir, errMsg, fileExists, isWin, runPowerShell } from '../core/util.js';
+const VALUES = {
+    'Software\\Microsoft\\Windows\\CurrentVersion\\Themes\\Personalize': ['AppsUseLightTheme', 'SystemUsesLightTheme', 'EnableTransparency', 'ColorPrevalence'],
+    'Software\\Microsoft\\Windows\\DWM': ['AccentColor', 'AccentColorInactive', 'ColorizationColor', 'ColorizationAfterglow', 'ColorizationColorBalance', 'ColorPrevalence', 'EnableWindowColorization'],
+    'Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\Accent': ['AccentPalette', 'AccentColorMenu', 'StartColorMenu'],
+    'Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\Advanced': ['TaskbarAl', 'TaskbarSi', 'TaskbarDa', 'TaskbarMn', 'TaskbarGlomLevel', 'ShowTaskViewButton', 'Hidden', 'HideFileExt', 'ShowSuperHidden', 'LaunchTo', 'NavPaneExpandToCurrentFolder', 'NavPaneShowAllFolders', 'ShowCopilotButton', 'Start_TrackDocs', 'Start_Layout'],
+    'Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\StuckRects3': ['Settings'],
+    'Software\\Microsoft\\Windows\\CurrentVersion\\Search': ['SearchboxTaskbarMode'],
+    'Control Panel\\Desktop': ['WallpaperStyle', 'TileWallpaper', 'MenuShowDelay', 'CursorBlinkRate', 'DragFullWindows', 'FontSmoothing', 'FontSmoothingType', 'UserPreferencesMask'],
+    'Control Panel\\Colors': ['Background', 'Hilight', 'HotTrackingColor'],
+    'Control Panel\\Mouse': ['MouseSpeed', 'MouseSensitivity', 'MouseThreshold1', 'MouseThreshold2', 'DoubleClickSpeed', 'SwapMouseButtons'],
+    'Control Panel\\Keyboard': ['KeyboardDelay', 'KeyboardSpeed'],
+    'Control Panel\\International': ['sShortDate', 'sLongDate', 'sShortTime', 'sTimeFormat', 'iFirstDayOfWeek', 'sDecimal', 'sThousand', 'sList', 'iMeasure', 'iTime', 'iTLZero'],
+    'Control Panel\\Accessibility\\StickyKeys': ['Flags'],
+};
+const toHex = (bytes) => [...bytes].map((b) => b.toString(16).padStart(2, '0')).join(',');
+const regString = (s) => '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+/** Formats captured values as a .reg file (UTF-16 friendly text; written as UTF-16LE with BOM). */
+export const toRegFile = (values) => {
+    const byKey = new Map();
+    for (const v of values)
+        byKey.set(v.key, [...(byKey.get(v.key) ?? []), v]);
+    const lines = ['Windows Registry Editor Version 5.00', ''];
+    for (const [key, list] of byKey) {
+        lines.push('[HKEY_CURRENT_USER\\' + key + ']');
+        for (const v of list) {
+            const name = regString(v.name);
+            switch (v.kind) {
+                case 'DWord':
+                    lines.push(name + '=dword:' + (Number(v.value) >>> 0).toString(16).padStart(8, '0'));
+                    break;
+                case 'QWord':
+                    lines.push(name + '=hex(b):' + toHex(Buffer.from(BigInt.asUintN(64, BigInt(v.value)).toString(16).padStart(16, '0'), 'hex').reverse()));
+                    break;
+                case 'Binary':
+                    lines.push(name + '=hex:' + toHex(Buffer.from(String(v.value), 'base64')));
+                    break;
+                case 'ExpandString':
+                    lines.push(name + '=hex(2):' + toHex(Buffer.from(String(v.value) + '\0', 'utf16le')));
+                    break;
+                case 'MultiString':
+                    lines.push(name + '=hex(7):' + toHex(Buffer.from(v.value.join('\0') + '\0\0', 'utf16le')));
+                    break;
+                default: lines.push(name + '=' + regString(String(v.value)));
+            }
+        }
+        lines.push('');
+    }
+    return lines.join('\r\n');
+};
+const CAPTURE_SCRIPT = (spec) => [
+    '$ErrorActionPreference = "SilentlyContinue"',
+    '$spec = \'' + JSON.stringify(spec).replace(/'/g, "''") + '\' | ConvertFrom-Json',
+    '$out = @()',
+    'foreach ($p in $spec.PSObject.Properties) {',
+    '  $key = Get-Item -LiteralPath ("HKCU:\\" + $p.Name)',
+    '  if (-not $key) { continue }',
+    '  foreach ($name in $p.Value) {',
+    '    $raw = $key.GetValue($name, $null, "DoNotExpandEnvironmentNames")',
+    '    if ($null -eq $raw) { continue }',
+    '    $kind = $key.GetValueKind($name).ToString()',
+    '    if ($kind -eq "Binary") { $raw = [Convert]::ToBase64String([byte[]]$raw) }',
+    '    $out += [pscustomobject]@{ key = $p.Name; name = $name; kind = $kind; value = $raw }',
+    '  }',
+    '}',
+    '$wall = (Get-ItemProperty -LiteralPath "HKCU:\\Control Panel\\Desktop").WallPaper',
+    '[pscustomobject]@{ values = $out; wallpaper = $wall } | ConvertTo-Json -Depth 5 -Compress',
+].join('\n');
+/** Writes personalize.reg (+ the wallpaper image) into `<launch>\personalize`. Returns a short summary. */
+export const capturePersonalization = (launchPath) => {
+    if (!isWin)
+        return 'skipped (not Windows)';
+    try {
+        const { status, stdout } = runPowerShell(CAPTURE_SCRIPT(VALUES), true);
+        if (status !== 0)
+            return 'skipped (registry read failed)';
+        // runPowerShell has PowerShell write UTF-8 (non-ASCII date formats and wallpaper paths survive); a BOM is tolerated.
+        const parsed = JSON.parse(stdout.replace(/^/, '').trim());
+        const values = parsed.values === null ? [] : Array.isArray(parsed.values) ? parsed.values : [parsed.values];
+        const dir = path.join(launchPath, 'personalize');
+        ensureDir(dir);
+        fs.writeFileSync(path.join(dir, 'personalize.reg'), '' + toRegFile(values), 'utf16le');
+        const wallpaper = parsed.wallpaper ?? '';
+        const themesCopy = path.join(process.env.APPDATA ?? '', 'Microsoft', 'Windows', 'Themes', 'TranscodedWallpaper');
+        const source = fileExists(wallpaper) ? wallpaper : fileExists(themesCopy) ? themesCopy : null;
+        if (source)
+            fs.copyFileSync(source, path.join(dir, 'wallpaper' + (path.extname(source) || '.jpg')));
+        return values.length + ' settings' + (source ? ' + wallpaper' : '');
+    }
+    catch (e) {
+        return 'skipped (' + errMsg(e) + ')';
+    }
+};