windows-development-sandbox 1.10.0 → 1.11.4

package/dist/host/engines/hcs/leftovers.js

@@ -0,0 +1,101 @@
+// HCS compute systems this tool left running (a crashed command: they are created to outlive their handle). Only
+// systems with our id prefix AND our Owner are ever listed or stopped; HcsHost.exe checks both again before it
+// terminates one. Nothing here runs unless the PC has the Host Compute Service.
+import path from 'node:path';
+import { z } from 'zod';
+import { errMsg, fail } from '../../../core/util/index.js';
+import { realHcsProbes, system32Dir } from './check.js';
+import { HCS_OWNER } from './documents.js';
+import { HcsHelper, builtHcsHostExe, isMySystemId } from './helper.js';
+export const LEFTOVER_DEPS = { current: null };
+function realDeps() {
+    return {
+        probes: realHcsProbes(),
+        helper: (root) => {
+            const exe = builtHcsHostExe(root);
+            return exe ? new HcsHelper(() => exe) : null;
+        },
+    };
+}
+const SystemListSchema = z.array(z
+    .object({
+    Id: z.string().max(300),
+    SystemType: z.string().max(100).optional(),
+    Owner: z.string().max(300).optional(),
+    State: z.string().max(100).optional(),
+    CreateTimestamp: z.string().max(100).optional(),
+})
+    .passthrough());
+/** The reason HCS cannot be there at all, or null. Looks only (service list, one file). */
+function noHcsReason(p) {
+    if (!p.isWindows())
+        return 'HCS only exists on Windows.';
+    if (!p.fileExists(path.join(system32Dir(), 'computecore.dll')) || p.serviceInstalled('vmcompute') === false)
+        return 'The Host Compute Service is not on this PC.';
+    return null;
+}
+/** Ours only: the id has our prefix and the system names us as its Owner. Anything else is never shown or touched. */
+function ownedSystems(helper) {
+    let list;
+    try {
+        list = JSON.parse(helper.enumerate().json || '[]');
+    }
+    catch (e) {
+        if (e instanceof SyntaxError)
+            return fail('The Host Compute Service answered with something that is not JSON.');
+        throw e;
+    }
+    const parsed = SystemListSchema.safeParse(list);
+    if (!parsed.success)
+        return [];
+    return parsed.data
+        .filter((s) => s.Owner === HCS_OWNER && isMySystemId(s.Id))
+        .map((s) => ({
+        id: s.Id,
+        kind: s.SystemType ?? 'unknown',
+        state: s.State ?? 'unknown',
+        since: s.CreateTimestamp && !Number.isNaN(Date.parse(s.CreateTimestamp)) ? s.CreateTimestamp : null,
+    }));
+}
+/**
+ * The compute systems of ours that exist now. Never builds HcsHost.exe: a PC that never used HCS has none, and
+ * nothing of ours can be running there.
+ */
+export function lookForLeftovers(storageRoot) {
+    const deps = LEFTOVER_DEPS.current ?? realDeps();
+    const none = noHcsReason(deps.probes);
+    if (none)
+        return { available: false, reason: none };
+    try {
+        const helper = deps.helper(storageRoot);
+        if (!helper)
+            return { available: true, systems: [] };
+        return { available: true, systems: ownedSystems(helper) };
+    }
+    catch (e) {
+        return { available: false, reason: 'The Host Compute Service could not be asked: ' + errMsg(e) };
+    }
+}
+/**
+ * Stops the named systems, containers before the utility VM that hosts them. Each id is looked up again first: one that
+ * is not one of ours (or is gone) never reaches the helper; the helper checks the Owner with HCS itself once more.
+ */
+export function stopLeftovers(storageRoot, ids) {
+    const deps = LEFTOVER_DEPS.current ?? realDeps();
+    const helper = deps.helper(storageRoot);
+    if (!helper)
+        return ids.map((id) => ({ id, stopped: false, problem: 'HcsHost.exe is not available.' }));
+    const now = ownedSystems(helper);
+    const wanted = [...ids].sort((a, b) => Number(b.endsWith('-c')) - Number(a.endsWith('-c')));
+    return wanted.map((id) => {
+        if (!now.some((s) => s.id === id))
+            return { id, stopped: false, problem: 'it is gone, or it is not one of ours' };
+        try {
+            helper.terminate(id);
+            return { id, stopped: true };
+        }
+        catch (e) {
+            return { id, stopped: false, problem: errMsg(e) };
+        }
+    });
+}

package/dist/host/engines/index.d.ts

@@ -5,3 +5,4 @@ export { WindowsSandboxEngine } from './windows-sandbox/engine.js';
 export { wsbText } from './windows-sandbox/wsb-text.js';
 export { HcsEngine, HCS_CAPABILITIES, hcsStartEnabled } from './hcs/engine.js';
 export { checkHcs, realHcsProbes, type HcsProbes } from './hcs/check.js';
+export { lookForLeftovers, stopLeftovers, LEFTOVER_DEPS, type LeftoverDeps, type LeftoverLook, type LeftoverOutcome, type LeftoverSystem, } from './hcs/leftovers.js';

package/dist/host/engines/index.js

@@ -3,3 +3,4 @@ export { WindowsSandboxEngine } from './windows-sandbox/engine.js';
 export { wsbText } from './windows-sandbox/wsb-text.js';
 export { HcsEngine, HCS_CAPABILITIES, hcsStartEnabled } from './hcs/engine.js';
 export { checkHcs, realHcsProbes } from './hcs/check.js';
+export { lookForLeftovers, stopLeftovers, LEFTOVER_DEPS, } from './hcs/leftovers.js';

package/dist/host/github/deliver.d.ts

@@ -0,0 +1,13 @@
+import type { BootWant } from '../../core/local-config/index.js';
+import type { Config } from '../../core/types.js';
+import { GithubToken } from './token.js';
+/** github.shareToken is on and git access is "full" for every project this sandbox boots with. */
+export declare function githubTokenAllowed(config: Config, others?: readonly BootWant[]): boolean;
+export interface GithubDelivery {
+    /** The token for the one-shot secrets file, when it is handed over. */
+    readonly token?: string;
+    /** What to tell you about it (never the token). */
+    readonly notes: readonly string[];
+}
+/** What this launch hands over. Never throws: a token that cannot be read is a note, and the launch goes on. */
+export declare function prepareGithubToken(config: Config, storageRoot: string, store?: GithubToken, others?: readonly BootWant[]): GithubDelivery;

package/dist/host/github/deliver.js

@@ -0,0 +1,51 @@
+import { GithubToken } from './token.js';
+/** The first project (the launch's own, then the others at boot) whose git access is not "full", or null. */
+function stricterProject(config, others) {
+    if (config.provisioning.git.access !== 'full')
+        return { name: '', access: config.provisioning.git.access };
+    const other = others.find((o) => o.config.provisioning.git.access !== 'full');
+    return other ? { name: other.name, access: other.config.provisioning.git.access } : null;
+}
+/** github.shareToken is on and git access is "full" for every project this sandbox boots with. */
+export function githubTokenAllowed(config, others = []) {
+    return config.github.shareToken && stricterProject(config, others) === null;
+}
+/** What this launch hands over. Never throws: a token that cannot be read is a note, and the launch goes on. */
+export function prepareGithubToken(config, storageRoot, store, others = []) {
+    if (!config.github.shareToken)
+        return { notes: [] };
+    const stricter = stricterProject(config, others);
+    if (stricter)
+        return {
+            notes: [
+                'github.shareToken is on, but git access is "' +
+                    stricter.access +
+                    '"' +
+                    (stricter.name ? ' for ' + stricter.name + ' (also in this sandbox)' : ' in this sandbox') +
+                    ', so your GitHub token was not handed over (it needs provisioning.git.access "full").',
+            ],
+        };
+    const tokens = store ?? new GithubToken(storageRoot);
+    let token;
+    try {
+        token = tokens.read();
+    }
+    catch {
+        // The reason may come from DPAPI or a damaged file; a fixed text is enough (and can never hold the token).
+        return {
+            notes: [
+                'Your saved GitHub token could not be read (only the Windows user that saved it can), so it was not handed over. Save it again: sandbox github login',
+            ],
+        };
+    }
+    if (!token)
+        return {
+            notes: ['github.shareToken is on, but no GitHub token is saved. Save one: sandbox github login'],
+        };
+    return {
+        token,
+        notes: [
+            'Your GitHub token is handed to this sandbox (github.shareToken): the agent can read it and use it for whatever it allows.',
+        ],
+    };
+}

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

@@ -0,0 +1,2 @@
+export { GithubToken, checkGithubToken, type TokenState } from './token.js';
+export { githubTokenAllowed, prepareGithubToken, type GithubDelivery } from './deliver.js';

package/dist/host/github/index.js

@@ -0,0 +1,3 @@
+// The GitHub token for sandboxes: its encrypted store and whether a launch hands it over.
+export { GithubToken, checkGithubToken } from './token.js';
+export { githubTokenAllowed, prepareGithubToken } from './deliver.js';

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

@@ -0,0 +1,21 @@
+import { type GithubTokenKind } from '../../shared/github/index.js';
+import { SecretStore } from '../secrets/index.js';
+/** What the status may say about the token: never its value. */
+export type TokenState = 'none' | 'saved' | 'unreadable';
+/** The token's kind, or a refusal that says what to do (the message never holds what was typed). */
+export declare function checkGithubToken(token: string): GithubTokenKind;
+export declare class GithubToken {
+    private readonly storageRoot;
+    private readonly secrets;
+    constructor(storageRoot: string, secrets?: SecretStore);
+    private file;
+    /** Checks, encrypts and saves the token (replacing an earlier one). Returns its kind. */
+    save(token: string): GithubTokenKind;
+    /** The token, decrypted. Only the launch calls this; throws when this Windows user cannot open it. */
+    read(): string | null;
+    /** Whether a token is saved and can be decrypted by this Windows user (the value is never returned). */
+    state(): TokenState;
+    savedAt(): string | null;
+    kind(): GithubTokenKind | null;
+    remove(): boolean;
+}

package/dist/host/github/token.js

@@ -0,0 +1,74 @@
+// The GitHub token you saved for sandboxes (github.shareToken), kept encrypted with Windows DPAPI in host-only storage
+// (<storage>\github\token.json). It is read only when a sandbox starts, to hand to the sandbox in a one-shot file, and
+// is never printed, logged or returned to a surface: they only learn its state, kind and when it was saved.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { JsonFile } from '../../shared/io/index.js';
+import { GITHUB_TOKEN_KINDS, GithubTokenSchema, githubTokenKind, githubTokenProblem, } from '../../shared/github/index.js';
+import { fail } from '../../core/util/index.js';
+import { SecretStore } from '../secrets/index.js';
+const SavedSchema = z.object({
+    savedAt: z.string().max(64),
+    kind: z.enum(GITHUB_TOKEN_KINDS),
+    sealed: z.string().max(10000),
+});
+/** The token's kind, or a refusal that says what to do (the message never holds what was typed). */
+export function checkGithubToken(token) {
+    const problem = githubTokenProblem(token);
+    if (problem)
+        fail(problem.message, problem.fix);
+    return githubTokenKind(token) ?? fail('That is not a GitHub personal access token.', 'Run: sandbox github login');
+}
+export class GithubToken {
+    storageRoot;
+    secrets;
+    constructor(storageRoot, secrets = SecretStore.standard()) {
+        this.storageRoot = storageRoot;
+        this.secrets = secrets;
+    }
+    file() {
+        return new JsonFile(SavedSchema, path.join(this.storageRoot, 'github', 'token.json'));
+    }
+    /** Checks, encrypts and saves the token (replacing an earlier one). Returns its kind. */
+    save(token) {
+        const kind = checkGithubToken(token);
+        this.file().write({ savedAt: new Date().toISOString(), kind, sealed: this.secrets.sealJson({ token }) });
+        return kind;
+    }
+    /** The token, decrypted. Only the launch calls this; throws when this Windows user cannot open it. */
+    read() {
+        const saved = this.file().read();
+        if (!saved)
+            return null;
+        const value = this.secrets.openJson(saved.sealed);
+        const token = GithubTokenSchema.safeParse(value?.token);
+        if (!token.success)
+            fail('The saved GitHub token is damaged.', 'Save it again with: sandbox github login');
+        return token.data;
+    }
+    /** Whether a token is saved and can be decrypted by this Windows user (the value is never returned). */
+    state() {
+        if (!this.file().read())
+            return 'none';
+        try {
+            return this.read() ? 'saved' : 'none';
+        }
+        catch {
+            return 'unreadable';
+        }
+    }
+    savedAt() {
+        return this.file().read()?.savedAt ?? null;
+    }
+    kind() {
+        return this.file().read()?.kind ?? null;
+    }
+    remove() {
+        const file = this.file().file;
+        if (!fs.existsSync(file))
+            return false;
+        fs.rmSync(file, { force: true });
+        return true;
+    }
+}

package/dist/host/launch/generate.js

@@ -9,6 +9,7 @@ import { dirExists, ensureDir, fail, writeJson } from '../../core/util/index.js'
 import { engineFor } from '../engines/index.js';
 import { capturePersonalization, stageClaudeProfile } from '../profile/index.js';
 import { clearSecrets, writeSecrets } from '../secrets/index.js';
+import { githubTokenAllowed } from '../github/index.js';
 import { folderAttachment } from '../storage/providers/index.js';
 import { assertTestWritable } from '../test-guard.js';
 import { writeLoadSettings } from '../life/watchdog.js';
@@ -20,7 +21,7 @@ import { guestSession, logonEnv } from './session-file.js';
 import { copyRuntime, stageGitIdentity, stageHooks } from './stage.js';
 import { decideProjectToolchains } from './toolchains.js';
 import { buildLaunchPlan } from './launch-plan.js';
-import { decideMemory, GUEST, memoryNote, resolveMemoryMb } from './wsb-file.js';
+import { cappedMemoryMb, decideMemory, GUEST, memoryNote, residentNote, resolveMemoryMb } from './wsb-file.js';
 const NO_PROFILE = { hostDir: null, staged: [], skipped: [], credentials: false, secretsRemoved: [] };
 /** Moves the staged copy of this PC's Claude login out of the launch folder; its text goes in the one-shot file. */
 function takeStagedCredentials(launchPath) {
@@ -59,7 +60,9 @@ opened) {
     assertTestWritable(dataPath);
     // Checked before anything is written, so a refusal leaves nothing behind.
     const commitAvailableMb = o.commitAvailableMb ?? null;
-    const memoryMb = Math.max(resolveMemoryMb(config.sandbox, o.freeMemoryBytes, undefined, commitAvailableMb), ...others.map((p) => (typeof p.config.sandbox.memoryMb === 'number' ? p.config.sandbox.memoryMb : 0)));
+    const askedMb = Math.max(resolveMemoryMb(config.sandbox, o.freeMemoryBytes, undefined, commitAvailableMb), ...others.map((p) => (typeof p.config.sandbox.memoryMb === 'number' ? p.config.sandbox.memoryMb : 0)));
+    // Never more than this PC can keep in RAM for it, whatever was asked.
+    const memoryMb = cappedMemoryMb(askedMb, config.sandbox, Math.floor(os.totalmem() / 1048576));
     const launchId = Date.now() + '-' + crypto.randomBytes(3).toString('hex');
     const launchPath = path.join(storageRoot, 'launches', launchId);
     // Whatever must stay secret goes in a one-shot file in the data folder, never into the launch folder (the sandbox
@@ -104,6 +107,8 @@ opened) {
         ...(claudeCredentials ? { claudeCredentials } : {}),
         ...(o.vpn?.credentials ? { vpn: o.vpn.credentials } : {}),
         ...(o.vpn?.wireguardConfig ? { wireguardConfig: o.vpn.wireguardConfig } : {}),
+        // Checked again on the configs the sandbox boots with: never when a project in it has git access below "full".
+        ...(o.githubToken && githubTokenAllowed(config, others) ? { githubToken: o.githubToken } : {}),
     });
     fs.writeFileSync(path.join(launchPath, 'env.cmd'), logonEnv(session.workspace), 'utf8');
     copyRuntime(o.packageRoot, launchPath);
@@ -127,9 +132,10 @@ opened) {
         launchId,
         sessionPath,
         memoryMb,
-        memoryNote: config.sandbox.memoryMb === 'auto'
-            ? memoryNote(decideMemory(config.sandbox, Math.floor((o.freeMemoryBytes ?? os.freemem()) / 1048576), Math.floor(os.totalmem() / 1048576), commitAvailableMb))
-            : null,
+        memoryNote: residentNote(askedMb, memoryMb) ??
+            (config.sandbox.memoryMb === 'auto'
+                ? memoryNote(decideMemory(config.sandbox, Math.floor((o.freeMemoryBytes ?? os.freemem()) / 1048576), Math.floor(os.totalmem() / 1048576), commitAvailableMb))
+                : null),
         bootConfig: config,
         widened: wide.widened,
         mappings,

package/dist/host/launch/index.d.ts

@@ -1,7 +1,7 @@
 export { generateSandbox } from './generate.js';
 export { decideProjectToolchains } from './toolchains.js';
 export { hostToolsOf, logonEnv } from './session-file.js';
-export { agentMemoryLimitMb, decideMemory, GUEST, memoryNote, resolveMemoryMb } from './wsb-file.js';
+export { cappedMemoryMb, decideMemory, GUEST, memoryNote, residentCapMb, residentNote, resolveMemoryMb, } from './wsb-file.js';
 export { GENTLE_NOTE, vgpuSource, vgpuWarning } from './risk-notes.js';
 export { buildLaunchPlan, buildWsb } from './launch-plan.js';
 export { MAX_BOOT_PROJECTS, planBootProjects, shownByRoot, type BootProjects } from './boot-projects.js';

package/dist/host/launch/index.js

@@ -1,7 +1,7 @@
 export { generateSandbox } from './generate.js';
 export { decideProjectToolchains } from './toolchains.js';
 export { hostToolsOf, logonEnv } from './session-file.js';
-export { agentMemoryLimitMb, decideMemory, GUEST, memoryNote, resolveMemoryMb } from './wsb-file.js';
+export { cappedMemoryMb, decideMemory, GUEST, memoryNote, residentCapMb, residentNote, resolveMemoryMb, } from './wsb-file.js';
 export { GENTLE_NOTE, vgpuSource, vgpuWarning } from './risk-notes.js';
 export { buildLaunchPlan, buildWsb } from './launch-plan.js';
 export { MAX_BOOT_PROJECTS, planBootProjects, shownByRoot } from './boot-projects.js';

package/dist/host/launch/session-file.js

@@ -5,7 +5,6 @@ import { resolveToolchains } from '../../core/detect/index.js';
 import { hubName, PROJECTS_GUEST, substDrives } from '../../shared/paths/index.js';
 import { hostClaudeDir } from '../profile/index.js';
 import { databaseCatalog } from './database-plan.js';
-import { agentMemoryLimitMb } from './wsb-file.js';
 import { effectiveCpuLimit } from '../../shared/memory/index.js';
 import { loadProfileOf } from './risk-notes.js';
 /** What was found on this PC to copy instead of download. */
@@ -65,7 +64,7 @@ export function guestSession(o, parts) {
         cpuLimitPercent: effectiveCpuLimit(config.sandbox.cpuLimit, loadProfileOf(config)),
         loadProfile: loadProfileOf(config),
         pageFileMb: config.sandbox.pageFileMb,
-        agentMemoryLimitMb: agentMemoryLimitMb(parts.memoryMb, config.sandbox.agentMemoryHeadroomMb),
+        agentBackstop: config.sandbox.agentMemoryHeadroomMb,
         pressureResponse: config.sandbox.pressureResponse,
         apps: config.apps,
         auditProcesses: config.audit.enabled && config.audit.processes,

package/dist/host/launch/wsb-file.d.ts

@@ -6,7 +6,7 @@ export declare const GUEST: {
     readonly mirror: "C:\\Mirror";
 };
 type SandboxSettings = Config['sandbox'];
-export type MemoryLimit = 'free' | 'share' | 'max' | 'commit';
+export type MemoryLimit = 'free' | 'share' | 'max' | 'commit' | 'resident';
 export interface MemoryDecision {
     readonly mb: number;
     /** What set the size. */
@@ -17,18 +17,22 @@ export interface MemoryDecision {
     readonly freeMb: number;
     readonly commitAvailableMb: number | null;
 }
+/**
+ * The most memory this PC can keep in RAM for the sandbox (pure): its RAM minus max(reserveHostMb, 25 %), and 2 GB
+ * more with vGPU. Windows Sandbox's memory is this PC's memory taken as needed; beyond what the PC can keep resident it
+ * is paged to this PC's disk while the sandbox pages to its own, and that is what can freeze the whole PC.
+ */
+export declare function residentCapMb(sandbox: SandboxSettings, totalMb: number): number;
+/** A fixed memoryMb above what this PC can keep resident is lowered to that (never below 4 GB). */
+export declare function cappedMemoryMb(memoryMb: number, sandbox: SandboxSettings, totalMb: number): number;
+/** The launch note when a fixed memoryMb was lowered. */
+export declare function residentNote(asked: number, given: number): string | null;
 /**
  * "auto" (pure): free RAM minus the reserve, never more than maxMemoryMb or maxMemoryPercent of the PC's total RAM,
  * and, when the PC's available commit (RAM plus paging file, what the sandbox's memory is charged against) is known,
  * never more than that minus the reserve either.
  */
 export declare function decideMemory(sandbox: SandboxSettings, freeMb: number, totalMb: number, commitAvailableMb: number | null): MemoryDecision;
-/**
- * The most memory everything the agents start may use together (pure): the sandbox's memory minus the headroom
- * ("auto" =
- * the larger of 2048 MB and 10 %), at least half of it so a tiny sandbox still works; null = no limit ("none").
- */
-export declare function agentMemoryLimitMb(memoryMb: number, headroom: SandboxSettings['agentMemoryHeadroomMb']): number | null;
 /** A plain-words note when the commit made the sandbox's memory much smaller (2 GB or more) than free RAM allowed. */
 export declare function memoryNote(decision: MemoryDecision): string | null;
 /** "auto": see decideMemory. commitAvailableMb: from HostTools memory-status (omitted = not checked). */

package/dist/host/launch/wsb-file.js

@@ -11,6 +11,34 @@ export const GUEST = {
 const MB = 1048576;
 const MIN_AUTO_MEMORY_MB = 4096;
 const roundDown = (mb) => Math.floor(mb / 1024) * 1024;
+/** GPU-PV (vGPU) needs room of its own on this PC: memory the graphics driver pins for the sandbox. */
+const VGPU_RESERVE_MB = 2048;
+/**
+ * The most memory this PC can keep in RAM for the sandbox (pure): its RAM minus max(reserveHostMb, 25 %), and 2 GB
+ * more with vGPU. Windows Sandbox's memory is this PC's memory taken as needed; beyond what the PC can keep resident it
+ * is paged to this PC's disk while the sandbox pages to its own, and that is what can freeze the whole PC.
+ */
+export function residentCapMb(sandbox, totalMb) {
+    const keep = Math.max(sandbox.reserveHostMb, Math.floor(totalMb / 4)) + (sandbox.vGpu ? VGPU_RESERVE_MB : 0);
+    return roundDown(totalMb - keep);
+}
+/** A fixed memoryMb above what this PC can keep resident is lowered to that (never below 4 GB). */
+export function cappedMemoryMb(memoryMb, sandbox, totalMb) {
+    const cap = residentCapMb(sandbox, totalMb);
+    return cap >= MIN_AUTO_MEMORY_MB && memoryMb > cap ? cap : memoryMb;
+}
+/** The launch note when a fixed memoryMb was lowered. */
+export function residentNote(asked, given) {
+    if (given >= asked)
+        return null;
+    return ('sandbox.memoryMb asks for ' +
+        asked +
+        ' MB; this PC can keep ' +
+        given +
+        ' MB in RAM for the sandbox (its RAM minus what it needs itself), so the sandbox gets ' +
+        given +
+        " MB. More would be paged to this PC's disk, which can freeze the whole PC.");
+}
 /**
  * "auto" (pure): free RAM minus the reserve, never more than maxMemoryMb or maxMemoryPercent of the PC's total RAM,
  * and, when the PC's available commit (RAM plus paging file, what the sandbox's memory is charged against) is known,
@@ -25,22 +53,12 @@ export function decideMemory(sandbox, freeMb, totalMb, commitAvailableMb) {
         ['share', shareMb],
         ['free', byFree],
         ['commit', byCommit],
+        ['resident', residentCapMb(sandbox, totalMb)],
     ];
     const lowest = candidates.reduce((a, b) => (b[1] < a[1] ? b : a));
-    const withoutCommit = roundDown(Math.min(sandbox.maxMemoryMb, shareMb, byFree));
+    const withoutCommit = roundDown(Math.min(sandbox.maxMemoryMb, shareMb, byFree, residentCapMb(sandbox, totalMb)));
     return { mb: roundDown(lowest[1]), limitedBy: lowest[0], withoutCommitMb: withoutCommit, freeMb, commitAvailableMb };
 }
-/**
- * The most memory everything the agents start may use together (pure): the sandbox's memory minus the headroom
- * ("auto" =
- * the larger of 2048 MB and 10 %), at least half of it so a tiny sandbox still works; null = no limit ("none").
- */
-export function agentMemoryLimitMb(memoryMb, headroom) {
-    if (headroom === 'none')
-        return null;
-    const keep = headroom === 'auto' ? Math.max(2048, Math.floor(memoryMb / 10)) : headroom;
-    return Math.max(Math.floor(memoryMb / 2), memoryMb - keep);
-}
 /** A plain-words note when the commit made the sandbox's memory much smaller (2 GB or more) than free RAM allowed. */
 export function memoryNote(decision) {
     if (decision.limitedBy !== 'commit' || decision.withoutCommitMb - decision.mb < 2048)

package/dist/host/life/host-memory.d.ts

@@ -17,6 +17,24 @@ export type HostMemory = z.output<typeof HostMemorySchema>;
 export declare function parseHostMemory(text: string): HostMemory | null;
 /** This PC's memory now, or null when it cannot be read (and always during the self-test: it never asks Windows). */
 export declare function readHostMemory(storageRoot: string): HostMemory | null;
+/**
+ * One long-running `HostTools memory-status --serve` for the watcher: a reading every `seconds`, instead of starting a
+ * program (and building a disk counter) for each one. Without HostTools.exe it does nothing and `latest()` stays null.
+ */
+export declare class HostMemoryStream {
+    private readonly storageRoot;
+    private readonly seconds;
+    private child;
+    private last;
+    private startedAt;
+    private stopped;
+    constructor(storageRoot: string, seconds: number);
+    start(): void;
+    /** The newest reading while it is fresh; starts the stream again when it ended (at most once a minute). */
+    latest(): HostMemory | null;
+    /** Ends it (closing its input ends HostTools). */
+    stop(): void;
+}
 /** The same without blocking: for the watcher, which must never wait on it. */
 export declare function readHostMemoryAsync(storageRoot: string): Promise<HostMemory | null>;
 /** How low this PC's memory is: what the host watchdog acts on (pure). */

package/dist/host/life/host-memory.js

@@ -47,6 +47,72 @@ export function readHostMemory(storageRoot) {
     const result = spawnSync(file, args, { encoding: 'utf8', windowsHide: true, timeout: TIMEOUT_MS });
     return parseHostMemory(result.stdout || '');
 }
+/** A reading older than this is not used (the stream stopped answering): the watcher asks once instead. */
+const STREAM_FRESH_MS = 30000;
+/** A stream that ended is started again at most this often. */
+const STREAM_RESTART_MS = 60000;
+/**
+ * One long-running `HostTools memory-status --serve` for the watcher: a reading every `seconds`, instead of starting a
+ * program (and building a disk counter) for each one. Without HostTools.exe it does nothing and `latest()` stays null.
+ */
+export class HostMemoryStream {
+    storageRoot;
+    seconds;
+    child = null;
+    last = null;
+    startedAt = 0;
+    stopped = false;
+    constructor(storageRoot, seconds) {
+        this.storageRoot = storageRoot;
+        this.seconds = seconds;
+    }
+    start() {
+        if (!isWin || selfTestRunning() || this.stopped || this.child)
+            return;
+        const tools = hostToolsExe(this.storageRoot);
+        if (!tools)
+            return;
+        this.startedAt = Date.now();
+        try {
+            const child = spawn(tools, ['memory-status', '--serve', String(this.seconds)], {
+                windowsHide: true,
+                stdio: ['pipe', 'pipe', 'ignore'],
+            });
+            this.child = child;
+            let buffer = '';
+            child.stdout.setEncoding('utf8');
+            child.stdout.on('data', (chunk) => {
+                buffer = (buffer + chunk).slice(-16384);
+                let end;
+                while ((end = buffer.indexOf('\n')) >= 0) {
+                    const memory = parseHostMemory(buffer.slice(0, end).trim());
+                    buffer = buffer.slice(end + 1);
+                    if (memory)
+                        this.last = { at: Date.now(), memory };
+                }
+            });
+            child.stdin.on('error', () => undefined);
+            child.on('error', () => (this.child = null));
+            child.on('exit', () => (this.child = null));
+        }
+        catch {
+            // Could not start it: the watcher asks the old way.
+            this.child = null;
+        }
+    }
+    /** The newest reading while it is fresh; starts the stream again when it ended (at most once a minute). */
+    latest() {
+        if (!this.child && Date.now() - this.startedAt >= STREAM_RESTART_MS)
+            this.start();
+        return this.last && Date.now() - this.last.at < STREAM_FRESH_MS ? this.last.memory : null;
+    }
+    /** Ends it (closing its input ends HostTools). */
+    stop() {
+        this.stopped = true;
+        this.child?.stdin?.end();
+        this.child = null;
+    }
+}
 /** The same without blocking: for the watcher, which must never wait on it. */
 export function readHostMemoryAsync(storageRoot) {
     if (!isWin || selfTestRunning())

package/dist/host/life/watchdog.d.ts

@@ -3,6 +3,8 @@ import { type HostThresholds, type LoadProfile } from '../../shared/memory/index
 import { type HostMemory } from './host-memory.js';
 export interface WatchdogState {
     readonly low: boolean;
+    /** Nearly out of memory: the request asks for the governor's last step. */
+    readonly severe: boolean;
     readonly calm: number;
     /** Seconds the CPU has been above the limit. */
     readonly cpuHighSeconds: number;
@@ -31,6 +33,8 @@ export interface WatchdogStep {
     readonly send: boolean;
     /** Why the PC is low (plain words), empty when it is not. */
     readonly reason: string;
+    /** Nearly out of memory: builds go to the governor's last step. */
+    readonly severe: boolean;
     /** The state changed (the log says so). */
     readonly changed: boolean;
 }
@@ -40,6 +44,11 @@ export interface WatchdogStep {
  * `scale` widens the limits (1.25 = the level it must climb back above).
  */
 export declare function lowReason(memory: HostMemory, reserveHostMb: number, t: HostThresholds, scale: number): string;
+/**
+ * Nearly out of memory on this PC: under 1.5 GB of RAM free, or commit within max(2 GB, 4 %) of its limit. Then the
+ * sandbox's builds go to the governor's last step at once (one compiler at a time, 15 % CPU) until it passes.
+ */
+export declare function severeHost(memory: HostMemory): boolean;
 /** One watchdog step. Hysteresis: low starts at the limits and ends above 1.25 times them for calmSamples samples. */
 export declare function watchdogStep(prev: WatchdogState, input: WatchdogInput): WatchdogStep;
 /** Total CPU use between two os.cpus() readings (percent). */

package/dist/host/life/watchdog.js

@@ -5,6 +5,7 @@ import { HOST_THRESHOLDS } from '../../shared/memory/index.js';
 import { hostMemoryLine } from './host-memory.js';
 export const WATCHDOG_START = {
     low: false,
+    severe: false,
     calm: 0,
     cpuHighSeconds: 0,
     diskHighSeconds: 0,
@@ -27,6 +28,17 @@ export function lowReason(memory, reserveHostMb, t, scale) {
         return 'only ' + memory.commitAvailableMb + ' MB of memory (RAM plus paging file) is left on this PC';
     return '';
 }
+/**
+ * Nearly out of memory on this PC: under 1.5 GB of RAM free, or commit within max(2 GB, 4 %) of its limit. Then the
+ * sandbox's builds go to the governor's last step at once (one compiler at a time, 15 % CPU) until it passes.
+ */
+export function severeHost(memory) {
+    return (memory.availableMb < SEVERE_AVAILABLE_MB ||
+        memory.commitAvailableMb < Math.max(SEVERE_COMMIT_MB, (memory.commitLimitMb * SEVERE_COMMIT_PERCENT) / 100));
+}
+const SEVERE_AVAILABLE_MB = 1536;
+const SEVERE_COMMIT_MB = 2048;
+const SEVERE_COMMIT_PERCENT = 4;
 /** One watchdog step. Hysteresis: low starts at the limits and ends above 1.25 times them for calmSamples samples. */
 export function watchdogStep(prev, input) {
     const t = HOST_THRESHOLDS[input.profile];
@@ -54,10 +66,13 @@ export function watchdogStep(prev, input) {
             calm = 0;
         }
     }
-    const send = low && input.nowMs - prev.lastSentAt >= RESEND_MS;
+    const severe = low && input.memory !== null && severeHost(input.memory);
+    // Getting severe is sent at once; otherwise the request is repeated every RESEND_MS while the PC stays low.
+    const send = low && (input.nowMs - prev.lastSentAt >= RESEND_MS || (severe && !prev.severe));
     return {
         state: {
             low,
+            severe,
             calm,
             cpuHighSeconds: cpuHigh,
             diskHighSeconds: diskHigh,
@@ -65,6 +80,7 @@ export function watchdogStep(prev, input) {
         },
         send,
         reason: reason || (low ? 'this PC is still low' : ''),
+        severe,
         changed: low !== prev.low,
     };
 }