windows-development-sandbox 0.0.0-stage → 1.1.0

package/dist/guest/toolchains/scripting/vcruntime.js

@@ -0,0 +1,45 @@
+// The Visual C++ runtime (vcruntime140.dll & co.) that PHP and other native tools need.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnAsync } from '../../../shared/download.js';
+import { SYSTEM } from '../../../shared/system.js';
+import { dryRun, execOutput, exists, log } from '../../env.js';
+import { downloadFile, tool } from '../common.js';
+const VC_REDIST = 'https://aka.ms/vs/17/release/vc_redist.x64.exe';
+const MICROSOFT_SIGNER = 'CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US';
+/** 1638: a newer version is already installed; 3010: installed, a restart would finish it (not needed for the DLLs). */
+const OK_EXIT_CODES = [0, 1638, 3010];
+/** The subject of a valid Authenticode signature, or '' when the file is unsigned or tampered with. */
+const signerOf = (file) => execOutput(SYSTEM.powershell(), ['-NoLogo', '-NoProfile', '-Command',
+    "$s = Get-AuthenticodeSignature -LiteralPath '" + file.replace(/'/g, "''") + "'; if ($s.Status -eq 'Valid') { $s.SignerCertificate.Subject }"]).trim();
+/**
+ * A real installer (it writes to System32), so it runs on every boot; the installer itself is kept in persistent
+ * storage and only run when Microsoft's signature on it checks out. Resolves true when this call ran the installer.
+ * Only the "Visual C++ runtime" step reports it (`summary`); PHP calls it again just to be sure.
+ */
+export const setupVcRuntime = async (env, summary = true) => {
+    if (dryRun) {
+        log('(dry run) would install the Visual C++ runtime');
+        return false;
+    }
+    const system32 = path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32');
+    const missing = !exists(path.join(system32, 'vcruntime140.dll')) || !exists(path.join(system32, 'msvcp140.dll'));
+    if (missing) {
+        const installer = tool('vcredist', 'vc_redist.x64.exe');
+        if (!exists(installer)) {
+            log('Downloading the Visual C++ runtime (~25 MB once) ...');
+            await downloadFile(VC_REDIST, installer);
+        }
+        if (signerOf(installer) !== MICROSOFT_SIGNER) {
+            fs.rmSync(installer, { force: true });
+            throw new Error('vc_redist.x64.exe is not signed by Microsoft; deleted it (it is downloaded again next boot)');
+        }
+        log('Installing the Visual C++ runtime ...');
+        const code = await spawnAsync(installer, ['/install', '/quiet', '/norestart']);
+        if (!OK_EXIT_CODES.includes(code ?? -1) || !exists(path.join(system32, 'vcruntime140.dll')))
+            throw new Error('the Visual C++ runtime installer failed (exit ' + code + ')');
+    }
+    if (summary)
+        env.summary.push('vc++ runtime: installed');
+    return missing;
+};

package/dist/guest/toolchains/versions.d.ts

@@ -0,0 +1,47 @@
+export interface NodeRelease {
+    version: string;
+    lts: string | false;
+}
+/** Turns an .nvmrc-style spec (20, v20.11.1, lts/*, lts/iron, node, latest) into an exact version like 20.11.1. */
+export declare const pickNodeVersion: (releases: NodeRelease[], spec: string) => string | null;
+/**
+ * Which of this PC's nvm versions to copy along with `current`: at most `max` in total, current included, the rest
+ * spread across the range (newest of each major first, then evenly spaced from oldest to newest).
+ */
+export declare const pickSpreadVersions: (available: string[], current: string, max: number) => string[];
+/** Newest stable version matching a prefix spec ("3" -> 3.13.1, "3.12" -> 3.12.10). */
+export declare const pickPackageVersion: (all: string[], spec: string) => string | null;
+/** Version spec from a version file's text (.ruby-version "ruby-3.3.1", .java-version "temurin-21", ...): its first x[.y[.z]]. */
+export declare const specFromVersionFile: (text: string) => string | null;
+/** Java major version from .java-version ("21", "17.0.9", "1.8", "temurin-21") or .sdkmanrc ("java=21.0.2-tem"). */
+export declare const javaMajorFrom: (text: string, sdkmanrc?: boolean) => string | null;
+export interface GoRelease {
+    version: string;
+    stable: boolean;
+    files: {
+        filename: string;
+        os: string;
+        arch: string;
+        kind: string;
+        sha256: string;
+    }[];
+}
+/** "stable" / "latest" -> newest stable release; "1.23" -> newest 1.23.x; "1.23.2" -> exactly that. Returns go.dev's entry. */
+export declare const pickGoRelease: (releases: GoRelease[], spec: string) => GoRelease | null;
+/**
+ * Does the project use a language? `entries` are file names in the workspace root and one folder down ("api/go.mod");
+ * markers are exact names or "*.ext".
+ */
+export declare const projectUses: (entries: readonly string[], markers: readonly string[]) => boolean;
+/** Newest MSVC tools version among VS manifest package ids ("microsoft.vc.14.44.17.14.tools.hostx64.targetx64.base"). */
+export declare const pickMsvcVersion: (packageIds: string[], spec?: string) => string | null;
+/** Newest Windows SDK build among component ids ("microsoft.visualstudio.component.windows11sdk.26100"). */
+export declare const pickWindowsSdk: (packageIds: string[], spec?: string) => {
+    build: string;
+    componentId: string;
+} | null;
+/** The .cab files an SDK .msi refers to (their names are inside the msi as plain "<32 hex>.cab"). */
+export declare const msiCabs: (msi: Buffer) => string[];
+/** The oldest CMake many projects (OpenMoHAA among them) accept. */
+export declare const CMAKE_FLOOR = "3.25";
+export declare const cmakeTooOld: (version: string) => boolean;

package/dist/guest/toolchains/versions.js

@@ -0,0 +1,77 @@
+// Version picking for the toolchains. Pure functions only (no environment, no I/O), so the host and the tests can
+// import them without loading the guest runtime.
+/** Turns an .nvmrc-style spec (20, v20.11.1, lts/*, lts/iron, node, latest) into an exact version like 20.11.1. */
+export const pickNodeVersion = (releases, spec) => {
+    const s = spec.trim().toLowerCase().replace(/^v/, '');
+    const hit = ['node', 'latest', 'current', 'stable'].includes(s) ? releases[0]
+        : s === 'lts' || s === 'lts/*' ? releases.find((r) => r.lts)
+            : s.startsWith('lts/') ? releases.find((r) => typeof r.lts === 'string' && r.lts.toLowerCase() === s.slice(4))
+                : releases.find((r) => r.version === 'v' + s || r.version.startsWith('v' + s + '.'));
+    return hit ? hit.version.slice(1) : null;
+};
+/**
+ * Which of this PC's nvm versions to copy along with `current`: at most `max` in total, current included, the rest
+ * spread across the range (newest of each major first, then evenly spaced from oldest to newest).
+ */
+export const pickSpreadVersions = (available, current, max) => {
+    const byVersion = (a, b) => a.localeCompare(b, undefined, { numeric: true });
+    const exact = available.filter((v) => /^\d+\.\d+\.\d+$/.test(v) && v !== current).sort(byVersion);
+    const newestPerMajor = exact.filter((v, i) => exact[i + 1]?.split('.')[0] !== v.split('.')[0]);
+    const pool = newestPerMajor.filter((v) => v.split('.')[0] !== current.split('.')[0]);
+    const want = Math.max(0, max - 1);
+    const picked = want >= pool.length ? pool
+        : want === 1 ? [pool[pool.length - 1]]
+            : Array.from({ length: want }, (_, i) => pool[Math.round(i * (pool.length - 1) / (want - 1))]);
+    return [current, ...picked];
+};
+/** Newest stable version matching a prefix spec ("3" -> 3.13.1, "3.12" -> 3.12.10). */
+export const pickPackageVersion = (all, spec) => {
+    const s = spec.trim().replace(/^python-?/i, '');
+    const stable = all.filter((v) => /^\d+(\.\d+)*$/.test(v)).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+    return stable.find((v) => v === s || v.startsWith(s + '.')) ?? null;
+};
+/** Version spec from a version file's text (.ruby-version "ruby-3.3.1", .java-version "temurin-21", ...): its first x[.y[.z]]. */
+export const specFromVersionFile = (text) => /(\d+(?:\.\d+){0,2})/.exec(text.split(/\r?\n/).map((l) => l.replace(/#.*$/, '').trim()).find(Boolean) ?? '')?.[1] ?? null;
+/** Java major version from .java-version ("21", "17.0.9", "1.8", "temurin-21") or .sdkmanrc ("java=21.0.2-tem"). */
+export const javaMajorFrom = (text, sdkmanrc = false) => {
+    const line = sdkmanrc ? /^\s*java\s*=\s*(.+)$/m.exec(text)?.[1] : text;
+    const spec = line ? specFromVersionFile(line) : null;
+    if (!spec)
+        return null;
+    const [major, minor] = spec.split('.');
+    return major === '1' && minor ? minor : major;
+};
+/** "stable" / "latest" -> newest stable release; "1.23" -> newest 1.23.x; "1.23.2" -> exactly that. Returns go.dev's entry. */
+export const pickGoRelease = (releases, spec) => {
+    const s = spec.trim().toLowerCase().replace(/^go/, '');
+    const stable = releases.filter((r) => r.stable);
+    if (s === 'stable' || s === 'latest')
+        return stable[0] ?? null;
+    return stable.find((r) => r.version === 'go' + s || r.version.startsWith('go' + s + '.')) ?? null;
+};
+/**
+ * Does the project use a language? `entries` are file names in the workspace root and one folder down ("api/go.mod");
+ * markers are exact names or "*.ext".
+ */
+export const projectUses = (entries, markers) => entries.some((entry) => {
+    const name = entry.split(/[\/]/).pop().toLowerCase();
+    return markers.some((m) => (m.startsWith('*.') ? name.endsWith(m.slice(1).toLowerCase()) : name === m.toLowerCase()));
+});
+/** Newest MSVC tools version among VS manifest package ids ("microsoft.vc.14.44.17.14.tools.hostx64.targetx64.base"). */
+export const pickMsvcVersion = (packageIds, spec = 'latest') => {
+    const versions = packageIds.map((id) => /^microsoft\.vc\.(\d+\.\d+\.\d+\.\d+)\.tools\.hostx64\.targetx64\.base$/i.exec(id)?.[1]).filter((v) => Boolean(v));
+    const sorted = [...new Set(versions)].sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+    return (spec === 'latest' ? sorted[0] : sorted.find((v) => v === spec || v.startsWith(spec + '.'))) ?? null;
+};
+/** Newest Windows SDK build among component ids ("microsoft.visualstudio.component.windows11sdk.26100"). */
+export const pickWindowsSdk = (packageIds, spec = 'latest') => {
+    const found = packageIds.map((id) => ({ id, build: /^microsoft\.visualstudio\.component\.windows1[01]sdk\.(\d+)$/i.exec(id)?.[1] })).filter((x) => Boolean(x.build));
+    const sorted = found.sort((a, b) => Number(b.build) - Number(a.build));
+    const hit = spec === 'latest' ? sorted[0] : sorted.find((x) => x.build === spec.replace(/^10\.0\./, '').split('.')[0]);
+    return hit ? { build: hit.build, componentId: hit.id } : null;
+};
+/** The .cab files an SDK .msi refers to (their names are inside the msi as plain "<32 hex>.cab"). */
+export const msiCabs = (msi) => [...new Set([...msi.toString('latin1').matchAll(/([0-9a-f]{32}\.cab)/gi)].map((m) => m[1].toLowerCase()))];
+/** The oldest CMake many projects (OpenMoHAA among them) accept. */
+export const CMAKE_FLOOR = '3.25';
+export const cmakeTooOld = (version) => /^\d+\.\d+/.test(version) && version.localeCompare(CMAKE_FLOOR, undefined, { numeric: true }) < 0;

package/dist/guest/toolchains/vscode.d.ts

@@ -0,0 +1,2 @@
+import { type ToolEnv } from './common.js';
+export declare const setupVscode: (env: ToolEnv, refresh: boolean) => Promise<void>;

package/dist/guest/toolchains/vscode.js

@@ -0,0 +1,53 @@
+// VS Code for debugging inside the sandbox: the portable zip build, checksum-verified. A `data` folder next to Code.exe
+// switches it to portable mode, so settings and extensions live in C:\AgentData\tools\vscode\data and persist.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fetchJson, installArchive } from '../../shared/download.js';
+import { dryRun, exists, isWin, log, mkdirp, powershell } from '../env.js';
+import { arch, tool } from './common.js';
+/** Newer builds keep their files under a commit-hash folder, so the installed version is recorded here. */
+const VERSION_MARKER = '.agent-sandbox-version';
+const desktopShortcut = (exe) => {
+    if (!isWin)
+        return;
+    const link = path.join(os.homedir(), 'Desktop', 'Visual Studio Code.lnk');
+    const q = (s) => "'" + s.replace(/'/g, "''") + "'";
+    powershell('$s = (New-Object -ComObject WScript.Shell).CreateShortcut(' + q(link) + '); $s.TargetPath = ' + q(exe) + '; $s.Arguments = ' + q('"' + (process.env.AGENT_WORKSPACE ?? '') + '"') + '; $s.Save()');
+};
+export const setupVscode = async (env, refresh) => {
+    const root = tool('vscode');
+    const exe = path.join(root, 'Code.exe');
+    if (dryRun) {
+        log('(dry run) would provision VS Code');
+        return;
+    }
+    if (!exists(exe) || refresh) {
+        const release = await fetchJson('https://update.code.visualstudio.com/api/update/win32-' + (arch === 'arm64' ? 'arm64' : 'x64') + '-archive/stable/latest');
+        log('Downloading VS Code ' + release.productVersion + ' (~150 MB once) ...');
+        // Keep settings/extensions across a refresh: move the portable data folder aside and back, also when the install
+        // fails (finally). A folder still parked from an interrupted earlier run is the one to keep.
+        const keep = path.join(root, 'data');
+        const parked = root + '-data';
+        if (exists(keep)) {
+            fs.rmSync(parked, { recursive: true, force: true });
+            fs.renameSync(keep, parked);
+        }
+        try {
+            await installArchive(release.url, root, { sha256: release.sha256hash, locate: 'Code.exe', fileName: 'vscode.zip' });
+            fs.writeFileSync(path.join(root, VERSION_MARKER), release.productVersion);
+        }
+        finally {
+            if (exists(parked)) {
+                mkdirp(root);
+                fs.rmSync(keep, { recursive: true, force: true });
+                fs.renameSync(parked, keep);
+            }
+        }
+    }
+    mkdirp(path.join(root, 'data'));
+    env.prepend.push(path.join(root, 'bin'));
+    desktopShortcut(exe);
+    const version = exists(path.join(root, VERSION_MARKER)) ? fs.readFileSync(path.join(root, VERSION_MARKER), 'utf8').trim() : 'installed';
+    env.summary.push('vscode: ' + version + ' (portable; run code . or use the desktop shortcut)');
+};

package/dist/guest/view.d.ts

@@ -0,0 +1 @@
+export declare const viewSession: (id: string) => Promise<number>;

package/dist/guest/view.js

@@ -0,0 +1,42 @@
+// A terminal tab inside the sandbox that shows one agent session (same pseudo console the host can attach to).
+// Usage: node view.js <sessionId>
+import { connect, runTerminalClient } from '../shared/pty-client.js';
+import { readSession } from '../shared/rundir.js';
+import { dataDir } from './env.js';
+/** A session that is still being set up (its project provisioning, its agent installing): show the progress until it runs. */
+const waitUntilStarted = async (id) => {
+    let last = '';
+    for (let i = 0; i < 3600; i++) {
+        const s = readSession(dataDir, id);
+        if (s && s.phase !== 'starting')
+            return s;
+        if (s && s.message !== last) {
+            console.log('  ' + s.message);
+            last = s.message;
+        }
+        await new Promise((r) => setTimeout(r, 500));
+    }
+    return readSession(dataDir, id);
+};
+export const viewSession = async (id) => {
+    const session = await waitUntilStarted(id);
+    if (session?.phase === 'failed') {
+        console.error('Session ' + id + ' could not start: ' + session.message);
+        await new Promise((r) => setTimeout(r, 30000));
+        return 1;
+    }
+    if (!session?.attach) {
+        console.error('Session ' + id + ' is not running.');
+        return 1;
+    }
+    const socket = await connect({ ...session.attach, addresses: ['127.0.0.1'] });
+    const result = await runTerminalClient(socket, session.attach.token);
+    if (result.reason === 'exit')
+        console.log(session.harness + ' exited with code ' + result.exitCode + '.');
+    else if (result.reason === 'error')
+        console.log('Session error: ' + result.message);
+    return result.reason === 'exit' ? result.exitCode : 1;
+};
+if (process.argv[1]?.endsWith('view.js') && process.argv[2]) {
+    viewSession(process.argv[2]).then((code) => { process.exitCode = code; }, (e) => { console.error(e instanceof Error ? e.message : String(e)); process.exitCode = 1; });
+}

package/dist/host/accounts.d.ts

@@ -0,0 +1,32 @@
+export interface Account {
+    name: string;
+    savedAt: string;
+    email: string | null;
+    credentials: unknown;
+    oauthAccount: unknown;
+}
+export interface AccountRow {
+    name: string;
+    email: string | null;
+    isDefault: boolean;
+    isActive: boolean;
+    savedAt: string;
+}
+export declare const accountsDir: (storageRoot: string) => string;
+export declare const sandboxClaudeDir: (dataPath: string) => string;
+export declare const readAccount: (storageRoot: string, name: string) => Account | null;
+export declare const defaultAccount: (storageRoot: string) => string | null;
+export declare const activeAccount: (dataPath: string) => string | null;
+export declare const listAccounts: (storageRoot: string, dataPath: string) => AccountRow[];
+/** Saves the sandbox's current login (or this PC's, with fromHost) under `name`. */
+export declare const saveAccount: (storageRoot: string, dataPath: string, name: string, fromHost: {
+    claudeDir: string;
+    globalStateFile: string;
+} | null) => Account;
+/**
+ * Makes `name` the sandbox's login. Claude refreshes (rotates) tokens while it runs, so the outgoing account's
+ * current tokens are saved back first; otherwise its stored refresh token could already be invalid.
+ */
+export declare const activateAccount: (storageRoot: string, dataPath: string, name: string) => Account;
+export declare const setDefaultAccount: (storageRoot: string, name: string | null) => void;
+export declare const removeAccount: (storageRoot: string, name: string) => void;

package/dist/host/accounts.js

@@ -0,0 +1,128 @@
+// Several Claude logins for the sandbox. Each account is a saved copy of Claude's .credentials.json plus the
+// `oauthAccount` block of .claude.json, kept in host-only storage (<storage>\accounts, never mapped into a sandbox).
+// Switching writes them into the sandbox's persistent Claude state; when the sandbox is running the agent is then
+// restarted in place with --continue so the conversation carries on.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { isSafeFileName } from '../shared/paths.js';
+import { assertTestWritable } from './test-guard.js';
+import { readValid, writeJsonAtomic } from '../shared/rundir.js';
+import { assertNoLinks, fail, fileExists, isLink, removeLink, tryReadJson, writeJson } from '../core/util.js';
+const NAME = /^[A-Za-z0-9_-]{1,40}$/;
+const AccountSchema = z.object({ name: z.string().regex(NAME), savedAt: z.string().max(64), email: z.string().max(200).nullable(), credentials: z.looseObject({}), oauthAccount: z.unknown() });
+const IndexSchema = z.object({ default: z.string().regex(NAME).optional(), active: z.record(z.string().max(200), z.string().regex(NAME)).optional() });
+const ACCOUNT_CACHES = ['remote-settings.json', 'policy-limits.json', 'policy-limits.json.stamp.json'];
+const MAX_LOGIN_BYTES = 1024 * 1024;
+/** .claude.json holds per-project state and can be large; it is still capped so a hostile file cannot exhaust memory. */
+const MAX_STATE_BYTES = 256 * 1024 * 1024;
+export const accountsDir = (storageRoot) => path.join(storageRoot, 'accounts');
+export const sandboxClaudeDir = (dataPath) => path.join(dataPath, 'state', 'claude');
+const storageOf = (dataPath) => path.dirname(path.dirname(dataPath));
+const dataName = (dataPath) => path.basename(dataPath);
+const accountFile = (storageRoot, name) => path.join(accountsDir(storageRoot), name + '.json');
+const indexFile = (storageRoot) => path.join(accountsDir(storageRoot), 'index.json');
+const readIndex = (storageRoot) => readValid(IndexSchema, indexFile(storageRoot)) ?? {};
+const updateIndex = (storageRoot, change) => writeJsonAtomic(indexFile(storageRoot), change(readIndex(storageRoot)));
+/** A file name of its own: not "index" (the index file), not a Windows device name such as con or nul. */
+const validName = (name) => NAME.test(name) && name.toLowerCase() !== 'index' && isSafeFileName(name + '.json');
+const assertName = (name) => { if (!validName(name))
+    fail('Invalid account name "' + name + '".', 'Use letters, numbers, - and _ only (max 40), e.g. work or personal.'); };
+const emailOf = (oauthAccount) => {
+    const email = oauthAccount?.emailAddress;
+    return typeof email === 'string' ? email.slice(0, 200) : null;
+};
+export const readAccount = (storageRoot, name) => (validName(name) ? readValid(AccountSchema, accountFile(storageRoot, name)) : null);
+export const defaultAccount = (storageRoot) => readIndex(storageRoot).default ?? null;
+export const activeAccount = (dataPath) => readIndex(storageOf(dataPath)).active?.[dataName(dataPath)] ?? null;
+const setActive = (dataPath, name) => updateIndex(storageOf(dataPath), (i) => ({ ...i, active: { ...i.active, [dataName(dataPath)]: name } }));
+export const listAccounts = (storageRoot, dataPath) => {
+    const dir = accountsDir(storageRoot);
+    if (!fs.existsSync(dir))
+        return [];
+    const def = defaultAccount(storageRoot);
+    const active = activeAccount(dataPath);
+    return fs.readdirSync(dir)
+        .filter((f) => f.endsWith('.json') && f !== 'index.json')
+        .map((f) => readAccount(storageRoot, f.slice(0, -5)))
+        .filter((a) => a !== null)
+        .map((a) => ({ name: a.name, email: a.email, isDefault: a.name === def, isActive: a.name === active, savedAt: a.savedAt }));
+};
+/** Reads a JSON file that may be sandbox-written: no links, size-capped. */
+const readUntrusted = (file, max) => (fileExists(file) && !isLink(file) && fs.statSync(file).size <= max ? tryReadJson(file) : null);
+/** The login currently in a Claude config folder (+ its global state file). */
+const readLogin = (claudeDir, globalStateFile) => {
+    const credentials = readUntrusted(path.join(claudeDir, '.credentials.json'), MAX_LOGIN_BYTES);
+    if (!credentials || typeof credentials !== 'object')
+        fail('No Claude login found in ' + claudeDir + '.', 'Sign in to Claude first (inside the sandbox, or on this PC with --from-host), then save it again.');
+    return { credentials, oauthAccount: readUntrusted(globalStateFile, MAX_STATE_BYTES)?.oauthAccount ?? null };
+};
+const store = (storageRoot, name, login) => {
+    const account = { name, savedAt: new Date().toISOString(), email: emailOf(login.oauthAccount), ...login };
+    writeJsonAtomic(accountFile(storageRoot, name), account);
+    return account;
+};
+const sandboxLogin = (dataPath) => {
+    assertNoLinks(dataPath, sandboxClaudeDir(dataPath));
+    return { claudeDir: sandboxClaudeDir(dataPath), globalStateFile: path.join(sandboxClaudeDir(dataPath), '.claude.json') };
+};
+/** Saves the sandbox's current login (or this PC's, with fromHost) under `name`. */
+export const saveAccount = (storageRoot, dataPath, name, fromHost) => {
+    assertName(name);
+    const source = fromHost ?? sandboxLogin(dataPath);
+    const account = store(storageRoot, name, readLogin(source.claudeDir, source.globalStateFile));
+    if (!fromHost)
+        setActive(dataPath, name);
+    if (!defaultAccount(storageRoot))
+        setDefaultAccount(storageRoot, name);
+    return account;
+};
+/** Replaces a file that may be a sandbox-planted link instead of writing through it. */
+const writeSandboxJson = (file, value) => {
+    assertTestWritable(file);
+    if (isLink(file))
+        removeLink(file);
+    writeJson(file, value);
+};
+/**
+ * Makes `name` the sandbox's login. Claude refreshes (rotates) tokens while it runs, so the outgoing account's
+ * current tokens are saved back first; otherwise its stored refresh token could already be invalid.
+ */
+export const activateAccount = (storageRoot, dataPath, name) => {
+    const account = readAccount(storageRoot, name) ?? fail('Unknown account "' + name + '".', 'Saved accounts: ' + (listAccounts(storageRoot, dataPath).map((a) => a.name).join(', ') || 'none yet; save one with sandbox account save <name>'));
+    const { claudeDir, globalStateFile } = sandboxLogin(dataPath);
+    const outgoing = activeAccount(dataPath);
+    if (outgoing && outgoing !== name && readAccount(storageRoot, outgoing) && fileExists(path.join(claudeDir, '.credentials.json'))) {
+        try {
+            store(storageRoot, outgoing, readLogin(claudeDir, globalStateFile));
+        }
+        catch { /* nothing usable to save back */ }
+    }
+    fs.mkdirSync(claudeDir, { recursive: true });
+    // Caches tied to the previous account (Claude deletes these on /logout); otherwise its org policy could linger.
+    for (const cache of ACCOUNT_CACHES) {
+        const file = path.join(claudeDir, cache);
+        if (isLink(file))
+            removeLink(file);
+        else
+            fs.rmSync(file, { force: true });
+    }
+    writeSandboxJson(path.join(claudeDir, '.credentials.json'), account.credentials);
+    const state = readUntrusted(globalStateFile, MAX_STATE_BYTES);
+    if (account.oauthAccount && (state || !fileExists(globalStateFile)))
+        writeSandboxJson(globalStateFile, { ...(state ?? {}), oauthAccount: account.oauthAccount });
+    setActive(dataPath, name);
+    return account;
+};
+export const setDefaultAccount = (storageRoot, name) => {
+    if (name !== null && !readAccount(storageRoot, name))
+        fail('Unknown account "' + name + '".', 'See your accounts with: sandbox account list');
+    updateIndex(storageRoot, (i) => ({ ...i, default: name ?? undefined }));
+};
+export const removeAccount = (storageRoot, name) => {
+    if (!readAccount(storageRoot, name))
+        fail('Unknown account "' + name + '".', 'See your accounts with: sandbox account list');
+    fs.rmSync(accountFile(storageRoot, name));
+    if (defaultAccount(storageRoot) === name)
+        setDefaultAccount(storageRoot, null);
+};

package/dist/host/agent-commands.d.ts

@@ -0,0 +1,25 @@
+import type { Config } from '../core/types.js';
+export declare const commandsDir: (storageRoot: string) => string;
+export interface AgentCommand {
+    harness: string;
+    command: string;
+    real: string;
+}
+/** The agent's own executable on this PC, skipping this tool's forwarding files. */
+export declare const realAgent: (command: string, skipDir: string, pathValue?: string) => string | null;
+/** The agents that get a forwarding command: installed on this PC, and listed (or "auto" = all of them). */
+export declare const agentCommands: (config: Config, storageRoot: string, pathValue?: string) => AgentCommand[];
+/** The .cmd file for one agent (cmd, PowerShell and Windows Terminal all run it). */
+export declare const forwardingCmd: (a: AgentCommand, node: string, entry: string) => string;
+/** The same for Git Bash, which looks for a file without an extension. */
+export declare const forwardingSh: (a: AgentCommand, node: string, entry: string) => string;
+export interface Reconciled {
+    on: boolean;
+    commands: AgentCommand[];
+    changed: boolean;
+}
+/**
+ * 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 declare const reconcileAgentCommands: (config: Config, storageRoot: string, node: string, entry: string) => Reconciled;

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>;