windows-development-sandbox 1.4.1 → 1.4.3

package/dist/guest/toolchains/plan.js

@@ -1,140 +1,128 @@
-// Which toolchain and database steps this sandbox runs, in the order their PATH entries are listed, and what each
-// step depends on. The scheduler (index.ts) runs them.
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
 import { appsNeedMesa, setupApps } from '../apps/index.js';
-import { dataDir, dryRun, execAsync, exists, localDir, mkdirp } from '../env.js';
-import { ensureCompiled } from '../helpers.js';
-import { arch, installOnce, tool, wanted } from './common.js';
-import { DATABASE_NAMES, setupDatabase } from './databases/index.js';
-import { setupGit } from './git.js';
-import { setupGo } from './go.js';
-import { setupJava } from './java.js';
-import { setupCli } from './cli.js';
+import { dryRun } from '../runtime/paths.js';
+import { wanted } from './detect.js';
+import { DATABASE_NAMES, setupDatabase } from '../databases/index.js';
+import { setupGit } from './tools/git.js';
+import { setupGo } from './languages/go.js';
+import { setupJava } from './languages/java.js';
+import { setupCli } from './tools/cli.js';
 import { setupPyenv, setupVolta, wantsPyenv, wantsVolta } from './managers.js';
 import { setupCpp } from './native/cpp.js';
 import { setupDotnet } from './native/dotnet.js';
 import { setupMesa } from './native/mesa.js';
 import { setupMsvc } from './native/msvc/index.js';
 import { setupRust } from './native/rust.js';
-import { setupNode } from './node.js';
-import { setupPwsh } from './pwsh.js';
-import { setupPython } from './python.js';
-import { setupBun, setupDeno, setupUv, uvVars } from './runtimes.js';
-import { setupPhp } from './scripting/php.js';
-import { setupRuby } from './scripting/ruby.js';
-import { setupVcRuntime } from './scripting/vcruntime.js';
-import { setupVscode } from './vscode.js';
-/** Python command-line tools through uv (each in its own environment, commands in uv's bin folder on PATH). */
-const setupPythonTools = async (env, tools) => {
-    const uv = tool('uv', 'uv.exe');
-    if (!exists(uv))
-        throw new Error('toolchains.python.tools needs uv (toolchains.uv.enabled)');
-    await installOnce(env, 'uv tool', tools, (pkg) => execAsync(uv, ['tool', 'install', pkg], { env: { ...process.env, ...uvVars() } }));
-};
-/**
- * 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/cargoshim.cs) gives every checkout its own target\sandbox, so git worktrees of several agents
- * never overwrite each other's builds.
- */
-const cargoTarget = (targetDir) => {
-    if (targetDir === 'shared' || targetDir === 'separate')
-        return null;
-    if (targetDir === 'local')
-        return path.join(localDir, 'cargo-target');
-    return targetDir;
-};
-/** "separate": tools\shims\cargo\cargo.exe in front of the real cargo, which it runs with the checkout's target dir. */
-const cargoShim = (env, rust) => {
-    const real = path.join(tool('rust', 'cargo', 'bin'), 'cargo.exe');
-    if (rust.targetDir !== 'separate' || !exists(real))
-        return;
-    const dir = mkdirp(tool('shims', 'cargo'));
-    fs.copyFileSync(ensureCompiled('cargoshim'), path.join(dir, 'cargo.exe'));
-    env.prepend.unshift(dir);
-    env.vars.AGENT_REAL_CARGO = real;
-};
-/**
- * Cargo defaults that fit Windows, written only when there is no $CARGO_HOME\config.toml yet: fewer parallel jobs
- * (parallel rustc ran out of paging file) and, for the GNU host, only line tables as debug info (full debug info made
- * test executables bigger than the 2 GB Windows allows).
- */
-const 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)));
-    const gnu = host.endsWith('-gnu');
-    fs.writeFileSync(file, [
-        '# Written by windows-development-sandbox once; edit freely, it is never overwritten.',
-        '[build]', 'jobs = ' + jobs, '',
-        ...(gnu ? ['[profile.dev]', 'debug = "line-tables-only"', '', '[profile.test]', 'debug = "line-tables-only"', ''] : []),
-    ].join('\n'));
-};
-/**
- * Where cargo builds and where sccache keeps its cache. Cargo fingerprints hold absolute paths and the host toolchain,
- * so a target\\ shared with builds on the PC rebuilds every time the side changes: "separate" (the default) keeps a
- * sandbox one next to it. sccache's cache persists unless the project sets SCCACHE_DIR itself.
- */
-const rustCaches = (rust) => {
-    const target = cargoTarget(rust.targetDir);
-    return { ...(target ? { CARGO_TARGET_DIR: target } : {}), ...(process.env.SCCACHE_DIR ? {} : { SCCACHE_DIR: path.join(dataDir, 'cache', 'sccache') }) };
-};
-/** "auto": the msvc host when the MSVC step runs (as on most PCs), else GNU with MinGW. */
-const rustHost = (config) => {
-    if (config.rust.host !== 'auto')
-        return config.rust.host;
-    const cpu = arch === 'arm64' ? 'aarch64' : 'x86_64';
-    return cpu + (wanted(config.msvc.enabled, 'msvc') ? '-pc-windows-msvc' : '-pc-windows-gnu');
-};
-export const plan = (config, versions, o) => {
+import { setupNode } from './languages/node.js';
+import { setupPwsh } from './tools/pwsh.js';
+import { setupPython } from './languages/python.js';
+import { setupBun, setupDeno, setupUv } from './runtimes.js';
+import { setupPhp } from './languages/php.js';
+import { setupRuby } from './languages/ruby.js';
+import { setupVcRuntime } from './native/vcruntime.js';
+import { setupVscode } from './tools/vscode.js';
+import { rustHost, rustCaches, cargoDefaults, cargoShim, linkGate } from './native/rust-extras.js';
+import { setupPythonTools } from './languages/python-tools.js';
+export function plan(config, versions, o) {
     const apps = Boolean(o.apps && (o.apps.install.length || Object.keys(o.apps.custom).length));
     const java = wanted(config.java.enabled, 'java');
     const python = wanted(config.python.enabled, 'python');
     return [
-        { name: 'Git', on: o.gitEnabled, shared: true, run: (env) => setupGit(env, o.hostGit, o.refresh, o.gitAccess) },
+        {
+            name: 'Git',
+            enabled: o.gitEnabled,
+            shared: true,
+            install: (env) => setupGit(env, o.hostGit, o.refresh, o.gitAccess),
+        },
         // Before Node: with package.json pins, Volta's node/npm/pnpm/yarn come first on PATH.
-        { name: 'Volta', on: wantsVolta(config.node.volta), run: (env) => setupVolta(env) },
-        { name: 'Node ' + versions.node.spec, on: true, run: (env) => setupNode(env, versions, config.node) },
-        { name: 'Python', on: python, run: (env) => setupPython(env, config.python, versions) },
-        { name: 'pyenv-win', on: python && wantsPyenv(config.python.pyenv), run: (env) => setupPyenv(env) },
-        { name: 'C/C++', on: wanted(config.cpp.enabled, 'cpp') || wanted(config.rust.enabled, 'rust'), run: (env) => setupCpp(env, config.cpp) },
-        { name: 'MSVC', on: wanted(config.msvc.enabled, 'msvc'), run: (env) => setupMsvc(env, config.msvc) },
+        { name: 'Volta', enabled: wantsVolta(config.node.volta), install: (env) => setupVolta(env) },
+        { name: 'Node ' + versions.node.spec, enabled: true, install: (env) => setupNode(env, versions, config.node) },
+        { name: 'Python', enabled: python, install: (env) => setupPython(env, config.python, versions) },
+        { name: 'pyenv-win', enabled: python && wantsPyenv(config.python.pyenv), install: (env) => setupPyenv(env) },
+        {
+            name: 'C/C++',
+            enabled: wanted(config.cpp.enabled, 'cpp') || wanted(config.rust.enabled, 'rust'),
+            install: (env) => setupCpp(env, config.cpp),
+        },
+        { name: 'MSVC', enabled: wanted(config.msvc.enabled, 'msvc'), install: (env) => setupMsvc(env, config.msvc) },
         // Rust links with MSVC (msvc host) or MinGW's gcc (GNU host): whichever it uses goes first.
         {
-            name: 'Rust', on: wanted(config.rust.enabled, 'rust'), after: ['C/C++', 'MSVC'],
-            run: async (env) => {
+            name: 'Rust',
+            enabled: wanted(config.rust.enabled, 'rust'),
+            after: ['C/C++', 'MSVC'],
+            install: async (env) => {
                 await setupRust(env, { ...config.rust, host: rustHost(config) }, o.refresh);
                 Object.assign(env.vars, rustCaches(config.rust));
                 if (!dryRun) {
                     cargoDefaults(rustHost(config));
                     cargoShim(env, config.rust);
+                    linkGate(env, config.rust, rustHost(config));
                 }
             },
         },
-        { name: '.NET', on: wanted(config.dotnet.enabled, 'dotnet'), run: (env) => setupDotnet(env, config.dotnet, o.refresh) },
-        { name: 'Go', on: wanted(config.go.enabled, 'go'), run: (env) => setupGo(env, config.go) },
-        { name: 'Java', on: java, run: (env) => setupJava(env, config.java) },
-        { name: 'Ruby', on: wanted(config.ruby.enabled, 'ruby'), run: (env) => setupRuby(env, config.ruby) },
+        {
+            name: '.NET',
+            enabled: wanted(config.dotnet.enabled, 'dotnet'),
+            install: (env) => setupDotnet(env, config.dotnet, o.refresh),
+        },
+        { name: 'Go', enabled: wanted(config.go.enabled, 'go'), install: (env) => setupGo(env, config.go) },
+        { name: 'Java', enabled: java, install: (env) => setupJava(env, config.java) },
+        { name: 'Ruby', enabled: wanted(config.ruby.enabled, 'ruby'), install: (env) => setupRuby(env, config.ruby) },
         // PHP installs the Visual C++ runtime itself: one installer at a time.
         // Many apps (bat, delta, Neovim, most GUIs, your own programs) are built against it too.
-        { name: 'Visual C++ runtime', on: config.vcRuntime.enabled || apps, shared: true, run: async (env) => { await setupVcRuntime(env); } },
-        { name: 'PHP', on: wanted(config.php.enabled, 'php'), after: ['Visual C++ runtime'], run: (env) => setupPhp(env, config.php) },
-        { name: 'Deno', on: wanted(config.deno.enabled, 'deno'), run: (env) => setupDeno(env) },
-        { name: 'Bun', on: config.bun.enabled, run: (env) => setupBun(env) },
-        { name: 'uv', on: config.uv.enabled, run: (env) => setupUv(env) },
-        { name: 'PowerShell 7', on: wanted(config.pwsh.enabled, 'pwsh'), run: (env) => setupPwsh(env, o.refresh) },
+        {
+            name: 'Visual C++ runtime',
+            enabled: config.vcRuntime.enabled || apps,
+            shared: true,
+            install: async (env) => {
+                await setupVcRuntime(env);
+            },
+        },
+        {
+            name: 'PHP',
+            enabled: wanted(config.php.enabled, 'php'),
+            after: ['Visual C++ runtime'],
+            install: (env) => setupPhp(env, config.php),
+        },
+        { name: 'Deno', enabled: wanted(config.deno.enabled, 'deno'), install: (env) => setupDeno(env) },
+        { name: 'Bun', enabled: config.bun.enabled, install: (env) => setupBun(env) },
+        { name: 'uv', enabled: config.uv.enabled, install: (env) => setupUv(env) },
+        { name: 'PowerShell 7', enabled: wanted(config.pwsh.enabled, 'pwsh'), install: (env) => setupPwsh(env, o.refresh) },
         // The openssl tool comes from Git's install: after Git.
-        { name: 'CLI tools', on: Object.values(config.cli).some((v) => v !== false), after: ['Git'], run: (env) => setupCli(env, config.cli, o.gitAccess, o.refresh) },
-        { name: 'Mesa 3D', on: config.mesa.enabled || appsNeedMesa(o.apps), shared: true, run: (env) => setupMesa(env, config.mesa) },
-        { name: 'VS Code', on: config.vscode.enabled, shared: true, run: (env) => setupVscode(env, o.refresh) },
+        {
+            name: 'CLI tools',
+            enabled: Object.values(config.cli).some((v) => v !== false),
+            after: ['Git'],
+            install: (env) => setupCli(env, config.cli, o.gitAccess, o.refresh),
+        },
+        {
+            name: 'Mesa 3D',
+            enabled: config.mesa.enabled || appsNeedMesa(o.apps),
+            shared: true,
+            install: (env) => setupMesa(env, config.mesa),
+        },
+        { name: 'VS Code', enabled: config.vscode.enabled, shared: true, install: (env) => setupVscode(env, o.refresh) },
         // Desktop apps and extra tools (apps.install / apps.custom); games and 3D apps copy Mesa's OpenGL next to them.
-        { name: 'Apps', on: apps, shared: true, after: ['Mesa 3D', 'Visual C++ runtime'], run: (env) => setupApps(env, o.apps, { gitAccess: o.gitAccess, refresh: o.refresh }) },
-        { name: 'Python tools', on: python && config.python.tools.length > 0, after: ['Python', 'uv'], run: (env) => setupPythonTools(env, config.python.tools) },
+        {
+            name: 'Apps',
+            enabled: apps,
+            shared: true,
+            after: ['Mesa 3D', 'Visual C++ runtime'],
+            install: (env) => setupApps(env, o.apps, { gitAccess: o.gitAccess, refresh: o.refresh }),
+        },
+        {
+            name: 'Python tools',
+            enabled: python && config.python.tools.length > 0,
+            after: ['Python', 'uv'],
+            install: (env) => setupPythonTools(env, config.python.tools),
+        },
         // DynamoDB Local runs on Java: the Java step installs the JDK first instead of racing it.
         // One server per database in the sandbox: a project that joins later shares the one the boot started.
-        ...o.databases.map((db) => ({ name: DATABASE_NAMES[db.database], on: true, shared: true, after: db.database === 'dynamodb' && java ? ['Java'] : [], run: (env) => setupDatabase(env, db) })),
+        ...o.databases.map((db) => ({
+            name: DATABASE_NAMES[db.database],
+            enabled: true,
+            shared: true,
+            after: db.database === 'dynamodb' && java ? ['Java'] : [],
+            install: (env) => setupDatabase(env, db),
+        })),
     ];
-};
+}

package/dist/guest/toolchains/runtimes.d.ts

@@ -1,4 +1,4 @@
-import { type ToolEnv } from './common.js';
+import { type ToolEnv } from './tool-env.js';
 export interface SingleExeOptions {
     /** Download again even when installed (provisioning.refresh). */
     refresh?: boolean;
@@ -11,9 +11,9 @@ export interface SingleExeOptions {
     size?: string;
 }
 /** A tool from one GitHub release archive, into `dir` (atomically), on PATH. */
-export declare const setupSingleExe: (env: ToolEnv, name: string, repo: string, pattern: RegExp, exeName: string, dir: string, options?: SingleExeOptions) => Promise<void>;
-export declare const setupBun: (env: ToolEnv) => Promise<void>;
-export declare const setupDeno: (env: ToolEnv) => Promise<void>;
+export declare function setupSingleExe(env: ToolEnv, name: string, repo: string, pattern: RegExp, exeName: string, dir: string, options?: SingleExeOptions): Promise<void>;
+export declare function setupBun(env: ToolEnv): Promise<void>;
+export declare function setupDeno(env: ToolEnv): Promise<void>;
 /** Where uv keeps its cache, Pythons and tools (persistent). */
-export declare const uvVars: () => Record<string, string>;
-export declare const setupUv: (env: ToolEnv) => Promise<void>;
+export declare function uvVars(): Record<string, string>;
+export declare function setupUv(env: ToolEnv): Promise<void>;

package/dist/guest/toolchains/runtimes.js

@@ -1,9 +1,12 @@
 // Bun, uv and Deno: single-binary tools from GitHub releases (claude-mem needs Bun and uv).
 import path from 'node:path';
-import { dryRun, exists, localDir, log } from '../env.js';
-import { arch, installFromGithub, tool, versionOf } from './common.js';
+import { dryRun, localDir } from '../runtime/paths.js';
+import { exists } from '../runtime/fs.js';
+import { log } from '../runtime/log.js';
+import { arch, tool, versionOf } from './tool-env.js';
+import { installFromGithub } from './install.js';
 /** A tool from one GitHub release archive, into `dir` (atomically), on PATH. */
-export const setupSingleExe = async (env, name, repo, pattern, exeName, dir, options = {}) => {
+export async function setupSingleExe(env, name, repo, pattern, exeName, dir, options = {}) {
     if (dryRun) {
         log('(dry run) would provision ' + name);
         return;
@@ -12,27 +15,42 @@ export const setupSingleExe = async (env, name, repo, pattern, exeName, dir, opt
     const exe = path.join(bin, exeName);
     if (!exists(exe) || options.refresh) {
         const size = options.size ? ', ~' + options.size : '';
-        await installFromGithub(repo, pattern, { dest: dir, what: (a) => name + ' (' + a.name + size + ' once)', ...(options.subdir ? {} : { locate: exeName }) });
+        await installFromGithub(repo, pattern, {
+            dest: dir,
+            what: (a) => name + ' (' + a.name + size + ' once)',
+            ...(options.subdir ? {} : { locate: exeName }),
+        });
     }
     if (!exists(exe))
         throw new Error(exeName + ' missing after installing ' + name);
     env.prepend.push(bin);
     env.summary.push(name + ': ' + versionOf(exe, options.versionArgs) + (options.note ?? ''));
-};
-export const setupBun = async (env) => {
+}
+export async function setupBun(env) {
     await setupSingleExe(env, 'bun', 'oven-sh/bun', arch === 'arm64' ? /^bun-windows-aarch64\.zip$/ : /^bun-windows-x64\.zip$/, 'bun.exe', tool('bun', 'bin'), { size: '35 MB' });
     // Bun cannot keep its cache or temp files on a mapped folder (EINVAL); they go to the sandbox's own disk.
-    Object.assign(env.vars, { BUN_INSTALL: tool('bun'), BUN_INSTALL_CACHE_DIR: path.join(localDir, 'bun-cache'), BUN_TMPDIR: path.join(localDir, 'bun-tmp') });
-};
-export const setupDeno = async (env) => {
+    Object.assign(env.vars, {
+        BUN_INSTALL: tool('bun'),
+        BUN_INSTALL_CACHE_DIR: path.join(localDir, 'bun-cache'),
+        BUN_TMPDIR: path.join(localDir, 'bun-tmp'),
+    });
+}
+export async function setupDeno(env) {
     await setupSingleExe(env, 'deno', 'denoland/deno', arch === 'arm64' ? /^deno-aarch64-pc-windows-msvc[.]zip$/ : /^deno-x86_64-pc-windows-msvc[.]zip$/, 'deno.exe', tool('deno', 'bin'), { size: '40 MB' });
     // `deno install` puts commands in DENO_INSTALL_ROOT/bin: the folder deno.exe is in, already on PATH.
     Object.assign(env.vars, { DENO_DIR: tool('deno-cache'), DENO_INSTALL_ROOT: tool('deno'), DENO_NO_UPDATE_CHECK: '1' });
-};
+}
 /** Where uv keeps its cache, Pythons and tools (persistent). */
-export const uvVars = () => ({ UV_CACHE_DIR: tool('uv-cache'), UV_PYTHON_INSTALL_DIR: tool('uv-python'), UV_TOOL_DIR: tool('uv-tools'), UV_TOOL_BIN_DIR: tool('uv-bin') });
-export const setupUv = async (env) => {
+export function uvVars() {
+    return {
+        UV_CACHE_DIR: tool('uv-cache'),
+        UV_PYTHON_INSTALL_DIR: tool('uv-python'),
+        UV_TOOL_DIR: tool('uv-tools'),
+        UV_TOOL_BIN_DIR: tool('uv-bin'),
+    };
+}
+export async function setupUv(env) {
     await setupSingleExe(env, 'uv', 'astral-sh/uv', arch === 'arm64' ? /^uv-aarch64-pc-windows-msvc\.zip$/ : /^uv-x86_64-pc-windows-msvc\.zip$/, 'uv.exe', tool('uv'), { size: '20 MB' });
     Object.assign(env.vars, uvVars());
     env.prepend.push(tool('uv-bin'));
-};
+}

package/dist/guest/toolchains/scheduler.d.ts

@@ -0,0 +1,22 @@
+import { type ToolEnv } from './tool-env.js';
+import type { ToolchainStep } from './step.js';
+export interface RunOptions {
+    /** Progress lines ("Installing Go, Rust (3 of 9 done)"); default: the sandbox's boot status. */
+    report?: (message: string) => void;
+    /** What machine-wide (shared) steps contributed at boot: reused instead of run again. */
+    reuse?: Record<string, ToolEnv>;
+}
+export declare class StepScheduler {
+    private readonly parallel;
+    /** One lock per kind of step ("Node 20" and "Node 22" share nvm's folders): held while that step runs, in any run. */
+    private readonly locks;
+    /** The step a download belongs to (several run at once), for its progress. */
+    private readonly currentStep;
+    constructor(parallel?: number);
+    /** Runs the steps (each with its own environment) and returns each step's environment, in plan order. */
+    run(steps: readonly ToolchainStep[], o: RunOptions): Promise<Map<string, ToolEnv>>;
+    /** Runs `work` once no other step of the same kind (first word of the name) is running. */
+    private exclusive;
+}
+/** The one scheduler: its locks span the boot's run and every project's run. */
+export declare const scheduler: StepScheduler;

package/dist/guest/toolchains/scheduler.js

@@ -0,0 +1,123 @@
+// Runs the planned steps in parallel, a few at a time, after the steps they depend on. One lock per kind of step is
+// held across runs: the boot and projects that join later never install two Nodes (or two Gos) at once.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { downloader } from '../../shared/download/index.js';
+import { warn } from '../runtime/log.js';
+import { setSandboxStatus } from '../runtime/status.js';
+import { errMsg } from '../../core/util/errors.js';
+import { emptyEnv } from './tool-env.js';
+/** How many installers run at once: enough to overlap downloads with installs, few enough not to thrash the disk. */
+const PARALLEL = 4;
+/** Runs one installer; a failure is reported and skipped so it never blocks the other toolchains. */
+async function runReported(name, env, work) {
+    try {
+        await work();
+    }
+    catch (e) {
+        warn(name +
+            ' could not be set up and is skipped; everything else still works, and the next start tries again. Reason: ' +
+            errMsg(e));
+        env.summary.push(name + ': FAILED');
+    }
+}
+export class StepScheduler {
+    parallel;
+    /** One lock per kind of step ("Node 20" and "Node 22" share nvm's folders): held while that step runs, in any run. */
+    locks = new Map();
+    /** The step a download belongs to (several run at once), for its progress. */
+    currentStep = new AsyncLocalStorage();
+    constructor(parallel = PARALLEL) {
+        this.parallel = parallel;
+    }
+    /** Runs the steps (each with its own environment) and returns each step's environment, in plan order. */
+    async run(steps, o) {
+        const envs = new Map(steps.map((s) => [s.name, emptyEnv()]));
+        const finished = new Map();
+        const running = new Set();
+        const waiting = [];
+        let done = 0;
+        // The boot (no `report`) also publishes structured progress: what runs now, how far its download is, how many are
+        // done.
+        const percent = new Map();
+        const active = () => [...running].map((name) => ({ name, ...(percent.has(name) ? { percent: percent.get(name) } : {}) }));
+        const say = o.report ??
+            ((message) => setSandboxStatus('provisioning', message, { active: active(), done, total: steps.length }));
+        const report = () => {
+            if (running.size)
+                say('Installing ' + [...running].join(', ') + ' (' + done + ' of ' + steps.length + ' done)');
+        };
+        if (!o.report)
+            downloader.watch(() => {
+                const name = this.currentStep.getStore();
+                return name
+                    ? (fraction) => {
+                        percent.set(name, Math.round(fraction * 100));
+                        report();
+                    }
+                    : null;
+            });
+        for (const s of steps) {
+            // Dependencies first (they are earlier in the plan, so their promises exist), then a free slot.
+            finished.set(s.name, (async () => {
+                await Promise.all((s.after ?? []).map((name) => finished.get(name)));
+                const env = envs.get(s.name);
+                const reused = s.shared ? o.reuse?.[s.name] : undefined;
+                if (reused) {
+                    envs.set(s.name, structuredClone(reused));
+                    done++;
+                    return;
+                }
+                while (running.size >= this.parallel)
+                    await new Promise((r) => waiting.push(r));
+                running.add(s.name);
+                report();
+                try {
+                    await this.currentStep.run(s.name, () => this.exclusive(s.name, () => runReported(s.name, env, async () => s.install(env))));
+                }
+                finally {
+                    running.delete(s.name);
+                    percent.delete(s.name);
+                    done++;
+                    report();
+                    waiting.shift()?.();
+                }
+            })());
+        }
+        try {
+            await Promise.all(finished.values());
+        }
+        finally {
+            if (!o.report)
+                downloader.watch(null);
+        }
+        if (!o.report)
+            setSandboxStatus('provisioning', 'Set up ' + steps.length + ' toolchains and databases', {
+                active: [],
+                done,
+                total: steps.length,
+            });
+        return envs;
+    }
+    /** Runs `work` once no other step of the same kind (first word of the name) is running. */
+    async exclusive(name, work) {
+        const key = name.split(' ')[0].toLowerCase();
+        const previous = this.locks.get(key) ?? Promise.resolve();
+        let release = () => undefined;
+        const mine = new Promise((r) => {
+            release = r;
+        });
+        const chained = previous.then(() => mine);
+        this.locks.set(key, chained);
+        await previous;
+        try {
+            return await work();
+        }
+        finally {
+            release();
+            if (this.locks.get(key) === chained)
+                this.locks.delete(key);
+        }
+    }
+}
+/** The one scheduler: its locks span the boot's run and every project's run. */
+export const scheduler = new StepScheduler();

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

@@ -0,0 +1,10 @@
+import type { Toolchains, ToolVersions } from '../../core/types.js';
+import { type ToolEnv } from './tool-env.js';
+import type { ToolchainOptions } from './step.js';
+import { type RunOptions } from './scheduler.js';
+/** The combined environment, plus what each step contributed (kept so later projects reuse the shared steps). */
+export interface ToolchainResult extends ToolEnv {
+    steps: Record<string, ToolEnv>;
+}
+/** Provisions every enabled toolchain and database, and returns the combined environment for the agent. */
+export declare function setupToolchains(config: Toolchains, versions: ToolVersions, options: ToolchainOptions, run?: RunOptions): Promise<ToolchainResult>;

package/dist/guest/toolchains/setup.js

@@ -0,0 +1,22 @@
+import { log } from '../runtime/log.js';
+import { mkdirp } from '../runtime/fs.js';
+import { emptyEnv, tool } from './tool-env.js';
+import { plan } from './plan.js';
+import { scheduler } from './scheduler.js';
+/** Provisions every enabled toolchain and database, and returns the combined environment for the agent. */
+export async function setupToolchains(config, versions, options, run = {}) {
+    const steps = plan(config, versions, options).filter((s) => s.enabled);
+    const envs = await scheduler.run(steps, run);
+    // Merged in plan order, so PATH order never depends on which download finished first.
+    const env = { ...emptyEnv(), steps: Object.fromEntries(envs) };
+    env.prepend.push(mkdirp(tool('bin')));
+    for (const part of envs.values()) {
+        Object.assign(env.vars, part.vars);
+        env.prepend.push(...part.prepend);
+        env.append.push(...part.append);
+        env.summary.push(...part.summary);
+    }
+    Object.assign(env.vars, config.environment);
+    log('Set up ' + steps.length + ' toolchains and databases.');
+    return env;
+}

package/dist/guest/toolchains/state-file.d.ts

@@ -0,0 +1,3 @@
+import type { z } from 'zod';
+/** Small JSON state files in tools\: read with zod (a half-written file is just empty), written atomically. */
+export declare function readState<S extends z.ZodType>(file: string, schema: S, empty: z.output<S>): z.output<S>;

package/dist/guest/toolchains/state-file.js

@@ -0,0 +1,10 @@
+import fs from 'node:fs';
+/** Small JSON state files in tools\: read with zod (a half-written file is just empty), written atomically. */
+export function readState(file, schema, empty) {
+    try {
+        return schema.safeParse(JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''))).data ?? empty;
+    }
+    catch {
+        return empty;
+    }
+}

package/dist/guest/toolchains/step.d.ts

@@ -0,0 +1,24 @@
+import type { Config, DatabasePlan, GitAccess } from '../../core/types.js';
+import type { ToolEnv } from './tool-env.js';
+/** apps: the boot only (apps are machine-wide; a project that joins later shares them). */
+export interface ToolchainOptions {
+    gitEnabled: boolean;
+    gitAccess: GitAccess;
+    hostGit: boolean;
+    refresh: boolean;
+    databases: DatabasePlan[];
+    apps?: Config['apps'];
+}
+/** One installer the scheduler runs: a toolchain, the apps, or a database server. */
+export interface ToolchainStep {
+    readonly name: string;
+    readonly enabled: boolean;
+    /** Steps that finish first (they are earlier in the plan). */
+    readonly after?: readonly string[];
+    /**
+     * The step's effect is machine-wide and the same for every project (an installer, a registry entry, a shortcut, the
+     * git guard): a project added after boot reuses what the boot's run contributed instead of running it again.
+     */
+    readonly shared?: boolean;
+    install(env: ToolEnv): Promise<void> | void;
+}

package/dist/guest/toolchains/step.js

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

package/dist/guest/toolchains/tool-env.d.ts

@@ -0,0 +1,12 @@
+/** What the toolchains contribute to the agent's environment. */
+export interface ToolEnv {
+    vars: Record<string, string>;
+    prepend: string[];
+    append: string[];
+    summary: string[];
+}
+export declare function emptyEnv(): ToolEnv;
+export declare const arch: string;
+export declare function tool(...parts: string[]): string;
+/** First x.y.z in a tool's `--version` output. */
+export declare function versionOf(exe: string, args?: string[], options?: {}): string;

package/dist/guest/toolchains/tool-env.js

@@ -0,0 +1,16 @@
+// Shared plumbing for the toolchain installers. Everything lives in C:\AgentData\tools (persistent), so only the first
+// boot downloads; later boots only put things on PATH.
+import path from 'node:path';
+import { execOutput } from '../runtime/process.js';
+import { toolsDir } from '../runtime/paths.js';
+export function emptyEnv() {
+    return { vars: {}, prepend: [], append: [], summary: [] };
+}
+export const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
+export function tool(...parts) {
+    return path.join(toolsDir, ...parts);
+}
+/** First x.y.z in a tool's `--version` output. */
+export function versionOf(exe, args = ['--version'], options = {}) {
+    return /\d+\.\d+\.\d+\S*/.exec(execOutput(exe, args, options))?.[0] ?? 'installed';
+}

package/dist/guest/toolchains/tools/cli.d.ts

@@ -0,0 +1,10 @@
+import type { GitAccess } from '../../../core/types.js';
+import { type CliSettings } from '../catalogue.js';
+import { type ToolEnv } from '../tool-env.js';
+/** gh keeps `gh auth login` here, under the agent state (persists like Claude's login; never copied from the PC). */
+export declare function ghConfigDir(): string;
+/**
+ * Installs the tools toolchains.cli asks for. Settings still "auto" here (normally the host decides) use the same
+ * rules on the workspace as the host would. The gh rule is enforced here again, whatever the host sent.
+ */
+export declare function setupCli(env: ToolEnv, settings: CliSettings, gitAccess: GitAccess, refresh?: boolean): Promise<void>;