windows-development-sandbox 1.20.0 → 1.23.1

package/dist/guest/runtime/process.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { moveIntoPlace, spawnAsync, stagingFolder } from '../../shared/download/index.js';
 import { safeRemove } from '../../shared/io/safe-remove.js';
 import { robocopyErrors, robocopyFailed, robocopyMeaning } from '../../shared/io/robocopy-result.js';
@@ -41,6 +41,31 @@ export function runScript(name, args = []) {
     if (result.status !== 0)
         throw new Error(name + ' failed with exit code ' + result.status + (errors ? ': ' + errors.slice(0, 400) : ''));
 }
+/** runScript without blocking the event loop (other boot tasks keep going while the script runs). */
+export function runScriptAsync(name, args = []) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(SYSTEM.powershell(), scriptArgs(name, args), {
+            stdio: ['inherit', 'inherit', 'pipe'],
+            windowsHide: true,
+        });
+        let errors = '';
+        child.stderr?.setEncoding('utf8');
+        child.stderr?.on('data', (chunk) => {
+            if (errors.length < 4096)
+                errors += chunk;
+        });
+        child.once('error', reject);
+        child.once('close', (code) => {
+            errors = errors.trim();
+            if (errors)
+                process.stderr.write(errors + '\n');
+            if (code !== 0)
+                reject(new Error(name + ' failed with exit code ' + code + (errors ? ': ' + errors.slice(0, 400) : '')));
+            else
+                resolve();
+        });
+    });
+}
 /** runScript for what it prints ('' when it fails). */
 export function scriptOutput(name, args = [], options = {}) {
     return execOutput(SYSTEM.powershell(), scriptArgs(name, args), options);
@@ -57,6 +82,18 @@ export function runScriptWithJson(name, param, data, args = []) {
         fs.rmSync(dir, { recursive: true, force: true });
     }
 }
+/** runScriptWithJson without blocking the event loop. */
+export async function runScriptWithJsonAsync(name, param, data, args = []) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sbx-'));
+    const file = path.join(dir, 'input.json');
+    try {
+        fs.writeFileSync(file, JSON.stringify(data), 'utf8');
+        await runScriptAsync(name, ['-' + param, file, ...args]);
+    }
+    finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
 /**
  * Copies a folder with robocopy (fast, restartable), or just the named files in it; exit codes below 8 mean success.
  */

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

@@ -1,7 +1,11 @@
 import type { SandboxStatus } from '../../core/types.js';
-import type { BootProgress } from '../../shared/channel/schema.js';
+import type { BackgroundWork, BootProgress } from '../../shared/channel/schema.js';
 /**
  * Best-effort: progress reporting must never be what breaks the boot. `update` changes the structured progress
  * (a new step, what is being set up); it stays as it was otherwise.
  */
 export declare function setSandboxStatus(phase: SandboxStatus['phase'], message: string, update?: Partial<BootProgress>): void;
+/** Whether the boot (another process: the daemon asks) still has this work running in the background. */
+export declare function backgroundRunning(name: string): boolean;
+/** Lists the work that continues after the boot (the phase and message stay as they are). */
+export declare function setBackgroundWork(work: readonly BackgroundWork[]): void;

package/dist/guest/runtime/status.js

@@ -8,11 +8,15 @@ import { run } from './paths.js';
 import { session, workspace } from './session.js';
 /** The boot's structured progress (the host shows it as one line); kept between status writes. */
 let progress;
+/** What goes on after the boot is ready (Visual Studio installing), and the phase it is reported under. */
+let background = [];
+let current = { phase: 'booting', message: '' };
 /**
  * Best-effort: progress reporting must never be what breaks the boot. `update` changes the structured progress
  * (a new step, what is being set up); it stays as it was otherwise.
  */
 export function setSandboxStatus(phase, message, update) {
+    current = { phase, message };
     try {
         if (update)
             progress = fitProgress({ step: 1, steps: 1, title: '', active: [], done: 0, total: 0, ...progress, ...update });
@@ -35,6 +39,20 @@ function fitProgress(p) {
         })),
     };
 }
+/** Whether the boot (another process: the daemon asks) still has this work running in the background. */
+export function backgroundRunning(name) {
+    return (run.readSandboxStatus()?.background ?? []).some((w) => w.state === 'running' && w.name.includes(name));
+}
+/** Lists the work that continues after the boot (the phase and message stay as they are). */
+export function setBackgroundWork(work) {
+    background = work.slice(0, 16).map((w) => ({ name: w.name.slice(0, 64), state: w.state }));
+    try {
+        writeStatus(current.phase, current.message);
+    }
+    catch (e) {
+        warn('Could not update sandbox status: ' + errMsg(e));
+    }
+}
 function ownAddresses() {
     return Object.values(os.networkInterfaces())
         .flat()
@@ -53,5 +71,6 @@ function writeStatus(phase, message) {
         headless: session.headless,
         addresses: ownAddresses(),
         ...(progress ? { progress } : {}),
+        ...(background.length ? { background } : {}),
     });
 }

package/dist/guest/setup/addon-mcp.d.ts

@@ -1,2 +1,2 @@
-/** Sets the add-ons' MCP servers in the sandbox's .claude.json; the names that are on. */
+/** Sets the add-ons' MCP servers in the sandbox's .claude.json (and Codex's config.toml); the names that are on. */
 export declare function writeAddonMcpServers(): string[];

package/dist/guest/setup/addon-mcp.js

@@ -1,23 +1,40 @@
-// The agent add-ons' MCP servers (Playwright, Context7) in the sandbox's own Claude Code: user-scope servers named
-// sbx-... in its .claude.json, set every boot while the add-on is on and removed again when it is off. Your servers
-// (from this PC or added in the sandbox) are never touched, and nothing on this PC changes.
+// The agent add-ons' MCP servers (Playwright, Context7, Perplexity ...) in the sandbox's own Claude Code: user-scope
+// servers named sbx-... in its .claude.json, set every boot while the add-on is on and removed again when it is off.
+// The add-ons marked `codex` also go into the sandbox's Codex config.toml as [mcp_servers.sbx-...] tables. Your servers
+// (from this PC or added in the sandbox) are never touched, and nothing on this PC changes. No secret is written:
+// a server that needs a key reads it from the agent's environment (PERPLEXITY_API_KEY).
 import fs from 'node:fs';
 import path from 'node:path';
-import { addonMcpServer, APPS, withAddonMcpServers } from '../../shared/apps/index.js';
+import { addonMcpServer, APPS, codexWithAddonMcpServers, withAddonMcpServers, } from '../../shared/apps/index.js';
 import { writeJsonAtomic } from '../../shared/io/json.js';
-import { claudeDir } from '../runtime/session.js';
+import { cometExe } from '../browser/comet.js';
+import { exists, mkdirp } from '../runtime/fs.js';
+import { dryRun } from '../runtime/paths.js';
+import { claudeDir, session, stateDir } from '../runtime/session.js';
 import { log, warn } from '../runtime/log.js';
 import { installedMcpAddons } from './agent-addons.js';
 /** The names of every MCP server an add-on can add (the ones the sandbox may remove). */
 const ADDON_MCP_NAMES = APPS.flatMap((a) => (a.mcp ? [a.mcp.name] : []));
-/** Sets the add-ons' MCP servers in the sandbox's .claude.json; the names that are on. */
-export function writeAddonMcpServers() {
-    const servers = {};
-    for (const { id, folder } of installedMcpAddons()) {
+/** Variables only this sandbox can tell an add-on's server (where Comet is). */
+function placeEnv(id) {
+    if (id !== 'comet-mcp')
+        return {};
+    const exe = cometExe();
+    return exe ? { COMET_PATH: exe } : {};
+}
+/** The servers of the add-ons that are on and installed, with their catalogue entry. */
+function addonServers() {
+    return installedMcpAddons().flatMap(({ id, folder, exe }) => {
         const mcp = APPS.find((a) => a.id === id)?.mcp;
-        if (mcp)
-            servers[mcp.name] = addonMcpServer(folder, mcp);
-    }
+        const server = mcp ? addonMcpServer(folder, mcp, { exe, env: placeEnv(id) }) : null;
+        return mcp && server ? [{ mcp, server }] : [];
+    });
+}
+/** Sets the add-ons' MCP servers in the sandbox's .claude.json (and Codex's config.toml); the names that are on. */
+export function writeAddonMcpServers() {
+    const on = addonServers();
+    writeCodexAddonMcpServers(on);
+    const servers = Object.fromEntries(on.map(({ mcp, server }) => [mcp.name, server]));
     const file = path.join(claudeDir, '.claude.json');
     let state = {};
     if (fs.existsSync(file)) {
@@ -47,3 +64,26 @@ export function writeAddonMcpServers() {
         log('Claude Code MCP servers from Apps: ' + names.join(', '));
     return names;
 }
+/** The add-ons marked for Codex in its config.toml (state\codex), when Codex is one of this sandbox's agents. */
+function writeCodexAddonMcpServers(on) {
+    if (dryRun || !session.agents?.codex)
+        return;
+    const file = path.join(stateDir, 'codex', 'config.toml');
+    const servers = Object.fromEntries(on
+        .filter(({ mcp }) => mcp.codex)
+        .map(({ mcp, server }) => [mcp.name, { ...server, ...(mcp.envVars?.length ? { envVars: mcp.envVars } : {}) }]));
+    const before = exists(file) ? fs.readFileSync(file, 'utf8') : '';
+    if (!before && !Object.keys(servers).length)
+        return;
+    const known = APPS.flatMap((a) => (a.mcp?.codex ? [a.mcp.name] : []));
+    const result = codexWithAddonMcpServers(before, servers, known);
+    for (const name of result.skipped)
+        warn('Codex MCP servers from Apps: ' + name + ' is already in config.toml in another form, left as it is');
+    if (result.changed) {
+        mkdirp(path.dirname(file));
+        fs.writeFileSync(file, result.toml, 'utf8');
+    }
+    const names = Object.keys(servers).filter((n) => !result.skipped.includes(n));
+    if (names.length)
+        log('Codex MCP servers from Apps: ' + names.join(', '));
+}

package/dist/guest/setup/agent-addons.d.ts

@@ -1,9 +1,10 @@
-/** The add-on's program when it is chosen and installed, else null. */
+/** The add-on's program when it is chosen and installed (a remote server: its folder once set up), else null. */
 export declare function installedAddon(id: string): string | null;
 /** rtk.exe when rtk is chosen and installed, else null. */
 export declare function installedRtk(): string | null;
-/** The add-ons with an MCP server that are chosen and installed: their folder and server. */
+/** The add-ons with an MCP server that are chosen and installed: their folder and program. */
 export declare function installedMcpAddons(): {
     id: string;
     folder: string;
+    exe: string;
 }[];

package/dist/guest/setup/agent-addons.js

@@ -1,22 +1,31 @@
 // Agent add-ons in this sandbox: an add-on is plugged into the agents only while it is chosen (apps.install) AND its
 // program is really there (a failed download adds no hook, proxy or MCP server that would fail on every use).
+import fs from 'node:fs';
+import path from 'node:path';
 import { APPS, appById } from '../../shared/apps/index.js';
 import { findExe } from '../apps/find-exe.js';
 import { dryRun } from '../runtime/paths.js';
 import { session } from '../runtime/session.js';
 import { tool } from '../toolchains/tool-env.js';
-/** The add-on's program when it is chosen and installed, else null. */
+/** The add-on's program when it is chosen and installed (a remote server: its folder once set up), else null. */
 export function installedAddon(id) {
     const entry = appById(id);
     if (dryRun || !entry || !(session.apps?.install ?? []).includes(id))
         return null;
+    if ('remote' in entry.source) {
+        const folder = tool('apps', id);
+        return fs.existsSync(path.join(folder, '.agent-sandbox-app')) ? folder : null;
+    }
     return findExe(tool('apps', id), entry.exe);
 }
 /** rtk.exe when rtk is chosen and installed, else null. */
 export function installedRtk() {
     return installedAddon('rtk');
 }
-/** The add-ons with an MCP server that are chosen and installed: their folder and server. */
+/** The add-ons with an MCP server that are chosen and installed: their folder and program. */
 export function installedMcpAddons() {
-    return APPS.filter((a) => a.mcp && installedAddon(a.id)).map((a) => ({ id: a.id, folder: tool('apps', a.id) }));
+    return APPS.flatMap((a) => {
+        const exe = a.mcp ? installedAddon(a.id) : null;
+        return exe ? [{ id: a.id, folder: tool('apps', a.id), exe }] : [];
+    });
 }

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

@@ -7,7 +7,7 @@ export interface EnvTarget {
 }
 export declare function agentEnv(tools: Pick<ToolEnv, 'vars' | 'prepend' | 'append'>, target?: EnvTarget): NodeJS.ProcessEnv;
 /** Makes the agent environment machine-wide, so new terminal tabs and anything the agent starts see the same tools. */
-export declare function persistEnvironment(env: NodeJS.ProcessEnv, toolVars: string[]): void;
+export declare function persistEnvironment(env: NodeJS.ProcessEnv, toolVars: string[], additive?: boolean): Promise<void>;
 /**
  * Adds variables and PATH folders machine-wide after boot (`sbx-db start`): new terminal tabs see them.
  * additive: for a project registered later. Only variables not set yet, and folders go to the END of PATH, so what

package/dist/guest/setup/environment.js

@@ -3,13 +3,13 @@ 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 { exists, mkdirp } from '../runtime/fs.js';
-import { execOutput, runScriptWithJson } from '../runtime/process.js';
+import { execOutput, runScriptWithJson, runScriptWithJsonAsync } 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';
+import { appendMissing, expandVars, isPinnedNodeDir, msvcBeforeGitUsr, 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. */
@@ -57,26 +57,39 @@ export function agentEnv(tools, target = { workspace, project: session.project,
     // 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());
     const base = (target.base.PATH ?? '').split(path.delimiter).filter((d) => d && !runners.includes(d.toLowerCase()));
-    env.PATH = [...new Set([...tools.prepend, ...base, ...tools.append])].join(path.delimiter);
+    // MSVC's link.exe before Git's coreutils link.exe, wherever each came from.
+    env.PATH = msvcBeforeGitUsr([...new Set([...tools.prepend, ...base, ...tools.append])]).join(path.delimiter);
     return env;
 }
 /** Makes the agent environment machine-wide, so new terminal tabs and anything the agent starts see the same tools. */
-export function persistEnvironment(env, toolVars) {
+export async function persistEnvironment(env, toolVars, additive = false) {
     if (!isWin || dryRun || testMode)
         return;
     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', {
+        await runScriptWithJsonAsync('set-machine-environment.ps1', 'SettingsFile', {
             vars,
-            path: planPath({
-                entries: [env.PATH ?? '', ...installedAgentDirs()],
-                exists,
-                drop: (dir) => isPinnedNodeDir(dir, nvmHome()),
-            }).join(path.delimiter),
-            add: [],
-            additive: false,
+            ...(additive
+                ? {
+                    // Visual Studio done: variables not set yet, new folders at the end of the machine PATH.
+                    path: null,
+                    add: planPath({
+                        entries: (env.PATH ?? '').split(path.delimiter),
+                        exists,
+                        drop: (dir) => isPinnedNodeDir(dir, nvmHome()),
+                    }),
+                }
+                : {
+                    path: planPath({
+                        entries: [env.PATH ?? '', ...installedAgentDirs()],
+                        exists,
+                        drop: (dir) => isPinnedNodeDir(dir, nvmHome()),
+                    }).join(path.delimiter),
+                    add: [],
+                }),
+            additive,
         });
     }
     catch (e) {

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

@@ -1,7 +1,12 @@
 /** The proxy's log (it redacts keys and tokens in what it logs). */
 export declare const HEADROOM_LOG: string;
 /**
- * Starts the proxy when Headroom is chosen and installed; its base URL once it answers, else null (Claude Code then
- * talks to the API directly).
+ * Starts the proxy process when Headroom is chosen and installed (nothing waits for it). True when the proxy is
+ * running or starting; `awaitHeadroom` then waits until it answers. The environment is the agent's.
  */
-export declare function startHeadroom(env: NodeJS.ProcessEnv): Promise<string | null>;
+export declare function spawnHeadroom(env: NodeJS.ProcessEnv): Promise<boolean>;
+/**
+ * Waits until the proxy answers as Headroom; its base URL, else null (Claude Code then talks to the API directly).
+ * Starts it first when `spawnHeadroom` did not.
+ */
+export declare function awaitHeadroom(env: NodeJS.ProcessEnv): Promise<string | null>;

package/dist/guest/setup/headroom.js

@@ -28,31 +28,60 @@ function answersAsHeadroom(port) {
         req.on('error', () => resolve(false));
     });
 }
+/** The one start of the proxy in this process (the early start, the one after Apps and the wait share it). */
+let starting = null;
+/** Whether the proxy is installed and may be used (the agent environment does not name another API address). */
+function usable(env) {
+    const exe = installedAddon('headroom');
+    return exe && !env.ANTHROPIC_BASE_URL ? exe : null;
+}
 /**
- * Starts the proxy when Headroom is chosen and installed; its base URL once it answers, else null (Claude Code then
- * talks to the API directly).
+ * Starts the proxy process when Headroom is chosen and installed (nothing waits for it). True when the proxy is
+ * running or starting; `awaitHeadroom` then waits until it answers. The environment is the agent's.
  */
-export async function startHeadroom(env) {
-    const exe = installedAddon('headroom');
+export async function spawnHeadroom(env) {
+    const attempt = (starting ??= startProxy(env));
+    const started = await attempt;
+    // Not installed (yet): a later call, after the Apps step, may still start it.
+    if (!started && starting === attempt)
+        starting = null;
+    return started;
+}
+async function startProxy(env) {
+    const exe = usable(env);
     if (!exe)
-        return null;
-    if (env.ANTHROPIC_BASE_URL) {
-        log('Headroom: not used, ANTHROPIC_BASE_URL is set in the agent environment (' + env.ANTHROPIC_BASE_URL + ')');
-        return null;
-    }
-    const port = HEADROOM_PORT;
-    if (!(await portOpen(port))) {
-        const out = fs.openSync(HEADROOM_LOG, 'a');
-        spawn(exe, headroomArgs(port), {
+        return false;
+    if (await portOpen(HEADROOM_PORT))
+        return true;
+    const out = fs.openSync(HEADROOM_LOG, 'a');
+    try {
+        spawn(exe, headroomArgs(HEADROOM_PORT), {
             detached: true,
             stdio: ['ignore', out, out],
             windowsHide: true,
             env: headroomEnv(env),
         }).unref();
+    }
+    finally {
         fs.closeSync(out);
-        if (!(await waitForPort(port, 90)))
-            throw new Error('the Headroom proxy did not start on port ' + port + '; see ' + HEADROOM_LOG);
     }
+    return true;
+}
+/**
+ * Waits until the proxy answers as Headroom; its base URL, else null (Claude Code then talks to the API directly).
+ * Starts it first when `spawnHeadroom` did not.
+ */
+export async function awaitHeadroom(env) {
+    if (!installedAddon('headroom'))
+        return null;
+    if (env.ANTHROPIC_BASE_URL) {
+        log('Headroom: not used, ANTHROPIC_BASE_URL is set in the agent environment (' + env.ANTHROPIC_BASE_URL + ')');
+        return null;
+    }
+    const port = HEADROOM_PORT;
+    await spawnHeadroom(env);
+    if (!(await waitForPort(port, 90)))
+        throw new Error('the Headroom proxy did not start on port ' + port + '; see ' + HEADROOM_LOG);
     if (!(await answersAsHeadroom(port)))
         throw new Error('port ' + port + ' is taken by another program; Claude Code talks to the API directly');
     log('Headroom: Claude Code reaches the API through ' + headroomUrl(port) + ' (log: ' + HEADROOM_LOG + ')');

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

@@ -30,3 +30,31 @@ export declare function rebuildPath(o: {
 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;
+/** MSVC's compiler folder (`...\VC\Tools\MSVC\<version>\bin\Host<arch>\<arch>`): where the real link.exe lives. */
+export declare function isMsvcToolsDir(folder: string): boolean;
+/** Git for Windows' `usr\bin` (coreutils): its link.exe is not MSVC's linker, and it has many other lookalikes. */
+export declare function isGitUsrBin(folder: string): boolean;
+/**
+ * The same folders with MSVC's tools before Git's `usr\bin`, so `link` is the linker and not coreutils' `link` (a
+ * msvc Rust build then died with os error 1392). Nothing else moves: MSVC folders found after the first Git `usr\bin`
+ * are put just before it, in their own order.
+ */
+export declare function msvcBeforeGitUsr(folders: readonly string[]): string[];
+/** How `installedToolPaths` looks at the tools folder (injected so it is a pure function). */
+export interface ToolsFs {
+    readonly exists: (file: string) => boolean;
+    /** Names in a folder ([] when it is missing). */
+    readonly list: (folder: string) => readonly string[];
+}
+/**
+ * What a toolchain that is already installed in the persistent tools folder adds to PATH even when the project in this
+ * session did not ask for it (python and rust: another project of the same sandbox, a terminal tab, a script that
+ * calls `python`). Only PATH entries and the two variables rust's own tools read, nothing is installed or changed,
+ * and the folders go at the END so they never shadow what a project's own toolchains put first. `skip` names the
+ * toolchains whose own step already runs (they bring their own entries).
+ */
+export declare function installedToolPaths(toolsDir: string, fsApi: ToolsFs, skip?: ReadonlySet<'python' | 'rust'>): {
+    readonly append: string[];
+    readonly vars: Record<string, string>;
+    readonly summary: string[];
+};

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

@@ -30,7 +30,7 @@ export function planPath(input) {
         seen.add(key);
         result.push(entry);
     }
-    return result;
+    return msvcBeforeGitUsr(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) {
@@ -42,7 +42,7 @@ export function appendMissing(base, extra, skip = () => false) {
         seen.add(key);
         return true;
     });
-    return [...splitPath(base), ...added].join(';');
+    return msvcBeforeGitUsr([...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
@@ -65,3 +65,70 @@ export function isPinnedNodeDir(folder, nvmHome) {
     const home = pathKey(nvmHome);
     return key.startsWith(home + '\\') && /^v\d/.test(path.win32.basename(key));
 }
+/** MSVC's compiler folder (`...\VC\Tools\MSVC\<version>\bin\Host<arch>\<arch>`): where the real link.exe lives. */
+export function isMsvcToolsDir(folder) {
+    return /\\vc\\tools\\msvc\\[^\\]+\\bin\\host[^\\]+\\[^\\]+$/.test(pathKey(folder));
+}
+/** Git for Windows' `usr\bin` (coreutils): its link.exe is not MSVC's linker, and it has many other lookalikes. */
+export function isGitUsrBin(folder) {
+    const key = pathKey(folder);
+    return key.endsWith('\\usr\\bin') && /\\git(\\|$)/.test(key);
+}
+/**
+ * The same folders with MSVC's tools before Git's `usr\bin`, so `link` is the linker and not coreutils' `link` (a
+ * msvc Rust build then died with os error 1392). Nothing else moves: MSVC folders found after the first Git `usr\bin`
+ * are put just before it, in their own order.
+ */
+export function msvcBeforeGitUsr(folders) {
+    const firstGit = folders.findIndex(isGitUsrBin);
+    if (firstGit < 0 || !folders.slice(firstGit).some(isMsvcToolsDir))
+        return [...folders];
+    const late = folders.slice(firstGit).filter(isMsvcToolsDir);
+    return [...folders.slice(0, firstGit), ...late, ...folders.slice(firstGit).filter((f) => !isMsvcToolsDir(f))];
+}
+/** Compares "3.9.1" and "3.15.2" by their numbers. */
+function compareVersions(a, b) {
+    const x = a.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    const y = b.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    for (let i = 0; i < Math.max(x.length, y.length); i++) {
+        const d = (x[i] ?? 0) - (y[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+/**
+ * What a toolchain that is already installed in the persistent tools folder adds to PATH even when the project in this
+ * session did not ask for it (python and rust: another project of the same sandbox, a terminal tab, a script that
+ * calls `python`). Only PATH entries and the two variables rust's own tools read, nothing is installed or changed,
+ * and the folders go at the END so they never shadow what a project's own toolchains put first. `skip` names the
+ * toolchains whose own step already runs (they bring their own entries).
+ */
+export function installedToolPaths(toolsDir, fsApi, skip = new Set()) {
+    const join = (...parts) => path.win32.join(toolsDir, ...parts);
+    const append = [];
+    const vars = {};
+    const summary = [];
+    if (!skip.has('python')) {
+        const newest = fsApi
+            .list(join('python'))
+            .filter((n) => /^python-\d+(\.\d+)*$/.test(n) && fsApi.exists(join('python', n, 'python.exe')))
+            .map((n) => n.slice('python-'.length))
+            .sort(compareVersions)
+            .pop();
+        if (newest) {
+            const dir = join('python', 'python-' + newest);
+            append.push(dir, join('python', 'python-' + newest, 'Scripts'));
+            if (fsApi.exists(join('shims', 'py.cmd')))
+                append.push(join('shims'));
+            summary.push('python: ' + newest + ' (already installed here, on PATH for every project)');
+        }
+    }
+    if (!skip.has('rust') && fsApi.exists(join('rust', 'cargo', 'bin', 'rustup.exe'))) {
+        append.push(join('rust', 'cargo', 'bin'));
+        vars.RUSTUP_HOME = join('rust', 'rustup');
+        vars.CARGO_HOME = join('rust', 'cargo');
+        summary.push('rust: rustup (already installed here, on PATH for every project)');
+    }
+    return { append, vars, summary };
+}

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

@@ -1 +1 @@
-export declare function installShellPath(): void;
+export declare function installShellPath(): Promise<void>;

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

@@ -5,13 +5,13 @@ 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() {
+import { runScriptAsync } from '../runtime/process.js';
+export async 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', [
+    await runScriptAsync('install-shell-path.ps1', [
         '-Helper',
         helper,
         '-PwshDir',

package/dist/guest/toolchains/fivem/artifacts.d.ts

@@ -1,6 +1,53 @@
+import { z } from 'zod';
+export declare const VERSIONS_URL = "https://changelogs-live.fivem.net/api/changelog/versions/win32/server";
+export declare const ARTIFACTS_PAGE = "https://runtime.fivem.net/artifacts/fivem/build_server_windows/master/";
+/** The subject of the signature on FXServer.exe (checked on build 35245, 2026-11). */
+export declare const FXSERVER_SIGNER: RegExp;
+export declare const CHANNELS: readonly ["recommended", "optional", "latest", "critical"];
+export type Channel = (typeof CHANNELS)[number];
 export interface FivemArtifact {
     readonly build: number;
     readonly url: string;
+    /** The channel that names it, when one does. */
+    readonly channel?: Channel;
+    /** The txAdmin version it bundles, when the versions API says. */
+    readonly txAdmin?: string;
 }
+/** The versions API's answer (its other fields, such as support_policy, are not needed). */
+export declare const VersionsSchema: z.ZodObject<{
+    recommended: z.ZodString;
+    recommended_download: z.ZodString;
+    recommended_txadmin: z.ZodOptional<z.ZodString>;
+    optional: z.ZodString;
+    optional_download: z.ZodString;
+    optional_txadmin: z.ZodOptional<z.ZodString>;
+    latest: z.ZodString;
+    latest_download: z.ZodString;
+    latest_txadmin: z.ZodOptional<z.ZodString>;
+    critical: z.ZodString;
+    critical_download: z.ZodString;
+    critical_txadmin: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Every channel's build, from the versions API's JSON (throws on any other shape). */
+export declare function parseVersions(json: unknown): Record<Channel, FivemArtifact>;
+/** The builds the artifacts page links to (newest first), as server.zip downloads. Reads at most 4 MB of it. */
+export declare function parseArtifactsPage(html: string): FivemArtifact[];
+/** What a setting names: a channel, or a build number. */
+export declare function artifactSetting(setting: string): Channel | number | null;
+/** The build a setting names among the channels and the page's builds, or null. */
+export declare function chooseArtifact(setting: string, channels: Record<Channel, FivemArtifact>, page?: readonly FivemArtifact[]): FivemArtifact | null;
+export interface ArtifactSources {
+    readonly versions?: () => Promise<unknown>;
+    readonly page?: () => Promise<string>;
+}
+/** The channels from the versions API. */
+export declare function fetchChannels(src?: ArtifactSources): Promise<Record<Channel, FivemArtifact>>;
 /** The build an artifact setting names, or null when it cannot be told. */
-export declare function pickArtifact(_setting: string): Promise<FivemArtifact | null>;
+export declare function pickArtifact(setting: string, src?: ArtifactSources): Promise<FivemArtifact | null>;
+export type ArtifactTrust = 'signed' | 'unsigned-allowed' | 'refused';
+/**
+ * Whether a downloaded build may be used. The artifacts have no checksums: the Authenticode signature on FXServer.exe
+ * stands in for one, so downloads.requireChecksum refuses a build whose FXServer.exe is not validly signed by Rockstar
+ * Games; without that setting an unsigned one is used (with a warning).
+ */
+export declare function artifactTrust(requireChecksum: boolean, signerSubject: string): ArtifactTrust;