windows-development-sandbox 1.0.5 → 1.1.0

package/dist/guest/env.js

@@ -2,8 +2,9 @@
 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 { 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';
@@ -18,6 +19,7 @@ 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');
@@ -94,6 +96,6 @@ export const copyNode = (from, to) => {
         moveIntoPlace(work, to);
     }
     finally {
-        fs.rmSync(work, { recursive: true, force: true });
+        safeRemove(work, path.dirname(work));
     }
 };

package/dist/guest/guide.d.ts

@@ -1,5 +1,9 @@
 /** Deliberately tiny: it is loaded into every conversation. */
-export declare const sandboxGuide: (toolSummary: string[], lan?: "blocked" | "open" | "offline") => string;
+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;
 /**
@@ -9,4 +13,4 @@ export declare const upsertGuide: (file: string, guide: string) => void;
  * 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;
+export declare const writeGuides: (toolSummary: string[], lan: "blocked" | "open" | "offline", projects?: GuideProject[]) => string;

package/dist/guest/guide.js

@@ -13,12 +13,13 @@ const mirrorLine = () => {
         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') => [
+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)',
@@ -45,8 +46,8 @@ export const upsertGuide = (file, guide) => {
  * 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);
+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');

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.js

@@ -12,9 +12,12 @@ 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 { 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); };
@@ -63,12 +66,17 @@ const main = async () => {
     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 ?? [] });
+    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());
@@ -82,15 +90,16 @@ const main = async () => {
     await soft('Claude managed settings', () => writeManagedSettings(gitAccess));
     step(6, 'Agent: ' + session.harnessName);
     if (session.harness)
-        provisionHarness(session.harnessName, session.harness, env);
+        await 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) {
+    // 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 (no agent requested). Workspace: ' + workspace);
+        log('Ready' + (session.harness ? '' : ' (no agent requested)') + '. Workspace: ' + workspace);
         return;
     }
     if (dryRun) {
@@ -115,6 +124,7 @@ main().catch((e) => {
         fs.writeFileSync(path.join(logsDir, 'guest-error.txt'), message);
     }
     catch { /* ignore */ }
-    console.error('\n\x1b[31mFATAL: ' + message + '\x1b[0m\nLogs: ' + logsDir);
+    // 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

@@ -1,21 +1,5 @@
 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;
@@ -36,5 +20,3 @@ export interface PtyHostOptions {
 }
 /** 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

@@ -1,62 +1,11 @@
-// 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.
+// Starts one ptyhost (the ConPTY bridge, sandbox/ptyhost.cs) per agent session and waits for it to listen.
 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;
-};
+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');
-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;
@@ -85,10 +34,3 @@ export const ptyHostLogTail = (id, lines = 12) => {
 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

@@ -1,6 +1,9 @@
 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;
+/**
+ * Copies the agent from this PC when it was mapped in (primary agent only), otherwise installs it with npm or uv.
+ * Asynchronous, so the session daemon keeps serving other requests while an agent installs.
+ */
+export declare const provisionHarness: (name: string, harness: Harness, env: NodeJS.ProcessEnv, refresh?: boolean) => Promise<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;

package/dist/guest/setup/agents.js

@@ -2,14 +2,15 @@
 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';
+import { uvVars } from '../toolchains/runtimes.js';
+import { dryRun, execAsync, 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) => {
+const installViaNpm = async (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');
@@ -21,10 +22,10 @@ const installViaNpm = (name, harness, dir, env) => {
     }
     if (!exists(npmCli))
         throw new Error('npm not found at ' + npmCli);
-    exec(process.execPath, args, { env });
+    await execAsync(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 installViaUv = async (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) {
@@ -33,10 +34,23 @@ const installViaUv = (name, harness, dir, env) => {
     }
     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') } });
+    await execAsync(uv, ['tool', 'install', '--force', '--python', '3.12', harness.uvPackage], { env: { ...env, ...uvVars(), UV_TOOL_BIN_DIR: dir } });
 };
-/** Copies the agent from this PC when it was mapped in (primary agent only), otherwise installs it with npm or uv. */
+/** One install per agent at a time: two sessions asking for a new agent at once share the first one's install. */
+const installing = new Map();
+/**
+ * Copies the agent from this PC when it was mapped in (primary agent only), otherwise installs it with npm or uv.
+ * Asynchronous, so the session daemon keeps serving other requests while an agent installs.
+ */
 export const provisionHarness = (name, harness, env, refresh = session.provisioning.refresh) => {
+    const current = installing.get(name);
+    if (current)
+        return current;
+    const work = installHarness(name, harness, env, refresh).finally(() => installing.delete(name));
+    installing.set(name, work);
+    return work;
+};
+const installHarness = async (name, harness, env, refresh) => {
     const p = harnessPaths(name, harness);
     const cached = (p.exe !== null && exists(p.exe)) || (p.cmd !== null && exists(p.cmd));
     if (cached && !refresh) {
@@ -56,9 +70,9 @@ export const provisionHarness = (name, harness, env, refresh = session.provision
         warn('Host copy of ' + name + ' not available; installing instead.');
     }
     if (harness.uvPackage && !harness.npmPackage)
-        installViaUv(name, harness, p.dir, env);
+        await installViaUv(name, harness, p.dir, env);
     else
-        installViaNpm(name, harness, p.dir, env);
+        await 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) => {

package/dist/guest/setup/claude.js

@@ -3,6 +3,8 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { translatePaths } from '../../shared/paths.js';
+import { writeJsonAtomic } from '../../shared/rundir.js';
+import { safeRemove } from '../../shared/safe-remove.js';
 import { claudeDir, dryRun, exists, launchDir, log, mkdirp, robocopy, session, stateDir, warn, workspace } from '../env.js';
 /** The sandbox keeps its own login and global state; everything else is refreshed from this PC each boot. */
 const KEEP_SANDBOX_COPY = ['.claude.json', '.credentials.json'];
@@ -41,7 +43,7 @@ export const mergeMcpServers = (hostFile, guestFile, hostWorkspace, guestWorkspa
     const guestKey = Object.keys(projects).find((key) => sameFolder(key, guestWorkspace)) ?? guestWorkspace.replace(/\\/g, '/');
     projects[guestKey] = { ...(projects[guestKey] ?? {}), mcpServers: { ...(projects[guestKey]?.mcpServers ?? {}), ...hostProject } };
     const merged = { ...guest, mcpServers: { ...(guest.mcpServers ?? {}), ...(host.mcpServers ?? {}) }, projects };
-    fs.writeFileSync(guestFile, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+    writeJsonAtomic(guestFile, merged);
     return Object.keys(host.mcpServers ?? {}).length + Object.keys(hostProject).length;
 };
 export const syncClaudeProfile = () => {
@@ -63,7 +65,7 @@ export const syncClaudeProfile = () => {
         }
         // Folders (skills, commands, plugins) are mirrored: what was removed on this PC goes here too.
         if (fs.statSync(from).isDirectory())
-            fs.rmSync(to, { recursive: true, force: true });
+            safeRemove(to, claudeDir);
         fs.cpSync(from, to, { recursive: true, force: true });
         log('Claude settings: copied ' + name + ' from this PC');
     }
@@ -81,7 +83,13 @@ export const syncClaudeProfile = () => {
 export const claudeMemPaths = { store: path.join(stateDir, 'claude-mem'), local: path.join(os.homedir(), '.claude-mem') };
 const claudeMemEnabled = () => session.claudeProfile.syncClaudeMem && !dryRun;
 export const restoreClaudeMem = () => {
-    if (!claudeMemEnabled() || !exists(claudeMemPaths.store))
+    if (!claudeMemEnabled())
+        return;
+    // A save cut off between its two renames (see saveClaudeMem) leaves only the aside copy: it is the newest data.
+    const previous = claudeMemPaths.store + '.previous';
+    if (!exists(claudeMemPaths.store) && exists(previous))
+        fs.renameSync(previous, claudeMemPaths.store);
+    if (!exists(claudeMemPaths.store))
         return;
     robocopy(claudeMemPaths.store, claudeMemPaths.local);
     log('claude-mem data restored from persistent storage.');

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

@@ -1,6 +1,16 @@
 import type { ToolEnv } from '../toolchains/index.js';
-export declare const agentEnv: (tools: Pick<ToolEnv, "vars" | "prepend" | "append">) => NodeJS.ProcessEnv;
+/** Whose environment: the launch folder's at boot, or a project registered later (with the boot's base environment). */
+export interface EnvTarget {
+    workspace: string;
+    project: string;
+    base: NodeJS.ProcessEnv;
+}
+export declare const agentEnv: (tools: Pick<ToolEnv, "vars" | "prepend" | "append">, target?: EnvTarget) => NodeJS.ProcessEnv;
 /** Makes the agent environment machine-wide, so new terminal tabs and anything the agent starts see the same tools. */
 export declare const persistEnvironment: (env: NodeJS.ProcessEnv, toolVars: string[]) => void;
-/** Adds variables and PATH folders machine-wide after boot (`sbx-db start`): new terminal tabs see them. */
-export declare const addMachineEnvironment: (vars: Record<string, string>, dirs: string[]) => void;
+/**
+ * Adds variables and PATH folders machine-wide after boot (`sbx-db start`): new terminal tabs see them.
+ * additive: for a project registered later. Only variables not set yet, and folders go to the END of PATH, so what
+ * the boot project's terminals see never changes; the project's own sessions get its full environment anyway.
+ */
+export declare const addMachineEnvironment: (vars: Record<string, string>, dirs: string[], additive?: boolean) => void;

package/dist/guest/setup/environment.js

@@ -3,28 +3,28 @@ import path from 'node:path';
 import { claudeDir, dataDir, dryRun, errMsg, isWin, testMode, mkdirp, powershell, session, stateDir, toolsDir, warn, workspace } from '../env.js';
 /** Variables agent-sandbox itself sets (besides the toolchains' own). */
 const AGENT_VARS = ['CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'GEMINI_CLI_HOME', 'npm_config_cache', 'npm_config_update_notifier', 'AGENT_WORKSPACE', 'AGENT_DATA', 'AGENT_TOOLS', 'AGENT_PROJECT', 'AGENT_SANDBOX', 'AGENT_SANDBOX_WORKSPACE'];
-export const agentEnv = (tools) => {
+export const agentEnv = (tools, target = { workspace, project: session.project, base: process.env }) => {
     const env = {
-        ...process.env,
+        ...target.base,
         ...tools.vars,
         CLAUDE_CONFIG_DIR: claudeDir,
         CODEX_HOME: path.join(stateDir, 'codex'),
         GEMINI_CLI_HOME: path.join(stateDir, 'gemini'),
         npm_config_cache: path.join(toolsDir, 'npm-cache'),
         npm_config_update_notifier: 'false',
-        AGENT_WORKSPACE: workspace,
+        AGENT_WORKSPACE: target.workspace,
         AGENT_DATA: dataDir,
         AGENT_TOOLS: toolsDir,
-        AGENT_PROJECT: session.project,
+        AGENT_PROJECT: target.project,
         // For project scripts: "am I in the sandbox, and where is the project?" (stable names; documented).
         AGENT_SANDBOX: '1',
-        AGENT_SANDBOX_WORKSPACE: workspace,
+        AGENT_SANDBOX_WORKSPACE: target.workspace,
     };
     for (const dir of [env.CLAUDE_CONFIG_DIR, env.CODEX_HOME, env.GEMINI_CLI_HOME, env.npm_config_cache])
         mkdirp(dir);
     // The runner's own Node (bootstrap.ps1 puts it first on PATH) is not exposed: `node` is whatever nvm selected.
     const runners = [path.join(toolsDir, 'node'), path.dirname(process.execPath)].map((d) => d.toLowerCase());
-    const base = (process.env.PATH ?? '').split(path.delimiter).filter((d) => d && !runners.includes(d.toLowerCase()));
+    const base = (target.base.PATH ?? '').split(path.delimiter).filter((d) => d && !runners.includes(d.toLowerCase()));
     env.PATH = [...new Set([...tools.prepend, ...base, ...tools.append])].join(path.delimiter);
     return env;
 };
@@ -45,16 +45,20 @@ export const persistEnvironment = (env, toolVars) => {
         warn('Could not persist the environment machine-wide: ' + errMsg(e));
     }
 };
-/** Adds variables and PATH folders machine-wide after boot (`sbx-db start`): new terminal tabs see them. */
-export const addMachineEnvironment = (vars, dirs) => {
+/**
+ * Adds variables and PATH folders machine-wide after boot (`sbx-db start`): new terminal tabs see them.
+ * additive: for a project registered later. Only variables not set yet, and folders go to the END of PATH, so what
+ * the boot project's terminals see never changes; the project's own sessions get its full environment anyway.
+ */
+export const addMachineEnvironment = (vars, dirs, additive = false) => {
     if (!isWin || dryRun || testMode)
         return;
     const script = [
         "$vars = '" + JSON.stringify(vars).replace(/'/g, "''") + "' | ConvertFrom-Json",
-        "foreach ($p in $vars.PSObject.Properties) { [Environment]::SetEnvironmentVariable($p.Name, [string]$p.Value, 'Machine') }",
+        "foreach ($p in $vars.PSObject.Properties) { " + (additive ? "if ([Environment]::GetEnvironmentVariable($p.Name, 'Machine')) { continue }; " : '') + "[Environment]::SetEnvironmentVariable($p.Name, [string]$p.Value, 'Machine') }",
         "$path = [Environment]::GetEnvironmentVariable('Path', 'Machine') -split ';'",
         "$add = '" + JSON.stringify(dirs).replace(/'/g, "''") + "' | ConvertFrom-Json | Where-Object { $path -notcontains $_ }",
-        "if ($add) { [Environment]::SetEnvironmentVariable('Path', ((@($add) + $path) -join ';'), 'Machine') }",
+        "if ($add) { [Environment]::SetEnvironmentVariable('Path', (" + (additive ? '($path + @($add))' : '(@($add) + $path)') + " -join ';'), 'Machine') }",
     ].join('\n');
     try {
         powershell(script);

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

@@ -1 +1,9 @@
-export declare const runHooks: (stage: string, env: NodeJS.ProcessEnv) => void;
+/** Hooks of the launch folder (C:\AgentLaunch\hooks), or of a project registered later (...\projects\<name>\hooks). */
+export interface HookTarget {
+    root: string;
+    cwd: string;
+}
+export declare const projectHooks: (name: string, cwd: string) => HookTarget;
+export declare const runHooks: (stage: string, env: NodeJS.ProcessEnv, target?: HookTarget) => void;
+/** The same without blocking: the session daemon keeps answering other requests while a project's hooks run. */
+export declare const runHooksAsync: (stage: string, env: NodeJS.ProcessEnv, target: HookTarget) => Promise<void>;