windows-development-sandbox 1.4.1 → 1.4.3

package/dist/{guest/toolchains → core/detect}/versions.js

@@ -3,9 +3,12 @@
 /** Turns an .nvmrc-style spec (20, v20.11.1, lts/*, lts/iron, node, latest) into an exact version like 20.11.1. */
 export const pickNodeVersion = (releases, spec) => {
     const s = spec.trim().toLowerCase().replace(/^v/, '');
-    const hit = ['node', 'latest', 'current', 'stable'].includes(s) ? releases[0]
-        : s === 'lts' || s === 'lts/*' ? releases.find((r) => r.lts)
-            : s.startsWith('lts/') ? releases.find((r) => typeof r.lts === 'string' && r.lts.toLowerCase() === s.slice(4))
+    const hit = ['node', 'latest', 'current', 'stable'].includes(s)
+        ? releases[0]
+        : s === 'lts' || s === 'lts/*'
+            ? releases.find((r) => r.lts)
+            : s.startsWith('lts/')
+                ? releases.find((r) => typeof r.lts === 'string' && r.lts.toLowerCase() === s.slice(4))
                 : releases.find((r) => r.version === 'v' + s || r.version.startsWith('v' + s + '.'));
     return hit ? hit.version.slice(1) : null;
 };
@@ -19,19 +22,26 @@ export const pickSpreadVersions = (available, current, max) => {
     const newestPerMajor = exact.filter((v, i) => exact[i + 1]?.split('.')[0] !== v.split('.')[0]);
     const pool = newestPerMajor.filter((v) => v.split('.')[0] !== current.split('.')[0]);
     const want = Math.max(0, max - 1);
-    const picked = want >= pool.length ? pool
-        : want === 1 ? [pool[pool.length - 1]]
-            : Array.from({ length: want }, (_, i) => pool[Math.round(i * (pool.length - 1) / (want - 1))]);
+    const picked = want >= pool.length
+        ? pool
+        : want === 1
+            ? [pool[pool.length - 1]]
+            : Array.from({ length: want }, (_, i) => pool[Math.round((i * (pool.length - 1)) / (want - 1))]);
     return [current, ...picked];
 };
 /** Newest stable version matching a prefix spec ("3" -> 3.13.1, "3.12" -> 3.12.10). */
 export const pickPackageVersion = (all, spec) => {
     const s = spec.trim().replace(/^python-?/i, '');
-    const stable = all.filter((v) => /^\d+(\.\d+)*$/.test(v)).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+    const stable = all
+        .filter((v) => /^\d+(\.\d+)*$/.test(v))
+        .sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
     return stable.find((v) => v === s || v.startsWith(s + '.')) ?? null;
 };
 /** Version spec from a version file's text (.ruby-version "ruby-3.3.1", .java-version "temurin-21", ...): its first x[.y[.z]]. */
-export const specFromVersionFile = (text) => /(\d+(?:\.\d+){0,2})/.exec(text.split(/\r?\n/).map((l) => l.replace(/#.*$/, '').trim()).find(Boolean) ?? '')?.[1] ?? null;
+export const specFromVersionFile = (text) => /(\d+(?:\.\d+){0,2})/.exec(text
+    .split(/\r?\n/)
+    .map((l) => l.replace(/#.*$/, '').trim())
+    .find(Boolean) ?? '')?.[1] ?? null;
 /** Java major version from .java-version ("21", "17.0.9", "1.8", "temurin-21") or .sdkmanrc ("java=21.0.2-tem"). */
 export const javaMajorFrom = (text, sdkmanrc = false) => {
     const line = sdkmanrc ? /^\s*java\s*=\s*(.+)$/m.exec(text)?.[1] : text;
@@ -55,23 +65,29 @@ export const pickGoRelease = (releases, spec) => {
  */
 export const projectUses = (entries, markers) => entries.some((entry) => {
     const name = entry.split(/[\/]/).pop().toLowerCase();
-    return markers.some((m) => (m.startsWith('*.') ? name.endsWith(m.slice(1).toLowerCase()) : name === m.toLowerCase()));
+    return markers.some((m) => m.startsWith('*.') ? name.endsWith(m.slice(1).toLowerCase()) : name === m.toLowerCase());
 });
 /** Newest MSVC tools version among VS manifest package ids ("microsoft.vc.14.44.17.14.tools.hostx64.targetx64.base"). */
 export const pickMsvcVersion = (packageIds, spec = 'latest') => {
-    const versions = packageIds.map((id) => /^microsoft\.vc\.(\d+\.\d+\.\d+\.\d+)\.tools\.hostx64\.targetx64\.base$/i.exec(id)?.[1]).filter((v) => Boolean(v));
+    const versions = packageIds
+        .map((id) => /^microsoft\.vc\.(\d+\.\d+\.\d+\.\d+)\.tools\.hostx64\.targetx64\.base$/i.exec(id)?.[1])
+        .filter((v) => Boolean(v));
     const sorted = [...new Set(versions)].sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
     return (spec === 'latest' ? sorted[0] : sorted.find((v) => v === spec || v.startsWith(spec + '.'))) ?? null;
 };
 /** Newest Windows SDK build among component ids ("microsoft.visualstudio.component.windows11sdk.26100"). */
 export const pickWindowsSdk = (packageIds, spec = 'latest') => {
-    const found = packageIds.map((id) => ({ id, build: /^microsoft\.visualstudio\.component\.windows1[01]sdk\.(\d+)$/i.exec(id)?.[1] })).filter((x) => Boolean(x.build));
+    const found = packageIds
+        .map((id) => ({ id, build: /^microsoft\.visualstudio\.component\.windows1[01]sdk\.(\d+)$/i.exec(id)?.[1] }))
+        .filter((x) => Boolean(x.build));
     const sorted = found.sort((a, b) => Number(b.build) - Number(a.build));
     const hit = spec === 'latest' ? sorted[0] : sorted.find((x) => x.build === spec.replace(/^10\.0\./, '').split('.')[0]);
     return hit ? { build: hit.build, componentId: hit.id } : null;
 };
 /** The .cab files an SDK .msi refers to (their names are inside the msi as plain "<32 hex>.cab"). */
-export const msiCabs = (msi) => [...new Set([...msi.toString('latin1').matchAll(/([0-9a-f]{32}\.cab)/gi)].map((m) => m[1].toLowerCase()))];
+export const msiCabs = (msi) => [
+    ...new Set([...msi.toString('latin1').matchAll(/([0-9a-f]{32}\.cab)/gi)].map((m) => m[1].toLowerCase())),
+];
 /** The oldest CMake many projects (OpenMoHAA among them) accept. */
 export const CMAKE_FLOOR = '3.25';
 export const cmakeTooOld = (version) => /^\d+\.\d+/.test(version) && version.localeCompare(CMAKE_FLOOR, undefined, { numeric: true }) < 0;

package/dist/core/disk.d.ts

@@ -3,6 +3,8 @@ export declare const GB: number;
 export declare const humanBytes: (bytes: number) => string;
 /** Size on disk, never following links or junctions (a link counts as 0, so a planted junction cannot make us walk this PC's disk). */
 export declare const sizeOf: (p: string) => number;
+/** sizeOf with a time budget: null when measuring would take longer than `ms` (a big data folder can take minutes). */
+export declare const sizeWithin: (p: string, ms: number) => number | null;
 /** Free bytes on the drive that holds `dir` (which may not exist yet: the nearest existing parent is asked); null if unknown. */
 export declare const freeBytesAt: (dir: string) => number | null;
 export interface DiskUsage {

package/dist/core/disk.js

@@ -18,12 +18,44 @@ export const sizeOf = (p) => {
             return 0;
         if (!stat.isDirectory())
             return stat.size;
-        return _.sumBy(fs.readdirSync(p, { withFileTypes: true }), (d) => (d.isSymbolicLink() ? 0 : sizeOf(path.join(p, d.name))));
+        return _.sumBy(fs.readdirSync(p, { withFileTypes: true }), (d) => d.isSymbolicLink() ? 0 : sizeOf(path.join(p, d.name)));
     }
     catch {
         return 0;
     }
 };
+/** sizeOf with a time budget: null when measuring would take longer than `ms` (a big data folder can take minutes). */
+export const sizeWithin = (p, ms) => {
+    const deadline = Date.now() + ms;
+    const overBudget = Symbol('over budget');
+    const walk = (at) => {
+        if (Date.now() > deadline)
+            throw overBudget;
+        let stat;
+        let entries = [];
+        try {
+            stat = fs.lstatSync(at);
+            if (stat.isDirectory() && !stat.isSymbolicLink())
+                entries = fs.readdirSync(at, { withFileTypes: true });
+        }
+        catch {
+            return 0; /* gone or unreadable: counts as nothing, like sizeOf */
+        }
+        if (stat.isSymbolicLink())
+            return 0;
+        if (!stat.isDirectory())
+            return stat.size;
+        return _.sumBy(entries, (d) => (d.isSymbolicLink() ? 0 : walk(path.join(at, d.name))));
+    };
+    try {
+        return walk(p);
+    }
+    catch (e) {
+        if (e === overBudget)
+            return null;
+        throw e;
+    }
+};
 /** Free bytes on the drive that holds `dir` (which may not exist yet: the nearest existing parent is asked); null if unknown. */
 export const freeBytesAt = (dir) => {
     let at = path.resolve(dir);
@@ -40,13 +72,24 @@ export const freeBytesAt = (dir) => {
 /** Every local drive's size and free space, and which one holds the sandbox storage. */
 export const diskUsage = (storageRoot) => {
     const storageDrive = path.parse(path.resolve(storageRoot)).root.toUpperCase();
-    return 'CDEFGHIJKLMNOPQRSTUVWXYZ'.split('').map((letter) => letter + ':\\').flatMap((drive) => {
+    return 'CDEFGHIJKLMNOPQRSTUVWXYZ'
+        .split('')
+        .map((letter) => letter + ':\\')
+        .flatMap((drive) => {
         try {
             const s = fs.statfsSync(drive);
             const totalBytes = s.blocks * s.bsize;
             if (!totalBytes)
                 return [];
-            return [{ drive, totalBytes, freeBytes: s.bavail * s.bsize, usedBytes: totalBytes - s.bfree * s.bsize, holdsStorage: drive.toUpperCase() === storageDrive }];
+            return [
+                {
+                    drive,
+                    totalBytes,
+                    freeBytes: s.bavail * s.bsize,
+                    usedBytes: totalBytes - s.bfree * s.bsize,
+                    holdsStorage: drive.toUpperCase() === storageDrive,
+                },
+            ];
         }
         catch {
             return [];

package/dist/core/local-config/boot-wants.d.ts

@@ -0,0 +1,45 @@
+import type { Config, ResolvedMapping } from '../types.js';
+import type { Protections } from './policy.js';
+/** .wsb devices a project may want on (only when your settings or your answer for that project allow it). */
+export declare const BOOT_SETTINGS: string[];
+/** What the running sandbox booted with (host-only registry). */
+export interface BootRecord {
+    memoryMb: number | null;
+    mappings: ResolvedMapping[];
+}
+/** What a project wants that the running sandbox started without. */
+export interface Missing {
+    settings: string[];
+    memoryMb: number | null;
+    mappings: ResolvedMapping[];
+}
+/** A project mapped at boot besides the launch folder, with its effective config. */
+export interface BootWant {
+    name: string;
+    config: Config;
+}
+export interface Widened {
+    config: Config;
+    /** Setting -> the project it was turned on for. */
+    widened: Record<string, string>;
+    notes: string[];
+}
+/**
+ * The boot-only things `config` (a project's effective config: your settings, its approved file, your answers) asks
+ * for that the running sandbox lacks. `exists`: optional mappings whose folder is missing are no wish.
+ */
+export declare function missingAtBoot(running: Protections, boot: BootRecord, config: Config, exists?: (folder: string) => boolean): Missing;
+export declare function nothingMissing(m: Missing): boolean;
+/** "mw2-agent wants vGPU and 2 folders (C:\Steam\..., F:\SteamLibrary\...), but this sandbox started without them." */
+export declare function describeMissing(project: string, m: Missing): string;
+/** "Set sandbox.vGpu (or the mappings) in your own settings to have them in every sandbox." */
+export declare function missingTip(m: Missing): string;
+/**
+ * The launch folder's config plus what the other projects mapped at boot want: their allowed .wsb devices, a fixed
+ * memory size larger than the launch's, and their mappings (placed with every other mapping at launch).
+ * `keepOff`: devices the launch folder's own .sandbox-config.json switched off; they stay off.
+ */
+export declare function widenForProjects(launch: Config, others: readonly BootWant[], opts?: {
+    keepOff?: readonly string[];
+    exists?: (folder: string) => boolean;
+}): Widened;

package/dist/core/local-config/boot-wants.js

@@ -0,0 +1,120 @@
+// What a project WANTS at boot (a .wsb device you allowed for it, more memory, its mappings) and the running sandbox
+// started without. Those can only come with a restart, so they are named (missingAtBoot), and a sandbox started with
+// several projects boots with all of their allowed wants (widenForProjects). Pure.
+import _ from 'lodash';
+/** .wsb devices a project may want on (only when your settings or your answer for that project allow it). */
+export const BOOT_SETTINGS = [
+    'sandbox.vGpu',
+    'sandbox.networking',
+    'sandbox.clipboard',
+    'sandbox.audioInput',
+    'sandbox.videoInput',
+    'sandbox.printerRedirection',
+];
+const LABELS = {
+    'sandbox.vGpu': 'vGPU',
+    'sandbox.networking': 'networking',
+    'sandbox.clipboard': 'the shared clipboard',
+    'sandbox.audioInput': 'the microphone',
+    'sandbox.videoInput': 'the camera',
+    'sandbox.printerRedirection': 'printers',
+};
+function sameHost(a, b) {
+    return a.toLowerCase().replace(/\\+$/, '') === b.toLowerCase().replace(/\\+$/, '');
+}
+/** `m`'s folder is mapped, wherever the launch placed it (read-only is enough for a read-only wish). */
+function isMapped(mapped, m) {
+    return mapped.some((x) => sameHost(x.host, m.host) && (m.readOnly || !x.readOnly));
+}
+function listing(items) {
+    return items.length <= 1 ? items.join('') : items.slice(0, -1).join(', ') + ' and ' + items[items.length - 1];
+}
+/**
+ * The boot-only things `config` (a project's effective config: your settings, its approved file, your answers) asks
+ * for that the running sandbox lacks. `exists`: optional mappings whose folder is missing are no wish.
+ */
+export function missingAtBoot(running, boot, config, exists = () => true) {
+    const memory = config.sandbox.memoryMb;
+    return {
+        settings: BOOT_SETTINGS.filter((s) => _.get(config, s) === true && running[s] === false),
+        memoryMb: typeof memory === 'number' && boot.memoryMb !== null && memory > boot.memoryMb ? memory : null,
+        mappings: config.mappings
+            .filter((m) => (!m.optional || exists(m.host)) && !isMapped(boot.mappings, m))
+            .map((m) => ({ host: m.host, guest: m.guest ?? m.host, readOnly: m.readOnly })),
+    };
+}
+export function nothingMissing(m) {
+    return m.settings.length === 0 && m.memoryMb === null && m.mappings.length === 0;
+}
+/** "mw2-agent wants vGPU and 2 folders (C:\Steam\..., F:\SteamLibrary\...), but this sandbox started without them." */
+export function describeMissing(project, m) {
+    const folders = m.mappings.length
+        ? [
+            m.mappings.length +
+                ' folder' +
+                (m.mappings.length === 1 ? '' : 's') +
+                ' (' +
+                m.mappings.map((x) => x.host).join(', ') +
+                ')',
+        ]
+        : [];
+    const items = [
+        ...m.settings.map((s) => LABELS[s] ?? s),
+        ...(m.memoryMb !== null ? [m.memoryMb + ' MB of memory'] : []),
+        ...folders,
+    ];
+    const pronoun = items.length === 1 && !m.mappings.length ? 'it' : 'them';
+    return project + ' wants ' + listing(items) + ', but this sandbox started without ' + pronoun + '.';
+}
+/** "Set sandbox.vGpu (or the mappings) in your own settings to have them in every sandbox." */
+export function missingTip(m) {
+    const keys = [...m.settings, ...(m.memoryMb !== null ? ['sandbox.memoryMb'] : [])];
+    const what = keys.length ? listing(keys) + (m.mappings.length ? ' (or the mappings)' : '') : 'the mappings';
+    return 'Set ' + what + ' in your own settings to have them in every sandbox.';
+}
+/**
+ * The launch folder's config plus what the other projects mapped at boot want: their allowed .wsb devices, a fixed
+ * memory size larger than the launch's, and their mappings (placed with every other mapping at launch).
+ * `keepOff`: devices the launch folder's own .sandbox-config.json switched off; they stay off.
+ */
+export function widenForProjects(launch, others, opts = {}) {
+    const keepOff = opts.keepOff ?? [];
+    const exists = opts.exists ?? (() => true);
+    const config = _.cloneDeep(launch);
+    const widened = {};
+    const notes = [];
+    for (const setting of BOOT_SETTINGS) {
+        const by = others.find((o) => _.get(o.config, setting) === true);
+        if (!by || _.get(config, setting) === true)
+            continue;
+        const label = LABELS[setting] ?? setting;
+        if (keepOff.includes(setting)) {
+            notes.push(by.name +
+                ' wants ' +
+                label +
+                ", but the launch folder's .sandbox-config.json switches it off, so it stays off.");
+            continue;
+        }
+        _.set(config, setting, true);
+        widened[setting] = by.name;
+        notes.push(label + ' is on in this sandbox (for every project in it): ' + by.name + ' asks for it and you allowed it.');
+    }
+    for (const o of others) {
+        const mem = o.config.sandbox.memoryMb;
+        if (typeof mem === 'number' && typeof config.sandbox.memoryMb === 'number' && mem > config.sandbox.memoryMb)
+            config.sandbox.memoryMb = mem;
+        for (const m of o.config.mappings) {
+            if (config.mappings.some((x) => sameHost(x.host, m.host)))
+                continue;
+            if (m.optional && !exists(m.host))
+                continue;
+            if (!exists(m.host)) {
+                notes.push(o.name + ': mapped folder not found, skipped: ' + m.host);
+                continue;
+            }
+            // Where it appears (and moving it when that place is taken) is decided with every other mapping at launch.
+            config.mappings.push({ ...m, optional: true });
+        }
+    }
+    return { config, widened, notes };
+}

package/dist/core/local-config/file.d.ts

@@ -0,0 +1,3 @@
+import type { LocalConfigFile } from '../types.js';
+export declare const LOCAL_CONFIG_NAME = ".sandbox-config.json";
+export declare const readLocalConfig: (dir: string) => LocalConfigFile | null;

package/dist/core/local-config/file.js

@@ -0,0 +1,16 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileExists, parseJsonc } from '../util/index.js';
+export const LOCAL_CONFIG_NAME = '.sandbox-config.json';
+export const readLocalConfig = (dir) => {
+    const file = path.join(dir, LOCAL_CONFIG_NAME);
+    if (!fileExists(file))
+        return null;
+    const raw = fs.readFileSync(file);
+    return {
+        path: file,
+        hash: crypto.createHash('sha256').update(raw).digest('hex'),
+        data: parseJsonc(raw.toString('utf8'), file),
+    };
+};

package/dist/core/local-config/index.d.ts

@@ -0,0 +1,5 @@
+export { LOCAL_CONFIG_NAME, readLocalConfig } from './file.js';
+export { normalizeOverrides, ON_IS_SAFER, OFF_IS_SAFER, GIT_STRICTNESS, NEVER_LOOSER, loosenedRequests, applyOverrides, describeOverrides, allowRequests, outsideMappings, insideProject, } from './overrides.js';
+export { trustStorePath, isTrusted, saveTrust, allowStorePath, allowedAnswer, saveAllowed, OUTSIDE_FOLDER, outsideKey, } from './trust.js';
+export * from './policy.js';
+export * from './boot-wants.js';

package/dist/core/local-config/index.js

@@ -0,0 +1,7 @@
+// A project's .sandbox-config.json: validated against the LocalOverrides schema (a safe subset of settings), applied
+// over the user config, and only used once you have approved this exact version of the file.
+export { LOCAL_CONFIG_NAME, readLocalConfig } from './file.js';
+export { normalizeOverrides, ON_IS_SAFER, OFF_IS_SAFER, GIT_STRICTNESS, NEVER_LOOSER, loosenedRequests, applyOverrides, describeOverrides, allowRequests, outsideMappings, insideProject, } from './overrides.js';
+export { trustStorePath, isTrusted, saveTrust, allowStorePath, allowedAnswer, saveAllowed, OUTSIDE_FOLDER, outsideKey, } from './trust.js';
+export * from './policy.js';
+export * from './boot-wants.js';

package/dist/core/{local-config.d.ts → local-config/overrides.d.ts}

@@ -1,14 +1,13 @@
-import type { Config, LocalConfigFile, Overrides } from './types.js';
-export declare const LOCAL_CONFIG_NAME = ".sandbox-config.json";
+import type { Config, Overrides } from '../types.js';
 /** Validates a folder's settings and resolves its relative paths against that folder. */
 export declare const normalizeOverrides: (data: unknown, dir: string, source: string) => Overrides;
 /**
  * The project file's mappings of folders outside the project (%VAR% expanded, links and short names followed). A repo
  * ships this file, so these reach the rest of this PC: projects.allowOutsideMappings in YOUR settings decides.
  */
-export declare const outsideMappings: <M extends {
+export declare function outsideMappings<M extends {
     host: string;
-}>(dir: string, mappings?: M[]) => M[];
+}>(dir: string, mappings?: readonly M[]): M[];
 /** `folder` (also where it really is, through links) is inside the project folder `dir`. */
 export declare const insideProject: (dir: string, folder: string) => boolean;
 /**
@@ -29,20 +28,6 @@ export declare const loosenedRequests: (config: Config, ov: Overrides) => {
 export declare const applyOverrides: (config: Config, ov: Overrides) => Config;
 /** Human-readable list of what a local config changes, with risky items flagged. */
 export declare const describeOverrides: (ov: Overrides, dir?: string) => string[];
-export declare const readLocalConfig: (dir: string) => LocalConfigFile | null;
-export declare const trustStorePath: (storageRoot: string) => string;
-export declare const isTrusted: (store: string, file: string, hash: string) => boolean;
-export declare const saveTrust: (store: string, file: string, hash: string) => void;
-export declare const allowStorePath: (storageRoot: string) => string;
-/** true = you allowed it, false = you said no (not asked again), null = not asked yet. */
-export declare const allowedAnswer: (store: string, file: string, setting: string, value: unknown) => boolean | null;
-export declare const saveAllowed: (store: string, file: string, setting: string, value: unknown, allow: boolean) => void;
-/** Answers for folders outside the project are kept with the others, one per folder (and read-only or not). */
-export declare const OUTSIDE_FOLDER = "folder outside the project";
-export declare const outsideKey: (m: {
-    host: string;
-    readOnly: boolean;
-}) => string;
 /** Your config with these requests let through, so applyOverrides' "strictest wins" keeps the project's value. */
 export declare const allowRequests: (config: Config, allowed: {
     key: string;

package/dist/core/{local-config.js → local-config/overrides.js}

@@ -1,17 +1,12 @@
-// A project's .sandbox-config.json: validated against the LocalOverrides schema (a safe subset of settings), applied
-// over the user config, and only used once you have approved this exact version of the file.
 import fs from 'node:fs';
 import path from 'node:path';
-import crypto from 'node:crypto';
 import _ from 'lodash';
-import { z } from 'zod';
-import { mergeConfig } from './config.js';
-import { describeIssues, LocalOverrides } from './schema.js';
-import { expandPath, fail, fileExists, isInsideOrEqual, parseJsonc, tryReadJson, writeJson } from './util.js';
-export const LOCAL_CONFIG_NAME = '.sandbox-config.json';
+import { mergeConfig } from '../config/index.js';
+import { describeIssues, LocalOverridesSchema } from '../schema/index.js';
+import { expandPath, fail, fileExists, isInsideOrEqual } from '../util/index.js';
 /** Validates a folder's settings and resolves its relative paths against that folder. */
 export const normalizeOverrides = (data, dir, source) => {
-    const parsed = LocalOverrides.safeParse(data);
+    const parsed = LocalOverridesSchema.safeParse(data);
     if (!parsed.success)
         fail(source + ' is not valid:\n  - ' + describeIssues(parsed.error).join('\n  - '));
     const overrides = parsed.data;
@@ -26,10 +21,13 @@ export const normalizeOverrides = (data, dir, source) => {
  * The project file's mappings of folders outside the project (%VAR% expanded, links and short names followed). A repo
  * ships this file, so these reach the rest of this PC: projects.allowOutsideMappings in YOUR settings decides.
  */
-export const outsideMappings = (dir, mappings = []) => mappings.filter((m) => !insideProject(dir, m.host));
+export function outsideMappings(dir, mappings = []) {
+    return mappings.filter((m) => !insideProject(dir, m.host));
+}
 /** `folder` (also where it really is, through links) is inside the project folder `dir`. */
 export const insideProject = (dir, folder) => {
-    // Where a path really is: the nearest existing folder resolved (links, 8.3 short names), plus the part not created yet.
+    // Where a path really is: the nearest existing folder resolved (links, 8.3 short names), plus the part not created
+    // yet.
     const real = (p) => {
         const full = path.resolve(p);
         try {
@@ -45,8 +43,25 @@ export const insideProject = (dir, folder) => {
  * Protections a project file may only make stricter, never looser. A repo can ship the file, so it must not be able to
  * switch off what you turned on (or turn on what you turned off). The strictest of the two values always wins.
  */
-export const ON_IS_SAFER = ['readOnly', 'workspaceFilter.enabled', 'network.blockPrivateRanges', 'sandbox.protectedClient', 'downloads.requireChecksum'];
-export const OFF_IS_SAFER = ['sandbox.networking', 'sandbox.clipboard', 'sandbox.audioInput', 'sandbox.videoInput', 'sandbox.printerRedirection', 'sandbox.vGpu', 'claudeProfile.copyCredentials', 'claudeProfile.enabled', 'claudeProfile.syncHistory', 'claudeProfile.syncClaudeMem'];
+export const ON_IS_SAFER = [
+    'readOnly',
+    'workspaceFilter.enabled',
+    'network.blockPrivateRanges',
+    'sandbox.protectedClient',
+    'downloads.requireChecksum',
+];
+export const OFF_IS_SAFER = [
+    'sandbox.networking',
+    'sandbox.clipboard',
+    'sandbox.audioInput',
+    'sandbox.videoInput',
+    'sandbox.printerRedirection',
+    'sandbox.vGpu',
+    'claudeProfile.copyCredentials',
+    'claudeProfile.enabled',
+    'claudeProfile.syncHistory',
+    'claudeProfile.syncClaudeMem',
+];
 export const GIT_STRICTNESS = { full: 0, readonly: 1, none: 2 };
 export const NEVER_LOOSER = [...ON_IS_SAFER, ...OFF_IS_SAFER, 'provisioning.git.access'];
 const keepStrictest = (yours, merged) => {
@@ -59,7 +74,10 @@ const keepStrictest = (yours, merged) => {
 export const loosenedRequests = (config, ov) => [
     ...ON_IS_SAFER.filter((p) => _.has(ov, p) && !_.get(ov, p) && _.get(config, p)),
     ...OFF_IS_SAFER.filter((p) => _.has(ov, p) && _.get(ov, p) && !_.get(config, p)),
-    ...(_.has(ov, 'provisioning.git.access') && GIT_STRICTNESS[_.get(ov, 'provisioning.git.access')] < GIT_STRICTNESS[config.provisioning.git.access] ? ['provisioning.git.access'] : []),
+    ...(_.has(ov, 'provisioning.git.access') &&
+        GIT_STRICTNESS[_.get(ov, 'provisioning.git.access')] < GIT_STRICTNESS[config.provisioning.git.access]
+        ? ['provisioning.git.access']
+        : []),
 ].map((key) => ({ key, wanted: _.get(ov, key), yours: _.get(config, key) }));
 /** Applies validated overrides. Mappings with the same guest folder replace the configured ones. */
 export const applyOverrides = (config, ov) => {
@@ -78,17 +96,27 @@ export const applyOverrides = (config, ov) => {
         next.workspaceFilter.exclude = _.union(config.workspaceFilter.exclude, rest.workspaceFilter.exclude);
     const sameGuest = (a, b) => Boolean(a && b && a.toLowerCase() === b.toLowerCase());
     if (mappings)
-        next.mappings = [..._.reject(config.mappings, (m) => mappings.some((o) => sameGuest(o.guest, m.guest))), ...mappings];
+        next.mappings = [
+            ..._.reject(config.mappings, (m) => mappings.some((o) => sameGuest(o.guest, m.guest))),
+            ...mappings,
+        ];
     return next;
 };
-const flatten = (value, prefix = '') => _.isPlainObject(value) ? Object.entries(value).flatMap(([k, v]) => flatten(v, prefix ? prefix + '.' + k : k)) : [prefix + ' = ' + JSON.stringify(value)];
+const flatten = (value, prefix = '') => _.isPlainObject(value)
+    ? Object.entries(value).flatMap(([k, v]) => flatten(v, prefix ? prefix + '.' + k : k))
+    : [prefix + ' = ' + JSON.stringify(value)];
 /** Human-readable list of what a local config changes, with risky items flagged. */
 export const describeOverrides = (ov, dir) => {
     const { harness, mappings = [], scripts = [], $schema: _schema, ...sections } = ov;
     const outside = dir ? outsideMappings(dir, mappings) : [];
     const lines = [
         ...(harness ? ['agent = ' + harness] : []),
-        ...mappings.map((m) => (m.readOnly ? 'read-only' : 'READ/WRITE') + ' folder ' + m.host + '  ->  ' + (m.guest ?? 'the same path') + (outside.includes(m) ? '  (outside the project)' : '')),
+        ...mappings.map((m) => (m.readOnly ? 'read-only' : 'READ/WRITE') +
+            ' folder ' +
+            m.host +
+            '  ->  ' +
+            (m.guest ?? 'the same path') +
+            (outside.includes(m) ? '  (outside the project)' : '')),
         ...scripts.map((s) => 'runs inside the sandbox: ' + s),
         ...flatten(sections),
     ];
@@ -99,41 +127,6 @@ export const describeOverrides = (ov, dir) => {
     const limited = NEVER_LOOSER.filter((p) => _.has(sections, p)).map((p) => p + ' is only used if it is stricter than your own setting');
     return [...lines, ...risky.map((r) => '!! ' + r), ...limited.map((r) => '   ' + r)];
 };
-export const readLocalConfig = (dir) => {
-    const file = path.join(dir, LOCAL_CONFIG_NAME);
-    if (!fileExists(file))
-        return null;
-    const raw = fs.readFileSync(file);
-    return { path: file, hash: crypto.createHash('sha256').update(raw).digest('hex'), data: parseJsonc(raw.toString('utf8'), file) };
-};
-// ---- approvals (host-only: <storage>\trusted-configs.json) ----------------------------------------------------------
-export const trustStorePath = (storageRoot) => path.join(storageRoot, 'trusted-configs.json');
-const loadTrust = (store) => tryReadJson(store) ?? {};
-const key = (file) => path.resolve(file).toLowerCase();
-export const isTrusted = (store, file, hash) => loadTrust(store)[key(file)] === hash;
-export const saveTrust = (store, file, hash) => writeJson(store, { ...loadTrust(store), [key(file)]: hash });
-// ---- looser settings you allowed for one project (host-only: <storage>\allowed-requests.json) ----------------------
-// A project file can never loosen a protection by itself. When it asks, you are asked once (interactively); a "yes"
-// is kept here, per project file and per "setting = value", so only that value is ever let through for that project.
-export const allowStorePath = (storageRoot) => path.join(storageRoot, 'allowed-requests.json');
-const loadAllowed = (store) => {
-    const parsed = z.record(z.string(), z.array(z.string().max(2000)).max(500)).safeParse(tryReadJson(store) ?? {});
-    return parsed.success ? parsed.data : {};
-};
-const allowKey = (setting, value) => setting + ' = ' + JSON.stringify(value);
-/** true = you allowed it, false = you said no (not asked again), null = not asked yet. */
-export const allowedAnswer = (store, file, setting, value) => {
-    const answers = loadAllowed(store)[key(file)] ?? [];
-    return answers.includes(allowKey(setting, value)) ? true : answers.includes('no: ' + allowKey(setting, value)) ? false : null;
-};
-export const saveAllowed = (store, file, setting, value, allow) => {
-    const all = loadAllowed(store);
-    const entry = allowKey(setting, value);
-    writeJson(store, { ...all, [key(file)]: _.union(_.without(all[key(file)] ?? [], entry, 'no: ' + entry), [(allow ? '' : 'no: ') + entry]) });
-};
-/** Answers for folders outside the project are kept with the others, one per folder (and read-only or not). */
-export const OUTSIDE_FOLDER = 'folder outside the project';
-export const outsideKey = (m) => (m.readOnly ? 'read-only ' : 'read/write ') + path.resolve(m.host).toLowerCase();
 /** Your config with these requests let through, so applyOverrides' "strictest wins" keeps the project's value. */
 export const allowRequests = (config, allowed) => {
     const next = _.cloneDeep(config);

package/dist/core/local-config/policy.d.ts

@@ -0,0 +1,19 @@
+import type { Config } from '../types.js';
+/** The protections of a running sandbox, by setting path (`sandbox.networking`, `provisioning.git.access`, ...). */
+export type Protections = Record<string, boolean | string>;
+export declare const protectionsOf: (config: Config) => Protections;
+export interface JoinCheck {
+    /** Settings this project needs stricter than the running sandbox: the launch is refused. */
+    stricter: string[];
+    /** Settings it would have looser: it gets the sandbox's (stricter) value; shown as a note. */
+    looser: string[];
+    /** Settings the sandbox turned on at its start for another project you allowed them for: shared, shown as a note. */
+    shared: string[];
+}
+/**
+ * Compares a project's effective protections with the running sandbox's. Hub projects are always read/write
+ * (Windows Sandbox maps the hub once, read/write), so a read-only project counts as stricter. `widened`: the boot
+ * settings the sandbox turned on for another of its projects (with your consent); a project that has them off
+ * shares them instead of being refused.
+ */
+export declare const checkJoin: (running: Protections, wanted: Protections, widened?: string[]) => JoinCheck;

package/dist/core/local-config/policy.js

@@ -0,0 +1,45 @@
+// Joining a running sandbox from another project. Its protections (network, LAN block, git access, clipboard, the
+// .wsb device settings, read-only) are machine-wide: they were fixed when the sandbox booted for the first project.
+// A second project may never loosen them, and a project that needs a STRICTER setting than the running sandbox has
+// cannot get it there without changing it for the sessions already running, so that launch is refused with a clear
+// message. A project asking for less than the sandbox has simply runs with the sandbox's (stricter) setting.
+// Pure: the host checks it before registering a project, the tests drive it directly.
+import _ from 'lodash';
+import { GIT_STRICTNESS, NEVER_LOOSER, OFF_IS_SAFER, ON_IS_SAFER } from './overrides.js';
+export const protectionsOf = (config) => Object.fromEntries(NEVER_LOOSER.map((p) => [p, _.get(config, p)]));
+/** 1 = `wanted` is stricter than `running`, -1 = looser, 0 = the same. */
+const compare = (setting, running, wanted) => {
+    if (setting === 'provisioning.git.access')
+        return Math.sign((GIT_STRICTNESS[String(wanted)] ?? 0) - (GIT_STRICTNESS[String(running)] ?? 0));
+    if (ON_IS_SAFER.includes(setting))
+        return Number(Boolean(wanted)) - Number(Boolean(running));
+    if (OFF_IS_SAFER.includes(setting))
+        return Number(Boolean(running)) - Number(Boolean(wanted));
+    return 0;
+};
+/**
+ * Compares a project's effective protections with the running sandbox's. Hub projects are always read/write
+ * (Windows Sandbox maps the hub once, read/write), so a read-only project counts as stricter. `widened`: the boot
+ * settings the sandbox turned on for another of its projects (with your consent); a project that has them off
+ * shares them instead of being refused.
+ */
+export const checkJoin = (running, wanted, widened = []) => {
+    const stricter = [];
+    const looser = [];
+    const shared = [];
+    for (const setting of NEVER_LOOSER) {
+        const result = compare(setting, setting === 'readOnly' ? false : running[setting], wanted[setting]);
+        if (result > 0 && widened.includes(setting))
+            shared.push(setting);
+        else if (result > 0)
+            stricter.push(setting +
+                ' = ' +
+                JSON.stringify(wanted[setting]) +
+                ' (the running sandbox has ' +
+                JSON.stringify(setting === 'readOnly' ? false : running[setting]) +
+                ')');
+        if (result < 0)
+            looser.push(setting + ' stays ' + JSON.stringify(running[setting]));
+    }
+    return { stricter, looser, shared };
+};

package/dist/core/local-config/trust.d.ts

@@ -0,0 +1,13 @@
+export declare const trustStorePath: (storageRoot: string) => string;
+export declare const isTrusted: (store: string, file: string, hash: string) => boolean;
+export declare const saveTrust: (store: string, file: string, hash: string) => void;
+export declare const allowStorePath: (storageRoot: string) => string;
+/** true = you allowed it, false = you said no (not asked again), null = not asked yet. */
+export declare const allowedAnswer: (store: string, file: string, setting: string, value: unknown) => boolean | null;
+export declare const saveAllowed: (store: string, file: string, setting: string, value: unknown, allow: boolean) => void;
+/** Answers for folders outside the project are kept with the others, one per folder (and read-only or not). */
+export declare const OUTSIDE_FOLDER = "folder outside the project";
+export declare function outsideKey(m: {
+    host: string;
+    readOnly: boolean;
+}): string;