windows-development-sandbox 1.0.5 → 1.1.0

package/dist/host/agent-commands.js

@@ -0,0 +1,145 @@
+// (Beta) Agent commands: with agentCommands.enabled, typing an agent's own command on this PC (claude, codex, ...) starts
+// it in a hidden sandbox for the folder you are in and attaches that terminal. Small forwarding files in
+// <storage>\agent-commands go first on YOUR PATH (so they win over npm's and the installers' copies); turning it off
+// removes the files and that one PATH entry. SANDBOX_AGENT_DIRECT=1 runs the real agent on this PC instead.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { ensureDir, fileExists } from '../core/util.js';
+import { writeFileAtomic } from '../shared/rundir.js';
+import { safeRemove } from '../shared/safe-remove.js';
+import { SYSTEM } from '../shared/system.js';
+import { refuseInSelfTest } from './test-guard.js';
+export const commandsDir = (storageRoot) => path.join(storageRoot, 'agent-commands');
+/** Marks files this tool wrote, so only those are ever replaced or removed. */
+const MARKER = 'windows-development-sandbox agent command';
+const EXTENSIONS = ['.exe', '.cmd', '.bat'];
+/** cmd.exe expands % and ^ even inside quotes: such paths cannot go into a forwarding file safely. */
+const cmdSafe = (p) => !/[%"^\r\n]/.test(p);
+/** The agent's own executable on this PC, skipping this tool's forwarding files. */
+export const realAgent = (command, skipDir, pathValue = process.env.PATH ?? process.env.Path ?? '') => {
+    const skip = path.resolve(skipDir).toLowerCase();
+    const dirs = pathValue.split(path.delimiter).filter((d) => d && path.resolve(d).toLowerCase() !== skip);
+    for (const dir of dirs)
+        for (const ext of EXTENSIONS) {
+            const candidate = path.join(dir, command + ext);
+            if (fileExists(candidate))
+                return candidate;
+        }
+    return null;
+};
+/** The agents that get a forwarding command: installed on this PC, and listed (or "auto" = all of them). */
+export const agentCommands = (config, storageRoot, pathValue) => {
+    const wanted = config.agentCommands.agents;
+    return Object.entries(config.harnesses).flatMap(([harness, h]) => {
+        if (wanted !== 'auto' && !wanted.includes(harness))
+            return [];
+        const command = h.npmBin ?? (h.hostExecutable ? path.parse(h.hostExecutable).name : harness);
+        const real = /^[A-Za-z0-9._-]+$/.test(command) ? realAgent(command, commandsDir(storageRoot), pathValue) : null;
+        return real && cmdSafe(real) ? [{ harness, command, real }] : [];
+    });
+};
+/** The .cmd file for one agent (cmd, PowerShell and Windows Terminal all run it). */
+export const forwardingCmd = (a, node, entry) => [
+    '@echo off',
+    'rem ' + MARKER + ' (Beta). Turn off: sandbox agent-commands off. Run the real one: set SANDBOX_AGENT_DIRECT=1',
+    'if "%SANDBOX_AGENT_DIRECT%"=="1" goto direct',
+    '"' + node + '" "' + entry + '" launch --harness ' + a.harness + ' --headless --terminal -- %*',
+    'exit /b %errorlevel%',
+    ':direct',
+    'call "' + a.real + '" %*',
+    '',
+].join('\r\n');
+/** The same for Git Bash, which looks for a file without an extension. */
+export const forwardingSh = (a, node, entry) => {
+    const posix = (p) => p.replace(/^([A-Za-z]):/, (_m, d) => '/' + d.toLowerCase()).replace(/\\/g, '/');
+    const q = (s) => "'" + s.replace(/'/g, "'\\''") + "'";
+    return [
+        '#!/bin/sh',
+        '# ' + MARKER + ' (Beta). Turn off: sandbox agent-commands off. Run the real one: SANDBOX_AGENT_DIRECT=1',
+        'if [ "$SANDBOX_AGENT_DIRECT" = "1" ]; then exec ' + q(posix(a.real)) + ' "$@"; fi',
+        'exec ' + q(posix(node)) + ' ' + q(posix(entry)) + ' launch --harness ' + a.harness + ' --headless --terminal -- "$@"',
+        '',
+    ].join('\n');
+};
+/** Runs a PowerShell script that edits YOUR PATH (HKCU\Environment) unexpanded, then tells Windows it changed. */
+const editUserPath = (dir, add) => {
+    refuseInSelfTest('change your PATH');
+    const quoted = "'" + dir.replace(/'/g, "''") + "'";
+    const script = [
+        '$dir = ' + quoted,
+        "$key = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Environment')",
+        'try {',
+        "  $raw = [string]$key.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)",
+        "  $rest = @($raw -split ';' | Where-Object { $_ -and $_.TrimEnd('\\') -ine $dir.TrimEnd('\\') })",
+        // First, so these commands win over the agents' own folders (also on YOUR PATH).
+        add ? '  $new = (@($dir) + $rest) -join \';\'' : "  $new = $rest -join ';'",
+        '  if ($new -eq $raw.TrimEnd(\';\')) { exit 0 }',
+        "  if ($new.Length -gt 32000) { Write-Error 'PATH too long'; exit 3 }",
+        "  $kind = if ($key.GetValueNames() -contains 'Path') { $key.GetValueKind('Path') } else { [Microsoft.Win32.RegistryValueKind]::ExpandString }",
+        "  $key.SetValue('Path', $new, $kind)",
+        '} finally { $key.Close() }',
+        "Add-Type -Namespace WdsAgents -Name Native -MemberDefinition '[System.Runtime.InteropServices.DllImport(\"user32.dll\", CharSet = System.Runtime.InteropServices.CharSet.Auto)] public static extern System.IntPtr SendMessageTimeout(System.IntPtr hWnd, uint msg, System.UIntPtr wParam, string lParam, uint flags, uint timeout, out System.UIntPtr result);'",
+        '$ignored = [UIntPtr]::Zero',
+        "[void][WdsAgents.Native]::SendMessageTimeout([IntPtr]0xffff, 0x1A, [UIntPtr]::Zero, 'Environment', 2, 5000, [ref]$ignored)",
+    ].join('\n');
+    const result = spawnSync(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-OutputFormat', 'Text', '-Command', script], { encoding: 'utf8', windowsHide: true });
+    if (result.status === 3)
+        throw new Error('Your PATH is too long to add ' + dir + '.');
+    if (result.status !== 0)
+        throw new Error('Could not ' + (add ? 'add ' + dir + ' to' : 'remove ' + dir + ' from') + ' your PATH: ' + (result.stderr || result.error?.message || 'exit ' + result.status).trim());
+};
+const ownFiles = (dir) => fs.existsSync(dir)
+    ? fs.readdirSync(dir).map((f) => path.join(dir, f)).filter((f) => { try {
+        return fs.lstatSync(f).isFile() && fs.readFileSync(f, 'utf8').includes(MARKER);
+    }
+    catch {
+        return false;
+    } })
+    : [];
+/**
+ * Makes this PC match agentCommands: on = a forwarding file per installed agent and the folder first on your PATH;
+ * off = no files, no PATH entry. Only touches files it wrote and its own PATH entry; does nothing when already right.
+ */
+export const reconcileAgentCommands = (config, storageRoot, node, entry) => {
+    const dir = commandsDir(storageRoot);
+    if (!config.agentCommands.enabled) {
+        if (!fs.existsSync(dir))
+            return { on: false, commands: [], changed: false };
+        for (const f of ownFiles(dir))
+            fs.rmSync(f, { force: true });
+        editUserPath(dir, false);
+        if (fs.readdirSync(dir).length === 0)
+            safeRemove(dir, storageRoot);
+        return { on: false, commands: [], changed: true };
+    }
+    if (!cmdSafe(node) || !cmdSafe(entry))
+        throw new Error('This tool is installed in a folder whose path has % " or ^, which cannot go into a command file safely.');
+    const commands = agentCommands(config, storageRoot);
+    ensureDir(dir);
+    const wanted = new Map();
+    for (const a of commands) {
+        wanted.set(path.join(dir, a.command + '.cmd'), forwardingCmd(a, node, entry));
+        wanted.set(path.join(dir, a.command), forwardingSh(a, node, entry));
+    }
+    let changed = false;
+    for (const f of ownFiles(dir))
+        if (!wanted.has(f)) {
+            fs.rmSync(f, { force: true });
+            changed = true;
+        }
+    for (const [file, text] of wanted) {
+        const current = fileExists(file) ? fs.readFileSync(file, 'utf8') : null;
+        // A file of the same name that this tool did not write is never replaced.
+        if (current !== null && !current.includes(MARKER))
+            continue;
+        if (current !== text) {
+            writeFileAtomic(file, text);
+            changed = true;
+        }
+    }
+    const onPath = (process.env.PATH ?? '').split(path.delimiter).some((d) => path.resolve(d).toLowerCase() === path.resolve(dir).toLowerCase());
+    if (changed || !onPath)
+        editUserPath(dir, true);
+    return { on: true, commands, changed: changed || !onPath };
+};

package/dist/host/attach.d.ts

@@ -0,0 +1,17 @@
+import os from 'node:os';
+import type { SessionStatus } from '../core/types.js';
+import { type Viewers } from '../shared/pty-client.js';
+/**
+ * True only for IPv4 addresses inside the subnet of one of this PC's Hyper-V adapters ("vEthernet ..."), which is
+ * where Windows Sandbox lives. Stops a compromised sandbox from pointing the host (and your keystrokes) anywhere else.
+ */
+export declare const isSandboxAddress: (ip: string, interfaces?: NodeJS.Dict<os.NetworkInterfaceInfo[]>) => boolean;
+/** Who is watching a session right now (closed terminals do not count); null when it cannot be asked. */
+export declare const sessionViewers: (session: SessionStatus) => Promise<Viewers | null>;
+/**
+ * The newest running session of this agent in exactly this folder that no terminal on this PC is attached to, so
+ * sandbox claude -t picks it back up instead of starting another. A session that cannot answer is never reused.
+ */
+export declare const findUnwatchedSession: (dataPath: string, harness: string, cwd: string) => Promise<SessionStatus | null>;
+/** Bridges this terminal to a session. Returns the agent's exit code, or 0 when the user detaches. */
+export declare const attachTerminal: (session: SessionStatus) => Promise<number>;

package/dist/host/attach.js

@@ -0,0 +1,69 @@
+// Attaching this terminal to an agent session inside the sandbox. Only addresses on this PC's own Hyper-V network are
+// trusted, and everything the sandbox reports is printed through safeText.
+import net from 'node:net';
+import os from 'node:os';
+import { fail, safeText, sleep } from '../core/util.js';
+import { connect, DETACH_KEY, queryViewers, runTerminalClient } from '../shared/pty-client.js';
+import { currentSessions } from './channel.js';
+import { insideSandbox } from './platform.js';
+const ipToInt = (ip) => ip.split('.').reduce((n, part) => n * 256 + Number(part), 0);
+/**
+ * True only for IPv4 addresses inside the subnet of one of this PC's Hyper-V adapters ("vEthernet ..."), which is
+ * where Windows Sandbox lives. Stops a compromised sandbox from pointing the host (and your keystrokes) anywhere else.
+ */
+export const isSandboxAddress = (ip, interfaces = os.networkInterfaces()) => {
+    if (!net.isIPv4(ip))
+        return false;
+    return Object.entries(interfaces).some(([name, list]) => /^vEthernet/i.test(name) && (list ?? []).some((i) => {
+        if (i.family !== 'IPv4' || i.internal)
+            return false;
+        const mask = ipToInt(i.netmask);
+        return mask !== 0 && (ipToInt(i.address) & mask) === (ipToInt(ip) & mask) && i.address !== ip;
+    }));
+};
+/** Where this PC may connect for a session: only addresses on its own Hyper-V network (null if there are none). */
+const hostEndpoint = (session) => {
+    // Inside the sandbox every session is on loopback; on the PC only addresses on its Hyper-V network are trusted.
+    const addresses = insideSandbox() ? ['127.0.0.1'] : session.attach?.addresses.filter((a) => isSandboxAddress(a)) ?? [];
+    return session.attach && addresses.length ? { ...session.attach, addresses } : null;
+};
+/** Who is watching a session right now (closed terminals do not count); null when it cannot be asked. */
+export const sessionViewers = (session) => {
+    const endpoint = hostEndpoint(session);
+    return endpoint ? queryViewers(endpoint) : Promise.resolve(null);
+};
+/**
+ * The newest running session of this agent in exactly this folder that no terminal on this PC is attached to, so
+ * sandbox claude -t picks it back up instead of starting another. A session that cannot answer is never reused.
+ */
+export const findUnwatchedSession = async (dataPath, harness, cwd) => {
+    const candidates = currentSessions(dataPath).filter((s) => s.harness === harness && s.cwd.toLowerCase() === cwd.toLowerCase()).reverse().slice(0, 8);
+    for (const session of candidates)
+        if ((await sessionViewers(session))?.remote === 0)
+            return session;
+    return null;
+};
+/** Bridges this terminal to a session. Returns the agent's exit code, or 0 when the user detaches. */
+export const attachTerminal = async (session) => {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        fail('--terminal / attach needs an interactive terminal.', 'Run it directly in Windows Terminal or PowerShell, not through a pipe or script.');
+    if (!session.attach)
+        fail('This session cannot be attached to: networking or attach is disabled for this sandbox.', 'Set sandbox.networking and attach.enabled to true, then start a new sandbox.');
+    const endpoint = hostEndpoint(session) ?? fail('Refusing to connect: the sandbox reported no address on this PC\'s Hyper-V (vEthernet) network (' + session.attach.addresses.join(', ') + ').', 'Use the sandbox window instead (sbx-show); if this keeps happening, run sandbox doctor.');
+    const socket = await connect(endpoint);
+    console.log('Attaching to ' + safeText(session.harness) + ' session ' + session.id + ' (' + safeText(session.cwd) + '). Detach any time with Ctrl+]');
+    await sleep(400);
+    const result = await runTerminalClient(socket, session.attach.token, { detachKey: DETACH_KEY });
+    switch (result.reason) {
+        case 'detach':
+            console.log('Detached. The session keeps running; reattach with: sandbox attach ' + session.id);
+            return 0;
+        case 'exit':
+            console.log(safeText(session.harness) + ' exited with code ' + result.exitCode + '.');
+            return result.exitCode;
+        case 'error': fail('The sandbox refused the connection: ' + result.message, 'Try sandbox attach again; the session may have restarted.');
+        default:
+            console.log('Connection to the sandbox closed.');
+            return 1;
+    }
+};

package/dist/host/channel.d.ts

@@ -1,37 +1,38 @@
-import os from 'node:os';
-import type { GuestRequest, GuestResponse, SandboxStatus, SessionStatus } from '../core/types.js';
-import { type Viewers } from '../shared/pty-client.js';
-/**
- * True only for IPv4 addresses inside the subnet of one of this PC's Hyper-V adapters ("vEthernet ..."), which is
- * where Windows Sandbox lives. Stops a compromised sandbox from pointing the host (and your keystrokes) anywhere else.
- */
-export declare const isSandboxAddress: (ip: string, interfaces?: NodeJS.Dict<os.NetworkInterfaceInfo[]>) => boolean;
-/** Waits until the sandbox finished provisioning, printing each boot step. */
-export declare const waitForReady: (dataPath: string, launchId: string | null, isAlive: () => boolean) => Promise<SandboxStatus>;
+import type { GuestRequest, GuestResponse, Harness, SandboxStatus, SessionStatus } from '../core/types.js';
+import type { ProjectSpecT } from '../shared/schema.js';
+/** Where progress lines go: printed by default; a spinner passes its own. Text from the sandbox, made safe first. */
+export type Progress = (line: string) => void;
+/** Waits until the sandbox finished provisioning, reporting each boot step. */
+export declare const waitForReady: (dataPath: string, launchId: string | null, isAlive: () => boolean, progress?: Progress) => Promise<SandboxStatus>;
 export declare const sendRequest: (dataPath: string, request: GuestRequest) => void;
 export declare const waitForResponse: (dataPath: string, requestId: string, isAlive: () => boolean, timeoutMs: number) => Promise<GuestResponse>;
-export declare const requestSession: (dataPath: string, harness: string, args: string[], cwd: string) => string;
-export declare const waitForSession: (dataPath: string, sessionId: string, isAlive: () => boolean, timeoutMs?: number) => Promise<SessionStatus>;
+/** project: a project registered after boot (provisioned first). harnessSpec: the agent's definition, for an agent the sandbox did not boot with. */
+export declare const requestSession: (dataPath: string, harness: string, args: string[], cwd: string, extra?: {
+    project?: ProjectSpecT;
+    harnessSpec?: Harness;
+}) => string;
+/**
+ * Provisions a registered project without starting an agent and waits for it, printing its progress (the guest's
+ * run\projects\<name>.json) as it goes. Throws when it failed.
+ */
+export declare const prepareProject: (dataPath: string, project: ProjectSpecT, isAlive: () => boolean, progress?: Progress) => Promise<GuestResponse>;
+export declare const waitForSession: (dataPath: string, sessionId: string, isAlive: () => boolean, timeoutMs?: number, progress?: Progress) => Promise<SessionStatus>;
 /** Runs a command inside the sandbox (in the workspace or a folder below it) and returns its output. */
 export declare const execInSandbox: (dataPath: string, command: string[], cwd: string, timeoutSeconds: number, isAlive: () => boolean) => Promise<GuestResponse>;
 /** Restarts running sessions in place (they resume via the harness's resumeArguments, e.g. claude --continue). */
-export declare const restartSessions: (dataPath: string, harness: string | null, isAlive: () => boolean) => Promise<GuestResponse>;
+export declare const restartSessions: (dataPath: string, harness: string | null, isAlive: () => boolean, cwd?: string) => Promise<GuestResponse>;
 export declare const pingSandbox: (dataPath: string, isAlive: () => boolean) => Promise<GuestResponse>;
 export declare const runningSessions: (dataPath: string) => SessionStatus[];
 /** Most sessions the host will ever contact for one listing: a sandbox can write as many session files as it likes. */
 export declare const MAX_QUERIED_SESSIONS = 32;
 /** Running sessions of the sandbox that is running now (its launch id), newest last, capped. */
 export declare const currentSessions: (dataPath: string) => SessionStatus[];
-/** The session with this id (or id prefix), else the most recently started running one. */
-export declare const pickSession: (dataPath: string, sessionId?: string) => SessionStatus;
-/** Who is watching a session right now (closed terminals do not count); null when it cannot be asked. */
-export declare const sessionViewers: (session: SessionStatus) => Promise<Viewers | null>;
+/** Sessions in this guest folder or below (one project's) first, each group newest first. */
+export declare const sessionsFirstIn: (sessions: SessionStatus[], guestDir: string | null) => SessionStatus[];
 /**
- * The newest running session of this agent in exactly this folder that no terminal on this PC is attached to, so
- * sandbox claude -t picks it back up instead of starting another. A session that cannot answer is never reused.
+ * The session with this id (or id prefix), else the most recently started running one: in `guestDir` (the project
+ * you are in) when it has one, else any.
  */
-export declare const findUnwatchedSession: (dataPath: string, harness: string, cwd: string) => Promise<SessionStatus | null>;
-/** Bridges this terminal to a session. Returns the agent's exit code, or 0 when the user detaches. */
-export declare const attachTerminal: (session: SessionStatus) => Promise<number>;
+export declare const pickSession: (dataPath: string, sessionId?: string, guestDir?: string | null) => SessionStatus;
 /** Forgets status from a previous sandbox run so nothing stale is picked up. */
 export declare const resetRunDir: (dataPath: string) => void;

package/dist/host/channel.js

@@ -1,30 +1,13 @@
-// Host side of the sandbox channel: follow the boot, send requests (sessions, exec, restart), and bridge this terminal
-// to a session's pseudo console. Everything read from the run folder is guest-written and treated as untrusted.
+// Host side of the sandbox channel: follow the boot and send requests (sessions, exec, restart, ping). Attaching a
+// terminal to a session is in attach.ts. Everything read from the run folder is guest-written and treated as untrusted.
 import crypto from 'node:crypto';
 import fs from 'node:fs';
-import net from 'node:net';
-import os from 'node:os';
-import { insideSandbox } from './platform.js';
-import { safeRemove } from '../shared/safe-remove.js';
-import { connect, DETACH_KEY, queryViewers, runTerminalClient } from '../shared/pty-client.js';
-import { listSessions, now, readResponse, readSandboxStatus, readSession, runPaths, writeJsonAtomic } from '../shared/rundir.js';
 import { assertNoLinks, fail, isLink, removeLink, safeText, sleep } from '../core/util.js';
+import { isWithin } from '../shared/projects.js';
+import { listSessions, now, readProjectStatus, readResponse, readSandboxStatus, readSession, runPaths, writeJsonAtomic } from '../shared/rundir.js';
+import { safeRemove } from '../shared/safe-remove.js';
+import { assertTestWritable, refuseInSelfTest } from './test-guard.js';
 const BOOT_TIMEOUT_MS = 30 * 60 * 1000;
-const ipToInt = (ip) => ip.split('.').reduce((n, part) => n * 256 + Number(part), 0);
-/**
- * True only for IPv4 addresses inside the subnet of one of this PC's Hyper-V adapters ("vEthernet ..."), which is
- * where Windows Sandbox lives. Stops a compromised sandbox from pointing the host (and your keystrokes) anywhere else.
- */
-export const isSandboxAddress = (ip, interfaces = os.networkInterfaces()) => {
-    if (!net.isIPv4(ip))
-        return false;
-    return Object.entries(interfaces).some(([name, list]) => /^vEthernet/i.test(name) && (list ?? []).some((i) => {
-        if (i.family !== 'IPv4' || i.internal)
-            return false;
-        const mask = ipToInt(i.netmask);
-        return mask !== 0 && (ipToInt(i.address) & mask) === (ipToInt(ip) & mask) && i.address !== ip;
-    }));
-};
 const id = () => Date.now().toString(36) + crypto.randomBytes(3).toString('hex');
 const until = async (timeoutMs, isAlive, poll, timeoutMessage) => {
     const deadline = Date.now() + timeoutMs;
@@ -38,15 +21,16 @@ const until = async (timeoutMs, isAlive, poll, timeoutMessage) => {
     }
     fail(timeoutMessage, 'Check what the sandbox is doing with sandbox logs -f (or sbx-show to see its window).');
 };
-/** Waits until the sandbox finished provisioning, printing each boot step. */
-export const waitForReady = (dataPath, launchId, isAlive) => {
+const printLine = (line) => console.log(line);
+/** Waits until the sandbox finished provisioning, reporting each boot step. */
+export const waitForReady = (dataPath, launchId, isAlive, progress = (m) => printLine('  [sandbox] ' + m)) => {
     let last = '';
     return until(BOOT_TIMEOUT_MS, isAlive, () => {
         const status = readSandboxStatus(dataPath);
         if (!status || (launchId !== null && status.launchId !== launchId))
             return null;
         if (status.message !== last) {
-            console.log('  [sandbox] ' + safeText(status.message).slice(0, 300));
+            progress(safeText(status.message).slice(0, 300));
             last = status.message;
         }
         if (status.phase === 'failed')
@@ -55,28 +39,62 @@ export const waitForReady = (dataPath, launchId, isAlive) => {
     }, 'Timed out waiting for the sandbox to finish provisioning.');
 };
 export const sendRequest = (dataPath, request) => {
+    assertTestWritable(dataPath);
+    // Asking the sandbox to power off is the one request with an effect outside it, so the self-test never sends it.
+    if (request.kind === 'exec' && /shutdown/i.test(request.command[0] ?? ''))
+        refuseInSelfTest('shut down Windows Sandbox');
     assertNoLinks(dataPath, runPaths(dataPath).requests);
     writeJsonAtomic(runPaths(dataPath).request(request.id), request);
 };
 export const waitForResponse = (dataPath, requestId, isAlive, timeoutMs) => until(timeoutMs, isAlive, () => {
     const response = readResponse(dataPath, requestId);
-    if (response && !isLink(runPaths(dataPath).responses))
-        fs.rmSync(runPaths(dataPath).response(requestId), { force: true });
+    if (response)
+        try {
+            assertNoLinks(dataPath, runPaths(dataPath).responses);
+            fs.rmSync(runPaths(dataPath).response(requestId), { force: true });
+        }
+        catch { /* a planted link: the answer is read, nothing is deleted */ }
     return response;
 }, 'The sandbox did not answer (its session daemon may have stopped).');
-export const requestSession = (dataPath, harness, args, cwd) => {
+/** project: a project registered after boot (provisioned first). harnessSpec: the agent's definition, for an agent the sandbox did not boot with. */
+export const requestSession = (dataPath, harness, args, cwd, extra = {}) => {
     const requestId = id();
-    sendRequest(dataPath, { kind: 'session', id: requestId, harness, args, cwd, createdAt: now() });
+    sendRequest(dataPath, { kind: 'session', id: requestId, harness, args, cwd, ...(extra.project ? { project: extra.project } : {}), ...(extra.harnessSpec ? { harnessSpec: extra.harnessSpec } : {}), createdAt: now() });
     return requestId;
 };
-export const waitForSession = (dataPath, sessionId, isAlive, timeoutMs = 15 * 60 * 1000) => {
+/**
+ * Provisions a registered project without starting an agent and waits for it, printing its progress (the guest's
+ * run\projects\<name>.json) as it goes. Throws when it failed.
+ */
+export const prepareProject = async (dataPath, project, isAlive, progress = (m) => printLine('  [' + project.name + '] ' + m)) => {
+    const requestId = id();
+    sendRequest(dataPath, { kind: 'project', id: requestId, project, createdAt: now() });
+    let last = '';
+    const response = await until(60 * 60 * 1000, isAlive, () => {
+        const status = readProjectStatus(dataPath, project.name);
+        if (status && status.message !== last) {
+            progress(safeText(status.message).slice(0, 300));
+            last = status.message;
+        }
+        return readResponse(dataPath, requestId);
+    }, 'Timed out waiting for the project to be set up.');
+    try {
+        assertNoLinks(dataPath, runPaths(dataPath).responses);
+        fs.rmSync(runPaths(dataPath).response(requestId), { force: true });
+    }
+    catch { /* read, nothing deleted */ }
+    if (!response.ok)
+        fail(safeText(response.message), 'See sandbox logs for details.');
+    return response;
+};
+export const waitForSession = (dataPath, sessionId, isAlive, timeoutMs = 15 * 60 * 1000, progress = (m) => printLine('  [session] ' + m)) => {
     let last = '';
     return until(timeoutMs, isAlive, () => {
         const session = readSession(dataPath, sessionId);
         if (!session)
             return null;
         if (session.message !== last) {
-            console.log('  [session] ' + safeText(session.message).slice(0, 300));
+            progress(safeText(session.message).slice(0, 300));
             last = session.message;
         }
         if (session.phase === 'failed')
@@ -93,9 +111,9 @@ export const execInSandbox = async (dataPath, command, cwd, timeoutSeconds, isAl
     return waitForResponse(dataPath, requestId, isAlive, (timeoutSeconds + 30) * 1000);
 };
 /** Restarts running sessions in place (they resume via the harness's resumeArguments, e.g. claude --continue). */
-export const restartSessions = async (dataPath, harness, isAlive) => {
+export const restartSessions = async (dataPath, harness, isAlive, cwd) => {
     const requestId = id();
-    sendRequest(dataPath, { kind: 'restart', id: requestId, harness, createdAt: now() });
+    sendRequest(dataPath, { kind: 'restart', id: requestId, harness, ...(cwd ? { cwd } : {}), createdAt: now() });
     return waitForResponse(dataPath, requestId, isAlive, 30000);
 };
 export const pingSandbox = async (dataPath, isAlive) => {
@@ -111,61 +129,25 @@ export const currentSessions = (dataPath) => {
     const launchId = readSandboxStatus(dataPath)?.launchId;
     return runningSessions(dataPath).filter((s) => s.launchId === launchId).slice(-MAX_QUERIED_SESSIONS);
 };
-/** The session with this id (or id prefix), else the most recently started running one. */
-export const pickSession = (dataPath, sessionId) => {
+/** Sessions in this guest folder or below (one project's) first, each group newest first. */
+export const sessionsFirstIn = (sessions, guestDir) => {
+    const newest = [...sessions].reverse();
+    if (!guestDir)
+        return newest;
+    return [...newest.filter((s) => isWithin(guestDir, s.cwd)), ...newest.filter((s) => !isWithin(guestDir, s.cwd))];
+};
+/**
+ * The session with this id (or id prefix), else the most recently started running one: in `guestDir` (the project
+ * you are in) when it has one, else any.
+ */
+export const pickSession = (dataPath, sessionId, guestDir = null) => {
     const running = runningSessions(dataPath);
     if (running.length === 0)
         fail('No agent session is running in the sandbox.', 'Start one with sandbox claude (it opens a new session in the running sandbox).');
     if (!sessionId)
-        return running[running.length - 1];
+        return sessionsFirstIn(running, guestDir)[0];
     return running.find((s) => s.id === sessionId || s.id.startsWith(sessionId)) ?? fail('No running session "' + sessionId + '".', 'Running sessions: ' + running.map((s) => s.id).join(', ') + ' (sandbox sessions lists them).');
 };
-/** Where this PC may connect for a session: only addresses on its own Hyper-V network (null if there are none). */
-const hostEndpoint = (session) => {
-    // Inside the sandbox every session is on loopback; on the PC only addresses on its Hyper-V network are trusted.
-    const addresses = insideSandbox() ? ['127.0.0.1'] : session.attach?.addresses.filter((a) => isSandboxAddress(a)) ?? [];
-    return session.attach && addresses.length ? { ...session.attach, addresses } : null;
-};
-/** Who is watching a session right now (closed terminals do not count); null when it cannot be asked. */
-export const sessionViewers = (session) => {
-    const endpoint = hostEndpoint(session);
-    return endpoint ? queryViewers(endpoint) : Promise.resolve(null);
-};
-/**
- * The newest running session of this agent in exactly this folder that no terminal on this PC is attached to, so
- * sandbox claude -t picks it back up instead of starting another. A session that cannot answer is never reused.
- */
-export const findUnwatchedSession = async (dataPath, harness, cwd) => {
-    const candidates = currentSessions(dataPath).filter((s) => s.harness === harness && s.cwd.toLowerCase() === cwd.toLowerCase()).reverse().slice(0, 8);
-    for (const session of candidates)
-        if ((await sessionViewers(session))?.remote === 0)
-            return session;
-    return null;
-};
-/** Bridges this terminal to a session. Returns the agent's exit code, or 0 when the user detaches. */
-export const attachTerminal = async (session) => {
-    if (!process.stdin.isTTY || !process.stdout.isTTY)
-        fail('--terminal / attach needs an interactive terminal.', 'Run it directly in Windows Terminal or PowerShell, not through a pipe or script.');
-    if (!session.attach)
-        fail('This session cannot be attached to: networking or attach is disabled for this sandbox.', 'Set sandbox.networking and attach.enabled to true, then start a new sandbox.');
-    const endpoint = hostEndpoint(session) ?? fail('Refusing to connect: the sandbox reported no address on this PC\'s Hyper-V (vEthernet) network (' + session.attach.addresses.join(', ') + ').', 'Use the sandbox window instead (sbx-show); if this keeps happening, run sandbox doctor.');
-    const socket = await connect(endpoint);
-    console.log('Attaching to ' + safeText(session.harness) + ' session ' + session.id + ' (' + safeText(session.cwd) + '). Detach any time with Ctrl+]');
-    await sleep(400);
-    const result = await runTerminalClient(socket, session.attach.token, { detachKey: DETACH_KEY });
-    switch (result.reason) {
-        case 'detach':
-            console.log('Detached. The session keeps running; reattach with: sandbox attach ' + session.id);
-            return 0;
-        case 'exit':
-            console.log(safeText(session.harness) + ' exited with code ' + result.exitCode + '.');
-            return result.exitCode;
-        case 'error': fail('The sandbox refused the connection: ' + result.message, 'Try sandbox attach again; the session may have restarted.');
-        default:
-            console.log('Connection to the sandbox closed.');
-            return 1;
-    }
-};
 /** Forgets status from a previous sandbox run so nothing stale is picked up. */
 export const resetRunDir = (dataPath) => {
     const p = runPaths(dataPath);
@@ -174,7 +156,7 @@ export const resetRunDir = (dataPath) => {
         removeLink(p.run);
         return;
     }
-    for (const target of [p.sandbox, p.requests, p.responses, p.sessions]) {
+    for (const target of [p.sandbox, p.requests, p.responses, p.sessions, p.projects]) {
         safeRemove(target, dataPath);
     }
 };

package/dist/host/claude-profile.js

@@ -1,13 +1,17 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { stripMcpServers, stripSettings } from './secrets.js';
-import { dirExists, ensureDir, fileExists, homeDir, readJson, writeJson } from '../core/util.js';
+import { dirExists, ensureDir, fileExists, homeDir, isLink, readJson, writeJson } from '../core/util.js';
 const MAX_BYTES = 250 * 1024 * 1024;
+/** Real files only: a link inside ~/.claude (even a loop or a dead one) is neither followed nor counted nor copied. */
 const directorySize = (dir) => {
     let total = 0;
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
         const full = path.join(dir, entry.name);
-        total += entry.isDirectory() ? directorySize(full) : fs.statSync(full).size;
+        if (entry.isDirectory())
+            total += directorySize(full);
+        else if (entry.isFile())
+            total += fs.statSync(full).size;
     }
     return total;
 };
@@ -78,7 +82,7 @@ export const stageClaudeProfile = (settings, launchPath, workspaceHost, secrets)
                 result.skipped.push(name + ' (over 250 MB)');
                 continue;
             }
-            fs.cpSync(source, destination, { recursive: true, force: true });
+            fs.cpSync(source, destination, { recursive: true, force: true, filter: (from) => from === source || !isLink(from) });
         }
         else {
             result.skipped.push(name + ' (not found)');

package/dist/host/cleanup.js

@@ -1,21 +1,12 @@
 // Keeps storage from growing forever. Runs automatically on every launch and via `sandbox clean`.
 import fs from 'node:fs';
-import { safeRemove } from '../shared/safe-remove.js';
 import path from 'node:path';
 import _ from 'lodash';
+import { sizeOf } from '../core/disk.js';
 import { dirExists, isLink } from '../core/util.js';
+import { safeRemove } from '../shared/safe-remove.js';
 const DAY = 24 * 60 * 60 * 1000;
 export const DEFAULT_PRUNE = { launchDays: 7, logDays: 14, conflictDays: 30, keep: [] };
-/** Size on disk, never following links (a sandbox-planted junction must not make us walk this PC's disk). */
-const sizeOf = (p) => {
-    try {
-        const stat = fs.lstatSync(p);
-        return stat.isDirectory() ? _.sumBy(fs.readdirSync(p), (name) => sizeOf(path.join(p, name))) : stat.isSymbolicLink() ? 0 : stat.size;
-    }
-    catch {
-        return 0;
-    }
-};
 const ageMs = (p, now) => { try {
     return now - fs.lstatSync(p).mtimeMs;
 }

package/dist/host/database-plan.d.ts

@@ -0,0 +1,12 @@
+import type { Config, DatabasePlan } from '../core/types.js';
+import { type Database, type ProjectFile } from '../core/detect-databases.js';
+/**
+ * What to run in this sandbox: databases set to true, plus "auto" ones the project needs. SQL Server is reported (so
+ * the user hears about it) but cannot run inside Windows Sandbox.
+ */
+export declare const planDatabases: (config: Config["databases"], workspace: string, probe?: {
+    files?: ProjectFile[];
+    host?: Database[];
+}) => DatabasePlan[];
+/** Every database the sandbox can run, so `sbx-db start <name>` works for ones that did not start at boot. */
+export declare const databaseCatalog: (config: Config["databases"]) => DatabasePlan[];