windows-development-sandbox 1.11.7 → 1.13.0

package/dist/guest/daemon/sessions.js

@@ -1,6 +1,8 @@
-// `session` and `restart` requests: agent sessions, each in its own ptyhost process. A session runs in the launch
-// folder's project (the boot environment) or in a project registered later, which is provisioned first
-// (daemon/project).
+// `session`, `restart` and `close` requests: agent sessions and plain shell sessions, each in its own ptyhost process.
+// A session runs in the launch folder's project (the boot environment) or in a project registered later, which is
+// provisioned first (daemon/project). A shell gets the same environment as an agent, without the agent's own
+// environment (its keys) and without the agent's install, hooks and conversation tracking.
+import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import os from 'node:os';
@@ -10,7 +12,8 @@ import { isWithin } from '../../shared/paths/projects.js';
 import { now } from '../../shared/channel/run-dir.js';
 import { SYSTEM } from '../../shared/system.js';
 import { buildJobs, cargoJobs, linkSlotsFor, usableCpus } from '../../shared/memory/index.js';
-import { commandLine } from '../sessions/cmdline.js';
+import { commandLine, shellLaunch } from '../sessions/cmdline.js';
+import { pwshDir } from '../toolchains/tools/pwsh.js';
 import { freePort } from '../runtime/ports.js';
 import { primaryProject } from '../boot/project-status.js';
 import { ensurePtyHost, ptyHostLogTail, startPtyHost, waitForPtyHost } from '../sessions/pty-host.js';
@@ -30,7 +33,11 @@ import { isConversationId } from '../../shared/paths/conversation.js';
 import { errMsg } from '../../core/util/errors.js';
 import { provisioner } from './project-provisioner.js';
 import { IdleShutdown } from './idle-shutdown.js';
-import { insidePrimary, respond, safely, saveStatus } from './state.js';
+import { insidePrimary, insideWorkspace, respond, safely, saveStatus } from './state.js';
+/** How long a close waits for the session to end before it ends its ptyhost instead. */
+const CLOSE_WAIT_MS = 8000;
+/** An ended session's ptyhost is remembered this long: its last programs reach the audit up to 15 s later. */
+const ROOTS_KEPT_MS = 10 * 60 * 1000;
 function terminalTab(id, title, cwd) {
     const view = [process.execPath, path.join(path.dirname(process.argv[1]), 'view.js'), id];
     const wt = path.join(toolsDir, 'terminal', 'wt.exe');
@@ -93,16 +100,45 @@ function writeBudget(cpus, memoryGb, jobs, env) {
         warn('budget.json could not be written: ' + errMsg(e));
     }
 }
-/** Starts ptyhost for the agent and waits until it listens; a failure carries the tail of ptyhost's own log. */
-const launchPtyHost = async (req, remote, env, say, sessions) => {
+/** The agent, installed if it is not yet; its environment may hold its API keys. */
+const agentProgram = async (req, env, say) => {
     const harness = harnessFor(req);
     // Never refresh here: main already did, and replacing a running agent's executable would fail.
     say('Preparing ' + req.harness);
     await agents.provision(req.harness, harness, env, false);
     const launch = agents.resolveLaunch(req.harness, harness);
     const base = [...launch.args, ...harness.arguments];
+    return {
+        command: commandLine(launch.file, [...base, ...req.args]),
+        restartCommand: commandLine(launch.file, [...base, ...(harness.resumeArguments ?? [])]),
+        environment: harness.environment,
+    };
+};
+/** Where the shells are: PowerShell 7 from the toolchains (or an installed copy), Windows' own PowerShell and cmd. */
+function shellPaths() {
+    const candidates = [
+        path.join(pwshDir(), 'pwsh.exe'),
+        path.join(process.env.ProgramFiles ?? 'C:\\Program Files', 'PowerShell', '7', 'pwsh.exe'),
+    ];
+    return { pwsh: candidates.find((f) => fs.existsSync(f)) ?? null, powershell: SYSTEM.powershell(), cmd: SYSTEM.cmd() };
+}
+/** A plain shell: no install, no arguments of the request, nothing of the agent's environment. */
+const shellProgram = (shell) => {
+    const line = commandLine(shell.file, shell.args);
+    return { command: line, restartCommand: line, environment: {} };
+};
+/** Starts ptyhost for the program and waits until it listens; a failure carries the tail of ptyhost's own log. */
+const launchPtyHost = async (req, program, remote, env, sessions, onSpawn) => {
     const port = await freePort();
     const token = crypto.randomBytes(24).toString('base64url');
+    const sessionEnv = {
+        ...withRegistryPath(env),
+        ...program.environment,
+        ...memoryEnv(env, sessions),
+    };
+    // Each PowerShell builds its own module path; one inherited from another PowerShell breaks its modules.
+    if (req.shell)
+        delete sessionEnv.PSModulePath;
     const child = startPtyHost({
         exe: ensurePtyHost(),
         port,
@@ -111,11 +147,12 @@ const launchPtyHost = async (req, remote, env, say, sessions) => {
         rows: 32,
         id: req.id,
         cwd: req.cwd,
-        env: { ...withRegistryPath(env), ...harness.environment, ...memoryEnv(env, sessions) },
+        env: sessionEnv,
         remote,
-        command: commandLine(launch.file, [...base, ...req.args]),
-        restartCommand: commandLine(launch.file, [...base, ...(harness.resumeArguments ?? [])]),
+        command: program.command,
+        restartCommand: program.restartCommand,
     });
+    onSpawn(child);
     try {
         await waitForPtyHost(child, port, 15000);
     }
@@ -131,6 +168,16 @@ const launchPtyHost = async (req, remote, env, say, sessions) => {
 /** The launch folder's project, or the registered project this session is for (provisioned first if needed). */
 const placeFor = async (req, say) => {
     if (!req.project) {
+        // A project set up earlier (the web UI and sandbox shell name it by its folder only): its own environment.
+        const known = insidePrimary(req.cwd) ? null : provisioner.provisionedFor(req.cwd);
+        if (known && exists(req.cwd))
+            return {
+                env: known.env,
+                hooks: known.spec.hooks ? projectHooks(known.spec.name, known.spec.workspace) : null,
+                project: known.spec.name,
+            };
+        if (!insidePrimary(req.cwd) && insideWorkspace(req.cwd))
+            throw new Error('The project in ' + req.cwd + ' is not set up in the sandbox yet: run sandbox start in its folder first.');
         if (!insidePrimary(req.cwd) || !exists(req.cwd))
             throw new Error('Folder is not inside the sandbox workspace ' + workspace + ': ' + req.cwd);
         return { env: process.env, hooks: null, project: primaryProject() };
@@ -160,20 +207,55 @@ export class SessionManager {
     /** Sessions and projects being set up right now (a headless sandbox must not shut down under them). */
     starting = 0;
     idle = new IdleShutdown(() => this.live.size > 0 || this.starting > 0);
+    /** Each session's ptyhost (process id and when it ran), for linking the programs it starts to it (audit). */
+    ptyHosts = new Map();
     /** How many sessions are running. */
     get count() {
         return this.live.size;
     }
-    /** `session` requests: an agent in its own ptyhost, in the launch folder's project or a registered one. */
+    /** The sessions' ptyhosts, running or ended within ROOTS_KEPT_MS (audit events arrive after they happen). */
+    roots() {
+        const cutoff = Date.now() - ROOTS_KEPT_MS;
+        for (const [id, r] of this.ptyHosts)
+            if (r.to !== undefined && r.to < cutoff)
+                this.ptyHosts.delete(id);
+        return [...this.ptyHosts.values()];
+    }
+    rootStarted(id, child, from) {
+        if (child.pid)
+            this.ptyHosts.set(id, { session: id, pid: child.pid, from });
+        child.once('exit', () => this.rootEnded(id));
+    }
+    rootEnded(id) {
+        const r = this.ptyHosts.get(id);
+        if (r && r.to === undefined)
+            this.ptyHosts.set(id, { ...r, to: Date.now() });
+    }
+    /**
+     * `session` requests: an agent (or a plain shell) in its own ptyhost, in the launch folder's project or a registered
+     * one.
+     */
     async start(req) {
+        let shell = null;
+        let problem = null;
+        if (req.shell)
+            try {
+                shell = shellLaunch(req.shell, shellPaths());
+            }
+            catch (e) {
+                problem = errMsg(e);
+            }
+        // A shell is listed by its own name (pwsh, powershell, cmd).
+        const name = shell?.name ?? (req.shell ? 'shell' : req.harness);
         let status = {
             id: req.id,
             launchId: session.launchId,
-            harness: req.harness,
+            harness: name,
+            ...(req.shell ? { kind: 'shell' } : {}),
             cwd: req.cwd,
             ...(req.project ? { project: req.project.name } : {}),
             phase: 'starting',
-            message: 'Starting ' + req.harness,
+            message: 'Starting ' + name,
             updatedAt: now(),
             startedAt: now(),
         };
@@ -186,29 +268,34 @@ export class SessionManager {
         this.starting++;
         // Sessions after the first get their own tab right away (it shows the setup progress until the agent starts).
         if (req.id !== session.launchId && process.env.AGENT_NO_TABS !== '1')
-            safely('terminal tab', () => terminalTab(req.id, req.harness + ' ' + path.basename(req.cwd), req.cwd));
+            safely('terminal tab', () => terminalTab(req.id, name + ' ' + path.basename(req.cwd), req.cwd));
         try {
+            if (problem)
+                throw new Error(problem);
             const place = await placeFor(req, say);
+            const program = shell ? shellProgram(shell) : await agentProgram(req, place.env, say);
             const remote = session.networking && session.attach.enabled;
-            const { child, port, token } = await launchPtyHost(req, remote, place.env, say, this.live.size + 1);
-            const resumed = req.harness === 'claude' ? resumedConversation(req.args) : undefined;
+            const from = Date.now();
+            const { child, port, token } = await launchPtyHost(req, program, remote, place.env, this.live.size + 1, (c) => this.rootStarted(req.id, c, from));
+            const agent = shell === null;
+            const resumed = agent && req.harness === 'claude' ? resumedConversation(req.args) : undefined;
             const running = {
                 ...status,
                 ...(resumed ? { conversation: resumed } : {}),
                 project: place.project,
                 phase: 'running',
-                message: req.harness + ' is running',
+                message: name + ' is running',
                 attach: { addresses: remote ? guestAddresses() : [], port, token },
             };
             this.live.set(req.id, { status: running, child });
             child.once('exit', (code) => this.onExit(running, place, code));
             saveStatus(running);
-            if (req.harness === 'claude')
+            if (agent && req.harness === 'claude')
                 this.trackConversation(running.id, resumed);
             log('Session ' +
                 req.id +
                 ' started (' +
-                req.harness +
+                name +
                 ' in ' +
                 req.cwd +
                 ', project ' +
@@ -218,6 +305,7 @@ export class SessionManager {
                 ')');
         }
         catch (e) {
+            this.rootEnded(req.id);
             saveStatus({ ...status, phase: 'failed', message: errMsg(e) });
             warn('Session ' + req.id + ' failed: ' + errMsg(e));
             this.idle.check();
@@ -246,15 +334,53 @@ export class SessionManager {
             this.idle.check();
         }
     }
-    /** `restart` requests: the matching sessions restart their agent (continuing the conversation where it can). */
+    /**
+     * `restart` requests: the matching sessions restart their agent (continuing the conversation where it can). Shells
+     * are left alone: restarting one would only throw away what it was doing.
+     */
     async restart(req) {
         const targets = [...this.live.values()].filter((s) => s.status.attach &&
+            s.status.kind !== 'shell' &&
             (req.harness === null || s.status.harness === req.harness) &&
             (!req.cwd || isWithin(req.cwd, s.status.cwd)));
         for (const s of targets)
             await sendControl({ addresses: ['127.0.0.1'], port: s.status.attach.port, token: s.status.attach.token }, FrameType.Restart);
         respond(req.id, { ok: true, message: 'restarted ' + targets.length + ' session(s)' });
     }
+    /**
+     * `close` requests: the session's ptyhost ends its program and everything it started (ProcessTree), then exits as
+     * if the program had. One that does not end in time has its ptyhost ended instead (closing the pseudo console ends
+     * what is attached to it).
+     */
+    async close(req) {
+        const entry = this.live.get(req.session);
+        if (!entry?.status.attach) {
+            respond(req.id, { ok: false, message: 'Session ' + req.session + ' is not running.' });
+            return;
+        }
+        const { child, status } = entry;
+        const ended = new Promise((resolve) => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return resolve(true);
+            const timer = setTimeout(() => resolve(false), CLOSE_WAIT_MS);
+            child.once('exit', () => {
+                clearTimeout(timer);
+                resolve(true);
+            });
+        });
+        try {
+            await sendControl({ addresses: ['127.0.0.1'], port: status.attach.port, token: status.attach.token }, FrameType.Close);
+        }
+        catch (e) {
+            warn('Session ' + req.session + ' did not take the close request: ' + errMsg(e));
+        }
+        if (!(await ended)) {
+            warn('Session ' + req.session + ' did not end in time; ending its session host.');
+            safely('ending a session host', () => child.kill());
+        }
+        log('Session ' + req.session + ' closed on request');
+        respond(req.id, { ok: true, message: 'Closed ' + status.harness + ' session ' + req.session + '.' });
+    }
     /**
      * Finds out which of Claude's conversation files this session writes (it appears with the first message) and puts
      * it in the status, so the host can reopen this very conversation. A reopened session starts with the one it was
@@ -299,6 +425,11 @@ export class SessionManager {
             attach: undefined,
         });
         log('Session ' + running.id + ' ended (exit ' + code + ')');
+        // A shell ran no agent: no post-agent hooks, nothing of an agent's to save.
+        if (running.kind === 'shell') {
+            this.idle.check();
+            return;
+        }
         if (place.hooks)
             void runHooksAsync('post-agent', place.env, place.hooks).catch((e) => warn('post-agent hooks failed: ' + errMsg(e)));
         else

package/dist/guest/entries/daemon.js

@@ -9,13 +9,14 @@ import { log, warn } from '../runtime/log.js';
 import { adoptBootSecrets } from '../runtime/secrets.js';
 import { errMsg } from '../../core/util/errors.js';
 import { Daemon } from '../daemon/daemon.js';
+import { sessions } from '../daemon/sessions.js';
 import { governor } from '../governor/index.js';
 process.on('uncaughtException', (e) => warn('daemon: unexpected error (continuing): ' + (e.stack ?? errMsg(e))));
 process.on('unhandledRejection', (e) => warn('daemon: unexpected error (continuing): ' + errMsg(e)));
 adoptBootSecrets();
 log('Session daemon started (pid ' + process.pid + ').');
 safely('port forwards', startRelays);
-safely('audit', startProcessCollector);
+safely('audit', () => startProcessCollector(() => sessions.roots()));
 safely('memory governor', () => governor.start());
 log('Memory governor: ' + governor.describe());
 new Daemon().start();

package/dist/guest/git/decision.js

@@ -57,6 +57,8 @@ const LISTING = {
 /** Global options that take a value (`git -C dir status`). Config overrides (-c, --config-env) are refused outright. */
 const WITH_VALUE = new Set(['-C', '--namespace']);
 const FORBIDDEN_GLOBAL = /^(-c|--config-env|--exec-path|--git-dir|--work-tree|--super-prefix)(=|$)/;
+/** Options of reading commands that run a program or write a file (grep -O<cmd>, ls-remote --upload-pack, --output). */
+const RUNS_OR_WRITES = /^(--open-files-in-pager|--upload-pack|--output|--ext-diff)(=|$)/;
 export function gitDecision(args, access) {
     if (access === 'full')
         return { allow: true };
@@ -72,6 +74,11 @@ export function gitDecision(args, access) {
         i += WITH_VALUE.has(args[i]) ? 2 : 1;
     }
     const [command, ...rest] = args.slice(i);
+    const runsOrWrites = rest.find((a) => RUNS_OR_WRITES.test(a) ||
+        (command === 'ls-remote' && /^-u(.|$)/.test(a)) ||
+        (command === 'grep' && /^-O/.test(a)));
+    if (runsOrWrites)
+        return { allow: false, reason: 'git ' + runsOrWrites + ' is not allowed: git is read-only in this sandbox.' };
     if (command === undefined || command === '--version' || READ_ONLY.has(command) || (LISTING[command]?.(rest) ?? false))
         return { allow: true };
     return {

package/dist/guest/sessions/cmdline.d.ts

@@ -10,3 +10,17 @@ export declare function quoteArg(arg: string): string;
 export declare function cmdArgs(args: string[]): string;
 /** The command line ptyhost starts; when the program is cmd.exe its arguments are quoted for cmd (cmdArgs). */
 export declare function commandLine(file: string, args: string[]): string;
+/** A plain shell session's program: which shell, its absolute path and its arguments. */
+export interface ShellLaunch {
+    readonly name: 'pwsh' | 'powershell' | 'cmd';
+    readonly file: string;
+    readonly args: string[];
+}
+/** Where the shells are in this sandbox (pwsh: null when PowerShell 7 is not installed). */
+export interface ShellPaths {
+    readonly pwsh: string | null;
+    readonly powershell: string;
+    readonly cmd: string;
+}
+/** The shell a session asked for runs as (auto: PowerShell 7 when present, else Windows PowerShell). Pure. */
+export declare function shellLaunch(asked: 'auto' | ShellLaunch['name'], paths: ShellPaths): ShellLaunch;

package/dist/guest/sessions/cmdline.js

@@ -31,3 +31,13 @@ export function commandLine(file, args) {
         ? [quoteArg(file), cmdArgs(args)].filter(Boolean).join(' ')
         : [file, ...args].map(quoteArg).join(' ');
 }
+/** The shell a session asked for runs as (auto: PowerShell 7 when present, else Windows PowerShell). Pure. */
+export function shellLaunch(asked, paths) {
+    if (asked === 'cmd')
+        return { name: 'cmd', file: paths.cmd, args: [] };
+    if (asked === 'powershell' || (asked === 'auto' && !paths.pwsh))
+        return { name: 'powershell', file: paths.powershell, args: ['-NoLogo'] };
+    if (!paths.pwsh)
+        throw new Error('PowerShell 7 is not installed in this sandbox (toolchains.pwsh). Open powershell or cmd instead, or turn pwsh on.');
+    return { name: 'pwsh', file: paths.pwsh, args: ['-NoLogo'] };
+}

package/dist/guest/setup/addon-mcp.d.ts

@@ -0,0 +1,2 @@
+/** Sets the add-ons' MCP servers in the sandbox's .claude.json; the names that are on. */
+export declare function writeAddonMcpServers(): string[];

package/dist/guest/setup/addon-mcp.js

@@ -0,0 +1,49 @@
+// The agent add-ons' MCP servers (Playwright, Context7) in the sandbox's own Claude Code: user-scope servers named
+// sbx-... in its .claude.json, set every boot while the add-on is on and removed again when it is off. Your servers
+// (from this PC or added in the sandbox) are never touched, and nothing on this PC changes.
+import fs from 'node:fs';
+import path from 'node:path';
+import { addonMcpServer, APPS, withAddonMcpServers } from '../../shared/apps/index.js';
+import { writeJsonAtomic } from '../../shared/io/json.js';
+import { claudeDir } from '../runtime/session.js';
+import { log, warn } from '../runtime/log.js';
+import { installedMcpAddons } from './agent-addons.js';
+/** The names of every MCP server an add-on can add (the ones the sandbox may remove). */
+const ADDON_MCP_NAMES = APPS.flatMap((a) => (a.mcp ? [a.mcp.name] : []));
+/** Sets the add-ons' MCP servers in the sandbox's .claude.json; the names that are on. */
+export function writeAddonMcpServers() {
+    const servers = {};
+    for (const { id, folder } of installedMcpAddons()) {
+        const mcp = APPS.find((a) => a.id === id)?.mcp;
+        if (mcp)
+            servers[mcp.name] = addonMcpServer(folder, mcp);
+    }
+    const file = path.join(claudeDir, '.claude.json');
+    let state = {};
+    if (fs.existsSync(file)) {
+        try {
+            const text = fs.readFileSync(file, 'utf8');
+            state = JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+        }
+        catch {
+            // Never rewrite a file Claude Code could not read either: its login and state are in it.
+            warn('Claude Code MCP servers from Apps: ' + file + ' is not valid JSON, left as it is');
+            return [];
+        }
+    }
+    else if (!Object.keys(servers).length)
+        return [];
+    if (typeof state !== 'object' || state === null || Array.isArray(state))
+        return [];
+    const current = state.mcpServers;
+    const before = current && typeof current === 'object' && !Array.isArray(current) ? current : {};
+    const after = withAddonMcpServers(before, servers, ADDON_MCP_NAMES);
+    if (JSON.stringify(before) !== JSON.stringify(after)) {
+        fs.mkdirSync(claudeDir, { recursive: true });
+        writeJsonAtomic(file, { ...state, mcpServers: after });
+    }
+    const names = Object.keys(servers);
+    if (names.length)
+        log('Claude Code MCP servers from Apps: ' + names.join(', '));
+    return names;
+}

package/dist/guest/setup/agent-addons.d.ts

@@ -0,0 +1,9 @@
+/** The add-on's program when it is chosen and installed, else null. */
+export declare function installedAddon(id: string): string | null;
+/** rtk.exe when rtk is chosen and installed, else null. */
+export declare function installedRtk(): string | null;
+/** The add-ons with an MCP server that are chosen and installed: their folder and server. */
+export declare function installedMcpAddons(): {
+    id: string;
+    folder: string;
+}[];

package/dist/guest/setup/agent-addons.js

@@ -0,0 +1,22 @@
+// Agent add-ons in this sandbox: an add-on is plugged into the agents only while it is chosen (apps.install) AND its
+// program is really there (a failed download adds no hook, proxy or MCP server that would fail on every use).
+import { APPS, appById } from '../../shared/apps/index.js';
+import { findExe } from '../apps/find-exe.js';
+import { dryRun } from '../runtime/paths.js';
+import { session } from '../runtime/session.js';
+import { tool } from '../toolchains/tool-env.js';
+/** The add-on's program when it is chosen and installed, else null. */
+export function installedAddon(id) {
+    const entry = appById(id);
+    if (dryRun || !entry || !(session.apps?.install ?? []).includes(id))
+        return null;
+    return findExe(tool('apps', id), entry.exe);
+}
+/** rtk.exe when rtk is chosen and installed, else null. */
+export function installedRtk() {
+    return installedAddon('rtk');
+}
+/** The add-ons with an MCP server that are chosen and installed: their folder and server. */
+export function installedMcpAddons() {
+    return APPS.filter((a) => a.mcp && installedAddon(a.id)).map((a) => ({ id: a.id, folder: tool('apps', a.id) }));
+}

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

@@ -0,0 +1,7 @@
+/** The proxy's log (it redacts keys and tokens in what it logs). */
+export declare const HEADROOM_LOG: string;
+/**
+ * Starts the proxy when Headroom is chosen and installed; its base URL once it answers, else null (Claude Code then
+ * talks to the API directly).
+ */
+export declare function startHeadroom(env: NodeJS.ProcessEnv): Promise<string | null>;

package/dist/guest/setup/headroom.js

@@ -0,0 +1,60 @@
+// The Headroom agent add-on: its proxy runs detached on 127.0.0.1 for the sandbox's life, and Claude Code is pointed at
+// it (managed-policy.ts) only once it answers as Headroom. It forwards only to Anthropic's API, starts without the
+// agents' keys in its environment and with HEADROOM_OFFLINE (no telemetry, update checks or model downloads).
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { HEADROOM_PORT, headroomArgs, headroomEnv, headroomUrl } from '../../shared/apps/index.js';
+import { logsDir } from '../runtime/paths.js';
+import { portOpen, waitForPort } from '../runtime/ports.js';
+import { log } from '../runtime/log.js';
+import { installedAddon } from './agent-addons.js';
+/** The proxy's log (it redacts keys and tokens in what it logs). */
+export const HEADROOM_LOG = path.join(logsDir, 'headroom.log');
+/** Whether Headroom's own health check answers on the port (not some other program that took it). */
+function answersAsHeadroom(port) {
+    return new Promise((resolve) => {
+        const req = http.get({ host: '127.0.0.1', port, path: '/livez', timeout: 3000 }, (res) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => {
+                if (body.length < 4096)
+                    body += chunk;
+            });
+            res.on('end', () => resolve(res.statusCode === 200 && /"service"\s*:\s*"headroom-proxy"/.test(body)));
+        });
+        req.on('timeout', () => req.destroy());
+        req.on('error', () => resolve(false));
+    });
+}
+/**
+ * Starts the proxy when Headroom is chosen and installed; its base URL once it answers, else null (Claude Code then
+ * talks to the API directly).
+ */
+export async function startHeadroom(env) {
+    const exe = installedAddon('headroom');
+    if (!exe)
+        return null;
+    if (env.ANTHROPIC_BASE_URL) {
+        log('Headroom: not used, ANTHROPIC_BASE_URL is set in the agent environment (' + env.ANTHROPIC_BASE_URL + ')');
+        return null;
+    }
+    const port = HEADROOM_PORT;
+    if (!(await portOpen(port))) {
+        const out = fs.openSync(HEADROOM_LOG, 'a');
+        spawn(exe, headroomArgs(port), {
+            detached: true,
+            stdio: ['ignore', out, out],
+            windowsHide: true,
+            env: headroomEnv(env),
+        }).unref();
+        fs.closeSync(out);
+        if (!(await waitForPort(port, 90)))
+            throw new Error('the Headroom proxy did not start on port ' + port + '; see ' + HEADROOM_LOG);
+    }
+    if (!(await answersAsHeadroom(port)))
+        throw new Error('port ' + port + ' is taken by another program; Claude Code talks to the API directly');
+    log('Headroom: Claude Code reaches the API through ' + headroomUrl(port) + ' (log: ' + HEADROOM_LOG + ')');
+    return headroomUrl(port);
+}

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

@@ -1,3 +1,4 @@
 import type { GitAccess } from '../../core/types.js';
 export declare function managedSettingsFile(): string;
-export declare function writeManagedSettings(access: GitAccess): void;
+/** `headroom`: the proxy's base URL when it answered at this boot (null: Claude Code talks to the API directly). */
+export declare function writeManagedSettings(access: GitAccess, headroom?: string | null): void;

package/dist/guest/setup/managed-policy.js

@@ -1,20 +1,29 @@
 // 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.
+// have the highest precedence and cannot be overridden by user or project settings, so they carry the hard rules (the
+// git access mode), the sandbox's own hooks (rtk, when it is installed) and the Headroom proxy's address while it runs
+// (env.ANTHROPIC_BASE_URL). Rewritten every boot; removed when there is nothing to write. Your Claude settings from
+// this PC are never changed for this.
 import fs from 'node:fs';
 import path from 'node:path';
+import { claudeManagedSettings } from '../../shared/apps/index.js';
 import { gitDenyRules } from './git-rules.js';
 import { managedClaudeMd } from '../boot/guide.js';
+import { installedRtk } from './agent-addons.js';
+import { log } from '../runtime/log.js';
 export function managedSettingsFile() {
     return path.join(path.dirname(managedClaudeMd()), 'managed-settings.json');
 }
-export function writeManagedSettings(access) {
+/** `headroom`: the proxy's base URL when it answered at this boot (null: Claude Code talks to the API directly). */
+export function writeManagedSettings(access, headroom = null) {
     const file = managedSettingsFile();
-    const deny = gitDenyRules(access);
-    if (deny.length === 0) {
+    const rtk = installedRtk();
+    const settings = claudeManagedSettings(gitDenyRules(access), rtk, headroom);
+    if (!settings) {
         fs.rmSync(file, { force: true });
         return;
     }
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify({ permissions: { deny } }, null, 2) + '\n', 'utf8');
+    fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    if (rtk)
+        log("rtk: Claude Code's Bash commands go through it (hook in " + file + ')');
 }

package/dist/guest/toolchains/plan.js

@@ -1,4 +1,4 @@
-import { appsNeedMesa, setupApps } from '../apps/index.js';
+import { appsNeedMesa, appsNeedUv, setupApps } from '../apps/index.js';
 import { dryRun } from '../runtime/paths.js';
 import { wanted } from './detect.js';
 import { DATABASE_NAMES, setupDatabase } from '../databases/index.js';
@@ -85,7 +85,12 @@ export function plan(config, versions, o) {
         },
         { name: 'Deno', enabled: wanted(config.deno.enabled, 'deno'), install: (env) => setupDeno(env) },
         { name: 'Bun', enabled: wanted(config.bun.enabled, 'bun'), install: (env) => setupBun(env) },
-        { name: 'uv', enabled: wanted(config.uv.enabled, 'uv'), install: (env) => setupUv(env) },
+        // Headroom (an agent add-on) installs with uv: the uv step runs for it too, before the apps.
+        {
+            name: 'uv',
+            enabled: wanted(config.uv.enabled, 'uv') || appsNeedUv(o.apps),
+            install: (env) => setupUv(env),
+        },
         { name: 'PowerShell 7', enabled: wanted(config.pwsh.enabled, 'pwsh'), install: (env) => setupPwsh(env, o.refresh) },
         // The openssl tool comes from Git's install: after Git.
         {
@@ -111,7 +116,7 @@ export function plan(config, versions, o) {
             name: 'Apps',
             enabled: apps,
             shared: true,
-            after: ['Mesa 3D', 'Visual C++ runtime'],
+            after: ['Mesa 3D', 'Visual C++ runtime', 'uv'],
             install: (env) => setupApps(env, o.apps, { gitAccess: o.gitAccess, refresh: o.refresh }),
         },
         {

package/dist/guest/toolchains/setup.js

@@ -17,6 +17,9 @@ export async function setupToolchains(config, versions, options, run = {}) {
         env.summary.push(...part.summary);
     }
     Object.assign(env.vars, config.environment);
+    // The git guard's variables (AGENT_GIT_ACCESS, GIT_DIR, GIT_CONFIG_*, BASH_ENV) always win over
+    // toolchains.environment.
+    Object.assign(env.vars, envs.get('Git')?.vars);
     log('Set up ' + steps.length + ' toolchains and databases.');
     return env;
 }