windows-development-sandbox 1.10.0 → 1.11.3

package/dist/core/schema/config.d.ts

@@ -86,6 +86,9 @@ export declare const ConfigSchema: z.ZodObject<{
         configFile: z.ZodString;
         killSwitch: z.ZodBoolean;
     }, z.core.$strict>;
+    github: z.ZodObject<{
+        shareToken: z.ZodBoolean;
+    }, z.core.$strict>;
     provisioning: z.ZodObject<{
         copyFromHost: z.ZodBoolean;
         fallbackToInstall: z.ZodBoolean;
@@ -243,6 +246,7 @@ export declare const ConfigSchema: z.ZodObject<{
         reuseSession: z.ZodBoolean;
         auto: z.ZodBoolean;
         autoHide: z.ZodBoolean;
+        confirmCtrlC: z.ZodBoolean;
     }, z.core.$strict>;
     web: z.ZodObject<{
         enabled: z.ZodBoolean;
@@ -699,6 +703,7 @@ export declare const LocalOverridesSchema: z.ZodObject<{
         reuseSession: z.ZodOptional<z.ZodBoolean>;
         auto: z.ZodOptional<z.ZodBoolean>;
         autoHide: z.ZodOptional<z.ZodBoolean>;
+        confirmCtrlC: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     personalization: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;

package/dist/core/schema/config.js

@@ -13,6 +13,7 @@ import { ProjectsSchema } from './projects.js';
 import { ResumeSchema } from './resume.js';
 import { WebSchema } from './web.js';
 import { VpnSchema } from './vpn.js';
+import { GithubSchema } from './github.js';
 export const ConfigSchema = z
     .strictObject({
     $schema: SchemaRefSchema.optional(),
@@ -50,6 +51,7 @@ export const ConfigSchema = z
     }),
     network: NetworkSchema,
     vpn: VpnSchema,
+    github: GithubSchema,
     provisioning: ProvisioningSchema,
     downloads: DownloadsSchema,
     toolchains: ToolchainsSchema,

package/dist/core/schema/github.d.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+export declare const GithubSchema: z.ZodObject<{
+    shareToken: z.ZodBoolean;
+}, z.core.$strict>;

package/dist/core/schema/github.js

@@ -0,0 +1,7 @@
+// The GitHub setting (the token itself is not a setting: it is kept encrypted by `sandbox github login`).
+import { z } from 'zod';
+export const GithubSchema = z.strictObject({
+    shareToken: z
+        .boolean()
+        .describe('Give each sandbox the GitHub token you saved with `sandbox github login` (best a fine-grained token limited to some repositories and permissions), so gh and https git work there without logging in. Only with provisioning.git.access "full". The agent in the sandbox can read the token and use it for whatever it allows. A project file (.sandbox-config.json) cannot turn this on.'),
+});

package/dist/core/schema/index.d.ts

@@ -5,4 +5,5 @@ export { HarnessSchema } from './harness.js';
 export { describeIssues, jsonSchemas } from './json-schema.js';
 export { MappingSchema } from './sandbox.js';
 export { ToolchainsSchema } from './toolchains.js';
+export { GithubSchema } from './github.js';
 export { VpnSchema, VPN_PROVIDERS, type VpnProvider } from './vpn.js';

package/dist/core/schema/index.js

@@ -7,4 +7,5 @@ export { HarnessSchema } from './harness.js';
 export { describeIssues, jsonSchemas } from './json-schema.js';
 export { MappingSchema } from './sandbox.js';
 export { ToolchainsSchema } from './toolchains.js';
+export { GithubSchema } from './github.js';
 export { VpnSchema, VPN_PROVIDERS } from './vpn.js';

package/dist/core/schema/profile.d.ts

@@ -10,6 +10,7 @@ export declare const AttachSchema: z.ZodObject<{
     reuseSession: z.ZodBoolean;
     auto: z.ZodBoolean;
     autoHide: z.ZodBoolean;
+    confirmCtrlC: z.ZodBoolean;
 }, z.core.$strict>;
 export declare const AgentCommandsSchema: z.ZodObject<{
     enabled: z.ZodBoolean;

package/dist/core/schema/profile.js

@@ -22,6 +22,9 @@ export const AttachSchema = z.strictObject({
     autoHide: z
         .boolean()
         .describe('Hide the Windows Sandbox window whenever this terminal attaches; it keeps running (sandbox show brings it back).'),
+    confirmCtrlC: z
+        .boolean()
+        .describe('In an attached terminal and the sandbox window, a single Ctrl+C is held back (the title says so) and only a second one within 1.5 seconds reaches the agent: a Ctrl+C meant as "copy" no longer stops it. Esc still stops an agent.'),
 });
 export const AgentCommandsSchema = z.strictObject({
     enabled: z

package/dist/core/schema/sandbox.js

@@ -21,7 +21,7 @@ export const SandboxSchema = z.strictObject({
         .describe('(alpha) What runs the sandbox. "windows-sandbox" = Windows Sandbox (the default: desktop, Windows Terminal, GPU, clipboard, audio, printers). "hcs" = a headless Hyper-V isolated Server Core container for agents (no desktop, GPU or clipboard); it needs Windows features and an image on this PC (sandbox engine check hcs lists what is missing), and starting it is not enabled yet in this alpha. sandbox engine shows what each engine can do. Yours only: a project file (.sandbox-config.json) cannot set it.'),
     memoryMb: z
         .union([z.literal('auto'), z.number().int().min(2048)])
-        .describe('Sandbox RAM in MB (>= 2048), or "auto": free RAM minus reserveHostMb, capped at maxMemoryMb.'),
+        .describe('Sandbox RAM in MB (>= 2048), or "auto": free RAM minus reserveHostMb, capped at maxMemoryMb. Never more than this PC can keep in RAM for it (its RAM minus the larger of reserveHostMb and 25 %, 2 GB more with vGPU): a bigger value is lowered.'),
     maxMemoryMb: z.number().int().positive().describe('Upper limit for memoryMb "auto".'),
     maxMemoryPercent: z
         .number()
@@ -45,10 +45,10 @@ export const SandboxSchema = z.strictObject({
         .describe('Memory always left for this PC when memoryMb is "auto": the sandbox gets at most (free RAM, and RAM plus paging file still unused) minus this.'),
     agentMemoryHeadroomMb: z
         .union([z.literal('auto'), z.literal('none'), z.number().int().min(0)])
-        .describe('Memory kept out of the agents reach inside the sandbox, in MB: everything the agents start (their builds, tests, tools) together may use at most the sandbox memory minus this; a runaway parallel build then gets out-of-memory errors in its own session instead of freezing or crashing the whole sandbox. "auto" = the larger of 2048 MB and 10 % of the sandbox memory; "none" = no limit. Yours only: a project file cannot change it.'),
+        .describe('The last resort that keeps the sandbox up, in MB below its commit limit (RAM plus paging file): builds are slowed down long before (sandbox.pressureResponse); only if everything the agents start together would take the sandbox to the very edge of its memory, where Windows inside it would start failing, is a build refused memory instead of Windows. "auto" = the larger of 1536 MB and 3 % of the commit limit; "none" = no backstop. Yours only: a project file cannot change it.'),
     pressureResponse: z
         .boolean()
-        .describe('When the sandbox (or this PC) runs low on memory, slow the heaviest build programs down (lower priority) and, if that is not enough, pause the biggest compiler for a few seconds at a time, so heavy parallel builds slow down instead of closing the sandbox. Never touches the agents themselves. Yours only: a project file cannot change it.'),
+        .describe('When the sandbox (or this PC) runs low on memory, slow builds down in steps, like a PC that gets slower instead of failing: build programs get lower CPU and memory priority, then less CPU, then compilers take turns (the waiting ones briefly suspended and trimmed to the paging file). Nothing is stopped or killed, and the agents themselves are never touched. Yours only: a project file cannot change it.'),
     vGpu: z
         .boolean()
         .describe("Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface. The sandbox then uses this PC's graphics card, and with some graphics drivers heavy use can freeze the whole PC: turn it on only when a program in the sandbox needs the GPU (the mesa toolchain gives software OpenGL without it)."),

package/dist/core/schema/toolchains.js

@@ -43,7 +43,7 @@ export const ToolchainsSchema = z.strictObject({
             .describe('GNU host: "lld" links with Rust\'s own lld through MinGW\'s gcc (much less memory than GNU ld), "gnu" with GNU ld.'),
         linkSlots: z
             .union([z.literal('auto'), z.number().int().min(1).max(32)])
-            .describe('GNU host: how many programs may link at the same time in the whole sandbox (other links wait). "auto" = one per 8 GB of sandbox memory, 2 to 4. Several agents linking big programs at once can take Windows down.'),
+            .describe('GNU host: how many programs may link at the same time in the whole sandbox (other links wait). "auto" = one per 3 GB of sandbox memory after 6 GB, 2 to 8 (the memory governor slows links down too when memory runs short).'),
     }),
     msvc: z.strictObject({
         enabled: enabled("MSVC (cl, link) and the Windows SDK, portable from Microsoft's Visual Studio manifest (~1-2 GB once), with vcvars64.bat and vswhere.", 'a .vcxproj, CMakePresets.json, a script calling vcvars/vswhere, or a Rust project when this PC builds Rust with MSVC'),
@@ -102,7 +102,7 @@ export const ToolchainsSchema = z.strictObject({
     }),
     cli: z
         .strictObject({
-        gh: EnabledSchema.describe('GitHub CLI (gh). Only with provisioning.git.access "full": gh can push and merge through the GitHub API, past a read-only git. Your PC\'s gh login is never copied; `gh auth login` inside persists (GH_CONFIG_DIR). "auto" = when the project has a .github folder.'),
+        gh: EnabledSchema.describe('GitHub CLI (gh). Only with provisioning.git.access "full": gh can push and merge through the GitHub API, past a read-only git. Your PC\'s gh login is never copied; `gh auth login` inside persists (GH_CONFIG_DIR), unless a token you saved for sandboxes is handed over (github.shareToken). "auto" = when the project has a .github folder.'),
         zstd: EnabledSchema.describe('Zstandard (zstd). "auto" = off; set true to get it.'),
         openssl: EnabledSchema.describe('`openssl` on PATH, from the copy Git for Windows ships (its mingw64\\bin is not put on PATH, so it cannot shadow MinGW\'s gcc). "auto" = on.'),
     })

package/dist/core/types.d.ts

@@ -141,6 +141,8 @@ export interface GenerateOptions {
     };
     /** The VPN for this launch (vpn.enabled); its profile goes in the launch folder, its login in the one-shot file. */
     vpn?: PreparedVpn;
+    /** The saved GitHub token (github.shareToken, host/github/deliver.ts): only ever written to the one-shot file. */
+    githubToken?: string;
     /** The data set's mappings from a storage provider (contained storage); else the data folder is one mapping. */
     dataMappings?: ResolvedMapping[];
 }
@@ -263,10 +265,11 @@ export interface GuestSession {
     /** sandbox.pageFileMb (0 = Windows' own); sandbox\scripts\set-page-file.ps1 applies it at logon. */
     pageFileMb?: number;
     /**
-     * sandbox.agentMemoryHeadroomMb as a limit: the most memory (MB) everything the agents start may use together
-     * (the sandbox's memory minus the headroom); null = no limit. ptyhost puts each agent in a job object with it.
+     * sandbox.agentMemoryHeadroomMb: how far below the sandbox's commit limit the last-resort backstop of the agents'
+     * job sits ("auto", MB, or "none"). ptyhost reads the commit limit in the sandbox and sets it once, on the job it
+     * creates.
      */
-    agentMemoryLimitMb?: number | null;
+    agentBackstop?: 'auto' | 'none' | number;
     /** "gentle" when vGPU is on: the governor and the watchdog act earlier, compilers run below normal. */
     loadProfile?: 'normal' | 'gentle';
     /** sandbox.pressureResponse: the daemon slows builds down when memory runs low. */

package/dist/guest/boot/boot.js

@@ -18,6 +18,7 @@ import { applyNetworkPolicy, networkProblems } from '../network/firewall.js';
 import { writeManagedSettings } from '../setup/managed-policy.js';
 import { applyPersonalization } from '../setup/desktop.js';
 import { setupGitConfig } from '../setup/git-identity.js';
+import { loginGithub, prepareGithubFolder } from '../setup/github-token.js';
 import { ensurePtyHost } from '../sessions/pty-host.js';
 import { pruneToolLeftovers } from '../toolchains/leftovers.js';
 import { wanted } from '../toolchains/detect.js';
@@ -137,6 +138,7 @@ export class Boot {
         mkdirp(run.root);
         this.secrets = takeSecrets(session.launchId);
         applyBootEnvironment(this.secrets.harnessEnvironment);
+        prepareGithubFolder(this.secrets.githubToken);
         await this.networkAndSessionHost();
         await this.hooksAndDesktop();
         const { tools, env } = await this.developerTools();
@@ -221,6 +223,12 @@ export class Boot {
     async gitIdentity(env) {
         step(5, 'Git identity');
         await soft('Git config', () => setupGitConfig(env));
+        // After the VPN (gh checks the token with GitHub) and the git config (setup-git adds to it).
+        const token = this.secrets.githubToken;
+        if (token) {
+            this.secrets = { ...this.secrets, githubToken: undefined };
+            await soft('GitHub token', () => loginGithub(token, env));
+        }
     }
     async claude(tools) {
         step(6, 'Claude settings, history and claude-mem');

package/dist/guest/daemon/daemon.js

@@ -56,7 +56,7 @@ export class Daemon {
                 return sessions.restart(req);
             case 'pressure':
                 // No response: the host repeats it every few seconds while its memory stays low.
-                return governor.hostPressure(req.seconds, req.reason);
+                return governor.hostPressure(req.seconds, req.reason, req.level ?? 'slow');
             case 'ping':
                 return respond(req.id, { ok: true, message: 'pong (' + sessions.count + ' session(s) running)' });
         }

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

@@ -3,8 +3,9 @@ type SessionRequest = Extract<GuestRequest, {
     kind: 'session';
 }>;
 /**
- * What keeps heavy load from taking the sandbox down: the job object's memory limit for everything the agents start
- * (ptyhost reads PTYHOST_JOB_MB) and cargo's parallel jobs sized to the sandbox's memory and the sessions building.
+ * What keeps heavy load from taking the sandbox down: the agents' job with its last-resort backstop (ptyhost reads
+ * PTYHOST_BACKSTOP_MB and the commit limit) and cargo's parallel jobs sized to the sandbox's memory and the sessions
+ * building. Slowing builds down comes first (the governor); the backstop only ever picks a build over Windows.
  */
 export declare function memoryEnv(env: NodeJS.ProcessEnv, sessions: number): NodeJS.ProcessEnv;
 /** The agent sessions of this sandbox: the running ones, the ones starting, and what happens when one ends. */

package/dist/guest/daemon/sessions.js

@@ -9,7 +9,7 @@ import { FrameType, sendControl } from '../../shared/pty/index.js';
 import { isWithin } from '../../shared/paths/projects.js';
 import { now } from '../../shared/channel/run-dir.js';
 import { SYSTEM } from '../../shared/system.js';
-import { cargoJobs } from '../../shared/memory/index.js';
+import { buildJobs, cargoJobs, linkSlotsFor, usableCpus } from '../../shared/memory/index.js';
 import { commandLine } from '../sessions/cmdline.js';
 import { freePort } from '../runtime/ports.js';
 import { primaryProject } from '../boot/project-status.js';
@@ -20,7 +20,8 @@ import { saveLocalState } from '../agents/local-state.js';
 import { projectHooks, runHooks, runHooksAsync } from '../setup/hooks.js';
 import { guestAddresses } from '../network/addresses.js';
 import { withRegistryPath } from '../setup/environment.js';
-import { dataDir, toolsDir } from '../runtime/paths.js';
+import { dataDir, run, toolsDir } from '../runtime/paths.js';
+import { writeJsonAtomic } from '../../shared/io/json.js';
 import { exists } from '../runtime/fs.js';
 import { log, warn } from '../runtime/log.js';
 import { claudeDir, session, workspace } from '../runtime/session.js';
@@ -51,17 +52,47 @@ const harnessFor = (req) => {
     throw new Error('Agent "' + req.harness + '" is not configured for this sandbox (it runs ' + session.harnessName + ').');
 };
 /**
- * What keeps heavy load from taking the sandbox down: the job object's memory limit for everything the agents start
- * (ptyhost reads PTYHOST_JOB_MB) and cargo's parallel jobs sized to the sandbox's memory and the sessions building.
+ * What keeps heavy load from taking the sandbox down: the agents' job with its last-resort backstop (ptyhost reads
+ * PTYHOST_BACKSTOP_MB and the commit limit) and cargo's parallel jobs sized to the sandbox's memory and the sessions
+ * building. Slowing builds down comes first (the governor); the backstop only ever picks a build over Windows.
  */
 export function memoryEnv(env, sessions) {
     const out = {};
-    if (session.agentMemoryLimitMb)
-        out.PTYHOST_JOB_MB = String(session.agentMemoryLimitMb);
+    out.PTYHOST_BACKSTOP_MB = String(session.agentBackstop ?? 'auto');
+    // What a program sees is what it may use: the processors of the CPU cap (the boot job's affinity), not every one.
+    const cpus = usableCpus(os.cpus().length, session.cpuLimitPercent ?? null);
+    const memoryGb = os.totalmem() / 1024 ** 3;
+    const jobs = cargoJobs(cpus, memoryGb, sessions);
+    out.NUMBER_OF_PROCESSORS = String(cpus);
     if (!env.CARGO_BUILD_JOBS)
-        out.CARGO_BUILD_JOBS = String(cargoJobs(os.cpus().length, os.totalmem() / 1024 ** 3, sessions));
+        out.CARGO_BUILD_JOBS = String(jobs);
+    if (!env.CMAKE_BUILD_PARALLEL_LEVEL)
+        out.CMAKE_BUILD_PARALLEL_LEVEL = String(jobs);
+    out.SANDBOX_BUDGET_FILE = run.budgetFile;
+    writeBudget(cpus, memoryGb, jobs, env);
     return out;
 }
+/**
+ * run\budget.json (SANDBOX_BUDGET_FILE): the numbers an agent should plan with, because a program in a sandbox sees
+ * the sandbox's maximum (all processors, the whole RAM) rather than what it may use. Never stops a session.
+ */
+function writeBudget(cpus, memoryGb, jobs, env) {
+    try {
+        writeJsonAtomic(run.budgetFile, {
+            processors: cpus,
+            memoryMb: Math.round(memoryGb * 1024),
+            buildJobs: buildJobs(cpus, memoryGb),
+            cargoJobsPerSession: jobs,
+            linkSlots: Number(env.AGENT_LINK_SLOTS) || linkSlotsFor(memoryGb),
+            cpuLimitPercent: session.cpuLimitPercent ?? null,
+            governor: run.pressureFile,
+            note: 'Plan builds with these numbers. When memory runs short the sandbox slows builds down in steps (governor); nothing fails.',
+        });
+    }
+    catch (e) {
+        warn('budget.json could not be written: ' + errMsg(e));
+    }
+}
 /** Starts ptyhost for the agent and waits until it listens; a failure carries the tail of ptyhost's own log. */
 const launchPtyHost = async (req, remote, env, say, sessions) => {
     const harness = harnessFor(req);

package/dist/guest/governor/core.d.ts

@@ -0,0 +1,44 @@
+import type { PressureStatus } from '../../shared/channel/schema.js';
+import type { LoadProfile } from '../../shared/memory/index.js';
+import { type GovernorState, type MemSample } from './decide.js';
+/** What the governor needs from Windows (injectable: the tests use a fake). */
+export interface GovernorPort {
+    setPriority(pid: number, to: 'idle' | 'below' | 'normal'): void;
+    /** Suspends for `ms`, then resumes (memgov resumes it even if the daemon goes away). */
+    hold(pid: number, ms: number): void;
+    setMemoryPriority(pid: number, low: boolean): void;
+    /** Into the throttle job (whose CPU cap setCpuRate sets). */
+    throttle(pid: number): void;
+    setCpuRate(percent: number): void;
+    trim(pid: number): void;
+}
+/** Everything a step changes outside the decision, behind injectable functions. */
+export interface GovernorDeps {
+    readonly port: GovernorPort;
+    readonly profile: LoadProfile;
+    /** At most this many heavy compilers run at once (null = no cap). */
+    readonly maxCompilers?: number | null;
+    readonly now: () => number;
+    /** A line in the memory log. */
+    readonly logLine: (line: string) => void;
+    /** run\pressure.json. */
+    readonly saveStatus: (status: PressureStatus) => void;
+    /** A problem worth the guest log (an action Windows refused). */
+    readonly warn: (text: string) => void;
+}
+/** The governor's logic over a port: feed it samples; the host's "slow down" requests go to hostPressure. */
+export declare class GovernorCore {
+    private readonly deps;
+    private state;
+    private lastAction;
+    private lastWrite;
+    private lastWriteAt;
+    /** Compilers waiting their turn now, by pid (name), to log a hold once. */
+    private held;
+    constructor(deps: GovernorDeps);
+    hostPressure(seconds: number, reason: string, level?: 'slow' | 'severe'): void;
+    get current(): GovernorState;
+    onSample(sample: MemSample): void;
+    private apply;
+    private note;
+}

package/dist/guest/governor/core.js

@@ -0,0 +1,124 @@
+import { now } from '../../shared/channel/run-dir.js';
+import { errMsg } from '../../core/util/errors.js';
+import { decide, HOLD_MS, INITIAL_STATE } from './decide.js';
+const STEP_TEXT = [
+    'builds back to normal',
+    'build programs at lower priority',
+    'builds get less CPU and take turns',
+    'builds take turns, waiting ones go to the paging file',
+    'one compiler at a time',
+];
+/** The governor's logic over a port: feed it samples; the host's "slow down" requests go to hostPressure. */
+export class GovernorCore {
+    deps;
+    state = INITIAL_STATE;
+    lastAction = '';
+    lastWrite = '';
+    lastWriteAt = 0;
+    /** Compilers waiting their turn now, by pid (name), to log a hold once. */
+    held = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    hostPressure(seconds, reason, level = 'slow') {
+        const nowMs = this.deps.now();
+        const until = nowMs + seconds * 1000;
+        const active = this.state.hostUntil > nowMs;
+        const step = Math.max(level === 'severe' ? 4 : 2, active ? this.state.hostStep : 0);
+        if (!active || step > this.state.hostStep)
+            this.deps.logLine('governor: this PC is ' +
+                (level === 'severe' ? 'nearly out of memory' : 'low') +
+                ' (' +
+                reason +
+                '); builds to step ' +
+                step);
+        this.state = { ...this.state, hostUntil: Math.max(until, this.state.hostUntil), hostStep: step };
+    }
+    get current() {
+        return this.state;
+    }
+    onSample(sample) {
+        const nowMs = this.deps.now();
+        const before = this.state.step;
+        const d = decide(this.state, sample, nowMs, this.deps.profile, this.deps.maxCompilers ?? null);
+        this.state = d.state;
+        const holding = new Set();
+        for (const action of d.actions) {
+            if (action.kind === 'hold')
+                holding.add(action.pid);
+            this.apply(action);
+        }
+        for (const pid of [...this.held.keys()])
+            if (!holding.has(pid))
+                this.held.delete(pid);
+        if (d.state.step !== before)
+            this.deps.logLine('governor: step ' +
+                d.state.step +
+                ' (' +
+                d.ramFreePercent +
+                '% RAM free, commit ' +
+                d.commitPercent +
+                '% used): ' +
+                STEP_TEXT[d.state.step]);
+        const status = {
+            level: d.level,
+            step: d.state.step,
+            profile: this.deps.profile,
+            ramFreePercent: Math.max(0, Math.min(100, d.ramFreePercent)),
+            commitPercent: Math.max(0, Math.min(100, d.commitPercent)),
+            lowered: Object.keys(d.state.lowered).length,
+            paused: [...this.held]
+                .slice(0, 8)
+                .map(([pid, name]) => ({ name: name.slice(0, 64), pid, seconds: HOLD_MS / 1000 })),
+            cpuPercent: d.state.cpuRate,
+            pcLow: nowMs < d.state.hostUntil,
+            lastAction: this.lastAction.slice(0, 300),
+            updatedAt: now(),
+        };
+        // Written when something changed, else once a minute (the host reads it, never polls it hard).
+        const shape = JSON.stringify({ ...status, updatedAt: '', paused: status.paused.map((p) => p.pid) });
+        if (shape !== this.lastWrite || nowMs - this.lastWriteAt > 60000) {
+            this.lastWrite = shape;
+            this.lastWriteAt = nowMs;
+            this.deps.saveStatus(status);
+        }
+    }
+    apply(action) {
+        const port = this.deps.port;
+        try {
+            switch (action.kind) {
+                case 'hold':
+                    port.hold(action.pid, action.ms);
+                    if (!this.held.has(action.pid)) {
+                        this.held.set(action.pid, action.name);
+                        this.note(action.name + ' (' + action.pid + ') waits its turn');
+                    }
+                    return;
+                case 'priority':
+                    port.setPriority(action.pid, action.to);
+                    this.note(action.name + ' (' + action.pid + ') priority ' + action.to);
+                    return;
+                case 'memory':
+                    port.setMemoryPriority(action.pid, action.low);
+                    return;
+                case 'throttle':
+                    port.throttle(action.pid);
+                    return;
+                case 'cpu':
+                    port.setCpuRate(action.percent);
+                    this.note(action.percent >= 100 ? 'compilers: no CPU cap' : 'compilers: at most ' + action.percent + '% CPU');
+                    return;
+                case 'trim':
+                    port.trim(action.pid);
+                    return;
+            }
+        }
+        catch (e) {
+            this.deps.warn('governor: ' + errMsg(e));
+        }
+    }
+    note(text) {
+        this.lastAction = text;
+        this.deps.logLine('governor: ' + text);
+    }
+}

package/dist/guest/governor/decide.d.ts

@@ -1,4 +1,4 @@
-import type { GuestThresholds, LoadProfile } from '../../shared/memory/index.js';
+import { type LoadProfile } from '../../shared/memory/index.js';
 export type Priority = 'idle' | 'below' | 'normal';
 export interface ProcSample {
     readonly pid: number;
@@ -21,19 +21,29 @@ export declare const isHeavyCompiler: (name: string) => boolean;
 export declare const canPause: (name: string) => boolean;
 export type Level = 'ok' | 'throttled' | 'suspending';
 export interface GovernorState {
-    /** Under pressure now (with hysteresis). */
-    readonly pressure: boolean;
-    /** Samples in a row that looked calm while under pressure. */
+    /** The dial: 0 nothing wrong, 1 lower priority, 2 less CPU and fewer compilers, 3 and 4 harder. */
+    readonly step: number;
+    /** Samples in a row clear of the current step (it turns down after DIAL_CALM_SAMPLES). */
     readonly calm: number;
-    /** Samples under pressure so far (resets when it ends). */
-    readonly samples: number;
     /** What was lowered and to what, by pid. */
     readonly lowered: Readonly<Record<number, Priority>>;
-    /** Until when (ms) the last pause lasts, and when another may start. */
-    readonly pausedUntil: number;
-    readonly nextPauseAt: number;
-    /** The PC asked for slowing down until this time (ms). */
+    /** Pids whose memory priority is low. */
+    readonly memLow: readonly number[];
+    /** Pids put in the throttle job (its CPU cap follows the step). */
+    readonly throttled: readonly number[];
+    /** Pids whose working set was trimmed while they waited. */
+    readonly trimmed: readonly number[];
+    /** The CPU cap last set on the throttle job (percent; 100 = none). */
+    readonly cpuRate: number;
+    /** Used commit (MB) and when, at the last sample: how fast it grows. */
+    readonly lastCommitMb: number;
+    readonly lastAt: number;
+    /** Commit growth in MB per second, smoothed over the samples. */
+    readonly growth: number;
+    /** The PC asked for slowing down until this time (ms): the dial is at least at `hostStep` until then. */
     readonly hostUntil: number;
+    /** 2 when the PC is low, 4 when it is nearly out of memory. */
+    readonly hostStep: number;
 }
 export declare const INITIAL_STATE: GovernorState;
 export type Action = {
@@ -42,20 +52,37 @@ export type Action = {
     readonly name: string;
     readonly to: Priority;
 } | {
-    readonly kind: 'pause';
+    readonly kind: 'memory';
     readonly pid: number;
     readonly name: string;
-    readonly ms: number;
+    readonly low: boolean;
+}
+/** Into the throttle job, whose CPU cap follows the dial. */
+ | {
+    readonly kind: 'throttle';
+    readonly pid: number;
+    readonly name: string;
+} | {
+    readonly kind: 'cpu';
+    readonly percent: number;
 }
-/** Waits (suspended) because more compilers run than the cap allows; repeated while it is over, never killed. */
+/** Waits (suspended) for its turn; repeated while it waits, always resumed, never killed. */
  | {
     readonly kind: 'hold';
     readonly pid: number;
     readonly name: string;
     readonly ms: number;
+}
+/** Its pages go to the paging file while it waits, so the compilers that run have the RAM. */
+ | {
+    readonly kind: 'trim';
+    readonly pid: number;
+    readonly name: string;
 };
-/** How long a held compiler waits before it gets a turn again (the governor repeats the hold while over the cap). */
+/** How long a held compiler waits before it may get a turn again (the governor repeats the hold while it waits). */
 export declare const HOLD_MS = 3000;
+/** Which compilers wait their turn changes this often, so none waits for ever. */
+export declare const ROTATE_MS = 20000;
 export interface Decision {
     readonly state: GovernorState;
     readonly actions: readonly Action[];
@@ -63,9 +90,10 @@ export interface Decision {
     readonly ramFreePercent: number;
     readonly commitPercent: number;
 }
-export declare const PAUSE_MS = 5000;
+/** The step a sample calls for on its own: the highest step whose threshold it crosses. */
+export declare function stepFor(ramFree: number, commit: number, secondsToLimit: number, profile: LoadProfile): number;
 /**
- * One step. `gentle` (vGPU on): compilers start below normal even without pressure. Programs go back to their normal
- * priority only when pressure ends (several calm samples in a row).
+ * One step of the governor. The dial turns up at once and down one step at a time after calm samples. `gentle` (vGPU
+ * on): compilers rest below normal priority, and `maxCompilers` caps how many heavy compilers run at any step.
  */
-export declare function decide(prev: GovernorState, sample: MemSample, nowMs: number, thresholds: GuestThresholds, profile: LoadProfile, maxCompilers?: number | null): Decision;
+export declare function decide(prev: GovernorState, sample: MemSample, nowMs: number, profile: LoadProfile, maxCompilers?: number | null): Decision;