windows-development-sandbox 1.11.7 → 1.12.0

package/dist/guest/audit/process-audit.js

@@ -1,12 +1,13 @@
 // audit.processes, sandbox side: Windows records every program started (Security log, event 4688, with its command
-// line); the daemon reads the new events every 15 s and leaves them in run\audit\ as small .jsonl files, which the
-// host takes into its own log (and deletes). Windows' own background programs are left out. The host treats all of it
-// as untrusted (it is checked line by line there).
+// line and process ids); the daemon reads the new events every 15 s, links each to the agent session whose ptyhost
+// started it (directly or further down), and leaves them in run\audit\ as small .jsonl files, which the host takes
+// into its own log (and deletes). Windows' own background programs are left out. The host treats all of it as
+// untrusted (it is checked line by line there, and a session it does not know is dropped).
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { SYSTEM } from '../../shared/system.js';
-import { parseProcessEvents } from './parse.js';
+import { Attributor, parseProcessEvents } from './parse.js';
 import { dryRun, isWin, run } from '../runtime/paths.js';
 import { log, warn } from '../runtime/log.js';
 import { mkdirp } from '../runtime/fs.js';
@@ -44,11 +45,13 @@ const newestRecord = () => {
 };
 /**
  * Reads new process events every 15 s for the daemon's life (from the moment it started: older ones are boot noise).
+ * `roots` gives the sessions' ptyhosts, so each program is linked to the session that started it (parse.ts).
  */
-export function startProcessCollector() {
+export function startProcessCollector(roots = () => []) {
     if (!auditOn())
         return;
     let last = newestRecord();
+    const attributor = new Attributor();
     const pass = () => {
         try {
             const r = spawnSync(wevtutil(), [
@@ -58,7 +61,7 @@ export function startProcessCollector() {
                 '/f:xml',
                 '/c:' + MAX_PER_PASS,
             ], { encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
-            const { lines, last: newest } = parseProcessEvents(r.stdout ?? '');
+            const { lines, last: newest } = parseProcessEvents(r.stdout ?? '', { attributor, roots: roots() });
             if (newest)
                 last = newest;
             if (lines.length)

package/dist/guest/boot/boot.js

@@ -16,6 +16,8 @@ import { runHooks } from '../setup/hooks.js';
 import { applyAllowOnly, proxyEnv } from '../network/allow-only.js';
 import { applyNetworkPolicy, networkProblems } from '../network/firewall.js';
 import { writeManagedSettings } from '../setup/managed-policy.js';
+import { writeAddonMcpServers } from '../setup/addon-mcp.js';
+import { startHeadroom } from '../setup/headroom.js';
 import { applyPersonalization } from '../setup/desktop.js';
 import { setupGitConfig } from '../setup/git-identity.js';
 import { loginGithub, prepareGithubFolder } from '../setup/github-token.js';
@@ -144,7 +146,7 @@ export class Boot {
         const { tools, env } = await this.developerTools();
         await this.vpn();
         await this.gitIdentity(env);
-        await this.claude(tools);
+        await this.claude(tools, env);
         await this.agent(env);
         this.preAgentHooks(env);
         await this.start(env);
@@ -230,15 +232,22 @@ export class Boot {
             await soft('GitHub token', () => loginGithub(token, env));
         }
     }
-    async claude(tools) {
+    async claude(tools, env) {
         step(6, 'Claude settings, history and claude-mem');
         if (session.harnessName === 'claude')
             await soft('Claude settings', () => syncClaudeProfile(this.secrets.claudeCredentials));
         await soft('claude-mem restore', restoreClaudeMem);
         await soft('Agent files of the last sandbox', resetMachineBound);
         await soft('Agent databases restore', restoreLocalState);
+        // Agent add-ons: MCP servers in the sandbox's Claude Code, and the Headroom proxy before the managed settings point
+        // Claude Code at it (the guide reads them back, so it comes last).
+        let headroom = null;
+        await soft('MCP servers from Apps', writeAddonMcpServers);
+        await soft('Headroom proxy', async () => {
+            headroom = await startHeadroom(env);
+        });
+        await soft('Claude managed settings', () => writeManagedSettings(this.gitAccess, headroom));
         await soft('Sandbox guide for the agent', () => writeGuides(tools.summary, this.lan));
-        await soft('Claude managed settings', () => writeManagedSettings(this.gitAccess));
     }
     async agent(env) {
         step(7, 'Agent: ' + session.harnessName);

package/dist/guest/boot/guide.d.ts

@@ -3,7 +3,7 @@ export interface GuideProject {
     guest: string;
     host: string;
 }
-export declare function sandboxGuide(toolSummary: string[], lan?: 'blocked' | 'open' | 'offline', projects?: GuideProject[]): string;
+export declare function sandboxGuide(toolSummary: string[], lan?: 'blocked' | 'open' | 'offline', projects?: GuideProject[], addons?: string[]): string;
 /** Inserts or replaces the generated section, keeping whatever else the file contains (the host's CLAUDE.md). */
 export declare function upsertGuide(file: string, guide: string): void;
 /**

package/dist/guest/boot/guide.js

@@ -3,7 +3,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { claudeDir, session, stateDir, workspace } from '../runtime/session.js';
-import { dataDir, launchDir, toolsDir } from '../runtime/paths.js';
+import { dataDir, launchDir, logsDir, toolsDir } from '../runtime/paths.js';
+import { addonGuideLine, APPS, headroomGuideLine, RTK_GUIDE_LINE } from '../../shared/apps/index.js';
+import { installedAddon, installedRtk } from '../setup/agent-addons.js';
 const BEGIN = '<!-- agent-sandbox:begin (generated every boot, do not edit) -->';
 const END = '<!-- agent-sandbox:end -->';
 /** Drives other than C: are subst drives onto C:\Mirror\<letter> (mapped folders shown at their PC paths). */
@@ -20,7 +22,7 @@ const mirrorLine = () => {
             '`; real-path tools may print that form).',
     ];
 };
-export function sandboxGuide(toolSummary, lan = 'blocked', projects = []) {
+export function sandboxGuide(toolSummary, lan = 'blocked', projects = [], addons = []) {
     return [
         BEGIN,
         '## Sandbox manifest — you are in a DISPOSABLE Windows Sandbox',
@@ -45,6 +47,8 @@ export function sandboxGuide(toolSummary, lan = 'blocked', projects = []) {
         '- RO: `' + launchDir + "` (this boot's scripts) · lost on close: everything else, incl. `C:\\nvm` (Node symlink)",
         ...mirrorLine(),
         '- Tools: ' + toolSummary.join(' · '),
+        // Agent add-ons that change how the agent works (rtk, Headroom, MCP servers, ccusage).
+        ...addons,
         '- Persistent installs: `npm i -g` (per nvm version), `pip`, `cargo install`, `dotnet tool -g`, `uv tool`, `bun add -g`. Real installers must re-run each boot via a hook (ask the user).',
         '- Mapped folders (workspace, C:\\AgentData) allow NO symlinks or junctions: pnpm runs hoisted (set), npm workspaces / `file:` deps and deno node_modules dirs fail there (use a folder on C:\\ outside them), bun cannot save its lockfile there (`bun install --no-save`).',
         '- Network: ' +
@@ -75,8 +79,28 @@ export function upsertGuide(file, guide) {
 export function managedClaudeMd() {
     return path.join(process.env.AGENT_MANAGED_DIR ?? path.join(process.env.ProgramFiles ?? 'C:\\Program Files', 'ClaudeCode'), 'CLAUDE.md');
 }
+/** Whether the managed settings point Claude Code at the Headroom proxy (written just before the guide). */
+const headroomRuns = () => {
+    try {
+        const file = path.join(path.dirname(managedClaudeMd()), 'managed-settings.json');
+        const settings = JSON.parse(fs.readFileSync(file, 'utf8'));
+        return typeof settings.env?.ANTHROPIC_BASE_URL === 'string';
+    }
+    catch {
+        return false; // no managed settings: nothing points at the proxy
+    }
+};
+/** The lines for the agent add-ons that are on and installed (rtk, Headroom, MCP servers, ccusage). */
+function addonLines() {
+    const mcp = APPS.flatMap((a) => (a.mcp && installedAddon(a.id) ? [a.mcp.name] : []));
+    return [
+        ...(installedRtk() ? [RTK_GUIDE_LINE] : []),
+        ...(installedAddon('headroom') && headroomRuns() ? [headroomGuideLine(path.join(logsDir, 'headroom.log'))] : []),
+        ...addonGuideLine(mcp, Boolean(installedAddon('ccusage'))),
+    ];
+}
 export function writeGuides(toolSummary, lan, projects = []) {
-    const guide = sandboxGuide(toolSummary, lan, projects);
+    const guide = sandboxGuide(toolSummary, lan, projects, addonLines());
     const managed = managedClaudeMd();
     fs.mkdirSync(path.dirname(managed), { recursive: true });
     fs.writeFileSync(managed, guide + '\n', 'utf8');

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

@@ -1,4 +1,5 @@
 import type { GuestRequest } from '../../core/types.js';
+import type { SessionRoot } from '../audit/parse.js';
 type SessionRequest = Extract<GuestRequest, {
     kind: 'session';
 }>;
@@ -14,8 +15,14 @@ export declare class SessionManager {
     /** Sessions and projects being set up right now (a headless sandbox must not shut down under them). */
     private starting;
     private readonly idle;
+    /** Each session's ptyhost (process id and when it ran), for linking the programs it starts to it (audit). */
+    private readonly ptyHosts;
     /** How many sessions are running. */
     get count(): number;
+    /** The sessions' ptyhosts, running or ended within ROOTS_KEPT_MS (audit events arrive after they happen). */
+    roots(): SessionRoot[];
+    private rootStarted;
+    private rootEnded;
     /** `session` requests: an agent in its own ptyhost, in the launch folder's project or a registered one. */
     start(req: SessionRequest): Promise<void>;
     /**

package/dist/guest/daemon/sessions.js

@@ -31,6 +31,8 @@ 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';
+/** 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');
@@ -94,7 +96,7 @@ function writeBudget(cpus, memoryGb, jobs, env) {
     }
 }
 /** 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) => {
+const launchPtyHost = async (req, remote, env, say, sessions, onSpawn) => {
     const harness = harnessFor(req);
     // Never refresh here: main already did, and replacing a running agent's executable would fail.
     say('Preparing ' + req.harness);
@@ -116,6 +118,7 @@ const launchPtyHost = async (req, remote, env, say, sessions) => {
         command: commandLine(launch.file, [...base, ...req.args]),
         restartCommand: commandLine(launch.file, [...base, ...(harness.resumeArguments ?? [])]),
     });
+    onSpawn(child);
     try {
         await waitForPtyHost(child, port, 15000);
     }
@@ -160,10 +163,30 @@ 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;
     }
+    /** 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 in its own ptyhost, in the launch folder's project or a registered one. */
     async start(req) {
         let status = {
@@ -190,7 +213,8 @@ export class SessionManager {
         try {
             const place = await placeFor(req, say);
             const remote = session.networking && session.attach.enabled;
-            const { child, port, token } = await launchPtyHost(req, remote, place.env, say, this.live.size + 1);
+            const from = Date.now();
+            const { child, port, token } = await launchPtyHost(req, remote, place.env, say, this.live.size + 1, (c) => this.rootStarted(req.id, c, from));
             const resumed = req.harness === 'claude' ? resumedConversation(req.args) : undefined;
             const running = {
                 ...status,
@@ -218,6 +242,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();

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/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/host/audit/attribute.d.ts

@@ -0,0 +1,46 @@
+/** A session as the audit remembers it (its run record goes with the sandbox). */
+export interface KnownSession {
+    readonly id: string;
+    readonly agent: string;
+    /** The project it runs in (hub name). */
+    readonly project: string;
+    /** When it started and ended (ms). */
+    readonly from: number;
+    readonly to?: number;
+}
+/** A git command a session ran that can make a commit (from the programs the sandbox reported). */
+export interface GitRun {
+    readonly t: number;
+    readonly session: string;
+}
+/** A link to a session: its id and how it was made (p: process tree / git command; t: only session running). */
+export interface Link {
+    readonly s: string;
+    readonly sv: 'p' | 't';
+}
+/** git commit, merge, cherry-pick, revert, rebase, am, pull: the commands that can add a commit. */
+export declare function makesCommits(program: string, commandLine: string): boolean;
+/** The sessions of this sandbox seen so far, with when each ran. */
+export declare class SessionBook {
+    private readonly sessions;
+    /** Takes the sessions as they are now: new ones are added, ended ones get their end time. */
+    update(list: readonly {
+        readonly id: string;
+        readonly harness: string;
+        readonly project?: string;
+        readonly phase: string;
+        readonly startedAt: string;
+        readonly updatedAt: string;
+    }[], fallbackProject: string, now?: number): void;
+    get(id: string | undefined): KnownSession | undefined;
+    /** The one session running in this project at time t, or undefined when none or several were. */
+    onlyRunning(project: string, t: number): KnownSession | undefined;
+    /** A file change in a project at time t: linked only when one session ran there then. */
+    linkFile(project: string, t: number): Link | undefined;
+    /**
+     * A commit in a project at time t: the session whose git command made it when that project's sessions ran git
+     * commands that make commits around then and all were the same session's; else, when `likely` is allowed (programs
+     * are not recorded, so no git command could be seen), the one session running there.
+     */
+    linkCommit(project: string, t: number, gitRuns: readonly GitRun[], likely?: boolean): Link | undefined;
+}

package/dist/host/audit/attribute.js

@@ -0,0 +1,76 @@
+// Which agent session an event belongs to, on the PC side. Programs come linked from the sandbox (by the process tree,
+// guest/audit/parse.ts); the host only keeps a link to a session it knows. Files and commits are seen from this PC,
+// where the writer cannot be told: they are linked only when exactly one session was running in that project at the
+// time ("likely", marked as such), or, for a commit, when that project's sessions ran exactly one git command that
+// makes commits around then. Anything else stays "no session": nothing is guessed. Pure, so the self-test checks it.
+import path from 'node:path';
+/** How long before and after a commit a git command counts as the one that made it. */
+const GIT_BEFORE_MS = 3 * 60 * 1000;
+const GIT_AFTER_MS = 30 * 1000;
+/** Sessions remembered at most. */
+const MAX_SESSIONS = 512;
+/** git commit, merge, cherry-pick, revert, rebase, am, pull: the commands that can add a commit. */
+export function makesCommits(program, commandLine) {
+    return (/^git(\.exe)?$/i.test(path.win32.basename(program)) &&
+        /\s(commit|merge|cherry-pick|revert|rebase|am|pull)(\s|$)/i.test(commandLine));
+}
+/** The sessions of this sandbox seen so far, with when each ran. */
+export class SessionBook {
+    sessions = new Map();
+    /** Takes the sessions as they are now: new ones are added, ended ones get their end time. */
+    update(list, fallbackProject, now = Date.now()) {
+        for (const s of list) {
+            const known = this.sessions.get(s.id);
+            const ended = s.phase === 'exited' || s.phase === 'failed';
+            if (known) {
+                if (ended && known.to === undefined)
+                    this.sessions.set(s.id, { ...known, to: Math.min(now, Date.parse(s.updatedAt) || now) });
+                continue;
+            }
+            if (this.sessions.size >= MAX_SESSIONS)
+                continue;
+            const from = Date.parse(s.startedAt) || now;
+            this.sessions.set(s.id, {
+                id: s.id,
+                agent: s.harness,
+                project: s.project ?? fallbackProject,
+                from,
+                ...(ended ? { to: Math.max(from, Date.parse(s.updatedAt) || now) } : {}),
+            });
+        }
+        // A session whose record is gone is not running any more: it ended by now at the latest.
+        const listed = new Set(list.map((s) => s.id));
+        for (const [id, s] of this.sessions)
+            if (!listed.has(id) && s.to === undefined)
+                this.sessions.set(id, { ...s, to: now });
+    }
+    get(id) {
+        return id === undefined ? undefined : this.sessions.get(id);
+    }
+    /** The one session running in this project at time t, or undefined when none or several were. */
+    onlyRunning(project, t) {
+        const running = [...this.sessions.values()].filter((s) => s.project.toLowerCase() === project.toLowerCase() && s.from <= t && (s.to === undefined || t <= s.to));
+        return running.length === 1 ? running[0] : undefined;
+    }
+    /** A file change in a project at time t: linked only when one session ran there then. */
+    linkFile(project, t) {
+        const only = this.onlyRunning(project, t);
+        return only ? { s: only.id, sv: 't' } : undefined;
+    }
+    /**
+     * A commit in a project at time t: the session whose git command made it when that project's sessions ran git
+     * commands that make commits around then and all were the same session's; else, when `likely` is allowed (programs
+     * are not recorded, so no git command could be seen), the one session running there.
+     */
+    linkCommit(project, t, gitRuns, likely = true) {
+        const near = new Set(gitRuns
+            .filter((g) => g.t >= t - GIT_BEFORE_MS && g.t <= t + GIT_AFTER_MS)
+            .map((g) => g.session)
+            .filter((id) => this.get(id)?.project.toLowerCase() === project.toLowerCase()));
+        if (near.size === 1)
+            return { s: [...near][0], sv: 'p' };
+        if (near.size > 1)
+            return undefined;
+        return likely ? this.linkFile(project, t) : undefined;
+    }
+}