windows-development-sandbox 1.5.0 → 1.9.0

package/dist/guest/governor/governor.js

@@ -0,0 +1,214 @@
+// The memory governor: samples the sandbox's memory every 2 seconds (memgov.exe, sandbox/csharp/MemGov.cs) and, when it
+// runs low, slows the heaviest build programs the agents started down and, as a last resort, pauses the biggest
+// compiler for a few seconds (decide.ts). What it does goes to the memory log and run\pressure.json, for the host.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { z } from 'zod';
+import { now } from '../../shared/channel/run-dir.js';
+import { writeJsonAtomic } from '../../shared/io/json.js';
+import { GUEST_THRESHOLDS } from '../../shared/memory/index.js';
+import { ensureCompiled } from '../runtime/csc.js';
+import { dataDir } from '../runtime/paths.js';
+import { warn } from '../runtime/log.js';
+import { run } from '../runtime/paths.js';
+import { session } from '../runtime/session.js';
+import { errMsg } from '../../core/util/errors.js';
+import { decide, INITIAL_STATE } from './decide.js';
+const SampleSchema = z.object({
+    ramTotalMb: z.number(),
+    ramAvailMb: z.number(),
+    commitLimitMb: z.number(),
+    commitAvailMb: z.number(),
+    procs: z
+        .array(z.object({
+        pid: z.number().int(),
+        name: z.string().max(128),
+        mb: z.number(),
+        prio: z.enum(['idle', 'below', 'normal']).catch('normal'),
+    }))
+        .max(1024),
+});
+/** 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;
+    pausedName = '';
+    pausedPid = 0;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    hostPressure(seconds, reason) {
+        const until = this.deps.now() + seconds * 1000;
+        if (until > this.state.hostUntil) {
+            if (this.state.hostUntil <= this.deps.now())
+                this.deps.logLine('governor: this PC is low (' + reason + '); slowing builds down');
+            this.state = { ...this.state, hostUntil: until };
+        }
+    }
+    get current() {
+        return this.state;
+    }
+    onSample(sample) {
+        const nowMs = this.deps.now();
+        const before = this.state.pressure;
+        const d = decide(this.state, sample, nowMs, GUEST_THRESHOLDS[this.deps.profile], this.deps.profile);
+        this.state = d.state;
+        for (const action of d.actions)
+            this.apply(action);
+        if (d.state.pressure !== before)
+            this.deps.logLine(d.state.pressure
+                ? 'governor: memory is low (' +
+                    d.ramFreePercent +
+                    '% RAM free, commit ' +
+                    d.commitPercent +
+                    '% used): slowing builds down'
+                : 'governor: memory is fine again: builds back to normal');
+        const paused = nowMs < d.state.pausedUntil && this.pausedPid
+            ? [{ name: this.pausedName, pid: this.pausedPid, seconds: Math.ceil((d.state.pausedUntil - nowMs) / 1000) }]
+            : [];
+        const status = {
+            level: d.level,
+            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,
+            pcLow: nowMs < d.state.hostUntil,
+            lastAction: this.lastAction,
+            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: 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) {
+        try {
+            if (action.kind === 'priority') {
+                this.deps.port.setPriority(action.pid, action.to);
+                this.lastAction = action.name + ' (' + action.pid + ') priority ' + action.to;
+            }
+            else {
+                this.deps.port.pause(action.pid, action.ms);
+                this.pausedName = action.name;
+                this.pausedPid = action.pid;
+                this.lastAction = 'paused ' + action.name + ' (' + action.pid + ') for ' + action.ms / 1000 + ' s';
+                this.deps.logLine('governor: ' + this.lastAction);
+                return;
+            }
+            this.deps.logLine('governor: ' + this.lastAction);
+        }
+        catch (e) {
+            warn('governor: ' + errMsg(e));
+        }
+    }
+}
+/** memgov.exe as a child process: samples come out of its stdout, commands go into its stdin. */
+class MemGovProcess {
+    onSample;
+    child = null;
+    constructor(onSample) {
+        this.onSample = onSample;
+    }
+    start() {
+        try {
+            const child = spawn(ensureCompiled('memgov'), ['serve', '--interval', '2'], {
+                stdio: ['pipe', 'pipe', 'ignore'],
+                windowsHide: true,
+            });
+            this.child = child;
+            createInterface({ input: child.stdout }).on('line', (line) => {
+                try {
+                    this.onSample(SampleSchema.parse(JSON.parse(line)));
+                }
+                catch (e) {
+                    warn('governor: bad sample: ' + errMsg(e));
+                }
+            });
+            child.stdin.on('error', () => undefined);
+            child.once('exit', () => {
+                this.child = null;
+                // It ends only when something is wrong: try again in a while.
+                setTimeout(() => this.start(), 30000).unref();
+            });
+        }
+        catch (e) {
+            warn('governor: could not start memgov.exe (no memory governor): ' + errMsg(e));
+        }
+    }
+    setPriority(pid, to) {
+        this.child?.stdin?.write('priority ' + pid + ' ' + to + '\n');
+    }
+    pause(pid, ms) {
+        this.child?.stdin?.write('suspend ' + pid + ' ' + ms + '\n');
+    }
+}
+/** The newest memory log SandboxTools writes, to add the governor's lines to it. */
+function appendToMemoryLog(line) {
+    try {
+        const logs = path.join(dataDir, 'logs');
+        const newest = fs
+            .readdirSync(logs)
+            .filter((f) => /^memory-\d{8}-\d{6}\.log$/.test(f))
+            .sort()
+            .pop();
+        if (!newest)
+            return;
+        const t = new Date();
+        const stamp = [t.getHours(), t.getMinutes(), t.getSeconds()].map((n) => String(n).padStart(2, '0')).join(':');
+        fs.appendFileSync(path.join(logs, newest), stamp + ' | ' + line + '\r\n');
+    }
+    catch {
+        // The log is for people; a missing or locked one never matters.
+    }
+}
+/** The daemon's governor: on unless sandbox.pressureResponse is off. */
+export class Governor {
+    core = null;
+    describe() {
+        const profile = session.loadProfile === 'gentle' ? 'gentle' : 'normal';
+        const t = GUEST_THRESHOLDS[profile];
+        return session.pressureResponse === false
+            ? 'off (sandbox.pressureResponse)'
+            : profile +
+                ' profile: slows builds down below ' +
+                t.enterAvailablePercent +
+                '% free RAM or above ' +
+                t.enterCommitPercent +
+                '% commit';
+    }
+    start() {
+        if (session.pressureResponse === false)
+            return;
+        const profile = session.loadProfile === 'gentle' ? 'gentle' : 'normal';
+        const proc = new MemGovProcess((s) => this.core?.onSample(s));
+        this.core = new GovernorCore({
+            port: proc,
+            profile,
+            now: () => Date.now(),
+            logLine: appendToMemoryLog,
+            saveStatus: (status) => {
+                try {
+                    writeJsonAtomic(run.pressureFile, status);
+                }
+                catch (e) {
+                    warn('governor: could not write its status: ' + errMsg(e));
+                }
+            },
+        });
+        proc.start();
+    }
+    /** The host's watchdog: this PC is low for a while. */
+    hostPressure(seconds, reason) {
+        this.core?.hostPressure(seconds, reason);
+    }
+}
+export const governor = new Governor();

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

@@ -0,0 +1,2 @@
+export * from './decide.js';
+export * from './governor.js';

package/dist/guest/governor/index.js

@@ -0,0 +1,2 @@
+export * from './decide.js';
+export * from './governor.js';

package/dist/guest/runtime/csc.d.ts

@@ -6,6 +6,8 @@ declare const SOURCES: {
     readonly openssl: "OpenSsl.cs";
     readonly cargoshim: "CargoShim.cs";
     readonly linkgate: "LinkGate.cs";
+    readonly pathsync: "PathSync.cs";
+    readonly memgov: "MemGov.cs";
 };
 export type Helper = keyof typeof SOURCES;
 /** %TEMP%\agent-sandbox\<name>-<hash>.exe, compiled from this launch's source the first time it is needed. */

package/dist/guest/runtime/csc.js

@@ -19,6 +19,8 @@ const SOURCES = {
     openssl: 'OpenSsl.cs',
     cargoshim: 'CargoShim.cs',
     linkgate: 'LinkGate.cs',
+    pathsync: 'PathSync.cs',
+    memgov: 'MemGov.cs',
 };
 function sourceOf(name) {
     return path.join(launchDir, 'sandbox', 'csharp', SOURCES[name]);

package/dist/guest/runtime/secrets.d.ts

@@ -0,0 +1,12 @@
+import type { GuestRequest } from '../../core/types.js';
+import { type SecretsFile } from '../../shared/channel/secrets.js';
+/** Where the boot's secrets travel from main.js to the daemon. */
+export declare const BOOT_SECRETS_VARIABLE = "SBX_BOOT_SECRETS";
+/** Reads and deletes <data>\secrets\<id>.json; nothing (or an unreadable file) gives {}. */
+export declare function takeSecrets(id: string): SecretsFile;
+/** The agent the sandbox booted with gets its environment (in memory only). */
+export declare function applyBootEnvironment(environment: Record<string, string> | undefined): void;
+/** The daemon takes what main.js passed it, and removes it from its own environment before any session starts. */
+export declare function adoptBootSecrets(): void;
+/** A request with the agent environment values that travelled in its own secrets file put back (in memory only). */
+export declare function withRequestSecrets(req: GuestRequest): GuestRequest;

package/dist/guest/runtime/secrets.js

@@ -0,0 +1,63 @@
+// The one-shot secrets the host handed over (shared/channel/secrets.ts): read once, the file deleted at once. What the
+// boot read for the agent is passed to the daemon in its own environment (SBX_BOOT_SECRETS, removed there at start), so
+// nothing waits on disk.
+import fs from 'node:fs';
+import { mergeRequestSecrets, SecretsFileSchema } from '../../shared/channel/secrets.js';
+import { run } from './paths.js';
+import { warn } from './log.js';
+import { session } from './session.js';
+/** Where the boot's secrets travel from main.js to the daemon. */
+export const BOOT_SECRETS_VARIABLE = 'SBX_BOOT_SECRETS';
+const MAX_BYTES = 4 * 1024 * 1024;
+/** Reads and deletes <data>\secrets\<id>.json; nothing (or an unreadable file) gives {}. */
+export function takeSecrets(id) {
+    const file = run.secretFile(id);
+    let text;
+    try {
+        if (fs.statSync(file).size > MAX_BYTES)
+            throw new Error('too big');
+        text = fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '');
+    }
+    catch {
+        return {};
+    }
+    finally {
+        fs.rmSync(file, { force: true });
+    }
+    try {
+        const parsed = SecretsFileSchema.safeParse(JSON.parse(text));
+        if (parsed.success)
+            return parsed.data;
+    }
+    catch {
+        // Not JSON: treated like an invalid file below.
+    }
+    warn('The secrets file for ' + id + ' was not valid and was ignored.');
+    return {};
+}
+/** The agent the sandbox booted with gets its environment (in memory only). */
+export function applyBootEnvironment(environment) {
+    if (session.harness && environment)
+        session.harness.environment = { ...environment };
+}
+/** The daemon takes what main.js passed it, and removes it from its own environment before any session starts. */
+export function adoptBootSecrets() {
+    const text = process.env[BOOT_SECRETS_VARIABLE];
+    delete process.env[BOOT_SECRETS_VARIABLE];
+    if (!text)
+        return;
+    try {
+        const parsed = SecretsFileSchema.pick({ harnessEnvironment: true }).safeParse(JSON.parse(text));
+        if (parsed.success)
+            applyBootEnvironment(parsed.data.harnessEnvironment);
+    }
+    catch {
+        warn('The boot secrets given to the daemon were not valid.');
+    }
+}
+/** A request with the agent environment values that travelled in its own secrets file put back (in memory only). */
+export function withRequestSecrets(req) {
+    if (req.kind !== 'session' && req.kind !== 'project')
+        return req;
+    return mergeRequestSecrets(req, takeSecrets(req.id));
+}

package/dist/guest/sessions/viewer.js

@@ -30,7 +30,9 @@ export async function viewSession(id) {
         return 1;
     }
     const socket = await connect({ ...session.attach, addresses: ['127.0.0.1'] });
-    const result = await runTerminalClient(socket, session.attach.token);
+    // The sandbox's own terminal: a copy in the agent reaches the sandbox's clipboard (and yours only through
+    // sandbox.clipboard, which already shares it).
+    const result = await runTerminalClient(socket, session.attach.token, { clipboardWrites: true });
     if (result.reason === 'exit')
         console.log(session.harness + ' exited with code ' + result.exitCode + '.');
     else if (result.reason === 'error')

package/dist/guest/setup/claude-profile.d.ts

@@ -4,4 +4,5 @@
  * Servers with the same name are replaced by this PC's definition; servers added inside the sandbox are kept.
  */
 export declare function mergeMcpServers(hostFile: string, guestFile: string, hostWorkspace: string, guestWorkspace: string): number;
-export declare function syncClaudeProfile(): void;
+/** `credentials`: the text of this PC's .credentials.json, handed over in the one-shot secrets file. */
+export declare function syncClaudeProfile(credentials?: string): void;

package/dist/guest/setup/claude-profile.js

@@ -57,7 +57,8 @@ export function mergeMcpServers(hostFile, guestFile, hostWorkspace, guestWorkspa
     writeJsonAtomic(guestFile, merged);
     return Object.keys(host.mcpServers ?? {}).length + Object.keys(hostProject).length;
 }
-export function syncClaudeProfile() {
+/** `credentials`: the text of this PC's .credentials.json, handed over in the one-shot secrets file. */
+export function syncClaudeProfile(credentials) {
     const profile = session.claudeProfile;
     if (profile.items.length === 0) {
         log('No Claude settings were staged from this PC.');
@@ -68,6 +69,16 @@ export function syncClaudeProfile() {
     for (const name of profile.items) {
         const from = path.join(source, name);
         const to = path.join(claudeDir, name);
+        if (name === '.credentials.json') {
+            // Never staged in the launch folder: it came in the secrets file.
+            if (credentials && !exists(to)) {
+                fs.writeFileSync(to, credentials, 'utf8');
+                log('Claude settings: copied ' + name + ' from this PC');
+            }
+            else
+                log("Claude settings: kept the sandbox's " + name);
+            continue;
+        }
         if (!exists(from))
             continue;
         if ((KEEP_SANDBOX_COPY.includes(name) || !profile.overwrite) && exists(to)) {

package/dist/guest/setup/environment.d.ts

@@ -14,3 +14,9 @@ export declare function persistEnvironment(env: NodeJS.ProcessEnv, toolVars: str
  * the boot project's terminals see never changes; the project's own sessions get its full environment anyway.
  */
 export declare function addMachineEnvironment(vars: Record<string, string>, dirs: string[], additive?: boolean): void;
+/**
+ * The environment for a program the daemon starts (an agent session, `sandbox exec`): its own PATH, plus every machine
+ * and user PATH folder added since the daemon started (python, cargo, other agents ...) at the end. Never changes
+ * `env`; without Windows it is returned as it is.
+ */
+export declare function withRegistryPath(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/guest/setup/environment.js

@@ -2,10 +2,14 @@
 import path from 'node:path';
 import { claudeDir, session, stateDir, workspace } from '../runtime/session.js';
 import { dataDir, dryRun, isWin, testMode, toolsDir } from '../runtime/paths.js';
-import { mkdirp } from '../runtime/fs.js';
-import { runScriptWithJson } from '../runtime/process.js';
+import { exists, mkdirp } from '../runtime/fs.js';
+import { execOutput, runScriptWithJson } from '../runtime/process.js';
+import { SYSTEM } from '../../shared/system.js';
 import { warn } from '../runtime/log.js';
 import { errMsg } from '../../core/util/errors.js';
+import { localStateVars } from '../agents/local-state.js';
+import { agentPaths } from '../agents/agent-files.js';
+import { appendMissing, expandVars, isPinnedNodeDir, parseRegPath, pathKey, planPath } from './path-plan.js';
 /** Older launch folders have no agentHomes: these two were always set. */
 const LEGACY_HOMES = { CODEX_HOME: 'codex', GEMINI_CLI_HOME: 'gemini' };
 /** Every agent's home variable (CODEX_HOME ...) with the folder it points to in the persistent state. */
@@ -31,6 +35,7 @@ export function agentEnv(tools, target = { workspace, project: session.project,
         ...tools.vars,
         CLAUDE_CONFIG_DIR: claudeDir,
         ...homes,
+        ...localStateVars(),
         npm_config_cache: path.join(toolsDir, 'npm-cache'),
         npm_config_update_notifier: 'false',
         AGENT_WORKSPACE: target.workspace,
@@ -41,7 +46,13 @@ export function agentEnv(tools, target = { workspace, project: session.project,
         AGENT_SANDBOX: '1',
         AGENT_SANDBOX_WORKSPACE: target.workspace,
     };
-    for (const dir of [env.CLAUDE_CONFIG_DIR, ...Object.keys(homes).map((n) => env[n]), env.npm_config_cache])
+    const local = Object.keys(localStateVars());
+    for (const dir of [
+        env.CLAUDE_CONFIG_DIR,
+        ...Object.keys(homes).map((n) => env[n]),
+        env.npm_config_cache,
+        ...local.map((n) => env[n]),
+    ])
         mkdirp(dir);
     // The runner's own Node (bootstrap.ps1 puts it first on PATH) is not exposed: `node` is whatever nvm selected.
     const runners = [path.join(toolsDir, 'node'), path.dirname(process.execPath)].map((d) => d.toLowerCase());
@@ -53,13 +64,17 @@ export function agentEnv(tools, target = { workspace, project: session.project,
 export function persistEnvironment(env, toolVars) {
     if (!isWin || dryRun || testMode)
         return;
-    const vars = Object.fromEntries([...toolVars, ...AGENT_VARS, ...Object.keys(agentHomes())]
+    const vars = Object.fromEntries([...toolVars, ...AGENT_VARS, ...Object.keys(agentHomes()), ...Object.keys(localStateVars())]
         .filter((n) => env[n] !== undefined)
         .map((n) => [n, env[n]]));
     try {
         runScriptWithJson('set-machine-environment.ps1', 'SettingsFile', {
             vars,
-            path: env.PATH ?? '',
+            path: planPath({
+                entries: [env.PATH ?? '', ...installedAgentDirs()],
+                exists,
+                drop: (dir) => isPinnedNodeDir(dir, nvmHome()),
+            }).join(path.delimiter),
             add: [],
             additive: false,
         });
@@ -76,10 +91,45 @@ export function persistEnvironment(env, toolVars) {
 export function addMachineEnvironment(vars, dirs, additive = false) {
     if (!isWin || dryRun || testMode)
         return;
+    // Folders that do not exist stay out, and so does a pinned Node version (`nvm use` could not move it).
+    const planned = planPath({ entries: dirs, exists, drop: (dir) => isPinnedNodeDir(dir, nvmHome()) });
     try {
-        runScriptWithJson('set-machine-environment.ps1', 'SettingsFile', { vars, path: null, add: dirs, additive });
+        runScriptWithJson('set-machine-environment.ps1', 'SettingsFile', { vars, path: null, add: planned, additive });
     }
     catch (e) {
         warn('Could not add to the environment: ' + errMsg(e));
     }
 }
+const nvmHome = () => path.join(toolsDir, 'nvm');
+/** The folder of every configured agent that is installed: its command works in any terminal. */
+function installedAgentDirs() {
+    return Object.entries(session.agents ?? {}).flatMap(([name, harness]) => {
+        const p = agentPaths(toolsDir, name, harness);
+        return (p.exe && exists(p.exe)) || (p.cmd && exists(p.cmd)) ? [p.dir] : [];
+    });
+}
+const MACHINE_ENVIRONMENT_KEY = 'HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment';
+const USER_ENVIRONMENT_KEY = 'HKCU\\Environment';
+const registryPath = (key) => parseRegPath(execOutput(SYSTEM.reg(), ['query', key, '/v', 'Path']));
+/**
+ * The environment for a program the daemon starts (an agent session, `sandbox exec`): its own PATH, plus every machine
+ * and user PATH folder added since the daemon started (python, cargo, other agents ...) at the end. Never changes
+ * `env`; without Windows it is returned as it is.
+ */
+export function withRegistryPath(env) {
+    if (!isWin || dryRun || testMode)
+        return env;
+    try {
+        const registry = expandVars(registryPath(MACHINE_ENVIRONMENT_KEY) + ';' + registryPath(USER_ENVIRONMENT_KEY), env);
+        const runner = pathKey(path.join(toolsDir, 'node'));
+        const pathName = Object.keys(env).find((k) => k.toLowerCase() === 'path') ?? 'PATH';
+        return {
+            ...env,
+            [pathName]: appendMissing(env[pathName] ?? '', registry, (dir) => pathKey(dir) === runner || isPinnedNodeDir(dir, nvmHome())),
+        };
+    }
+    catch (e) {
+        warn('Could not read the machine PATH (the session keeps the one it has): ' + errMsg(e));
+        return env;
+    }
+}

package/dist/guest/setup/path-plan.d.ts

@@ -0,0 +1,32 @@
+/** A folder as a comparison key: one slash style, no trailing slash (a drive root keeps its one), lower case. */
+export declare function pathKey(folder: string): string;
+/** The folders of a PATH string: no empty parts, no quotes around a folder. */
+export declare function splitPath(value: string): string[];
+/** Replaces %NAME% with the variable's value (any case); a name that is not set stays as written. */
+export declare function expandVars(value: string, env: Readonly<Record<string, string | undefined>>): string;
+export interface PathPlanInput {
+    /** In the order they should have: earlier entries win. */
+    readonly entries: readonly string[];
+    readonly exists: (folder: string) => boolean;
+    /** Entries to leave out (a folder that must not be machine-wide, matched like pathKey). */
+    readonly drop?: (folder: string) => boolean;
+}
+/** Ordered, de-duplicated (case, trailing slash) PATH folders; missing and dropped folders are left out. */
+export declare function planPath(input: PathPlanInput): string[];
+/** `base` with the folders of `extra` it lacks added at the end (a process keeps its own order and entries). */
+export declare function appendMissing(base: string, extra: string, skip?: (folder: string) => boolean): string;
+/**
+ * What a new shell gets: folders only this process has first (a parent put them there on purpose), then the machine
+ * and the user PATH with their %VARIABLES% expanded; no duplicates. `skip` leaves folders out (the runner's own Node).
+ */
+export declare function rebuildPath(o: {
+    readonly machine: string;
+    readonly user: string;
+    readonly process: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly skip?: (folder: string) => boolean;
+}): string;
+/** The value of `Path` in the output of `reg query <key> /v Path` ('' when there is none). */
+export declare function parseRegPath(output: string): string;
+/** A folder of one pinned Node version (nvm's `v24.22.0`): never machine-wide, `nvm use` would not move it. */
+export declare function isPinnedNodeDir(folder: string, nvmHome: string): boolean;

package/dist/guest/setup/path-plan.js

@@ -0,0 +1,67 @@
+// The one place that decides which folders are on the machine PATH, in what order, and how a process's PATH is brought
+// up to date with the registry. Pure (no side effects): the self-test imports this file. The shells' own start-up code
+// (sandbox\csharp\PathSync.cs) follows the same rules.
+import path from 'node:path';
+/** A folder as a comparison key: one slash style, no trailing slash (a drive root keeps its one), lower case. */
+export function pathKey(folder) {
+    const slashes = folder.trim().replace(/^"|"$/g, '').replace(/\//g, '\\');
+    return (slashes.length > 3 ? slashes.replace(/\\+$/, '') : slashes).toLowerCase();
+}
+/** The folders of a PATH string: no empty parts, no quotes around a folder. */
+export function splitPath(value) {
+    return value
+        .split(';')
+        .map((part) => part.trim().replace(/^"|"$/g, ''))
+        .filter(Boolean);
+}
+/** Replaces %NAME% with the variable's value (any case); a name that is not set stays as written. */
+export function expandVars(value, env) {
+    const lower = new Map(Object.entries(env).map(([k, v]) => [k.toLowerCase(), v]));
+    return value.replace(/%([^%;\\]+)%/g, (whole, name) => lower.get(name.toLowerCase()) ?? whole);
+}
+/** Ordered, de-duplicated (case, trailing slash) PATH folders; missing and dropped folders are left out. */
+export function planPath(input) {
+    const seen = new Set();
+    const result = [];
+    for (const entry of input.entries.flatMap(splitPath)) {
+        const key = pathKey(entry);
+        if (seen.has(key) || input.drop?.(entry) || !input.exists(entry))
+            continue;
+        seen.add(key);
+        result.push(entry);
+    }
+    return result;
+}
+/** `base` with the folders of `extra` it lacks added at the end (a process keeps its own order and entries). */
+export function appendMissing(base, extra, skip = () => false) {
+    const seen = new Set(splitPath(base).map(pathKey));
+    const added = splitPath(extra).filter((folder) => {
+        const key = pathKey(folder);
+        if (seen.has(key) || skip(folder))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    return [...splitPath(base), ...added].join(';');
+}
+/**
+ * What a new shell gets: folders only this process has first (a parent put them there on purpose), then the machine
+ * and the user PATH with their %VARIABLES% expanded; no duplicates. `skip` leaves folders out (the runner's own Node).
+ */
+export function rebuildPath(o) {
+    const registry = splitPath(expandVars(o.machine, o.env) + ';' + expandVars(o.user, o.env));
+    const known = new Set(registry.map(pathKey));
+    const only = splitPath(o.process).filter((f) => !known.has(pathKey(f)) && !o.skip?.(f));
+    return planPath({ entries: [...only, ...registry], exists: () => true }).join(';');
+}
+/** The value of `Path` in the output of `reg query <key> /v Path` ('' when there is none). */
+export function parseRegPath(output) {
+    const line = output.split(/\r?\n/).find((l) => /^\s+Path\s+REG_(EXPAND_)?SZ\s/i.test(l));
+    return line ? line.replace(/^\s+Path\s+REG_(EXPAND_)?SZ\s+/i, '').trim() : '';
+}
+/** A folder of one pinned Node version (nvm's `v24.22.0`): never machine-wide, `nvm use` would not move it. */
+export function isPinnedNodeDir(folder, nvmHome) {
+    const key = pathKey(folder);
+    const home = pathKey(nvmHome);
+    return key.startsWith(home + '\\') && /^v\d/.test(path.win32.basename(key));
+}

package/dist/guest/setup/shell-path.d.ts

@@ -0,0 +1 @@
+export declare function installShellPath(): void;

package/dist/guest/setup/shell-path.js

@@ -0,0 +1,22 @@
+// New shells (PowerShell, PowerShell 7, cmd, Git Bash) start with the current machine PATH, whatever their parent had:
+// pathsync.exe is built and the shells' start-up files call it (sandbox\scripts\install-shell-path.ps1).
+import fs from 'node:fs';
+import path from 'node:path';
+import { dryRun, isWin, localDir, testMode, toolsDir } from '../runtime/paths.js';
+import { mkdirp } from '../runtime/fs.js';
+import { ensureCompiled } from '../runtime/csc.js';
+import { runScript } from '../runtime/process.js';
+export function installShellPath() {
+    if (!isWin || dryRun || testMode)
+        return;
+    const helper = path.join(mkdirp(path.join(localDir, 'bin')), 'pathsync.exe');
+    fs.copyFileSync(ensureCompiled('pathsync'), helper);
+    runScript('install-shell-path.ps1', [
+        '-Helper',
+        helper,
+        '-PwshDir',
+        path.join(toolsDir, 'pwsh'),
+        '-GitRoot',
+        path.join(toolsDir, 'git'),
+    ]);
+}

package/dist/guest/toolchains/languages/python.js

@@ -77,7 +77,7 @@ export async function setupPython(env, config, versions) {
     const py3 = await installPython('python', versions.python.spec);
     const shims = shimDir(py3);
     shimPair(shims, '3', py3);
-    env.prepend.push(py3, path.join(py3, 'Scripts'), shims);
+    env.prepend.push(py3, mkdirp(path.join(py3, 'Scripts')), shims);
     env.vars.PYTHONIOENCODING = 'utf-8';
     env.summary.push('python: ' + path.basename(py3).replace('python-', '') + ' (from ' + versions.python.source + '; py works too)');
     if (!config.python2) {

package/dist/guest/toolchains/native/rust-extras.js

@@ -7,6 +7,7 @@ import { execOutput } from '../../runtime/process.js';
 import { ensureCompiled } from '../../runtime/csc.js';
 import { arch, tool } from '../tool-env.js';
 import { wanted } from '../detect.js';
+import { cargoJobs } from '../../../shared/memory/index.js';
 /**
  * Where cargo builds: shared with the PC's target\, one on the sandbox's disk, or a path. "separate" sets no variable:
  * the cargo shim (sandbox/csharp/CargoShim.cs) gives every checkout its own target\sandbox, so git worktrees of several
@@ -66,8 +67,9 @@ export function cargoDefaults(host) {
     const file = tool('rust', 'cargo', 'config.toml');
     if (exists(file) || !exists(path.dirname(file)))
         return;
-    // Several agents often build at once: up to 4 jobs each (8 each crashed Windows inside the sandbox on 13 Oct 2026).
-    const jobs = Math.max(2, Math.min(4, Math.floor(os.cpus().length / 4)));
+    // Several agents often build at once: up to 4 jobs each (8 each crashed Windows inside the sandbox on 13 Oct 2026),
+    // and about 4 GB of memory per job. The daemon lowers it further per session (CARGO_BUILD_JOBS) when several build.
+    const jobs = cargoJobs(os.cpus().length, os.totalmem() / 1024 ** 3, 1);
     const gnu = host.endsWith('-gnu');
     fs.writeFileSync(file, [
         '# Written by windows-development-sandbox once; edit freely, it is never overwritten.',