windows-development-sandbox 1.7.0 → 1.9.0

package/dist/core/schema/vpn.js

@@ -1,13 +1,13 @@
 // The VPN setting (inside the sandbox only; the login is not a setting: it is kept encrypted by `sandbox vpn login`).
 import { z } from 'zod';
-export const VPN_PROVIDERS = ['nordvpn', 'openvpn-file'];
+export const VPN_PROVIDERS = ['nordvpn', 'openvpn-file', 'wireguard-file'];
 export const VpnSchema = z.strictObject({
     enabled: z
         .boolean()
         .describe("Send the sandbox's traffic through a VPN. Only the sandbox: your PC's own connection is untouched. Needs a saved login first (sandbox vpn login). The agent in the sandbox can read that login and can turn the tunnel off (it is the administrator there)."),
     provider: z
         .enum(VPN_PROVIDERS)
-        .describe('nordvpn: a recommended NordVPN server is picked at every launch. openvpn-file: your own .ovpn file (configFile).'),
+        .describe('nordvpn: a recommended NordVPN server is picked at every launch. openvpn-file: your own .ovpn file (configFile). wireguard-file: your own WireGuard .conf (configFile), e.g. from your company.'),
     protocol: z.enum(['udp', 'tcp']).describe('udp is faster; tcp gets through networks that block udp.'),
     country: z
         .string()
@@ -15,7 +15,7 @@ export const VpnSchema = z.strictObject({
         .describe('nordvpn: the country of the server, e.g. uk, us or Germany. Empty = the best server anywhere.'),
     configFile: z
         .string()
-        .describe("openvpn-file: the .ovpn file on this PC (its certificates inside it). Files that run programs (script-security, up, down, plugin ...) are refused. A project's file can never set this."),
+        .describe("openvpn-file / wireguard-file: the .ovpn or .conf file on this PC (an .ovpn has its certificates inside it). Files that run programs (script-security, up, down, plugin, PostUp ...) are refused. A WireGuard file holds your private key: it is read when a sandbox starts and handed over in a one-shot file. A project's file can never set this."),
     killSwitch: z
         .boolean()
         .describe('Block all traffic that does not go through the tunnel: when the tunnel cannot start, the sandbox stays offline instead of using your normal connection. A project can only turn this on, never off.'),

package/dist/core/types.d.ts

@@ -105,12 +105,15 @@ export interface DatabasePlan {
 /** The VPN decided at launch (host/vpn/prepare.ts): its checked profile, and the login for the one-shot file. */
 export interface PreparedVpn {
     session: GuestVpn;
-    /** The profile text, already checked. */
-    profile: string;
-    credentials: {
+    /** openvpn: the profile text, already checked (goes in the launch folder). */
+    profile?: string;
+    /** openvpn: the login (one-shot file). */
+    credentials?: {
         username: string;
         password: string;
     };
+    /** wireguard-file: the checked config; holds the private key (one-shot file only). */
+    wireguardConfig?: string;
 }
 /** databases / pcLanguages: use these instead of scanning (tests). */
 export interface GenerateOptions {
@@ -119,6 +122,8 @@ export interface GenerateOptions {
     harnessArgs: string[];
     probe: HostProbe;
     freeMemoryBytes?: number;
+    /** This PC's unused commit (RAM plus paging file) in MB from HostTools memory-status; omitted = not checked. */
+    commitAvailableMb?: number | null;
     databases?: DatabasePlan[];
     pcLanguages?: AutoToolchain[];
     /**
@@ -136,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 data set's mappings from a storage provider (contained storage); else the data folder is one mapping. */
+    dataMappings?: ResolvedMapping[];
 }
 export interface Generated {
     wsbPath: string;
@@ -143,6 +150,8 @@ export interface Generated {
     launchId: string;
     sessionPath: string;
     memoryMb: number;
+    /** Plain words when the PC's commit made the memory much smaller than free RAM allowed. */
+    memoryNote: string | null;
     /** The config the sandbox boots with: the launch folder's plus what the other projects mapped at boot want. */
     bootConfig: Config;
     /** Boot settings turned on for another project (setting -> project). */
@@ -181,8 +190,8 @@ export interface GuestVpn {
     killSwitch: boolean;
     /** The server's name, for messages. */
     server: string;
-    /** The checked profile, relative to the launch folder. */
-    profile: string;
+    /** openvpn: the checked profile, relative to the launch folder (none for wireguard-file: its config is a secret). */
+    profile?: string;
 }
 /** Written by the host to C:\AgentLaunch\session.json (read-only for the guest): everything the guest needs to know. */
 export interface GuestSession {
@@ -253,6 +262,15 @@ export interface GuestSession {
     cpuLimitPercent?: number | null;
     /** 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.
+     */
+    agentMemoryLimitMb?: number | null;
+    /** "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. */
+    pressureResponse?: boolean;
     /** Apps to install (catalogue ids and your own programs); missing in launch folders of older versions. */
     apps?: Config['apps'];
     /** audit.enabled and audit.processes: the sandbox reports the programs it starts (host keeps the log). */

package/dist/core/util/fs.d.ts

@@ -1,6 +1,8 @@
 export declare function ensureDir(p: string): void;
 export declare function dirExists(p: string): boolean;
 export declare function fileExists(p: string): boolean;
+/** fileExists without blocking the program (the menu looks for programs while it stays responsive). */
+export declare function fileExistsAsync(p: string): Promise<boolean>;
 export declare function readJson<T>(p: string): T;
 export declare function tryReadJson<T>(p: string): T | null;
 /** Atomic (a crash or a second command never leaves half a file); refused outside temp during the self-test. */

package/dist/core/util/fs.js

@@ -19,6 +19,15 @@ export function fileExists(p) {
         return false;
     }
 }
+/** fileExists without blocking the program (the menu looks for programs while it stays responsive). */
+export async function fileExistsAsync(p) {
+    try {
+        return (await fs.promises.stat(p)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 export function readJson(p) {
     return JSON.parse(fs.readFileSync(p, 'utf8').replace(/^\uFEFF/, ''));
 }

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

@@ -1,7 +1,7 @@
 export { isWin, sleep, captureOutput } from './process.js';
 export { UserError, fail, errMsg } from './errors.js';
 export { parseJsonc, readJsonc } from './jsonc.js';
-export { ensureDir, dirExists, fileExists, readJson, tryReadJson, writeJson, realPath } from './fs.js';
+export { ensureDir, dirExists, fileExists, fileExistsAsync, readJson, tryReadJson, writeJson, realPath } from './fs.js';
 export { xmlEscape, safeText, plainText } from './text.js';
 export { homeDir, expandPath, expandVariables, isRootPath, isUserProfile, isInsideOrEqual, findOnPath, } from './paths.js';
 export { isLink, removeLink, assertNoLinks } from './links.js';

package/dist/core/util/index.js

@@ -1,7 +1,7 @@
 export { isWin, sleep, captureOutput } from './process.js';
 export { UserError, fail, errMsg } from './errors.js';
 export { parseJsonc, readJsonc } from './jsonc.js';
-export { ensureDir, dirExists, fileExists, readJson, tryReadJson, writeJson, realPath } from './fs.js';
+export { ensureDir, dirExists, fileExists, fileExistsAsync, readJson, tryReadJson, writeJson, realPath } from './fs.js';
 export { xmlEscape, safeText, plainText } from './text.js';
 export { homeDir, expandPath, expandVariables, isRootPath, isUserProfile, isInsideOrEqual, findOnPath, } from './paths.js';
 export { isLink, removeLink, assertNoLinks } from './links.js';

package/dist/guest/agents/agent-files.d.ts

@@ -43,6 +43,11 @@ export interface LocalState {
     readonly legacy: string;
 }
 export declare function localStateEntries(agents: Readonly<Record<string, Harness>>, stateDir: string, localRoot: string): LocalState[];
+/** Every agent's bootReset paths, absolute below its state folder (the schema allows only plain relative paths). */
+export declare function bootResetPaths(agents: Readonly<Record<string, Harness>>, stateDir: string): {
+    agent: string;
+    path: string;
+}[];
 /** A SQLite database file or one of its -wal / -shm siblings. */
 export declare const isDatabaseFile: (name: string) => boolean;
 /** Files that make a consistent copy: the databases and their -wal (the -shm is rebuilt by SQLite). */

package/dist/guest/agents/agent-files.js

@@ -57,6 +57,10 @@ export function localStateEntries(agents, stateDir, localRoot) {
         legacy: path.join(stateDir, agent),
     })));
 }
+/** Every agent's bootReset paths, absolute below its state folder (the schema allows only plain relative paths). */
+export function bootResetPaths(agents, stateDir) {
+    return Object.entries(agents).flatMap(([agent, harness]) => (harness.bootReset ?? []).map((rel) => ({ agent, path: path.join(stateDir, agent, rel) })));
+}
 /** A SQLite database file or one of its -wal / -shm siblings. */
 export const isDatabaseFile = (name) => /\.(sqlite3?|db)(-wal|-shm)?$/i.test(name);
 /** Files that make a consistent copy: the databases and their -wal (the -shm is rebuilt by SQLite). */

package/dist/guest/agents/local-state.d.ts

@@ -3,6 +3,8 @@ import { type LocalState } from './agent-files.js';
 export declare function agentLocalStates(): LocalState[];
 /** Variable -> working folder, for the agent environment (and the machine environment of new terminal tabs). */
 export declare function localStateVars(): Record<string, string>;
+/** Boot: what an agent sealed to the last sandbox (bootReset) is deleted, so it sets it up again. Links are left. */
+export declare function resetMachineBound(): void;
 /** Boot: the saved databases of every configured agent are copied to the sandbox's disk, where the agent runs them. */
 export declare function restoreLocalState(): void;
 /**

package/dist/guest/agents/local-state.js

@@ -10,7 +10,7 @@ import { execOutput } from '../runtime/process.js';
 import { log, warn } from '../runtime/log.js';
 import { session, stateDir } from '../runtime/session.js';
 import { errMsg } from '../../core/util/errors.js';
-import { isCopyableDatabaseFile, isDatabaseFile, localStateEntries } from './agent-files.js';
+import { bootResetPaths, isCopyableDatabaseFile, isDatabaseFile, localStateEntries, } from './agent-files.js';
 const SQLITE_HEADER = 'SQLite format 3\0';
 /** The sandbox-disk folder that holds the working copies. */
 const localRoot = () => path.join(localDir, 'agent-state');
@@ -82,6 +82,26 @@ function adoptLegacy(s) {
         fs.rmSync(path.join(s.legacy, n), { force: true });
     log(s.agent + ': moved ' + copyable.length + ' database file(s) to ' + s.store + '.');
 }
+/** Boot: what an agent sealed to the last sandbox (bootReset) is deleted, so it sets it up again. Links are left. */
+export function resetMachineBound() {
+    if (dryRun)
+        return;
+    for (const { agent, path: target } of bootResetPaths(session.agents ?? {}, stateDir)) {
+        try {
+            const stat = fs.lstatSync(target, { throwIfNoEntry: false });
+            if (!stat || stat.isSymbolicLink())
+                continue;
+            fs.rmSync(target, { recursive: true, force: true });
+            log(agent +
+                ': removed ' +
+                path.relative(path.join(stateDir, agent), target) +
+                ' (it only worked in the last sandbox).');
+        }
+        catch (e) {
+            warn(agent + ': could not remove ' + target + ' (' + errMsg(e) + ').');
+        }
+    }
+}
 /** Boot: the saved databases of every configured agent are copied to the sandbox's disk, where the agent runs them. */
 export function restoreLocalState() {
     if (dryRun)

package/dist/guest/boot/boot.js

@@ -6,7 +6,7 @@ import { writeGuides } from './guide.js';
 import { setupToolchains } from '../toolchains/index.js';
 import { agents } from '../agents/agent-installer.js';
 import { agentShims, sbxAgentText, shimText } from '../agents/agent-files.js';
-import { restoreLocalState } from '../agents/local-state.js';
+import { resetMachineBound, restoreLocalState } from '../agents/local-state.js';
 import { installShellPath } from '../setup/shell-path.js';
 import { linkProfileDirs } from '../agents/profile-links.js';
 import { restoreClaudeMem } from '../setup/claude-mem.js';
@@ -225,6 +225,7 @@ export class Boot {
         if (session.harnessName === 'claude')
             await soft('Claude settings', () => syncClaudeProfile(this.secrets.claudeCredentials));
         await soft('claude-mem restore', restoreClaudeMem);
+        await soft('Agent files of the last sandbox', resetMachineBound);
         await soft('Agent databases restore', restoreLocalState);
         await soft('Sandbox guide for the agent', () => writeGuides(tools.summary, this.lan));
         await soft('Claude managed settings', () => writeManagedSettings(this.gitAccess));

package/dist/guest/daemon/daemon.js

@@ -4,6 +4,7 @@ import { saveClaudeMem } from '../setup/claude-mem.js';
 import { saveLocalState } from '../agents/local-state.js';
 import { execCommand } from './exec.js';
 import { sessions } from './sessions.js';
+import { governor } from '../governor/index.js';
 import { respond, safely } from './state.js';
 import { run } from '../runtime/paths.js';
 import { withRequestSecrets } from '../runtime/secrets.js';
@@ -53,6 +54,9 @@ export class Daemon {
                 return execCommand(req);
             case 'restart':
                 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);
             case 'ping':
                 return respond(req.id, { ok: true, message: 'pong (' + sessions.count + ' session(s) running)' });
         }

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

@@ -2,6 +2,11 @@ import type { GuestRequest } from '../../core/types.js';
 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.
+ */
+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. */
 export declare class SessionManager {
     private readonly live;

package/dist/guest/daemon/sessions.js

@@ -3,11 +3,13 @@
 // (daemon/project).
 import path from 'node:path';
 import crypto from 'node:crypto';
+import os from 'node:os';
 import { spawn } from 'node:child_process';
 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 { commandLine } from '../sessions/cmdline.js';
 import { freePort } from '../runtime/ports.js';
 import { primaryProject } from '../boot/project-status.js';
@@ -48,8 +50,20 @@ const harnessFor = (req) => {
         return sent;
     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.
+ */
+export function memoryEnv(env, sessions) {
+    const out = {};
+    if (session.agentMemoryLimitMb)
+        out.PTYHOST_JOB_MB = String(session.agentMemoryLimitMb);
+    if (!env.CARGO_BUILD_JOBS)
+        out.CARGO_BUILD_JOBS = String(cargoJobs(os.cpus().length, os.totalmem() / 1024 ** 3, sessions));
+    return out;
+}
 /** 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) => {
+const launchPtyHost = async (req, remote, env, say, sessions) => {
     const harness = harnessFor(req);
     // Never refresh here: main already did, and replacing a running agent's executable would fail.
     say('Preparing ' + req.harness);
@@ -66,7 +80,7 @@ const launchPtyHost = async (req, remote, env, say) => {
         rows: 32,
         id: req.id,
         cwd: req.cwd,
-        env: { ...withRegistryPath(env), ...harness.environment },
+        env: { ...withRegistryPath(env), ...harness.environment, ...memoryEnv(env, sessions) },
         remote,
         command: commandLine(launch.file, [...base, ...req.args]),
         restartCommand: commandLine(launch.file, [...base, ...(harness.resumeArguments ?? [])]),
@@ -145,7 +159,7 @@ export class SessionManager {
         try {
             const place = await placeFor(req, say);
             const remote = session.networking && session.attach.enabled;
-            const { child, port, token } = await launchPtyHost(req, remote, place.env, say);
+            const { child, port, token } = await launchPtyHost(req, remote, place.env, say, this.live.size + 1);
             const resumed = req.harness === 'claude' ? resumedConversation(req.args) : undefined;
             const running = {
                 ...status,

package/dist/guest/entries/daemon.js

@@ -9,10 +9,13 @@ import { log, warn } from '../runtime/log.js';
 import { adoptBootSecrets } from '../runtime/secrets.js';
 import { errMsg } from '../../core/util/errors.js';
 import { Daemon } from '../daemon/daemon.js';
+import { governor } from '../governor/index.js';
 process.on('uncaughtException', (e) => warn('daemon: unexpected error (continuing): ' + (e.stack ?? errMsg(e))));
 process.on('unhandledRejection', (e) => warn('daemon: unexpected error (continuing): ' + errMsg(e)));
 adoptBootSecrets();
 log('Session daemon started (pid ' + process.pid + ').');
 safely('port forwards', startRelays);
 safely('audit', startProcessCollector);
+safely('memory governor', () => governor.start());
+log('Memory governor: ' + governor.describe());
 new Daemon().start();

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

@@ -0,0 +1,61 @@
+import type { GuestThresholds, LoadProfile } from '../../shared/memory/index.js';
+export type Priority = 'idle' | 'below' | 'normal';
+export interface ProcSample {
+    readonly pid: number;
+    readonly name: string;
+    /** Private memory in MB. */
+    readonly mb: number;
+    readonly prio: Priority;
+}
+export interface MemSample {
+    readonly ramTotalMb: number;
+    readonly ramAvailMb: number;
+    readonly commitLimitMb: number;
+    readonly commitAvailMb: number;
+    /** Only the processes in the agents' job. */
+    readonly procs: readonly ProcSample[];
+}
+export declare const isNeverTouched: (name: string) => boolean;
+export declare const canLower: (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. */
+    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). */
+    readonly hostUntil: number;
+}
+export declare const INITIAL_STATE: GovernorState;
+export type Action = {
+    readonly kind: 'priority';
+    readonly pid: number;
+    readonly name: string;
+    readonly to: Priority;
+} | {
+    readonly kind: 'pause';
+    readonly pid: number;
+    readonly name: string;
+    readonly ms: number;
+};
+export interface Decision {
+    readonly state: GovernorState;
+    readonly actions: readonly Action[];
+    readonly level: Level;
+    readonly ramFreePercent: number;
+    readonly commitPercent: number;
+}
+export declare const PAUSE_MS = 5000;
+/**
+ * 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).
+ */
+export declare function decide(prev: GovernorState, sample: MemSample, nowMs: number, thresholds: GuestThresholds, profile: LoadProfile): Decision;

package/dist/guest/governor/decide.js

@@ -0,0 +1,182 @@
+/** Programs that compile or link: they may be slowed down and, as the last resort, paused for a few seconds. */
+const COMPILERS = new Set([
+    'rustc',
+    'clippy-driver',
+    'rustdoc',
+    'cc1',
+    'cc1plus',
+    'cc1obj',
+    'collect2',
+    'gcc',
+    'g++',
+    'c++',
+    'cc',
+    'clang',
+    'clang++',
+    'clang-cl',
+    'cl',
+    'link',
+    'lld',
+    'lld-link',
+    'ld',
+    'ld.lld',
+    'as',
+    'tsc',
+    'javac',
+]);
+/** Build tools and workers: slowed down but never paused (a node process may be a dev server or an agent). */
+const BUILD_TOOLS = new Set([
+    'node',
+    'dotnet',
+    'msbuild',
+    'vbcscompiler',
+    'ninja',
+    'make',
+    'mingw32-make',
+    'cmake',
+    'cargo',
+    'go',
+    'java',
+    'gradle',
+    'python',
+]);
+/** Never touched: the agents themselves, shells, terminals, this tool's own programs, Windows. */
+const NEVER = new Set([
+    'claude',
+    'codex',
+    'gemini',
+    'opencode',
+    'aider',
+    'cursor-agent',
+    'cmd',
+    'powershell',
+    'pwsh',
+    'bash',
+    'sh',
+    'zsh',
+    'git',
+    'conhost',
+    'openconsole',
+    'windowsterminal',
+    'wt',
+    'ptyhost',
+    'memgov',
+    'sandboxtools',
+    'sbx-db',
+    'explorer',
+    'csrss',
+    'wininit',
+    'winlogon',
+    'services',
+    'svchost',
+    'lsass',
+    'system',
+    'smss',
+    'dwm',
+]);
+const key = (name) => name.toLowerCase().replace(/\.exe$/, '');
+export const isNeverTouched = (name) => NEVER.has(key(name));
+export const canLower = (name) => !isNeverTouched(name) && (COMPILERS.has(key(name)) || BUILD_TOOLS.has(key(name)));
+export const canPause = (name) => !isNeverTouched(name) && COMPILERS.has(key(name));
+export const INITIAL_STATE = {
+    pressure: false,
+    calm: 0,
+    samples: 0,
+    lowered: {},
+    pausedUntil: 0,
+    nextPauseAt: 0,
+    hostUntil: 0,
+};
+export const PAUSE_MS = 5000;
+const PAUSE_COOLDOWN_MS = 10000;
+/** Samples under pressure before programs go from below-normal to idle, and before one is paused. */
+const IDLE_AFTER = 3;
+const PAUSE_AFTER = 4;
+/** Only a program this big is worth pausing. */
+const PAUSE_MIN_MB = 300;
+/**
+ * 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).
+ */
+export function decide(prev, sample, nowMs, thresholds, profile) {
+    const ramFree = (sample.ramAvailMb / Math.max(1, sample.ramTotalMb)) * 100;
+    const commit = ((sample.commitLimitMb - sample.commitAvailMb) / Math.max(1, sample.commitLimitMb)) * 100;
+    const pcLow = nowMs < prev.hostUntil;
+    const low = ramFree < thresholds.enterAvailablePercent || commit > thresholds.enterCommitPercent || pcLow;
+    const recovered = ramFree > thresholds.exitAvailablePercent && commit < thresholds.exitCommitPercent && !pcLow;
+    let pressure = prev.pressure;
+    let calm = prev.calm;
+    let samples = prev.samples;
+    if (low) {
+        pressure = true;
+        calm = 0;
+        samples = prev.samples + 1;
+    }
+    else if (prev.pressure) {
+        calm = recovered ? prev.calm + 1 : 0;
+        if (calm >= thresholds.calmSamples) {
+            pressure = false;
+            calm = 0;
+            samples = 0;
+        }
+    }
+    const actions = [];
+    const present = new Set(sample.procs.map((p) => p.pid));
+    const lowered = {};
+    for (const [pid, to] of Object.entries(prev.lowered))
+        if (present.has(Number(pid)))
+            lowered[Number(pid)] = to;
+    if (pressure) {
+        const target = samples > IDLE_AFTER ? 'idle' : 'below';
+        for (const p of sample.procs) {
+            if (!canLower(p.name) || lowered[p.pid] === target)
+                continue;
+            // Already as low as asked (or lower): only remember it.
+            if (p.prio !== target && !(target === 'below' && p.prio === 'idle'))
+                actions.push({ kind: 'priority', pid: p.pid, name: p.name, to: target });
+            lowered[p.pid] = target;
+        }
+    }
+    else {
+        for (const p of sample.procs) {
+            if (!canLower(p.name))
+                continue;
+            // Where a program rests when nothing is wrong: compilers below normal in the gentle profile.
+            const base = profile === 'gentle' && canPause(p.name) ? 'below' : 'normal';
+            const was = lowered[p.pid];
+            if (prev.pressure && was !== undefined && was !== base) {
+                if (p.prio !== base)
+                    actions.push({ kind: 'priority', pid: p.pid, name: p.name, to: base });
+                if (base === 'normal')
+                    delete lowered[p.pid];
+                else
+                    lowered[p.pid] = base;
+            }
+            else if (!prev.pressure && base === 'below' && was === undefined) {
+                if (p.prio === 'normal')
+                    actions.push({ kind: 'priority', pid: p.pid, name: p.name, to: 'below' });
+                lowered[p.pid] = 'below';
+            }
+        }
+    }
+    let pausedUntil = prev.pausedUntil;
+    let nextPauseAt = prev.nextPauseAt;
+    if (pressure && samples >= PAUSE_AFTER && nowMs >= prev.nextPauseAt && nowMs >= prev.pausedUntil) {
+        const victim = [...sample.procs]
+            .filter((p) => canPause(p.name) && p.mb >= PAUSE_MIN_MB)
+            .sort((a, b) => b.mb - a.mb)[0];
+        if (victim) {
+            actions.push({ kind: 'pause', pid: victim.pid, name: victim.name, ms: PAUSE_MS });
+            pausedUntil = nowMs + PAUSE_MS;
+            nextPauseAt = pausedUntil + PAUSE_COOLDOWN_MS;
+        }
+    }
+    const level = nowMs < pausedUntil ? 'suspending' : pressure ? 'throttled' : 'ok';
+    return {
+        state: { pressure, calm, samples, lowered, pausedUntil, nextPauseAt, hostUntil: prev.hostUntil },
+        actions,
+        level,
+        ramFreePercent: Math.round(ramFree),
+        commitPercent: Math.round(commit),
+    };
+}

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

@@ -0,0 +1,42 @@
+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;
+    pause(pid: number, ms: number): void;
+}
+/** Everything a step changes outside the decision, behind injectable functions. */
+export interface GovernorDeps {
+    readonly port: GovernorPort;
+    readonly profile: LoadProfile;
+    readonly now: () => number;
+    /** A line in the memory log. */
+    readonly logLine: (line: string) => void;
+    /** run\pressure.json. */
+    readonly saveStatus: (status: PressureStatus) => 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;
+    private pausedName;
+    private pausedPid;
+    constructor(deps: GovernorDeps);
+    hostPressure(seconds: number, reason: string): void;
+    get current(): GovernorState;
+    onSample(sample: MemSample): void;
+    private apply;
+}
+/** The daemon's governor: on unless sandbox.pressureResponse is off. */
+export declare class Governor {
+    private core;
+    describe(): string;
+    start(): void;
+    /** The host's watchdog: this PC is low for a while. */
+    hostPressure(seconds: number, reason: string): void;
+}
+export declare const governor: Governor;