windows-development-sandbox 0.0.0-stage → 1.1.0

package/dist/core/types.d.ts

@@ -0,0 +1,190 @@
+import type { z } from 'zod';
+import type { Config as ConfigSchema, GitAccess as GitAccessSchema, Harness as HarnessSchema, LocalOverrides, Mapping as MappingSchema } from './schema.js';
+export type { AttachEndpointT as AttachEndpoint, GuestRequestT as GuestRequest, GuestResponseT as GuestResponse, SandboxStatusT as SandboxStatus, SessionStatusT as SessionStatus } from '../shared/schema.js';
+export type Config = z.output<typeof ConfigSchema>;
+export type Overrides = z.output<typeof LocalOverrides>;
+export type GitAccess = z.output<typeof GitAccessSchema>;
+export type Harness = z.output<typeof HarnessSchema>;
+export type Mapping = z.output<typeof MappingSchema>;
+export type Toolchains = Config['toolchains'];
+export type ClaudeProfileConfig = Config['claudeProfile'];
+export interface ResolvedMapping {
+    host: string;
+    guest: string;
+    readOnly: boolean;
+}
+export interface LocalConfigFile {
+    path: string;
+    hash: string;
+    data: unknown;
+}
+export interface LoadedConfig {
+    config: Config;
+    configPath: string | null;
+    base: string;
+}
+export interface RunRequest {
+    packageRoot: string;
+    loaded: LoadedConfig;
+    cwd: string;
+    workspace?: string;
+    harness?: string;
+    noAgent: boolean;
+    noLocalConfig: boolean;
+    trustConfig: boolean;
+    scripts: string[];
+    headless?: boolean;
+    /** --database: start these whatever the config and detection say. */
+    databases?: string[];
+    nodeVersion?: string;
+    pythonVersion?: string;
+    ask?: (question: string) => Promise<boolean>;
+}
+export interface ResolvedRun {
+    config: Config;
+    storageRoot: string;
+    dataPath: string;
+    workspaceHost: string;
+    harnessName: string;
+    scripts: string[];
+    localConfigPath: string | null;
+    notes: string[];
+    versions: ToolVersions;
+    /** Your config asks for guestWorkspace "mirror" (project roots then appear at their PC paths too). */
+    mirror?: boolean;
+}
+/** A requested version plus where the request came from (shown to the user). */
+export interface VersionSpec {
+    spec: string;
+    source: string;
+}
+export interface ToolVersions {
+    node: VersionSpec;
+    nodeExtra: string[];
+    python: VersionSpec;
+}
+export interface HostProbe {
+    nodeDir: string | null;
+    harnessExe: {
+        dir: string;
+        file: string;
+    } | null;
+    gitDir: string | null;
+    nvmDir: string | null;
+    hostNodeVersion: string;
+    /** This PC's Node is one of nvm's versions, so it comes in with nvm and nodeDir stays unmapped. */
+    nvmNode?: boolean;
+    /** This PC has Volta / pyenv-win (VOLTA_HOME / PYENV set). */
+    volta?: boolean;
+    pyenv?: boolean;
+}
+/** A database the sandbox runs, and why ("compose.yaml: a compose service runs Postgres"). */
+export interface DatabasePlan {
+    database: 'postgres' | 'mysql' | 'sqlserver' | 'mongodb' | 'redis' | 'dynamodb';
+    reasons: string[];
+    version: string;
+    port: number;
+    adminPort?: number;
+}
+/** databases / pcLanguages: use these instead of scanning (tests). */
+export interface GenerateOptions {
+    packageRoot: string;
+    run: ResolvedRun;
+    harnessArgs: string[];
+    probe: HostProbe;
+    freeMemoryBytes?: number;
+    databases?: DatabasePlan[];
+    pcLanguages?: import('./detect-toolchains.js').AutoToolchain[];
+    /** More projects to map (a restart that adds one keeps the ones in use); knownProjects: instead of known-projects.json (tests). */
+    extraProjects?: string[];
+    knownProjects?: string[];
+    /** false: no agent session at boot. */
+    autoSession?: boolean;
+}
+export interface Generated {
+    wsbPath: string;
+    launchPath: string;
+    launchId: string;
+    sessionPath: string;
+    memoryMb: number;
+    mappings: ResolvedMapping[];
+    profile: ProfileResult;
+    databases: DatabasePlan[];
+    /** Project roots and other projects mapped with the launch folder. */
+    projects: {
+        roots: {
+            host: string;
+            guest: string;
+        }[];
+        projects: {
+            host: string;
+            guest: string;
+        }[];
+        notes: string[];
+    };
+    toolchains: Record<import('./detect-toolchains.js').AutoToolchain, import('./detect-toolchains.js').ToolchainDecision>;
+}
+/** secretsRemoved: what secrets.strip kept on this PC, e.g. "settings.json env.AWS_SECRET_ACCESS_KEY". */
+export interface ProfileResult {
+    hostDir: string | null;
+    staged: string[];
+    skipped: string[];
+    credentials: boolean;
+    secretsRemoved: string[];
+}
+/** Written by the host to C:\AgentLaunch\session.json (read-only for the guest): everything the guest needs to know. */
+export interface GuestSession {
+    launchId: string;
+    project: string;
+    workspace: string;
+    workspaceHost: string;
+    /** The launch folder's project id (file-name safe; status files and sessions use it). Older launch folders lack it. */
+    projectId?: string;
+    /** Where other projects appear (C:\Projects), and the project roots' guest folders. Older launch folders lack them. */
+    projectsDir?: string;
+    roots?: string[];
+    /** false: start no agent session at boot (a restart that adds a project opens its sessions itself). */
+    autoSession?: boolean;
+    harnessName: string;
+    harness: Harness | null;
+    harnessArguments: string[];
+    persistAgentState: boolean;
+    networking: boolean;
+    headless: boolean;
+    network: Config['network'];
+    provisioning: Config['provisioning'];
+    toolchains: Toolchains;
+    databases: DatabasePlan[];
+    versions: ToolVersions;
+    /** Every database `sbx-db start` can run later (older launch folders lack it). */
+    databaseCatalog?: DatabasePlan[];
+    attach: Config['attach'];
+    hooks: Config['hooks'];
+    downloads: Config['downloads'];
+    /** nodeVersion: this PC's Node (e.g. 22.11.0), found under nvm\v<version> when nvm is mapped, else under node. */
+    /** volta / pyenv: this PC uses them (their "auto" settings turn them on in the sandbox too). */
+    hostTools: {
+        node: boolean;
+        nodeVersion: string | null;
+        harnessExecutable: string | null;
+        git: boolean;
+        nvm: boolean;
+        volta?: boolean;
+        pyenv?: boolean;
+    };
+    claudeProfile: {
+        overwrite: boolean;
+        items: string[];
+        credentials: boolean;
+        hostConfigDir: string | null;
+        syncClaudeMem: boolean;
+    };
+    personalization: boolean;
+    /** Drives other than C: that bootstrap.ps1 makes with subst before anything uses them: letter D-Z onto C:\Mirror\<letter>. */
+    substDrives?: {
+        letter: string;
+        target: string;
+    }[];
+    /** sandbox.cpuLimit as a number (null = no cap); sandbox\cpucap.ps1 applies it before anything starts. */
+    cpuLimitPercent?: number | null;
+}

package/dist/core/types.js

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

package/dist/core/util.d.ts

@@ -0,0 +1,60 @@
+export declare const isWin: boolean;
+/** An expected problem the user can act on: what went wrong, and (optionally) how to fix it. */
+export declare class UserError extends Error {
+    readonly fix?: string | undefined;
+    constructor(message: string, fix?: string | undefined);
+}
+/** Throws a UserError. Typed explicitly so TypeScript narrows after calls (arrow functions need it to act as never). */
+export declare const fail: (message: string, fix?: string) => never;
+/**
+ * Parses JSON with comments and trailing commas (JSONC, like VS Code's settings.json). Errors name the file, line
+ * and column, and say what to fix.
+ */
+export declare const parseJsonc: <T>(text: string, source: string) => T;
+export declare const readJsonc: <T>(file: string) => T;
+export declare const errMsg: (e: unknown) => string;
+export declare const ensureDir: (p: string) => void;
+export declare const dirExists: (p: string) => boolean;
+export declare const fileExists: (p: string) => boolean;
+export declare const readJson: <T>(p: string) => T;
+export declare const tryReadJson: <T>(p: string) => T | null;
+/** Atomic (a crash or a second command never leaves half a file); refused outside temp during the self-test. */
+export declare const writeJson: (p: string, value: unknown) => void;
+export declare const realPath: (p: string) => string;
+export declare const xmlEscape: (v: string) => string;
+export declare const homeDir: () => string;
+export declare const sleep: (ms: number) => Promise<void>;
+/** Expands %VAR% and resolves relative paths against `base`. */
+export declare const expandPath: (input: string, base: string) => string;
+export declare const isRootPath: (p: string) => boolean;
+export declare const isUserProfile: (p: string) => boolean;
+export declare const isInsideOrEqual: (parent: string, child: string) => boolean;
+/**
+ * Text that came from the sandbox, made safe to print: control characters and escape sequences are removed except
+ * plain colours (SGR), so nothing written by the sandbox can drive your terminal (titles, clipboard, cursor tricks).
+ */
+export declare const safeText: (text: string) => string;
+export declare const findOnPath: (names: string[]) => string | null;
+/** True if `p` itself is a symlink or junction (lstat; never follows it). */
+export declare const isLink: (p: string) => boolean;
+/** Removes a symlink or junction itself (never its target). Junctions need rmdir on Windows. */
+export declare const removeLink: (p: string) => void;
+/**
+ * The sandbox can write anywhere in its data folder, so it could swap a folder for a junction that points at this
+ * PC's own disk. Before the host reads, writes or deletes anything under `root`, every existing path component from
+ * `root` down to `target` must be a plain folder/file. Throws otherwise.
+ */
+export declare const assertNoLinks: (root: string, target: string) => void;
+/** Runs a PowerShell script and returns its exit code (and stdout when `capture`). */
+export declare const runPowerShell: (script: string, capture?: boolean) => {
+    status: number;
+    stdout: string;
+};
+/** Runs a program (an absolute path: `SYSTEM.*`, never a bare name) and returns its stdout, or '' if it failed or timed out. */
+export declare const captureOutput: (file: string, args: string[], options?: {
+    timeout?: number;
+    cwd?: string;
+    maxBuffer?: number;
+}) => string;
+/** Async variant (does not block the event loop), resolving with stdout. */
+export declare const runPowerShellAsync: (script: string) => Promise<string>;

package/dist/core/util.js

@@ -0,0 +1,154 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { SYSTEM } from '../shared/system.js';
+import { writeJsonAtomic } from '../shared/rundir.js';
+import { assertTestWritable } from '../shared/test-guard.js';
+import { parse as parseJsoncText, printParseErrorCode } from 'jsonc-parser';
+export const isWin = process.platform === 'win32';
+/** An expected problem the user can act on: what went wrong, and (optionally) how to fix it. */
+export class UserError extends Error {
+    fix;
+    constructor(message, fix) {
+        super(message);
+        this.fix = fix;
+        this.name = 'UserError';
+    }
+}
+/** Throws a UserError. Typed explicitly so TypeScript narrows after calls (arrow functions need it to act as never). */
+export const fail = (message, fix) => { throw new UserError(message, fix); };
+/**
+ * Parses JSON with comments and trailing commas (JSONC, like VS Code's settings.json). Errors name the file, line
+ * and column, and say what to fix.
+ */
+export const parseJsonc = (text, source) => {
+    const errors = [];
+    const value = parseJsoncText(text.replace(/^/, ''), errors, { allowTrailingComma: true, disallowComments: false });
+    if (errors.length) {
+        const { offset, error } = errors[0];
+        const before = text.slice(0, offset).split(/\r?\n/);
+        fail(source + ' is not valid JSON (line ' + before.length + ', column ' + (before[before.length - 1].length + 1) + ': ' + printParseErrorCode(error) + ').', 'Fix that spot in the file. Comments (// and /* */) and trailing commas are fine.');
+    }
+    return value;
+};
+export const readJsonc = (file) => parseJsonc(fs.readFileSync(file, 'utf8'), file);
+export const errMsg = (e) => e instanceof Error ? e.message : String(e);
+export const ensureDir = (p) => { fs.mkdirSync(p, { recursive: true }); };
+export const dirExists = (p) => { try {
+    return fs.statSync(p).isDirectory();
+}
+catch {
+    return false;
+} };
+export const fileExists = (p) => { try {
+    return fs.statSync(p).isFile();
+}
+catch {
+    return false;
+} };
+export const readJson = (p) => JSON.parse(fs.readFileSync(p, 'utf8').replace(/^\uFEFF/, ''));
+export const tryReadJson = (p) => { try {
+    return readJson(p);
+}
+catch {
+    return null;
+} };
+/** Atomic (a crash or a second command never leaves half a file); refused outside temp during the self-test. */
+export const writeJson = (p, value) => writeJsonAtomic(p, value);
+export const realPath = (p) => { try {
+    return fs.realpathSync(p);
+}
+catch {
+    return p;
+} };
+export const xmlEscape = (v) => v.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+export const homeDir = () => process.env.USERPROFILE ?? os.homedir();
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Expands %VAR% and resolves relative paths against `base`. */
+export const expandPath = (input, base) => {
+    const expanded = input.replace(/%([^%]+)%/g, (_m, name) => process.env[name] ?? '%' + name + '%').replace(/^~(?=$|[\\/])/, homeDir());
+    return path.resolve(path.isAbsolute(expanded) ? expanded : path.join(base, expanded));
+};
+export const isRootPath = (p) => { const n = path.resolve(p); return n.toLowerCase() === path.parse(n).root.toLowerCase(); };
+export const isUserProfile = (p) => { const profile = process.env.USERPROFILE ?? process.env.HOME ?? ''; return profile !== '' && path.resolve(p).toLowerCase() === path.resolve(profile).toLowerCase(); };
+export const isInsideOrEqual = (parent, child) => {
+    const rel = path.relative(path.resolve(parent).toLowerCase(), path.resolve(child).toLowerCase());
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+};
+/**
+ * Text that came from the sandbox, made safe to print: control characters and escape sequences are removed except
+ * plain colours (SGR), so nothing written by the sandbox can drive your terminal (titles, clipboard, cursor tricks).
+ */
+export const safeText = (text) => text.replace(/\x1b\[[0-9;]*m|\x1b(\[[0-9;?]*[ -\/]*[@-~]|\][^\x07\x1b]*(\x07|\x1b\\)|[@-Z\\-_])|[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, (m) => (/^\x1b\[[0-9;]*m$/.test(m) ? m : ''));
+export const findOnPath = (names) => {
+    const dirs = (process.env.PATH ?? process.env.Path ?? '').split(path.delimiter).filter((d) => d !== '');
+    for (const name of names)
+        for (const dir of dirs) {
+            const candidate = path.join(dir, name);
+            if (fileExists(candidate))
+                return candidate;
+        }
+    return null;
+};
+/** True if `p` itself is a symlink or junction (lstat; never follows it). */
+export const isLink = (p) => { try {
+    return fs.lstatSync(p).isSymbolicLink();
+}
+catch {
+    return false;
+} };
+/** Removes a symlink or junction itself (never its target). Junctions need rmdir on Windows. */
+export const removeLink = (p) => { assertTestWritable(p); try {
+    fs.unlinkSync(p);
+}
+catch {
+    fs.rmdirSync(p);
+} };
+/**
+ * The sandbox can write anywhere in its data folder, so it could swap a folder for a junction that points at this
+ * PC's own disk. Before the host reads, writes or deletes anything under `root`, every existing path component from
+ * `root` down to `target` must be a plain folder/file. Throws otherwise.
+ */
+export const assertNoLinks = (root, target) => {
+    const rel = path.relative(path.resolve(root), path.resolve(target));
+    if (rel.startsWith('..') || path.isAbsolute(rel))
+        fail('Refusing to touch ' + target + ': it is outside ' + root);
+    let current = path.resolve(root);
+    for (const part of ['', ...rel.split(path.sep).filter(Boolean)]) {
+        current = part ? path.join(current, part) : current;
+        if (isLink(current))
+            fail('Refusing to touch ' + target + ': ' + current + ' is a link (possible escape attempt from the sandbox).');
+    }
+};
+/**
+ * PowerShell arguments for a script passed encoded (no quoting issues, no progress-bar noise on stderr). Output is
+ * UTF-8: Windows PowerShell 5.1 otherwise writes redirected stdout in the OEM code page, mangling non-ASCII (regional
+ * date formats, wallpaper paths). UTF8Encoding($false): no byte-order mark in front of the output.
+ */
+const powerShellArgs = (script) => {
+    const prelude = "[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding $false\n$ProgressPreference = 'SilentlyContinue'\n";
+    const encoded = Buffer.from(prelude + script, 'utf16le').toString('base64');
+    // -OutputFormat Text: with redirected output PowerShell would otherwise print its progress stream as "#< CLIXML" XML.
+    return ['-NoLogo', '-NoProfile', '-NonInteractive', '-OutputFormat', 'Text', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded];
+};
+/** Runs a PowerShell script and returns its exit code (and stdout when `capture`). */
+export const runPowerShell = (script, capture = false) => {
+    const result = spawnSync(SYSTEM.powershell(), powerShellArgs(script), { stdio: capture ? ['ignore', 'pipe', 'inherit'] : 'inherit', encoding: 'utf8', windowsHide: true });
+    if (result.error)
+        throw result.error;
+    return { status: result.status ?? 1, stdout: result.stdout ?? '' };
+};
+/** Runs a program (an absolute path: `SYSTEM.*`, never a bare name) and returns its stdout, or '' if it failed or timed out. */
+export const captureOutput = (file, args, options = {}) => {
+    const result = spawnSync(file, args, { encoding: 'utf8', windowsHide: true, timeout: 60000, ...options });
+    return result.status === 0 ? result.stdout ?? '' : '';
+};
+/** Async variant (does not block the event loop), resolving with stdout. */
+export const runPowerShellAsync = (script) => new Promise((resolve, reject) => {
+    const child = spawn(SYSTEM.powershell(), powerShellArgs(script), { stdio: ['ignore', 'pipe', 'inherit'], windowsHide: true });
+    let out = '';
+    child.stdout.on('data', (d) => { out += d.toString('utf8'); });
+    child.on('error', reject);
+    child.on('close', () => resolve(out));
+});

package/dist/core/workspace.d.ts

@@ -0,0 +1,18 @@
+import type { Config, Overrides, ResolvedRun, RunRequest, ToolVersions } from './types.js';
+/**
+ * 'auto' guest workspace: C:\Workspace\<folder name>. Keeping the real folder name means Claude's per-project history
+ * and claude-mem's project name match this PC instead of every project being "Workspace".
+ */
+export declare const autoGuestWorkspace: (workspaceHost: string) => string;
+/** The Node version a Volta project pins ("volta": { "node": "20.11.1" } in package.json), so nvm defaults to it too. */
+export declare const voltaNode: (workspace: string) => string | null;
+/**
+ * Picks tool versions. Highest priority first: command line, the folder's .sandbox-config.json,
+ * version files in the workspace (.nvmrc, .node-version, .python-version), the tool config, this PC's node version.
+ */
+export declare const resolveVersions: (config: Config, workspace: string, local: Overrides, req: {
+    nodeVersion?: string;
+    pythonVersion?: string;
+}, hostNodeVersion: string) => ToolVersions;
+/** Precedence (lowest to highest): built-in defaults, user config, .sandbox-config.json in the workspace, command-line flags. */
+export declare const resolveRun: (req: RunRequest, hostNodeVersion?: string) => Promise<ResolvedRun>;

package/dist/core/workspace.js

@@ -0,0 +1,128 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { planMirrorWorkspace } from '../shared/guest-paths.js';
+import { DATABASES } from './detect-databases.js';
+import { applyOverrides, describeOverrides, isTrusted, normalizeOverrides, readLocalConfig, saveTrust, trustStorePath } from './local-config.js';
+import { assertSafeWorkspace } from './safe-paths.js';
+import { dirExists, expandPath, fail, fileExists } from './util.js';
+/**
+ * 'auto' guest workspace: C:\Workspace\<folder name>. Keeping the real folder name means Claude's per-project history
+ * and claude-mem's project name match this PC instead of every project being "Workspace".
+ */
+export const autoGuestWorkspace = (workspaceHost) => {
+    const name = path.basename(workspaceHost).replace(/[^A-Za-z0-9._ -]/g, '_').replace(/^[. ]+|[. ]+$/g, '');
+    return 'C:\\Workspace\\' + (name || 'project');
+};
+const firstLine = (file) => {
+    if (!fileExists(file))
+        return null;
+    const line = fs.readFileSync(file, 'utf8').replace(/^/, '').split(/\r?\n/).map((l) => l.replace(/#.*$/, '').trim()).find((l) => l !== '');
+    return line ?? null;
+};
+const VOLTA_PIN = 'package.json volta.node';
+const PackageJson = z.object({ volta: z.object({ node: z.string().regex(/^\d+(\.\d+){0,2}$/).optional() }).optional() });
+/** The Node version a Volta project pins ("volta": { "node": "20.11.1" } in package.json), so nvm defaults to it too. */
+export const voltaNode = (workspace) => {
+    const file = path.join(workspace, 'package.json');
+    if (!fileExists(file))
+        return null;
+    try {
+        return PackageJson.safeParse(JSON.parse(fs.readFileSync(file, 'utf8').replace(/^/, ''))).data?.volta?.node ?? null;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Picks tool versions. Highest priority first: command line, the folder's .sandbox-config.json,
+ * version files in the workspace (.nvmrc, .node-version, .python-version), the tool config, this PC's node version.
+ */
+export const resolveVersions = (config, workspace, local, req, hostNodeVersion) => {
+    const localTools = (local.toolchains ?? {});
+    const pick = (cli, localValue, files, configured) => {
+        if (cli)
+            return { spec: cli, source: 'command line' };
+        if (localValue)
+            return { spec: localValue, source: '.sandbox-config.json' };
+        for (const name of files) {
+            const value = name === VOLTA_PIN ? voltaNode(workspace) : firstLine(path.join(workspace, name));
+            if (value)
+                return { spec: value, source: name };
+        }
+        return { spec: configured, source: 'config' };
+    };
+    let node = pick(req.nodeVersion, localTools.node?.version, ['.nvmrc', '.node-version', VOLTA_PIN], config.toolchains.node.version);
+    if (node.spec === 'host')
+        node = { spec: hostNodeVersion.replace(/^v/, ''), source: 'this PC' };
+    const python = pick(req.pythonVersion, localTools.python?.version, ['.python-version'], config.toolchains.python.version);
+    return { node, nodeExtra: config.toolchains.node.extraVersions, python };
+};
+/** Precedence (lowest to highest): built-in defaults, user config, .sandbox-config.json in the workspace, command-line flags. */
+export const resolveRun = async (req, hostNodeVersion = process.version) => {
+    const notes = [];
+    // Mappings from the user config are relative to that config file; expand them before anything else uses them.
+    const expand = (list) => list.map((p) => expandPath(p, req.loaded.base));
+    const projects = req.loaded.config.projects;
+    let config = {
+        ...req.loaded.config,
+        mappings: req.loaded.config.mappings.map((m) => ({ ...m, host: expandPath(m.host, req.loaded.base) })),
+        projects: { ...projects, roots: expand(projects.roots), exclude: expand(projects.exclude), declinedRoots: expand(projects.declinedRoots) },
+    };
+    const mirror = config.guestWorkspace === 'mirror';
+    const storageRoot = expandPath(config.storage.root, req.loaded.base);
+    const workspaceHost = path.resolve(req.workspace ?? req.cwd);
+    if (!dirExists(workspaceHost))
+        fail('The workspace folder does not exist: ' + workspaceHost, 'Check the --workspace path, or cd into the project first.');
+    assertSafeWorkspace(workspaceHost, req.packageRoot, storageRoot);
+    const scripts = [];
+    let localConfigPath = null;
+    let overrides = {};
+    const local = req.noLocalConfig ? null : readLocalConfig(workspaceHost);
+    if (local) {
+        overrides = normalizeOverrides(local.data, workspaceHost, local.path);
+        const store = trustStorePath(storageRoot);
+        if (!isTrusted(store, local.path, local.hash)) {
+            const summary = describeOverrides(overrides);
+            let trusted = req.trustConfig;
+            if (!trusted && req.ask) {
+                console.log('\nFound ' + local.path + ' which is not trusted yet. It would apply:');
+                for (const line of summary)
+                    console.log('  ' + line);
+                trusted = await req.ask('Trust and use this file?');
+            }
+            if (!trusted)
+                fail(local.path + ' has not been approved yet (a repo can ship this file, so it needs your OK). It would apply:\n  ' + (summary.join('\n  ') || '(no changes)'), 'Review it, then run again in an interactive terminal and answer y, or add --trust-config. To ignore the file: --no-local-config');
+            saveTrust(store, local.path, local.hash);
+            notes.push('Trusted ' + local.path + ' (you will only be asked again if the file changes).');
+        }
+        config = applyOverrides(config, overrides);
+        scripts.push(...(overrides.scripts ?? []));
+        localConfigPath = local.path;
+        notes.push('Using ' + local.path);
+    }
+    if (req.headless !== undefined)
+        config = { ...config, sandbox: { ...config.sandbox, headless: req.headless } };
+    for (const name of req.databases ?? []) {
+        const db = name.toLowerCase();
+        if (!DATABASES.includes(db))
+            fail('Unknown database "' + name + '".', 'Choose from: ' + DATABASES.join(', '));
+        config = { ...config, databases: { ...config.databases, [db]: { ...config.databases[db], enabled: true } } };
+    }
+    if (config.guestWorkspace === 'auto')
+        config = { ...config, guestWorkspace: autoGuestWorkspace(workspaceHost) };
+    else if (config.guestWorkspace === 'mirror') {
+        const plan = planMirrorWorkspace(workspaceHost, autoGuestWorkspace(workspaceHost));
+        if (plan.note)
+            notes.push(plan.note);
+        config = { ...config, guestWorkspace: plan.guest };
+    }
+    scripts.push(...req.scripts.map((s) => path.resolve(s)));
+    const harnessName = req.noAgent ? 'none' : (req.harness ?? config.defaultHarness);
+    if (harnessName !== 'none' && !config.harnesses[harnessName])
+        fail('Unknown agent "' + harnessName + '".', 'Configured agents: ' + Object.keys(config.harnesses).join(', ') + ' (add more under "harnesses" in your config).');
+    const versions = resolveVersions(config, workspaceHost, overrides, req, hostNodeVersion);
+    const dataPath = path.join(storageRoot, 'data', config.storage.dataName);
+    // A project file may ask for "mirror" too (it decides only its own path); project roots follow the user's choice.
+    return { config, storageRoot, dataPath, workspaceHost, harnessName, scripts, localConfigPath, notes, versions, mirror };
+};

package/dist/guest/boot-env.d.ts

@@ -0,0 +1,4 @@
+import { type BootEnvT } from './project-env.js';
+export { baseEnvFor, type BootEnvT } from './project-env.js';
+export declare const saveBootEnv: (value: BootEnvT) => void;
+export declare const readBootEnv: () => BootEnvT | null;

package/dist/guest/boot-env.js

@@ -0,0 +1,25 @@
+// What the boot's provisioning left for projects that join later: the PATH before any toolchain was added, which
+// variables the toolchains set, and what each step contributed. Kept on the sandbox's own disk (lost on close, as it
+// should be). The session daemon builds every later project's environment from it instead of from the boot
+// project's, so project A's Node, Rust target folder or database variables never leak into project B's sessions.
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeJsonAtomic } from '../shared/rundir.js';
+import { localDir } from './env.js';
+import { BootEnv } from './project-env.js';
+export { baseEnvFor } from './project-env.js';
+const file = () => path.join(localDir, 'boot-env.json');
+export const saveBootEnv = (value) => {
+    try {
+        writeJsonAtomic(file(), value);
+    }
+    catch { /* projects added later then fall back to the boot environment */ }
+};
+export const readBootEnv = () => {
+    try {
+        return BootEnv.safeParse(JSON.parse(fs.readFileSync(file(), 'utf8'))).data ?? null;
+    }
+    catch {
+        return null;
+    }
+};

package/dist/guest/cmdline.d.ts

@@ -0,0 +1,12 @@
+export declare const quoteArg: (arg: string) => string;
+/**
+ * Arguments on a `cmd /d /c <agent>.cmd ...` line (npm agents). cmd parses them twice: the /c line, then the .cmd's %*.
+ * & | < > ^ are literal inside quotes, so arguments with them are quoted (https://x?a=1&b=2 survives). % expands even
+ * inside quotes, so each one sits between quoted pieces ("50"%" off"): every %name% cmd could see then starts with a
+ * quote, and no variable is called that. cmd's quote state runs across the whole line (an embedded \" toggles it too),
+ * so a metacharacter it would see outside quotes gets ^^^ (one caret left after each parse). Arguments without any
+ * of these are quoted as usual.
+ */
+export declare const cmdArgs: (args: string[]) => string;
+/** The command line ptyhost starts; when the program is cmd.exe its arguments are quoted for cmd (cmdArgs). */
+export declare const commandLine: (file: string, args: string[]) => string;

package/dist/guest/cmdline.js

@@ -0,0 +1,23 @@
+// Command lines for the agent: Windows argument quoting, and the extra layer cmd.exe needs for npm agents (.cmd files).
+import path from 'node:path';
+const quoted = (arg) => '"' + arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1') + '"';
+export const quoteArg = (arg) => (arg !== '' && !/[\s"]/.test(arg) ? arg : quoted(arg));
+/**
+ * Arguments on a `cmd /d /c <agent>.cmd ...` line (npm agents). cmd parses them twice: the /c line, then the .cmd's %*.
+ * & | < > ^ are literal inside quotes, so arguments with them are quoted (https://x?a=1&b=2 survives). % expands even
+ * inside quotes, so each one sits between quoted pieces ("50"%" off"): every %name% cmd could see then starts with a
+ * quote, and no variable is called that. cmd's quote state runs across the whole line (an embedded \" toggles it too),
+ * so a metacharacter it would see outside quotes gets ^^^ (one caret left after each parse). Arguments without any
+ * of these are quoted as usual.
+ */
+export const cmdArgs = (args) => {
+    const pieces = args.map((arg) => (/[&|<>^%]/.test(arg) ? arg.split('%').map(quoted).join('%') : quoteArg(arg))).join(' ');
+    let inQuotes = false;
+    return [...pieces].map((c) => {
+        if (c === '"')
+            inQuotes = !inQuotes;
+        return !inQuotes && /[&|<>^]/.test(c) ? '^^^' + c : c;
+    }).join('');
+};
+/** The command line ptyhost starts; when the program is cmd.exe its arguments are quoted for cmd (cmdArgs). */
+export const commandLine = (file, args) => path.win32.basename(file).toLowerCase() === 'cmd.exe' ? [quoteArg(file), cmdArgs(args)].filter(Boolean).join(' ') : [file, ...args].map(quoteArg).join(' ');

package/dist/guest/daemon/exec.d.ts

@@ -0,0 +1,5 @@
+import type { GuestRequest } from '../../core/types.js';
+/** Runs a command for the host without blocking the daemon (other requests and pings keep being answered). */
+export declare const execCommand: (req: Extract<GuestRequest, {
+    kind: "exec";
+}>) => void;