windows-development-sandbox 1.0.5 → 1.4.0

package/dist/host/generate.js

@@ -1,160 +1,77 @@
+// 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 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' : '';
+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),
+});
+/**
+ * env.cmd, which logon.cmd calls before it opens Windows Terminal: Terminal expands "%AGENT_WORKSPACE%" (the starting
+ * folder of new tabs) from its own environment, and the runtime only sets the variable machine-wide after Terminal
+ * started. `%` is doubled for cmd; a Windows path holds no quotes.
+ */
+export const logonEnv = (workspace) => '@set "AGENT_WORKSPACE=' + workspace.replace(/[\r\n"]/g, '').replace(/%/g, '%%') + '"\r\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.');
+    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 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 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 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 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,
@@ -170,16 +87,22 @@ export const generateSandbox = (o) => {
         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) },
+        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,
+        pageFileMb: config.sandbox.pageFileMb,
+        apps: config.apps,
+        auditProcesses: config.audit.enabled && config.audit.processes,
     };
     const sessionPath = path.join(launchPath, 'session.json');
     writeJson(sessionPath, session);
+    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');
-    return { wsbPath, launchPath, launchId, sessionPath, memoryMb, mappings, profile, personalization, databases, toolchains: toolchainDecisions };
+    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,54 @@
+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';
+import { guestGitDir, planView } from '../workspace-view/index.js';
+export const collectMappings = (o, launchPath, boot = { roots: [], projects: [], notes: [] }) => {
+    const { config, dataPath, workspaceHost, harnessName } = o.run;
+    assertGuestPath(config.guestWorkspace, 'guestWorkspace');
+    // workspaceFilter: the sandbox gets the project's filtered view (no git-ignored files) and its real .git beside it.
+    const view = planView(config, o.run.storageRoot, workspaceHost);
+    const mappings = [
+        { host: launchPath, guest: GUEST.launch, readOnly: true },
+        { host: dataPath, guest: GUEST.data, readOnly: false },
+        { host: view ? view.options.view : workspaceHost, guest: config.guestWorkspace, readOnly: config.readOnly },
+        ...(view?.hostGit ? [{ host: view.hostGit, guest: guestGitDir(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', 'netproxy.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/motw.d.ts

@@ -0,0 +1,17 @@
+/** What Windows runs when you open it (not source files such as .js or .py: those need a program you choose). */
+export declare const RISKY: RegExp;
+/** Marks one file if it is a program or script (and a plain file, not a link). Returns true when it marked it. */
+export declare const markFromSandbox: (file: string) => boolean;
+/** Has this file the mark? */
+export declare const isMarked: (file: string) => boolean;
+/** Watches the projects while the sandbox runs and marks what appears or changes; returns a function that stops it. */
+export declare const watchAndMark: (projects: string[], note?: (message: string) => void) => (() => void);
+/** The projects to watch and mark (empty: storage.markSandboxFiles is off). */
+export declare const saveMarkedProjects: (storageRoot: string, dataPath: string, projects: string[]) => void;
+export declare const readMarkedProjects: (storageRoot: string, dataPath: string) => string[];
+/** The data folder's size, measured by the watcher when a sandbox closes (measuring at launch would be slow). */
+export declare const saveDataSize: (storageRoot: string, dataPath: string, bytes: number) => void;
+export declare const readDataSize: (storageRoot: string, dataPath: string) => {
+    bytes: number;
+    at: string;
+} | null;