windows-development-sandbox 1.0.5 → 1.4.0

package/dist/cli/validate.js

@@ -0,0 +1,89 @@
+// Checks what the user typed before anything starts, so a typo fails at once with the list of valid values
+// instead of halfway into a sandbox boot. Pure helpers first, then validateOptions (the one call from the dispatcher).
+import fs from 'node:fs';
+import path from 'node:path';
+import { DATABASES } from '../core/detect-databases.js';
+import { fail } from '../core/util.js';
+import { listAccounts } from '../host/accounts.js';
+/** Edit distance, for "did you mean". */
+export const distance = (a, b) => {
+    let row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const next = [i];
+        for (let j = 1; j <= b.length; j++)
+            next[j] = Math.min(row[j] + 1, next[j - 1] + 1, row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        row = next;
+    }
+    return row[b.length];
+};
+/** The closest of `choices` to `input`, when it is close enough to be a typo. */
+export const closest = (input, choices) => {
+    const best = choices.map((c) => ({ c, d: distance(input.toLowerCase(), c.toLowerCase()) })).sort((x, y) => x.d - y.d)[0];
+    return best && best.d <= Math.max(2, Math.floor(input.length / 3)) ? best.c : undefined;
+};
+/** "Unknown agent "cluade". Did you mean claude?" with the valid values as the fix. */
+export const unknownValue = (what, input, choices, howToList) => {
+    const hint = closest(input, choices);
+    return fail('Unknown ' + what + ' "' + input + '".' + (hint ? ' Did you mean ' + hint + '?' : ''), (choices.length ? 'Choose one of: ' + choices.join(', ') + '. ' : '') + howToList);
+};
+/** Node: 22, 22.1, v22.1.0, lts, lts/*, lts/iron, latest, current, node. */
+export const validNodeSpec = (spec) => /^(v?\d+(\.\d+){0,2}|node|latest|current|stable|lts(\/(\*|[a-z]+))?)$/i.test(spec.trim());
+/** Python 3: 3, 3.12, 3.12.4. */
+export const validPythonSpec = (spec) => /^v?3(\.\d+){0,2}$/.test(spec.trim());
+export const checkHarness = (name, harnesses) => {
+    if (name !== undefined && !harnesses.includes(name))
+        unknownValue('agent', name, harnesses, 'Add your own under "harnesses" in your settings (sandbox config).');
+};
+/** Commands that read these options; checked only for them (restart/doctor take --harness too). */
+const LAUNCHING = new Set(['launch', 'generate', 'host-claude']);
+export const PROJECT_ACTIONS = ['list', 'choose', 'add', 'remove', 'include', 'exclude', 'all', 'roots'];
+/** `sandbox projects <action> [value] [folder]`: the action, then what it needs. Pure (no file checks). */
+export const validateProjectsArgs = (args) => {
+    const [action = 'list', value, folder] = args;
+    if (!PROJECT_ACTIONS.includes(action))
+        unknownValue('projects action', action, PROJECT_ACTIONS, 'sandbox projects with no action lists your projects.');
+    if (['add', 'remove', 'include', 'exclude'].includes(action) && !value)
+        fail('Which folder?', 'Usage: sandbox projects ' + action + ' <folder>   (. = this folder)');
+    if (action === 'all' && value !== undefined && !['on', 'off'].includes(value))
+        unknownValue('value for projects all', value, ['on', 'off'], 'sandbox projects all on|off');
+    if (action === 'roots' && value !== undefined && !['list', 'add', 'remove'].includes(value))
+        unknownValue('projects roots action', value, ['list', 'add', 'remove'], 'sandbox projects roots add|remove <folder>');
+    if (action === 'roots' && (value === 'add' || value === 'remove') && !folder)
+        fail('Which folder?', 'Usage: sandbox projects roots ' + value + ' <folder>');
+};
+/** Fails with what is wrong and what is valid, before anything is started. */
+export const validateOptions = (ctx) => {
+    const o = ctx.options;
+    const harnesses = Object.keys(ctx.loaded.config.harnesses);
+    if (['launch', 'generate', 'restart', 'doctor'].includes(o.command))
+        checkHarness(o.harness, harnesses);
+    if (o.command === 'projects')
+        validateProjectsArgs(o.positionals);
+    if (!LAUNCHING.has(o.command))
+        return;
+    if (o.node !== undefined && !validNodeSpec(o.node))
+        fail('"' + o.node + '" is not a Node version.', 'Use a number like 22 or 22.11.0, or lts, latest.');
+    if (o.python !== undefined && !validPythonSpec(o.python))
+        fail('"' + o.python + '" is not a Python 3 version.', 'Use 3, 3.12 or 3.12.4.');
+    for (const db of o.databases.flatMap((d) => d.split(',')).map((d) => d.trim()).filter(Boolean)) {
+        if (!DATABASES.includes(db))
+            unknownValue('database', db, DATABASES, 'Repeat --database for several.');
+    }
+    if (o.account !== undefined) {
+        const names = listAccounts(ctx.storageRoot, ctx.dataPath).map((a) => a.name);
+        if (!names.includes(o.account))
+            unknownValue('account', o.account, names, names.length ? 'See them with: sandbox account list' : 'None saved yet: sign in inside the sandbox, then run sandbox account save <name>.');
+    }
+    for (const s of o.sessions) {
+        checkHarness(s.harness, harnesses);
+        if (!fs.existsSync(s.folder) || !fs.statSync(s.folder).isDirectory())
+            fail('The folder ' + s.folder + ' (--session ' + s.harness + '@...) does not exist.', 'Check the path after the @.');
+    }
+    if (o.sessions.length && (o.harness !== undefined || o.workspace !== undefined))
+        fail('--session names the agent and folder of each session, so --harness and --workspace do not apply.', 'Use only --session <agent>@<folder> (repeatable).');
+    if (o.workspace !== undefined && !fs.existsSync(path.resolve(o.workspace)))
+        fail('The folder ' + path.resolve(o.workspace) + ' does not exist.', 'Check the --workspace path (or leave it out to use the current folder).');
+    for (const script of o.scripts)
+        if (!fs.existsSync(path.resolve(script)))
+            fail('The script ' + path.resolve(script) + ' does not exist.', 'Check the --script path.');
+};

package/dist/core/config.js

@@ -8,11 +8,14 @@ export const DEFAULTS = {
     defaultHarness: 'claude',
     guestWorkspace: 'auto',
     readOnly: false,
+    workspaceFilter: { enabled: false, exclude: [], include: [] },
+    audit: { enabled: false, days: 14, maxMb: 100, processes: true, files: true },
     mappings: [],
-    sandbox: { memoryMb: 'auto', maxMemoryMb: 32768, reserveHostMb: 8192, vGpu: false, networking: true, clipboard: true, audioInput: false, videoInput: false, printerRedirection: false, protectedClient: true, headless: false },
-    storage: { root: '%LOCALAPPDATA%\\AgentSandbox', persistAgentState: true, dataName: 'default' },
-    network: { blockPrivateRanges: true },
-    provisioning: { copyFromHost: true, fallbackToInstall: true, refresh: false, git: { enabled: true, access: 'full' }, terminal: { enabled: true } },
+    sandbox: { memoryMb: 'auto', maxMemoryMb: 32768, maxMemoryPercent: 80, cpuLimit: 80, pageFileMb: 16384, reserveHostMb: 8192, vGpu: false, networking: true, clipboard: true, audioInput: false, videoInput: false, printerRedirection: false, protectedClient: true, headless: false, keepAwake: true },
+    storage: { root: '%LOCALAPPDATA%\\AgentSandbox', persistAgentState: true, dataName: 'default', markSandboxFiles: true, warnDataGb: 50 },
+    network: { blockPrivateRanges: true, allowOnly: [], blockHosts: [], forwardPorts: [], dns: [], proxy: '' },
+    provisioning: { copyFromHost: true, fallbackToInstall: true, refresh: false, git: { enabled: true, access: 'full' }, terminal: { enabled: true }, conpty: { enabled: true } },
+    downloads: { requireChecksum: false },
     toolchains: {
         node: { version: 'host', extraVersions: [], corepack: true, volta: 'auto', globalPackages: [] },
         python: { enabled: 'auto', version: '3', python2: true, pyenv: 'auto', tools: [] },
@@ -32,7 +35,7 @@ export const DEFAULTS = {
         uv: { enabled: true },
         vcRuntime: { enabled: false },
         mesa: { enabled: false, vulkan: false },
-        vscode: { enabled: true },
+        vscode: { enabled: true, setup: true, recommended: true, extensions: [] },
         environment: {},
     },
     databases: {
@@ -44,9 +47,11 @@ export const DEFAULTS = {
         sqlserver: { enabled: 'auto' },
     },
     attach: { enabled: true, reuseSession: true, auto: false, autoHide: false },
+    agentCommands: { enabled: false, agents: 'auto' },
     secrets: { strip: true, allow: [], patterns: [], warnFiles: true },
     personalization: { enabled: true },
-    claudeProfile: { enabled: true, hostDir: 'auto', include: ['settings.json', 'CLAUDE.md', 'commands', 'agents', 'skills', 'plugins'], globalStateFile: 'auto', copyCredentials: false, overwrite: true, syncHistory: true, syncClaudeMem: true },
+    apps: { install: [], custom: {} },
+    claudeProfile: { enabled: true, hostDir: 'auto', include: ['settings.json', 'CLAUDE.md', 'commands', 'agents', 'skills', 'plugins'], globalStateFile: 'auto', copyCredentials: false, overwrite: true, syncHistory: true, historyScope: 'project', syncClaudeMem: true, syncClaudeMemBack: false },
     harnesses: {
         claude: { hostExecutable: 'claude.exe', hostDir: 'auto', npmPackage: '@anthropic-ai/claude-code@latest', npmBin: 'claude', arguments: [], environment: { DISABLE_AUTOUPDATER: '1' }, resumeArguments: ['--continue'] },
         codex: { npmPackage: '@openai/codex@latest', npmBin: 'codex', arguments: [], environment: {}, resumeArguments: ['resume', '--last'] },
@@ -67,6 +72,7 @@ export const DEFAULTS = {
         aider: { uvPackage: 'aider-chat', uvBin: 'aider', arguments: [], environment: {}, resumeArguments: ['--restore-chat-history'] },
     },
     hooks: { failFast: false },
+    projects: { all: false, exclude: [], roots: [], askToAddRoot: true, declinedRoots: [], wsbShare: true },
 };
 /** Per-user folder for config and hooks. Survives reinstalling the npm package. */
 export const userDir = () => process.env.AGENT_SANDBOX_HOME ?? path.join(homeDir(), '.agent-sandbox');

package/dist/core/disk.d.ts

@@ -0,0 +1,16 @@
+export declare const GB: number;
+/** 1536 -> "1.5 KB". */
+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;
+/** 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 {
+    drive: string;
+    totalBytes: number;
+    freeBytes: number;
+    usedBytes: number;
+    holdsStorage: boolean;
+}
+/** Every local drive's size and free space, and which one holds the sandbox storage. */
+export declare const diskUsage: (storageRoot: string) => DiskUsage[];

package/dist/core/disk.js

@@ -0,0 +1,55 @@
+// Sizes and free space on disk, shared by `data`, `repair`, `setup` and the storage cleanup.
+import fs from 'node:fs';
+import path from 'node:path';
+import _ from 'lodash';
+export const GB = 1024 ** 3;
+/** 1536 -> "1.5 KB". */
+export const humanBytes = (bytes) => {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = bytes <= 0 ? 0 : Math.min(units.length - 1, Math.floor(Math.log(bytes) / Math.log(1024)));
+    const value = bytes / 1024 ** i;
+    return (i === 0 ? String(bytes) : value.toFixed(value < 10 ? 1 : 0)) + ' ' + units[i];
+};
+/** 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 const sizeOf = (p) => {
+    try {
+        const stat = fs.lstatSync(p);
+        if (stat.isSymbolicLink())
+            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))));
+    }
+    catch {
+        return 0;
+    }
+};
+/** 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);
+    while (!fs.existsSync(at) && path.dirname(at) !== at)
+        at = path.dirname(at);
+    try {
+        const s = fs.statfsSync(at);
+        return s.bavail * s.bsize;
+    }
+    catch {
+        return null;
+    }
+};
+/** 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) => {
+        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 }];
+        }
+        catch {
+            return [];
+        }
+    });
+};

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

@@ -2,6 +2,20 @@ import type { Config, LocalConfigFile, Overrides } from './types.js';
 export declare const LOCAL_CONFIG_NAME = ".sandbox-config.json";
 /** Validates a folder's settings and resolves its relative paths against that folder. */
 export declare const normalizeOverrides: (data: unknown, dir: string, source: string) => Overrides;
+/**
+ * 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 declare const ON_IS_SAFER: string[];
+export declare const OFF_IS_SAFER: string[];
+export declare const GIT_STRICTNESS: Record<string, number>;
+export declare const NEVER_LOOSER: string[];
+/** What a project file asks for that would loosen one of your protections (so it is not used). */
+export declare const loosenedRequests: (config: Config, ov: Overrides) => {
+    key: string;
+    wanted: unknown;
+    yours: unknown;
+}[];
 /** Applies validated overrides. Mappings with the same guest folder replace the configured ones. */
 export declare const applyOverrides: (config: Config, ov: Overrides) => Config;
 /** Human-readable list of what a local config changes, with risky items flagged. */
@@ -10,3 +24,12 @@ 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;
+/** 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;
+    wanted: unknown;
+}[]) => Config;

package/dist/core/local-config.js

@@ -4,9 +4,10 @@ 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, parseJsonc, tryReadJson, writeJson } from './util.js';
+import { expandPath, fail, fileExists, isInsideOrEqual, parseJsonc, tryReadJson, writeJson } from './util.js';
 export const LOCAL_CONFIG_NAME = '.sandbox-config.json';
 /** Validates a folder's settings and resolves its relative paths against that folder. */
 export const normalizeOverrides = (data, dir, source) => {
@@ -18,14 +19,62 @@ export const normalizeOverrides = (data, dir, source) => {
     const missing = scripts?.filter((s) => !fileExists(s)) ?? [];
     if (missing.length)
         fail(source + ' is not valid:\n  - scripts: file not found: ' + missing.join(', '));
-    return { ...overrides, scripts, mappings: overrides.mappings?.map((m) => ({ ...m, host: expandPath(m.host, dir) })) };
+    const mappings = overrides.mappings?.map((m) => ({ ...m, host: expandPath(m.host, dir) }));
+    // A repo ships this file, so it must not reach the rest of this PC: its extra folders stay inside the project.
+    const outside = mappings?.filter((m) => !insideProject(dir, m.host)) ?? [];
+    if (outside.length)
+        fail(source + ' is not valid:\n  - mappings: a project file may only map folders inside the project, not ' + outside.map((m) => m.host).join(', '), 'Map other folders in your own settings (sandbox config path shows where they are).');
+    return { ...overrides, scripts, mappings };
 };
+/** `folder` (also where it really is, through links) is inside the project folder `dir`. */
+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.
+    const real = (p) => {
+        const full = path.resolve(p);
+        try {
+            return fs.realpathSync.native(full);
+        }
+        catch {
+            return path.dirname(full) === full ? full : path.join(real(path.dirname(full)), path.basename(full));
+        }
+    };
+    return isInsideOrEqual(dir, folder) && isInsideOrEqual(real(dir), real(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 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) => {
+    ON_IS_SAFER.forEach((p) => _.set(merged, p, Boolean(_.get(yours, p)) || Boolean(_.get(merged, p))));
+    OFF_IS_SAFER.forEach((p) => _.set(merged, p, Boolean(_.get(yours, p)) && Boolean(_.get(merged, p))));
+    if (GIT_STRICTNESS[yours.provisioning.git.access] > GIT_STRICTNESS[merged.provisioning.git.access])
+        merged.provisioning.git.access = yours.provisioning.git.access;
+};
+/** What a project file asks for that would loosen one of your protections (so it is not used). */
+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'] : []),
+].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) => {
     const { harness, mappings, scripts: _scripts, $schema: _schema, ...rest } = ov;
     const next = mergeConfig(config, rest);
+    keepStrictest(config, next);
     if (harness)
         next.defaultHarness = harness;
+    // A project adds catalogue apps to yours; it never removes the ones you chose.
+    if (rest.apps?.install)
+        next.apps.install = _.union(config.apps.install, rest.apps.install);
+    // Its patterns keep more out on top of yours; yours stay.
+    if (rest.network?.blockHosts)
+        next.network.blockHosts = _.union(config.network.blockHosts, rest.network.blockHosts);
+    if (rest.workspaceFilter?.exclude)
+        next.workspaceFilter.exclude = _.union(config.workspaceFilter.exclude, rest.workspaceFilter.exclude);
     if (mappings)
         next.mappings = [..._.reject(config.mappings, (m) => mappings.some((o) => o.guest.toLowerCase() === m.guest.toLowerCase())), ...mappings];
     return next;
@@ -41,13 +90,11 @@ export const describeOverrides = (ov) => {
         ...flatten(sections),
     ];
     const risky = _.compact([
-        ov.claudeProfile?.copyCredentials === true && 'claudeProfile.copyCredentials = true copies your Claude LOGIN into the sandbox',
-        ov.network?.blockPrivateRanges === false && 'network.blockPrivateRanges = false turns OFF the LAN block',
         mappings.some((m) => !m.readOnly) && 'a READ/WRITE mapping lets the agent change files outside your workspace',
-        ov.provisioning?.git?.access === 'full' && 'provisioning.git.access = full lets the agent commit and push',
-        ov.sandbox?.vGpu === true && 'sandbox.vGpu = true widens the sandbox attack surface',
     ]);
-    return [...lines, ...risky.map((r) => '!! ' + r)];
+    // These are only used when they are stricter than your own settings, so a project can never loosen them.
+    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);
@@ -62,3 +109,28 @@ 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(300)).max(50)).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]) });
+};
+/** 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);
+    allowed.forEach((a) => _.set(next, a.key, a.wanted));
+    return next;
+};

package/dist/core/project-policy.d.ts

@@ -0,0 +1,15 @@
+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[];
+}
+/**
+ * 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.
+ */
+export declare const checkJoin: (running: Protections, wanted: Protections) => JoinCheck;

package/dist/core/project-policy.js

@@ -0,0 +1,35 @@
+// 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 './local-config.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.
+ */
+export const checkJoin = (running, wanted) => {
+    const stricter = [];
+    const looser = [];
+    for (const setting of NEVER_LOOSER) {
+        const result = compare(setting, setting === 'readOnly' ? false : running[setting], wanted[setting]);
+        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 };
+};

package/dist/core/prompt.d.ts

@@ -0,0 +1,4 @@
+/** A yes/no question (default no). */
+export declare const askYesNo: (question: string, defaultYes?: boolean) => Promise<boolean>;
+/** Asks the user to type `expected` (a stronger confirmation than yes/no). */
+export declare const askTyped: (question: string, expected: string) => Promise<boolean>;

package/dist/core/prompt.js

@@ -0,0 +1,15 @@
+// Questions asked on the terminal, all through @inquirer/prompts. Without an interactive terminal the answer is always "no".
+import { confirm, input } from '@inquirer/prompts';
+/** A yes/no question (default no). */
+export const askYesNo = async (question, defaultYes = false) => {
+    if (!process.stdin.isTTY)
+        return false;
+    return confirm({ message: question, default: defaultYes });
+};
+/** Asks the user to type `expected` (a stronger confirmation than yes/no). */
+export const askTyped = async (question, expected) => {
+    if (!process.stdin.isTTY)
+        return false;
+    const answer = await input({ message: question + ' Type "' + expected + '" to confirm:' });
+    return answer.trim().toLowerCase() === expected;
+};

package/dist/core/safe-paths.d.ts

@@ -0,0 +1,4 @@
+/** A read/write folder mapped into the sandbox must not contain, or sit inside, any protected folder. */
+export declare const assertSafeMapping: (folder: string, packageRoot: string, storageRoot: string) => void;
+/** The agent gets read/write access to the workspace, so refuse folders that would let it reach the tool itself, its storage, or the OS. */
+export declare const assertSafeWorkspace: (workspace: string, packageRoot: string, storageRoot: string) => void;

package/dist/core/safe-paths.js

@@ -0,0 +1,37 @@
+// Which folders may be shared with the sandbox. The agent gets read/write access to what is mapped, so nothing that
+// would let it reach this tool, its storage, your settings or the OS may be mapped.
+import { userDir } from './config.js';
+import { fail, isInsideOrEqual, isRootPath, isUserProfile } from './util.js';
+/** Folders the agent must never be able to write: the tool itself, its storage and your settings for it. */
+const protectedFolders = (packageRoot, storageRoot) => [
+    ['this tool\'s install folder', packageRoot],
+    ['the sandbox storage folder', storageRoot],
+    ['your sandbox settings folder', userDir()],
+];
+/** A read/write folder mapped into the sandbox must not contain, or sit inside, any protected folder. */
+export const assertSafeMapping = (folder, packageRoot, storageRoot) => {
+    if (isRootPath(folder) || isUserProfile(folder))
+        fail('A whole drive or user profile cannot be mapped into the sandbox: ' + folder, 'Map a specific folder instead.');
+    for (const [label, dir] of protectedFolders(packageRoot, storageRoot)) {
+        if (isInsideOrEqual(dir, folder) || isInsideOrEqual(folder, dir))
+            fail(folder + ' cannot be mapped into the sandbox: it overlaps ' + label + ' (' + dir + ').', 'Map a folder that is not inside (and does not contain) ' + dir + '.');
+    }
+};
+/** The agent gets read/write access to the workspace, so refuse folders that would let it reach the tool itself, its storage, or the OS. */
+export const assertSafeWorkspace = (workspace, packageRoot, storageRoot) => {
+    if (isRootPath(workspace))
+        fail('A whole drive cannot be the workspace: ' + workspace, 'Run sandbox claude from a project folder (or pass --workspace <folder>).');
+    if (isUserProfile(workspace))
+        fail('Your whole user profile cannot be the workspace: ' + workspace, 'Run sandbox claude from a project folder (or pass --workspace <folder>).');
+    for (const [label, dir] of protectedFolders(packageRoot, storageRoot)) {
+        if (isInsideOrEqual(dir, workspace))
+            fail(workspace + ' cannot be the workspace: it is inside ' + label + ' (' + dir + '), so the agent could change the code that runs on this PC.', dir === packageRoot ? 'Developing windows-development-sandbox itself? Install it as a copy instead of a link: run `npm run install:global` in the repository, then sandbox claude works there.' : 'Run sandbox claude from a project folder somewhere else.');
+        if (isInsideOrEqual(workspace, dir))
+            fail(workspace + ' cannot be the workspace: it contains ' + label + ' (' + dir + '), which the agent must not be able to change.', 'Run sandbox claude from a project folder that does not contain it.');
+    }
+    for (const name of ['WINDIR', 'SystemRoot', 'ProgramFiles', 'ProgramFiles(x86)', 'ProgramData']) {
+        const dir = process.env[name];
+        if (dir && isInsideOrEqual(dir, workspace))
+            fail('A system folder cannot be the workspace: ' + workspace, 'Run sandbox claude from a project folder.');
+    }
+};

package/dist/core/schema/apps.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+export declare const AppId: z.ZodEnum<{
+    [x: string]: string;
+}>;
+export declare const CustomAppId: z.ZodString;
+export declare const CustomApp: z.ZodObject<{
+    name: z.ZodString;
+    github: z.ZodOptional<z.ZodString>;
+    asset: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    sha256: z.ZodOptional<z.ZodString>;
+    unpack: z.ZodOptional<z.ZodEnum<{
+        file: "file";
+        archive: "archive";
+        nsis: "nsis";
+        msi: "msi";
+    }>>;
+    exe: z.ZodString;
+    cli: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const Apps: z.ZodObject<{
+    install: z.ZodArray<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+    custom: z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        github: z.ZodOptional<z.ZodString>;
+        asset: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        sha256: z.ZodOptional<z.ZodString>;
+        unpack: z.ZodOptional<z.ZodEnum<{
+            file: "file";
+            archive: "archive";
+            nsis: "nsis";
+            msi: "msi";
+        }>>;
+        exe: z.ZodString;
+        cli: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;

package/dist/core/schema/apps.js

@@ -0,0 +1,27 @@
+// Apps installed in the sandbox: entries from the catalogue (shared/apps.ts) and programs of your own.
+import { z } from 'zod';
+import { APPS } from '../../shared/apps.js';
+const CATALOGUE_IDS = APPS.filter((a) => !a.setting).map((a) => a.id);
+export const AppId = z.enum(CATALOGUE_IDS);
+export const CustomAppId = z.string().regex(/^[a-z0-9][a-z0-9-]{0,40}$/, 'lower-case letters, digits and - only');
+const compiles = (pattern) => { try {
+    new RegExp(pattern);
+    return true;
+}
+catch {
+    return false;
+} };
+export const CustomApp = z.strictObject({
+    name: z.string().min(1).max(80).describe('The name on the desktop shortcut, e.g. "My Tool".'),
+    github: z.string().regex(/^[\w.-]+\/[\w.-]+$/, 'owner/repo, e.g. sharkdp/bat').optional().describe('GitHub repository (owner/repo): the file comes from its latest release.'),
+    asset: z.string().max(200).refine(compiles, 'not a valid pattern').optional().describe('With github: a pattern (regular expression) matching the release file, e.g. windows.*x64\\.zip$'),
+    url: z.string().url().startsWith('https://', 'https:// only').optional().describe('Or a direct https:// download link (zip, 7z, exe or msi).'),
+    sha256: z.string().regex(/^[0-9a-fA-F]{64}$/, '64 hex characters').optional().describe('SHA-256 of the download (GitHub releases usually publish one; then this is not needed).'),
+    unpack: z.enum(['archive', 'file', 'nsis', 'msi']).optional().describe('archive (zip, 7z, tar: the default), file (a single .exe), nsis (an installer 7-Zip can open) or msi.'),
+    exe: z.string().min(1).max(200).describe('The program to start (found anywhere in the download), e.g. mytool.exe.'),
+    cli: z.boolean().optional().describe('A command-line tool: its folder goes on PATH instead of getting a desktop shortcut.'),
+}).refine((a) => (a.github && a.asset ? !a.url : Boolean(a.url) && !a.github && !a.asset), { message: 'give github + asset, or url (not both)' });
+export const Apps = z.strictObject({
+    install: z.array(AppId).describe('Apps from the catalogue to install in every sandbox (the Apps screen in the menu lists them by category). Each is downloaded once and kept.'),
+    custom: z.record(CustomAppId, CustomApp).describe('Programs of your own: a GitHub release or a download link, and the program to start. Installed like the catalogue apps.'),
+});

package/dist/core/schema/common.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export declare const GuestPath: z.ZodString;
+export declare const Name: z.ZodString;
+export declare const Strings: z.ZodArray<z.ZodString>;
+export declare const toggle: (description: string) => z.ZodObject<{
+    enabled: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const SchemaRef: z.ZodString;
+export declare const GitAccess: z.ZodEnum<{
+    readonly: "readonly";
+    full: "full";
+    none: "none";
+}>;
+/** true, false, or "auto": only when the project uses it (found from files like go.mod in the workspace or one level down). */
+export declare const Enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+export declare const enabled: (what: string, markers: string) => z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+export declare const Packages: (what: string, example: string) => z.ZodArray<z.ZodString>;

package/dist/core/schema/common.js

@@ -0,0 +1,15 @@
+// Building blocks shared by the settings schemas.
+import { z } from 'zod';
+import { isValidGuestPath } from '../../shared/guest-paths.js';
+// Rules (and RESERVED_GUEST) live in shared/guest-paths.ts: the host re-checks them before writing the .wsb.
+export const GuestPath = z.string().refine(isValidGuestPath, 'reserved or invalid guest path (a folder under C:\\ other than Windows, Program Files, Users, AgentData, Mirror, ..., or on drive D: to Z:)');
+export const Name = z.string().regex(/^[A-Za-z0-9_-]+$/, 'letters, numbers, - and _ only');
+export const Strings = z.array(z.string());
+export const toggle = (description) => z.strictObject({ enabled: z.boolean().describe(description) });
+export const SchemaRef = z.string().describe('Path or URL of the JSON Schema for editor autocomplete and docs.');
+export const GitAccess = z.enum(['full', 'readonly', 'none'])
+    .describe('full: normal git. readonly: status/log/diff/show/blame only (no commit, push, checkout, ...). none: no git at all; .git is hidden from the agent.');
+/** true, false, or "auto": only when the project uses it (found from files like go.mod in the workspace or one level down). */
+export const Enabled = z.union([z.boolean(), z.literal('auto')]);
+export const enabled = (what, markers) => Enabled.describe(what + ' true, false, or "auto" = only when the project has ' + markers + '.');
+export const Packages = (what, example) => Strings.describe(what + ', installed once and kept (e.g. ' + example + ').');