windows-development-sandbox 1.4.0 → 1.4.1

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

@@ -13,3 +13,5 @@ export declare const planBootProjects: (o: {
     extraProjects?: string[];
     knownProjects?: string[];
 }) => BootProjects;
+/** The launch folder is inside a mapped root and placed under it (core/workspace.ts): the root shows it, no own mapping. */
+export declare const shownByRoot: (roots: RootMapping[], workspaceHost: string, guestWorkspace: string) => boolean;

package/dist/host/launch/projects.js

@@ -4,7 +4,7 @@
 import path from 'node:path';
 import { assertSafeMapping, assertSafeWorkspace } from '../../core/safe-paths.js';
 import { dirExists, errMsg, fail } from '../../core/util.js';
-import { isWithin, planProjectMappings } from '../../shared/projects.js';
+import { guestDirFor, isWithin, planProjectMappings, projectForHostDir, usableRoots } from '../../shared/projects.js';
 import { allProjectsToMap, readKnown } from '../projects.js';
 /** More folders than this would make the .wsb (and every boot) unwieldy; the rest join with a restart later. */
 export const MAX_BOOT_PROJECTS = 48;
@@ -21,7 +21,6 @@ export const planBootProjects = (o) => {
             return errMsg(e);
         }
     };
-    const roots = [];
     for (const root of config.projects.roots.map((r) => path.resolve(r))) {
         if (!dirExists(root)) {
             notes.push('Project root not found, skipped: ' + root);
@@ -30,9 +29,9 @@ export const planBootProjects = (o) => {
         const refusal = safe(root);
         if (refusal)
             fail('projects.roots: ' + refusal, 'Use a folder that holds your projects, e.g. F:\\Code (not a drive, your profile or a system folder).');
-        if (!roots.some((r) => isWithin(r, root)))
-            roots.push(root);
     }
+    // The same list resolveRun used to place a launch folder that is inside a root (core/workspace.ts).
+    const roots = usableRoots(config.projects.roots, dirExists);
     const known = o.knownProjects ?? readKnown(storageRoot).map((k) => k.host);
     const wanted = [...(o.extraProjects ?? []), ...(config.projects.all ? allProjectsToMap(known, { primary: workspaceHost, roots, exclude: config.projects.exclude }) : [])];
     const projects = [];
@@ -52,5 +51,12 @@ export const planBootProjects = (o) => {
         }
         projects.push(folder);
     }
-    return { ...planProjectMappings(roots, projects, Boolean(o.run.mirror)), notes };
+    // Projects mapped on their own sit where they would as the launch folder (C:\Workspace\<name>), never on top of it.
+    const taken = [config.guestWorkspace, ...config.mappings.flatMap((m) => (m.guest ? [m.guest] : []))];
+    return { ...planProjectMappings(roots, projects, Boolean(o.run.mirror), taken), notes };
+};
+/** The launch folder is inside a mapped root and placed under it (core/workspace.ts): the root shows it, no own mapping. */
+export const shownByRoot = (roots, workspaceHost, guestWorkspace) => {
+    const root = projectForHostDir(roots, workspaceHost);
+    return root !== null && guestDirFor(root, workspaceHost).toLowerCase() === guestWorkspace.replace(/[\\/]+$/, '').toLowerCase();
 };

package/dist/host/projects.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { Missing } from '../core/project-policy.js';
 import { PROJECTS_GUEST, type ProjectEntry, type RootMapping } from '../shared/projects.js';
 import { type Wsb } from './wsb.js';
 export { PROJECTS_GUEST };
@@ -36,7 +37,17 @@ declare const Registry: z.ZodObject<{
         }>;
         registeredAt: z.ZodString;
     }, z.core.$strict>>;
+    atBoot: z.ZodOptional<z.ZodObject<{
+        memoryMb: z.ZodNullable<z.ZodNumber>;
+        mappings: z.ZodArray<z.ZodObject<{
+            host: z.ZodString;
+            guest: z.ZodString;
+            readOnly: z.ZodBoolean;
+        }, z.core.$strict>>;
+        widened: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
+export type AtBoot = NonNullable<z.output<typeof Registry>['atBoot']>;
 export type RegistryEntry = z.output<typeof Entry>;
 export type ProjectRegistry = z.output<typeof Registry>;
 export declare const readRegistry: (storageRoot: string) => ProjectRegistry | null;
@@ -47,12 +58,24 @@ export declare const startRegistry: (storageRoot: string, o: {
     primary: RootMapping;
     roots: RootMapping[];
     boot: RootMapping[];
+    atBoot?: AtBoot;
 }) => RegistryEntry;
-/** Why a folder cannot join the running sandbox without a restart (the caller offers one). */
+/** Reads the memory and mapped folders back from a .wsb this tool wrote (host-only launch folder; bounded). */
+export declare const parseWsbBoot: (xml: string) => AtBoot;
+/**
+ * What the running sandbox booted with. A sandbox started by 1.4.0 or older has no record: it is read from the .wsb in
+ * its launch folder (host-only storage) and recorded. null when neither is there.
+ */
+export declare const bootRecordOf: (storageRoot: string, launchPath: string | null) => AtBoot | null;
+/**
+ * Why a folder cannot join the running sandbox without a restart (the caller offers one). With `missing`: it could
+ * join, but you chose to restart for what it wants at boot (core/project-policy.ts).
+ */
 export declare class NeedsRestart extends Error {
     readonly hostDir: string;
     readonly reason: string;
-    constructor(hostDir: string, reason: string);
+    readonly missing?: Missing | undefined;
+    constructor(hostDir: string, reason: string, missing?: Missing | undefined);
 }
 export interface ProjectMapper {
     /** The projects of the running sandbox (the launch folder first). */

package/dist/host/projects.js

@@ -4,13 +4,14 @@
 //    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 fs from 'node:fs';
 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 { guestDirFor, hubName, isWithin, ownGuestFolder, 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');
@@ -24,6 +25,13 @@ const Registry = z.strictObject({
     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),
+    /** What the sandbox booted with that a joining project may also want (missing in registries of 1.4.0 and older). */
+    atBoot: z.strictObject({
+        memoryMb: z.number().int().positive().nullable(),
+        mappings: z.array(z.strictObject({ host: z.string().max(1024), guest: z.string().max(1024), readOnly: z.boolean() })).max(1024),
+        /** Boot settings turned on for a project mapped at boot (setting -> project): other projects share them. */
+        widened: z.record(z.string().max(100), z.string().max(100)),
+    }).optional(),
 });
 const registryFile = (storageRoot) => path.join(storageRoot, 'run', 'projects.json');
 export const readRegistry = (storageRoot) => readValid(Registry, registryFile(storageRoot));
@@ -34,17 +42,57 @@ export const startRegistry = (storageRoot, o) => {
     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] });
+    saveRegistry(storageRoot, { launchId: o.launchId, protections: o.protections, roots: o.roots, projects: [primary, ...boot], ...(o.atBoot ? { atBoot: o.atBoot } : {}) });
     return primary;
 };
-/** Why a folder cannot join the running sandbox without a restart (the caller offers one). */
+/** Reads the memory and mapped folders back from a .wsb this tool wrote (host-only launch folder; bounded). */
+export const parseWsbBoot = (xml) => {
+    const text = xml.slice(0, 1_000_000);
+    const unescape = (s) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, '\'').replace(/&amp;/g, '&');
+    const mappings = [...text.matchAll(/<MappedFolder><HostFolder>([^<]{1,1024})<\/HostFolder><SandboxFolder>([^<]{1,1024})<\/SandboxFolder><ReadOnly>(true|false)<\/ReadOnly><\/MappedFolder>/g)]
+        .slice(0, 1024).map((m) => ({ host: unescape(m[1]), guest: unescape(m[2]), readOnly: m[3] === 'true' }));
+    const memory = /<MemoryInMB>(\d{1,7})<\/MemoryInMB>/.exec(text);
+    return { memoryMb: memory ? Number(memory[1]) : null, mappings, widened: {} };
+};
+/**
+ * What the running sandbox booted with. A sandbox started by 1.4.0 or older has no record: it is read from the .wsb in
+ * its launch folder (host-only storage) and recorded. null when neither is there.
+ */
+export const bootRecordOf = (storageRoot, launchPath) => {
+    const registry = readRegistry(storageRoot);
+    if (!registry)
+        return null;
+    if (registry.atBoot)
+        return registry.atBoot;
+    if (!launchPath)
+        return null;
+    let xml;
+    try {
+        xml = fs.readFileSync(path.join(launchPath, 'agent.wsb'), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const atBoot = parseWsbBoot(xml);
+    try {
+        saveRegistry(storageRoot, { ...registry, atBoot });
+    }
+    catch { /* the record is a convenience */ }
+    return atBoot;
+};
+/**
+ * Why a folder cannot join the running sandbox without a restart (the caller offers one). With `missing`: it could
+ * join, but you chose to restart for what it wants at boot (core/project-policy.ts).
+ */
 export class NeedsRestart extends Error {
     hostDir;
     reason;
-    constructor(hostDir, reason) {
+    missing;
+    constructor(hostDir, reason, missing) {
         super(reason);
         this.hostDir = hostDir;
         this.reason = reason;
+        this.missing = missing;
     }
 }
 /** Roots first (instant), then `wsb share` where the Windows Sandbox CLI exists, else NeedsRestart. */
@@ -84,7 +132,8 @@ export const projectMapper = (o) => {
             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);
+            // Where it is as a launch folder too (C:\Workspace\<name>), unless another project already uses that place.
+            const guest = ownGuestFolder(host, false, [...reg.projects.map((p) => p.guest), ...reg.roots.map((r) => r.guest)]);
             const shared = shareFolder(wsb, sandbox.id, host, guest);
             if (!shared.ok)
                 throw new NeedsRestart(host, 'wsb share failed (untested on this Windows): ' + shared.error);

package/dist/runtime/daemon.js

@@ -25320,7 +25320,7 @@ var ClaudeProfile = external_exports.strictObject({
 var GuestWorkspace = external_exports.union([external_exports.literal("auto"), external_exports.literal("mirror"), GuestPath]).describe('Where the workspace appears inside the sandbox. "auto" = C:\\Workspace\\<folder name>. "mirror" = the same path as on this PC, so absolute paths in configs and build caches match (another drive letter such as F: is a subst drive onto C:\\Mirror\\F); paths the sandbox reserves (C:\\Users\\..., C:\\Program Files\\...) fall back to "auto".');
 var Mapping = external_exports.strictObject({
   host: external_exports.string().min(1).describe("Folder on this PC (relative paths are relative to the config file)."),
-  guest: GuestPath.describe("Where it appears inside the sandbox, e.g. C:\\Assets, or on another drive letter (D: to Z:) such as F:\\SteamLibrary\\steamapps\\common\\Game: mapped to C:\\Mirror\\F\\... and shown as F: (subst) at boot."),
+  guest: external_exports.string().min(1).max(1024).optional().describe("Where it appears inside the sandbox, e.g. C:\\Assets, or on another drive letter (D: to Z:) such as F:\\SteamLibrary\\steamapps\\common\\Game (shown as F: at boot). Leave it out to use the same path as on this PC (a folder inside the project stays where it is in the project). A path the sandbox cannot use (C:\\Windows\\..., C:\\Users\\..., one already in use) goes to C:\\Mapped\\<drive>\\<path> instead, and the launch says so."),
   readOnly: external_exports.boolean().describe("true = the agent can only read it."),
   optional: external_exports.boolean().optional().describe("true = skip it quietly when the host folder does not exist.")
 });
@@ -25608,6 +25608,7 @@ var Projects = external_exports.strictObject({
   roots: external_exports.array(external_exports.string().min(1)).describe('Folders whose subfolders are your projects (e.g. "F:\\\\Code"), mapped read/write at every start. Any project inside one, including ones you create later, opens in the running sandbox at once, without a restart. Every agent in the sandbox can see all of them.'),
   askToAddRoot: external_exports.boolean().describe("When you start a project whose parent folder is not a root yet, ask once whether to add it."),
   declinedRoots: external_exports.array(external_exports.string().min(1)).describe("Parent folders you said no to (not asked again)."),
+  allowOutsideMappings: external_exports.union([external_exports.literal("ask"), external_exports.boolean()]).describe(`A project's .sandbox-config.json may map folders from outside the project (e.g. a game folder on another drive). "ask" = an interactive launch asks once per project and set of folders, and remembers your answer; true = always allowed (still listed when you approve the file); false = never (the launch stops and says which folders). Only your own settings decide this, never a project file.`),
   wsbShare: external_exports.boolean().describe("On Windows 11 24H2+ with the Windows Sandbox command line (wsb), add other folders to the running sandbox with `wsb share` (untested). Otherwise starting a project outside every root offers a restart.")
 });
 
@@ -25650,7 +25651,7 @@ var LocalOverrides = external_exports.strictObject({
   readOnly: external_exports.boolean().describe("Map this project read-only."),
   // A project may turn the filter on and keep more out, never let ignored files in.
   workspaceFilter: WorkspaceFilter.pick({ enabled: true, exclude: true }).partial(),
-  mappings: external_exports.array(Mapping).describe("Extra folders inside this project (relative to this file), e.g. a read-only data folder at another place in the sandbox."),
+  mappings: external_exports.array(Mapping).describe("Extra folders (relative paths are relative to this file), e.g. a read-only data folder at another place in the sandbox. Folders outside the project are used only as your projects.allowOutsideMappings setting allows (by default you are asked once)."),
   scripts: Strings.describe("Scripts (.ps1 / .mjs / .cmd, relative to this file) run inside the sandbox before the agent."),
   // This PC's resources are yours to share: CPU and paging file (this PC's disk) are not a project's to set.
   sandbox: Sandbox.omit({ cpuLimit: true, pageFileMb: true }).partial(),
@@ -25681,6 +25682,15 @@ var AttachEndpoint = external_exports.strictObject({
   port: external_exports.number().int().min(1024).max(65535),
   token: Text(256)
 });
+var BootProgress = external_exports.strictObject({
+  step: external_exports.number().int().min(1).max(32),
+  steps: external_exports.number().int().min(1).max(32),
+  title: Text(120),
+  /** Being set up now; percent while it downloads (when the size is known). */
+  active: external_exports.array(external_exports.strictObject({ name: Text(64), percent: external_exports.number().int().min(0).max(100).optional() })).max(8),
+  done: external_exports.number().int().min(0).max(1e3),
+  total: external_exports.number().int().min(0).max(1e3)
+});
 var SandboxStatus = external_exports.object({
   launchId: Text(64),
   phase: external_exports.enum(["booting", "provisioning", "ready", "failed"]),
@@ -25690,7 +25700,9 @@ var SandboxStatus = external_exports.object({
   guestWorkspace: Text(),
   headless: external_exports.boolean(),
   /** The sandbox's IPv4 addresses (for network.forwardPorts; the host only uses ones on its Hyper-V network). */
-  addresses: external_exports.array(external_exports.string().max(45)).max(8).optional()
+  addresses: external_exports.array(external_exports.string().max(45)).max(8).optional(),
+  /** A malformed progress is dropped, never the status (the phase still counts). */
+  progress: BootProgress.optional().catch(void 0)
 });
 var Version = external_exports.strictObject({ spec: Text(128), source: Text(256) });
 var DatabasePlan = external_exports.strictObject({
@@ -25984,6 +25996,10 @@ var checksumRequired = false;
 var setChecksumRequired = (on) => {
   checksumRequired = on;
 };
+var downloadWatcher = null;
+var watchDownloads = (watcher) => {
+  downloadWatcher = watcher;
+};
 var download = async (url2, destination, expected = null) => {
   const sums = typeof expected === "string" || expected === null ? { sha256: expected } : expected;
   if (checksumRequired && !sums.sha256?.trim() && !sums.sha512?.trim()) {
@@ -25996,8 +26012,25 @@ var download = async (url2, destination, expected = null) => {
     const want = sums[kind]?.trim().toLowerCase();
     return want ? [{ want, hash: crypto.createHash(kind) }] : [];
   });
+  const size = Number(response.headers.get("content-length")) || 0;
+  const report = size > 0 ? downloadWatcher?.() ?? null : null;
+  let received = 0;
+  let tenth = 0;
+  let reportedAt = Date.now();
   const tap = new Transform({ transform(chunk, _encoding, done) {
     for (const c of checks) c.hash.update(chunk);
+    if (report) {
+      received += chunk.length;
+      const now2 = Math.floor(received * 10 / size);
+      if (now2 !== tenth || Date.now() - reportedAt > 5e3) {
+        tenth = now2;
+        reportedAt = Date.now();
+        try {
+          report(Math.min(1, received / size));
+        } catch {
+        }
+      }
+    }
     done(null, chunk);
   } });
   const partial2 = destination + ".part";
@@ -26145,16 +26178,25 @@ var mkdirp = (p) => {
   fs5.mkdirSync(p, { recursive: true });
   return p;
 };
-var setSandboxStatus = (phase, message) => {
+var progress;
+var setSandboxStatus = (phase, message, update) => {
   try {
+    if (update) progress = fitProgress({ step: 1, steps: 1, title: "", active: [], done: 0, total: 0, ...progress, ...update });
     writeJsonAtomicChecked(phase, message);
   } catch (e) {
     warn("Could not update sandbox status: " + errMsg(e));
   }
 };
+var fitProgress = (p) => ({
+  ...p,
+  title: p.title.slice(0, 120),
+  done: Math.min(p.done, 1e3),
+  total: Math.min(p.total, 1e3),
+  active: p.active.slice(0, 8).map((a) => ({ name: a.name.slice(0, 64), ...a.percent === void 0 ? {} : { percent: Math.max(0, Math.min(100, Math.round(a.percent))) } }))
+});
 var ownAddresses = () => Object.values(os3.networkInterfaces()).flat().filter((i) => Boolean(i) && i.family === "IPv4" && !i.internal).map((i) => i.address).slice(0, 8);
 var writeJsonAtomicChecked = (phase, message) => {
-  writeJsonAtomic(run.sandbox, { launchId: session.launchId, phase, message, updatedAt: now(), workspaceHost: session.workspaceHost, guestWorkspace: workspace, headless: session.headless, addresses: ownAddresses() });
+  writeJsonAtomic(run.sandbox, { launchId: session.launchId, phase, message, updatedAt: now(), workspaceHost: session.workspaceHost, guestWorkspace: workspace, headless: session.headless, addresses: ownAddresses(), ...progress ? { progress } : {} });
 };
 var exec = (file3, args, options = {}) => {
   const result = spawnSync(file3, args, { stdio: "inherit", windowsHide: true, ...options });
@@ -26273,6 +26315,7 @@ import path45 from "node:path";
 // src/shared/projects.ts
 import path8 from "node:path";
 var PROJECTS_GUEST = "C:\\Projects";
+var WORKSPACES_GUEST = "C:\\Workspace";
 var norm2 = (p) => path8.win32.resolve(p).replace(/[\\/]+$/, "").toLowerCase();
 var isWithin = (parent, child) => {
   const a = norm2(parent);
@@ -26286,7 +26329,7 @@ var hubName = (hostDir, taken) => {
   for (let i = 2; ; i++) if (!used.has((base + "-" + i).toLowerCase())) return base + "-" + i;
 };
 var isBelow = (parent, child) => isWithin(parent, child) && norm2(parent) !== norm2(child);
-var insideProjects = (guestDir, roots = [], projectsDir = PROJECTS_GUEST) => isBelow(projectsDir, guestDir) || roots.some((r) => isWithin(r, guestDir));
+var insideProjects = (guestDir, roots = [], projectsDir = PROJECTS_GUEST) => isBelow(projectsDir, guestDir) || isBelow(WORKSPACES_GUEST, guestDir) || roots.some((r) => isWithin(r, guestDir));
 
 // src/guest/daemon/state.ts
 import path9 from "node:path";
@@ -26510,6 +26553,9 @@ var runHooksAsync = async (stage, env, target) => {
   }
 };
 
+// src/guest/toolchains/index.ts
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
+
 // src/guest/toolchains/common.ts
 import fs10 from "node:fs";
 import path14 from "node:path";
@@ -28644,6 +28690,7 @@ var plan = (config2, versions, o) => {
 
 // src/guest/toolchains/index.ts
 var PARALLEL2 = 4;
+var currentStep = new AsyncLocalStorage2();
 var locks = /* @__PURE__ */ new Map();
 var lockKey = (name) => name.split(" ")[0].toLowerCase();
 var exclusive = async (name, work) => {
@@ -28669,10 +28716,19 @@ var runSteps = async (steps, o) => {
   const running = /* @__PURE__ */ new Set();
   const waiting = [];
   let done = 0;
-  const say = o.report ?? ((message) => setSandboxStatus("provisioning", message));
+  const percent = /* @__PURE__ */ new Map();
+  const active = () => [...running].map((name) => ({ name, ...percent.has(name) ? { percent: percent.get(name) } : {} }));
+  const say = o.report ?? ((message) => setSandboxStatus("provisioning", message, { active: active(), done, total: steps.length }));
   const report = () => {
     if (running.size) say("Installing " + [...running].join(", ") + " (" + done + " of " + steps.length + " done)");
   };
+  if (!o.report) watchDownloads(() => {
+    const name = currentStep.getStore();
+    return name ? (fraction) => {
+      percent.set(name, Math.round(fraction * 100));
+      report();
+    } : null;
+  });
   for (const s of steps) {
     finished.set(s.name, (async () => {
       await Promise.all((s.after ?? []).map((name) => finished.get(name)));
@@ -28686,16 +28742,22 @@ var runSteps = async (steps, o) => {
       running.add(s.name);
       report();
       try {
-        await exclusive(s.name, () => step(s.name, envs.get(s.name), async () => s.run(envs.get(s.name))));
+        await currentStep.run(s.name, () => exclusive(s.name, () => step(s.name, envs.get(s.name), async () => s.run(envs.get(s.name)))));
       } finally {
         running.delete(s.name);
+        percent.delete(s.name);
         done++;
         report();
         waiting.shift()?.();
       }
     })());
   }
-  await Promise.all(finished.values());
+  try {
+    await Promise.all(finished.values());
+  } finally {
+    if (!o.report) watchDownloads(null);
+  }
+  if (!o.report) setSandboxStatus("provisioning", "Set up " + steps.length + " toolchains and databases", { active: [], done, total: steps.length });
   return envs;
 };
 var setupToolchains = async (config2, versions, options, run2 = {}) => {

package/dist/runtime/db.js

@@ -25316,7 +25316,7 @@ var ClaudeProfile = external_exports.strictObject({
 var GuestWorkspace = external_exports.union([external_exports.literal("auto"), external_exports.literal("mirror"), GuestPath]).describe('Where the workspace appears inside the sandbox. "auto" = C:\\Workspace\\<folder name>. "mirror" = the same path as on this PC, so absolute paths in configs and build caches match (another drive letter such as F: is a subst drive onto C:\\Mirror\\F); paths the sandbox reserves (C:\\Users\\..., C:\\Program Files\\...) fall back to "auto".');
 var Mapping = external_exports.strictObject({
   host: external_exports.string().min(1).describe("Folder on this PC (relative paths are relative to the config file)."),
-  guest: GuestPath.describe("Where it appears inside the sandbox, e.g. C:\\Assets, or on another drive letter (D: to Z:) such as F:\\SteamLibrary\\steamapps\\common\\Game: mapped to C:\\Mirror\\F\\... and shown as F: (subst) at boot."),
+  guest: external_exports.string().min(1).max(1024).optional().describe("Where it appears inside the sandbox, e.g. C:\\Assets, or on another drive letter (D: to Z:) such as F:\\SteamLibrary\\steamapps\\common\\Game (shown as F: at boot). Leave it out to use the same path as on this PC (a folder inside the project stays where it is in the project). A path the sandbox cannot use (C:\\Windows\\..., C:\\Users\\..., one already in use) goes to C:\\Mapped\\<drive>\\<path> instead, and the launch says so."),
   readOnly: external_exports.boolean().describe("true = the agent can only read it."),
   optional: external_exports.boolean().optional().describe("true = skip it quietly when the host folder does not exist.")
 });
@@ -25573,6 +25573,7 @@ var Projects = external_exports.strictObject({
   roots: external_exports.array(external_exports.string().min(1)).describe('Folders whose subfolders are your projects (e.g. "F:\\\\Code"), mapped read/write at every start. Any project inside one, including ones you create later, opens in the running sandbox at once, without a restart. Every agent in the sandbox can see all of them.'),
   askToAddRoot: external_exports.boolean().describe("When you start a project whose parent folder is not a root yet, ask once whether to add it."),
   declinedRoots: external_exports.array(external_exports.string().min(1)).describe("Parent folders you said no to (not asked again)."),
+  allowOutsideMappings: external_exports.union([external_exports.literal("ask"), external_exports.boolean()]).describe(`A project's .sandbox-config.json may map folders from outside the project (e.g. a game folder on another drive). "ask" = an interactive launch asks once per project and set of folders, and remembers your answer; true = always allowed (still listed when you approve the file); false = never (the launch stops and says which folders). Only your own settings decide this, never a project file.`),
   wsbShare: external_exports.boolean().describe("On Windows 11 24H2+ with the Windows Sandbox command line (wsb), add other folders to the running sandbox with `wsb share` (untested). Otherwise starting a project outside every root offers a restart.")
 });
 
@@ -25615,7 +25616,7 @@ var LocalOverrides = external_exports.strictObject({
   readOnly: external_exports.boolean().describe("Map this project read-only."),
   // A project may turn the filter on and keep more out, never let ignored files in.
   workspaceFilter: WorkspaceFilter.pick({ enabled: true, exclude: true }).partial(),
-  mappings: external_exports.array(Mapping).describe("Extra folders inside this project (relative to this file), e.g. a read-only data folder at another place in the sandbox."),
+  mappings: external_exports.array(Mapping).describe("Extra folders (relative paths are relative to this file), e.g. a read-only data folder at another place in the sandbox. Folders outside the project are used only as your projects.allowOutsideMappings setting allows (by default you are asked once)."),
   scripts: Strings.describe("Scripts (.ps1 / .mjs / .cmd, relative to this file) run inside the sandbox before the agent."),
   // This PC's resources are yours to share: CPU and paging file (this PC's disk) are not a project's to set.
   sandbox: Sandbox.omit({ cpuLimit: true, pageFileMb: true }).partial(),
@@ -25646,6 +25647,15 @@ var AttachEndpoint = external_exports.strictObject({
   port: external_exports.number().int().min(1024).max(65535),
   token: Text(256)
 });
+var BootProgress = external_exports.strictObject({
+  step: external_exports.number().int().min(1).max(32),
+  steps: external_exports.number().int().min(1).max(32),
+  title: Text(120),
+  /** Being set up now; percent while it downloads (when the size is known). */
+  active: external_exports.array(external_exports.strictObject({ name: Text(64), percent: external_exports.number().int().min(0).max(100).optional() })).max(8),
+  done: external_exports.number().int().min(0).max(1e3),
+  total: external_exports.number().int().min(0).max(1e3)
+});
 var SandboxStatus = external_exports.object({
   launchId: Text(64),
   phase: external_exports.enum(["booting", "provisioning", "ready", "failed"]),
@@ -25655,7 +25665,9 @@ var SandboxStatus = external_exports.object({
   guestWorkspace: Text(),
   headless: external_exports.boolean(),
   /** The sandbox's IPv4 addresses (for network.forwardPorts; the host only uses ones on its Hyper-V network). */
-  addresses: external_exports.array(external_exports.string().max(45)).max(8).optional()
+  addresses: external_exports.array(external_exports.string().max(45)).max(8).optional(),
+  /** A malformed progress is dropped, never the status (the phase still counts). */
+  progress: BootProgress.optional().catch(void 0)
 });
 var Version = external_exports.strictObject({ spec: Text(128), source: Text(256) });
 var DatabasePlan = external_exports.strictObject({
@@ -25895,6 +25907,7 @@ var checksumRequired = false;
 var setChecksumRequired = (on) => {
   checksumRequired = on;
 };
+var downloadWatcher = null;
 var download = async (url2, destination, expected = null) => {
   const sums = typeof expected === "string" || expected === null ? { sha256: expected } : expected;
   if (checksumRequired && !sums.sha256?.trim() && !sums.sha512?.trim()) {
@@ -25907,8 +25920,25 @@ var download = async (url2, destination, expected = null) => {
     const want = sums[kind]?.trim().toLowerCase();
     return want ? [{ want, hash: crypto.createHash(kind) }] : [];
   });
+  const size = Number(response.headers.get("content-length")) || 0;
+  const report = size > 0 ? downloadWatcher?.() ?? null : null;
+  let received = 0;
+  let tenth = 0;
+  let reportedAt = Date.now();
   const tap = new Transform({ transform(chunk, _encoding, done) {
     for (const c of checks) c.hash.update(chunk);
+    if (report) {
+      received += chunk.length;
+      const now2 = Math.floor(received * 10 / size);
+      if (now2 !== tenth || Date.now() - reportedAt > 5e3) {
+        tenth = now2;
+        reportedAt = Date.now();
+        try {
+          report(Math.min(1, received / size));
+        } catch {
+        }
+      }
+    }
     done(null, chunk);
   } });
   const partial2 = destination + ".part";