windows-development-sandbox 1.11.7 → 1.13.0

package/dist/selftest/resume.test.js

@@ -57,6 +57,7 @@ export const resumeSuite = {
             status({ id: 's2', harness: 'codex', cwd: 'C:\\Workspace\\web\\src', startedAt: minutes(20) }),
             status({ id: 's3', phase: 'exited' }),
             status({ id: 's4', cwd: 'D:\\nowhere' }),
+            status({ id: 's5', harness: 'pwsh', kind: 'shell' }),
         ], reg, NOW);
         const saved = ledger.read();
         t.equal([saved?.sessions.map((s) => [s.harness, s.project, s.conversation]), saved?.launch.projects], [
@@ -65,7 +66,7 @@ export const resumeSuite = {
                 ['codex', 'F:\\code\\web\\src', undefined],
             ],
             ['F:\\code\\web'],
-        ], 'running sessions are noted with their folder on this PC (ended ones and unknown folders are not), and the projects');
+        ], 'running sessions are noted with their folder on this PC (ended ones, unknown folders and shells are not), and the projects');
         ledger.recordSessions([
             status({ startedAt: minutes(30) }),
             status({ id: 's2', harness: 'codex', cwd: 'C:\\Workspace\\web\\src', startedAt: minutes(20) }),

package/dist/selftest/sharing.test.js

@@ -142,7 +142,7 @@ async function permissionPlan(t) {
     await t.throws(() => sharingAclPlan({ storageUserDir, dataPath: t.at('elsewhere', 'default'), groupSid: GROUP_SID, on: true }), 'not under', 'a data set outside the user folder is refused');
 }
 /** The PowerShell script: it parses, changes a temp folder's permissions, and refuses links. Windows only. */
-function folderScript(t) {
+async function folderScript(t) {
     t.section('set-folder-access.ps1');
     if (process.platform !== 'win32') {
         t.skip('the folder-permission script runs only on Windows');
@@ -223,6 +223,13 @@ function folderScript(t) {
     fs.mkdirSync(path.join(own, 'child'));
     fs.writeFileSync(path.join(own, 'child', 'a.txt'), 'x');
     t.check(fs.readFileSync(path.join(own, 'child', 'a.txt'), 'utf8') === 'x', 'the owner can still use a private folder');
+    // Security review 2026-10: under an all-users install another member of the group can create users\<you> first.
+    const theirs = t.dir('acl-someone-elses');
+    const given = spawnSync(SYSTEM.icacls(), [theirs, '/setowner', '*S-1-5-18'], { encoding: 'utf8', windowsHide: true });
+    if (given.status !== 0)
+        t.skip('a folder owned by someone else (cannot give a folder to SYSTEM here)');
+    else
+        await t.throws(() => runPrivateFolder(theirs), 'not to you', 'a folder someone else owns is refused, never made "private" for you (its owner could open it again)');
 }
 export const sharingSuite = {
     name: 'sharing',
@@ -236,7 +243,7 @@ export const sharingSuite = {
             recordsSection(t);
             ownership(t);
             await permissionPlan(t);
-            folderScript(t);
+            await folderScript(t);
         }
         finally {
             // Later suites load the settings too: the machine file this suite wrote must not outlive it.

package/dist/selftest/support/engine-golden.js

@@ -30,6 +30,15 @@ export const LAUNCH_FILES_GOLDEN = [
     'runtime/main.js',
     'runtime/netproxy.js',
     'runtime/view.js',
+    // The agent add-ons' lock files (pinned installs), copied with the rest of sandbox\.
+    'sandbox/addons/ccusage/package-lock.json',
+    'sandbox/addons/ccusage/package.json',
+    'sandbox/addons/context7/package-lock.json',
+    'sandbox/addons/context7/package.json',
+    'sandbox/addons/headroom/requirements.in',
+    'sandbox/addons/headroom/requirements.txt',
+    'sandbox/addons/playwright-mcp/package-lock.json',
+    'sandbox/addons/playwright-mcp/package.json',
     'sandbox/boot/bootstrap.ps1',
     'sandbox/boot/bootstrap/drives.ps1',
     'sandbox/boot/bootstrap/files.ps1',

package/dist/selftest/support/fixtures.d.ts

@@ -45,6 +45,7 @@ export declare function createFixtures(t: Harness): {
             maxMb: number;
             processes: boolean;
             files: boolean;
+            commits: boolean;
         };
         mappings: {
             host: string;
@@ -262,6 +263,19 @@ export declare function createFixtures(t: Harness): {
             enabled: boolean;
             port: number;
             openOnLaunch: boolean;
+            remote: {
+                windowsSignIn: boolean;
+                users: {
+                    name: string;
+                    role: "view" | "control";
+                }[];
+                rememberDays: number;
+                lan: {
+                    enabled: boolean;
+                    port: number;
+                    address: string;
+                };
+            };
         };
         agentCommands: {
             enabled: boolean;

package/dist/selftest/support/web-preview.js

@@ -17,6 +17,8 @@ import { showData } from '../../app/features/data/index.js';
 import { updatesStatus } from '../../app/features/updates/index.js';
 import { containedStatus, showStorage } from '../../app/features/storage/index.js';
 import { listSessions } from '../../app/features/sessions/index.js';
+import { auditListing, listAudit } from '../../app/features/audit/index.js';
+import { AuditLog } from '../../host/audit/index.js';
 import { cancelled } from '../../app/kernel/index.js';
 import { runDefinition } from '../../app/registry.js';
 import { webSession } from '../../cli/services/index.js';
@@ -509,12 +511,159 @@ function sampleLogTail(input) {
         next: 0,
     });
 }
+/** A plausible audit log: two agents' sessions, the sandbox's own setup, a commit each, a guard finding. */
+function sampleAuditLog(dir) {
+    const log = new AuditLog(dir, { days: 7, maxMb: 100 });
+    const at = (minutesAgo) => new Date(Date.now() - minutesAgo * MINUTE).toISOString();
+    const claude = { s: SESSIONS[0].id, ag: 'claude', pj: 'windows-sandbox', sv: 'p' };
+    const codex = { s: 'mva7codex2k91x', ag: 'codex', pj: 'mw2-agent', sv: 'p' };
+    const git = 'C:\\AgentData\\tools\\git\\cmd\\git.exe';
+    const node = 'C:\\nvm\\nodejs\\node.exe';
+    const ws = 'F:\\AgentProjects\\windows-sandbox';
+    const mw = 'F:\\AgentProjects\\mw2-agent';
+    const proc = (m, p, c, who, n) => ({
+        t: at(m),
+        k: 'proc',
+        p,
+        c,
+        pp: node,
+        ...who,
+        ...(n ? { n } : {}),
+    });
+    const file = (m, p, w, who) => ({
+        t: at(m),
+        k: 'file',
+        a: 'change',
+        p,
+        w,
+        ...who,
+    });
+    log.append([
+        { t: at(95), k: 'note', p: 'sandbox started; audit: programs, files, commits, sessions' },
+        proc(94, 'C:\\AgentData\\tools\\uv\\uv.exe', 'uv tool install aider-chat', {}),
+        { t: at(90), k: 'session', a: 'start', p: 'claude', w: SESSIONS[0].cwd, c: claude.s, ...claude, sv: undefined },
+        proc(88, git, 'git status --short', claude),
+        proc(87, node, 'node dist/bin/agent-sandbox.js self-test audit', claude, 2),
+        file(80, 'src/host/audit/collect.ts', ws, claude),
+        file(79, 'src/app/features/audit/audit.def.ts', ws, claude),
+        proc(70, 'C:\\nvm\\nodejs\\npm.cmd', 'npm run build', claude),
+        {
+            t: at(66),
+            k: 'session',
+            a: 'start',
+            p: 'codex',
+            w: 'C:\\Projects\\mw2-agent',
+            c: codex.s,
+            ...codex,
+            sv: undefined,
+        },
+        proc(64, 'C:\\Users\\WDAGUtilityAccount\\.cargo\\bin\\cargo.exe', 'cargo build --release', codex, 3),
+        file(60, 'src/main.rs', mw, { ...codex, sv: 't' }),
+        proc(52, git, 'git commit -m "Audit: link programs to their session"', claude),
+        {
+            t: at(52),
+            k: 'commit',
+            a: 'commit',
+            p: 'Audit: link programs to their session',
+            h: 'a3f9c2e81b7d4c60a1e2f3b4c5d6e7f8a9b0c1d2',
+            au: 'Josh <josh@example.com>',
+            w: ws,
+            ...claude,
+        },
+        proc(40, git, 'git push --set-upstream origin https://***@github.com/example/mw2-agent.git', codex),
+        { t: at(38), k: 'guard', p: 'hook: a pre-push hook added inside the sandbox was neutralised' },
+        proc(30, 'C:\\Users\\WDAGUtilityAccount\\.cargo\\bin\\cargo.exe', 'cargo test', codex, 4),
+        {
+            t: at(28),
+            k: 'commit',
+            a: 'commit',
+            p: 'Fix the map loader',
+            h: '7be0d41c9a2f4e3b8c1d0e9f8a7b6c5d4e3f2a1b',
+            au: 'Josh <josh@example.com>',
+            w: mw,
+            ...codex,
+        },
+        {
+            t: at(20),
+            k: 'session',
+            a: 'end',
+            p: 'codex',
+            w: 'C:\\Projects\\mw2-agent',
+            c: codex.s + ' exit 0',
+            ...codex,
+            sv: undefined,
+        },
+        proc(5, node, 'node dist/bin/agent-sandbox.js self-test app', claude),
+        { t: at(4), k: 'remote', p: 'sessions.restart', a: 'ok', au: "device Josh's iPhone" },
+        { t: at(3), k: 'remote', p: 'settings.set', a: 'refused', au: 'Windows user DESKTOP-JOSH\\sam' },
+    ]);
+    return log;
+}
+const ACCESS_FINGERPRINT = '3A:7F:01:C2:9B:44:E8:15:6D:A0:2B:93:CC:71:58:0E:F4:12:9A:BD:63:07:E5:2C:48:D9:B1:76:0A:3F:C8:E2';
+/** Remote access: LAN mode on, two devices, one Windows sign-in, a code waiting. */
+function sampleAccess() {
+    const at = (hours) => new Date(Date.now() + hours * 3_600_000).toISOString();
+    return {
+        lan: {
+            enabled: true,
+            running: true,
+            address: 'https://192.168.1.20:47801',
+            fingerprint: ACCESS_FINGERPRINT,
+            problem: null,
+            network: 'Home Wi-Fi',
+        },
+        windowsSignIn: true,
+        users: [
+            { name: 'sam', role: 'view' },
+            { name: 'OFFICE\\kim', role: 'control' },
+        ],
+        rememberDays: 30,
+        devices: [
+            {
+                id: '4f2c9a7e1b3d5f60',
+                name: "Josh's iPhone",
+                role: 'control',
+                address: '192.168.1.42',
+                createdAt: at(-24 * 6),
+                expiresAt: at(24 * 24),
+                lastSeen: at(-0.2),
+            },
+            {
+                id: '9d1e0b2a7c4f6e83',
+                name: 'Kitchen tablet',
+                role: 'view',
+                address: '192.168.1.57',
+                createdAt: at(-24 * 20),
+                expiresAt: at(24 * 10),
+                lastSeen: at(-30),
+            },
+        ],
+        windows: [{ id: '1a2b3c4d5e6f7a8b', user: 'DESKTOP-JOSH\\sam', createdAt: at(-3), expiresAt: at(24 * 30 - 3) }],
+        pending: { role: 'view', expiresAt: at(0.06) },
+        codeVoided: false,
+    };
+}
 /** The real features where they only touch the temp folder, sample data for the rest. */
 function previewRpc(ctx, state) {
+    const auditDir = path.join(ctx.storageRoot, 'audit', 'preview');
+    const audit = sampleAuditLog(auditDir);
     const sample = async (id, input, io) => {
         switch (id) {
+            case 'audit.list':
+                // The real listing over a sample log in the temp folder.
+                return auditListing(audit, { enabled: true, days: 7, maxMb: 100 }, listAudit.input.parse(input ?? {}), auditDir);
             case 'sandbox.status':
                 return sampleStatus(state.running);
+            case 'access.status':
+                return sampleAccess();
+            case 'access.allowDevice':
+                return {
+                    code: 'K7QD-M2XP',
+                    expiresAt: new Date(Date.now() + 5 * 60_000).toISOString(),
+                    role: input?.role ?? 'view',
+                    address: 'https://192.168.1.20:47801',
+                    fingerprint: ACCESS_FINGERPRINT,
+                };
             case 'vpn.status':
                 return vpnStatus.output.parse({
                     enabled: true,
@@ -792,9 +941,17 @@ function previewRpc(ctx, state) {
         'logs.tail': 'query',
         'engine.status': 'query',
         'engine.leftovers': 'query',
+        'audit.list': 'query',
+        'access.status': 'query',
+        'access.allowDevice': 'operation',
+        'access.revoke': 'operation',
+        'access.revokeAll': 'operation',
+        'access.lanOn': 'operation',
+        'access.lanOff': 'operation',
     };
     return {
         kind: (id) => kinds[id],
+        need: (id) => (kinds[id] ? 'view' : undefined),
         liveMs: (id) => (id === 'sandbox.status' || id === 'sessions.list' ? 2500 : id === 'logs.tail' ? 1000 : undefined),
         run: async (id, input, io) => id !== 'apps.request' && (id.startsWith('settings.') || id.startsWith('apps.') || id === 'files.browse')
             ? runDefinition(id, ctx, input, io)

package/dist/selftest/toolchains.test.js

@@ -1,12 +1,13 @@
 // Picking tool versions and release assets: Node/Go/Python/Java version rules, GitHub release pages, PowerShell 7,
-// cargo-binstall, the small CLI tools (gh, zstd, openssl), and when PowerShell 7 is wanted.
+// cargo-binstall, the small CLI tools (gh, zstd, openssl), when PowerShell 7 is wanted, and the apps' agent add-ons.
+import fs from 'node:fs';
 import path from 'node:path';
 import { javaMajorFrom, pickGoRelease, pickNodeVersion, pickPackageVersion, pickSpreadVersions, projectUses, specFromVersionFile, } from '../core/detect/index.js';
 import { parseReleasePage, parseReleaseTags } from '../shared/download/index.js';
 import { decidePwsh, pcHasPwsh, PWSH_MAX_BYTES, readPwshScripts, usesPwsh } from '../core/detect/index.js';
 import { binstallAsset, CLI_TOOLS, decideCli, pwshAsset } from '../guest/toolchains/catalogue.js';
 import { missingExtensions, vscodeExtensions, vscodeSettings } from '../guest/toolchains/tools/vscode-profile.js';
-import { APP_CATEGORIES, APPS, appsNeedMesa, appsToInstall, exeMatcher } from '../shared/apps/index.js';
+import { addonGuideLine, addonMcpServer, APP_CATEGORIES, APPS, appsNeedMesa, appsNeedUv, appsToInstall, CCUSAGE_VERSION, claudeManagedSettings, CONTEXT7_MCP_VERSION, exeMatcher, HEADROOM_VERSION, headroomArgs, headroomEnv, headroomUrl, PLAYWRIGHT_MCP_VERSION, RTK_VERSION, withAddonMcpServers, } from '../shared/apps/index.js';
 import { ConfigSchema, LocalOverridesSchema } from '../core/schema/index.js';
 export const toolchainsSuite = {
     name: 'toolchains',
@@ -236,5 +237,149 @@ export const toolchainsSuite = {
             !custom({ name: 'E', github: 'o/r', asset: 'x', url: 'https://x.org', exe: 'e.exe' }), 'apps: your own program comes from a GitHub release or an https link; plain http, a broken pattern or both are refused');
         t.check(!LocalOverridesSchema.safeParse({ apps: { custom: {} } }).success &&
             LocalOverridesSchema.safeParse({ apps: { install: ['jq'] } }).success, 'apps: a project file may add catalogue apps but never programs of its own');
+        t.section('agent add-ons');
+        const rtk = APPS.find((a) => a.id === 'rtk');
+        const rtkSource = rtk?.source;
+        t.check(rtk?.category === 'agents' &&
+            rtk.cli === true &&
+            rtk.userOnly === true &&
+            rtkSource !== undefined &&
+            'url' in rtkSource &&
+            rtkSource.url.startsWith('https://github.com/rtk-ai/rtk/releases/download/v' + RTK_VERSION + '/') &&
+            rtkSource.url.endsWith('-x86_64-pc-windows-msvc.zip') &&
+            /^[0-9a-f]{64}$/.test(rtkSource.sha256 ?? ''), 'rtk: a pinned https release file of rtk-ai/rtk with its SHA-256, on PATH, in your own settings only');
+        t.check(APPS.every((a) => !('url' in a.source) || a.source.url.startsWith('https://')) &&
+            APPS.every((a) => !('url' in a.source) || a.source.sha256 === undefined || /^[0-9a-f]{64}$/.test(a.source.sha256)), 'apps: every direct link is https, and a pinned checksum is 64 hex characters');
+        const agentApps = APPS.filter((a) => a.category === 'agents').map((a) => a.id);
+        t.check(APP_CATEGORIES.some((c) => c.id === 'agents' && c.label === 'Agent add-ons') &&
+            agentApps.includes('rtk') &&
+            agentApps.includes('claude-mem') &&
+            APPS.find((a) => a.id === 'claude-mem')?.setting === 'claudeProfile.syncClaudeMem', 'apps: the Agent add-ons category holds rtk and claude-mem (claude-mem through its own setting)');
+        t.check(!LocalOverridesSchema.safeParse({ apps: { install: ['rtk'] } }).success &&
+            !LocalOverridesSchema.safeParse({ apps: { install: ['claude-mem'] } }).success &&
+            ConfigSchema.shape.apps.shape.install.safeParse(['rtk']).success, 'rtk: only your own settings turn it on; a project file cannot');
+        const exe = 'C:\\AgentData\\tools\\apps\\rtk\\rtk.exe';
+        const withRtk = claudeManagedSettings([], exe);
+        const both = claudeManagedSettings(['Bash(git push:*)'], exe);
+        const gitOnly = claudeManagedSettings(['Bash(git push:*)'], null);
+        t.equal(withRtk?.hooks?.PreToolUse, [{ matcher: 'Bash', hooks: [{ type: 'command', command: '"C:/AgentData/tools/apps/rtk/rtk.exe" hook claude' }] }], "rtk: its documented Bash PreToolUse hook goes into the sandbox's managed settings");
+        t.check(claudeManagedSettings([], null) === null &&
+            gitOnly?.hooks === undefined &&
+            gitOnly?.permissions?.deny.length === 1 &&
+            both?.permissions?.deny.length === 1 &&
+            both.hooks?.PreToolUse.length === 1 &&
+            withRtk?.permissions === undefined, 'rtk: no hook when it is off; the git deny rules stay beside it; nothing to write when neither');
+        t.section('agent add-ons: Headroom, ccusage, Playwright MCP, Context7 MCP');
+        const pinned = {
+            headroom: ['uv', 'headroom-ai', HEADROOM_VERSION],
+            ccusage: ['npm', 'ccusage', CCUSAGE_VERSION],
+            'playwright-mcp': ['npm', '@playwright/mcp', PLAYWRIGHT_MCP_VERSION],
+            context7: ['npm', '@upstash/context7-mcp', CONTEXT7_MCP_VERSION],
+        };
+        for (const [id, [kind, pkg, version]] of Object.entries(pinned)) {
+            const entry = APPS.find((a) => a.id === id);
+            const source = entry?.source;
+            t.check(entry?.category === 'agents' &&
+                entry.userOnly === true &&
+                source !== undefined &&
+                'locked' in source &&
+                source.locked === kind &&
+                source.package === pkg &&
+                source.version === version &&
+                /^\d+\.\d+\.\d+$/.test(version) &&
+                !LocalOverridesSchema.safeParse({ apps: { install: [id] } }).success &&
+                ConfigSchema.shape.apps.shape.install.safeParse([id]).success, id + ': in Agent add-ons, a pinned ' + kind + ' package (' + pkg + ' ' + version + '), your own settings only');
+            const lockDir = path.join(t.packageRoot, 'sandbox', 'addons', id);
+            if (kind === 'npm') {
+                const manifest = JSON.parse(fs.readFileSync(path.join(lockDir, 'package.json'), 'utf8'));
+                const lock = JSON.parse(fs.readFileSync(path.join(lockDir, 'package-lock.json'), 'utf8'));
+                const deps = Object.entries(lock.packages).filter(([key]) => key !== '');
+                t.check(manifest.dependencies[pkg] === version &&
+                    Object.keys(manifest.dependencies).length === 1 &&
+                    lock.lockfileVersion === 3 &&
+                    lock.packages['node_modules/' + pkg]?.version === version &&
+                    deps.length > 0 &&
+                    deps.every(([, p]) => !p.link &&
+                        (p.resolved ?? '').startsWith('https://registry.npmjs.org/') &&
+                        /^sha512-[A-Za-z0-9+/]+=*$/.test(p.integrity ?? '')), id + ': its lock file pins ' + pkg + ' ' + version + '; every package comes from npm with a sha512 integrity');
+            }
+            else {
+                const lines = fs.readFileSync(path.join(lockDir, 'requirements.txt'), 'utf8').split(/\r?\n/);
+                const requirements = lines.filter((l) => /^[A-Za-z0-9]/.test(l));
+                const blocks = lines
+                    .join('\n')
+                    .split(/\n(?=[A-Za-z0-9])/)
+                    .slice(1);
+                t.check(requirements.includes(pkg + '==' + version + ' \\') &&
+                    requirements.length > 10 &&
+                    requirements.every((l) => /^[A-Za-z0-9._-]+(\[[^\]]+\])?==[^\s]+ \\$/.test(l)) &&
+                    blocks.every((b) => /--hash=sha256:[0-9a-f]{64}/.test(b)) &&
+                    !lines.some((l) => /^\s*(-e|--index-url|--extra-index-url|-f|--find-links|git\+|https?:)/.test(l.trim())), id + ': its requirements.txt pins every package to one version with SHA-256 hashes, from PyPI only');
+            }
+        }
+        t.check(appsNeedUv({ install: ['headroom'], custom: {} }) &&
+            !appsNeedUv({ install: ['ccusage', 'rtk'], custom: {} }) &&
+            !appsNeedUv(undefined), 'headroom: choosing it brings the uv step (it installs with uv)');
+        const services = APPS.filter((a) => a.service).map((a) => a.id);
+        t.check(['headroom', 'playwright-mcp', 'context7'].every((id) => services.includes(id)) &&
+            APPS.find((a) => a.id === 'ccusage')?.cli === true &&
+            !services.includes('ccusage'), 'add-ons: the proxy and MCP servers get no shortcut and no PATH entry; ccusage is a command on PATH');
+        // Headroom: loopback only, Anthropic only, no telemetry, and none of the agents' secrets in its environment.
+        const args = headroomArgs();
+        t.check(args[0] === 'proxy' &&
+            args[args.indexOf('--host') + 1] === '127.0.0.1' &&
+            args[args.indexOf('--port') + 1] === '8787' &&
+            args[args.indexOf('--anthropic-api-url') + 1] === 'https://api.anthropic.com' &&
+            args.includes('--no-telemetry') &&
+            headroomUrl() === 'http://127.0.0.1:8787', 'headroom: the proxy listens on 127.0.0.1 only and forwards only to api.anthropic.com, telemetry off');
+        const proxyEnv = headroomEnv({
+            PATH: 'C:\\Windows',
+            ANTHROPIC_API_KEY: 'sk-ant-x',
+            CLAUDE_CODE_OAUTH_TOKEN: 'oauth',
+            GITHUB_TOKEN: 'ghp',
+            OPENAI_API_KEY: 'sk',
+            DB_PASSWORD: 'pw',
+            HTTPS_PROXY: 'http://127.0.0.1:3128',
+            HEADROOM_OFFLINE: '0',
+        });
+        t.check(proxyEnv.PATH === 'C:\\Windows' &&
+            proxyEnv.HTTPS_PROXY === 'http://127.0.0.1:3128' &&
+            !Object.values(proxyEnv).some((v) => ['sk-ant-x', 'oauth', 'ghp', 'sk', 'pw'].includes(v)) &&
+            proxyEnv.HEADROOM_OFFLINE === '1' &&
+            proxyEnv.HEADROOM_TELEMETRY === 'off' &&
+            proxyEnv.HEADROOM_UPDATE_CHECK === 'off', 'headroom: starts without keys or tokens, offline apart from forwarding (no telemetry, updates or downloads)');
+        const routed = claudeManagedSettings([], null, headroomUrl());
+        t.check(routed?.env?.ANTHROPIC_BASE_URL === 'http://127.0.0.1:8787' &&
+            claudeManagedSettings([], exe)?.env === undefined &&
+            claudeManagedSettings(['Bash(git push:*)'], null)?.env === undefined &&
+            claudeManagedSettings(['Bash(git push:*)'], exe, headroomUrl())?.hooks?.PreToolUse.length === 1, "headroom: Claude Code is pointed at the proxy only while it runs (the sandbox's managed settings env)");
+        // MCP servers: set while on, removed when off, your own servers never touched.
+        const playwright = APPS.find((a) => a.id === 'playwright-mcp')?.mcp;
+        const context7 = APPS.find((a) => a.id === 'context7')?.mcp;
+        const known = APPS.flatMap((a) => (a.mcp ? [a.mcp.name] : []));
+        const pw = playwright ? addonMcpServer('C:\\AgentData\\tools\\apps\\playwright-mcp', playwright) : null;
+        t.equal(pw, {
+            type: 'stdio',
+            command: 'node',
+            args: [
+                'C:\\AgentData\\tools\\apps\\playwright-mcp\\node_modules\\@playwright\\mcp\\cli.js',
+                '--browser',
+                'msedge',
+            ],
+            env: {},
+        }, 'playwright-mcp: a stdio MCP server run by node from its own folder, with Edge');
+        const mine = { playwright: { type: 'stdio', command: 'npx', args: ['@playwright/mcp'] } };
+        const on = withAddonMcpServers(mine, pw ? { 'sbx-playwright': pw } : {}, known);
+        const off = withAddonMcpServers({ ...on, 'sbx-context7': {} }, {}, known);
+        t.check(known.length === 2 &&
+            known.every((n) => n.startsWith('sbx-')) &&
+            context7?.name === 'sbx-context7' &&
+            'sbx-playwright' in on &&
+            'playwright' in on &&
+            Object.keys(off).join() === 'playwright' &&
+            withAddonMcpServers({ 'sbx-other': 1 }, {}, known)['sbx-other'] === 1, 'add-ons: their sbx-... MCP servers are set while on and removed when off; servers of your own stay');
+        t.check(addonGuideLine([], false).length === 0 &&
+            addonGuideLine(['sbx-playwright'], true).length === 2 &&
+            addonGuideLine(['sbx-playwright'], false)[0].includes('sbx-playwright'), 'add-ons: the agent guide names the MCP servers and ccusage only when they are on');
     },
 };

package/dist/selftest/web.test.js

@@ -105,6 +105,7 @@ function fakeRpc() {
     const host = {
         kind: (id) => (id === 'test.work' ? 'operation' : id === 'test.live' ? 'query' : undefined),
         liveMs: (id) => (id === 'test.live' ? 50 : undefined),
+        need: (id) => (id === 'test.work' ? 'control' : id === 'test.live' ? 'view' : undefined),
         run: async (id, input, io) => {
             ran.push(id);
             if (id === 'test.live')
@@ -216,6 +217,7 @@ export const webSuite = {
             let reads = 0;
             const host = {
                 kind: () => 'query',
+                need: () => 'view',
                 liveMs: () => 40,
                 run: async () => {
                     reads++;

package/dist/shared/apps/agent-addons.d.ts

@@ -0,0 +1,64 @@
+import type { AddonMcp } from './catalogue.js';
+/** One hook command in Claude Code's settings. */
+interface ClaudeHook {
+    readonly type: 'command';
+    readonly command: string;
+}
+/** Claude Code's managed-settings.json as the sandbox writes it. */
+export interface ManagedSettings {
+    readonly permissions?: {
+        readonly deny: readonly string[];
+    };
+    readonly hooks?: {
+        readonly PreToolUse: readonly {
+            readonly matcher: string;
+            readonly hooks: readonly ClaudeHook[];
+        }[];
+    };
+    readonly env?: Readonly<Record<string, string>>;
+}
+/** The command Claude Code runs for rtk's hook: the program by its full path (quoted, forward slashes for Git Bash). */
+export declare function rtkHookCommand(exe: string): string;
+/**
+ * The managed settings for the git deny rules, rtk's Bash hook when rtk is installed (`rtkExe`) and the Headroom proxy
+ * when it runs (`headroomUrl`). Null when there is nothing to write (the file is removed then).
+ */
+export declare function claudeManagedSettings(deny: readonly string[], rtkExe: string | null, headroomUrl?: string | null): ManagedSettings | null;
+/** The line every agent's sandbox guide gets while rtk is installed (Claude's commands go through it on their own). */
+export declare const RTK_GUIDE_LINE = "- rtk is on PATH and compacts command output: Claude Code's Bash commands go through it on their own; in other agents prefix shell commands with `rtk` (`rtk git status`, `rtk cargo test`, `rtk ls`).";
+/** Headroom listens here, on loopback only (its default port). */
+export declare const HEADROOM_PORT = 8787;
+/** The only upstream Headroom forwards to: Anthropic's API, set on its command line. */
+export declare const HEADROOM_UPSTREAM = "https://api.anthropic.com";
+/** Claude Code's ANTHROPIC_BASE_URL while the proxy runs. */
+export declare function headroomUrl(port?: number): string;
+/** `headroom proxy` on loopback, forwarding only to Anthropic's API, with no telemetry. */
+export declare function headroomArgs(port?: number): string[];
+/**
+ * Headroom's own switches: HEADROOM_OFFLINE refuses every connection Headroom would make on its own (telemetry, update
+ * checks, model downloads, usage polling) and keeps only the forwarding of the agent's requests.
+ */
+export declare const HEADROOM_ENV: Readonly<Record<string, string>>;
+/** The environment Headroom starts with: the sandbox's, minus anything secret, plus its own switches. */
+export declare function headroomEnv(base: Readonly<Record<string, string | undefined>>): Record<string, string>;
+/** The guide line while the proxy runs. */
+export declare function headroomGuideLine(logFile: string): string;
+/** A user-scope MCP server in Claude Code's .claude.json. */
+export interface McpServerConfig {
+    readonly type: 'stdio';
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+}
+/** The name prefix of the sandbox's own MCP servers: names with it are the sandbox's to add and remove. */
+export declare const ADDON_MCP_PREFIX = "sbx-";
+/** The MCP server of an installed add-on: `node <folder>\<script> <args>` (Node is on PATH in every sandbox). */
+export declare function addonMcpServer(folder: string, mcp: AddonMcp): McpServerConfig;
+/**
+ * The user-scope MCP servers with the add-ons' servers set: every sbx-... server that `known` lists and that is not in
+ * `servers` is removed (an add-on turned off); servers of your own are never touched.
+ */
+export declare function withAddonMcpServers(current: Readonly<Record<string, unknown>>, servers: Readonly<Record<string, McpServerConfig>>, known: readonly string[]): Record<string, unknown>;
+/** The guide line for the add-ons' MCP servers and tools (none: no line). */
+export declare function addonGuideLine(mcpNames: readonly string[], ccusage: boolean): string[];
+export {};

package/dist/shared/apps/agent-addons.js

@@ -0,0 +1,95 @@
+/** The command Claude Code runs for rtk's hook: the program by its full path (quoted, forward slashes for Git Bash). */
+export function rtkHookCommand(exe) {
+    return '"' + exe.replace(/\\/g, '/') + '" hook claude';
+}
+/**
+ * The managed settings for the git deny rules, rtk's Bash hook when rtk is installed (`rtkExe`) and the Headroom proxy
+ * when it runs (`headroomUrl`). Null when there is nothing to write (the file is removed then).
+ */
+export function claudeManagedSettings(deny, rtkExe, headroomUrl = null) {
+    if (!deny.length && !rtkExe && !headroomUrl)
+        return null;
+    return {
+        ...(deny.length ? { permissions: { deny } } : {}),
+        ...(rtkExe
+            ? { hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: rtkHookCommand(rtkExe) }] }] } }
+            : {}),
+        ...(headroomUrl ? { env: { ANTHROPIC_BASE_URL: headroomUrl } } : {}),
+    };
+}
+/** The line every agent's sandbox guide gets while rtk is installed (Claude's commands go through it on their own). */
+export const RTK_GUIDE_LINE = "- rtk is on PATH and compacts command output: Claude Code's Bash commands go through it on their own; in other agents prefix shell commands with `rtk` (`rtk git status`, `rtk cargo test`, `rtk ls`).";
+/** Headroom listens here, on loopback only (its default port). */
+export const HEADROOM_PORT = 8787;
+/** The only upstream Headroom forwards to: Anthropic's API, set on its command line. */
+export const HEADROOM_UPSTREAM = 'https://api.anthropic.com';
+/** Claude Code's ANTHROPIC_BASE_URL while the proxy runs. */
+export function headroomUrl(port = HEADROOM_PORT) {
+    return 'http://127.0.0.1:' + port;
+}
+/** `headroom proxy` on loopback, forwarding only to Anthropic's API, with no telemetry. */
+export function headroomArgs(port = HEADROOM_PORT) {
+    return [
+        'proxy',
+        '--host',
+        '127.0.0.1',
+        '--port',
+        String(port),
+        '--anthropic-api-url',
+        HEADROOM_UPSTREAM,
+        '--no-telemetry',
+    ];
+}
+/**
+ * Headroom's own switches: HEADROOM_OFFLINE refuses every connection Headroom would make on its own (telemetry, update
+ * checks, model downloads, usage polling) and keeps only the forwarding of the agent's requests.
+ */
+export const HEADROOM_ENV = {
+    HEADROOM_OFFLINE: '1',
+    HEADROOM_TELEMETRY: 'off',
+    HEADROOM_BEACON: 'off',
+    HEADROOM_UPDATE_CHECK: 'off',
+    DO_NOT_TRACK: '1',
+    HF_HUB_OFFLINE: '1',
+    PYTHONIOENCODING: 'utf-8',
+};
+/** Variables the proxy never gets: keys, tokens and passwords of the agents (it only forwards what Claude sends). */
+const SECRET_NAME = /(KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH)/i;
+/** The environment Headroom starts with: the sandbox's, minus anything secret, plus its own switches. */
+export function headroomEnv(base) {
+    const env = {};
+    for (const [name, value] of Object.entries(base))
+        if (value !== undefined && !SECRET_NAME.test(name) && !/^(ANTHROPIC|OPENAI|CLAUDE)_/i.test(name))
+            env[name] = value;
+    return { ...env, ...HEADROOM_ENV };
+}
+/** The guide line while the proxy runs. */
+export function headroomGuideLine(logFile) {
+    return ("- Headroom compresses Claude Code's requests: Claude Code reaches the API through its proxy on " +
+        headroomUrl() +
+        ' (log: `' +
+        logFile +
+        '`). If Claude Code cannot reach the API, the proxy stopped: it starts again with the next sandbox, or turn Headroom off in Apps.');
+}
+/** The name prefix of the sandbox's own MCP servers: names with it are the sandbox's to add and remove. */
+export const ADDON_MCP_PREFIX = 'sbx-';
+/** The MCP server of an installed add-on: `node <folder>\<script> <args>` (Node is on PATH in every sandbox). */
+export function addonMcpServer(folder, mcp) {
+    const script = folder.replace(/[\\/]+$/, '') + '\\' + mcp.script.replace(/\//g, '\\');
+    return { type: 'stdio', command: 'node', args: [script, ...(mcp.args ?? [])], env: {} };
+}
+/**
+ * The user-scope MCP servers with the add-ons' servers set: every sbx-... server that `known` lists and that is not in
+ * `servers` is removed (an add-on turned off); servers of your own are never touched.
+ */
+export function withAddonMcpServers(current, servers, known) {
+    const kept = Object.fromEntries(Object.entries(current).filter(([name]) => !known.includes(name) || name in servers));
+    return { ...kept, ...servers };
+}
+/** The guide line for the add-ons' MCP servers and tools (none: no line). */
+export function addonGuideLine(mcpNames, ccusage) {
+    return [
+        ...(mcpNames.length ? ['- MCP servers in Claude Code from Apps: ' + mcpNames.join(', ') + '.'] : []),
+        ...(ccusage ? ['- ccusage is on PATH: `ccusage daily` (or `monthly`, `session`) reports token use and cost.'] : []),
+    ];
+}