windows-development-sandbox 1.10.0 → 1.11.4

package/dist/selftest/update-service.test.js

@@ -5,7 +5,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { parseCli } from '../cli/args.js';
-import { describeResult, runUpdate } from '../cli/commands/maintenance/update.js';
+import { describeResult } from '../app/features/updates/update-lines.js';
+import { updateWith } from '../app/features/updates/updates.run.js';
+import { fakeIO } from '../app/kernel/index.js';
 import { UpdateService, runsAsSystem } from '../cli/services/index.js';
 import { InstallLayout, InstallRecordFile, UpdateTask, shimText } from '../host/install/index.js';
 import { nativeScript } from '../host/native.js';
@@ -170,7 +172,7 @@ async function failedInstall(t) {
     t.check(bad2?.kind === 'failed' &&
         bad2.autoUpdateOff &&
         new InstallRecordFile(root2).read()?.autoUpdate === false &&
-        (await runUpdate(svc2, { check: false, rollback: false, unattended: true }, () => undefined)) === 0 &&
+        (await updateWith(svc2, { check: false, rollback: false, unattended: true }, fakeIO().io)).line === '' &&
         layout2.activeVersion() === '1.0.0', 'a task that cannot be removed does not stop the rollback; an unattended run with updates off does nothing');
     publish(t, feed2, '1.0.2', 'good');
     const ok2 = await svc2.run();
@@ -204,11 +206,17 @@ function pure(t) {
 async function command(t) {
     t.section('sandbox update: what it prints');
     const lines = [];
-    const print = (line) => void lines.push(line);
+    // sandbox update's work through the feature: the line it returns is what the command prints.
+    const runU = async (svc, input) => {
+        const auto = input.auto ? { auto: input.auto } : {};
+        const out = await updateWith(svc, { check: input.check ?? false, rollback: false, unattended: false, ...auto }, fakeIO([true]).io);
+        lines.push(out.line);
+        return out.line;
+    };
     const npm = new UpdateService(null, { version: '1.0.0' });
     const npmAuto = await t.thrownMessage(() => npm.setAuto(true));
     t.check(!npm.managed &&
-        (await runUpdate(npm, { check: false, rollback: false, unattended: false }, print)) === 0 &&
+        (await runU(npm, {})).includes('npm install -g windows-development-sandbox') &&
         lines.join('\n').includes('npm install -g windows-development-sandbox') &&
         npmAuto.includes('installed with npm'), 'an npm install is not managed, is told the npm command, and cannot turn on automatic updates', npmAuto);
     const root = t.dir('cmd', 'install');
@@ -221,17 +229,16 @@ async function command(t) {
         sandboxRunning: () => false,
         version: '1.0.0',
     });
-    await runUpdate(machine, { check: false, rollback: false, unattended: false, auto: 'on' }, print);
+    await runU(machine, { auto: 'on' });
     const afterOn = [...task.calls];
-    await runUpdate(machine, { check: false, rollback: false, unattended: false, auto: 'off' }, print);
+    await runU(machine, { auto: 'off' });
     t.check(afterOn.join() === 'register' && task.calls.join() === 'register,remove' && !machine.autoUpdateDue(), '--auto on/off creates and removes the scheduled task of an all-users install; it never updates from a CLI start');
     task.fail = true;
     const noAdmin = await t.thrownMessage(() => machine.setAuto(true));
     t.check(noAdmin.includes('needs admin') && new InstallRecordFile(root).read()?.autoUpdate === false, 'a task that cannot be created fails and the setting stays off', noAdmin);
     publish(t, feed, '1.0.1', 'good');
     lines.length = 0;
-    t.check((await runUpdate(machine, { check: true, rollback: false, unattended: false }, print)) === 0 &&
-        lines.join('\n').includes('Version 1.0.1 is available'), '--check names the newer version and exits 0');
+    t.check((await runU(machine, { check: true })).includes('Version 1.0.1 is available'), '--check names the newer version and exits 0');
     const waiting = { kind: 'skipped', reason: 'sandbox-running', current: '1.0.0' };
     t.check(describeResult(null, false).code === 0 &&
         describeResult(waiting, false).code === 1 &&

package/dist/selftest/vpn.test.js

@@ -2,7 +2,13 @@
 // the settings rules for projects, and that the login never lands in session.json or the launch folder.
 import fs from 'node:fs';
 import path from 'node:path';
+import { vpnLoginRowOf, vpnPage, VPN_WARNINGS } from '../app/features/vpn/index.js';
+import { fakeIO, pageActions } from '../app/kernel/index.js';
+import { runDefinition } from '../app/registry.js';
+import { pageLines } from '../cli/output/index.js';
+import { VpnService } from '../cli/services/index.js';
 import { DEFAULTS } from '../core/config/index.js';
+import { insideSandbox } from '../host/sandbox/platform.js';
 import { applyOverrides, loosenedRequests, NEVER_LOOSER, normalizeOverrides } from '../core/local-config/index.js';
 import { ConfigSchema, LocalOverridesSchema } from '../core/schema/index.js';
 import { SecretStore } from '../host/secrets/index.js';
@@ -11,7 +17,7 @@ import { generateSandbox } from '../host/launch/index.js';
 import { findCountry, nordProfile, prepareVpn, wireguardFileProblem, recommendedServer, VpnLogin, vpnLine, vpnNotes, } from '../host/vpn/index.js';
 import { RunDir } from '../shared/channel/index.js';
 import { OPENVPN_MSI, WIREGUARD_MSI } from '../shared/vpn/download.js';
-import { cleanServers, killSwitchCommands, removeKillSwitchCommands, tunnelAddressFromLog, tunnelCommands, } from '../shared/vpn/kill-switch.js';
+import { cleanServers, ipv4Except, killSwitchCommands, removeKillSwitchCommands, tunnelAddressFromLog, tunnelCommands, } from '../shared/vpn/kill-switch.js';
 import { assertSafeOvpn, inspectOvpn, PROGRAM_DIRECTIVES } from '../shared/vpn/ovpn.js';
 import { assertSafeWireguard, handshakeDone, inspectWireguard, renderWireguard, serviceRunning, WIREGUARD_PROGRAM_KEYS, wireguardEndpoints, wireguardTunnelAddress, } from '../shared/vpn/wireguard.js';
 const PROFILE = [
@@ -128,6 +134,32 @@ export const vpnSuite = {
                 c.includes('program=C:\\AgentLaunch\\ptyhost.exe')) &&
             phase1.some((c) => c.includes('name=AgentSandbox-VPN-DHCP')), 'it allows loopback, each VPN server endpoint, the attach channel on the Hyper-V network and DHCP');
         t.check(!phase1.some((c) => c.includes('localip=') || (c.includes('action=allow') && c.includes('remoteip=any'))), 'nothing else is allowed before the tunnel exists (no blanket rule)');
+        const blockAt = (name) => phase1.findIndex((c) => c.includes('name=AgentSandbox-VPN-' + name + ' '));
+        const internet = phase1[blockAt('Block-Internet')] ?? '';
+        t.check(['Block-Internet', 'Block-IPv6', 'Block-DNS-UDP', 'Block-DNS-TCP'].every((name) => blockAt(name) >= 0 && blockAt(name) < policyAt && phase1[blockAt(name)].includes('action=block')), 'the kill switch is made of block rules, added before anything else (Windows Sandbox allows all outbound itself)', phase1.join('\n'));
+        t.check(internet.includes('1.0.0.0-9.255.255.255') &&
+            internet.includes('-185.1.2.2,185.1.2.4-185.9.9.8,185.9.9.10-') &&
+            !/(^|[=,])10\.\d/.test(internet.split('remoteip=')[1] ?? '') &&
+            internet.includes('-172.15.255.255,172.32.0.0-') &&
+            internet.includes('-192.167.255.255,192.169.0.0-') &&
+            internet.endsWith('-223.255.255.255'), 'the block covers every public address except the VPN servers (private, loopback and multicast are the LAN block)', internet);
+        t.check(phase1[blockAt('Block-IPv6')].includes('remoteip=2000::/3') &&
+            phase1[blockAt('Block-DNS-UDP')].includes('protocol=udp remoteport=53') &&
+            phase1[blockAt('Block-DNS-TCP')].includes('protocol=tcp remoteport=53'), 'global IPv6 and DNS (which would leak the names you visit) are blocked too');
+        t.equal([
+            ipv4Except([]),
+            ipv4Except([[0, 0]]),
+            ipv4Except([[4294967295, 4294967295]]),
+            ipv4Except([
+                [5, 9],
+                [7, 12],
+            ]),
+        ], [
+            '0.0.0.0-255.255.255.255',
+            '0.0.0.1-255.255.255.255',
+            '0.0.0.0-255.255.255.254',
+            '0.0.0.0-0.0.0.4,0.0.0.13-255.255.255.255',
+        ], 'address lists without some addresses (edges and overlaps)');
         t.check(killSwitchCommands([], null).every((c) => !c.join(' ').includes('Server-1') || c[2] === 'delete') &&
             !killSwitchCommands([], null).some((c) => c.join(' ').includes('name=AgentSandbox-VPN-Host') && c[2] === 'add'), 'with no servers and no session host only the block and the loopback rules remain (the failure case: offline)');
         t.equal(tunnelCommands('10.8.0.6')
@@ -135,9 +167,13 @@ export const vpnSuite = {
             .filter((c) => c.includes(' add ')), [
             'advfirewall firewall add rule name=AgentSandbox-VPN-Tunnel dir=out action=allow enable=yes profile=any protocol=any localip=10.8.0.6',
         ], 'once the tunnel is up, traffic from its own address (the tunnel) is allowed');
+        const phase2 = tunnelCommands('10.8.0.6').map((c) => c.join(' '));
+        t.check(['Block-Internet', 'Block-DNS-UDP', 'Block-DNS-TCP'].every((name) => phase2.some((c) => c.startsWith('advfirewall firewall set rule name=AgentSandbox-VPN-' + name + ' new ') &&
+            c.endsWith('localip=0.0.0.0-10.8.0.5,10.8.0.7-255.255.255.255'))) && !phase2.some((c) => c.includes('delete') && c.includes('Block-')), 'the block rules are narrowed in place to everything but the tunnel (never deleted, so no moment without them)', phase2.join('\n'));
         await t.throws(() => tunnelCommands('10.8.0.6; calc'), 'Not an IPv4', 'a tunnel address that is not an address makes no rule');
         t.check(removeKillSwitchCommands().some((c) => c.join(' ').includes('blockinbound,allowoutbound')) &&
-            removeKillSwitchCommands().some((c) => c.join(' ').includes('name=AgentSandbox-VPN-Tunnel')), 'taking it away restores the default and deletes the rules');
+            removeKillSwitchCommands().some((c) => c.join(' ').includes('name=AgentSandbox-VPN-Tunnel')) &&
+            removeKillSwitchCommands().some((c) => c.join(' ').includes('name=AgentSandbox-VPN-Block-Internet')), 'taking it away restores the default and deletes the rules');
         t.equal([
             tunnelAddressFromLog('... net_addr_v4_add: 10.100.0.2/16 dev Wintun ...'),
             tunnelAddressFromLog('ifconfig 10.8.0.6 255.255.255.0'),
@@ -288,6 +324,10 @@ export const vpnSuite = {
             status('failed', { message: 'login refused' }).text.includes('no internet') &&
             vpnLine({ state: 'failed', message: 'x', killSwitch: false, updatedAt: 'now' }).text.includes('normal connection') &&
             status('starting').level === 'warn', "up with another address is fine, up with this PC's own address is flagged, a failure says what the kill switch did");
+        t.check(status('failed', { killSwitchHeld: false }).text.includes('ONLINE') &&
+            !status('failed', { killSwitchHeld: false }).text.includes('no internet') &&
+            status('failed', { killSwitchHeld: true }).text.includes('no internet') &&
+            status('up', { publicIp: '185.1.2.3', killSwitchHeld: false }).level === 'warn', 'a kill switch that did not hold is never reported as "no internet" (a failure says the sandbox is online)');
         t.check(!vpnLine({
             state: 'failed',
             message: 'bad \u001b]52;c;ZXZpbA==\u0007 text',
@@ -408,5 +448,49 @@ export const vpnSuite = {
         clearSecrets(wgSettings.storage.root, wgRun.dataPath);
         t.check(!fs.existsSync(new RunDir(wgRun.dataPath).secretFile(wgLaunch.launchId)) &&
             vpnNotes(wgSettings.vpn).some((n) => n.includes('WireGuard private key') && n.includes('turn the tunnel off')), 'the launch warns that the agent can read the key and turn the tunnel off');
+        t.section('the VPN feature: status page, login and logout');
+        const sample = {
+            enabled: true,
+            provider: 'nordvpn',
+            protocol: 'udp',
+            country: '',
+            killSwitch: true,
+            login: 'none',
+            loginSavedAt: null,
+            running: null,
+        };
+        const lines = pageLines(vpnPage(sample)).join('\n');
+        t.check(lines.includes('Next: sandbox vpn login') &&
+            VPN_WARNINGS.every((w) => lines.includes(w)) &&
+            !lines.includes('Running now'), 'vpn status page: the facts, the next step on the command line only, the warnings', lines);
+        t.equal(pageActions(vpnPage({ ...sample, provider: 'wireguard-file' })).map((a) => a.kind === 'operation' ? a.op : a.kind), ['settings.set'], 'vpn: wireguard needs no login and offers only turning the VPN on or off');
+        t.equal(pageActions(vpnPage({ ...sample, login: 'saved', loginSavedAt: '2026-10-14T09:30:00.000Z' })).map((a) => a.kind === 'operation' ? a.op : a.kind), ['settings.set', 'vpn.login', 'vpn.logout'], 'a saved login offers turning the VPN on or off, saving the login again and deleting it');
+        t.equal(vpnLoginRowOf(sample).hint, 'not saved', 'the Settings row says not saved when no login is saved');
+        const featureStorage = t.dir('vpn-feature');
+        const featureCtx = {
+            storageRoot: featureStorage,
+            dataPath: t.at('vpn-feature', 'data'),
+            loaded: { config: { vpn: { ...DEFAULTS.vpn, provider: 'nordvpn' } } },
+        };
+        const read = (await runDefinition('vpn.status', featureCtx, { tunnel: false }, fakeIO().io));
+        t.check(read.login === 'none' && read.running === null, 'vpn status reads the saved login without the tunnel request', JSON.stringify(read));
+        const { io: loginIO, seen: loginSeen } = fakeIO();
+        await t.throws(() => runDefinition('vpn.login', featureCtx, { password: PASSWORD }, loginIO), 'does not work', 'the login is never accepted as an input');
+        t.check(loginSeen.questions.length === 0, 'a login passed on the command line asks nothing');
+        // The on-PC guard only refuses inside a sandbox, so it is tested there; elsewhere there is nothing to assert.
+        if (insideSandbox()) {
+            const { io, seen } = fakeIO();
+            await t.throws(() => runDefinition('vpn.login', featureCtx, {}, io), 'inside the sandbox already', 'vpn login refuses inside the sandbox');
+            t.check(seen.questions.length === 0, 'and asks no question first');
+        }
+        const service = new VpnService(featureCtx, SecretStore.memory());
+        service.save({ username: USERNAME, password: PASSWORD });
+        const onDisk = fs.readFileSync(path.join(featureStorage, 'vpn', 'nordvpn.json'), 'utf8');
+        t.check(!onDisk.includes(PASSWORD) && !onDisk.includes(USERNAME), 'the saved file holds no login in clear');
+        const report = await service.report({ tunnel: false });
+        t.check(report.login === 'saved' &&
+            !JSON.stringify(report).includes(PASSWORD) &&
+            !JSON.stringify(report).includes(USERNAME), 'a saved login shows as saved, and the status never holds it');
+        t.check(service.remove() && service.loginState() === 'none', 'deleting the login leaves none saved');
     },
 };

package/dist/selftest/web.test.js

@@ -8,7 +8,7 @@ import WebSocket from 'ws';
 import { cancelled } from '../app/kernel/index.js';
 import { webSession } from '../cli/services/index.js';
 import { fail } from '../core/util/index.js';
-import { cookieValue, csrfOk, hostAllowed, originAllowed, sameSecret, StaticFiles, WebAuth, WebServer, WebStore, } from '../host/web/index.js';
+import { cookieValue, csrfOk, hostAllowed, LiveHub, originAllowed, sameSecret, StaticFiles, WebAuth, WebServer, WebStore, } from '../host/web/index.js';
 import { encodeFrame, FrameReader, FrameType } from '../shared/pty/index.js';
 import { CSRF_HEADER, CSRF_VALUE, parseClientMessage } from '../shared/web/index.js';
 const TOKEN = 'a'.repeat(64);
@@ -153,7 +153,7 @@ export const webSuite = {
         t.check(good.ok, 'the right token logs in');
         const cookie = good.ok ? good.cookie : '';
         t.check(auth.signedIn('x=1; sbxweb=' + cookie), 'the cookie signs in');
-        t.check(!auth.signedIn('sbxweb=' + cookie.replace(/.$/, '0')) && !auth.signedIn(undefined), 'another cookie does not');
+        t.check(!auth.signedIn('sbxweb=' + cookie.replace(/.$/, (c) => (c === '0' ? '1' : '0'))) && !auth.signedIn(undefined), 'another cookie does not');
         clock += 13 * 60 * 60 * 1000;
         t.check(!auth.signedIn('sbxweb=' + cookie), 'a cookie unused for 12 hours expires');
         const limited = new WebAuth(TOKEN, () => clock);
@@ -210,12 +210,46 @@ export const webSuite = {
         t.excludes(shown, ATTACH_TOKEN, 'the attach token is not in what the browser gets');
         t.excludes(shown, '1234', 'nor the port');
         t.excludes(shown, '\x1b', 'text from the sandbox is made safe');
+        t.section('live queries are shared, slow down when calm, and stop when nobody watches');
+        {
+            let value = 1;
+            let reads = 0;
+            const host = {
+                kind: () => 'query',
+                liveMs: () => 40,
+                run: async () => {
+                    reads++;
+                    return { value };
+                },
+            };
+            const hub = new LiveHub(host);
+            const seenA = [];
+            const seenB = [];
+            const stopA = hub.watch('q', {}, (e) => seenA.push(e));
+            await t.waitFor(() => seenA.length === 1, 2000);
+            const readsBeforeB = reads;
+            const stopB = hub.watch('q', {}, (e) => seenB.push(e));
+            t.check(reads === readsBeforeB && seenB.length === 1 && hub.size === 1, 'a second watcher of the same query gets the last answer at once, without another read');
+            const before = reads;
+            await new Promise((r) => setTimeout(r, 800));
+            const calmReads = reads - before;
+            t.check(calmReads >= 3 && calmReads < 20, 'an unchanged answer is read less often than every interval (' + calmReads + ' reads in 20 intervals)');
+            t.check(seenA.length === 1, 'an unchanged answer is not sent again');
+            value = 2;
+            hub.poke();
+            await t.waitFor(() => seenA.length === 2 && seenB.length === 2, 2000);
+            t.check(true, 'after an operation (poke) every watcher gets the new answer at once');
+            stopA();
+            stopB();
+            const stopped = reads;
+            await new Promise((r) => setTimeout(r, 300));
+            t.check(hub.size === 0 && reads === stopped, 'with nobody watching, nothing is read');
+        }
         t.section('the server');
         const fake = new FakePtyHost();
         await fake.start();
         const endpoint = { addresses: ['127.0.0.1'], port: fake.port, token: ATTACH_TOKEN };
         const listed = webSession(session('abc123'), 0);
-        const created = [];
         const backend = {
             info: () => Promise.resolve({
                 sandbox: 'running',
@@ -227,10 +261,6 @@ export const webSuite = {
             }),
             sessions: () => Promise.resolve([listed]),
             endpoint: (id) => (id === 'abc123' ? endpoint : null),
-            create: (request) => {
-                created.push(request);
-                return Promise.resolve(listed);
-            },
         };
         let stopped = false;
         const rpc = fakeRpc();
@@ -241,6 +271,7 @@ export const webSuite = {
             staticRoot: root,
             rpc: rpc.host,
             onStop: () => (stopped = true),
+            heartbeatMs: 200,
         });
         await server.start();
         const { port } = server;
@@ -276,10 +307,7 @@ export const webSuite = {
             t.check(list.status === 200 && JSON.parse(list.body).length === 1, 'a signed-in browser lists sessions');
             t.excludes(list.body, ATTACH_TOKEN, 'the list has no attach token');
             t.equal((await send(port, 'GET', '/api/info', { Cookie })).status, 200, 'and reads the info');
-            t.equal((await send(port, 'POST', '/api/sessions', { ...json, Cookie }, '{}')).status, 403, 'a new session needs CSRF and Origin');
-            t.equal((await send(port, 'POST', '/api/sessions', { ...ajax, Cookie }, '{"harness":"../x","project":"p"}')).status, 400, 'odd names are refused');
-            const made = await send(port, 'POST', '/api/sessions', { ...ajax, Cookie }, '{"harness":"claude","project":"app"}');
-            t.check(made.status === 201 && created.length === 1, 'a new session is requested');
+            t.equal((await send(port, 'POST', '/api/sessions', { ...json, Cookie }, '{}')).status, 404, 'starting an agent is an operation now: there is no POST /api/sessions');
             t.section('the terminal bridge');
             const url = 'ws://127.0.0.1:' + port + '/api/sessions/abc123/terminal?cols=100&rows=40';
             const attempts = [
@@ -380,6 +408,25 @@ export const webSuite = {
             leaver.socket.close();
             await t.waitFor(() => leaver.closeCode !== null, 5000);
             t.check(rpc.ran.length === runs + 1, 'a browser that leaves mid-question answers no (the call ends)');
+            t.section('connections never pile up');
+            const tabs = [];
+            for (let i = 0; i < 9; i++) {
+                const tab = new Tab(rpcUrl, { Origin: origin, Cookie });
+                tabs.push(tab);
+                await t.waitFor(() => tab.opened || tab.failed, 5000);
+            }
+            await t.waitFor(() => server.openSockets('rpc') <= 8, 5000);
+            t.check(tabs.every((tab) => tab.opened) && server.openSockets('rpc') === 8, 'a new page always connects: at the limit the oldest connection makes room', 'open: ' + server.openSockets('rpc'));
+            t.check([browser, ...tabs].some((tab) => tab.closeCode === 4000), 'the oldest is closed with "replaced by a newer page"');
+            for (const tab of tabs)
+                tab.socket.close();
+            const silent = new WebSocket(rpcUrl, { headers: { Origin: origin, Cookie }, autoPong: false });
+            let silentClosed = false;
+            silent.on('close', () => (silentClosed = true));
+            silent.on('error', () => undefined);
+            await t.waitFor(() => silent.readyState === WebSocket.OPEN, 5000);
+            await t.waitFor(() => silentClosed, 3000);
+            t.check(silentClosed, 'a page that stops answering pings (gone without closing) is dropped');
             t.section('stopping');
             t.equal((await send(port, 'POST', '/api/stop', { ...json, Cookie }, '{}')).status, 403, 'stop needs CSRF and Origin too');
             t.equal((await send(port, 'POST', '/api/stop', { ...ajax, Cookie }, '{}')).status, 200, 'a signed-in browser can stop it');

package/dist/shared/channel/run-dir.d.ts

@@ -9,6 +9,8 @@ export declare class RunDir {
     readonly vpnFile: string;
     /** What the memory governor in the sandbox is doing (pressure.json). */
     readonly pressureFile: string;
+    /** What the sandbox's programs may really use (budget.json): processors, memory, build jobs, link slots. */
+    readonly budgetFile: string;
     readonly requestsDir: string;
     readonly responsesDir: string;
     readonly sessionsDir: string;

package/dist/shared/channel/run-dir.js

@@ -36,6 +36,8 @@ export class RunDir {
     vpnFile;
     /** What the memory governor in the sandbox is doing (pressure.json). */
     pressureFile;
+    /** What the sandbox's programs may really use (budget.json): processors, memory, build jobs, link slots. */
+    budgetFile;
     requestsDir;
     responsesDir;
     sessionsDir;
@@ -49,6 +51,7 @@ export class RunDir {
         this.sandboxFile = path.join(this.root, 'sandbox.json');
         this.vpnFile = path.join(this.root, 'vpn.json');
         this.pressureFile = path.join(this.root, 'pressure.json');
+        this.budgetFile = path.join(this.root, 'budget.json');
         this.requestsDir = path.join(this.root, 'requests');
         this.responsesDir = path.join(this.root, 'responses');
         this.sessionsDir = path.join(this.root, 'sessions');

package/dist/shared/channel/schema.d.ts

@@ -556,6 +556,10 @@ export declare const GuestRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     id: z.ZodString;
     reason: z.ZodString;
     seconds: z.ZodNumber;
+    level: z.ZodOptional<z.ZodEnum<{
+        slow: "slow";
+        severe: "severe";
+    }>>;
     createdAt: z.ZodString;
 }, z.core.$strict>], "kind">;
 /** C:\AgentData\run\pressure.json: what the memory governor in the sandbox is doing (guest-written, capped). */
@@ -565,6 +569,7 @@ export declare const PressureStatusSchema: z.ZodObject<{
         throttled: "throttled";
         suspending: "suspending";
     }>;
+    step: z.ZodOptional<z.ZodNumber>;
     profile: z.ZodEnum<{
         normal: "normal";
         gentle: "gentle";
@@ -577,6 +582,7 @@ export declare const PressureStatusSchema: z.ZodObject<{
         pid: z.ZodNumber;
         seconds: z.ZodNumber;
     }, z.core.$strip>>;
+    cpuPercent: z.ZodOptional<z.ZodNumber>;
     pcLow: z.ZodBoolean;
     lastAction: z.ZodString;
     updatedAt: z.ZodString;
@@ -645,6 +651,7 @@ export declare const VpnStatusSchema: z.ZodObject<{
     }>;
     message: z.ZodString;
     killSwitch: z.ZodBoolean;
+    killSwitchHeld: z.ZodOptional<z.ZodBoolean>;
     server: z.ZodOptional<z.ZodString>;
     publicIp: z.ZodOptional<z.ZodString>;
     updatedAt: z.ZodString;

package/dist/shared/channel/schema.js

@@ -100,20 +100,26 @@ export const GuestRequestSchema = z.discriminatedUnion('kind', [
         id: IdSchema,
         reason: Text(300),
         seconds: z.number().int().min(10).max(300),
+        /** "severe": the PC is nearly out of memory; builds go to the governor's last step at once. */
+        level: z.enum(['slow', 'severe']).optional(),
         createdAt: TimeSchema,
     }),
 ]);
 /** C:\AgentData\run\pressure.json: what the memory governor in the sandbox is doing (guest-written, capped). */
 export const PressureStatusSchema = z.object({
     level: z.enum(['ok', 'throttled', 'suspending']),
+    /** The governor's dial, 0 (nothing wrong) to 4 (one compiler at a time). */
+    step: z.number().int().min(0).max(4).optional(),
     profile: z.enum(['normal', 'gentle']),
     /** Share of the sandbox's RAM still free and of its commit limit in use (percent). */
     ramFreePercent: z.number().int().min(0).max(100),
     commitPercent: z.number().int().min(0).max(100),
     /** Programs running at lower priority because of it. */
     lowered: z.number().int().min(0).max(1024),
-    /** Programs paused right now (name, process id, seconds left). */
+    /** Compilers waiting their turn right now (name, process id, seconds until they may go on). */
     paused: z.array(z.object({ name: Text(64), pid: z.number().int(), seconds: z.number().int().min(0).max(60) })).max(8),
+    /** The CPU share the compilers get together (percent; 100 = no cap). */
+    cpuPercent: z.number().int().min(0).max(100).optional(),
     /** The PC itself asked for slowing down (its memory or CPU is low). */
     pcLow: z.boolean(),
     lastAction: Text(300),
@@ -163,6 +169,8 @@ export const VpnStatusSchema = z.object({
     state: z.enum(['off', 'starting', 'up', 'failed']),
     message: Text(2000),
     killSwitch: z.boolean(),
+    /** A direct connection was tried after the kill switch was applied: false = it still got out. */
+    killSwitchHeld: z.boolean().optional(),
     /** The server's name, e.g. uk2201.nordvpn.com. */
     server: Text(128).optional(),
     /** What the sandbox's traffic looks like from outside, once the tunnel is up. */

package/dist/shared/channel/secrets.d.ts

@@ -9,6 +9,7 @@ export declare const SecretsFileSchema: z.ZodObject<{
         password: z.ZodString;
     }, z.core.$strict>>;
     wireguardConfig: z.ZodOptional<z.ZodString>;
+    githubToken: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type SecretsFile = z.output<typeof SecretsFileSchema>;
 interface WithHarnesses {

package/dist/shared/channel/secrets.js

@@ -4,6 +4,7 @@
 // sandbox may change run\, never this folder. The agent in the sandbox can still read what it was given (its own
 // environment, its login): that is inherent. Every part is optional.
 import { z } from 'zod';
+import { GithubTokenSchema } from '../github/index.js';
 const Environment = z.record(z.string().max(256), z.string().max(65536));
 export const SecretsFileSchema = z.strictObject({
     /** The agent the sandbox booted with: its harness environment. */
@@ -25,6 +26,8 @@ export const SecretsFileSchema = z.strictObject({
         .min(1)
         .max(32 * 1024)
         .optional(),
+    /** The GitHub token you saved for sandboxes (github.shareToken), only with git access "full". */
+    githubToken: GithubTokenSchema.optional(),
 });
 /** The environment a harness gets: its own, then the values that travelled in the secrets file. */
 const withEnvironment = (harness, environment) => (environment ? { ...harness, environment: { ...harness.environment, ...environment } } : harness);

package/dist/shared/github/index.d.ts

@@ -0,0 +1 @@
+export { GITHUB_TOKEN_KINDS, GithubTokenSchema, ghLoginCommand, ghOutputText, ghSetupGitCommand, githubTokenKind, githubTokenProblem, type GhCommand, type GithubTokenKind, } from './token.js';

package/dist/shared/github/index.js

@@ -0,0 +1,2 @@
+// A GitHub token for sandboxes: its rules and the gh commands that use it (host and guest).
+export { GITHUB_TOKEN_KINDS, GithubTokenSchema, ghLoginCommand, ghOutputText, ghSetupGitCommand, githubTokenKind, githubTokenProblem, } from './token.js';

package/dist/shared/github/token.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+export declare const GITHUB_TOKEN_KINDS: readonly ["fine-grained", "classic"];
+export type GithubTokenKind = (typeof GITHUB_TOKEN_KINDS)[number];
+/** The token in the secrets file: the same limits as on the PC. */
+export declare const GithubTokenSchema: z.ZodString;
+/** What kind of personal access token this is, from its prefix (null: not one). */
+export declare function githubTokenKind(token: string): GithubTokenKind | null;
+/** Why this text cannot be saved as the sandbox token (fixed texts: never the token), or null when it can. */
+export declare function githubTokenProblem(token: string): {
+    message: string;
+    fix: string;
+} | null;
+/** One gh run: the program, its arguments, what goes on its stdin, and its environment. */
+export interface GhCommand {
+    readonly file: string;
+    readonly args: readonly string[];
+    readonly input?: string;
+    readonly env: Readonly<Record<string, string>>;
+}
+/**
+ * `gh auth login` with the token on stdin, never in the arguments (other processes can read those). The login is
+ * kept as a file in configDir (--insecure-storage, rather than Credential Manager), which is on the sandbox's own disk
+ * and gone with it.
+ */
+export declare function ghLoginCommand(ghExe: string, configDir: string, token: string, base: Readonly<Record<string, string | undefined>>): GhCommand;
+/** `gh auth setup-git`: https git to github.com asks gh for the login. */
+export declare function ghSetupGitCommand(ghExe: string, configDir: string, base: Readonly<Record<string, string | undefined>>): GhCommand;
+/** Text from gh, safe to log: the token blanked out should it ever appear, and kept short. */
+export declare function ghOutputText(text: string, token: string): string;

package/dist/shared/github/token.js

@@ -0,0 +1,89 @@
+// A GitHub token for sandboxes (github.shareToken): the rules for one (both sides check them) and the gh commands the
+// sandbox runs with it. Pure. The token is never part of a message, an argument or a log line: gh reads it on stdin.
+import { z } from 'zod';
+export const GITHUB_TOKEN_KINDS = ['fine-grained', 'classic'];
+const MIN_LENGTH = 20;
+const MAX_LENGTH = 255;
+/** Printable ASCII without spaces: what GitHub's tokens are made of. */
+const PRINTABLE = /^[\x21-\x7e]+$/;
+/** The token in the secrets file: the same limits as on the PC. */
+export const GithubTokenSchema = z.string().min(MIN_LENGTH).max(MAX_LENGTH).regex(PRINTABLE);
+/** Prefixes of tokens that are not personal access tokens (OAuth from `gh auth login`, app and refresh tokens). */
+const OTHER_TOKENS = {
+    gho_: 'This is an OAuth token (from gh auth login or gh auth token), which can reach everything your account can.',
+    ghu_: 'This is a GitHub App user token, not a personal access token.',
+    ghs_: 'This is a GitHub App installation token, not a personal access token.',
+    ghr_: 'This is a refresh token, not a personal access token.',
+};
+const CREATE_FINE_GRAINED = 'Create a fine-grained token at https://github.com/settings/personal-access-tokens/new with only the repositories and permissions the agent needs, then run: sandbox github login';
+/** What kind of personal access token this is, from its prefix (null: not one). */
+export function githubTokenKind(token) {
+    if (token.startsWith('github_pat_'))
+        return 'fine-grained';
+    if (token.startsWith('ghp_'))
+        return 'classic';
+    return null;
+}
+/** Why this text cannot be saved as the sandbox token (fixed texts: never the token), or null when it can. */
+export function githubTokenProblem(token) {
+    if (!token)
+        return { message: 'No token was typed.', fix: CREATE_FINE_GRAINED };
+    if (!PRINTABLE.test(token))
+        return {
+            message: 'The token may not contain spaces, line breaks or other special characters.',
+            fix: 'Copy the token again from GitHub (only the token itself) and run: sandbox github login',
+        };
+    if (token.length < MIN_LENGTH || token.length > MAX_LENGTH)
+        return {
+            message: 'That is not the length of a GitHub token.',
+            fix: 'Copy the whole token again from GitHub and run: sandbox github login',
+        };
+    const other = Object.keys(OTHER_TOKENS).find((p) => token.startsWith(p));
+    if (other)
+        return { message: OTHER_TOKENS[other], fix: CREATE_FINE_GRAINED };
+    if (!githubTokenKind(token))
+        return {
+            message: 'That is not a GitHub personal access token (they start with github_pat_ or ghp_).',
+            fix: CREATE_FINE_GRAINED,
+        };
+    return null;
+}
+/** Variables that would make gh use another token than the one it is given (gh refuses --with-token with them). */
+const TOKEN_VARIABLES = /^(GH_TOKEN|GITHUB_TOKEN|GH_ENTERPRISE_TOKEN|GITHUB_ENTERPRISE_TOKEN)$/i;
+const ghEnv = (base, configDir) => ({
+    ...Object.fromEntries(Object.entries(base).filter((e) => e[1] !== undefined && !TOKEN_VARIABLES.test(e[0]))),
+    GH_CONFIG_DIR: configDir,
+    GH_PROMPT_DISABLED: '1',
+    GH_NO_UPDATE_NOTIFIER: '1',
+});
+/**
+ * `gh auth login` with the token on stdin, never in the arguments (other processes can read those). The login is
+ * kept as a file in configDir (--insecure-storage, rather than Credential Manager), which is on the sandbox's own disk
+ * and gone with it.
+ */
+export function ghLoginCommand(ghExe, configDir, token, base) {
+    return {
+        file: ghExe,
+        args: [
+            'auth',
+            'login',
+            '--hostname',
+            'github.com',
+            '--git-protocol',
+            'https',
+            '--insecure-storage',
+            '--with-token',
+        ],
+        input: token + '\n',
+        env: ghEnv(base, configDir),
+    };
+}
+/** `gh auth setup-git`: https git to github.com asks gh for the login. */
+export function ghSetupGitCommand(ghExe, configDir, base) {
+    return { file: ghExe, args: ['auth', 'setup-git', '--hostname', 'github.com'], env: ghEnv(base, configDir) };
+}
+/** Text from gh, safe to log: the token blanked out should it ever appear, and kept short. */
+export function ghOutputText(text, token) {
+    const clean = token ? text.split(token).join('***') : text;
+    return clean.replace(/\s+/g, ' ').trim().slice(0, 300);
+}

package/dist/shared/memory/policy.d.ts

@@ -1,16 +1,27 @@
 export type LoadProfile = 'normal' | 'gentle';
-/** The guest governor: when memory inside the sandbox counts as under pressure, and when it has recovered. */
-export interface GuestThresholds {
-    /** Pressure starts when available RAM is below this share of the sandbox's RAM (percent)... */
-    readonly enterAvailablePercent: number;
-    /** ...or commit is above this share of its limit. */
-    readonly enterCommitPercent: number;
-    /** Pressure ends only when available RAM is above this and commit is below the next, for `calmSamples` in a row. */
-    readonly exitAvailablePercent: number;
-    readonly exitCommitPercent: number;
-    readonly calmSamples: number;
+/**
+ * One step of the guest governor's dial. It turns up when available RAM falls below `availablePercent` of the
+ * sandbox's RAM, commit rises above `commitPercent` of its limit, or (from step 3) the commit would reach its limit
+ * within `secondsToLimit` at the rate it is growing. It turns down one step after `calmSamples` samples in a row that
+ * are clear of the step by the margins below.
+ */
+export interface DialStep {
+    readonly availablePercent: number;
+    readonly commitPercent: number;
+    readonly secondsToLimit?: number;
 }
-export declare const GUEST_THRESHOLDS: Readonly<Record<LoadProfile, GuestThresholds>>;
+/** Steps 1 to 4 of the dial, per profile (index 0 is step 1). The gentle profile (vGPU on) turns earlier. */
+export declare const DIAL_STEPS: Readonly<Record<LoadProfile, readonly DialStep[]>>;
+/** How clear of a step a sample must be to count as calm: this much more RAM free and this much less commit. */
+export declare const DIAL_EXIT_MARGIN: {
+    readonly availablePercent: 5;
+    readonly commitPercent: 4;
+};
+export declare const DIAL_CALM_SAMPLES = 3;
+/** The CPU share (percent of the sandbox) the compilers get together at each step; 100 = no cap. */
+export declare const DIAL_CPU_RATE: readonly number[];
+/** How many of the compilers running may go on at each step (the rest wait their turn), as a share of them. */
+export declare function compilersAllowed(step: number, running: number): number;
 /** The PC watchdog: when this PC itself is low. */
 export interface HostThresholds {
     /** Low when available RAM is below max(this, availableShare of total RAM)... */
@@ -32,7 +43,17 @@ export declare const HOST_THRESHOLDS: Readonly<Record<LoadProfile, HostThreshold
 export declare function gentleCpuLimit(cpuLimit: 'none' | number): number;
 /** The CPU cap the sandbox runs with (percent; null = none) for a profile. */
 export declare function effectiveCpuLimit(cpuLimit: 'none' | number, profile: LoadProfile): number | null;
-/** Cargo jobs that fit the memory (about 4 GB per rustc) and the CPUs, fewer when several agent sessions build. */
+/**
+ * The build budget of the whole sandbox: how many compile jobs fit together (about 3 GB each after 6 GB for Windows,
+ * the agents and their tools), never more than the processors the sandbox may use. The governor slows them down when
+ * memory runs short anyway; this keeps builds from starting far more than fits.
+ */
+export declare function buildJobs(cpus: number, memoryGb: number): number;
+/** Links that may run at once in the whole sandbox ("auto"): one per 3 GB after 6 GB, 2 to 8. */
+export declare function linkSlotsFor(memoryGb: number): number;
+/** The processors the sandbox's programs may use with a CPU cap of `percent` (affinity): at least 2. */
+export declare function usableCpus(cpus: number, percent: number | null): number;
+/** Cargo jobs for one more agent session: what fits the memory and CPUs, shared with the sessions already building. */
 export declare function cargoJobs(cpus: number, memoryGb: number, sessions: number): number;
 /** The most heavy compilers (rustc, clippy-driver, link ...) that run at once in the agents' job: only with vGPU on. */
 export declare function maxCompilers(cpus: number, profile: LoadProfile): number | null;