windows-development-sandbox 1.0.5 → 1.1.0

package/dist/host/launch/wsb.js

@@ -0,0 +1,34 @@
+// The .wsb file Windows Sandbox starts from: memory, devices and the folders mapped in.
+import os from 'node:os';
+import { fail, xmlEscape } from '../../core/util.js';
+import { MIRROR_ROOT, sandboxFolder } from '../../shared/guest-paths.js';
+export const GUEST = { launch: 'C:\\AgentLaunch', data: 'C:\\AgentData', hostTools: 'C:\\HostTools', mirror: MIRROR_ROOT };
+const toggle = (value) => (value ? 'Enable' : 'Disable');
+/** "auto": free RAM minus the reserve, but never more than maxMemoryMb or maxMemoryPercent of the PC's total RAM. */
+export const resolveMemoryMb = (sandbox, freeMemoryBytes = os.freemem(), totalMemoryBytes = os.totalmem()) => {
+    if (sandbox.memoryMb !== 'auto')
+        return sandbox.memoryMb;
+    const freeMb = Math.floor(freeMemoryBytes / 1048576);
+    const shareMb = Math.floor((totalMemoryBytes / 1048576) * sandbox.maxMemoryPercent / 100);
+    const rounded = Math.floor(Math.min(sandbox.maxMemoryMb, shareMb, freeMb - sandbox.reserveHostMb) / 1024) * 1024;
+    if (rounded < 4096)
+        fail('Not enough free RAM for the sandbox (' + freeMb + ' MB free, ' + sandbox.reserveHostMb + ' MB kept for this PC).', 'Close some apps, lower sandbox.reserveHostMb, or set sandbox.memoryMb to a fixed value (>= 4096).');
+    return rounded;
+};
+export const buildWsb = (config, memoryMb, mappings) => {
+    const s = config.sandbox;
+    // Guest paths on other drive letters (F:\x) really live under C:\Mirror\F; bootstrap.ps1 substs F: onto it at boot.
+    const folders = mappings.map((m) => '<MappedFolder><HostFolder>' + xmlEscape(m.host) + '</HostFolder><SandboxFolder>' + xmlEscape(sandboxFolder(m.guest)) + '</SandboxFolder><ReadOnly>' + String(m.readOnly) + '</ReadOnly></MappedFolder>').join('');
+    return '<Configuration>'
+        + '<MemoryInMB>' + memoryMb + '</MemoryInMB>'
+        + '<vGPU>' + toggle(s.vGpu) + '</vGPU>'
+        + '<Networking>' + toggle(s.networking) + '</Networking>'
+        + '<ClipboardRedirection>' + toggle(s.clipboard) + '</ClipboardRedirection>'
+        + '<AudioInput>' + toggle(s.audioInput) + '</AudioInput>'
+        + '<VideoInput>' + toggle(s.videoInput) + '</VideoInput>'
+        + '<PrinterRedirection>' + toggle(s.printerRedirection) + '</PrinterRedirection>'
+        + '<ProtectedClient>' + toggle(s.protectedClient) + '</ProtectedClient>'
+        + '<MappedFolders>' + folders + '</MappedFolders>'
+        + '<LogonCommand><Command>' + xmlEscape(GUEST.launch + '\\sandbox\\logon.cmd') + '</Command></LogonCommand>'
+        + '</Configuration>';
+};

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

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

package/dist/host/pc-scan.js

@@ -0,0 +1,37 @@
+// What this PC has installed (languages on PATH, MSVC for Rust, database services), so `auto` settings can follow it.
+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';
+/** This PC builds Rust with MSVC: rustup's default host is *-msvc (read from rustup's settings; nothing is run). */
+const 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));
+    }
+    catch {
+        return false;
+    }
+};
+/** Languages this PC has (their commands on PATH; Windows' Store stubs for python do not count). */
+export const 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'),
+    };
+    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 = () => {
+    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/platform.d.ts

@@ -10,6 +10,8 @@ export declare const GUEST_DATA_DIR = "C:\\AgentData";
 export declare const isSandboxRunning: () => boolean;
 export declare const sandboxFeatureInstalled: () => boolean;
 export declare const assertCanLaunch: () => void;
+/** cmd.exe expands %VAR% and ^ even inside quotes, and a quote ends them: such a path could run something else. */
+export declare const assertCmdSafePath: (file: string) => void;
 export declare const startSandbox: (wsbPath: string) => void;
 /** Runs a detached copy of this CLI (used for the background history/claude-mem sync watcher). */
 export declare const spawnDetached: (entry: string, args: string[]) => void;

package/dist/host/platform.js

@@ -3,6 +3,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { SYSTEM } from '../shared/system.js';
+import { refuseInSelfTest } from './test-guard.js';
+import { commandsDir, realAgent } from './agent-commands.js';
 import { dirExists, ensureDir, fail, fileExists, findOnPath, homeDir, isWin, realPath } from '../core/util.js';
 const findHarnessExe = (config, harnessName) => {
     const harness = config.harnesses[harnessName];
@@ -70,18 +72,28 @@ export const assertCanLaunch = () => {
     if (isSandboxRunning())
         fail('A Windows Sandbox is already running (Windows allows one at a time).', 'Attach to it with sandbox claude -t, show it with sbx-show, or shut it down with sandbox stop.');
 };
+/** cmd.exe expands %VAR% and ^ even inside quotes, and a quote ends them: such a path could run something else. */
+export const assertCmdSafePath = (file) => {
+    if (/[%"^\r\n]/.test(file))
+        fail('The storage folder path has a character that cannot be started safely: ' + file, 'Set storage.root to a folder without % " ^ in its path.');
+};
 export const startSandbox = (wsbPath) => {
+    refuseInSelfTest('start Windows Sandbox');
+    assertCmdSafePath(wsbPath);
     const result = spawnSync(SYSTEM.cmd(), ['/d', '/c', 'start', '""', '"' + wsbPath + '"'], { stdio: 'inherit', windowsVerbatimArguments: true });
     if (result.error)
         throw result.error;
 };
 /** Runs a detached copy of this CLI (used for the background history/claude-mem sync watcher). */
 export const spawnDetached = (entry, args) => {
+    refuseInSelfTest('start background programs');
     // cwd = the install folder: the caller's folder is the workspace, which the sandbox can write.
     spawn(process.execPath, [entry, ...args], { cwd: path.dirname(entry), detached: true, stdio: 'ignore', windowsHide: true }).unref();
 };
 export const hostClaude = (storageRoot, personal, args) => {
-    const exe = findOnPath(['claude.exe', 'claude.cmd']);
+    refuseInSelfTest('run Claude Code on this PC');
+    // Never this tool's own forwarding command (agentCommands), which would start a sandbox instead.
+    const exe = realAgent('claude', commandsDir(storageRoot));
     if (!exe)
         fail('Claude Code is not installed on this PC (no claude.exe or claude.cmd on PATH).', 'Install it: npm install -g @anthropic-ai/claude-code');
     const env = { ...process.env };

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

@@ -1,23 +1,7 @@
-import type { Config, DatabasePlan } from '../core/types.js';
-import { type Database, type ProjectFile } from '../core/detect-databases.js';
-import { type AutoToolchain } from '../core/detect-toolchains.js';
+import { type ProjectFile } from '../core/detect-databases.js';
 /** Manifest-type files in the project, up to 3 folders deep. Links are not followed (the workspace may be guest-written). */
 export declare const 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 const 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 const msvcHint: (root: string) => string | undefined;
-/** Languages this PC has (their commands on PATH; Windows' Store stubs for python do not count). */
-export declare const pcLanguages: () => AutoToolchain[];
-/** Database services installed on this PC (names from the service control manager; nothing is started or changed). */
-export declare const hostDatabases: () => Database[];
-/**
- * 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 declare const planDatabases: (config: Config["databases"], workspace: string, probe?: {
-    files?: ProjectFile[];
-    host?: Database[];
-}) => DatabasePlan[];
-/** Every database the sandbox can run, so `sbx-db start <name>` works for ones that did not start at boot. */
-export declare const databaseCatalog: (config: Config["databases"]) => DatabasePlan[];

package/dist/host/project-scan.js

@@ -1,14 +1,7 @@
-// Reads a project the way detect-databases.ts needs it (only manifest/config/compose files, bounded), and looks at which
-// database services this PC has, so `enabled: "auto"` databases are installed only for projects that use them.
+// Reads a project the way detect-databases.ts and detect-toolchains.ts need it (only manifest/config files, bounded).
 import fs from 'node:fs';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { DATABASES, databasesFromServices, detectDatabases, INTERESTING_FILE } from '../core/detect-databases.js';
-import os from 'node:os';
-import { AUTO_TOOLCHAINS } from '../core/detect-toolchains.js';
-import { pcHasPwsh } from '../core/detect-pwsh.js';
-import { isWin } from '../core/util.js';
-import { system32 } from '../shared/system.js';
+import { INTERESTING_FILE } from '../core/detect-databases.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;
@@ -76,16 +69,6 @@ export const projectEntries = (root) => {
         .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];
 };
-/** This PC builds Rust with MSVC: rustup's default host is *-msvc (read from rustup's settings; nothing is run). */
-const 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));
-    }
-    catch {
-        return false;
-    }
-};
 /** 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);
@@ -104,70 +87,3 @@ export const msvcHint = (root) => {
     }
     return undefined;
 };
-/** Languages this PC has (their commands on PATH; Windows' Store stubs for python do not count). */
-export const 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'),
-    };
-    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 = () => {
-    if (!isWin)
-        return [];
-    const result = spawnSync(system32('sc.exe'), ['query', 'type=', 'service', 'state=', 'all'], { encoding: 'utf8', windowsHide: true, timeout: 10000 });
-    const names = [...(result.stdout ?? '').matchAll(/^SERVICE_NAME:\s*(.+)$/gm)].map((m) => m[1].trim());
-    return databasesFromServices(names);
-};
-/** The version a compose file pins (postgres:16-alpine -> 16, mongo:7.0 -> 7.0), if any. */
-const 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 = {}) => {
-    const autos = DATABASES.filter((db) => config[db].enabled === 'auto');
-    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) => {
-        const setting = config[database].enabled;
-        const found = detected.find((d) => d.database === database);
-        if (setting === true)
-            return [plan(database, ['enabled in config'])];
-        if (setting === 'auto' && found)
-            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) => {
-    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) => {
-    const versions = {
-        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 };
-    return (database, reasons) => ({
-        database, reasons, version: versions[database], port: ports[database],
-        ...(database === 'dynamodb' && config.dynamodb.admin ? { adminPort: config.dynamodb.adminPort } : {}),
-    });
-};

package/dist/host/projects.d.ts

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+import { PROJECTS_GUEST, type ProjectEntry, type RootMapping } from '../shared/projects.js';
+import { type Wsb } from './wsb.js';
+export { PROJECTS_GUEST };
+export type { ProjectEntry };
+declare const Entry: z.ZodObject<{
+    name: z.ZodString;
+    host: z.ZodString;
+    guest: z.ZodString;
+    primary: z.ZodBoolean;
+    mechanism: z.ZodEnum<{
+        root: "root";
+        launch: "launch";
+        boot: "boot";
+        wsb: "wsb";
+    }>;
+    registeredAt: z.ZodString;
+}, z.core.$strict>;
+declare const Registry: z.ZodObject<{
+    launchId: z.ZodString;
+    protections: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    roots: z.ZodArray<z.ZodObject<{
+        host: z.ZodString;
+        guest: z.ZodString;
+    }, z.core.$strict>>;
+    projects: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        host: z.ZodString;
+        guest: z.ZodString;
+        primary: z.ZodBoolean;
+        mechanism: z.ZodEnum<{
+            root: "root";
+            launch: "launch";
+            boot: "boot";
+            wsb: "wsb";
+        }>;
+        registeredAt: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type RegistryEntry = z.output<typeof Entry>;
+export type ProjectRegistry = z.output<typeof Registry>;
+export declare const readRegistry: (storageRoot: string) => ProjectRegistry | null;
+/** At launch: the launch folder, the projects mapped with it, and the roots. */
+export declare const startRegistry: (storageRoot: string, o: {
+    launchId: string;
+    protections: ProjectRegistry["protections"];
+    primary: RootMapping;
+    roots: RootMapping[];
+    boot: RootMapping[];
+}) => RegistryEntry;
+/** Why a folder cannot join the running sandbox without a restart (the caller offers one). */
+export declare class NeedsRestart extends Error {
+    readonly hostDir: string;
+    readonly reason: string;
+    constructor(hostDir: string, reason: string);
+}
+export interface ProjectMapper {
+    /** The projects of the running sandbox (the launch folder first). */
+    list(): RegistryEntry[];
+    /** Makes a folder of this PC a project of the running sandbox; throws NeedsRestart when that needs a restart. */
+    register(hostDir: string): RegistryEntry;
+    /** Forgets a project (never the launch folder). Its folder stays visible until the next start if it is mapped. */
+    unregister(name: string): void;
+}
+export interface MapperOptions {
+    storageRoot: string;
+    packageRoot: string;
+    wsbShare: boolean;
+    detect?: () => Wsb | null;
+}
+/** Roots first (instant), then `wsb share` where the Windows Sandbox CLI exists, else NeedsRestart. */
+export declare const projectMapper: (o: MapperOptions) => ProjectMapper;
+/** Which project of the running sandbox a folder on this PC is in, and where that folder is inside. */
+export interface ProjectHere {
+    project: RegistryEntry;
+    guestDir: string;
+}
+export declare const projectHere: (storageRoot: string, hostDir: string) => ProjectHere | null;
+/** The running sandbox's root containing this folder, if any. */
+export declare const rootHere: (storageRoot: string, hostDir: string) => RootMapping | null;
+declare const Known: z.ZodObject<{
+    projects: z.ZodArray<z.ZodObject<{
+        host: z.ZodString;
+        lastUsed: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type KnownProject = z.output<typeof Known>['projects'][number];
+export declare const readKnown: (storageRoot: string) => KnownProject[];
+export declare const rememberProject: (storageRoot: string, hostDir: string) => void;
+export declare const forgetProject: (storageRoot: string, hostDir: string) => boolean;
+/**
+ * projects.all: the known projects mapped at boot on their own (existing folders, not excluded, not the launch folder,
+ * not inside it or a root, which already show them). Pure apart from checking that the folders exist.
+ */
+export declare const allProjectsToMap: (known: string[], o: {
+    primary: string;
+    roots: string[];
+    exclude: string[];
+    exists?: (p: string) => boolean;
+}) => string[];

package/dist/host/projects.js

@@ -0,0 +1,147 @@
+// The projects of the running sandbox, and how another folder joins it (shared/projects.ts explains the ways in).
+// Two host-only files under the storage folder, never in the data folder the sandbox can write:
+//  - run\projects.json: the running sandbox's projects, roots and machine-wide protections (written at launch, then
+//    as folders join);
+//  - known-projects.json: every folder this tool has started a project in (for projects.all and `sandbox projects`).
+// Everything about HOW a folder becomes visible is behind ProjectMapper, so the mechanisms can change independently.
+import path from 'node:path';
+import { z } from 'zod';
+import { assertSafeWorkspace } from '../core/safe-paths.js';
+import { dirExists, fail } from '../core/util.js';
+import { Id } from '../shared/schema.js';
+import { readValid, writeJsonAtomic } from '../shared/rundir.js';
+import { guestDirFor, hubName, isWithin, PROJECTS_GUEST, projectForHostDir } from '../shared/projects.js';
+import { detectWsb, runningSandboxId, shareFolder } from './wsb.js';
+export { PROJECTS_GUEST };
+const AbsolutePath = z.string().max(1024).refine((p) => path.isAbsolute(p), 'must be an absolute path');
+const Entry = z.strictObject({
+    name: Id, host: AbsolutePath, guest: z.string().max(1024), primary: z.boolean(),
+    mechanism: z.enum(['launch', 'root', 'boot', 'wsb']), registeredAt: z.string().max(64),
+});
+const Registry = z.strictObject({
+    launchId: z.string().max(64),
+    /** The running sandbox's protections (core/project-policy.ts), fixed at boot. */
+    protections: z.record(z.string(), z.union([z.boolean(), z.string()])),
+    roots: z.array(z.strictObject({ host: AbsolutePath, guest: z.string().max(1024) })).max(64),
+    projects: z.array(Entry).max(1024),
+});
+const registryFile = (storageRoot) => path.join(storageRoot, 'run', 'projects.json');
+export const readRegistry = (storageRoot) => readValid(Registry, registryFile(storageRoot));
+const saveRegistry = (storageRoot, registry) => writeJsonAtomic(registryFile(storageRoot), registry);
+/** At launch: the launch folder, the projects mapped with it, and the roots. */
+export const startRegistry = (storageRoot, o) => {
+    const at = new Date().toISOString();
+    const primary = { name: hubName(o.primary.host, []), host: o.primary.host, guest: o.primary.guest, primary: true, mechanism: 'launch', registeredAt: at };
+    const names = [primary.name];
+    const boot = o.boot.map((b) => { const name = hubName(b.host, names); names.push(name); return { name, host: b.host, guest: b.guest, primary: false, mechanism: 'boot', registeredAt: at }; });
+    saveRegistry(storageRoot, { launchId: o.launchId, protections: o.protections, roots: o.roots, projects: [primary, ...boot] });
+    return primary;
+};
+/** Why a folder cannot join the running sandbox without a restart (the caller offers one). */
+export class NeedsRestart extends Error {
+    hostDir;
+    reason;
+    constructor(hostDir, reason) {
+        super(reason);
+        this.hostDir = hostDir;
+        this.reason = reason;
+    }
+}
+/** Roots first (instant), then `wsb share` where the Windows Sandbox CLI exists, else NeedsRestart. */
+export const projectMapper = (o) => {
+    const registry = () => readRegistry(o.storageRoot) ?? fail('The running sandbox was started by an older version, so it cannot take another folder.', 'Stop it (sandbox stop) and start it again.');
+    const add = (reg, host, guest, mechanism, name) => {
+        const entry = { name, host, guest, primary: false, mechanism, registeredAt: new Date().toISOString() };
+        // Re-read right before writing: another terminal may have registered something meanwhile.
+        const latest = readRegistry(o.storageRoot) ?? reg;
+        const same = latest.projects.find((p) => p.host.toLowerCase() === host.toLowerCase());
+        if (same)
+            return same;
+        saveRegistry(o.storageRoot, { ...latest, projects: [...latest.projects, entry] });
+        return entry;
+    };
+    return {
+        list: () => readRegistry(o.storageRoot)?.projects ?? [],
+        register: (hostDir) => {
+            const host = path.resolve(hostDir);
+            const reg = registry();
+            const known = reg.projects.find((p) => p.host.toLowerCase() === host.toLowerCase());
+            if (known)
+                return known;
+            assertSafeWorkspace(host, o.packageRoot, o.storageRoot);
+            if (!dirExists(host))
+                fail('The folder does not exist: ' + host);
+            const name = hubName(host, reg.projects.map((p) => p.name));
+            // Inside a root: visible already (also a project created after the sandbox started).
+            const root = projectForHostDir(reg.roots, host);
+            if (root)
+                return add(reg, host, guestDirFor(root, host), 'root', name);
+            if (!o.wsbShare)
+                throw new NeedsRestart(host, 'it is not inside a project root (projects.roots), and adding folders with wsb share is off (projects.wsbShare)');
+            const wsb = (o.detect ?? detectWsb)();
+            if (!wsb?.has('share'))
+                throw new NeedsRestart(host, 'it is not inside a project root (projects.roots), and this Windows has no Windows Sandbox command line (wsb share needs Windows 11 24H2+ with the updated Windows Sandbox)');
+            const sandbox = runningSandboxId(wsb);
+            if (!sandbox.id)
+                throw new NeedsRestart(host, 'wsb share could not find the running sandbox: ' + sandbox.error);
+            const guest = path.win32.join(PROJECTS_GUEST, name);
+            const shared = shareFolder(wsb, sandbox.id, host, guest);
+            if (!shared.ok)
+                throw new NeedsRestart(host, 'wsb share failed (untested on this Windows): ' + shared.error);
+            return add(reg, host, guest, 'wsb', name);
+        },
+        unregister: (name) => {
+            const reg = registry();
+            const entry = reg.projects.find((p) => p.name.toLowerCase() === name.toLowerCase());
+            if (!entry)
+                fail('No project "' + name + '" in the running sandbox.', 'sandbox projects lists them.');
+            if (entry.primary)
+                fail(entry.host + ' is the folder the sandbox started from; it stays until the sandbox stops.');
+            saveRegistry(o.storageRoot, { ...reg, projects: reg.projects.filter((p) => p !== entry) });
+        },
+    };
+};
+export const projectHere = (storageRoot, hostDir) => {
+    const project = projectForHostDir(readRegistry(storageRoot)?.projects ?? [], hostDir);
+    return project ? { project, guestDir: guestDirFor(project, hostDir) } : null;
+};
+/** The running sandbox's root containing this folder, if any. */
+export const rootHere = (storageRoot, hostDir) => projectForHostDir(readRegistry(storageRoot)?.roots ?? [], hostDir);
+// ---- known projects (every folder a project was started in) ------------------------------------------------------
+const Known = z.strictObject({ projects: z.array(z.strictObject({ host: AbsolutePath, lastUsed: z.string().max(64) })).max(2000) });
+const knownFile = (storageRoot) => path.join(storageRoot, 'known-projects.json');
+export const readKnown = (storageRoot) => readValid(Known, knownFile(storageRoot))?.projects ?? [];
+export const rememberProject = (storageRoot, hostDir) => {
+    const host = path.resolve(hostDir);
+    const rest = readKnown(storageRoot).filter((p) => p.host.toLowerCase() !== host.toLowerCase());
+    try {
+        writeJsonAtomic(knownFile(storageRoot), { projects: [{ host, lastUsed: new Date().toISOString() }, ...rest].slice(0, 2000) });
+    }
+    catch { /* a convenience list */ }
+};
+export const forgetProject = (storageRoot, hostDir) => {
+    const host = path.resolve(hostDir);
+    const all = readKnown(storageRoot);
+    const rest = all.filter((p) => p.host.toLowerCase() !== host.toLowerCase());
+    if (rest.length !== all.length)
+        writeJsonAtomic(knownFile(storageRoot), { projects: rest });
+    return rest.length !== all.length;
+};
+/**
+ * projects.all: the known projects mapped at boot on their own (existing folders, not excluded, not the launch folder,
+ * not inside it or a root, which already show them). Pure apart from checking that the folders exist.
+ */
+export const allProjectsToMap = (known, o) => {
+    const exists = o.exists ?? dirExists;
+    const out = [];
+    for (const host of known.map((k) => path.resolve(k))) {
+        if (o.exclude.some((e) => isWithin(path.resolve(e), host)))
+            continue;
+        if (isWithin(o.primary, host) || o.roots.some((r) => isWithin(r, host)))
+            continue;
+        if (out.some((x) => isWithin(x, host) || isWithin(host, x)) || !exists(host))
+            continue;
+        out.push(host);
+    }
+    return out;
+};

package/dist/host/repo-guard.d.ts

@@ -15,8 +15,21 @@ export declare const snapshotRepo: (workspace: string) => RepoSnapshot;
  * Returns what was found (and fixed). Never touches what was already there before the sandbox ran.
  */
 export declare const guardRepo: (workspace: string, before: RepoSnapshot) => RepoFinding[];
-export declare const saveRepoSnapshot: (dataPath: string, workspace: string) => void;
-/** Re-checks the workspace of the current/last launch; findings are kept in a host-only file for `status`. */
+/**
+ * At launch: every folder the sandbox will be able to write. The launch folder, projects mapped with it and every
+ * project already inside a project root are snapshotted as they are now, before the sandbox can touch them.
+ */
+export declare const saveRepoSnapshot: (dataPath: string, workspace: string, more?: string[], roots?: string[]) => void;
+/**
+ * A project that joins the running sandbox: snapshotted before its first session, then guarded like the launch
+ * folder. A project already guarded keeps its first snapshot (what was there before the sandbox could touch it).
+ */
+export declare const addRepoSnapshot: (dataPath: string, workspace: string, o?: {
+    empty?: boolean;
+}) => void;
+/** The folders being guarded (for status). */
+export declare const guardedProjects: (dataPath: string) => string[];
+/** Re-checks every project of the current/last launch; findings are kept in a host-only file for `status`. Returns the new ones. */
 export declare const checkRepo: (dataPath: string) => RepoFinding[];
 export declare const repoFindings: (dataPath: string) => (RepoFinding & {
     at?: string;