windows-development-sandbox 1.0.5 → 1.1.0

package/dist/host/database-plan.js

@@ -0,0 +1,52 @@
+import { DATABASES, detectDatabases } from '../core/detect-databases.js';
+import { hostDatabases } from './pc-scan.js';
+import { readProjectFiles } from './project-scan.js';
+/** The version a compose file pins (postgres:16-alpine -> 16, mongo:7.0 -> 7.0), if any. */
+const pinnedVersion = (files, image) => {
+    for (const file of files) {
+        const match = image.exec(file.text);
+        if (match?.[1] && /^\d+(\.\d+)?/.test(match[1]))
+            return /^\d+(\.\d+)?/.exec(match[1])[0];
+    }
+    return null;
+};
+/**
+ * What to run in this sandbox: databases set to true, plus "auto" ones the project needs. SQL Server is reported (so
+ * the user hears about it) but cannot run inside Windows Sandbox.
+ */
+export const planDatabases = (config, workspace, probe = {}) => {
+    const autos = DATABASES.filter((db) => config[db].enabled === 'auto');
+    const files = autos.length ? probe.files ?? readProjectFiles(workspace) : [];
+    const detected = autos.length ? detectDatabases(files, probe.host ?? hostDatabases) : [];
+    const plan = databasePlanner(config, files.filter((f) => /compose/i.test(f.path)));
+    return DATABASES.flatMap((database) => {
+        const setting = config[database].enabled;
+        const found = detected.find((d) => d.database === database);
+        if (setting === true)
+            return [plan(database, ['enabled in config'])];
+        if (setting === 'auto' && found)
+            return [plan(database, found.reasons)];
+        return [];
+    });
+};
+/** Every database the sandbox can run, so `sbx-db start <name>` works for ones that did not start at boot. */
+export const databaseCatalog = (config) => {
+    const plan = databasePlanner(config, []);
+    return DATABASES.filter((db) => db !== 'sqlserver').map((db) => plan(db, ['started with sbx-db']));
+};
+/** Version (a compose file's image tag wins), port and admin UI for one database. */
+const databasePlanner = (config, compose) => {
+    const versions = {
+        postgres: pinnedVersion(compose, /image:\s*["']?(?:[\w.-]+\/)*postgres:([\w.-]+)/i) ?? (config.postgres.version === 'latest' ? 'latest' : config.postgres.version),
+        mysql: config.mysql.version,
+        mongodb: pinnedVersion(compose, /image:\s*["']?(?:[\w.-]+\/)*mongo:([\w.-]+)/i) ?? config.mongodb.version,
+        redis: 'latest',
+        dynamodb: 'latest',
+        sqlserver: '',
+    };
+    const ports = { postgres: config.postgres.port, mysql: config.mysql.port, mongodb: config.mongodb.port, redis: config.redis.port, dynamodb: config.dynamodb.port, sqlserver: 1433 };
+    return (database, reasons) => ({
+        database, reasons, version: versions[database], port: ports[database],
+        ...(database === 'dynamodb' && config.dynamodb.admin ? { adminPort: config.dynamodb.adminPort } : {}),
+    });
+};

package/dist/host/generate.d.ts

@@ -1,15 +1,7 @@
-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;
+import type { GenerateOptions, Generated } from '../core/types.js';
+import { decideToolchains } from '../core/detect-toolchains.js';
+/** Which toolchains the project needs ("auto" settings follow the project's files and what this PC has). */
+export declare const decideProjectToolchains: (o: Pick<GenerateOptions, "run" | "pcLanguages">) => ReturnType<typeof decideToolchains>;
 export declare const generateSandbox: (o: GenerateOptions) => Generated & {
     personalization: string;
 };

package/dist/host/generate.js

@@ -1,160 +1,71 @@
+// 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),
+});
 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,10 +81,12 @@ 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,
     };
     const sessionPath = path.join(launchPath, 'session.json');
     writeJson(sessionPath, session);
@@ -181,5 +94,5 @@ export const generateSandbox = (o) => {
     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,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;