windows-development-sandbox 0.0.0-stage → 1.0.5

package/dist/guest/setup/claude.js

@@ -0,0 +1,138 @@
+// Claude settings from this PC, plugin path fix-up, and the claude-mem working copy.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { translatePaths } from '../../shared/paths.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'];
+/** Plugin manifests store absolute paths to the plugin cache; point them at the sandbox's Claude folder. */
+const fixPluginPaths = (hostConfigDir) => {
+    const plugins = path.join(claudeDir, 'plugins');
+    if (!hostConfigDir || !exists(plugins))
+        return;
+    for (const name of fs.readdirSync(plugins).filter((f) => f.endsWith('.json'))) {
+        const file = path.join(plugins, name);
+        const text = fs.readFileSync(file, 'utf8');
+        const fixed = translatePaths(text, hostConfigDir, claudeDir);
+        if (fixed !== text)
+            fs.writeFileSync(file, fixed, 'utf8');
+    }
+};
+const readState = (file) => { try {
+    return JSON.parse(fs.readFileSync(file, 'utf8').replace(/^/, ''));
+}
+catch {
+    return null;
+} };
+const sameFolder = (a, b) => a.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase() === b.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+/**
+ * The sandbox keeps its own .claude.json (login, onboarding, per-project state), so MCP servers from this PC are
+ * merged into it each boot: user-scope `mcpServers`, and this project's local-scope servers under the sandbox path.
+ * Servers with the same name are replaced by this PC's definition; servers added inside the sandbox are kept.
+ */
+export const mergeMcpServers = (hostFile, guestFile, hostWorkspace, guestWorkspace) => {
+    const host = readState(hostFile);
+    const guest = readState(guestFile);
+    if (!host || !guest)
+        return 0;
+    const hostProject = Object.entries(host.projects ?? {}).find(([key]) => sameFolder(key, hostWorkspace))?.[1]?.mcpServers ?? {};
+    const projects = { ...(guest.projects ?? {}) };
+    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');
+    return Object.keys(host.mcpServers ?? {}).length + Object.keys(hostProject).length;
+};
+export const syncClaudeProfile = () => {
+    const profile = session.claudeProfile;
+    if (profile.items.length === 0) {
+        log('No Claude settings were staged from this PC.');
+        return;
+    }
+    const source = path.join(launchDir, 'claude-profile');
+    mkdirp(claudeDir);
+    for (const name of profile.items) {
+        const from = path.join(source, name);
+        const to = path.join(claudeDir, name);
+        if (!exists(from))
+            continue;
+        if ((KEEP_SANDBOX_COPY.includes(name) || !profile.overwrite) && exists(to)) {
+            log('Claude settings: kept the sandbox\'s ' + name);
+            continue;
+        }
+        // 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 });
+        fs.cpSync(from, to, { recursive: true, force: true });
+        log('Claude settings: copied ' + name + ' from this PC');
+    }
+    fixPluginPaths(profile.hostConfigDir);
+    const mcp = mergeMcpServers(path.join(source, '.claude.json'), path.join(claudeDir, '.claude.json'), session.workspaceHost, workspace);
+    if (mcp)
+        log('Claude settings: ' + mcp + ' MCP server(s) from this PC merged in');
+    if (profile.credentials)
+        warn('Your host Claude LOGIN was copied into the sandbox (copyCredentials is true).');
+};
+/**
+ * claude-mem keeps SQLite + a vector store. They run from the sandbox's own disk (SQLite and mapped folders do not
+ * mix) and are mirrored to persistent storage, from where the host syncs them back to your PC.
+ */
+export 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))
+        return;
+    robocopy(claudeMemPaths.store, claudeMemPaths.local);
+    log('claude-mem data restored from persistent storage.');
+};
+/** Size + mtime of every SQLite database and -wal file under `dir`: when these have not moved, nothing was written. */
+const databaseFingerprint = (dir) => {
+    const parts = [];
+    const walk = (folder) => {
+        for (const entry of fs.readdirSync(folder, { withFileTypes: true })) {
+            const full = path.join(folder, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.isFile() && /\.(db|sqlite3?)(-wal)?$/i.test(entry.name)) {
+                const s = fs.statSync(full);
+                parts.push(full + ':' + s.size + ':' + s.mtimeMs);
+            }
+        }
+    };
+    walk(dir);
+    return parts.sort().join('|');
+};
+/** The databases as of the last save by this process (null: not saved yet, so the first save always copies). */
+let lastSaved = null;
+/**
+ * Copies the live claude-mem folder back to persistent storage (staging folder + swap, never a half copy). Called from
+ * the daemon tick: when no database changed since the last save it does nothing (no copy of the whole folder).
+ */
+export const saveClaudeMem = () => {
+    if (!claudeMemEnabled() || !exists(claudeMemPaths.local))
+        return;
+    const { store, local } = claudeMemPaths;
+    const fingerprint = databaseFingerprint(local);
+    if (fingerprint === lastSaved && exists(store))
+        return;
+    const incoming = store + '.incoming';
+    const previous = store + '.previous';
+    fs.rmSync(incoming, { recursive: true, force: true });
+    // The database, its -wal and -shm files are copied together, so the copy is consistent with itself.
+    fs.cpSync(local, incoming, { recursive: true, filter: (src) => !/\.(pid|lock)$/i.test(src) });
+    // Swap without a window where no copy exists: old aside, new in, then drop the old one.
+    fs.rmSync(previous, { recursive: true, force: true });
+    if (exists(store))
+        fs.renameSync(store, previous);
+    try {
+        fs.renameSync(incoming, store);
+    }
+    catch (e) {
+        if (exists(previous))
+            fs.renameSync(previous, store);
+        throw e;
+    }
+    fs.rmSync(previous, { recursive: true, force: true });
+    lastSaved = fingerprint;
+};

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

@@ -0,0 +1,6 @@
+import type { ToolEnv } from '../toolchains/index.js';
+export declare const agentEnv: (tools: Pick<ToolEnv, "vars" | "prepend" | "append">) => 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;

package/dist/guest/setup/environment.js

@@ -0,0 +1,65 @@
+// The environment every agent session, hook and terminal tab in the sandbox gets.
+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) => {
+    const env = {
+        ...process.env,
+        ...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_DATA: dataDir,
+        AGENT_TOOLS: toolsDir,
+        AGENT_PROJECT: session.project,
+        // For project scripts: "am I in the sandbox, and where is the project?" (stable names; documented).
+        AGENT_SANDBOX: '1',
+        AGENT_SANDBOX_WORKSPACE: 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()));
+    env.PATH = [...new Set([...tools.prepend, ...base, ...tools.append])].join(path.delimiter);
+    return env;
+};
+/** Makes the agent environment machine-wide, so new terminal tabs and anything the agent starts see the same tools. */
+export const persistEnvironment = (env, toolVars) => {
+    if (!isWin || dryRun || testMode)
+        return;
+    const vars = Object.fromEntries([...toolVars, ...AGENT_VARS].filter((n) => env[n] !== undefined).map((n) => [n, env[n]]));
+    const script = [
+        "$vars = '" + JSON.stringify(vars).replace(/'/g, "''") + "' | ConvertFrom-Json",
+        "foreach ($p in $vars.PSObject.Properties) { [Environment]::SetEnvironmentVariable($p.Name, [string]$p.Value, 'Machine') }",
+        "[Environment]::SetEnvironmentVariable('Path', '" + (env.PATH ?? '').replace(/'/g, "''") + "', 'Machine')",
+    ].join('\n');
+    try {
+        powershell(script);
+    }
+    catch (e) {
+        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) => {
+    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') }",
+        "$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') }",
+    ].join('\n');
+    try {
+        powershell(script);
+    }
+    catch (e) {
+        warn('Could not add to the environment: ' + errMsg(e));
+    }
+};

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

@@ -0,0 +1 @@
+export declare const runHooks: (stage: string, env: NodeJS.ProcessEnv) => void;

package/dist/guest/setup/hooks.js

@@ -0,0 +1,36 @@
+// User hook scripts (.ps1 / .mjs / .js / .cmd / .bat) from hooks\<stage>, run in name order in the workspace.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { SYSTEM } from '../../shared/system.js';
+import { exists, isWin, launchDir, log, session, warn, workspace } from '../env.js';
+const commandFor = (file) => {
+    const ext = path.extname(file).toLowerCase();
+    if (ext === '.mjs' || ext === '.js')
+        return [process.execPath, [file]];
+    if (!isWin)
+        return null;
+    if (ext === '.ps1')
+        return [SYSTEM.powershell(), ['-NoLogo', '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', file]];
+    if (ext === '.cmd' || ext === '.bat')
+        return [SYSTEM.cmd(), ['/d', '/c', file]];
+    return null;
+};
+export const runHooks = (stage, env) => {
+    const dir = path.join(launchDir, 'hooks', stage);
+    if (!exists(dir))
+        return;
+    for (const name of fs.readdirSync(dir).sort()) {
+        const command = commandFor(path.join(dir, name));
+        if (!command)
+            continue;
+        log('Hook [' + stage + ']: ' + name);
+        const result = spawnSync(command[0], command[1], { stdio: 'inherit', cwd: workspace, env });
+        if (result.status === 0)
+            continue;
+        const message = 'Hook failed (' + stage + '/' + name + ', exit ' + result.status + ')';
+        if (session.hooks.failFast)
+            throw new Error(message);
+        warn(message);
+    }
+};

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

@@ -0,0 +1,10 @@
+/** What the agent's manifest says about the LAN. */
+export type LanState = 'blocked' | 'open' | 'offline';
+/**
+ * Applies the LAN block. Internet is checked first; if it works before the rules but not after, the rules (not the
+ * internet) are the problem, so they are removed and the agent is told the LAN is open. If there is no internet at
+ * all, the block stays in place: being offline is never a reason to open the LAN.
+ */
+export declare const applyNetworkPolicy: (ptyHostExe: string | null) => Promise<LanState>;
+/** Guest IPv4 addresses the host can use to reach session ports. */
+export declare const guestAddresses: () => string[];

package/dist/guest/setup/network.js

@@ -0,0 +1,99 @@
+// Guest firewall: block the host's LAN (keeping DNS/DHCP to the gateway) and let the host reach session ports.
+import dns from 'node:dns';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { buildFirewallCommands, ipv4DnsServers, parseDefaultGateways, parseDnsServers } from '../../shared/netrules.js';
+import { SYSTEM } from '../../shared/system.js';
+import { dryRun, isWin, log, session, warn } from '../env.js';
+const ATTACH_RULE = 'AgentSandbox-Attach';
+const netsh = (args) => {
+    const r = spawnSync(SYSTEM.netsh(), args, { encoding: 'utf8', windowsHide: true });
+    return { status: r.status, out: (r.stdout ?? '') + (r.stderr ?? '') };
+};
+const discoverExemptIps = () => {
+    if (process.env.AGENT_TEST_EXEMPT)
+        return process.env.AGENT_TEST_EXEMPT.split(',');
+    if (!isWin)
+        return [];
+    const route = spawnSync(SYSTEM.route(), ['print', '-4'], { encoding: 'utf8', windowsHide: true });
+    // The resolver's own list works on every Windows language; `ipconfig /all` (English labels only) is the fallback.
+    let servers = [];
+    try {
+        servers = ipv4DnsServers(dns.getServers());
+    }
+    catch { /* fall back below */ }
+    if (!servers.length)
+        servers = parseDnsServers(spawnSync(SYSTEM.ipconfig(), ['/all'], { encoding: 'utf8', windowsHide: true }).stdout ?? '');
+    return [...parseDefaultGateways(route.stdout ?? ''), ...servers];
+};
+const internetWorks = async () => {
+    try {
+        return (await fetch('https://nodejs.org', { method: 'HEAD', signal: AbortSignal.timeout(10000) })).status > 0;
+    }
+    catch {
+        return false;
+    }
+};
+/** The sandbox network can take a few seconds to come up after logon. */
+const waitForInternet = async (seconds) => {
+    for (const end = Date.now() + seconds * 1000; Date.now() < end;) {
+        if (await internetWorks())
+            return true;
+        await new Promise((r) => setTimeout(r, 2000));
+    }
+    return false;
+};
+/** Inbound rule for ptyhost only, and only from the sandbox's own subnet (where the host's Hyper-V adapter is). */
+const attachRule = (ptyHostExe) => [
+    ['advfirewall', 'firewall', 'delete', 'rule', 'name=' + ATTACH_RULE],
+    ['advfirewall', 'firewall', 'add', 'rule', 'name=' + ATTACH_RULE, 'dir=in', 'action=allow', 'enable=yes', 'profile=any', 'protocol=tcp', 'remoteip=LocalSubnet', 'program=' + ptyHostExe],
+];
+const run = (commands) => {
+    for (const c of commands) {
+        const r = netsh(c);
+        if (r.status !== 0 && c[2] !== 'delete')
+            throw new Error('netsh ' + c.slice(0, 5).join(' ') + ' failed (exit ' + r.status + '): ' + r.out.trim());
+    }
+};
+/**
+ * Applies the LAN block. Internet is checked first; if it works before the rules but not after, the rules (not the
+ * internet) are the problem, so they are removed and the agent is told the LAN is open. If there is no internet at
+ * all, the block stays in place: being offline is never a reason to open the LAN.
+ */
+export const applyNetworkPolicy = async (ptyHostExe) => {
+    if (!session.networking) {
+        log('Networking is disabled for this sandbox.');
+        return 'offline';
+    }
+    const block = session.network.blockPrivateRanges;
+    const exempt = block ? discoverExemptIps() : [];
+    const lanRules = block ? buildFirewallCommands(exempt) : [];
+    const commands = [...lanRules, ...(ptyHostExe && session.attach.enabled ? attachRule(ptyHostExe) : [])];
+    if (!block)
+        log('Private-range blocking disabled by config.');
+    if (block)
+        log('Gateway/DNS addresses kept reachable for DNS only: ' + (exempt.length ? [...new Set(exempt)].join(', ') : '(none found)'));
+    if (!isWin || dryRun) {
+        log('(dry run) firewall plan:');
+        for (const c of commands)
+            log('  netsh ' + c.join(' '));
+        return block ? 'blocked' : 'open';
+    }
+    if (commands.length === 0)
+        return 'open';
+    const online = block ? await waitForInternet(30) : true;
+    run(commands);
+    if (!block)
+        return 'open';
+    if (online && !(await waitForInternet(15))) {
+        run(lanRules.filter((c) => c[2] === 'delete'));
+        warn('The LAN block broke internet access in this sandbox, so it was removed: the agent CAN reach your local network this time. Set sandbox.networking to false for hard isolation.');
+        return 'open';
+    }
+    if (!online)
+        warn('No internet detected yet; the LAN block is in place anyway.');
+    log('LAN blocked in the guest firewall (10/8, 172.16/12, 192.168/16, 100.64/10, link-local, multicast, IPv6 local, SMB); DNS/DHCP to the gateway allowed.');
+    return 'blocked';
+};
+/** Guest IPv4 addresses the host can use to reach session ports. */
+export const guestAddresses = () => Object.values(os.networkInterfaces()).flat().filter((i) => Boolean(i) && i.family === 'IPv4' && !i.internal).map((i) => i.address);

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

@@ -0,0 +1,3 @@
+import type { GitAccess } from '../../core/types.js';
+export declare const managedSettingsFile: () => string;
+export declare const writeManagedSettings: (access: GitAccess) => void;

package/dist/guest/setup/policy.js

@@ -0,0 +1,18 @@
+// Claude Code managed settings for the sandbox (C:\Program Files\ClaudeCode\managed-settings.json). Managed settings
+// have the highest precedence and cannot be overridden by user or project settings, so they carry the hard rules:
+// today, the git access mode. Rewritten every boot; removed when there is nothing to enforce.
+import fs from 'node:fs';
+import path from 'node:path';
+import { gitDenyRules } from '../gitrules.js';
+import { managedClaudeMd } from '../guide.js';
+export const managedSettingsFile = () => path.join(path.dirname(managedClaudeMd()), 'managed-settings.json');
+export const writeManagedSettings = (access) => {
+    const file = managedSettingsFile();
+    const deny = gitDenyRules(access);
+    if (deny.length === 0) {
+        fs.rmSync(file, { force: true });
+        return;
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ permissions: { deny } }, null, 2) + '\n', 'utf8');
+};

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

@@ -0,0 +1,7 @@
+/** Imports the host's look (registry values + wallpaper) and restarts Explorer so it applies. */
+export declare const applyPersonalization: () => void;
+/**
+ * Your Git identity from this PC (name/email only), plus safe.directory for the mapped workspace (its owner SID
+ * differs in the sandbox). Uses the real git.exe directly: the read-only guard would rightly refuse `config --add`.
+ */
+export declare const setupGitConfig: (env: NodeJS.ProcessEnv) => void;

package/dist/guest/setup/user.js

@@ -0,0 +1,47 @@
+// Making the sandbox feel like your PC: desktop look and Git identity.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { SYSTEM } from '../../shared/system.js';
+import { dryRun, exec, exists, isWin, launchDir, log, mkdirp, powershell, session, toolsDir } from '../env.js';
+const psQuote = (s) => "'" + s.replace(/'/g, "''") + "'";
+/** Imports the host's look (registry values + wallpaper) and restarts Explorer so it applies. */
+export const applyPersonalization = () => {
+    const dir = path.join(launchDir, 'personalize');
+    if (!session.personalization || !exists(dir) || dryRun || !isWin)
+        return;
+    exec(SYSTEM.reg(), ['import', path.join(dir, 'personalize.reg')], { stdio: 'ignore' });
+    const wallpaper = fs.readdirSync(dir).find((f) => f.startsWith('wallpaper'));
+    const local = wallpaper ? path.join(mkdirp(path.join(os.homedir(), 'Pictures')), wallpaper) : null;
+    if (wallpaper && local)
+        fs.copyFileSync(path.join(dir, wallpaper), local);
+    powershell([
+        local ? "Set-ItemProperty -Path 'HKCU:\\Control Panel\\Desktop' -Name WallPaper -Value " + psQuote(local) : '',
+        "Add-Type -Namespace AgentSandbox -Name Desk -MemberDefinition '[System.Runtime.InteropServices.DllImport(\"user32.dll\", CharSet = System.Runtime.InteropServices.CharSet.Unicode)] public static extern int SystemParametersInfo(int a, int b, string c, int d);'",
+        local ? '[void][AgentSandbox.Desk]::SystemParametersInfo(20, 0, ' + psQuote(local) + ', 3)' : '',
+        // Explorer restarts by itself and picks up taskbar/theme changes.
+        'Stop-Process -Name explorer -Force -ErrorAction SilentlyContinue',
+    ].filter(Boolean).join('\n'));
+    log('Desktop personalisation applied from this PC.');
+};
+/**
+ * Your Git identity from this PC (name/email only), plus safe.directory for the mapped workspace (its owner SID
+ * differs in the sandbox). Uses the real git.exe directly: the read-only guard would rightly refuse `config --add`.
+ */
+export const setupGitConfig = (env) => {
+    // A dry run (the self-test) must not touch the real ~/.gitconfig: it once replaced the sandbox's own, safe.directory
+    // included, so git refused the workspace until the next boot.
+    if (dryRun)
+        return;
+    const source = path.join(launchDir, 'home', '.gitconfig');
+    if (exists(source))
+        fs.copyFileSync(source, path.join(os.homedir(), '.gitconfig'));
+    const git = path.join(toolsDir, 'git', 'cmd', 'git.exe');
+    if (!exists(git))
+        return;
+    const { GIT_DIR: _gitDir, ...rest } = env;
+    spawnSync(git, ['config', '--global', '--add', 'safe.directory', '*'], { env: rest, windowsHide: true, stdio: 'ignore' });
+    // Windows long paths are on in the sandbox, but git skips files over 260 characters unless told.
+    spawnSync(git, ['config', '--global', 'core.longpaths', 'true'], { env: rest, windowsHide: true, stdio: 'ignore' });
+};

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

@@ -0,0 +1,7 @@
+import type { SpawnOptions } from 'node:child_process';
+/**
+ * Returns the installer for one crate: `cargo binstall` (prebuilt only: its own compile fallback is off, so a crate
+ * without a Windows build is compiled by our `cargo install` with the linker settings in `cargoEnv`), then
+ * `cargo install --locked`. cargo-binstall is fetched on first use, so boots with every crate installed download nothing.
+ */
+export declare const crateInstaller: (cargoHome: string, cargoEnv: SpawnOptions) => ((crate: string) => Promise<void>);

package/dist/guest/toolchains/binstall.js

@@ -0,0 +1,55 @@
+// toolchains.rust.crates with prebuilt binaries: cargo-binstall (from its own GitHub release) fetches a crate's
+// published Windows build in seconds; only crates without one are compiled with `cargo install --locked`.
+import fs from 'node:fs';
+import path from 'node:path';
+import { githubAsset, installArchive } from '../../shared/download.js';
+import { errMsg, execAsync, exists, log, warn } from '../env.js';
+import { binstallAsset } from './catalogue.js';
+import { arch, tool } from './common.js';
+/**
+ * cargo-binstall.exe into CARGO_HOME\bin (so `cargo binstall` works for the agent too). Downloaded into its own
+ * tools\cargo-binstall folder first: installArchive replaces its destination, which must never be cargo's bin.
+ */
+const ensureBinstall = async (cargoBin) => {
+    const target = path.join(cargoBin, 'cargo-binstall.exe');
+    if (exists(target))
+        return true;
+    try {
+        const dir = tool('cargo-binstall');
+        if (!exists(path.join(dir, 'cargo-binstall.exe'))) {
+            const asset = await githubAsset('cargo-bins/cargo-binstall', binstallAsset(arch));
+            log('Downloading ' + asset.name + ' (prebuilt Rust tools) ...');
+            await installArchive(asset.url, dir, { sha256: asset.sha256, locate: 'cargo-binstall.exe', fileName: asset.name });
+        }
+        fs.copyFileSync(path.join(dir, 'cargo-binstall.exe'), target);
+        return true;
+    }
+    catch (e) {
+        warn('cargo-binstall unavailable, compiling crates with cargo install instead: ' + errMsg(e));
+        return false;
+    }
+};
+/**
+ * Returns the installer for one crate: `cargo binstall` (prebuilt only: its own compile fallback is off, so a crate
+ * without a Windows build is compiled by our `cargo install` with the linker settings in `cargoEnv`), then
+ * `cargo install --locked`. cargo-binstall is fetched on first use, so boots with every crate installed download nothing.
+ */
+export const crateInstaller = (cargoHome, cargoEnv) => {
+    const cargo = path.join(cargoHome, 'bin', 'cargo.exe');
+    let binstall = null;
+    // quick-install's install statistics are opt-out; the sandbox opts out.
+    const binstallEnv = { ...cargoEnv, env: { ...(cargoEnv.env ?? process.env), BINSTALL_DISABLE_TELEMETRY: 'true' } };
+    return async (crate) => {
+        binstall ??= ensureBinstall(path.join(cargoHome, 'bin'));
+        if (await binstall) {
+            try {
+                await execAsync(cargo, ['binstall', '--no-confirm', '--locked', '--disable-strategies', 'compile', crate], binstallEnv);
+                return;
+            }
+            catch (e) {
+                log('No prebuilt ' + crate + ' for Windows (' + errMsg(e) + '); compiling it with cargo install ...');
+            }
+        }
+        await execAsync(cargo, ['install', '--locked', crate], cargoEnv);
+    };
+};

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

@@ -0,0 +1,51 @@
+import type { GitAccess } from '../../core/types.js';
+export type Arch = 'x64' | 'arm64';
+/** PowerShell/PowerShell: the portable zip (PowerShell-7.6.6-win-x64.zip), never the MSI or the fxdependent builds. */
+export declare const pwshAsset: (arch: Arch) => RegExp;
+/** cargo-bins/cargo-binstall: the plain zip (the .full build adds nothing we use; .sig files are signatures). */
+export declare const binstallAsset: (arch: Arch) => RegExp;
+/**
+ * One portable command-line tool from a GitHub release. The archive is unpacked into tools\cli\<name>; without
+ * `subdir` only the folder holding `exe` is kept (and goes on PATH), with `subdir` the whole archive stays and that
+ * folder inside it goes on PATH (for tools whose exe needs files next to it).
+ */
+export interface CliTool {
+    name: string;
+    repo: string;
+    asset: (arch: Arch) => RegExp;
+    exe: string;
+    subdir?: string;
+    /** What the tool is for (summary and docs). */
+    about: string;
+}
+export declare const CLI_TOOLS: readonly [{
+    readonly name: "gh";
+    readonly repo: "cli/cli";
+    readonly asset: (arch: Arch) => RegExp;
+    readonly exe: "gh.exe";
+    readonly about: "GitHub CLI";
+}, {
+    readonly name: "zstd";
+    readonly repo: "facebook/zstd";
+    readonly asset: () => RegExp;
+    readonly exe: "zstd.exe";
+    readonly about: "Zstandard compression";
+}];
+export type CliName = (typeof CLI_TOOLS)[number]['name'] | 'openssl';
+export declare const CLI_NAMES: readonly CliName[];
+/** toolchains.cli: each tool true, false or "auto" (gh: when the project has a .github folder; zstd: never by itself). */
+export type CliSettings = Partial<Record<CliName, boolean | 'auto'>>;
+export interface CliContext {
+    gitAccess: GitAccess;
+    /** The workspace has a .github folder (workflows, CODEOWNERS ...). */
+    hasGithubDir: boolean;
+}
+export interface CliDecision {
+    on: boolean;
+    reason: string;
+}
+/**
+ * Which catalogue tools a sandbox gets. gh is never installed unless git access is "full": gh pushes, merges and edits
+ * branches through the GitHub API, so it would walk straight past a "readonly" (or "none") git guard.
+ */
+export declare const decideCli: (settings: CliSettings, ctx: CliContext) => Record<CliName, CliDecision>;

package/dist/guest/toolchains/catalogue.js

@@ -0,0 +1,31 @@
+/** PowerShell/PowerShell: the portable zip (PowerShell-7.6.6-win-x64.zip), never the MSI or the fxdependent builds. */
+export const pwshAsset = (arch) => (arch === 'arm64' ? /^PowerShell-\d+\.\d+\.\d+-win-arm64\.zip$/ : /^PowerShell-\d+\.\d+\.\d+-win-x64\.zip$/);
+/** cargo-bins/cargo-binstall: the plain zip (the .full build adds nothing we use; .sig files are signatures). */
+export const binstallAsset = (arch) => (arch === 'arm64' ? /^cargo-binstall-aarch64-pc-windows-msvc\.zip$/ : /^cargo-binstall-x86_64-pc-windows-msvc\.zip$/);
+export const CLI_TOOLS = [
+    // gh_2.102.0_windows_amd64.zip holds bin\gh.exe.
+    { name: 'gh', repo: 'cli/cli', asset: (arch) => (arch === 'arm64' ? /^gh_\d+\.\d+\.\d+_windows_arm64\.zip$/ : /^gh_\d+\.\d+\.\d+_windows_amd64\.zip$/), exe: 'gh.exe', about: 'GitHub CLI' },
+    // zstd-v1.5.7-win64.zip; there is no arm64 build, and Windows on Arm runs the x64 one.
+    { name: 'zstd', repo: 'facebook/zstd', asset: () => /^zstd-v\d+\.\d+\.\d+-win64\.zip$/, exe: 'zstd.exe', about: 'Zstandard compression' },
+];
+export const CLI_NAMES = [...CLI_TOOLS.map((t) => t.name), 'openssl'];
+/**
+ * Which catalogue tools a sandbox gets. gh is never installed unless git access is "full": gh pushes, merges and edits
+ * branches through the GitHub API, so it would walk straight past a "readonly" (or "none") git guard.
+ */
+export const decideCli = (settings, ctx) => {
+    const decide = (name) => {
+        const setting = settings[name] ?? false;
+        if (name === 'gh' && setting !== false && ctx.gitAccess !== 'full')
+            return { on: false, reason: 'needs provisioning.git.access "full" (gh can push and merge through the GitHub API)' };
+        if (setting !== 'auto')
+            return { on: setting, reason: setting ? 'enabled in config' : 'disabled in config' };
+        if (name === 'gh' && ctx.hasGithubDir)
+            return { on: true, reason: '.github' };
+        // openssl is only a shim onto Git's own copy: free, so "auto" means on.
+        if (name === 'openssl')
+            return { on: true, reason: 'Git for Windows ships it' };
+        return { on: false, reason: 'not listed in toolchains.cli' };
+    };
+    return Object.fromEntries(CLI_NAMES.map((name) => [name, decide(name)]));
+};

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

@@ -0,0 +1,10 @@
+import type { GitAccess } from '../../core/types.js';
+import { type CliSettings } from './catalogue.js';
+import { type ToolEnv } from './common.js';
+/** gh keeps `gh auth login` here, under the agent state (persists like Claude's own login; never copied from the PC). */
+export declare const ghConfigDir: () => string;
+/**
+ * Installs the tools toolchains.cli asks for. Settings still "auto" here (normally the host decides) use the same
+ * rules on the workspace as the host would. The gh rule is enforced here again, whatever the host sent.
+ */
+export declare const setupCli: (env: ToolEnv, settings: CliSettings, gitAccess: GitAccess, refresh?: boolean) => Promise<void>;