windows-development-sandbox 1.9.0 → 1.11.3

package/dist/selftest/health.test.js

@@ -5,6 +5,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { ALL_CHECKS } from '../cli/commands/repair/checks/index.js';
 import { proxyProblem } from '../cli/commands/repair/checks/network.js';
+import { healthPage, ioEvents, summaryText as featureSummaryText, } from '../app/features/health/index.js';
+import { fakeIO } from '../app/kernel/index.js';
+import { runDefinition } from '../app/registry.js';
+import { menuView } from '../cli/menu/render-view.js';
 import { HealthRun, summarize } from '../cli/commands/repair/engine.js';
 import { logText, writeRepairLog } from '../cli/commands/repair/log.js';
 import { HealthPrinter, summaryText } from '../cli/commands/repair/printer.js';
@@ -455,6 +459,72 @@ function backups(t) {
     t.equal(found[0].label, '1.4.0 to 1.5.0 at 2026-10-14 09:30:12', 'a backup is labelled with its versions and time');
     t.equal(lineDiff('{\n  "a": 1,\n  "x": 3\n}', '{\n  "a": 2,\n  "x": 3\n}'), ['- "a": 1,', '+ "a": 2,'], 'the difference shows the lines only in one file');
 }
+/** The shared core: the same run as the menu and the web use, the saved results, and the health page. */
+async function sharedCore(t) {
+    t.section('the shared core');
+    const bad = (plan, over = {}) => ({
+        status: 'needs-you',
+        detail: 'broken',
+        plan,
+        means: 'it hurts',
+        ...over,
+    });
+    const cracks = [];
+    const three = [
+        check('p1', 'This PC', { name: 'Windows' }),
+        check('p2', 'Data folder', {
+            name: 'Cracks',
+            run: () => (cracks.length ? { status: 'ok', detail: 'whole' } : bad('mend the cracks', { fix: undefined })),
+            fix: () => {
+                cracks.push('mended');
+                return { done: 'mended the cracks' };
+            },
+        }),
+        check('p3', 'Network', {
+            name: 'GitHub',
+            run: () => ({ status: 'warn', detail: 'no answer', fix: 'check your VPN' }),
+        }),
+    ];
+    const fake = fakeIO();
+    await runHealth(fakeEnv(t, 'events'), ioEvents(fake.io), { yes: true, ask: false, question: () => '' }, three, () => Promise.resolve(true));
+    const logged = fake.seen.logs.map((l) => l.text).join('\n');
+    t.includes(logged, '  [ok] Windows: p1 is fine', 'ioEvents writes a line per result, like the printer');
+    t.includes(logged, 'What it means: it hurts', 'ioEvents says what a problem means');
+    t.includes(logged, 'Fix: sandbox repair will mend the cracks', 'ioEvents says what repair would do');
+    t.includes(logged, 'Repair will change:', 'ioEvents lists the changes before they are made');
+    t.includes(logged, '[fixed] Cracks: mended the cracks', 'ioEvents reports a fix on its own line');
+    t.equal(featureSummaryText({ total: 9, ok: 6, fixed: 1, warn: 1, needsYou: 1, skipped: 0, fixable: 0 }), '6 ok, 1 fixed, 1 needs you, 1 warning', 'summaryText moved to the feature and reads the same');
+    t.equal(featureSummaryText({ total: 3, ok: 0, fixed: 0, warn: 0, needsYou: 2, skipped: 1, fixable: 0 }), '0 ok, 2 need you, 1 skipped', 'summaryText plurals (feature)');
+    const saved = {
+        at: '2026-10-15T09:30:12.000Z',
+        mode: 'check',
+        checks: [{ id: 'p1', group: 'This PC', name: 'Windows', status: 'ok', detail: 'fine', fixable: false }],
+        summary: { total: 1, ok: 1, fixed: 0, warn: 0, needsYou: 0, skipped: 0, fixable: 0 },
+        details: [['Config file', 'valid']],
+        setup: { checks: [{ name: 'Edition', status: 'ok', detail: 'Pro' }], canEnable: false, error: null },
+        log: null,
+    };
+    const storage = t.dir('health', 'saved', 'storage');
+    const ctx = { storageRoot: storage };
+    const none = await runDefinition('health.last', ctx, {}, fakeIO().io);
+    t.equal(none, { last: null }, 'nothing saved yet: no results');
+    t.writeJson(path.join(storage, 'health', 'last.json'), saved);
+    const read = await runDefinition('health.last', ctx, {}, fakeIO().io);
+    t.equal(read, { last: saved }, 'a check is saved and read back by health.last');
+    t.write(path.join(storage, 'health', 'last.json'), '{ this is not json');
+    t.equal(await runDefinition('health.last', ctx, {}, fakeIO().io), { last: null }, 'a damaged results file reads as nothing saved');
+    const empty = healthPage({ last: null });
+    const emptyIds = empty.sections.flatMap((s) => (s.items ?? []).map((i) => i.id));
+    t.equal(emptyIds, ['health:check', 'repair:run'], 'before any check the page offers the check and the repair');
+    t.equal(menuView(empty, { category: 'health', refresh: false }).enterLabel('health', 'repair:run'), 'check and fix', 'Enter on the repair row says check and fix');
+    const page = healthPage({ last: saved });
+    const ids = page.sections.flatMap((s) => (s.items ?? []).map((i) => i.id));
+    t.check(['doctor:0', 'repair:0', 'setup:0'].every((id) => ids.includes(id)), 'with results the page lists the doctor, repair and setup rows', ids.join(', '));
+    const keys = menuView(page, { category: 'health', refresh: false }).actions.map((a) => a.key);
+    t.equal(keys, ['f', 'l'], 'the health keys are f and l (e only when Windows Sandbox can be turned on)');
+    const canEnable = healthPage({ last: { ...saved, setup: { ...saved.setup, canEnable: true } } });
+    t.equal(menuView(canEnable, { category: 'health', refresh: false }).actions.map((a) => a.key), ['f', 'l', 'e'], 'e turns Windows Sandbox on when the setup says it can be');
+}
 export const healthSuite = {
     name: 'health',
     title: 'doctor and repair (engine, printer, log, the install, stale state, permissions, settings backups)',
@@ -466,5 +536,6 @@ export const healthSuite = {
         await staleState(t);
         parsing(t);
         backups(t);
+        await sharedCore(t);
     },
 };

package/dist/selftest/heavy-load.test.js

@@ -8,11 +8,13 @@ import { DEFAULTS } from '../core/config/index.js';
 import { isWin } from '../core/util/index.js';
 import { SYSTEM } from '../shared/system.js';
 import { GuestRequestSchema, PressureStatusSchema } from '../shared/channel/index.js';
-import { GUEST_THRESHOLDS, HOST_THRESHOLDS, cargoJobs, effectiveCpuLimit, gentleCpuLimit, } from '../shared/memory/index.js';
-import { agentMemoryLimitMb, decideMemory, memoryNote, resolveMemoryMb } from '../host/launch/index.js';
+import { compilersAllowed, DIAL_CALM_SAMPLES, DIAL_STEPS, HOST_THRESHOLDS, buildJobs, cargoJobs, linkSlotsFor, usableCpus, effectiveCpuLimit, gentleCpuLimit, maxCompilers, } from '../shared/memory/index.js';
+import { cappedMemoryMb, decideMemory, memoryNote, residentCapMb, residentNote, resolveMemoryMb, } from '../host/launch/index.js';
 import { vgpuWarning, GENTLE_NOTE } from '../host/launch/risk-notes.js';
-import { bugcheckCode, cpuPercentBetween, explainStop, findDumps, findingLines, freezeLine, hostPressure, lowReason, pageFileRisk, parseHostMemory, crashReportText, watchdogStep, WATCHDOG_START, } from '../host/life/index.js';
-import { canLower, canPause, decide, GovernorCore, INITIAL_STATE, } from '../guest/governor/index.js';
+import { bugcheckCode, cpuPercentBetween, explainStop, findDumps, findingLines, freezeLine, hostPressure, lowReason, severeHost, pageFileRisk, parseHostMemory, crashReportText, watchdogStep, WATCHDOG_START, } from '../host/life/index.js';
+// The pure governor files only: governor.ts loads the guest runtime (session.json), which exists only in a sandbox.
+import { canLower, canPause, decide, INITIAL_STATE, ROTATE_MS, } from '../guest/governor/decide.js';
+import { GovernorCore } from '../guest/governor/core.js';
 const GB = 1024;
 const MB_SANDBOX = DEFAULTS.sandbox;
 const proc = (pid, name, mb, prio = 'normal') => ({
@@ -59,17 +61,22 @@ export const heavyLoadSuite = {
             refused = String(e instanceof Error ? e.message : e);
         }
         t.check(refused.includes('RAM plus paging file'), 'too little commit refuses with the real reason', refused);
-        t.check(resolveMemoryMb({ ...MB_SANDBOX, memoryMb: 5000 }, 1, 1, 1) === 5000, 'a fixed memoryMb is never changed');
-        t.section("the agents' memory limit");
-        t.check(agentMemoryLimitMb(32768, 'auto') === 32768 - 3276, 'auto: sandbox memory minus 10 %');
-        t.check(agentMemoryLimitMb(8192, 'auto') === 8192 - 2048, 'auto: at least 2 GB of headroom');
-        t.check(agentMemoryLimitMb(4096, 'auto') === 2048, 'a small sandbox keeps at least half for agents');
-        t.check(agentMemoryLimitMb(16384, 1000) === 15384 && agentMemoryLimitMb(16384, 'none') === null, 'a number, or none');
+        t.check(resolveMemoryMb({ ...MB_SANDBOX, memoryMb: 5000 }, 1, 1, 1) === 5000, 'a fixed memoryMb is taken as asked (the resident cap below is the only limit on it)');
+        t.check(residentCapMb({ ...MB_SANDBOX, vGpu: false }, 32768) === 24576 &&
+            residentCapMb({ ...MB_SANDBOX, vGpu: true }, 32768) === 22528 &&
+            residentCapMb({ ...MB_SANDBOX, vGpu: false }, 65536) === 49152, 'what this PC can keep in RAM for the sandbox: its RAM minus max(reserve, 25 %), 2 GB more with vGPU');
+        t.check(cappedMemoryMb(32768, { ...MB_SANDBOX, vGpu: true }, 32768) === 22528 &&
+            cappedMemoryMb(16384, { ...MB_SANDBOX, vGpu: true }, 32768) === 16384 &&
+            cappedMemoryMb(8192, MB_SANDBOX, 6144) === 8192, 'a fixed memoryMb above it is lowered to it (never on a PC too small to keep 4 GB)');
+        t.check(residentNote(32768, 22528)?.includes('gets 22528 MB') === true && residentNote(16384, 16384) === null, 'and the launch says so');
+        t.check(decideMemory({ ...MB_SANDBOX, maxMemoryPercent: 100, maxMemoryMb: 65536, reserveHostMb: 1024 }, 32000, 32768, null).limitedBy === 'resident', '"auto" never goes above it either');
+        t.section("the agents' job backstop");
         const gen = await f.launch({}, { args: ['--version'] });
         const session = JSON.parse(fs.readFileSync(gen.sessionPath, 'utf8'));
-        t.check(session.agentMemoryLimitMb === agentMemoryLimitMb(gen.memoryMb, 'auto') &&
+        t.check(session.agentBackstop === 'auto' &&
+            session.agentMemoryLimitMb === undefined &&
             session.pressureResponse === true &&
-            session.loadProfile === 'normal', 'session.json carries the limit, the governor switch and the profile (all on by default)', JSON.stringify(session.agentMemoryLimitMb));
+            session.loadProfile === 'normal', 'session.json carries the backstop setting (no limit from RAM any more), the governor switch and the profile', JSON.stringify(session.agentBackstop));
         const vgpuConfig = f.makeConfig();
         vgpuConfig.sandbox.vGpu = true;
         const gentle = await f.launch({}, { args: ['--version'], config: vgpuConfig });
@@ -82,9 +89,13 @@ export const heavyLoadSuite = {
         t.check(cargoJobs(16, 32, 1) === 4, '16 CPUs, 32 GB: 4 jobs');
         t.check(cargoJobs(16, 8, 1) === 2 && cargoJobs(16, 3, 1) === 1, 'about 4 GB per job');
         t.check(cargoJobs(16, 32, 3) === 2 && cargoJobs(16, 32, 8) === 1, 'fewer when several sessions build');
+        t.check(cargoJobs(32, 32, 1) === 8, '32 processors, 32 GB: 8 jobs for one session');
+        t.check(buildJobs(32, 32) === 8 && buildJobs(32, 64) === 19 && buildJobs(4, 64) === 4 && buildJobs(16, 4) === 2, 'the build budget: 3 GB per job after 6 GB, never more than the processors, at least 2');
+        t.check(linkSlotsFor(32) === 8 && linkSlotsFor(16) === 3 && linkSlotsFor(8) === 2 && linkSlotsFor(128) === 8, 'links at once ("auto"): one per 3 GB after 6 GB, 2 to 8');
+        t.check(usableCpus(32, 80) === 25 && usableCpus(32, null) === 32 && usableCpus(4, 10) === 2 && usableCpus(8, 100) === 8, 'the processors programs see follow the CPU cap (at least 2)');
         t.section('the governor: which programs');
         t.check(canPause('rustc.exe') && canPause('link.exe') && canPause('ld.lld.exe'), 'compilers and linkers may be paused');
-        t.check(!canPause('node.exe') && canLower('node.exe') && canLower('MSBuild.exe'), 'build tools are only slowed down');
+        t.check(!canPause('node.exe') && !canLower('node.exe') && canLower('MSBuild.exe'), 'build tools are only slowed down');
         t.check([
             'claude.exe',
             'codex.exe',
@@ -95,65 +106,106 @@ export const heavyLoadSuite = {
             'svchost.exe',
             'memgov.exe',
         ].every((n) => !canLower(n) && !canPause(n)), 'agents, shells, ptyhost, git and system programs are never touched');
-        t.section('the governor: thresholds and hysteresis');
-        const normal = GUEST_THRESHOLDS.normal;
+        t.section('the governor: the dial turns up in steps, down slowly');
         const procs = [
             proc(1, 'rustc.exe', 2800),
             proc(2, 'rustc.exe', 2000),
             proc(3, 'claude.exe', 900),
             proc(4, 'link.exe', 500),
         ];
-        const calm = decide(INITIAL_STATE, sample(50, 50, procs), 1000, normal, 'normal');
-        t.check(calm.level === 'ok' && calm.actions.length === 0, '50 % free: nothing happens');
-        const edge = decide(INITIAL_STATE, sample(9, 91, procs), 1000, normal, 'normal');
-        t.check(edge.level === 'ok', '9 % free and 91 % commit are still fine (limits: 8 % and 92 %)');
-        const low = decide(INITIAL_STATE, sample(7, 50, procs), 1000, normal, 'normal');
-        t.check(low.level === 'throttled' &&
-            low.actions
-                .filter((a) => a.kind === 'priority')
-                .map((a) => a.kind === 'priority' && a.pid)
-                .join() === '1,2,4', '7 % free: the compilers go below normal, the agent does not');
-        const lowCommit = decide(INITIAL_STATE, sample(50, 93, procs), 1000, normal, 'normal');
-        t.check(lowCommit.level === 'throttled', 'commit above 92 % counts too');
-        let s2 = INITIAL_STATE;
-        const kinds = [];
-        for (let i = 0; i < 6; i++) {
-            const d = decide(s2, sample(5, 50, procs), i * 2000, normal, 'normal');
-            s2 = d.state;
-            kinds.push(d.level);
+        const of = (d, kind) => d.actions.filter((a) => a.kind === kind);
+        const pids = (actions) => actions
+            .map((a) => ('pid' in a ? a.pid : 0))
+            .sort()
+            .join();
+        const calm = decide(INITIAL_STATE, sample(50, 50, procs), 1000, 'normal');
+        t.check(calm.state.step === 0 && calm.level === 'ok' && calm.actions.length === 0, '50 % free: nothing happens');
+        t.check(decide(INITIAL_STATE, sample(16, 79, procs), 1000, 'normal').state.step === 0, '16 % free and 79 % commit are fine (step 1 starts at 15 % and 80 %)');
+        const one = decide(INITIAL_STATE, sample(14, 50, procs), 1000, 'normal');
+        t.check(one.state.step === 1 &&
+            of(one, 'priority').every((a) => a.kind === 'priority' && a.to === 'below') &&
+            pids(of(one, 'priority')) === '1,2,4' &&
+            pids(of(one, 'memory')) === '1,2,4' &&
+            of(one, 'hold').length === 0 &&
+            of(one, 'cpu').length === 0, 'step 1: build programs get lower CPU and memory priority, nothing waits, the agent is untouched');
+        const two = decide(INITIAL_STATE, sample(9, 50, procs), 1000, 'normal');
+        t.check(two.state.step === 2 &&
+            of(two, 'priority').every((a) => a.kind === 'priority' && a.to === 'idle') &&
+            pids(of(two, 'throttle')) === '1,2,4' &&
+            of(two, 'cpu').some((a) => a.kind === 'cpu' && a.percent === 60) &&
+            of(two, 'hold').length === 1, 'step 2: idle priority, compilers share 60 % of the CPU, 2 of 3 compilers go on');
+        const three = decide(INITIAL_STATE, sample(5, 50, procs), 1000, 'normal');
+        t.check(three.state.step === 3 &&
+            three.level === 'suspending' &&
+            of(three, 'cpu').some((a) => a.kind === 'cpu' && a.percent === 35) &&
+            of(three, 'hold').length === 2 &&
+            pids(of(three, 'trim')) === pids(of(three, 'hold')), 'step 3: 35 % CPU, one compiler goes on, the waiting ones are trimmed to the paging file');
+        t.check(decide(INITIAL_STATE, sample(50, 98, procs), 1000, 'normal').state.step === 4, 'commit above 97 % is step 4');
+        // A build that grabs 2 GB in two seconds while most memory is free is normal: no false alarm (it paused compilers).
+        const burst = decide({ ...INITIAL_STATE, lastCommitMb: 4000, lastAt: 1000 }, sample(50, 60, procs), 3000, 'normal');
+        t.check(burst.state.step === 0, 'a burst of commit while most memory is free does not turn the dial', 'step ' + burst.state.step);
+        const growing = decide({ ...INITIAL_STATE, lastCommitMb: 8400, lastAt: 1000, growth: 200 }, sample(50, 88, procs), 3000, 'normal');
+        t.check(growing.state.step === 4, 'commit near its limit that keeps growing (about 6 s left) turns the dial up before it gets there', 'step ' + growing.state.step);
+        const everything = [one, two, three, growing].flatMap((d) => d.actions);
+        t.check(everything.every((a) => !('pid' in a) || a.pid !== 3), 'the agent is never slowed, held or trimmed at any step');
+        // Hysteresis: step 2 holds while memory is between its entry (10 %) and its exit (15 %).
+        let h = decide(INITIAL_STATE, sample(9, 50, procs), 0, 'normal').state;
+        h = decide(h, sample(12, 50, procs), 2000, 'normal').state;
+        t.check(h.step === 2, 'between the entry and the exit of a step it stays (no flapping)');
+        const steps = [];
+        for (let i = 0; i < 2 * DIAL_CALM_SAMPLES; i++) {
+            h = decide(h, sample(40, 40, procs), 4000 + i * 2000, 'normal').state;
+            steps.push(h.step);
         }
-        t.check(kinds[0] === 'throttled' && kinds.includes('suspending'), 'throttled first, paused later: ' + kinds.join());
-        const oneStep = decide(INITIAL_STATE, sample(5, 50, procs), 0, normal, 'normal');
-        t.check(!oneStep.actions.some((a) => a.kind === 'pause'), 'never paused on the first sample');
-        // Hysteresis: 10 % free is above the 8 % entry but below the 12 % exit: still under pressure.
-        let h = decide(INITIAL_STATE, sample(5, 50, procs), 0, normal, 'normal').state;
-        h = decide(h, sample(10, 50, procs), 2000, normal, 'normal').state;
-        t.check(h.pressure, 'between the entry and exit limits it stays under pressure (no flapping)');
-        for (let i = 0; i < normal.calmSamples; i++)
-            h = decide(h, sample(30, 50, procs), 4000 + i * 2000, normal, 'normal').state;
-        t.check(!h.pressure, 'ends only after ' + normal.calmSamples + ' calm samples');
-        const back = decide({ ...INITIAL_STATE, pressure: true, calm: normal.calmSamples - 1, lowered: { 1: 'below' } }, sample(30, 50, [proc(1, 'rustc.exe', 2800, 'below')]), 9000, normal, 'normal');
-        t.check(back.level === 'ok' &&
-            back.actions.length === 1 &&
-            back.actions[0].kind === 'priority' &&
-            back.actions[0].to === 'normal', 'when it ends the compilers get their normal priority back');
-        t.check(decide(INITIAL_STATE, sample(5, 50, [proc(1, 'rustc.exe', 100)]), 0, normal, 'normal').actions.length === 1 &&
-            !decide({ ...INITIAL_STATE, samples: 10 }, sample(5, 50, [proc(1, 'rustc.exe', 100)]), 99999, normal, 'normal').actions.some((a) => a.kind === 'pause'), 'a small compiler (under 300 MB) is never worth pausing');
-        const hostAsked = decide({ ...INITIAL_STATE, hostUntil: 5000 }, sample(60, 40, procs), 1000, normal, 'normal');
-        t.check(hostAsked.level === 'throttled', 'the PC asking for it counts as pressure while the request lasts');
+        t.check(steps.join() === '2,2,1,1,1,0', 'it turns down one step after ' + DIAL_CALM_SAMPLES + ' calm samples: ' + steps.join());
+        const back = decide({ ...INITIAL_STATE, step: 1, calm: DIAL_CALM_SAMPLES - 1, lowered: { 1: 'below' }, memLow: [1], cpuRate: 100 }, sample(40, 40, [proc(1, 'rustc.exe', 2800, 'below')]), 9000, 'normal');
+        t.check(back.state.step === 0 &&
+            of(back, 'priority').some((a) => a.kind === 'priority' && a.to === 'normal') &&
+            of(back, 'memory').some((a) => a.kind === 'memory' && !a.low), 'at step 0 the compilers get their normal CPU and memory priority back');
+        const uncapped = decide({ ...INITIAL_STATE, step: 2, calm: DIAL_CALM_SAMPLES - 1, cpuRate: 60 }, sample(40, 40, procs), 9000, 'normal');
+        t.check(uncapped.state.step === 1 && of(uncapped, 'cpu').some((a) => a.kind === 'cpu' && a.percent === 100), 'the CPU cap is lifted when the dial goes below step 2');
+        const hostAsked = decide({ ...INITIAL_STATE, hostUntil: 5000, hostStep: 2 }, sample(60, 40, procs), 1000, 'normal');
+        t.check(hostAsked.state.step >= 2, 'the PC asking for it turns the dial to at least step 2 while it lasts');
+        const turnA = of(decide(INITIAL_STATE, sample(5, 50, procs), 0, 'normal'), 'hold');
+        const turnB = of(decide(INITIAL_STATE, sample(5, 50, procs), ROTATE_MS, 'normal'), 'hold');
+        t.check(pids(turnA) !== pids(turnB), 'who waits changes over time, so no compiler waits for ever');
+        t.check(compilersAllowed(2, 10) === 6 && compilersAllowed(3, 10) === 4 && compilersAllowed(4, 10) === 1, 'how many compilers go on at steps 2, 3 and 4');
         t.section('the gentle profile (vGPU on)');
-        const gentleT = GUEST_THRESHOLDS.gentle;
-        t.check(gentleT.enterAvailablePercent === 15 && normal.enterAvailablePercent === 8, 'it acts at 15 % free instead of 8 %');
-        const g = decide(INITIAL_STATE, sample(50, 50, procs), 0, gentleT, 'gentle');
-        t.check(g.level === 'ok' &&
+        t.check(DIAL_STEPS.gentle[0].availablePercent > DIAL_STEPS.normal[0].availablePercent &&
+            DIAL_STEPS.gentle[0].commitPercent < DIAL_STEPS.normal[0].commitPercent, 'every step starts earlier');
+        const g = decide(INITIAL_STATE, sample(50, 50, procs), 0, 'gentle');
+        t.check(g.state.step === 0 &&
             g.actions.length === 3 &&
-            g.actions.every((a) => a.kind === 'priority' && a.to === 'below' && a.pid !== 3), 'compilers start below normal even with plenty of memory (the agent does not)');
-        t.check(decide(INITIAL_STATE, sample(14, 50, procs), 0, gentleT, 'gentle').level === 'throttled', '14 % free is pressure');
+            g.actions.every((a) => a.kind === 'priority' && a.to === 'below' && a.pid !== 3), 'compilers rest below normal even with plenty of memory (the agent does not)');
+        t.check(decide(INITIAL_STATE, sample(19, 50, procs), 0, 'gentle').state.step === 1, '19 % free is step 1');
+        t.section('the compiler cap (vGPU on)');
+        t.check(maxCompilers(16, 'gentle') === 4 && maxCompilers(4, 'gentle') === 2 && maxCompilers(16, 'normal') === null, 'at most max(2, cores / 4) with vGPU, none otherwise');
+        const many = [
+            proc(10, 'rustc.exe', 800),
+            proc(11, 'rustc.exe', 900),
+            proc(12, 'clippy-driver.exe', 700),
+            proc(13, 'link.exe', 100),
+            proc(3, 'claude.exe', 500),
+            proc(14, 'node.exe', 400),
+        ];
+        // The cap is a memory measure: with memory to spare no compiler waits (a waiting rustc stalls cargo's whole build).
+        const free = decide(INITIAL_STATE, sample(60, 40, many), 0, 'gentle', 2);
+        t.check(of(free, 'hold').length === 0, 'with memory to spare, nothing waits even beyond the cap');
+        const capped = decide(INITIAL_STATE, sample(14, 40, many), 0, 'gentle', 2);
+        const holds = of(capped, 'hold').map((a) => ('pid' in a ? a.pid : 0));
+        t.check(capped.state.step === 2 && holds.length === 2, 'under memory pressure (step 2), compilers beyond the cap wait their turn', holds.join(','));
+        t.check(!holds.includes(3) && !holds.includes(14), 'agents (claude, and codex or gemini as node) are never held');
+        t.check(of(decide(INITIAL_STATE, sample(60, 40, many), 0, 'gentle', null), 'hold').length === 0, 'no cap, no pressure: nothing waits');
+        t.check(of(decide(INITIAL_STATE, sample(60, 40, many.slice(0, 2)), 0, 'gentle', 2), 'hold').length === 0, 'under the cap nothing waits');
         t.section('the governor over a port (fake Windows)');
         const calls = [];
         const port = {
             setPriority: (pid, to) => calls.push('prio ' + pid + ' ' + to),
-            pause: (pid, ms) => calls.push('pause ' + pid + ' ' + ms),
+            hold: (pid, ms) => calls.push('hold ' + pid + ' ' + ms),
+            setMemoryPriority: (pid, low) => calls.push('mem ' + pid + ' ' + (low ? 'low' : 'normal')),
+            throttle: (pid) => calls.push('throttle ' + pid),
+            setCpuRate: (percent) => calls.push('cpu ' + percent),
+            trim: (pid) => calls.push('trim ' + pid),
         };
         const logs = [];
         const statuses = [];
@@ -164,15 +216,29 @@ export const heavyLoadSuite = {
             now: () => clock,
             logLine: (l) => logs.push(l),
             saveStatus: (s) => statuses.push(s),
+            warn: (line) => logs.push(line),
         });
-        for (let i = 0; i < 6; i++) {
+        for (let i = 0; i < 4; i++) {
             clock = i * 2000;
-            core.onSample(sample(4, 60, procs));
+            core.onSample(sample(5, 60, procs));
         }
-        t.check(calls.includes('prio 1 below') && calls.includes('pause 1 5000') && !calls.some((c) => c.includes(' 3 ')), 'priority first, then a pause of the biggest; the agent untouched', calls.join('; '));
-        t.check(logs.some((l) => l.includes('memory is low')) && logs.some((l) => l.includes('paused rustc')), 'what it did goes to the memory log');
-        t.check(statuses.length > 0 && PressureStatusSchema.safeParse(statuses[statuses.length - 1]).success, 'its status file matches the schema the host reads');
+        t.check(calls.includes('prio 1 idle') &&
+            calls.includes('mem 1 low') &&
+            calls.includes('cpu 35') &&
+            calls.some((c) => c.startsWith('hold ')) &&
+            calls.some((c) => c.startsWith('trim ')) &&
+            !calls.some((c) => / 3( |$)/.test(c)), 'priority, memory priority, CPU cap, turns and trimming go through the port; the agent untouched', calls.join('; '));
+        t.check(logs.some((l) => l.includes('step 3')) && logs.some((l) => l.includes('waits its turn')), 'what it did goes to the memory log');
+        const lastStatus = statuses[statuses.length - 1];
+        t.check(statuses.length > 0 && PressureStatusSchema.safeParse(lastStatus).success, 'its status file matches the schema the host reads', JSON.stringify(lastStatus));
+        core.hostPressure(60, 'test');
+        t.check(core.current.hostStep === 2, 'the PC being low asks for step 2');
+        core.hostPressure(60, 'test', 'severe');
+        t.check(core.current.hostStep === 4, 'the PC nearly out of memory asks for step 4 at once');
         core.hostPressure(60, 'test');
+        t.check(core.current.hostStep === 4, 'a later "low" does not lower a severe request while it lasts');
+        t.check(decide({ ...INITIAL_STATE, hostUntil: clock + 60000, hostStep: 4 }, sample(60, 40, procs), clock, 'normal').state
+            .step === 4, 'with plenty of memory in the sandbox, a severe PC still turns the dial to 4');
         t.check(core.current.hostUntil === clock + 60000, 'a host request is remembered for its seconds');
         t.section("the PC's watchdog");
         const input = (memory, nowMs, cpu = 10, profile = 'normal') => ({
@@ -184,6 +250,12 @@ export const heavyLoadSuite = {
             profile,
         });
         t.check(watchdogStep(WATCHDOG_START, input(pc(), 0)).state.low === false, 'plenty of memory: quiet');
+        t.check(severeHost(pc({ availableMb: 1200 })) &&
+            severeHost(pc({ commitAvailableMb: 1500 })) &&
+            !severeHost(pc({ availableMb: 3000 })), 'nearly out of memory: under 1.5 GB of RAM free, or commit within max(2 GB, 4 %) of its limit');
+        const lowState = watchdogStep(WATCHDOG_START, input(pc({ availableMb: 3000 }), 100000)).state;
+        const severeNow = watchdogStep(lowState, input(pc({ availableMb: 1200 }), 105000));
+        t.check(severeNow.severe && severeNow.send, 'getting severe is sent at once (not after the usual 30 seconds)');
         t.check(lowReason(pc({ availableMb: 3000 }), 8192, HOST_THRESHOLDS.normal, 1) !== '', 'under 4 GB of RAM: low');
         t.check(lowReason(pc({ availableMb: 5000 }), 8192, HOST_THRESHOLDS.normal, 1) === '', '5 GB free on a 32 GB PC is fine (limit max(4 GB, 12 % = 3.9 GB))');
         t.check(lowReason(pc({ totalMb: 65536, availableMb: 7000 }), 8192, HOST_THRESHOLDS.normal, 1) !== '', '12 % of 64 GB = 7.7 GB: 7 GB is low');
@@ -209,6 +281,16 @@ export const heavyLoadSuite = {
         }
         t.check(sent && cpu.low, 'CPU above 95 % for 60 s: asks the sandbox to slow down');
         t.check(!watchdogStep(WATCHDOG_START, input(pc(), 0, 97)).state.low, 'a short CPU peak is nothing');
+        let disk = WATCHDOG_START;
+        let diskSent = false;
+        for (let i = 0; i < 5; i++) {
+            const st = watchdogStep(disk, input(pc({ diskQueue: 40 }), i * 10000));
+            disk = st.state;
+            diskSent = diskSent || st.send;
+        }
+        t.check(diskSent && disk.low, 'a disk queue of 32 or more for 40 s: asks the sandbox to slow down');
+        t.check(!watchdogStep(WATCHDOG_START, input(pc({ diskQueue: 40 }), 0)).state.low, 'a short disk peak is nothing');
+        t.check(!watchdogStep(WATCHDOG_START, input(pc(), 0)).state.low, 'no disk counter: memory and CPU only');
         t.check(cpuPercentBetween([{ times: { user: 0, nice: 0, sys: 0, idle: 0, irq: 0 } }], [{ times: { user: 90, nice: 0, sys: 0, idle: 10, irq: 0 } }]) === 90, 'CPU use from two readings');
         t.check(GuestRequestSchema.safeParse({ kind: 'pressure', id: 'p1', reason: 'low', seconds: 90, createdAt: 'now' })
             .success &&
@@ -314,13 +396,17 @@ export const heavyLoadSuite = {
         const firstLine = (served.stdout ?? '').split(/\r?\n/)[0] ?? '';
         let sampleOk = false;
         try {
+            // In a sandbox started by 1.10 or later the real agents job exists, so the list may hold its processes.
             const parsedSample = JSON.parse(firstLine);
-            sampleOk = Array.isArray(parsedSample.procs) && parsedSample.procs.length === 0 && parsedSample.ramTotalMb > 0;
+            sampleOk =
+                Array.isArray(parsedSample.procs) &&
+                    parsedSample.procs.every((p) => typeof p.pid === 'number' && typeof p.name === 'string') &&
+                    parsedSample.ramTotalMb > 0;
         }
         catch {
             // Not JSON: the check below fails.
         }
-        t.check(sampleOk && served.status === 0, 'memgov serve prints a sample (no job yet: no processes) and ends when its input closes', firstLine);
+        t.check(sampleOk && served.status === 0, 'memgov serve prints a well-formed sample and ends when its input closes', firstLine);
         for (const script of ['memory-status.ps1', 'stop-events.ps1']) {
             const text = fs.readFileSync(path.join(t.packageRoot, 'native', 'scripts', script), 'utf8');
             t.check(text.startsWith('#Requires -Version 5.1'), script + ' says its PowerShell version');

package/dist/selftest/index.js

@@ -13,6 +13,7 @@ import { liveTestsAvailable } from './support/live.js';
 import { accountsSuite } from './accounts.test.js';
 import { credentialsSuite } from './credentials.test.js';
 import { vpnSuite } from './vpn.test.js';
+import { githubSuite } from './github.test.js';
 import { agentCommandsSuite } from './agent-commands.test.js';
 import { channelSuite } from './channel.test.js';
 import { heavyLoadSuite } from './heavy-load.test.js';
@@ -24,6 +25,7 @@ import { migrateSuite } from './migrate.test.js';
 import { storageSuite } from './storage.test.js';
 import { updateSuite } from './update.test.js';
 import { installSuite } from './install.test.js';
+import { powershellVariablesSuite } from './powershell-variables.test.js';
 import { sharedUseSuite } from './shared-use.test.js';
 import { updateServiceSuite } from './update-service.test.js';
 import { sharingSuite } from './sharing.test.js';
@@ -74,6 +76,7 @@ export const SUITES = [
     updateSuite,
     updateServiceSuite,
     installSuite,
+    powershellVariablesSuite,
     sharingSuite,
     sharedUseSuite,
     workspaceSuite,
@@ -92,6 +95,7 @@ export const SUITES = [
     accountsSuite,
     credentialsSuite,
     vpnSuite,
+    githubSuite,
     workspaceViewSuite,
     auditSuite,
     // an untrusted sandbox: what the host refuses to do with what it finds

package/dist/selftest/layout.test.js

@@ -21,6 +21,8 @@ const PURE_GUEST = [
     'guest/setup/path-plan.js',
     'guest/toolchains/catalogue.js',
     'guest/toolchains/tools/vscode-profile.js',
+    'guest/governor/decide.js',
+    'guest/governor/core.js',
 ];
 const SIDE_EFFECTS = ['guest/runtime/session.js', 'guest/runtime/log.js'];
 const readModules = (dist) => {
@@ -110,6 +112,12 @@ export const layoutSuite = {
             .filter((d) => area(d) === 'guest')
             .map((d) => f + ' -> ' + d));
         t.check(!intoGuest.length, 'host, cli, core, sync and shared import no guest file', list(intoGuest));
+        // The self-test runs outside a sandbox too (GitHub Actions): no test may load the guest runtime, which reads
+        // C:\AgentLaunch\session.json and creates the log folder on import.
+        const testsIntoRuntime = files
+            .filter((f) => area(f) === 'selftest')
+            .flatMap((f) => [...closure(modules, f)].filter((d) => SIDE_EFFECTS.includes(d)).map((d) => f + ' -> ' + d));
+        t.check(!testsIntoRuntime.length, 'no test loads the guest runtime (session.json, log folder), so the self-test runs outside a sandbox', list(testsIntoRuntime));
         t.section('pure guest files');
         for (const pure of PURE_GUEST) {
             t.check(modules.has(pure), pure + ' exists');

package/dist/selftest/live-terminal.test.js

@@ -10,6 +10,7 @@ import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { pathToFileURL } from 'node:url';
 import { encodeFrame, FrameType } from '../shared/pty/index.js';
+import { SYSTEM } from '../shared/system.js';
 import { CSC, openViewer, tail, WAIT } from './support/live.js';
 /**
  * The stand-in agent: VT input and SGR mouse tracking on, echoes what it reads ("got <1b>[<0;10;5M"). L prints 500
@@ -89,6 +90,79 @@ export const liveTerminalSuite = {
         t.check(!errors, 'ptyhost and the stand-in agent compile', errors);
         if (errors)
             return;
+        t.section("the agents' job: a last-resort backstop, set once");
+        {
+            // A job of the test's own (PTYHOST_JOB_NAME), never the agents' real one.
+            const jobName = 'Local\\AgentSandboxAgentsJobTest' + process.pid + '-' + Date.now();
+            const ping = path.join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'PING.EXE');
+            const holder = '"' + SYSTEM.cmd() + '" /c "' + ping + '" -n 6 127.0.0.1 >nul';
+            const startHost = async (backstop, log) => spawn(ptyhost, [String(await freePort()), 'tok', '80', '24', t.at(log), holder], {
+                env: { ...process.env, PTYHOST_BIND: 'loopback', PTYHOST_BACKSTOP_MB: backstop, PTYHOST_JOB_NAME: jobName },
+                stdio: 'ignore',
+                windowsHide: true,
+            });
+            const read = (log) => (fs.existsSync(t.at(log)) ? fs.readFileSync(t.at(log), 'utf8') : '');
+            const first = await startHost('auto', 'job-first.log');
+            await t.waitFor(() => read('job-first.log').includes('agent job:'), WAIT.screen);
+            const second = await startHost('500000', 'job-second.log');
+            await t.waitFor(() => read('job-second.log').includes('agent job:'), WAIT.screen);
+            // The governor's hands on the same test job (MEMGOV_JOB_NAME): it sees the job's processes, and the dial's
+            // commands (memory priority, the throttle job and its CPU cap, trimming) leave them running.
+            const memgovExe = t.at('memgov.exe');
+            const memgovErrors = compile(path.join(t.packageRoot, 'sandbox', 'csharp', 'MemGov.cs'), memgovExe);
+            t.check(!memgovErrors, 'memgov compiles', memgovErrors);
+            if (!memgovErrors) {
+                const memgov = spawn(memgovExe, ['serve', '--interval', '1'], {
+                    env: { ...process.env, MEMGOV_JOB_NAME: jobName },
+                    stdio: ['pipe', 'pipe', 'ignore'],
+                    windowsHide: true,
+                });
+                let lines = '';
+                memgov.stdout.on('data', (chunk) => (lines += chunk.toString('utf8')));
+                const procsSeen = () => {
+                    const last = lines.trim().split(/\r?\n/).pop() ?? '';
+                    try {
+                        return JSON.parse(last).procs;
+                    }
+                    catch {
+                        return [];
+                    }
+                };
+                await t.waitFor(() => procsSeen().length > 0, WAIT.screen);
+                const target = procsSeen().find((p) => /ping|cmd/i.test(p.name));
+                t.check(target !== undefined, "memgov sees the processes in the agents' job", lines.slice(-300));
+                if (target) {
+                    for (const command of [
+                        'memprio ' + target.pid + ' low',
+                        'throttle ' + target.pid,
+                        'cpurate 20',
+                        'trim ' + target.pid,
+                    ])
+                        memgov.stdin.write(command + '\n');
+                    await new Promise((r) => setTimeout(r, 1500));
+                    memgov.stdin.write('cpurate 100\n');
+                    await new Promise((r) => setTimeout(r, 1200));
+                    t.check(memgov.exitCode === null && procsSeen().some((p) => p.pid === target.pid), 'memory priority, the throttle job, a CPU cap and trimming leave the process running (and memgov too)');
+                }
+                memgov.stdin.end();
+                await t.waitFor(() => memgov.exitCode !== null, 5000);
+                t.check(memgov.exitCode === 0, 'memgov ends cleanly when the daemon goes away (and lifts the cap)');
+            }
+            for (const c of [first, second]) {
+                try {
+                    if (c.exitCode === null)
+                        c.kill();
+                }
+                catch {
+                    /* it ended between the check and the kill: nothing left to stop */
+                }
+            }
+            const set = /backstop at (\d+) MB committed \(the sandbox's commit limit is (\d+) MB\)/.exec(read('job-first.log'));
+            const commit = Number(set?.[2] ?? 0);
+            t.check(set !== null &&
+                Number(set[1]) === Math.max(Math.floor(commit / 2), commit - Math.max(1536, Math.floor((commit * 3) / 100))), 'the ptyhost that creates the job sets the backstop just below the commit limit (auto: 3 %, at least 1.5 GB)', read('job-first.log'));
+            t.check(read('job-second.log').includes('joined the existing one'), 'a ptyhost that joins the job never changes its backstop', read('job-second.log'));
+        }
         const client = t.at('client.mjs');
         fs.writeFileSync(client, [
             'import { connect, runTerminalClient } from ' +