windows-development-sandbox 1.4.0 → 1.4.3

package/dist/host/{database-plan.js → launch/database-plan.js}

@@ -1,22 +1,22 @@
-import { DATABASES, detectDatabases } from '../core/detect-databases.js';
+import { DATABASES, detectDatabases } from '../../core/detect/index.js';
 import { hostDatabases } from './pc-scan.js';
 import { readProjectFiles } from './project-scan.js';
 /** The version a compose file pins (postgres:16-alpine -> 16, mongo:7.0 -> 7.0), if any. */
-const pinnedVersion = (files, image) => {
+function pinnedVersion(files, image) {
     for (const file of files) {
         const match = image.exec(file.text);
         if (match?.[1] && /^\d+(\.\d+)?/.test(match[1]))
             return /^\d+(\.\d+)?/.exec(match[1])[0];
     }
     return null;
-};
+}
 /**
  * What to run in this sandbox: databases set to true, plus "auto" ones the project needs. SQL Server is reported (so
  * the user hears about it) but cannot run inside Windows Sandbox.
  */
-export const planDatabases = (config, workspace, probe = {}) => {
+export function planDatabases(config, workspace, probe = {}) {
     const autos = DATABASES.filter((db) => config[db].enabled === 'auto');
-    const files = autos.length ? probe.files ?? readProjectFiles(workspace) : [];
+    const files = autos.length ? (probe.files ?? readProjectFiles(workspace)) : [];
     const detected = autos.length ? detectDatabases(files, probe.host ?? hostDatabases) : [];
     const plan = databasePlanner(config, files.filter((f) => /compose/i.test(f.path)));
     return DATABASES.flatMap((database) => {
@@ -28,25 +28,36 @@ export const planDatabases = (config, workspace, probe = {}) => {
             return [plan(database, found.reasons)];
         return [];
     });
-};
+}
 /** Every database the sandbox can run, so `sbx-db start <name>` works for ones that did not start at boot. */
-export const databaseCatalog = (config) => {
+export function databaseCatalog(config) {
     const plan = databasePlanner(config, []);
     return DATABASES.filter((db) => db !== 'sqlserver').map((db) => plan(db, ['started with sbx-db']));
-};
+}
 /** Version (a compose file's image tag wins), port and admin UI for one database. */
-const databasePlanner = (config, compose) => {
+function databasePlanner(config, compose) {
     const versions = {
-        postgres: pinnedVersion(compose, /image:\s*["']?(?:[\w.-]+\/)*postgres:([\w.-]+)/i) ?? (config.postgres.version === 'latest' ? 'latest' : config.postgres.version),
+        postgres: pinnedVersion(compose, /image:\s*["']?(?:[\w.-]+\/)*postgres:([\w.-]+)/i) ??
+            (config.postgres.version === 'latest' ? 'latest' : config.postgres.version),
         mysql: config.mysql.version,
         mongodb: pinnedVersion(compose, /image:\s*["']?(?:[\w.-]+\/)*mongo:([\w.-]+)/i) ?? config.mongodb.version,
         redis: 'latest',
         dynamodb: 'latest',
         sqlserver: '',
     };
-    const ports = { postgres: config.postgres.port, mysql: config.mysql.port, mongodb: config.mongodb.port, redis: config.redis.port, dynamodb: config.dynamodb.port, sqlserver: 1433 };
+    const ports = {
+        postgres: config.postgres.port,
+        mysql: config.mysql.port,
+        mongodb: config.mongodb.port,
+        redis: config.redis.port,
+        dynamodb: config.dynamodb.port,
+        sqlserver: 1433,
+    };
     return (database, reasons) => ({
-        database, reasons, version: versions[database], port: ports[database],
+        database,
+        reasons,
+        version: versions[database],
+        port: ports[database],
         ...(database === 'dynamodb' && config.dynamodb.admin ? { adminPort: config.dynamodb.adminPort } : {}),
     });
-};
+}

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

@@ -0,0 +1,4 @@
+import type { GenerateOptions, Generated } from '../../core/types.js';
+export declare function generateSandbox(given: GenerateOptions): Generated & {
+    personalization: string;
+};

package/dist/host/launch/generate.js

@@ -0,0 +1,77 @@
+// Writes a launch folder for one sandbox: session.json (what the guest needs to know), the bundled runtime, hooks, the
+// staged Claude settings and the .wsb file that starts Windows Sandbox. The pieces live in the sibling files.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { widenForProjects } from '../../core/local-config/index.js';
+import { dirExists, ensureDir, fail, writeJson } from '../../core/util/index.js';
+import { capturePersonalization, stageClaudeProfile } from '../profile/index.js';
+import { assertTestWritable } from '../test-guard.js';
+import { planBootProjects } from './boot-projects.js';
+import { planDatabases } from './database-plan.js';
+import { collectMappings } from './mappings.js';
+import { guestSession, logonEnv } from './session-file.js';
+import { copyRuntime, stageGitIdentity, stageHooks } from './stage.js';
+import { decideProjectToolchains } from './toolchains.js';
+import { buildWsb, resolveMemoryMb } from './wsb-file.js';
+const NO_PROFILE = { hostDir: null, staged: [], skipped: [], credentials: false, secretsRemoved: [] };
+export function generateSandbox(given) {
+    // Several projects at boot: the sandbox also gets what the others want and you allowed (core/local-config).
+    const others = given.bootWants?.projects ?? [];
+    const boot = planBootProjects({
+        run: given.run,
+        packageRoot: given.packageRoot,
+        extraProjects: given.extraProjects,
+        knownProjects: given.knownProjects,
+    });
+    const wide = widenForProjects(given.run.config, others, { keepOff: given.bootWants?.keepOff, exists: dirExists });
+    const o = { ...given, run: { ...given.run, config: wide.config } };
+    const { config, dataPath, workspaceHost, harnessName, storageRoot } = o.run;
+    const harness = harnessName === 'none'
+        ? null
+        : (config.harnesses[harnessName] ??
+            fail('Unknown agent: ' + harnessName, 'Configured agents: ' + Object.keys(config.harnesses).join(', ')));
+    if (!dirExists(workspaceHost))
+        fail('The workspace folder does not exist: ' + workspaceHost, 'cd into the project first.');
+    assertTestWritable(storageRoot);
+    assertTestWritable(dataPath);
+    // Checked before anything is written, so a refusal leaves nothing behind.
+    const memoryMb = Math.max(resolveMemoryMb(config.sandbox, o.freeMemoryBytes), ...others.map((p) => (typeof p.config.sandbox.memoryMb === 'number' ? p.config.sandbox.memoryMb : 0)));
+    const launchId = Date.now() + '-' + crypto.randomBytes(3).toString('hex');
+    const launchPath = path.join(storageRoot, 'launches', launchId);
+    ensureDir(launchPath);
+    ensureDir(dataPath);
+    const mappingNotes = [];
+    const mappings = collectMappings(o, launchPath, boot, mappingNotes);
+    const profile = harnessName === 'claude'
+        ? stageClaudeProfile(config.claudeProfile, launchPath, workspaceHost, config.secrets)
+        : NO_PROFILE;
+    stageGitIdentity(launchPath);
+    const personalization = config.personalization.enabled ? capturePersonalization(launchPath) : 'disabled';
+    const databases = o.databases ?? planDatabases(config.databases, workspaceHost);
+    const toolchains = decideProjectToolchains(o);
+    const session = guestSession(o, { launchId, launchPath, harness, boot, mappings, profile, databases, toolchains });
+    const sessionPath = path.join(launchPath, 'session.json');
+    writeJson(sessionPath, session);
+    fs.writeFileSync(path.join(launchPath, 'env.cmd'), logonEnv(session.workspace), 'utf8');
+    copyRuntime(o.packageRoot, launchPath);
+    stageHooks(o.packageRoot, launchPath, o.run.scripts);
+    const wsbPath = path.join(launchPath, 'agent.wsb');
+    fs.writeFileSync(wsbPath, buildWsb(config, memoryMb, mappings), 'utf8');
+    return {
+        wsbPath,
+        launchPath,
+        launchId,
+        sessionPath,
+        memoryMb,
+        bootConfig: config,
+        widened: wide.widened,
+        mappings,
+        profile,
+        personalization,
+        databases,
+        toolchains,
+        projects: { ...boot, notes: [...boot.notes, ...wide.notes] },
+        mappingNotes,
+    };
+}

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

@@ -0,0 +1,10 @@
+export { generateSandbox } from './generate.js';
+export { decideProjectToolchains } from './toolchains.js';
+export { hostToolsOf, logonEnv } from './session-file.js';
+export { GUEST, buildWsb, resolveMemoryMb } from './wsb-file.js';
+export { MAX_BOOT_PROJECTS, planBootProjects, shownByRoot, type BootProjects } from './boot-projects.js';
+export { databaseCatalog, planDatabases } from './database-plan.js';
+export { msvcHint, projectEntries, readProjectFiles } from './project-scan.js';
+export { hostDatabases, pcLanguages } from './pc-scan.js';
+export { collectMappings } from './mappings.js';
+export { RUNTIME_FILES, copyRuntime, gitIdentity, stageGitIdentity, stageHooks, stageScripts } from './stage.js';

package/dist/host/launch/index.js

@@ -0,0 +1,10 @@
+export { generateSandbox } from './generate.js';
+export { decideProjectToolchains } from './toolchains.js';
+export { hostToolsOf, logonEnv } from './session-file.js';
+export { GUEST, buildWsb, resolveMemoryMb } from './wsb-file.js';
+export { MAX_BOOT_PROJECTS, planBootProjects, shownByRoot } from './boot-projects.js';
+export { databaseCatalog, planDatabases } from './database-plan.js';
+export { msvcHint, projectEntries, readProjectFiles } from './project-scan.js';
+export { hostDatabases, pcLanguages } from './pc-scan.js';
+export { collectMappings } from './mappings.js';
+export { RUNTIME_FILES, copyRuntime, gitIdentity, stageGitIdentity, stageHooks, stageScripts } from './stage.js';

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

@@ -1,3 +1,8 @@
 import type { GenerateOptions, ResolvedMapping } from '../../core/types.js';
-import type { BootProjects } from './projects.js';
-export declare const collectMappings: (o: GenerateOptions, launchPath: string, boot?: BootProjects) => ResolvedMapping[];
+import { type BootProjects } from './boot-projects.js';
+/**
+ * Every mapping, placed. An extra folder appears at its `guest` path, or at the same path as on this PC when it has
+ * none. A folder that cannot appear there (a reserved or relative path, one already in use, a folder that is not
+ * there, a whole drive, this tool's own folders) stops the launch; every such folder is listed in one message.
+ */
+export declare function collectMappings(o: GenerateOptions, launchPath: string, boot?: BootProjects, notes?: string[]): ResolvedMapping[];

package/dist/host/launch/mappings.js

@@ -1,38 +1,97 @@
-import { assertNoGuestOverlap } from '../../core/config.js';
+// Which folders are mapped into the sandbox: the launch folder, the data folder, the workspace, your extra folders and
+// the tools copied from this PC. Everything is checked before it can reach the .wsb.
+import path from 'node:path';
+import { assertNoGuestOverlap } from '../../core/config/index.js';
 import { assertSafeMapping } from '../../core/safe-paths.js';
-import { dirExists, fail } from '../../core/util.js';
-import { isValidGuestPath, sandboxFolder } from '../../shared/guest-paths.js';
-import { GUEST } from './wsb.js';
+import { dirExists, errMsg, fail, isInsideOrEqual, UserError } from '../../core/util/index.js';
+import { shownByRoot } from './boot-projects.js';
+import { deriveGuest, isValidGuestPath, guestConflict, guestFix, PROJECTS_GUEST, sandboxFolder, tidyGuestPath, } from '../../shared/paths/index.js';
+import { GUEST } from './wsb-file.js';
 import { guestGitDir, planView } from '../workspace-view/index.js';
-export const collectMappings = (o, launchPath, boot = { roots: [], projects: [], notes: [] }) => {
+/**
+ * Every mapping, placed. An extra folder appears at its `guest` path, or at the same path as on this PC when it has
+ * none. A folder that cannot appear there (a reserved or relative path, one already in use, a folder that is not
+ * there, a whole drive, this tool's own folders) stops the launch; every such folder is listed in one message.
+ */
+export function collectMappings(o, launchPath, boot = { roots: [], projects: [], notes: [] }, notes = []) {
     const { config, dataPath, workspaceHost, harnessName } = o.run;
     assertGuestPath(config.guestWorkspace, 'guestWorkspace');
     // workspaceFilter: the sandbox gets the project's filtered view (no git-ignored files) and its real .git beside it.
     const view = planView(config, o.run.storageRoot, workspaceHost);
+    // A launch folder inside a project root is shown by the root, at the place it has whichever project starts the sandbox.
+    const inRoot = !view && shownByRoot(boot.roots, workspaceHost, config.guestWorkspace);
     const mappings = [
         { host: launchPath, guest: GUEST.launch, readOnly: true },
         { host: dataPath, guest: GUEST.data, readOnly: false },
-        { host: view ? view.options.view : workspaceHost, guest: config.guestWorkspace, readOnly: config.readOnly },
-        ...(view?.hostGit ? [{ host: view.hostGit, guest: guestGitDir(config.guestWorkspace), readOnly: config.readOnly }] : []),
+        ...(inRoot
+            ? []
+            : [{ host: view ? view.options.view : workspaceHost, guest: config.guestWorkspace, readOnly: config.readOnly }]),
+        ...(view?.hostGit
+            ? [{ host: view.hostGit, guest: guestGitDir(config.guestWorkspace), readOnly: config.readOnly }]
+            : []),
     ];
+    // Project roots and other projects, so they can join the running sandbox without a restart (launch/boot-projects.ts).
+    const projects = [];
+    for (const m of [...boot.roots, ...boot.projects]) {
+        assertGuestPath(m.guest, 'project folder for ' + m.host);
+        projects.push({ host: m.host, guest: m.guest, readOnly: false });
+    }
+    const taken = [
+        { guest: config.guestWorkspace, what: 'the project' },
+        ...(view?.hostGit ? [{ guest: guestGitDir(config.guestWorkspace), what: "the project's .git" }] : []),
+        { guest: PROJECTS_GUEST, what: 'the other projects' },
+        ...projects.map((p) => ({ guest: p.guest, what: p.host })),
+    ];
+    const outside = new Set((o.run.outsideMappings ?? []).map((h) => path.resolve(h).toLowerCase()));
+    const problems = [];
+    const missing = [];
+    const extra = [];
     for (const m of config.mappings) {
         const host = m.host;
-        assertGuestPath(m.guest, 'mappings[].guest for ' + host);
         if (!dirExists(host)) {
-            if (m.optional) {
-                console.warn('Skipping optional mapping (folder not found): ' + host);
-                continue;
-            }
-            fail('A mapped folder does not exist: ' + host, 'Create it, fix the path in your config, or mark the mapping "optional": true.');
+            if (m.optional)
+                missing.push(host);
+            else
+                problems.push(host + ': the folder does not exist. Fix: create it, correct the path, or mark the mapping "optional": true.');
+            continue;
         }
-        assertSafeMapping(host, o.packageRoot, o.run.storageRoot);
-        mappings.push({ host, guest: m.guest, readOnly: m.readOnly });
-    }
-    // Project roots and other projects, so they can join the running sandbox without a restart (launch/projects.ts).
-    for (const m of [...boot.roots, ...boot.projects]) {
-        assertGuestPath(m.guest, 'project folder for ' + m.host);
-        mappings.push({ host: m.host, guest: m.guest, readOnly: false });
+        try {
+            assertSafeMapping(host, o.packageRoot, o.run.storageRoot);
+        }
+        catch (e) {
+            problems.push(errMsg(e) + (e instanceof UserError && e.fix ? ' Fix: ' + e.fix : ''));
+            continue;
+        }
+        // A folder inside the project with no guest path of its own is already there (unless the filtered view hides it).
+        if (!m.guest && !view && isInsideOrEqual(workspaceHost, host)) {
+            notes.push(host +
+                ' is inside the project, so it is already in the sandbox at ' +
+                deriveGuest(host, workspaceHost, config.guestWorkspace) +
+                '.');
+            continue;
+        }
+        const wanted = tidyGuestPath(m.guest ?? deriveGuest(host, workspaceHost, config.guestWorkspace));
+        // The same folder at the same place twice (your settings and the project file): once is enough.
+        if (extra.some((x) => x.host.toLowerCase() === host.toLowerCase() && x.guest.toLowerCase() === wanted.toLowerCase()))
+            continue;
+        const conflict = guestConflict(wanted, [...taken, ...extra.map((x) => ({ guest: x.guest, what: x.host }))]);
+        if (conflict) {
+            problems.push(host + ': ' + conflict + '. Fix: ' + guestFix(m.guest));
+            continue;
+        }
+        const label = outside.has(path.resolve(host).toLowerCase()) ? 'outside the project, allowed' : undefined;
+        extra.push({ host, guest: wanted, readOnly: m.readOnly, ...(label ? { label } : {}) });
     }
+    if (problems.length)
+        fail((problems.length === 1
+            ? 'A mapped folder cannot be used:\n  '
+            : problems.length + ' mapped folders cannot be used:\n  ') + problems.join('\n  '));
+    if (missing.length)
+        notes.push('Skipped ' +
+            (missing.length === 1 ? 'an optional folder' : missing.length + ' optional folders') +
+            ' not on this PC: ' +
+            missing.join(', '));
+    mappings.push(...extra, ...projects);
     const { probe } = o;
     if (probe.nodeDir)
         mappings.push({ host: probe.nodeDir, guest: GUEST.hostTools + '\\node', readOnly: true });
@@ -42,13 +101,13 @@ export const collectMappings = (o, launchPath, boot = { roots: [], projects: [],
         mappings.push({ host: probe.gitDir, guest: GUEST.hostTools + '\\git', readOnly: true });
     if (probe.nvmDir)
         mappings.push({ host: probe.nvmDir, guest: GUEST.hostTools + '\\nvm', readOnly: true });
+    // Placement keeps extra folders apart; this guards the rest (and where the folders really are: F:\x is C:\Mirror\F\x).
     assertNoGuestOverlap(mappings);
-    // Same check on where the folders really are (F:\x and C:\Mirror\F\x are one place).
     assertNoGuestOverlap(mappings.map((m) => ({ guest: sandboxFolder(m.guest) })));
     return mappings;
-};
+}
 /** The schema checks this already; the host re-checks what goes into the .wsb and the subst list anyway. */
-const assertGuestPath = (guest, what) => {
+function assertGuestPath(guest, what) {
     if (!isValidGuestPath(guest))
         fail(what + ' is not a usable sandbox folder: ' + guest, 'Use a folder under C:\\ (not Windows, Program Files, Users, AgentData, Mirror, ...) or on drive D: to Z:, e.g. C:\\Assets or F:\\SteamLibrary\\steamapps\\common\\Game.');
-};
+}

package/dist/host/launch/pc-scan.d.ts

@@ -0,0 +1,5 @@
+import { type AutoToolchain, type Database } from '../../core/detect/index.js';
+/** Languages this PC has (their commands on PATH; Windows' Store stubs for python do not count). */
+export declare function pcLanguages(): AutoToolchain[];
+/** Database services installed on this PC (names from the service control manager; nothing is started or changed). */
+export declare function hostDatabases(): Database[];

package/dist/host/{pc-scan.js → launch/pc-scan.js}

@@ -2,13 +2,11 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { pcHasPwsh } from '../core/detect-pwsh.js';
-import { databasesFromServices } from '../core/detect-databases.js';
-import { AUTO_TOOLCHAINS } from '../core/detect-toolchains.js';
-import { captureOutput, isWin } from '../core/util.js';
-import { system32 } from '../shared/system.js';
+import { AUTO_TOOLCHAINS, databasesFromServices, pcHasPwsh, } from '../../core/detect/index.js';
+import { captureOutput, isWin } from '../../core/util/index.js';
+import { system32 } from '../../shared/system.js';
 /** This PC builds Rust with MSVC: rustup's default host is *-msvc (read from rustup's settings; nothing is run). */
-const msvcRust = () => {
+function msvcRust() {
     const settings = path.join(process.env.RUSTUP_HOME ?? path.join(os.homedir(), '.rustup'), 'settings.toml');
     try {
         return /default_host_triple\s*=\s*"[^"]*-msvc"/.test(fs.readFileSync(settings, 'utf8').slice(0, 64 * 1024));
@@ -16,22 +14,31 @@ const msvcRust = () => {
     catch {
         return false;
     }
-};
+}
 /** Languages this PC has (their commands on PATH; Windows' Store stubs for python do not count). */
-export const pcLanguages = () => {
+export function pcLanguages() {
     const dirs = (process.env.PATH ?? '').split(path.delimiter).filter((d) => d && !/WindowsApps/i.test(d));
     const has = (...names) => dirs.some((d) => names.some((n) => fs.existsSync(path.join(d, n))));
     const found = {
-        python: has('python.exe', 'py.exe'), rust: has('cargo.exe', 'rustc.exe'), cpp: has('gcc.exe', 'g++.exe', 'cl.exe', 'clang.exe'),
-        msvc: msvcRust(), pwsh: pcHasPwsh(), dotnet: has('dotnet.exe'), go: has('go.exe'), java: has('java.exe', 'javac.exe'), ruby: has('ruby.exe'), php: has('php.exe'), deno: has('deno.exe'),
+        python: has('python.exe', 'py.exe'),
+        rust: has('cargo.exe', 'rustc.exe'),
+        cpp: has('gcc.exe', 'g++.exe', 'cl.exe', 'clang.exe'),
+        msvc: msvcRust(),
+        pwsh: pcHasPwsh(),
+        dotnet: has('dotnet.exe'),
+        go: has('go.exe'),
+        java: has('java.exe', 'javac.exe'),
+        ruby: has('ruby.exe'),
+        php: has('php.exe'),
+        deno: has('deno.exe'),
     };
     return AUTO_TOOLCHAINS.filter((t) => found[t]);
-};
+}
 /** Database services installed on this PC (names from the service control manager; nothing is started or changed). */
-export const hostDatabases = () => {
+export function hostDatabases() {
     if (!isWin)
         return [];
     const output = captureOutput(system32('sc.exe'), ['query', 'type=', 'service', 'state=', 'all'], { timeout: 10000 });
     const names = [...output.matchAll(/^SERVICE_NAME:\s*(.+)$/gm)].map((m) => m[1].trim());
     return databasesFromServices(names);
-};
+}

package/dist/host/launch/project-scan.d.ts

@@ -0,0 +1,7 @@
+import { type ProjectFile } from '../../core/detect/index.js';
+/** Manifest-type files in the project, up to 3 folders deep. Links are not followed (the guest may have written it). */
+export declare function readProjectFiles(root: string, depth?: number): ProjectFile[];
+/** File names in the project and its direct sub-folders ("api/go.mod"), for toolchain detection. No links followed. */
+export declare function projectEntries(root: string): string[];
+/** Scripts in the project root or one folder down that set up MSVC (vcvars*.bat, vswhere): read with bounded effort. */
+export declare function msvcHint(root: string): string | undefined;

package/dist/host/{project-scan.js → launch/project-scan.js}

@@ -1,13 +1,13 @@
-// Reads a project the way detect-databases.ts and detect-toolchains.ts need it (only manifest/config files, bounded).
+// Reads a project the way core/detect needs it for databases and toolchains (only manifest/config files, bounded).
 import fs from 'node:fs';
 import path from 'node:path';
-import { INTERESTING_FILE } from '../core/detect-databases.js';
+import { INTERESTING_FILE } from '../../core/detect/index.js';
 const SKIP = /^(node_modules|\.git|\.hg|\.svn|vendor|target|bin|obj|dist|build|out|\.next|\.nuxt|\.venv|venv|env|__pycache__|\.gradle|\.idea|\.vs|coverage|packages)$/i;
 const MAX_FILES = 400;
 const MAX_BYTES = 256 * 1024;
 const MAX_FOLDERS = 2000;
 /** Reads a file through one handle, only if that handle is a regular file of at most MAX_BYTES. */
-const readSmallFile = (file) => {
+function readSmallFile(file) {
     let fd = null;
     try {
         fd = fs.openSync(file, 'r');
@@ -25,9 +25,9 @@ const readSmallFile = (file) => {
         if (fd !== null)
             fs.closeSync(fd);
     }
-};
-/** Manifest-type files in the project, up to 3 folders deep. Links are not followed (the workspace may be guest-written). */
-export const readProjectFiles = (root, depth = 3) => {
+}
+/** Manifest-type files in the project, up to 3 folders deep. Links are not followed (the guest may have written it). */
+export function readProjectFiles(root, depth = 3) {
     const files = [];
     let folders = 0;
     const walk = (dir, level) => {
@@ -55,28 +55,36 @@ export const readProjectFiles = (root, depth = 3) => {
     };
     walk(root, 0);
     return files;
-};
+}
 /** File names in the project and its direct sub-folders ("api/go.mod"), for toolchain detection. No links followed. */
-export const projectEntries = (root) => {
-    const list = (dir) => { try {
-        return fs.readdirSync(dir, { withFileTypes: true }).slice(0, 2000);
-    }
-    catch {
-        return [];
-    } };
+export function projectEntries(root) {
+    const list = (dir) => {
+        try {
+            return fs.readdirSync(dir, { withFileTypes: true }).slice(0, 2000);
+        }
+        catch {
+            return [];
+        }
+    };
     const top = list(root);
-    const below = top.filter((d) => d.isDirectory() && !d.name.startsWith('.') && !SKIP.test(d.name)).slice(0, 200)
-        .flatMap((d) => list(path.join(root, d.name)).filter((f) => f.isFile()).map((f) => d.name + '/' + f.name));
+    const below = top
+        .filter((d) => d.isDirectory() && !d.name.startsWith('.') && !SKIP.test(d.name))
+        .slice(0, 200)
+        .flatMap((d) => list(path.join(root, d.name))
+        .filter((f) => f.isFile())
+        .map((f) => d.name + '/' + f.name));
     return [...top.filter((d) => d.isFile()).map((d) => d.name), ...below];
-};
+}
 /** Scripts in the project root or one folder down that set up MSVC (vcvars*.bat, vswhere): read with bounded effort. */
-export const msvcHint = (root) => {
-    const scripts = projectEntries(root).filter((e) => /\.(ps1|cmd|bat|psm1)$/i.test(e)).slice(0, 60);
+export function msvcHint(root) {
+    const scripts = projectEntries(root)
+        .filter((e) => /\.(ps1|cmd|bat|psm1)$/i.test(e))
+        .slice(0, 60);
     for (const rel of scripts) {
         let text = '';
         try {
             const file = path.join(root, rel);
-            if (fs.statSync(file).size <= 256 * 1024)
+            if (fs.statSync(file).size <= MAX_BYTES)
                 text = fs.readFileSync(file, 'utf8');
         }
         catch {
@@ -86,4 +94,4 @@ export const msvcHint = (root) => {
             return rel + ' sets up MSVC';
     }
     return undefined;
-};
+}

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

@@ -0,0 +1,23 @@
+import type { DatabasePlan, GenerateOptions, Generated, GuestSession, HostProbe, ProfileResult, ResolvedMapping } from '../../core/types.js';
+import type { BootProjects } from './boot-projects.js';
+/** What generateSandbox has decided or staged before it writes session.json. */
+export interface SessionParts {
+    readonly launchId: string;
+    readonly launchPath: string;
+    readonly harness: GuestSession['harness'];
+    readonly boot: BootProjects;
+    readonly mappings: readonly ResolvedMapping[];
+    readonly profile: ProfileResult;
+    readonly databases: DatabasePlan[];
+    readonly toolchains: Generated['toolchains'];
+}
+/** What was found on this PC to copy instead of download. */
+export declare function hostToolsOf(probe: HostProbe): GuestSession['hostTools'];
+/** session.json. The key order is the file's byte order: keep it. */
+export declare function guestSession(o: GenerateOptions, parts: SessionParts): GuestSession;
+/**
+ * env.cmd, which logon.cmd calls before it opens Windows Terminal: Terminal expands "%AGENT_WORKSPACE%" (the starting
+ * folder of new tabs) from its own environment, and the runtime only sets the variable machine-wide after Terminal
+ * started. `%` is doubled for cmd; a Windows path holds no quotes.
+ */
+export declare function logonEnv(workspace: string): string;

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

@@ -0,0 +1,73 @@
+// What the guest reads at boot: session.json (the whole launch, decided on this side) and env.cmd for logon.cmd.
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveToolchains } from '../../core/detect/index.js';
+import { hubName, PROJECTS_GUEST, substDrives } from '../../shared/paths/index.js';
+import { hostClaudeDir } from '../profile/index.js';
+import { databaseCatalog } from './database-plan.js';
+/** What was found on this PC to copy instead of download. */
+export function hostToolsOf(probe) {
+    return {
+        node: Boolean(probe.nodeDir),
+        nodeVersion: probe.nodeDir || probe.nvmNode ? probe.hostNodeVersion.replace(/^v/, '') : null,
+        harnessExecutable: probe.harnessExe?.file ?? null,
+        git: Boolean(probe.gitDir),
+        nvm: Boolean(probe.nvmDir),
+        volta: Boolean(probe.volta),
+        pyenv: Boolean(probe.pyenv),
+    };
+}
+/** session.json. The key order is the file's byte order: keep it. */
+export function guestSession(o, parts) {
+    const { config, workspaceHost, harnessName } = o.run;
+    const { profile } = parts;
+    return {
+        launchId: parts.launchId,
+        project: path.basename(workspaceHost),
+        projectId: hubName(workspaceHost, []),
+        workspace: config.guestWorkspace,
+        workspaceHost,
+        projectsDir: PROJECTS_GUEST,
+        // Every folder mapped for other projects (roots and projects mapped at boot): the guest accepts projects in them.
+        roots: [...parts.boot.roots, ...parts.boot.projects].map((r) => r.guest),
+        ...(o.autoSession === false ? { autoSession: false } : {}),
+        harnessName,
+        harness: parts.harness,
+        harnessArguments: o.harnessArgs,
+        persistAgentState: config.storage.persistAgentState,
+        networking: config.sandbox.networking,
+        headless: config.sandbox.headless,
+        network: config.network,
+        provisioning: config.provisioning,
+        // "auto" is decided here, so the guest and the launch table agree.
+        toolchains: resolveToolchains(config.toolchains, parts.toolchains),
+        databases: parts.databases,
+        databaseCatalog: databaseCatalog(config.databases),
+        versions: o.run.versions,
+        attach: config.attach,
+        hooks: config.hooks,
+        downloads: config.downloads,
+        hostTools: hostToolsOf(o.probe),
+        claudeProfile: {
+            overwrite: config.claudeProfile.overwrite,
+            items: profile.staged,
+            credentials: profile.credentials,
+            hostConfigDir: profile.hostDir ?? hostClaudeDir(config.claudeProfile),
+            syncClaudeMem: config.claudeProfile.syncClaudeMem,
+        },
+        personalization: fs.existsSync(path.join(parts.launchPath, 'personalize', 'personalize.reg')),
+        substDrives: substDrives(parts.mappings.map((m) => m.guest)),
+        cpuLimitPercent: config.sandbox.cpuLimit === 'none' ? null : config.sandbox.cpuLimit,
+        pageFileMb: config.sandbox.pageFileMb,
+        apps: config.apps,
+        auditProcesses: config.audit.enabled && config.audit.processes,
+    };
+}
+/**
+ * env.cmd, which logon.cmd calls before it opens Windows Terminal: Terminal expands "%AGENT_WORKSPACE%" (the starting
+ * folder of new tabs) from its own environment, and the runtime only sets the variable machine-wide after Terminal
+ * started. `%` is doubled for cmd; a Windows path holds no quotes.
+ */
+export function logonEnv(workspace) {
+    return '@set "AGENT_WORKSPACE=' + workspace.replace(/[\r\n"]/g, '').replace(/%/g, '%%') + '"\r\n';
+}

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

@@ -1,11 +1,11 @@
 /** Package hooks first, then ~/.agent-sandbox/hooks (same file name = user's wins), then --script / "scripts". */
-export declare const stageHooks: (packageRoot: string, launchPath: string, scripts: string[]) => void;
+export declare function stageHooks(packageRoot: string, launchPath: string, scripts: readonly string[]): void;
 /** --script / "scripts" files, run before the agent in this order. */
-export declare const stageScripts: (target: string, scripts: string[]) => void;
+export declare function stageScripts(target: string, scripts: readonly string[]): void;
 export declare const RUNTIME_FILES: string[];
 /** The bundled sandbox runtime (dist/runtime: one self-contained file per entry point) and the sandbox/ scripts. */
-export declare const copyRuntime: (packageRoot: string, launchPath: string) => void;
+export declare function copyRuntime(packageRoot: string, launchPath: string): void;
 /** Only the identity from ~/.gitconfig: the rest can hold credentials (helpers, tokens in insteadOf URLs). */
-export declare const gitIdentity: (gitconfig: string) => string;
+export declare function gitIdentity(gitconfig: string): string;
 /** Writes this PC's git name and email to home\.gitconfig in the launch folder (nothing when there are none). */
-export declare const stageGitIdentity: (launchPath: string) => void;
+export declare function stageGitIdentity(launchPath: string): void;