windows-development-sandbox 0.0.0-stage → 1.1.0

package/dist/guest/env.js

@@ -0,0 +1,101 @@
+// 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, setChecksumRequired, spawnAsync, stagingFolder } from '../shared/download.js';
+import { now, runPaths, writeJsonAtomic } from '../shared/rundir.js';
+import { safeRemove } from '../shared/safe-remove.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/, ''));
+setChecksumRequired(session.downloads?.requireChecksum === true);
+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 {
+        safeRemove(work, path.dirname(work));
+    }
+};

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;

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,16 @@
+/** Deliberately tiny: it is loaded into every conversation. */
+export interface GuideProject {
+    guest: string;
+    host: string;
+}
+export declare const sandboxGuide: (toolSummary: string[], lan?: "blocked" | "open" | "offline", projects?: GuideProject[]) => 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", projects?: GuideProject[]) => string;

package/dist/guest/guide.js

@@ -0,0 +1,69 @@
+// 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).'];
+};
+export const sandboxGuide = (toolSummary, lan = 'blocked', projects = []) => [
+    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,
+    // Projects started from other folders while this sandbox runs: every agent here can see them.
+    ...projects.map((p) => '- RW, persists: `' + p.guest + '` = host folder ' + p.host + ' (another project in this sandbox; your own is `%AGENT_WORKSPACE%`)'),
+    '- 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, projects = []) => {
+    const guide = sandboxGuide(toolSummary, lan, projects);
+    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/helpers.d.ts

@@ -0,0 +1,3 @@
+export type Helper = 'ptyhost' | 'gitshim' | 'vswhere' | 'openssl';
+/** %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;

package/dist/guest/helpers.js

@@ -0,0 +1,26 @@
+// Builds the sandbox's small C# helpers (ptyhost.cs, gitshim.cs, vswhere.cs, openssl.cs) with the .NET Framework
+// compiler that ships with Windows.
+//
+// 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 os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { exists, launchDir, mkdirp } from './env.js';
+const CSC = path.join(process.env.WINDIR ?? 'C:\\Windows', 'Microsoft.NET', 'Framework64', 'v4.0.30319', 'csc.exe');
+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;
+};

package/dist/guest/main.d.ts

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

package/dist/guest/main.js

@@ -0,0 +1,130 @@
+// 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 } from './ptyhost.js';
+import { pruneToolLeftovers } from './toolchains/leftovers.js';
+import { now, readSession, writeJsonAtomic } from '../shared/rundir.js';
+import { viewSession } from './view.js';
+import { saveBootEnv } from './boot-env.js';
+import { primaryProject, saveProjectStatus } from './project-status.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, 'Developer tools (the first start downloads them once; later starts are quick)');
+    const basePath = process.env.PATH ?? '';
+    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));
+    saveBootEnv({ basePath, toolVars: Object.keys(tools.vars), steps: tools.steps, summary: tools.summary, lan });
+    saveProjectStatus(primaryProject(), workspace, 'ready', 'Ready', session.databases ?? [], tools.summary);
+    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)
+        await provisionHarness(session.harnessName, session.harness, env);
+    step(7, 'Pre-agent hooks');
+    runHooks('pre-agent', env);
+    step(8, 'Starting ' + session.harnessName);
+    setSandboxStatus('ready', 'Ready');
+    // No agent, or a restart that adds a project (the host opens its sessions itself once the sandbox is ready).
+    if (!session.harness || session.autoSession === false) {
+        if (!dryRun)
+            startDaemon(env);
+        log('Ready' + (session.harness ? '' : ' (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 */ }
+    // The window gets the plain message; the stack trace is in guest-error.txt.
+    console.error('\n\x1b[31mThe sandbox could not start: ' + errMsg(e) + '\x1b[0m\nDetails: ' + path.join(logsDir, 'guest-error.txt'));
+    process.exitCode = 1;
+});

package/dist/guest/ports.d.ts

@@ -0,0 +1,6 @@
+/** A free port on loopback: finding one must not count as "node listens on the network" (that raises firewall prompts). */
+export declare const freePort: () => Promise<number>;
+/** Whether something accepts connections on 127.0.0.1:port. */
+export declare const portOpen: (port: number) => Promise<boolean>;
+/** Polls until the port accepts connections; false when `seconds` pass first. */
+export declare const waitForPort: (port: number, seconds: number) => Promise<boolean>;

package/dist/guest/ports.js

@@ -0,0 +1,22 @@
+// Local TCP port helpers shared by the session host (ptyhost) and the databases.
+import net from 'node:net';
+/** A free port on loopback: finding one must not count as "node listens on the network" (that raises firewall prompts). */
+export const freePort = () => new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => { const { port } = server.address(); server.close(() => resolve(port)); });
+});
+/** Whether something accepts connections on 127.0.0.1:port. */
+export 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));
+});
+/** Polls until the port accepts connections; false when `seconds` pass first. */
+export const waitForPort = async (port, seconds) => {
+    for (const end = Date.now() + seconds * 1000; Date.now() < end;) {
+        if (await portOpen(port))
+            return true;
+        await new Promise((r) => setTimeout(r, 300));
+    }
+    return false;
+};

package/dist/guest/project-context.d.ts

@@ -0,0 +1,7 @@
+export interface ProjectContext {
+    workspace: string;
+    duringSession: boolean;
+}
+export declare const withProject: <T>(context: ProjectContext, work: () => Promise<T>) => Promise<T>;
+export declare const projectWorkspace: () => string;
+export declare const duringSession: () => boolean;

package/dist/guest/project-context.js

@@ -0,0 +1,10 @@
+// Which project a toolchain step is provisioning. At boot that is the launch folder; the daemon provisions projects
+// registered later (another folder on the PC) while other sessions keep running, several at once. Steps read version
+// files and markers from projectWorkspace(), and duringSession() tells them to leave machine-wide state alone (the
+// nvm symlink, shims, compiled helpers in use) because sessions of other projects depend on it.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { workspace } from './env.js';
+const store = new AsyncLocalStorage();
+export const withProject = (context, work) => store.run(context, work);
+export const projectWorkspace = () => store.getStore()?.workspace ?? workspace;
+export const duringSession = () => store.getStore()?.duringSession ?? false;

package/dist/guest/project-env.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+export declare const BootEnv: z.ZodObject<{
+    basePath: z.ZodString;
+    toolVars: z.ZodArray<z.ZodString>;
+    steps: z.ZodRecord<z.ZodString, z.ZodObject<{
+        vars: z.ZodRecord<z.ZodString, z.ZodString>;
+        prepend: z.ZodArray<z.ZodString>;
+        append: z.ZodArray<z.ZodString>;
+        summary: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    summary: z.ZodArray<z.ZodString>;
+    lan: z.ZodEnum<{
+        open: "open";
+        blocked: "blocked";
+        offline: "offline";
+    }>;
+}, z.core.$strip>;
+export type BootEnvT = z.output<typeof BootEnv>;
+/** The environment a later project starts from: the daemon's own, without the boot project's toolchains. */
+export declare const baseEnvFor: (boot: BootEnvT | null, current?: NodeJS.ProcessEnv) => NodeJS.ProcessEnv;

package/dist/guest/project-env.js

@@ -0,0 +1,20 @@
+// Pure (no guest state): the environment a project that joined after boot starts from. Kept apart from boot-env.ts,
+// which reads the guest's session, so the host-side tests can import it.
+import { z } from 'zod';
+const Env = z.object({ vars: z.record(z.string(), z.string()), prepend: z.array(z.string()), append: z.array(z.string()), summary: z.array(z.string()) });
+export const BootEnv = z.object({
+    basePath: z.string(), toolVars: z.array(z.string()), steps: z.record(z.string(), Env),
+    /** The boot's tool summary and LAN state, for the agent guide that lists every project. */
+    summary: z.array(z.string()), lan: z.enum(['blocked', 'open', 'offline']),
+});
+/** Variables the boot set for its own project (its workspace, its toolchains): never inherited by another project. */
+const PROJECT_VARS = /^(AGENT_WORKSPACE|AGENT_PROJECT|AGENT_SANDBOX_WORKSPACE|AGENT_PROJECT_FILE|CARGO_TARGET_DIR|VIRTUAL_ENV)$/i;
+/** The environment a later project starts from: the daemon's own, without the boot project's toolchains. */
+export const baseEnvFor = (boot, current = process.env) => {
+    if (!boot)
+        return { ...current };
+    const drop = new Set(boot.toolVars.map((v) => v.toLowerCase()));
+    // Windows spells it Path; a plain object would keep both spellings.
+    const base = Object.fromEntries(Object.entries(current).filter(([k]) => !drop.has(k.toLowerCase()) && !PROJECT_VARS.test(k) && k.toLowerCase() !== 'path'));
+    return { ...base, PATH: boot.basePath };
+};

package/dist/guest/project-status.d.ts

@@ -0,0 +1,5 @@
+import type { DatabasePlan } from '../core/types.js';
+import type { ProjectStatusT } from '../shared/schema.js';
+/** The launch folder's project id (older launch folders: derived from its name). */
+export declare const primaryProject: () => string;
+export declare const saveProjectStatus: (name: string, workspace: string, phase: ProjectStatusT["phase"], message: string, databases: DatabasePlan[], summary: string[]) => void;

package/dist/guest/project-status.js

@@ -0,0 +1,17 @@
+import { now, writeJsonAtomic } from '../shared/rundir.js';
+import { hubName } from '../shared/projects.js';
+import { errMsg, run, session, warn } from './env.js';
+/** The launch folder's project id (older launch folders: derived from its name). */
+export const primaryProject = () => session.projectId ?? hubName(session.workspaceHost || session.project, []);
+export const saveProjectStatus = (name, workspace, phase, message, databases, summary) => {
+    try {
+        writeJsonAtomic(run.project(name), {
+            name, workspace, phase, message: message.slice(0, 3500), updatedAt: now(),
+            databases: databases.filter((d) => d.database !== 'sqlserver').slice(0, 16).map((d) => ({ database: d.database, port: d.port })),
+            summary: summary.slice(0, 64).map((s) => s.slice(0, 500)),
+        });
+    }
+    catch (e) {
+        warn('Could not write the status of project ' + name + ': ' + errMsg(e));
+    }
+};

package/dist/guest/ptyhost.d.ts

@@ -0,0 +1,22 @@
+import { type ChildProcess } from 'node:child_process';
+export declare const ensurePtyHost: () => string;
+/** 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;

package/dist/guest/ptyhost.js

@@ -0,0 +1,36 @@
+// Starts one ptyhost (the ConPTY bridge, sandbox/ptyhost.cs) per agent session and waits for it to listen.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { ensureCompiled } from './helpers.js';
+import { portOpen } from './ports.js';
+import { logsDir } from './env.js';
+export const ensurePtyHost = () => ensureCompiled('ptyhost');
+/** 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,
+});