windows-development-sandbox 0.0.0-stage → 1.0.5

package/dist/guest/gitguard.js

@@ -0,0 +1,60 @@
+// `git` wrapper used when provisioning.git.access is 'readonly' or 'none'. Installed first on PATH (git.cmd) and as a
+// bash function (BASH_ENV), it decides per call and then runs the real git. Standalone on purpose: it runs on every
+// git call, so it reads only two environment variables (AGENT_GIT_ACCESS, AGENT_REAL_GIT).
+import { spawnSync } from 'node:child_process';
+/** Subcommands that only read. */
+const READ_ONLY = new Set([
+    'status', 'log', 'diff', 'show', 'blame', 'annotate', 'ls-files', 'ls-tree', 'ls-remote', 'rev-parse', 'rev-list', 'describe', 'shortlog',
+    'grep', 'cat-file', 'reflog', 'whatchanged', 'name-rev', 'for-each-ref', 'show-ref', 'merge-base', 'count-objects', 'check-ignore',
+    'check-attr', 'var', 'version', 'help', 'diff-tree', 'diff-files', 'diff-index', 'cherry', 'range-diff', 'show-branch', 'verify-commit', 'verify-tag',
+]);
+/**
+ * `git branch` / `git tag` list when every argument is a listing flag, or when a listing flag is present and the
+ * rest are patterns/commits (`git branch --contains HEAD`). A bare name (`git branch new`) creates, so it is refused.
+ */
+const listingOnly = (flags, listFlags) => (rest) => rest.every((a) => flags.test(a)) || (rest.some((a) => listFlags.test(a)) && rest.every((a) => flags.test(a) || !a.startsWith('-')));
+/** Subcommands that are read-only only in their listing forms. */
+const LISTING = {
+    branch: listingOnly(/^(-a|-r|-v|-vv|--all|--remotes|--list|-l|--show-current|--verbose|--no-color|--color(=.*)?|--contains|--no-contains|--merged|--no-merged|--sort=.*|--format=.*)$/, /^(--list|-l|--contains|--no-contains|--merged|--no-merged)$/),
+    tag: listingOnly(/^(-l|--list|-n\d*|--contains|--no-contains|--merged|--no-merged|--points-at|--sort=.*|--format=.*)$/, /^(-l|--list|--contains|--no-contains|--merged|--no-merged|--points-at)$/),
+    remote: (rest) => rest.length === 0 || ['-v', '--verbose', 'show', 'get-url'].includes(rest[0]),
+    config: (rest) => rest.some((a) => /^(--get|--get-all|--get-regexp|--list|-l|--show-origin|--show-scope|--name-only)$/.test(a)) && !rest.some((a) => /^(--add|--unset|--unset-all|--replace-all|--rename-section|--remove-section|-e|--edit)$/.test(a)),
+    stash: (rest) => ['list', 'show'].includes(rest[0] ?? ''),
+    worktree: (rest) => rest[0] === 'list',
+    submodule: (rest) => rest.length === 0 || rest[0] === 'status' || rest[0] === 'summary',
+    notes: (rest) => rest.length === 0 || ['list', 'show'].includes(rest[0]),
+};
+/** Global options that take a value (`git -C dir status`). Config overrides (-c, --config-env) are refused outright. */
+const WITH_VALUE = new Set(['-C', '--namespace']);
+const FORBIDDEN_GLOBAL = /^(-c|--config-env|--exec-path|--git-dir|--work-tree|--super-prefix)(=|$)/;
+export const gitDecision = (args, access) => {
+    if (access === 'full')
+        return { allow: true };
+    if (access !== 'readonly')
+        return { allow: false, reason: 'git is disabled in this sandbox (provisioning.git.access = ' + (access || 'none') + ').' };
+    let i = 0;
+    while (i < args.length && args[i].startsWith('-')) {
+        if (FORBIDDEN_GLOBAL.test(args[i]))
+            return { allow: false, reason: 'git ' + args[i] + ' is not allowed: git is read-only in this sandbox.' };
+        i += WITH_VALUE.has(args[i]) ? 2 : 1;
+    }
+    const [command, ...rest] = args.slice(i);
+    if (command === undefined || command === '--version' || READ_ONLY.has(command) || (LISTING[command]?.(rest) ?? false))
+        return { allow: true };
+    return { allow: false, reason: 'git ' + command + ' is blocked: git is read-only in this sandbox (provisioning.git.access = readonly). Reading (status, log, diff, show, blame) is allowed.' };
+};
+if (process.argv[1]?.toLowerCase().endsWith('gitguard.js')) {
+    const args = process.argv.slice(2);
+    const decision = gitDecision(args, process.env.AGENT_GIT_ACCESS ?? 'none');
+    if (!decision.allow) {
+        console.error('fatal: ' + decision.reason);
+        process.exit(128);
+    }
+    const real = process.env.AGENT_REAL_GIT;
+    if (!real) {
+        console.error('fatal: git is not available in this sandbox.');
+        process.exit(128);
+    }
+    const result = spawnSync(real, args, { stdio: 'inherit', windowsHide: true });
+    process.exit(result.status ?? 1);
+}

package/dist/guest/gitrules.d.ts

@@ -0,0 +1,2 @@
+import type { GitAccess } from '../core/types.js';
+export declare const gitDenyRules: (access: GitAccess) => string[];

package/dist/guest/gitrules.js

@@ -0,0 +1,11 @@
+const SHELLS = ['Bash', 'PowerShell'];
+const WRITE_COMMANDS = ['commit', 'push', 'add', 'rm', 'mv', 'merge', 'rebase', 'reset', 'checkout', 'switch', 'restore', 'stash', 'tag', 'cherry-pick', 'revert', 'am', 'apply', 'clean', 'pull', 'fetch', 'clone', 'init', 'gc', 'prune', 'update-ref', 'update-index', 'filter-branch', 'replace', 'worktree add', 'branch -d', 'branch -D', 'branch -m', 'branch -M', 'config --add', 'config --unset', 'remote add', 'remote remove', 'remote set-url'];
+const GIT_DIR_PATHS = ['**/.git', '**/.git/**'];
+export const gitDenyRules = (access) => {
+    if (access === 'full')
+        return [];
+    const commands = access === 'none' ? ['git'] : WRITE_COMMANDS.map((c) => 'git ' + c);
+    const shellRules = SHELLS.flatMap((shell) => commands.map((c) => shell + '(' + c + ':*)'));
+    const fileRules = GIT_DIR_PATHS.flatMap((p) => (access === 'none' ? ['Read(' + p + ')', 'Edit(' + p + ')'] : ['Edit(' + p + ')']));
+    return [...shellRules, ...fileRules];
+};

package/dist/guest/guide.d.ts

@@ -0,0 +1,12 @@
+/** Deliberately tiny: it is loaded into every conversation. */
+export declare const sandboxGuide: (toolSummary: string[], lan?: "blocked" | "open" | "offline") => string;
+/** Inserts or replaces the generated section, keeping whatever else the file contains (the host's CLAUDE.md). */
+export declare const upsertGuide: (file: string, guide: string) => void;
+/**
+ * Claude Code loads the machine-wide managed memory (C:\Program Files\ClaudeCode\CLAUDE.md on Windows) before the
+ * user and project CLAUDE.md, in every session. The sandbox is disposable and we are admin, so the manifest lives
+ * there: the user's own global CLAUDE.md and every project's CLAUDE.md stay exactly as they are.
+ * Codex/Gemini have no machine-level file, so the block goes into their sandbox-only global instruction files.
+ */
+export declare const managedClaudeMd: () => string;
+export declare const writeGuides: (toolSummary: string[], lan: "blocked" | "open" | "offline") => string;

package/dist/guest/guide.js

@@ -0,0 +1,68 @@
+// Tells the agent where it is. A generated section (between markers, rewritten every boot) is added to the agent's
+// global instructions: Claude's CLAUDE.md and Codex's AGENTS.md inside the sandbox. It never travels back to this PC.
+import fs from 'node:fs';
+import path from 'node:path';
+import { claudeDir, dataDir, launchDir, session, stateDir, toolsDir, workspace } from './env.js';
+const BEGIN = '<!-- agent-sandbox:begin (generated every boot, do not edit) -->';
+const END = '<!-- agent-sandbox:end -->';
+/** Drives other than C: are subst drives onto C:\Mirror\<letter> (mapped folders shown at their PC paths). */
+const mirrorLine = () => {
+    // Only the ones bootstrap.ps1 could create (a letter already in use is reported there and skipped).
+    const drives = (session.substDrives ?? []).filter((d) => fs.existsSync(d.letter + ':\\'));
+    if (!drives.length)
+        return [];
+    return ['- ' + drives.map((d) => d.letter + ':').join(', ') + ' = mapped folders at their PC paths (subst onto `' + drives.map((d) => d.target).join('`, `') + '`; real-path tools may print that form).'];
+};
+/** Deliberately tiny: it is loaded into every conversation. */
+export const sandboxGuide = (toolSummary, lan = 'blocked') => [
+    BEGIN,
+    '## Sandbox manifest — you are in a DISPOSABLE Windows Sandbox',
+    'Wiped on close: everything except the paths below (installers, winget/choco, C:\\Users, Program Files, registry).',
+    '- RW, persists: `' + workspace + '` = host folder ' + session.workspaceHost,
+    '- RW, persists: `' + toolsDir + '` (toolchains) — put portable exes in `' + path.join(toolsDir, 'bin') + '` (on PATH)',
+    '- RW, persists: `' + stateDir + '` (agent config/history; do not edit logins) · logs: `' + path.join(dataDir, 'logs') + '`',
+    '- RO: `' + launchDir + '` (this boot\'s scripts) · lost on close: everything else, incl. `C:\\nvm` (Node symlink)',
+    ...mirrorLine(),
+    '- Tools: ' + toolSummary.join(' · '),
+    '- Persistent installs: `npm i -g` (per nvm version), `pip`, `cargo install`, `dotnet tool -g`, `uv tool`, `bun add -g`. Real installers must re-run each boot via a hook (ask the user).',
+    '- Mapped folders (workspace, C:\\AgentData) allow NO symlinks or junctions: pnpm runs hoisted (set), npm workspaces / `file:` deps and deno node_modules dirs fail there (use a folder on C:\\ outside them), bun cannot save its lockfile there (`bun install --no-save`).',
+    '- Network: ' + (lan === 'offline' ? 'OFF' : lan === 'blocked' ? 'internet yes, host LAN blocked' : 'internet yes, host LAN NOT blocked this time') + '. Other sessions may share this workspace; the user may be typing from the host.',
+    END,
+].join('\n');
+/** Inserts or replaces the generated section, keeping whatever else the file contains (the host's CLAUDE.md). */
+export const upsertGuide = (file, guide) => {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    const start = current.indexOf(BEGIN);
+    const end = current.indexOf(END);
+    const without = start >= 0 && end > start ? current.slice(0, start) + current.slice(end + END.length) : current;
+    fs.writeFileSync(file, without.trimEnd() + (without.trim() ? '\n\n' : '') + guide + '\n', 'utf8');
+};
+/**
+ * Claude Code loads the machine-wide managed memory (C:\Program Files\ClaudeCode\CLAUDE.md on Windows) before the
+ * user and project CLAUDE.md, in every session. The sandbox is disposable and we are admin, so the manifest lives
+ * there: the user's own global CLAUDE.md and every project's CLAUDE.md stay exactly as they are.
+ * Codex/Gemini have no machine-level file, so the block goes into their sandbox-only global instruction files.
+ */
+export const managedClaudeMd = () => path.join(process.env.AGENT_MANAGED_DIR ?? path.join(process.env.ProgramFiles ?? 'C:\\Program Files', 'ClaudeCode'), 'CLAUDE.md');
+export const writeGuides = (toolSummary, lan) => {
+    const guide = sandboxGuide(toolSummary, lan);
+    const managed = managedClaudeMd();
+    fs.mkdirSync(path.dirname(managed), { recursive: true });
+    fs.writeFileSync(managed, guide + '\n', 'utf8');
+    fs.writeFileSync(path.join(dataDir, 'SANDBOX.md'), guide + '\n', 'utf8');
+    upsertGuide(path.join(stateDir, 'codex', 'AGENTS.md'), guide);
+    upsertGuide(path.join(stateDir, 'gemini', '.gemini', 'GEMINI.md'), guide);
+    removeGuide(path.join(claudeDir, 'CLAUDE.md'));
+    return managed;
+};
+/** Older versions put the block into the user's CLAUDE.md; take it out again. */
+const removeGuide = (file) => {
+    if (!fs.existsSync(file))
+        return;
+    const current = fs.readFileSync(file, 'utf8');
+    const start = current.indexOf(BEGIN);
+    const end = current.indexOf(END);
+    if (start >= 0 && end > start)
+        fs.writeFileSync(file, (current.slice(0, start) + current.slice(end + END.length)).trim() + '\n', 'utf8');
+};

package/dist/guest/main.d.ts

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

package/dist/guest/main.js

@@ -0,0 +1,120 @@
+// Guest entry point, started by bootstrap.ps1 in the sandbox window. Provisions everything, starts the session
+// daemon, asks it for the first agent session and then shows that session in this window.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { writeGuides } from './guide.js';
+import { setupToolchains } from './toolchains/index.js';
+import { provisionHarness, resolveLaunch } from './setup/agents.js';
+import { restoreClaudeMem, syncClaudeProfile } from './setup/claude.js';
+import { agentEnv, persistEnvironment } from './setup/environment.js';
+import { runHooks } from './setup/hooks.js';
+import { applyNetworkPolicy } from './setup/network.js';
+import { writeManagedSettings } from './setup/policy.js';
+import { applyPersonalization, setupGitConfig } from './setup/user.js';
+import { ensurePtyHost, pruneToolLeftovers } from './ptyhost.js';
+import { now, readSession, writeJsonAtomic } from '../shared/rundir.js';
+import { viewSession } from './view.js';
+import { dataDir, dryRun, errMsg, isWin, localDir, log, logPath, logsDir, mkdirp, run, session, setSandboxStatus, toolsDir, warn, workspace } from './env.js';
+const STEPS = 8;
+const step = (n, title) => { log('\n\x1b[36m[' + n + '/' + STEPS + '] ' + title + '\x1b[0m'); setSandboxStatus(n === 1 ? 'booting' : 'provisioning', '[' + n + '/' + STEPS + '] ' + title); };
+const soft = async (what, work) => { try {
+    await work();
+}
+catch (e) {
+    warn(what + ' failed (continuing): ' + errMsg(e));
+} };
+const startDaemon = (env) => {
+    spawn(process.execPath, [path.join(path.dirname(process.argv[1]), 'daemon.js')], { detached: true, stdio: 'ignore', windowsHide: true, env: { ...env, AGENT_LOG_PREFIX: 'daemon' } }).unref();
+};
+/** `sbx-db` for terminals and `sandbox db`: this boot's Node running runtime\db.js (on the sandbox's disk, rewritten each boot). */
+const writeDbCommand = () => {
+    const dir = mkdirp(path.join(localDir, 'bin'));
+    const db = path.join(path.dirname(process.argv[1]), 'db.js');
+    fs.writeFileSync(path.join(dir, 'sbx-db.cmd'), '@setlocal\r\n@set AGENT_LOG_PREFIX=db\r\n@"' + process.execPath + '" "' + db + '" %*\r\n');
+    return dir;
+};
+const waitForPrimary = async () => {
+    for (let i = 0; i < 600; i++) {
+        const s = readSession(dataDir, session.launchId);
+        if (s?.phase === 'running')
+            return true;
+        if (s?.phase === 'failed' || s?.phase === 'exited') {
+            warn(s.message);
+            return false;
+        }
+        await new Promise((r) => setTimeout(r, 500));
+    }
+    return false;
+};
+const main = async () => {
+    log('Agent sandbox: ' + session.project + ' | workspace ' + workspace + ' | agent ' + session.harnessName + ' | log ' + logPath);
+    if (!fs.statSync(workspace, { throwIfNoEntry: false })?.isDirectory())
+        throw new Error('Workspace folder is missing in the sandbox: ' + workspace);
+    mkdirp(toolsDir);
+    mkdirp(run.run);
+    step(1, 'Network and session host');
+    let ptyHost = null;
+    if (isWin && !dryRun && session.attach.enabled)
+        await soft('Building the session host', () => { ptyHost = ensurePtyHost(); });
+    let lan = session.networking ? 'open' : 'offline';
+    await soft('Private-network blocking', async () => { lan = await applyNetworkPolicy(ptyHost); });
+    step(2, 'Pre-provision hooks and desktop');
+    runHooks('pre-provision', process.env);
+    await soft('Personalisation', applyPersonalization);
+    const gitAccess = session.provisioning.git.access ?? 'full';
+    step(3, 'Toolchains (Git, nvm/Node, Python, Rust, .NET, Bun, uv)');
+    const tools = await setupToolchains(session.toolchains, session.versions, { gitEnabled: session.provisioning.git.enabled, gitAccess, hostGit: session.hostTools.git, refresh: session.provisioning.refresh, databases: session.databases ?? [] });
+    if (!dryRun)
+        tools.prepend.push(writeDbCommand());
+    const env = agentEnv(tools);
+    persistEnvironment(env, Object.keys(tools.vars));
+    for (const line of tools.summary)
+        log('  ' + line);
+    await soft('Cleaning old tool builds', () => pruneToolLeftovers());
+    step(4, 'Git identity');
+    await soft('Git config', () => setupGitConfig(env));
+    step(5, 'Claude settings, history and claude-mem');
+    if (session.harnessName === 'claude')
+        await soft('Claude settings', syncClaudeProfile);
+    await soft('claude-mem restore', restoreClaudeMem);
+    await soft('Sandbox guide for the agent', () => writeGuides(tools.summary, lan));
+    await soft('Claude managed settings', () => writeManagedSettings(gitAccess));
+    step(6, 'Agent: ' + session.harnessName);
+    if (session.harness)
+        provisionHarness(session.harnessName, session.harness, env);
+    step(7, 'Pre-agent hooks');
+    runHooks('pre-agent', env);
+    step(8, 'Starting ' + session.harnessName);
+    setSandboxStatus('ready', 'Ready');
+    if (!session.harness) {
+        if (!dryRun)
+            startDaemon(env);
+        log('Ready (no agent requested). Workspace: ' + workspace);
+        return;
+    }
+    if (dryRun) {
+        const launch = resolveLaunch(session.harnessName, session.harness);
+        log('(dry run) would run: ' + [launch.file, ...launch.args, ...session.harness.arguments, ...session.harnessArguments].join(' ') + ' | cwd=' + workspace);
+        runHooks('post-agent', env);
+        return;
+    }
+    startDaemon(env);
+    writeJsonAtomic(run.request(session.launchId), { kind: 'session', id: session.launchId, harness: session.harnessName, args: session.harnessArguments, cwd: workspace, createdAt: now() });
+    if (!(await waitForPrimary()))
+        throw new Error('The agent session did not start. Logs: ' + logsDir);
+    log('If Claude asks you to sign in, do it once; the login is saved in persistent storage.');
+    if (process.stdin.isTTY)
+        await viewSession(session.launchId);
+    log('\nThis window stays open in ' + workspace + '. Other sessions keep running in their own tabs.');
+};
+main().catch((e) => {
+    const message = errMsg(e) + (e instanceof Error && e.stack ? '\n' + e.stack : '');
+    try {
+        setSandboxStatus('failed', errMsg(e));
+        fs.writeFileSync(path.join(logsDir, 'guest-error.txt'), message);
+    }
+    catch { /* ignore */ }
+    console.error('\n\x1b[31mFATAL: ' + message + '\x1b[0m\nLogs: ' + logsDir);
+    process.exitCode = 1;
+});

package/dist/guest/ptyhost.d.ts

@@ -0,0 +1,40 @@
+import { type ChildProcess } from 'node:child_process';
+export declare const quoteArg: (arg: string) => string;
+/**
+ * Arguments on a `cmd /d /c <agent>.cmd ...` line (npm agents). cmd parses them twice: the /c line, then the .cmd's %*.
+ * & | < > ^ are literal inside quotes, so arguments with them are quoted (https://x?a=1&b=2 survives). % expands even
+ * inside quotes, so each one sits between quoted pieces ("50"%" off"): every %name% cmd could see then starts with a
+ * quote, and no variable is called that. cmd's quote state runs across the whole line (an embedded \" toggles it too),
+ * so a metacharacter it would see outside quotes gets ^^^ (one caret left after each parse). Arguments without any
+ * of these are quoted as usual.
+ */
+export declare const cmdArgs: (args: string[]) => string;
+/** The command line ptyhost starts; when the program is cmd.exe its arguments are quoted for cmd (cmdArgs). */
+export declare const commandLine: (file: string, args: string[]) => string;
+export type Helper = 'ptyhost' | 'gitshim' | 'vswhere';
+/** %TEMP%\agent-sandbox\<name>-<hash>.exe, compiled from this launch's sandbox\<name>.cs the first time it is needed. */
+export declare const ensureCompiled: (name: Helper) => string;
+export declare const ensurePtyHost: () => string;
+export declare const freePort: () => Promise<number>;
+/** Resolves when ptyhost listens; rejects early if it exits first (e.g. the agent could not be started). */
+export declare const waitForPtyHost: (child: ChildProcess, port: number, timeoutMs: number) => Promise<void>;
+export declare const ptyHostLog: (id: string) => string;
+/** The last lines of a session's ptyhost log (the agent's final output is written there when it exits). */
+export declare const ptyHostLogTail: (id: string, lines?: number) => string;
+export interface PtyHostOptions {
+    exe: string;
+    port: number;
+    token: string;
+    cols: number;
+    rows: number;
+    command: string;
+    restartCommand: string;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    id: string;
+    remote: boolean;
+}
+/** Starts ptyhost detached, so closing a terminal tab never kills the agent; only the agent exiting ends it. */
+export declare const startPtyHost: (o: PtyHostOptions) => ChildProcess;
+/** Removes helper builds older versions left in persistent storage, and interrupted downloads in the tools folder. */
+export declare const pruneToolLeftovers: () => void;

package/dist/guest/ptyhost.js

@@ -0,0 +1,94 @@
+// Builds the sandbox's small C# helpers (ptyhost.cs, gitshim.cs) with the .NET Framework compiler that ships with
+// Windows, and starts one ptyhost per agent session.
+//
+// The helpers are compiled onto the sandbox's own disk (wiped on close) on every boot, never cached in persistent
+// storage: a tampered ptyhost.exe there would survive the wipe and see every keystroke typed from this PC.
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn, spawnSync } from 'node:child_process';
+import { exists, launchDir, logsDir, mkdirp, toolsDir } from './env.js';
+const CSC = path.join(process.env.WINDIR ?? 'C:\\Windows', 'Microsoft.NET', 'Framework64', 'v4.0.30319', 'csc.exe');
+const quoted = (arg) => '"' + arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1') + '"';
+export const quoteArg = (arg) => (arg !== '' && !/[\s"]/.test(arg) ? arg : quoted(arg));
+/**
+ * Arguments on a `cmd /d /c <agent>.cmd ...` line (npm agents). cmd parses them twice: the /c line, then the .cmd's %*.
+ * & | < > ^ are literal inside quotes, so arguments with them are quoted (https://x?a=1&b=2 survives). % expands even
+ * inside quotes, so each one sits between quoted pieces ("50"%" off"): every %name% cmd could see then starts with a
+ * quote, and no variable is called that. cmd's quote state runs across the whole line (an embedded \" toggles it too),
+ * so a metacharacter it would see outside quotes gets ^^^ (one caret left after each parse). Arguments without any
+ * of these are quoted as usual.
+ */
+export const cmdArgs = (args) => {
+    const pieces = args.map((arg) => (/[&|<>^%]/.test(arg) ? arg.split('%').map(quoted).join('%') : quoteArg(arg))).join(' ');
+    let inQuotes = false;
+    return [...pieces].map((c) => {
+        if (c === '"')
+            inQuotes = !inQuotes;
+        return !inQuotes && /[&|<>^]/.test(c) ? '^^^' + c : c;
+    }).join('');
+};
+/** The command line ptyhost starts; when the program is cmd.exe its arguments are quoted for cmd (cmdArgs). */
+export const commandLine = (file, args) => path.win32.basename(file).toLowerCase() === 'cmd.exe' ? [quoteArg(file), cmdArgs(args)].filter(Boolean).join(' ') : [file, ...args].map(quoteArg).join(' ');
+const sourceHash = (name) => crypto.createHash('sha256').update(fs.readFileSync(path.join(launchDir, 'sandbox', name + '.cs'))).digest('hex').slice(0, 12);
+/** %TEMP%\agent-sandbox\<name>-<hash>.exe, compiled from this launch's sandbox\<name>.cs the first time it is needed. */
+export const ensureCompiled = (name) => {
+    const exe = path.join(os.tmpdir(), 'agent-sandbox', name + '-' + sourceHash(name) + '.exe');
+    if (exists(exe))
+        return exe;
+    if (!exists(CSC))
+        throw new Error('The .NET Framework C# compiler was not found at ' + CSC + ' (it ships with Windows 10/11).');
+    mkdirp(path.dirname(exe));
+    const result = spawnSync(CSC, ['/nologo', '/optimize', '/target:exe', '/out:' + exe, path.join(launchDir, 'sandbox', name + '.cs')], { encoding: 'utf8', windowsHide: true });
+    if (result.status !== 0)
+        throw new Error('Compiling ' + name + ' failed: ' + ((result.stdout ?? '') + (result.stderr ?? '')).trim().slice(0, 1500));
+    return exe;
+};
+export const ensurePtyHost = () => ensureCompiled('ptyhost');
+export const freePort = () => new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', reject);
+    // Loopback: finding a port must not count as "node listens on the network" (that is what raises firewall prompts).
+    server.listen(0, '127.0.0.1', () => { const { port } = server.address(); server.close(() => resolve(port)); });
+});
+const portOpen = (port) => new Promise((resolve) => {
+    const socket = net.connect({ host: '127.0.0.1', port }, () => { socket.destroy(); resolve(true); });
+    socket.once('error', () => resolve(false));
+});
+/** Resolves when ptyhost listens; rejects early if it exits first (e.g. the agent could not be started). */
+export const waitForPtyHost = async (child, port, timeoutMs) => {
+    let exitCode;
+    child.once('exit', (code) => { exitCode = code; });
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (exitCode !== undefined)
+            throw new Error('the session host stopped right away (exit ' + exitCode + ')');
+        if (await portOpen(port))
+            return;
+        await new Promise((r) => setTimeout(r, 200));
+    }
+    throw new Error('the session host did not start listening on port ' + port);
+};
+export const ptyHostLog = (id) => path.join(logsDir, 'ptyhost-' + id + '.log');
+/** The last lines of a session's ptyhost log (the agent's final output is written there when it exits). */
+export const ptyHostLogTail = (id, lines = 12) => {
+    try {
+        return fs.readFileSync(ptyHostLog(id), 'utf8').trim().split(/\r?\n/).slice(-lines).join('\n');
+    }
+    catch {
+        return '';
+    }
+};
+/** Starts ptyhost detached, so closing a terminal tab never kills the agent; only the agent exiting ends it. */
+export const startPtyHost = (o) => spawn(o.exe, [String(o.port), o.token, String(o.cols), String(o.rows), ptyHostLog(o.id), o.command, o.restartCommand], {
+    cwd: o.cwd, env: { ...o.env, PTYHOST_BIND: o.remote ? 'any' : 'loopback' }, detached: true, stdio: 'ignore', windowsHide: true,
+});
+/** Removes helper builds older versions left in persistent storage, and interrupted downloads in the tools folder. */
+export const pruneToolLeftovers = () => {
+    for (const legacy of ['ptyhost', 'gitshim'])
+        fs.rmSync(path.join(toolsDir, legacy), { recursive: true, force: true });
+    for (const name of fs.readdirSync(toolsDir).filter((n) => /\.staging-[0-9a-f]+$/i.test(n)))
+        fs.rmSync(path.join(toolsDir, name), { recursive: true, force: true });
+};

package/dist/guest/setup/agents.d.ts

@@ -0,0 +1,8 @@
+import type { Harness } from '../../core/types.js';
+/** Copies the agent from this PC when it was mapped in (primary agent only), otherwise installs it with npm or uv. */
+export declare const provisionHarness: (name: string, harness: Harness, env: NodeJS.ProcessEnv, refresh?: boolean) => void;
+/** Program + arguments that start the agent (an npm .cmd shim has to go through cmd.exe). */
+export declare const resolveLaunch: (name: string, harness: Harness) => {
+    file: string;
+    args: string[];
+};

package/dist/guest/setup/agents.js

@@ -0,0 +1,73 @@
+// Getting the agent (claude, codex, gemini, opencode, aider, ...) into persistent storage and working out how to start it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { SYSTEM } from '../../shared/system.js';
+import { dryRun, exec, exists, hostToolsDir, isWin, log, mkdirp, session, toolsDir, warn } from '../env.js';
+const harnessPaths = (name, harness) => {
+    const dir = path.join(toolsDir, 'agents', name);
+    const exe = harness.hostExecutable ?? (harness.uvBin ? harness.uvBin + '.exe' : null);
+    return { dir, exe: exe ? path.join(dir, exe) : null, cmd: harness.npmBin ? path.join(dir, harness.npmBin + '.cmd') : null };
+};
+/** npm install with the runner's own npm into tools\agents\<name> (no global state outside persistent storage). */
+const installViaNpm = (name, harness, dir, env) => {
+    if (!harness.npmPackage)
+        throw new Error('No npmPackage configured for ' + name + ' and no host executable was available.');
+    const npmCli = path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+    const args = [npmCli, 'install', '--global', '--prefix', dir, harness.npmPackage, '--no-fund', '--no-audit'];
+    log('Installing ' + harness.npmPackage + ' (this can take a minute)...');
+    if (dryRun) {
+        log('(dry run) ' + process.execPath + ' ' + args.join(' '));
+        return;
+    }
+    if (!exists(npmCli))
+        throw new Error('npm not found at ' + npmCli);
+    exec(process.execPath, args, { env });
+};
+/** `uv tool install` with its command put straight into tools\agents\<name> (Python agents such as aider). */
+const installViaUv = (name, harness, dir, env) => {
+    const uv = path.join(toolsDir, 'uv', 'uv.exe');
+    log('Installing ' + harness.uvPackage + ' with uv (this can take a minute)...');
+    if (dryRun) {
+        log('(dry run) uv tool install ' + harness.uvPackage);
+        return;
+    }
+    if (!exists(uv))
+        throw new Error(name + ' is installed with uv; enable toolchains.uv');
+    exec(uv, ['tool', 'install', '--force', '--python', '3.12', harness.uvPackage], { env: { ...env, UV_TOOL_BIN_DIR: dir, UV_TOOL_DIR: path.join(toolsDir, 'uv-tools'), UV_PYTHON_INSTALL_DIR: path.join(toolsDir, 'uv-python'), UV_CACHE_DIR: path.join(toolsDir, 'uv-cache') } });
+};
+/** Copies the agent from this PC when it was mapped in (primary agent only), otherwise installs it with npm or uv. */
+export const provisionHarness = (name, harness, env, refresh = session.provisioning.refresh) => {
+    const p = harnessPaths(name, harness);
+    const cached = (p.exe !== null && exists(p.exe)) || (p.cmd !== null && exists(p.cmd));
+    if (cached && !refresh) {
+        log(name + ' already cached in persistent storage.');
+        return;
+    }
+    mkdirp(p.dir);
+    if (session.provisioning.copyFromHost && harness.hostExecutable && name === session.harnessName) {
+        const source = path.join(hostToolsDir, 'agents', name, harness.hostExecutable);
+        if (exists(source) && p.exe) {
+            fs.copyFileSync(source, p.exe);
+            log('Copied ' + name + ' from this PC: ' + source);
+            return;
+        }
+        if (!session.provisioning.fallbackToInstall)
+            throw new Error('Host copy of ' + name + ' unavailable and fallbackToInstall is false.');
+        warn('Host copy of ' + name + ' not available; installing instead.');
+    }
+    if (harness.uvPackage && !harness.npmPackage)
+        installViaUv(name, harness, p.dir, env);
+    else
+        installViaNpm(name, harness, p.dir, env);
+};
+/** Program + arguments that start the agent (an npm .cmd shim has to go through cmd.exe). */
+export const resolveLaunch = (name, harness) => {
+    const p = harnessPaths(name, harness);
+    if (p.exe && exists(p.exe))
+        return { file: p.exe, args: [] };
+    if (p.cmd && exists(p.cmd))
+        return isWin ? { file: SYSTEM.cmd(), args: ['/d', '/c', p.cmd] } : { file: p.cmd, args: [] };
+    if (dryRun)
+        return { file: p.exe ?? p.cmd ?? name, args: [] };
+    throw new Error('Cannot find an executable for ' + name + ' after provisioning.');
+};

package/dist/guest/setup/claude.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The sandbox keeps its own .claude.json (login, onboarding, per-project state), so MCP servers from this PC are
+ * merged into it each boot: user-scope `mcpServers`, and this project's local-scope servers under the sandbox path.
+ * Servers with the same name are replaced by this PC's definition; servers added inside the sandbox are kept.
+ */
+export declare const mergeMcpServers: (hostFile: string, guestFile: string, hostWorkspace: string, guestWorkspace: string) => number;
+export declare const syncClaudeProfile: () => void;
+/**
+ * claude-mem keeps SQLite + a vector store. They run from the sandbox's own disk (SQLite and mapped folders do not
+ * mix) and are mirrored to persistent storage, from where the host syncs them back to your PC.
+ */
+export declare const claudeMemPaths: {
+    store: string;
+    local: string;
+};
+export declare const restoreClaudeMem: () => void;
+/**
+ * Copies the live claude-mem folder back to persistent storage (staging folder + swap, never a half copy). Called from
+ * the daemon tick: when no database changed since the last save it does nothing (no copy of the whole folder).
+ */
+export declare const saveClaudeMem: () => void;