windows-development-sandbox 0.0.0-stage → 1.0.5

package/dist/core/workspace.d.ts

@@ -0,0 +1,23 @@
+import type { Config, Overrides, ResolvedRun, RunRequest, ToolVersions } from './types.js';
+export declare const askYesNo: (question: string) => Promise<boolean>;
+/** A read/write folder mapped into the sandbox must not contain, or sit inside, any protected folder. */
+export declare const assertSafeMapping: (folder: string, packageRoot: string, storageRoot: string) => void;
+/** The agent gets read/write access to the workspace, so refuse folders that would let it reach the tool itself, its storage, or the OS. */
+export declare const assertSafeWorkspace: (workspace: string, packageRoot: string, storageRoot: string) => void;
+/**
+ * 'auto' guest workspace: C:\Workspace\<folder name>. Keeping the real folder name means Claude's per-project history
+ * and claude-mem's project name match this PC instead of every project being "Workspace".
+ */
+export declare const autoGuestWorkspace: (workspaceHost: string) => string;
+/** The Node version a Volta project pins ("volta": { "node": "20.11.1" } in package.json), so nvm defaults to it too. */
+export declare const voltaNode: (workspace: string) => string | null;
+/**
+ * Picks tool versions. Highest priority first: command line, the folder's .sandbox-config.json,
+ * version files in the workspace (.nvmrc, .node-version, .python-version), the tool config, this PC's node version.
+ */
+export declare const resolveVersions: (config: Config, workspace: string, local: Overrides, req: {
+    nodeVersion?: string;
+    pythonVersion?: string;
+}, hostNodeVersion: string) => ToolVersions;
+/** Precedence (lowest to highest): built-in defaults, user config, .sandbox-config.json in the workspace, command-line flags. */
+export declare const resolveRun: (req: RunRequest, hostNodeVersion?: string) => Promise<ResolvedRun>;

package/dist/core/workspace.js

@@ -0,0 +1,162 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { z } from 'zod';
+import { userDir } from './config.js';
+import { planMirrorWorkspace } from '../shared/guest-paths.js';
+import { DATABASES } from './detect-databases.js';
+import { applyOverrides, describeOverrides, isTrusted, normalizeOverrides, readLocalConfig, saveTrust, trustStorePath } from './local-config.js';
+import { dirExists, expandPath, fail, fileExists, isInsideOrEqual, isRootPath, isUserProfile } from './util.js';
+export const askYesNo = async (question) => {
+    if (!process.stdin.isTTY)
+        return false;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => rl.question(question + ' [y/N] ', resolve));
+    rl.close();
+    return /^y(es)?$/i.test(answer.trim());
+};
+/** Folders the agent must never be able to write: the tool itself, its storage and your settings for it. */
+const protectedFolders = (packageRoot, storageRoot) => [
+    ['this tool\'s install folder', packageRoot],
+    ['the sandbox storage folder', storageRoot],
+    ['your sandbox settings folder', userDir()],
+];
+/** A read/write folder mapped into the sandbox must not contain, or sit inside, any protected folder. */
+export const assertSafeMapping = (folder, packageRoot, storageRoot) => {
+    if (isRootPath(folder) || isUserProfile(folder))
+        fail('A whole drive or user profile cannot be mapped into the sandbox: ' + folder, 'Map a specific folder instead.');
+    for (const [label, dir] of protectedFolders(packageRoot, storageRoot)) {
+        if (isInsideOrEqual(dir, folder) || isInsideOrEqual(folder, dir))
+            fail(folder + ' cannot be mapped into the sandbox: it overlaps ' + label + ' (' + dir + ').', 'Map a folder that is not inside (and does not contain) ' + dir + '.');
+    }
+};
+/** The agent gets read/write access to the workspace, so refuse folders that would let it reach the tool itself, its storage, or the OS. */
+export const assertSafeWorkspace = (workspace, packageRoot, storageRoot) => {
+    if (isRootPath(workspace))
+        fail('A whole drive cannot be the workspace: ' + workspace, 'Run sandbox claude from a project folder (or pass --workspace <folder>).');
+    if (isUserProfile(workspace))
+        fail('Your whole user profile cannot be the workspace: ' + workspace, 'Run sandbox claude from a project folder (or pass --workspace <folder>).');
+    for (const [label, dir] of protectedFolders(packageRoot, storageRoot)) {
+        if (isInsideOrEqual(dir, workspace))
+            fail(workspace + ' cannot be the workspace: it is inside ' + label + ' (' + dir + '), so the agent could change the code that runs on this PC.', dir === packageRoot ? 'Developing windows-development-sandbox itself? Install it as a copy instead of a link: run `npm run install:global` in the repository, then sandbox claude works there.' : 'Run sandbox claude from a project folder somewhere else.');
+        if (isInsideOrEqual(workspace, dir))
+            fail(workspace + ' cannot be the workspace: it contains ' + label + ' (' + dir + '), which the agent must not be able to change.', 'Run sandbox claude from a project folder that does not contain it.');
+    }
+    for (const name of ['WINDIR', 'ProgramFiles', 'ProgramFiles(x86)', 'ProgramData']) {
+        const dir = process.env[name];
+        if (dir && isInsideOrEqual(dir, workspace))
+            fail('A system folder cannot be the workspace: ' + workspace, 'Run sandbox claude from a project folder.');
+    }
+};
+/**
+ * 'auto' guest workspace: C:\Workspace\<folder name>. Keeping the real folder name means Claude's per-project history
+ * and claude-mem's project name match this PC instead of every project being "Workspace".
+ */
+export const autoGuestWorkspace = (workspaceHost) => {
+    const name = path.basename(workspaceHost).replace(/[^A-Za-z0-9._ -]/g, '_').replace(/^[. ]+|[. ]+$/g, '');
+    return 'C:\\Workspace\\' + (name || 'project');
+};
+const firstLine = (file) => {
+    if (!fileExists(file))
+        return null;
+    const line = fs.readFileSync(file, 'utf8').replace(/^/, '').split(/\r?\n/).map((l) => l.replace(/#.*$/, '').trim()).find((l) => l !== '');
+    return line ?? null;
+};
+const VOLTA_PIN = 'package.json volta.node';
+const PackageJson = z.object({ volta: z.object({ node: z.string().regex(/^\d+(\.\d+){0,2}$/).optional() }).optional() });
+/** The Node version a Volta project pins ("volta": { "node": "20.11.1" } in package.json), so nvm defaults to it too. */
+export const voltaNode = (workspace) => {
+    const file = path.join(workspace, 'package.json');
+    if (!fileExists(file))
+        return null;
+    try {
+        return PackageJson.safeParse(JSON.parse(fs.readFileSync(file, 'utf8').replace(/^/, ''))).data?.volta?.node ?? null;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Picks tool versions. Highest priority first: command line, the folder's .sandbox-config.json,
+ * version files in the workspace (.nvmrc, .node-version, .python-version), the tool config, this PC's node version.
+ */
+export const resolveVersions = (config, workspace, local, req, hostNodeVersion) => {
+    const localTools = (local.toolchains ?? {});
+    const pick = (cli, localValue, files, configured) => {
+        if (cli)
+            return { spec: cli, source: 'command line' };
+        if (localValue)
+            return { spec: localValue, source: '.sandbox-config.json' };
+        for (const name of files) {
+            const value = name === VOLTA_PIN ? voltaNode(workspace) : firstLine(path.join(workspace, name));
+            if (value)
+                return { spec: value, source: name };
+        }
+        return { spec: configured, source: 'config' };
+    };
+    let node = pick(req.nodeVersion, localTools.node?.version, ['.nvmrc', '.node-version', VOLTA_PIN], config.toolchains.node.version);
+    if (node.spec === 'host')
+        node = { spec: hostNodeVersion.replace(/^v/, ''), source: 'this PC' };
+    const python = pick(req.pythonVersion, localTools.python?.version, ['.python-version'], config.toolchains.python.version);
+    return { node, nodeExtra: config.toolchains.node.extraVersions, python };
+};
+/** Precedence (lowest to highest): built-in defaults, user config, .sandbox-config.json in the workspace, command-line flags. */
+export const resolveRun = async (req, hostNodeVersion = process.version) => {
+    const notes = [];
+    // Mappings from the user config are relative to that config file; expand them before anything else uses them.
+    let config = { ...req.loaded.config, mappings: req.loaded.config.mappings.map((m) => ({ ...m, host: expandPath(m.host, req.loaded.base) })) };
+    const storageRoot = expandPath(config.storage.root, req.loaded.base);
+    const workspaceHost = path.resolve(req.workspace ?? req.cwd);
+    if (!dirExists(workspaceHost))
+        fail('The workspace folder does not exist: ' + workspaceHost, 'Check the --workspace path, or cd into the project first.');
+    assertSafeWorkspace(workspaceHost, req.packageRoot, storageRoot);
+    const scripts = [];
+    let localConfigPath = null;
+    let overrides = {};
+    const local = req.noLocalConfig ? null : readLocalConfig(workspaceHost);
+    if (local) {
+        overrides = normalizeOverrides(local.data, workspaceHost, local.path);
+        const store = trustStorePath(storageRoot);
+        if (!isTrusted(store, local.path, local.hash)) {
+            const summary = describeOverrides(overrides);
+            let trusted = req.trustConfig;
+            if (!trusted && req.ask) {
+                console.log('\nFound ' + local.path + ' which is not trusted yet. It would apply:');
+                for (const line of summary)
+                    console.log('  ' + line);
+                trusted = await req.ask('Trust and use this file?');
+            }
+            if (!trusted)
+                fail(local.path + ' has not been approved yet (a repo can ship this file, so it needs your OK). It would apply:\n  ' + (summary.join('\n  ') || '(no changes)'), 'Review it, then run again in an interactive terminal and answer y, or add --trust-config. To ignore the file: --no-local-config');
+            saveTrust(store, local.path, local.hash);
+            notes.push('Trusted ' + local.path + ' (you will only be asked again if the file changes).');
+        }
+        config = applyOverrides(config, overrides);
+        scripts.push(...(overrides.scripts ?? []));
+        localConfigPath = local.path;
+        notes.push('Using ' + local.path);
+    }
+    if (req.headless !== undefined)
+        config = { ...config, sandbox: { ...config.sandbox, headless: req.headless } };
+    for (const name of req.databases ?? []) {
+        const db = name.toLowerCase();
+        if (!DATABASES.includes(db))
+            fail('Unknown database "' + name + '".', 'Choose from: ' + DATABASES.join(', '));
+        config = { ...config, databases: { ...config.databases, [db]: { ...config.databases[db], enabled: true } } };
+    }
+    if (config.guestWorkspace === 'auto')
+        config = { ...config, guestWorkspace: autoGuestWorkspace(workspaceHost) };
+    else if (config.guestWorkspace === 'mirror') {
+        const plan = planMirrorWorkspace(workspaceHost, autoGuestWorkspace(workspaceHost));
+        if (plan.note)
+            notes.push(plan.note);
+        config = { ...config, guestWorkspace: plan.guest };
+    }
+    scripts.push(...req.scripts.map((s) => path.resolve(s)));
+    const harnessName = req.noAgent ? 'none' : (req.harness ?? config.defaultHarness);
+    if (harnessName !== 'none' && !config.harnesses[harnessName])
+        fail('Unknown agent "' + harnessName + '".', 'Configured agents: ' + Object.keys(config.harnesses).join(', ') + ' (add more under "harnesses" in your config).');
+    const versions = resolveVersions(config, workspaceHost, overrides, req, hostNodeVersion);
+    const dataPath = path.join(storageRoot, 'data', config.storage.dataName);
+    return { config, storageRoot, dataPath, workspaceHost, harnessName, scripts, localConfigPath, notes, versions };
+};

package/dist/guest/daemon.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/guest/daemon.js

@@ -0,0 +1,186 @@
+// Session daemon (runs detached inside the sandbox for its whole life). It is the only thing that acts on host
+// requests, and it only knows four request kinds: start a session, run a command, restart sessions, ping.
+// It must never die quietly: every iteration is guarded, and anything unexpected is written to its log.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn, spawnSync } from 'node:child_process';
+import { FrameType, sendControl } from '../shared/pty-client.js';
+import { SYSTEM } from '../shared/system.js';
+import { commandLine, ensurePtyHost, freePort, ptyHostLogTail, startPtyHost, waitForPtyHost } from './ptyhost.js';
+import { provisionHarness, resolveLaunch } from './setup/agents.js';
+import { saveClaudeMem } from './setup/claude.js';
+import { runHooks } from './setup/hooks.js';
+import { guestAddresses } from './setup/network.js';
+import { now, readSession, scanRequests, writeJsonAtomic } from '../shared/rundir.js';
+import { dataDir, errMsg, exists, isWin, log, run, session, toolsDir, warn, workspace } from './env.js';
+const MAX_OUTPUT = 1024 * 1024;
+const MAX_MESSAGE = 3500;
+const live = new Map();
+let starting = 0;
+let lastMemSave = Date.now();
+process.on('uncaughtException', (e) => warn('daemon: unexpected error (continuing): ' + (e.stack ?? errMsg(e))));
+process.on('unhandledRejection', (e) => warn('daemon: unexpected error (continuing): ' + errMsg(e)));
+const insideWorkspace = (cwd) => {
+    const rel = path.relative(workspace.toLowerCase(), path.resolve(cwd).toLowerCase());
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+};
+/** Status/response writes are best-effort: a briefly locked file (antivirus, the host's sync) must not kill the daemon. */
+const tryWrite = (file, value) => { try {
+    writeJsonAtomic(file, value);
+}
+catch (e) {
+    warn('Could not write ' + file + ': ' + errMsg(e));
+} };
+const respond = (id, result) => tryWrite(run.response(id), { id, ...result, message: result.message.slice(0, MAX_MESSAGE), finishedAt: now() });
+const saveStatus = (status) => tryWrite(run.session(status.id), { ...status, message: status.message.slice(0, MAX_MESSAGE), updatedAt: now() });
+const safely = (what, work) => { try {
+    work();
+}
+catch (e) {
+    warn(what + ' failed: ' + errMsg(e));
+} };
+const terminalTab = (id, title, cwd) => {
+    const view = [process.execPath, path.join(path.dirname(process.argv[1]), 'view.js'), id];
+    const wt = path.join(toolsDir, 'terminal', 'wt.exe');
+    if (exists(wt))
+        spawn(wt, ['-w', '0', 'nt', '--title', title, '-d', cwd, ...view], { detached: true, stdio: 'ignore' }).unref();
+    else
+        spawn(SYSTEM.cmd(), ['/d', '/c', 'start', title, ...view], { detached: true, stdio: 'ignore', cwd }).unref();
+};
+const onExit = (running) => (code) => {
+    live.delete(running.id);
+    const tail = code === 0 ? '' : ptyHostLogTail(running.id, 6);
+    saveStatus({ ...running, phase: 'exited', message: running.harness + ' exited with code ' + code + (tail ? '. Last output:\n' + tail : ''), exitCode: code ?? 1, attach: undefined });
+    log('Session ' + running.id + ' ended (exit ' + code + ')');
+    safely('post-agent hooks', () => runHooks('post-agent', process.env));
+    safely('claude-mem save', saveClaudeMem);
+    maybeShutdown();
+};
+const startSession = async (req) => {
+    const status = { id: req.id, launchId: session.launchId, harness: req.harness, cwd: req.cwd, phase: 'starting', message: 'Starting ' + req.harness, updatedAt: now(), startedAt: now() };
+    saveStatus(status);
+    starting++;
+    try {
+        if (!insideWorkspace(req.cwd) || !exists(req.cwd))
+            throw new Error('Folder is not inside the sandbox workspace ' + workspace + ': ' + req.cwd);
+        const harness = req.harness === session.harnessName && session.harness ? session.harness : null;
+        if (!harness)
+            throw new Error('Agent "' + req.harness + '" is not configured for this sandbox (it runs ' + session.harnessName + ').');
+        // Never refresh here: main already did, and replacing a running agent's executable would fail.
+        provisionHarness(req.harness, harness, process.env, false);
+        const launch = resolveLaunch(req.harness, harness);
+        const base = [...launch.args, ...harness.arguments];
+        const port = await freePort();
+        const token = crypto.randomBytes(24).toString('base64url');
+        const remote = session.networking && session.attach.enabled;
+        const child = startPtyHost({
+            exe: ensurePtyHost(), port, token, cols: 120, rows: 32, id: req.id, cwd: req.cwd, env: { ...process.env, ...harness.environment }, remote,
+            command: commandLine(launch.file, [...base, ...req.args]), restartCommand: commandLine(launch.file, [...base, ...(harness.resumeArguments ?? [])]),
+        });
+        try {
+            await waitForPtyHost(child, port, 15000);
+        }
+        catch (e) {
+            const tail = ptyHostLogTail(req.id);
+            throw new Error(errMsg(e) + (tail ? '. From its log:\n' + tail : '') + '\nLog: ' + path.join(dataDir, 'logs', 'ptyhost-' + req.id + '.log'));
+        }
+        const running = { ...status, phase: 'running', message: req.harness + ' is running', attach: { addresses: remote ? guestAddresses() : [], port, token } };
+        live.set(req.id, { status: running, child });
+        child.once('exit', onExit(running));
+        saveStatus(running);
+        log('Session ' + req.id + ' started (' + req.harness + ' in ' + req.cwd + ', port ' + port + ')');
+        if (req.id !== session.launchId && process.env.AGENT_NO_TABS !== '1')
+            terminalTab(req.id, req.harness + ' ' + path.basename(req.cwd), req.cwd);
+    }
+    catch (e) {
+        saveStatus({ ...status, phase: 'failed', message: errMsg(e) });
+        warn('Session ' + req.id + ' failed: ' + errMsg(e));
+        maybeShutdown();
+    }
+    finally {
+        starting--;
+    }
+};
+const quoteForCmd = (a) => (/[\s"&|<>^]/.test(a) ? '"' + a.replace(/"/g, '""') + '"' : a);
+/** Runs a command for the host without blocking the daemon (other requests and pings keep being answered). */
+const execCommand = (req) => {
+    if (!insideWorkspace(req.cwd) || !exists(req.cwd)) {
+        respond(req.id, { ok: false, message: 'Folder is not inside the sandbox workspace: ' + req.cwd });
+        return;
+    }
+    // chcp 65001 first: console programs then write UTF-8 (not the OEM code page) into the pipes.
+    const child = spawn(SYSTEM.cmd(), ['/d', '/s', '/c', '"chcp 65001>nul & ' + req.command.map(quoteForCmd).join(' ') + '"'], { cwd: req.cwd, env: process.env, windowsHide: true, windowsVerbatimArguments: true });
+    const output = { stdout: '', stderr: '' };
+    // setEncoding decodes across chunks: a multi-byte character split between two reads is not mangled.
+    const collect = (key) => (d) => { if (output[key].length < MAX_OUTPUT)
+        output[key] += d; };
+    child.stdout.setEncoding('utf8').on('data', collect('stdout'));
+    child.stderr.setEncoding('utf8').on('data', collect('stderr'));
+    const timer = setTimeout(() => child.kill(), Math.min(req.timeoutSeconds, 3600) * 1000);
+    const cap = (s) => (s.length > MAX_OUTPUT ? s.slice(0, MAX_OUTPUT) + '\n[output truncated]' : s);
+    child.on('error', (e) => { clearTimeout(timer); respond(req.id, { ok: false, message: 'Could not run the command: ' + errMsg(e) }); });
+    child.on('close', (code) => {
+        clearTimeout(timer);
+        respond(req.id, { ok: code === 0, message: code === null ? 'stopped after ' + req.timeoutSeconds + ' s' : 'exit ' + code, exitCode: code ?? -1, stdout: cap(output.stdout), stderr: cap(output.stderr) });
+    });
+};
+const restart = async (req) => {
+    const targets = [...live.values()].filter((s) => s.status.attach && (req.harness === null || s.status.harness === req.harness));
+    for (const s of targets)
+        await sendControl({ addresses: ['127.0.0.1'], port: s.status.attach.port, token: s.status.attach.token }, FrameType.Restart);
+    respond(req.id, { ok: true, message: 'restarted ' + targets.length + ' session(s)' });
+};
+const handle = (req) => {
+    switch (req.kind) {
+        case 'session': return startSession(req);
+        case 'exec': return execCommand(req);
+        case 'restart': return restart(req);
+        case 'ping': return respond(req.id, { ok: true, message: 'pong (' + live.size + ' session(s) running)' });
+    }
+};
+/** A headless sandbox with nothing running (or starting) only wastes RAM, so it shuts itself down. */
+const maybeShutdown = () => {
+    if (!session.headless || !isWin)
+        return;
+    const idle = () => live.size === 0 && starting === 0 && scanRequests(dataDir).valid.length === 0;
+    if (!idle())
+        return;
+    setTimeout(() => {
+        if (!idle())
+            return;
+        log('Headless sandbox has no sessions left; shutting down.');
+        safely('claude-mem save', saveClaudeMem);
+        spawnSync(SYSTEM.shutdown(), ['/s', '/t', '5'], { windowsHide: true });
+    }, 15000);
+};
+const tick = () => {
+    const { valid, invalid } = scanRequests(dataDir);
+    // Anything in requests/ that is not a valid request (wrong kind, bad id, junk) is deleted unread.
+    for (const file of invalid)
+        safely('removing an invalid request', () => fs.rmSync(file, { recursive: true, force: true }));
+    for (const req of valid) {
+        safely('claiming a request', () => fs.rmSync(run.request(req.id), { force: true }));
+        if (readSession(dataDir, req.id))
+            continue;
+        // Not awaited: starting a session or running a command must not hold up other requests.
+        void Promise.resolve(handle(req)).catch((e) => respond(req.id, { ok: false, message: errMsg(e) }));
+    }
+    if (Date.now() - lastMemSave > 120000) {
+        lastMemSave = Date.now();
+        safely('claude-mem save', saveClaudeMem);
+    }
+};
+const loop = () => {
+    try {
+        tick();
+    }
+    catch (e) {
+        warn('daemon loop: ' + errMsg(e));
+    }
+    finally {
+        setTimeout(loop, 400);
+    }
+};
+log('Session daemon started (pid ' + process.pid + ').');
+loop();

package/dist/guest/db.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/guest/db.js

@@ -0,0 +1,60 @@
+// `sbx-db`: list, start and stop the sandbox's databases from a terminal inside it (`sandbox db` on the PC runs it too).
+// Usage: sbx-db [list] | sbx-db start <name> | sbx-db stop <name>
+import { DATABASE_NAMES, portOpen, setupDatabase, stopDatabase } from './toolchains/databases.js';
+import { emptyEnv } from './toolchains/common.js';
+import { addMachineEnvironment } from './setup/environment.js';
+import { errMsg, session } from './env.js';
+const USAGE = 'Usage: sbx-db [list] | sbx-db start <name> | sbx-db stop <name>';
+/** Boot's own plans first (their versions and ports were chosen for this project), then everything else. */
+const plans = () => {
+    const boot = session.databases ?? [];
+    return [...boot, ...(session.databaseCatalog ?? []).filter((c) => !boot.some((b) => b.database === c.database))];
+};
+const find = (name) => {
+    const all = plans();
+    const plan = all.find((p) => p.database === name?.toLowerCase());
+    if (!plan)
+        throw new Error((name ? 'Unknown database "' + name + '". ' : '') + 'Choose one of: ' + all.map((p) => p.database).join(', '));
+    if (plan.database === 'sqlserver')
+        throw new Error('SQL Server cannot run inside Windows Sandbox.');
+    return plan;
+};
+const list = async () => {
+    for (const p of plans().filter((x) => x.database !== 'sqlserver')) {
+        const state = (await portOpen(p.port)) ? 'running' : 'stopped';
+        console.log(p.database.padEnd(10) + state.padEnd(9) + 'port ' + p.port + '  ' + DATABASE_NAMES[p.database]);
+    }
+    return 0;
+};
+const start = async (name) => {
+    const plan = find(name);
+    if (await portOpen(plan.port)) {
+        console.log(plan.database + ' is already running on port ' + plan.port + '.');
+        return 0;
+    }
+    console.log('Starting ' + DATABASE_NAMES[plan.database] + ' (the first time downloads it) ...');
+    const env = emptyEnv();
+    await setupDatabase(env, plan);
+    addMachineEnvironment(env.vars, env.prepend);
+    for (const line of env.summary)
+        console.log('  ' + line);
+    console.log('New terminal tabs have its variables and tools; this one does not.');
+    return 0;
+};
+const stop = async (name) => {
+    const plan = find(name);
+    console.log((await stopDatabase(plan)) ? 'Stopped ' + plan.database + '.' : plan.database + ' was not running.');
+    return 0;
+};
+const main = (args) => {
+    const [action = 'list', name] = args;
+    if (action === 'list')
+        return list();
+    if (action === 'start')
+        return start(name);
+    if (action === 'stop')
+        return stop(name);
+    console.error(USAGE);
+    return Promise.resolve(2);
+};
+main(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (e) => { console.error(errMsg(e)); process.exitCode = 1; });

package/dist/guest/env.d.ts

@@ -0,0 +1,49 @@
+import { type SpawnOptions, type SpawnSyncOptions } from 'node:child_process';
+import type { GuestSession, SandboxStatus } from '../core/types.js';
+export declare const isWin: boolean;
+export declare const dryRun: boolean;
+/** Real provisioning, but nothing machine-wide (environment variables): for end-to-end tests outside a sandbox. */
+export declare const testMode: boolean;
+export declare const launchDir: string;
+export declare const dataDir: string;
+export declare const hostToolsDir: string;
+/** Folders that must stay on the sandbox's own disk (symlinks, SQLite) rather than in a mapped folder. */
+export declare const localDir: string;
+export declare const toolsDir: string;
+export declare const logsDir: string;
+export declare const run: {
+    run: string;
+    sandbox: string;
+    requests: string;
+    responses: string;
+    sessions: string;
+    request: (id: string) => string;
+    response: (id: string) => string;
+    session: (id: string) => string;
+};
+export declare const session: GuestSession;
+export declare const workspace: string;
+export declare const stateDir: string;
+export declare const claudeDir: string;
+export declare const log: (message: string) => void;
+export declare const warn: (message: string) => void;
+export declare const errMsg: (e: unknown) => string;
+export declare const exists: (p: string) => boolean;
+export declare const mkdirp: (p: string) => string;
+export declare const logPath: string;
+/** Best-effort: progress reporting must never be what breaks the boot. */
+export declare const setSandboxStatus: (phase: SandboxStatus["phase"], message: string) => void;
+/** Runs a program, streaming output, and throws with a readable message when it fails. */
+export declare const exec: (file: string, args: string[], options?: SpawnSyncOptions) => void;
+/** exec without blocking: other toolchains keep downloading while this one runs an installer. */
+export declare const execAsync: (file: string, args: string[], options?: SpawnOptions) => Promise<void>;
+export declare const execOutput: (file: string, args: string[], options?: SpawnSyncOptions) => string;
+export declare const powershell: (script: string) => void;
+/** Copies a folder with robocopy (fast, restartable), or just the named files in it; exit codes below 8 mean success. */
+export declare const robocopy: (from: string, to: string, files?: string[]) => void;
+/**
+ * A Node install without its global packages (nvm keeps those per version: often tens of thousands of small files,
+ * which is what made copying from this PC slow). Same file list as Copy-NodeFromHost in sandbox/bootstrap.ps1.
+ * Copied into a staging folder and renamed into place: node.exe alone (an interrupted copy) must not look like a full install.
+ */
+export declare const copyNode: (from: string, to: string) => void;

package/dist/guest/env.js

@@ -0,0 +1,99 @@
+// Shared state for the guest scripts (main, daemon, view): fixed paths, the session description, logging, status.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { moveIntoPlace, spawnAsync, stagingFolder } from '../shared/download.js';
+import { now, runPaths, writeJsonAtomic } from '../shared/rundir.js';
+import { SYSTEM } from '../shared/system.js';
+export const isWin = process.platform === 'win32';
+export const dryRun = process.env.AGENT_DRY_RUN === '1';
+/** Real provisioning, but nothing machine-wide (environment variables): for end-to-end tests outside a sandbox. */
+export const testMode = process.env.AGENT_SANDBOX_TEST === '1';
+export const launchDir = process.env.AGENT_LAUNCH_DIR ?? 'C:\\AgentLaunch';
+export const dataDir = process.env.AGENT_DATA_DIR ?? 'C:\\AgentData';
+export const hostToolsDir = process.env.AGENT_HOST_TOOLS_DIR ?? 'C:\\HostTools';
+/** Folders that must stay on the sandbox's own disk (symlinks, SQLite) rather than in a mapped folder. */
+export const localDir = process.env.AGENT_LOCAL_DIR ?? 'C:\\nvm';
+export const toolsDir = path.join(dataDir, 'tools');
+export const logsDir = path.join(dataDir, 'logs');
+export const run = runPaths(dataDir);
+export const session = JSON.parse(fs.readFileSync(path.join(launchDir, 'session.json'), 'utf8').replace(/^\uFEFF/, ''));
+export const workspace = process.env.AGENT_WORKSPACE ?? session.workspace;
+export const stateDir = path.join(dataDir, session.persistAgentState ? 'state' : 'state-session');
+export const claudeDir = path.join(stateDir, 'claude');
+fs.mkdirSync(logsDir, { recursive: true });
+const logFile = path.join(logsDir, (process.env.AGENT_LOG_PREFIX ?? 'guest') + '-' + new Date().toISOString().replace(/[:.]/g, '-') + '.log');
+const append = (line) => { try {
+    fs.appendFileSync(logFile, line + '\n');
+}
+catch { /* logging must never break the run */ } };
+export const log = (message) => { console.log(message); append(message); };
+export const warn = (message) => { console.warn('\x1b[33mWARNING: ' + message + '\x1b[0m'); append('WARNING: ' + message); };
+export const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+export const exists = (p) => fs.existsSync(p);
+export const mkdirp = (p) => { fs.mkdirSync(p, { recursive: true }); return p; };
+export const logPath = logFile;
+/** Best-effort: progress reporting must never be what breaks the boot. */
+export const setSandboxStatus = (phase, message) => {
+    try {
+        writeJsonAtomicChecked(phase, message);
+    }
+    catch (e) {
+        warn('Could not update sandbox status: ' + errMsg(e));
+    }
+};
+const writeJsonAtomicChecked = (phase, message) => {
+    writeJsonAtomic(run.sandbox, { launchId: session.launchId, phase, message, updatedAt: now(), workspaceHost: session.workspaceHost, guestWorkspace: workspace, headless: session.headless });
+};
+/** Runs a program, streaming output, and throws with a readable message when it fails. */
+export const exec = (file, args, options = {}) => {
+    const result = spawnSync(file, args, { stdio: 'inherit', windowsHide: true, ...options });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0)
+        throw new Error(path.basename(file) + ' ' + args.slice(0, 3).join(' ') + ' failed with exit code ' + result.status);
+};
+/** exec without blocking: other toolchains keep downloading while this one runs an installer. */
+export const execAsync = async (file, args, options = {}) => {
+    const code = await spawnAsync(file, args, { stdio: 'inherit', ...options });
+    if (code !== 0)
+        throw new Error(path.basename(file) + ' ' + args.slice(0, 3).join(' ') + ' failed with exit code ' + code);
+};
+export const execOutput = (file, args, options = {}) => {
+    const result = spawnSync(file, args, { encoding: 'utf8', windowsHide: true, ...options });
+    return result.status === 0 ? String(result.stdout ?? '').trim() : '';
+};
+export const powershell = (script) => exec(SYSTEM.powershell(), ['-NoLogo', '-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', script]);
+/** Copies a folder with robocopy (fast, restartable), or just the named files in it; exit codes below 8 mean success. */
+export const robocopy = (from, to, files = []) => {
+    if (!isWin) {
+        if (!files.length) {
+            fs.cpSync(from, to, { recursive: true });
+            return;
+        }
+        fs.mkdirSync(to, { recursive: true });
+        for (const f of files.filter((f) => fs.existsSync(path.join(from, f))))
+            fs.copyFileSync(path.join(from, f), path.join(to, f));
+        return;
+    }
+    const what = files.length ? files : ['/E', '/MT:16'];
+    const result = spawnSync(SYSTEM.robocopy(), [from, to, ...what, '/NFL', '/NDL', '/NJH', '/NJS', '/NP', '/R:1', '/W:1', '/XJ'], { stdio: 'ignore', windowsHide: true });
+    if ((result.status ?? 16) >= 8)
+        throw new Error('robocopy ' + from + ' -> ' + to + ' failed (exit ' + result.status + ')');
+};
+/**
+ * A Node install without its global packages (nvm keeps those per version: often tens of thousands of small files,
+ * which is what made copying from this PC slow). Same file list as Copy-NodeFromHost in sandbox/bootstrap.ps1.
+ * Copied into a staging folder and renamed into place: node.exe alone (an interrupted copy) must not look like a full install.
+ */
+export const copyNode = (from, to) => {
+    const work = stagingFolder(to);
+    try {
+        robocopy(from, work, ['node.exe', 'npm', 'npm.cmd', 'npx', 'npx.cmd']);
+        robocopy(path.join(from, 'node_modules', 'npm'), path.join(work, 'node_modules', 'npm'));
+        moveIntoPlace(work, to);
+    }
+    finally {
+        fs.rmSync(work, { recursive: true, force: true });
+    }
+};

package/dist/guest/gitguard.d.ts

@@ -0,0 +1,7 @@
+export type Decision = {
+    allow: true;
+} | {
+    allow: false;
+    reason: string;
+};
+export declare const gitDecision: (args: string[], access: string) => Decision;