windows-development-sandbox 1.4.1 → 1.4.3

package/dist/host/generate.js

@@ -1,115 +0,0 @@
-// Writes a launch folder for one sandbox: session.json (what the guest needs to know), the bundled runtime, hooks, the
-// staged Claude settings and the .wsb file that starts Windows Sandbox. The pieces live in launch/.
-import fs from 'node:fs';
-import path from 'node:path';
-import crypto from 'node:crypto';
-import { decideToolchains, resolveToolchains } from '../core/detect-toolchains.js';
-import { readPwshScripts, usesPwsh } from '../core/detect-pwsh.js';
-import { widenForProjects } from '../core/project-policy.js';
-import { dirExists, ensureDir, fail, writeJson } from '../core/util.js';
-import { substDrives } from '../shared/guest-paths.js';
-import { PROJECTS_GUEST, hubName } from '../shared/projects.js';
-import { planBootProjects } from './launch/projects.js';
-import { hostClaudeDir, stageClaudeProfile } from './claude-profile.js';
-import { databaseCatalog, planDatabases } from './database-plan.js';
-import { collectMappings } from './launch/mappings.js';
-import { copyRuntime, stageGitIdentity, stageHooks } from './launch/stage.js';
-import { buildWsb, resolveMemoryMb } from './launch/wsb.js';
-import { capturePersonalization } from './personalize.js';
-import { pcLanguages } from './pc-scan.js';
-import { msvcHint, projectEntries } from './project-scan.js';
-import { assertTestWritable } from './test-guard.js';
-const NO_PROFILE = { hostDir: null, staged: [], skipped: [], credentials: false, secretsRemoved: [] };
-/** Which toolchains the project needs ("auto" settings follow the project's files and what this PC has). */
-export const decideProjectToolchains = (o) => {
-    const { config, workspaceHost } = o.run;
-    const msvcScript = config.toolchains.msvc.enabled === 'auto' ? msvcHint(workspaceHost) : undefined;
-    const pwshScript = config.toolchains.pwsh.enabled === 'auto' ? usesPwsh(readPwshScripts(workspaceHost)) : null;
-    const hints = { ...(msvcScript ? { msvc: msvcScript } : {}), ...(pwshScript ? { pwsh: pwshScript } : {}) };
-    return decideToolchains(config.toolchains, projectEntries(workspaceHost), o.pcLanguages ?? pcLanguages(), hints);
-};
-/** What was found on this PC to copy instead of download. */
-const hostToolsOf = (probe) => ({
-    node: Boolean(probe.nodeDir),
-    nodeVersion: probe.nodeDir || probe.nvmNode ? probe.hostNodeVersion.replace(/^v/, '') : null,
-    harnessExecutable: probe.harnessExe?.file ?? null,
-    git: Boolean(probe.gitDir),
-    nvm: Boolean(probe.nvmDir),
-    volta: Boolean(probe.volta),
-    pyenv: Boolean(probe.pyenv),
-});
-/**
- * env.cmd, which logon.cmd calls before it opens Windows Terminal: Terminal expands "%AGENT_WORKSPACE%" (the starting
- * folder of new tabs) from its own environment, and the runtime only sets the variable machine-wide after Terminal
- * started. `%` is doubled for cmd; a Windows path holds no quotes.
- */
-export const logonEnv = (workspace) => '@set "AGENT_WORKSPACE=' + workspace.replace(/[\r\n"]/g, '').replace(/%/g, '%%') + '"\r\n';
-export const generateSandbox = (given) => {
-    // Several projects at boot: the sandbox also gets what the others want and you allowed (core/project-policy.ts).
-    const others = given.bootWants?.projects ?? [];
-    const boot = planBootProjects({ run: given.run, packageRoot: given.packageRoot, extraProjects: given.extraProjects, knownProjects: given.knownProjects });
-    const wide = widenForProjects(given.run.config, others, { keepOff: given.bootWants?.keepOff, exists: dirExists });
-    const o = { ...given, run: { ...given.run, config: wide.config } };
-    const { config, dataPath, workspaceHost, harnessName, storageRoot } = o.run;
-    const harness = harnessName === 'none' ? null : config.harnesses[harnessName] ?? fail('Unknown agent: ' + harnessName, 'Configured agents: ' + Object.keys(config.harnesses).join(', '));
-    if (!dirExists(workspaceHost))
-        fail('The workspace folder does not exist: ' + workspaceHost, 'cd into the project first.');
-    assertTestWritable(storageRoot);
-    assertTestWritable(dataPath);
-    // Checked before anything is written, so a refusal leaves nothing behind.
-    const memoryMb = Math.max(resolveMemoryMb(config.sandbox, o.freeMemoryBytes), ...others.map((p) => typeof p.config.sandbox.memoryMb === 'number' ? p.config.sandbox.memoryMb : 0));
-    const launchId = Date.now() + '-' + crypto.randomBytes(3).toString('hex');
-    const launchPath = path.join(storageRoot, 'launches', launchId);
-    ensureDir(launchPath);
-    ensureDir(dataPath);
-    const mappingNotes = [];
-    const mappings = collectMappings(o, launchPath, boot, mappingNotes);
-    const profile = harnessName === 'claude' ? stageClaudeProfile(config.claudeProfile, launchPath, workspaceHost, config.secrets) : NO_PROFILE;
-    stageGitIdentity(launchPath);
-    const personalization = config.personalization.enabled ? capturePersonalization(launchPath) : 'disabled';
-    const databases = o.databases ?? planDatabases(config.databases, workspaceHost);
-    const toolchainDecisions = decideProjectToolchains(o);
-    const session = {
-        launchId,
-        project: path.basename(workspaceHost),
-        projectId: hubName(workspaceHost, []),
-        workspace: config.guestWorkspace,
-        workspaceHost,
-        projectsDir: PROJECTS_GUEST,
-        // Every folder mapped for other projects (roots and projects mapped at boot): the guest accepts projects in them.
-        roots: [...boot.roots, ...boot.projects].map((r) => r.guest),
-        ...(o.autoSession === false ? { autoSession: false } : {}),
-        harnessName,
-        harness,
-        harnessArguments: o.harnessArgs,
-        persistAgentState: config.storage.persistAgentState,
-        networking: config.sandbox.networking,
-        headless: config.sandbox.headless,
-        network: config.network,
-        provisioning: config.provisioning,
-        // "auto" is decided here, so the guest and the launch table agree.
-        toolchains: resolveToolchains(config.toolchains, toolchainDecisions),
-        databases,
-        databaseCatalog: databaseCatalog(config.databases),
-        versions: o.run.versions,
-        attach: config.attach,
-        hooks: config.hooks,
-        downloads: config.downloads,
-        hostTools: hostToolsOf(o.probe),
-        claudeProfile: { overwrite: config.claudeProfile.overwrite, items: profile.staged, credentials: profile.credentials, hostConfigDir: profile.hostDir ?? hostClaudeDir(config.claudeProfile), syncClaudeMem: config.claudeProfile.syncClaudeMem },
-        personalization: fs.existsSync(path.join(launchPath, 'personalize', 'personalize.reg')),
-        substDrives: substDrives(mappings.map((m) => m.guest)),
-        cpuLimitPercent: config.sandbox.cpuLimit === 'none' ? null : config.sandbox.cpuLimit,
-        pageFileMb: config.sandbox.pageFileMb,
-        apps: config.apps,
-        auditProcesses: config.audit.enabled && config.audit.processes,
-    };
-    const sessionPath = path.join(launchPath, 'session.json');
-    writeJson(sessionPath, session);
-    fs.writeFileSync(path.join(launchPath, 'env.cmd'), logonEnv(session.workspace), 'utf8');
-    copyRuntime(o.packageRoot, launchPath);
-    stageHooks(o.packageRoot, launchPath, o.run.scripts);
-    const wsbPath = path.join(launchPath, 'agent.wsb');
-    fs.writeFileSync(wsbPath, buildWsb(config, memoryMb, mappings), 'utf8');
-    return { wsbPath, launchPath, launchId, sessionPath, memoryMb, bootConfig: config, widened: wide.widened, mappings, profile, personalization, databases, toolchains: toolchainDecisions, projects: { ...boot, notes: [...boot.notes, ...wide.notes] }, mappingNotes };
-};

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

@@ -1,17 +0,0 @@
-import type { ResolvedRun } from '../../core/types.js';
-import { type RootMapping } from '../../shared/projects.js';
-/** More folders than this would make the .wsb (and every boot) unwieldy; the rest join with a restart later. */
-export declare const MAX_BOOT_PROJECTS = 48;
-export interface BootProjects {
-    roots: RootMapping[];
-    projects: RootMapping[];
-    notes: string[];
-}
-export declare const planBootProjects: (o: {
-    run: ResolvedRun;
-    packageRoot: string;
-    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/wsb.js

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

package/dist/host/motw.d.ts

@@ -1,17 +0,0 @@
-/** What Windows runs when you open it (not source files such as .js or .py: those need a program you choose). */
-export declare const RISKY: RegExp;
-/** Marks one file if it is a program or script (and a plain file, not a link). Returns true when it marked it. */
-export declare const markFromSandbox: (file: string) => boolean;
-/** Has this file the mark? */
-export declare const isMarked: (file: string) => boolean;
-/** Watches the projects while the sandbox runs and marks what appears or changes; returns a function that stops it. */
-export declare const watchAndMark: (projects: string[], note?: (message: string) => void) => (() => void);
-/** The projects to watch and mark (empty: storage.markSandboxFiles is off). */
-export declare const saveMarkedProjects: (storageRoot: string, dataPath: string, projects: string[]) => void;
-export declare const readMarkedProjects: (storageRoot: string, dataPath: string) => string[];
-/** The data folder's size, measured by the watcher when a sandbox closes (measuring at launch would be slow). */
-export declare const saveDataSize: (storageRoot: string, dataPath: string, bytes: number) => void;
-export declare const readDataSize: (storageRoot: string, dataPath: string) => {
-    bytes: number;
-    at: string;
-} | null;

package/dist/host/motw.js

@@ -1,74 +0,0 @@
-// storage.markSandboxFiles: programs and scripts that appear or change in a project while a sandbox runs get Windows'
-// "downloaded from the internet" mark (the Zone.Identifier stream, zone 3). Running one on this PC then goes through
-// SmartScreen, and PowerShell's RemoteSigned policy refuses an unsigned marked script. So something an agent planted is
-// not run by a double-click or a habit. Runs in the background watcher; only the mark is written, never the file.
-import fs from 'node:fs';
-import path from 'node:path';
-import { z } from 'zod';
-import { readValid, writeJsonAtomic } from '../shared/rundir.js';
-/** What Windows runs when you open it (not source files such as .js or .py: those need a program you choose). */
-export const RISKY = /\.(exe|dll|com|scr|pif|msi|msix|msp|appx|appxbundle|bat|cmd|ps1|psm1|psd1|vbs|vbe|wsf|wsh|hta|lnk|url|jar|reg|cpl|application|gadget|chm)$/i;
-const MARK = '[ZoneTransfer]\r\nZoneId=3\r\nHostUrl=about:windows-development-sandbox\r\n';
-/** Folders not worth watching closely (git's own files; dependency and build folders are still marked). */
-const SKIP = /(^|[\\/])\.git([\\/]|$)/i;
-/** Marks one file if it is a program or script (and a plain file, not a link). Returns true when it marked it. */
-export const markFromSandbox = (file) => {
-    if (!RISKY.test(file) || SKIP.test(file))
-        return false;
-    try {
-        const stat = fs.lstatSync(file);
-        if (!stat.isFile())
-            return false;
-        fs.writeFileSync(file + ':Zone.Identifier', MARK);
-        return true;
-    }
-    catch {
-        return false;
-    }
-};
-/** Has this file the mark? */
-export const isMarked = (file) => {
-    try {
-        return fs.readFileSync(file + ':Zone.Identifier', 'utf8').includes('ZoneId=3');
-    }
-    catch {
-        return false;
-    }
-};
-/** Watches the projects while the sandbox runs and marks what appears or changes; returns a function that stops it. */
-export const watchAndMark = (projects, note = () => undefined) => {
-    const pending = new Set();
-    let timer;
-    const flush = () => {
-        timer = undefined;
-        const marked = [...pending].filter(markFromSandbox);
-        pending.clear();
-        if (marked.length)
-            note('marked as from the sandbox (SmartScreen asks before they run here): ' + marked.slice(0, 10).map((f) => path.basename(f)).join(', ') + (marked.length > 10 ? ' and ' + (marked.length - 10) + ' more' : ''));
-    };
-    const watchers = projects.flatMap((project) => {
-        try {
-            return [fs.watch(project, { recursive: true }, (_event, file) => {
-                    const rel = file ? String(file) : '';
-                    if (!rel || !RISKY.test(rel) || SKIP.test(rel))
-                        return;
-                    pending.add(path.join(project, rel));
-                    timer ??= setTimeout(flush, 1000);
-                })];
-        }
-        catch {
-            return [];
-        }
-    });
-    return () => { watchers.forEach((w) => w.close()); clearTimeout(timer); if (pending.size)
-        flush(); };
-};
-// ---- what the watcher marks, and the size of the persisted data (host-only files next to the sync state) ----------
-const marksFile = (storageRoot, dataPath) => path.join(storageRoot, 'sync', path.basename(dataPath) + '-mark.json');
-const sizeFile = (storageRoot, dataPath) => path.join(storageRoot, 'sync', path.basename(dataPath) + '-size.json');
-/** The projects to watch and mark (empty: storage.markSandboxFiles is off). */
-export const saveMarkedProjects = (storageRoot, dataPath, projects) => writeJsonAtomic(marksFile(storageRoot, dataPath), projects);
-export const readMarkedProjects = (storageRoot, dataPath) => readValid(z.array(z.string().max(1024)).max(64), marksFile(storageRoot, dataPath)) ?? [];
-/** The data folder's size, measured by the watcher when a sandbox closes (measuring at launch would be slow). */
-export const saveDataSize = (storageRoot, dataPath, bytes) => writeJsonAtomic(sizeFile(storageRoot, dataPath), { bytes, at: new Date().toISOString() });
-export const readDataSize = (storageRoot, dataPath) => readValid(z.object({ bytes: z.number().min(0), at: z.string().max(40) }), sizeFile(storageRoot, dataPath));

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

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

package/dist/host/personalize.d.ts

@@ -1,10 +0,0 @@
-export interface RegValue {
-    key: string;
-    name: string;
-    kind: string;
-    value: string | number | string[];
-}
-/** Formats captured values as a .reg file (UTF-16 friendly text; written as UTF-16LE with BOM). */
-export declare const toRegFile: (values: RegValue[]) => string;
-/** Writes personalize.reg (+ the wallpaper image) into `<launch>\personalize`. Returns a short summary. */
-export declare const capturePersonalization: (launchPath: string) => string;

package/dist/host/personalize.js

@@ -1,97 +0,0 @@
-// Captures the look of this desktop (theme, accent colour, taskbar, Explorer options, wallpaper, mouse/keyboard,
-// regional formats) from HKCU as a .reg file the sandbox imports at logon. Only an allow-list of values is read.
-import fs from 'node:fs';
-import path from 'node:path';
-import { ensureDir, errMsg, fileExists, isWin, runPowerShell } from '../core/util.js';
-const VALUES = {
-    'Software\\Microsoft\\Windows\\CurrentVersion\\Themes\\Personalize': ['AppsUseLightTheme', 'SystemUsesLightTheme', 'EnableTransparency', 'ColorPrevalence'],
-    'Software\\Microsoft\\Windows\\DWM': ['AccentColor', 'AccentColorInactive', 'ColorizationColor', 'ColorizationAfterglow', 'ColorizationColorBalance', 'ColorPrevalence', 'EnableWindowColorization'],
-    'Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\Accent': ['AccentPalette', 'AccentColorMenu', 'StartColorMenu'],
-    'Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\Advanced': ['TaskbarAl', 'TaskbarSi', 'TaskbarDa', 'TaskbarMn', 'TaskbarGlomLevel', 'ShowTaskViewButton', 'Hidden', 'HideFileExt', 'ShowSuperHidden', 'LaunchTo', 'NavPaneExpandToCurrentFolder', 'NavPaneShowAllFolders', 'ShowCopilotButton', 'Start_TrackDocs', 'Start_Layout'],
-    'Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\StuckRects3': ['Settings'],
-    'Software\\Microsoft\\Windows\\CurrentVersion\\Search': ['SearchboxTaskbarMode'],
-    'Control Panel\\Desktop': ['WallpaperStyle', 'TileWallpaper', 'MenuShowDelay', 'CursorBlinkRate', 'DragFullWindows', 'FontSmoothing', 'FontSmoothingType', 'UserPreferencesMask'],
-    'Control Panel\\Colors': ['Background', 'Hilight', 'HotTrackingColor'],
-    'Control Panel\\Mouse': ['MouseSpeed', 'MouseSensitivity', 'MouseThreshold1', 'MouseThreshold2', 'DoubleClickSpeed', 'SwapMouseButtons'],
-    'Control Panel\\Keyboard': ['KeyboardDelay', 'KeyboardSpeed'],
-    'Control Panel\\International': ['sShortDate', 'sLongDate', 'sShortTime', 'sTimeFormat', 'iFirstDayOfWeek', 'sDecimal', 'sThousand', 'sList', 'iMeasure', 'iTime', 'iTLZero'],
-    'Control Panel\\Accessibility\\StickyKeys': ['Flags'],
-};
-const toHex = (bytes) => [...bytes].map((b) => b.toString(16).padStart(2, '0')).join(',');
-const regString = (s) => '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
-/** Formats captured values as a .reg file (UTF-16 friendly text; written as UTF-16LE with BOM). */
-export const toRegFile = (values) => {
-    const byKey = new Map();
-    for (const v of values)
-        byKey.set(v.key, [...(byKey.get(v.key) ?? []), v]);
-    const lines = ['Windows Registry Editor Version 5.00', ''];
-    for (const [key, list] of byKey) {
-        lines.push('[HKEY_CURRENT_USER\\' + key + ']');
-        for (const v of list) {
-            const name = regString(v.name);
-            switch (v.kind) {
-                case 'DWord':
-                    lines.push(name + '=dword:' + (Number(v.value) >>> 0).toString(16).padStart(8, '0'));
-                    break;
-                case 'QWord':
-                    lines.push(name + '=hex(b):' + toHex(Buffer.from(BigInt.asUintN(64, BigInt(v.value)).toString(16).padStart(16, '0'), 'hex').reverse()));
-                    break;
-                case 'Binary':
-                    lines.push(name + '=hex:' + toHex(Buffer.from(String(v.value), 'base64')));
-                    break;
-                case 'ExpandString':
-                    lines.push(name + '=hex(2):' + toHex(Buffer.from(String(v.value) + '\0', 'utf16le')));
-                    break;
-                case 'MultiString':
-                    lines.push(name + '=hex(7):' + toHex(Buffer.from(v.value.join('\0') + '\0\0', 'utf16le')));
-                    break;
-                default: lines.push(name + '=' + regString(String(v.value)));
-            }
-        }
-        lines.push('');
-    }
-    return lines.join('\r\n');
-};
-const CAPTURE_SCRIPT = (spec) => [
-    '$ErrorActionPreference = "SilentlyContinue"',
-    '$spec = \'' + JSON.stringify(spec).replace(/'/g, "''") + '\' | ConvertFrom-Json',
-    '$out = @()',
-    'foreach ($p in $spec.PSObject.Properties) {',
-    '  $key = Get-Item -LiteralPath ("HKCU:\\" + $p.Name)',
-    '  if (-not $key) { continue }',
-    '  foreach ($name in $p.Value) {',
-    '    $raw = $key.GetValue($name, $null, "DoNotExpandEnvironmentNames")',
-    '    if ($null -eq $raw) { continue }',
-    '    $kind = $key.GetValueKind($name).ToString()',
-    '    if ($kind -eq "Binary") { $raw = [Convert]::ToBase64String([byte[]]$raw) }',
-    '    $out += [pscustomobject]@{ key = $p.Name; name = $name; kind = $kind; value = $raw }',
-    '  }',
-    '}',
-    '$wall = (Get-ItemProperty -LiteralPath "HKCU:\\Control Panel\\Desktop").WallPaper',
-    '[pscustomobject]@{ values = $out; wallpaper = $wall } | ConvertTo-Json -Depth 5 -Compress',
-].join('\n');
-/** Writes personalize.reg (+ the wallpaper image) into `<launch>\personalize`. Returns a short summary. */
-export const capturePersonalization = (launchPath) => {
-    if (!isWin)
-        return 'skipped (not Windows)';
-    try {
-        const { status, stdout } = runPowerShell(CAPTURE_SCRIPT(VALUES), true);
-        if (status !== 0)
-            return 'skipped (registry read failed)';
-        // runPowerShell has PowerShell write UTF-8 (non-ASCII date formats and wallpaper paths survive); a BOM is tolerated.
-        const parsed = JSON.parse(stdout.replace(/^/, '').trim());
-        const values = parsed.values === null ? [] : Array.isArray(parsed.values) ? parsed.values : [parsed.values];
-        const dir = path.join(launchPath, 'personalize');
-        ensureDir(dir);
-        fs.writeFileSync(path.join(dir, 'personalize.reg'), '' + toRegFile(values), 'utf16le');
-        const wallpaper = parsed.wallpaper ?? '';
-        const themesCopy = path.join(process.env.APPDATA ?? '', 'Microsoft', 'Windows', 'Themes', 'TranscodedWallpaper');
-        const source = fileExists(wallpaper) ? wallpaper : fileExists(themesCopy) ? themesCopy : null;
-        if (source)
-            fs.copyFileSync(source, path.join(dir, 'wallpaper' + (path.extname(source) || '.jpg')));
-        return values.length + ' settings' + (source ? ' + wallpaper' : '');
-    }
-    catch (e) {
-        return 'skipped (' + errMsg(e) + ')';
-    }
-};

package/dist/host/platform.js

@@ -1,129 +0,0 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { spawn, spawnSync } from 'node:child_process';
-import { SYSTEM } from '../shared/system.js';
-import { refuseInSelfTest } from './test-guard.js';
-import { updateRestartPending } from './stops.js';
-import { commandsDir, realAgent } from './agent-commands.js';
-import { dirExists, ensureDir, fail, fileExists, findOnPath, homeDir, isWin, realPath } from '../core/util.js';
-const findHarnessExe = (config, harnessName) => {
-    const harness = config.harnesses[harnessName];
-    if (!harness?.hostExecutable)
-        return null;
-    const explicit = harness.hostDir && harness.hostDir !== 'auto' ? path.join(harness.hostDir, harness.hostExecutable) : null;
-    const found = explicit
-        ? (fileExists(explicit) ? explicit : null)
-        : findOnPath([harness.hostExecutable]) ?? [path.join(homeDir(), '.local', 'bin', harness.hostExecutable)].find(fileExists) ?? null;
-    if (!found)
-        return null;
-    const real = realPath(found);
-    return { dir: path.dirname(real), file: path.basename(real) };
-};
-/** Git for Windows root (the folder with cmd\git.exe and bin\bash.exe), from git on PATH. */
-const findGitRoot = () => {
-    const git = findOnPath(['git.exe']);
-    if (!git)
-        return null;
-    const root = path.resolve(path.dirname(realPath(git)), '..');
-    return fileExists(path.join(root, 'bin', 'bash.exe')) ? root : null;
-};
-/** What can be copied from this PC instead of downloaded inside the sandbox. */
-export const probeHost = (config, harnessName) => {
-    const nodeDir = isWin ? path.dirname(process.execPath) : null;
-    const copy = config.provisioning.copyFromHost;
-    const nvmHome = process.env.NVM_HOME;
-    const nvmDir = copy && nvmHome && dirExists(nvmHome) ? realPath(nvmHome) : null;
-    const hasNode = (dir) => fileExists(path.join(dir, 'node.exe')) && fileExists(path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js'));
-    // One source for Node: nvm's copy of this version when there is one, otherwise the Node folder itself.
-    const nvmNode = Boolean(nvmDir && hasNode(path.join(nvmDir, process.version)));
-    return {
-        nodeDir: copy && !nvmNode && nodeDir && hasNode(nodeDir) ? realPath(nodeDir) : null,
-        harnessExe: copy ? findHarnessExe(config, harnessName) : null,
-        gitDir: copy && config.provisioning.git.enabled ? findGitRoot() : null,
-        nvmDir,
-        hostNodeVersion: process.version,
-        nvmNode,
-        volta: Boolean(process.env.VOLTA_HOME),
-        pyenv: Boolean(process.env.PYENV ?? process.env.PYENV_ROOT ?? process.env.PYENV_HOME),
-    };
-};
-const SANDBOX_PROCESSES = ['WindowsSandboxClient.exe', 'WindowsSandboxRemoteSession.exe', 'WindowsSandbox.exe'];
-/**
- * Running INSIDE a Windows Sandbox this tool started (its launch folder and data folder are mapped in): then the CLI
- * talks to the sandbox it is in, through C:\\AgentData and loopback, instead of looking for one on a PC.
- */
-export const insideSandbox = () => isWin && !process.env.AGENT_SANDBOX_HOST_ONLY && fs.existsSync('C:\\AgentLaunch\\session.json') && fs.existsSync('C:\\AgentData\\run');
-export const GUEST_DATA_DIR = 'C:\\AgentData';
-export const isSandboxRunning = () => {
-    if (!isWin)
-        return false;
-    if (insideSandbox())
-        return true;
-    const result = spawnSync(SYSTEM.tasklist(), ['/NH', '/FO', 'CSV'], { encoding: 'utf8', windowsHide: true });
-    const out = (result.stdout ?? '').toLowerCase();
-    return SANDBOX_PROCESSES.some((image) => out.includes('"' + image.toLowerCase() + '"'));
-};
-export const sandboxFeatureInstalled = () => isWin && fileExists(path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32', 'WindowsSandbox.exe'));
-export const assertCanLaunch = () => {
-    if (!isWin)
-        fail('Windows Sandbox only runs on Windows.', 'Use sandbox generate to only write the files.');
-    if (!sandboxFeatureInstalled())
-        fail('Windows Sandbox is not enabled on this PC.', 'Run in an admin PowerShell, then reboot: Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All  (needs Windows Pro, Enterprise or Education)');
-    if (isSandboxRunning())
-        fail('A Windows Sandbox is already running (Windows allows one at a time).', 'Attach to it with sandbox claude -t, show it with sbx-show, or shut it down with sandbox stop.');
-};
-/** cmd.exe expands %VAR% and ^ even inside quotes, and a quote ends them: such a path could run something else. */
-export const assertCmdSafePath = (file) => {
-    if (/[%"^\r\n]/.test(file))
-        fail('The storage folder path has a character that cannot be started safely: ' + file, 'Set storage.root to a folder without % " ^ in its path.');
-};
-export const startSandbox = (wsbPath) => {
-    refuseInSelfTest('start Windows Sandbox');
-    assertCmdSafePath(wsbPath);
-    const result = spawnSync(SYSTEM.cmd(), ['/d', '/c', 'start', '""', '"' + wsbPath + '"'], { stdio: 'inherit', windowsVerbatimArguments: true });
-    if (result.error)
-        throw result.error;
-};
-/** Runs a detached copy of this CLI (used for the background history/claude-mem sync watcher). */
-export const spawnDetached = (entry, args) => {
-    refuseInSelfTest('start background programs');
-    // cwd = the install folder: the caller's folder is the workspace, which the sandbox can write.
-    spawn(process.execPath, [entry, ...args], { cwd: path.dirname(entry), detached: true, stdio: 'ignore', windowsHide: true }).unref();
-};
-export const hostClaude = (storageRoot, personal, args) => {
-    refuseInSelfTest('run Claude Code on this PC');
-    // Never this tool's own forwarding command (agentCommands), which would start a sandbox instead.
-    const exe = realAgent('claude', commandsDir(storageRoot));
-    if (!exe)
-        fail('Claude Code is not installed on this PC (no claude.exe or claude.cmd on PATH).', 'Install it: npm install -g @anthropic-ai/claude-code');
-    const env = { ...process.env };
-    if (!personal) {
-        const profile = path.join(storageRoot, 'host', 'claude');
-        ensureDir(profile);
-        env.CLAUDE_CONFIG_DIR = profile;
-        console.warn('Host Claude is NOT sandboxed. Using separate profile: ' + profile + ' (pass --personal to use your normal one).');
-    }
-    const result = exe.toLowerCase().endsWith('.cmd') ? spawnSync(SYSTEM.cmd(), ['/d', '/c', exe, ...args], { stdio: 'inherit', env }) : spawnSync(exe, args, { stdio: 'inherit', env });
-    if (result.error)
-        throw result.error;
-    return result.status ?? 1;
-};
-export const doctorRows = (config, harnessName, storageRoot, configPath) => {
-    const probe = probeHost(config, harnessName);
-    return [
-        ['Config file', configPath ?? '(none; built-in defaults; create one with: sandbox config init)'],
-        ['Windows', isWin ? 'yes' : 'NO (launch needs Windows)'],
-        ['Windows Sandbox feature', sandboxFeatureInstalled() ? 'enabled' : 'NOT enabled'],
-        ['Sandbox running', isSandboxRunning() ? 'YES' : 'no'],
-        ['Free host RAM (MB)', String(Math.floor(os.freemem() / 1048576))],
-        ['Update restart pending', updateRestartPending() ? 'YES (Windows may restart on its own and close the sandbox; restart first or pause updates)' : 'no'],
-        ['Keep this PC awake', config.sandbox.keepAwake ? 'yes, while a sandbox runs' : 'no (sandbox.keepAwake is off: the PC may sleep under running agents)'],
-        ['Provisioning', config.provisioning.copyFromHost ? 'copy from this PC' + (config.provisioning.fallbackToInstall ? ', fall back to download' : ', no fallback') : 'download inside sandbox'],
-        ['Host Node (runner)', probe.nvmNode ? 'nvm ' + probe.hostNodeVersion : probe.nodeDir ?? '(none; will download)'],
-        ['Host nvm versions', probe.nvmDir ?? '(no NVM_HOME; versions will be downloaded)'],
-        ['Host ' + harnessName, probe.harnessExe ? path.join(probe.harnessExe.dir, probe.harnessExe.file) : '(none; will npm install)'],
-        ['Host Git for Windows', probe.gitDir ?? '(none with bash; PortableGit will be downloaded)'],
-        ['Storage root', storageRoot + (dirExists(storageRoot) ? '' : ' (will be created)')],
-    ];
-};

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

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

package/dist/host/projects.d.ts

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