windows-development-sandbox 1.5.0 → 1.9.0

package/dist/guest/boot/boot.js

@@ -5,6 +5,9 @@ import { spawn } from 'node:child_process';
 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 { 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';
 import { syncClaudeProfile } from '../setup/claude-profile.js';
@@ -20,6 +23,7 @@ import { pruneToolLeftovers } from '../toolchains/leftovers.js';
 import { wanted } from '../toolchains/detect.js';
 import { configureVscode } from '../toolchains/tools/vscode.js';
 import { enableProcessAudit } from '../audit/process-audit.js';
+import { setupVpn } from '../vpn/index.js';
 import { now } from '../../shared/channel/run-dir.js';
 import { writeJsonAtomic } from '../../shared/io/json.js';
 import { viewSession } from '../sessions/viewer.js';
@@ -29,9 +33,10 @@ import { dryRun, isWin, localDir, logsDir, run, toolsDir } from '../runtime/path
 import { log, logPath, warn } from '../runtime/log.js';
 import { mkdirp } from '../runtime/fs.js';
 import { session, workspace } from '../runtime/session.js';
+import { applyBootEnvironment, BOOT_SECRETS_VARIABLE, takeSecrets } from '../runtime/secrets.js';
 import { setSandboxStatus } from '../runtime/status.js';
 import { errMsg } from '../../core/util/errors.js';
-const STEPS = 8;
+const STEPS = 9;
 const PRIMARY_POLLS = 600;
 const POLL_MS = 500;
 const VSCODE_LANGUAGES = ['python', 'java', 'go', 'rust', 'cpp', 'msvc', 'dotnet', 'ruby', 'php', 'deno', 'pwsh'];
@@ -56,12 +61,19 @@ async function soft(what, work) {
         warn(what + ' failed (continuing): ' + errMsg(e));
     }
 }
-function startDaemon(env) {
+function startDaemon(env, secrets) {
     spawn(process.execPath, [path.join(path.dirname(process.argv[1]), 'daemon.js')], {
         detached: true,
         stdio: 'ignore',
         windowsHide: true,
-        env: { ...env, AGENT_LOG_PREFIX: 'daemon' },
+        env: {
+            ...env,
+            AGENT_LOG_PREFIX: 'daemon',
+            // The agent's environment (it may hold API keys): the daemon moves it into memory and removes this at once.
+            ...(secrets.harnessEnvironment
+                ? { [BOOT_SECRETS_VARIABLE]: JSON.stringify({ harnessEnvironment: secrets.harnessEnvironment }) }
+                : {}),
+        },
     }).unref();
 }
 /**
@@ -72,8 +84,19 @@ function writeDbCommand() {
     const dir = mkdirp(path.join(localDir, 'bin'));
     const db = path.join(path.dirname(process.argv[1]), 'db.js');
     fs.writeFileSync(path.join(dir, 'sbx-db.cmd'), '@setlocal\r\n@set AGENT_LOG_PREFIX=db\r\n@"' + process.execPath + '" "' + db + '" %*\r\n');
+    writeAgentCommands(dir);
     return dir;
 }
+/**
+ * `claude`, `codex` ... by name in every terminal tab, installed yet or not (the command installs the agent on first
+ * use), and `sbx-agent`. Written to the sandbox's disk each boot, next to `sbx-db`.
+ */
+function writeAgentCommands(dir) {
+    const install = { node: process.execPath, script: path.join(path.dirname(process.argv[1]), 'agent.js') };
+    for (const shim of agentShims(toolsDir, session.agents ?? {}))
+        fs.writeFileSync(path.join(dir, shim.command + '.cmd'), shimText(shim, install));
+    fs.writeFileSync(path.join(dir, 'sbx-agent.cmd'), sbxAgentText(install));
+}
 async function waitForPrimary() {
     for (let i = 0; i < PRIMARY_POLLS; i++) {
         const s = run.readSession(session.launchId);
@@ -97,6 +120,8 @@ export class Boot {
     ptyHost = null;
     lan = session.networking ? 'open' : 'offline';
     gitAccess = session.provisioning.git.access ?? 'full';
+    /** What the host handed over in its one-shot file (read and deleted at the start of run()). */
+    secrets = {};
     async run() {
         log('Agent sandbox: ' +
             session.project +
@@ -110,9 +135,12 @@ export class Boot {
             throw new Error('Workspace folder is missing in the sandbox: ' + workspace);
         mkdirp(toolsDir);
         mkdirp(run.root);
+        this.secrets = takeSecrets(session.launchId);
+        applyBootEnvironment(this.secrets.harnessEnvironment);
         await this.networkAndSessionHost();
         await this.hooksAndDesktop();
         const { tools, env } = await this.developerTools();
+        await this.vpn();
         await this.gitIdentity(env);
         await this.claude(tools);
         await this.agent(env);
@@ -165,6 +193,7 @@ export class Boot {
             }));
         const env = agentEnv(tools);
         persistEnvironment(env, Object.keys(tools.vars));
+        await soft('Shell start-up PATH', installShellPath);
         saveBootEnv({
             basePath,
             toolVars: Object.keys(tools.vars),
@@ -178,36 +207,47 @@ export class Boot {
         await soft('Cleaning old tool builds', () => pruneToolLeftovers());
         return { tools, env };
     }
+    /** vpn.enabled: the tunnel and its kill switch, before anything else uses the network (git, the agent). */
+    async vpn() {
+        step(4, session.vpn ? 'VPN (' + session.vpn.server + ')' : 'VPN (off)');
+        if (!session.vpn)
+            return;
+        await soft('VPN', async () => {
+            await setupVpn(this.secrets, this.ptyHost);
+        });
+    }
     async gitIdentity(env) {
-        step(4, 'Git identity');
+        step(5, 'Git identity');
         await soft('Git config', () => setupGitConfig(env));
     }
     async claude(tools) {
-        step(5, 'Claude settings, history and claude-mem');
+        step(6, 'Claude settings, history and claude-mem');
         if (session.harnessName === 'claude')
-            await soft('Claude settings', syncClaudeProfile);
+            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));
     }
     async agent(env) {
-        step(6, 'Agent: ' + session.harnessName);
+        step(7, 'Agent: ' + session.harnessName);
         linkProfileDirs(session.agentProfileDirs ?? {});
         if (session.harness)
             await agents.provision(session.harnessName, session.harness, env);
     }
     preAgentHooks(env) {
-        step(7, 'Pre-agent hooks');
+        step(8, 'Pre-agent hooks');
         runHooks('pre-agent', env);
     }
     /** Ready: starts the session daemon and, with an agent, its first session, shown in this window. */
     async start(env) {
-        step(8, 'Starting ' + session.harnessName);
+        step(9, 'Starting ' + session.harnessName);
         setSandboxStatus('ready', 'Ready');
         // No agent, or a restart that adds a project (the host opens its sessions itself once the sandbox is ready).
         if (!session.harness || session.autoSession === false) {
             if (!dryRun)
-                startDaemon(env);
+                startDaemon(env, this.secrets);
             log('Ready' + (session.harness ? '' : ' (no agent requested)') + '. Workspace: ' + workspace);
             return;
         }
@@ -220,7 +260,7 @@ export class Boot {
             runHooks('post-agent', env);
             return;
         }
-        startDaemon(env);
+        startDaemon(env, this.secrets);
         writeJsonAtomic(run.requestFile(session.launchId), {
             kind: 'session',
             id: session.launchId,

package/dist/guest/daemon/daemon.js

@@ -1,10 +1,13 @@
 // The session daemon's polling loop: claims each valid request in run\requests and hands it to its handler.
 import fs from 'node:fs';
 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';
 import { warn } from '../runtime/log.js';
 import { errMsg } from '../../core/util/errors.js';
 const POLL_MS = 400;
@@ -33,11 +36,12 @@ export class Daemon {
             if (run.readSession(req.id))
                 continue;
             // Not awaited: starting a session or running a command must not hold up other requests.
-            void Promise.resolve(this.handle(req)).catch((e) => respond(req.id, { ok: false, message: errMsg(e) }));
+            void Promise.resolve(this.handle(withRequestSecrets(req))).catch((e) => respond(req.id, { ok: false, message: errMsg(e) }));
         }
         if (Date.now() - this.lastMemSave > MEM_SAVE_MS) {
             this.lastMemSave = Date.now();
             safely('claude-mem save', saveClaudeMem);
+            safely('agent databases save', saveLocalState);
         }
     }
     handle(req) {
@@ -50,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/exec.js

@@ -2,6 +2,7 @@
 import { spawn } from 'node:child_process';
 import { SYSTEM } from '../../shared/system.js';
 import { exists } from '../runtime/fs.js';
+import { withRegistryPath } from '../setup/environment.js';
 import { errMsg } from '../../core/util/errors.js';
 import { provisioner } from './project-provisioner.js';
 import { insideWorkspace, respond } from './state.js';
@@ -20,7 +21,7 @@ export function execCommand(req) {
     }
     // chcp 65001 first: console programs then write UTF-8 (not the OEM code page) into the pipes.
     // In a project registered after boot, its own environment (its Node, Python, database variables).
-    const env = provisioner.provisionedFor(req.cwd)?.env ?? process.env;
+    const env = withRegistryPath(provisioner.provisionedFor(req.cwd)?.env ?? process.env);
     const child = spawn(SYSTEM.cmd(), ['/d', '/s', '/c', '"chcp 65001>nul & ' + req.command.map(quoteForCmd).join(' ') + '"'], { cwd: req.cwd, env, windowsHide: true, windowsVerbatimArguments: true });
     const output = { stdout: '', stderr: '' };
     // setEncoding decodes across chunks: a multi-byte character split between two reads is not mangled.

package/dist/guest/daemon/idle-shutdown.js

@@ -2,6 +2,7 @@
 import { spawnSync } from 'node:child_process';
 import { SYSTEM } from '../../shared/system.js';
 import { saveClaudeMem } from '../setup/claude-mem.js';
+import { saveLocalState } from '../agents/local-state.js';
 import { isWin, run } from '../runtime/paths.js';
 import { log } from '../runtime/log.js';
 import { session } from '../runtime/session.js';
@@ -25,6 +26,7 @@ export class IdleShutdown {
                 return;
             log('Headless sandbox has no sessions left; shutting down.');
             safely('claude-mem save', saveClaudeMem);
+            safely('agent databases save', saveLocalState);
             spawnSync(SYSTEM.shutdown(), ['/s', '/t', '5'], { windowsHide: true });
         }, GRACE_MS);
     }

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,19 +3,23 @@
 // (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';
 import { ensurePtyHost, ptyHostLogTail, startPtyHost, waitForPtyHost } from '../sessions/pty-host.js';
 import { agents } from '../agents/agent-installer.js';
 import { saveClaudeMem } from '../setup/claude-mem.js';
+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 { exists } from '../runtime/fs.js';
 import { log, warn } from '../runtime/log.js';
@@ -46,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);
@@ -64,7 +80,7 @@ const launchPtyHost = async (req, remote, env, say) => {
         rows: 32,
         id: req.id,
         cwd: req.cwd,
-        env: { ...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 ?? [])]),
@@ -143,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,
@@ -257,6 +273,7 @@ export class SessionManager {
         else
             safely('post-agent hooks', () => runHooks('post-agent', process.env));
         safely('claude-mem save', saveClaudeMem);
+        safely('agent databases save', saveLocalState);
         this.idle.check();
     }
 }

package/dist/guest/entries/agent.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/guest/entries/agent.js

@@ -0,0 +1,10 @@
+// `sbx-agent`: list agents and install a configured one inside the sandbox. Usage: sbx-agent list | install <agent>
+import { dropInheritedModulePath } from '../../shared/system.js';
+import { runSbxAgent } from '../agents/sbx-agent.js';
+dropInheritedModulePath();
+runSbxAgent(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (e) => {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exitCode = 1;
+});

package/dist/guest/entries/daemon.js

@@ -6,11 +6,16 @@ import { startRelays } from '../daemon/relays.js';
 import { startProcessCollector } from '../audit/process-audit.js';
 import { safely } from '../daemon/state.js';
 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;