windows-development-sandbox 0.0.0-stage → 1.0.5

package/dist/selftest/harness.d.ts

@@ -0,0 +1,14 @@
+export interface Harness {
+    packageRoot: string;
+    temp: string;
+    check: (ok: boolean, name: string) => void;
+    rejects: (fn: () => unknown, needle: string) => Promise<boolean>;
+    write: (file: string, content: string) => string;
+    /** Polls `read` until it returns something truthy (or the timeout passes). */
+    waitFor: <T>(read: () => T | null | undefined | false | Promise<T | null | undefined | false>, ms?: number) => Promise<T | null>;
+    section: (title: string) => void;
+}
+export declare const createHarness: (packageRoot: string) => Harness & {
+    failures: () => number;
+    dispose: () => void;
+};

package/dist/selftest/harness.js

@@ -0,0 +1,36 @@
+// Minimal test harness: PASS/FAIL lines, a temp folder that is always removed, small helpers.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { ensureDir, errMsg, sleep } from '../core/util.js';
+export const createHarness = (packageRoot) => {
+    let failures = 0;
+    const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-sandbox-test-'));
+    return {
+        packageRoot,
+        temp,
+        failures: () => failures,
+        check: (ok, name) => { console.log((ok ? '\x1b[32mPASS\x1b[0m  ' : '\x1b[31mFAIL\x1b[0m  ') + name); if (!ok)
+            failures++; },
+        rejects: async (fn, needle) => { try {
+            await fn();
+            return false;
+        }
+        catch (e) {
+            return (errMsg(e) + ' ' + (e.fix ?? '')).includes(needle);
+        } },
+        write: (file, content) => { ensureDir(path.dirname(file)); fs.writeFileSync(file, content); return file; },
+        waitFor: async (read, ms = 30000) => {
+            const end = Date.now() + ms;
+            while (Date.now() < end) {
+                const v = await read();
+                if (v)
+                    return v;
+                await sleep(250);
+            }
+            return null;
+        },
+        section: (title) => console.log('\n\x1b[36m-- ' + title + '\x1b[0m'),
+        dispose: () => fs.rmSync(temp, { recursive: true, force: true, maxRetries: 5, retryDelay: 300 }),
+    };
+};

package/dist/selftest/helpers.test.d.ts

@@ -0,0 +1,2 @@
+import type { Harness } from './harness.js';
+export declare const helperTests: (t: Harness) => void;

package/dist/selftest/helpers.test.js

@@ -0,0 +1,125 @@
+// Small pure helpers: version picking, .reg generation, firewall maths, storage cleanup.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import { pruneStorage } from '../host/cleanup.js';
+import { toRegFile } from '../host/personalize.js';
+import { javaMajorFrom, pickGoRelease, pickNodeVersion, pickPackageVersion, pickSpreadVersions, projectUses, specFromVersionFile } from '../guest/toolchains/versions.js';
+import { parseReleaseTags } from '../shared/download.js';
+import { buildFirewallCommands, cidrToRange, ipv4DnsServers, parseDefaultGateways, parseDnsServers, subtractIps } from '../shared/netrules.js';
+import { ensureDir, isWin } from '../core/util.js';
+import { decidePwsh, pcHasPwsh, PWSH_MAX_BYTES, readPwshScripts, usesPwsh } from '../core/detect-pwsh.js';
+import { binstallAsset, CLI_TOOLS, decideCli, pwshAsset } from '../guest/toolchains/catalogue.js';
+import { PWSH_PROFILE_GUID, syncPwshProfile, withPwshProfile } from '../host/terminal.js';
+export const helperTests = (t) => {
+    const { check, write } = t;
+    t.section('versions, registry, firewall');
+    const releases = [{ version: 'v23.1.0', lts: false }, { version: 'v22.11.0', lts: 'Jod' }, { version: 'v20.18.0', lts: 'Iron' }, { version: 'v20.9.0', lts: 'Iron' }];
+    check(pickNodeVersion(releases, 'lts/*') === '22.11.0' && pickNodeVersion(releases, 'lts/iron') === '20.18.0' && pickNodeVersion(releases, '20') === '20.18.0' && pickNodeVersion(releases, 'v20.9.0') === '20.9.0' && pickNodeVersion(releases, 'node') === '23.1.0' && pickNodeVersion(releases, '99') === null, '.nvmrc specs resolve (lts/*, lts/<name>, major, exact, node)');
+    const spread = pickSpreadVersions(['16.20.2', '18.19.0', '18.20.4', '20.18.0', '22.3.0', '22.11.0', '23.1.0', 'notes'], '22.11.0', 3);
+    check(JSON.stringify(spread) === '["22.11.0","16.20.2","23.1.0"]' && pickSpreadVersions(['20.18.0'], '22.3.0', 3).join() === '22.3.0,20.18.0' && pickSpreadVersions(['18.20.4', '20.18.0'], '22.3.0', 1).join() === '22.3.0', 'host nvm versions: capped, current first, rest spread across other majors');
+    const go = [{ version: 'go1.24rc1', stable: false, files: [] }, { version: 'go1.23.2', stable: true, files: [] }, { version: 'go1.23.1', stable: true, files: [] }, { version: 'go1.22.8', stable: true, files: [] }];
+    check(pickGoRelease(go, 'stable')?.version === 'go1.23.2' && pickGoRelease(go, '1.22')?.version === 'go1.22.8' && pickGoRelease(go, 'go1.23.1')?.version === 'go1.23.1' && pickGoRelease(go, '1.30') === null, 'Go versions resolve (stable, minor prefix, exact; release candidates skipped)');
+    check(javaMajorFrom('21\n') === '21' && javaMajorFrom('17.0.9') === '17' && javaMajorFrom('1.8') === '8' && javaMajorFrom('temurin-21.0.2') === '21' && javaMajorFrom('# sdkman\njava=21.0.2-tem\n', true) === '21' && specFromVersionFile('ruby-3.3.1\n') === '3.3.1', 'version files: .java-version, .sdkmanrc, .ruby-version');
+    check(projectUses(['README.md', 'server/go.mod'], ['go.mod']) && projectUses(['App.csproj'], ['*.csproj']) && !projectUses(['notes.txt', 'docs/readme.md'], ['go.mod', '*.csproj']), 'enabled "auto": a language is used when its marker file is in the workspace or one folder down');
+    check(pickPackageVersion(['3.9.13', '3.12.7', '3.12.10', '3.13.0-rc1', '3.13.1'], '3') === '3.13.1' && pickPackageVersion(['3.12.7', '3.12.10'], '3.12') === '3.12.10' && pickPackageVersion(['2.7.18'], '2.7') === '2.7.18', 'Python versions resolve to the newest stable match');
+    const reg = toRegFile([{ key: 'Control Panel\\Desktop', name: 'WallpaperStyle', kind: 'String', value: '10' }, { key: 'X', name: 'D', kind: 'DWord', value: 4294967295 }, { key: 'X', name: 'B', kind: 'Binary', value: Buffer.from([1, 255]).toString('base64') }]);
+    check(reg.includes('[HKEY_CURRENT_USER\\Control Panel\\Desktop]') && reg.includes('"WallpaperStyle"="10"') && reg.includes('"D"=dword:ffffffff') && reg.includes('"B"=hex:01,ff'), 'personalisation: registry values become a valid .reg file (HKCU only)');
+    const [s172, e172] = cidrToRange('172.16.0.0/12');
+    const gw = 172 * 16777216 + 28 * 65536 + 1;
+    check(subtractIps([[s172, e172]], ['172.28.0.1']).every(([s, e]) => gw < s || gw > e) && !buildFirewallCommands(['8.8.8.8']).join().includes('8.8.8.8'), 'firewall maths: private block minus the gateway; public addresses ignored');
+    check(parseDefaultGateways('  0.0.0.0          0.0.0.0     172.28.80.1   172.28.85.200     5\n').join() === '172.28.80.1' && parseDnsServers('   DNS Servers . . . : 172.28.80.1\n                       8.8.8.8\n   NetBIOS : x\n').join() === '172.28.80.1,8.8.8.8', 'parses gateway and DNS servers');
+    check(ipv4DnsServers(['172.28.80.1', '8.8.8.8:1053', '[::1]:53', 'fe80::1']).join() === '172.28.80.1,8.8.8.8', 'DNS servers from the resolver (any Windows language): IPv4 only, ports dropped');
+    check(parseReleaseTags('<a href="/coreybutler/nvm-windows/releases/tag/1.2.2">x</a><a href="/coreybutler/nvm-windows/releases/tag/1.2.2">y</a><a href="/other/repo/releases/tag/9">z</a><a href="/coreybutler/nvm-windows/releases/tag/1.1.12">w</a>', 'coreybutler/nvm-windows').join() === '1.2.2,1.1.12', 'GitHub release list page: this repo\'s tags in order, once each');
+    t.section('cmd quoting (npm agents)');
+    // ptyhost.ts loads env.ts, which reads session.json: import it in a child with a throwaway launch/data folder.
+    const quoteDir = path.join(t.temp, 'quote');
+    write(path.join(quoteDir, 'launch', 'session.json'), '{}');
+    const agentCmd = write(path.join(quoteDir, 'agent.cmd'), '@"' + process.execPath + '" -e "console.log(JSON.stringify(process.argv.slice(1)))" %*\r\n');
+    // Odd quote counts flip cmd's quote state for every later argument: those come after them on purpose.
+    const tricky = ['https://x?a=1&b=2', '50% off', 'a|b<c>d', 'x^y', 'say "hi" & go', 'plain', '%PATH%', 'a"b&c', 'q"x|y^z"w', 'e"5%', 'k&v', '100%'];
+    const probe = spawnSync(process.execPath, ['--input-type=module', '-e', [
+            'const m = await import(process.argv[1]); const [cmd, tricky] = JSON.parse(process.argv[2]);',
+            'console.log(JSON.stringify({ normal: m.commandLine("C:\\\\W\\\\cmd.exe", ["/d", "/c", "C:\\\\a\\\\agent.cmd", "--model", "big one", "plain", ""]), direct: m.commandLine("C:\\\\a\\\\agent.exe", ["a&b", "50%"]),',
+            '  url: m.cmdArgs(["https://x?a=1&b=2"]), pct: m.cmdArgs(["50%"]), live: m.commandLine("cmd.exe", ["/d", "/c", cmd, ...tricky]).slice(8) }));',
+        ].join('\n'), pathToFileURL(path.join(t.packageRoot, 'dist', 'guest', 'ptyhost.js')).href, JSON.stringify([agentCmd, tricky])], {
+        encoding: 'utf8', env: { ...process.env, AGENT_LAUNCH_DIR: path.join(quoteDir, 'launch'), AGENT_DATA_DIR: path.join(quoteDir, 'data') },
+    });
+    const quoting = (() => { try {
+        return JSON.parse(probe.stdout);
+    }
+    catch {
+        return {};
+    } })();
+    check(quoting.normal === 'C:\\W\\cmd.exe /d /c C:\\a\\agent.cmd --model "big one" plain ""' && quoting.direct === 'C:\\a\\agent.exe a&b 50%', 'command lines: ordinary arguments quoted as before; a program started directly gets & and % unchanged' + (quoting.normal ? '' : ' (' + (probe.stderr || probe.stdout).trim().slice(0, 300) + ')'));
+    check(quoting.url === '"https://x?a=1&b=2"' && quoting.pct === '"50"%""', 'cmd /c arguments: & | < > ^ quoted, % split out so no %name% expands');
+    // (Agents live under C:\AgentData\tools; a temp folder with spaces would also need cmd's quote rules, so skip there.)
+    if (isWin && quoting.live && !/\s/.test(agentCmd)) {
+        const echoed = spawnSync(process.env.ComSpec ?? 'cmd.exe', [quoting.live], { encoding: 'utf8', windowsVerbatimArguments: true, windowsHide: true });
+        check(echoed.stdout.trim() === JSON.stringify(tricky), 'cmd /d /c <agent>.cmd passes &, |, <, >, ^, % and quotes through to the agent unchanged (got ' + echoed.stdout.trim() + ')');
+    }
+    t.section('cleanup');
+    const store = path.join(t.temp, 'prune');
+    const aged = (p, days) => { const d = new Date(Date.now() - days * 86400000); fs.utimesSync(p, d, d); };
+    for (const [name, days] of [['old', 9], ['kept', 30], ['new', 1]]) {
+        aged(write(path.join(store, 'launches', name, 'agent.wsb'), 'x'), days);
+        aged(path.join(store, 'launches', name), days);
+    }
+    aged(write(path.join(store, 'data', 'd', 'logs', 'guest-old.log'), 'x'), 20);
+    write(path.join(store, 'data', 'd', 'logs', 'guest-new.log'), 'x');
+    ensureDir(path.join(store, 'data', 'd', 'tools', 'git.staging-ab12'));
+    aged(path.join(store, 'data', 'd', 'tools', 'git.staging-ab12'), 2);
+    ensureDir(path.join(store, 'data', 'd', 'tools', 'node'));
+    const pruned = pruneStorage(store, { keep: ['kept'] });
+    const left = (p) => fs.existsSync(path.join(store, p));
+    check(pruned.launches === 1 && !left('launches/old') && left('launches/kept') && left('launches/new') && !left('data/d/logs/guest-old.log') && left('data/d/logs/guest-new.log') && !left('data/d/tools/git.staging-ab12') && left('data/d/tools/node'), 'cleanup: launches > 7 days, logs > 14 days and interrupted downloads go; the running launch and real tools stay');
+    t.section('PowerShell 7, CLI catalogue, cargo-binstall');
+    const pwshNames = ['PowerShell-7.6.6-win-x64.zip', 'PowerShell-7.6.6-win-arm64.zip', 'PowerShell-7.6.6-win-x64.msi', 'PowerShell-7.6.6-win-fxdependent.zip', 'PowerShell-7.6.6-win-x86.zip', 'PowerShell-7.6.6-win-x64.zip.sha256'];
+    check(pwshNames.filter((n) => pwshAsset('x64').test(n)).join() === 'PowerShell-7.6.6-win-x64.zip' && pwshNames.filter((n) => pwshAsset('arm64').test(n)).join() === 'PowerShell-7.6.6-win-arm64.zip', 'PowerShell 7: the portable zip for the architecture (no MSI, fxdependent or x86 build)');
+    const binstallNames = ['cargo-binstall-x86_64-pc-windows-msvc.zip', 'cargo-binstall-x86_64-pc-windows-msvc.full.zip', 'cargo-binstall-x86_64-pc-windows-msvc.zip.sig', 'cargo-binstall-aarch64-pc-windows-msvc.zip', 'cargo-binstall-x86_64-unknown-linux-musl.tgz'];
+    check(binstallNames.filter((n) => binstallAsset('x64').test(n)).join() === 'cargo-binstall-x86_64-pc-windows-msvc.zip' && binstallNames.filter((n) => binstallAsset('arm64').test(n)).join() === 'cargo-binstall-aarch64-pc-windows-msvc.zip', 'cargo-binstall: the plain Windows zip for the architecture (not .full, not the signature)');
+    const cliAsset = (name, arch, names) => names.filter((n) => CLI_TOOLS.find((c) => c.name === name).asset(arch).test(n)).join();
+    const ghNames = ['gh_2.102.0_windows_amd64.zip', 'gh_2.102.0_windows_amd64.msi', 'gh_2.102.0_windows_386.zip', 'gh_2.102.0_windows_arm64.zip', 'gh_2.102.0_linux_amd64.tar.gz'];
+    const zstdNames = ['zstd-v1.5.7-win64.zip', 'zstd-v1.5.7-win32.zip', 'zstd-v1.5.7.tar.gz'];
+    check(cliAsset('gh', 'x64', ghNames) === 'gh_2.102.0_windows_amd64.zip' && cliAsset('gh', 'arm64', ghNames) === 'gh_2.102.0_windows_arm64.zip' && cliAsset('zstd', 'x64', zstdNames) === 'zstd-v1.5.7-win64.zip' && cliAsset('zstd', 'arm64', zstdNames) === 'zstd-v1.5.7-win64.zip' && CLI_TOOLS.every((c) => c.exe.endsWith('.exe')), 'CLI catalogue: gh and zstd release zips per architecture (zstd: win64 also on Arm)');
+    const cli = (settings, gitAccess, hasGithubDir = false) => Object.entries(decideCli(settings, { gitAccess, hasGithubDir })).filter(([, d]) => d.on).map(([n]) => n).join();
+    check(cli({ gh: true, zstd: true, openssl: true }, 'full') === 'gh,zstd,openssl' && cli({ gh: true, zstd: true }, 'readonly') === 'zstd' && cli({ gh: 'auto' }, 'none', true) === '' && decideCli({ gh: true }, { gitAccess: 'readonly', hasGithubDir: false }).gh.reason.includes('"full"'), 'CLI catalogue: gh only with git access "full" (it pushes through the API), whatever the config says');
+    check(cli({ gh: 'auto', zstd: 'auto', openssl: 'auto' }, 'full', true) === 'gh,openssl' && cli({ gh: 'auto', zstd: 'auto' }, 'full', false) === '' && cli({}, 'full', true) === '', 'CLI catalogue: "auto" = gh with a .github folder, openssl always (a shim), zstd only when listed; unlisted tools stay off');
+    const ps = (text, file = 'moh.ps1') => usesPwsh([{ path: file, text }]);
+    check(ps('#Requires -Version 7.2\nparam()') === 'moh.ps1: #Requires -Version 7' && ps('  #requires -PSEdition Core') !== null && ps('#Requires -Modules Pester -Version 7') !== null && ps('<#\n.SYNOPSIS\n  Usage: pwsh scripts/moh/build-openmohaa.ps1 -Release\n#>') !== null && ps('& pwsh.exe -NoProfile -File x.ps1') !== null && ps('C:\\Program Files\\PowerShell\\7\\pwsh.exe -c 1') !== null, 'pwsh markers: #Requires -Version 7+ / -PSEdition Core, and pwsh usage lines');
+    check(ps('#Requires -Version 5.1') === null && ps('#Requires -PSEdition Desktop') === null && ps('# Works in Windows PowerShell and pwsh too.') === null && ps('$pwsh -x; Write-Host mypwsh -y') === null && ps('#Requires -Version 7', 'notes.txt') === null && ps('Write-Host hi') === null, 'pwsh markers: Windows PowerShell scripts, prose, variables and non-scripts do not count');
+    const evilStart = Date.now();
+    const evilText = (' #requires' + ' -version'.repeat(5000) + '\n' + 'xpwsh pwsh\t\t'.repeat(20000) + '\n' + ' '.repeat(100000) + 'pwsh\n' + 'pwsh\n'.repeat(50000)).repeat(3);
+    const evil = usesPwsh(Array.from({ length: 100 }, (_, i) => ({ path: 'a' + i + '.ps1', text: evilText })));
+    check(evil === null && Date.now() - evilStart < 2000, 'pwsh markers: hostile scripts (huge lines, endless repeats) are capped and scanned in linear time (' + (Date.now() - evilStart) + ' ms)');
+    check(decidePwsh('auto', [], true, true).on && !decidePwsh('auto', [], false, true).on && !decidePwsh('auto', [], true, false).on && decidePwsh('auto', [{ path: 'x/run.ps1', text: '#Requires -PSEdition Core' }], false, false).reason === 'x/run.ps1: #Requires -PSEdition Core' && !decidePwsh(false, [{ path: 'a.ps1', text: '#Requires -Version 7' }], true, true).on && decidePwsh(true, [], false, false).on, 'pwsh "auto": a script that needs it, else this PC has it (new folder only); true/false win');
+    const pf = 'C:\\PF';
+    check(pcHasPwsh({ ProgramFiles: pf }, (p) => p === 'C:\\PF\\PowerShell\\7\\pwsh.exe') && pcHasPwsh({ PATH: 'C:\\x;C:\\tools\\pwsh' }, (p) => p === 'C:\\tools\\pwsh\\pwsh.exe') && !pcHasPwsh({ ProgramFiles: pf, PATH: 'C:\\Users\\u\\AppData\\Local\\Microsoft\\WindowsApps' }, (p) => /WindowsApps/.test(p)), 'pwsh on this PC: Program Files\\PowerShell\\7 or PATH, not a Store alias');
+    const psRoot = path.join(t.temp, 'pwsh-scan');
+    write(path.join(psRoot, 'moh.ps1'), '#Requires -Version 7\n');
+    write(path.join(psRoot, 'scripts', 'build.ps1'), 'x'.repeat(200000) + '\n#Requires -Version 7');
+    write(path.join(psRoot, 'node_modules', 'pkg.ps1'), '#Requires -Version 7');
+    write(path.join(psRoot, 'scripts', 'deep', 'far.ps1'), '#Requires -Version 7');
+    write(path.join(psRoot, 'readme.md'), 'pwsh -File x.ps1');
+    const scanned = readPwshScripts(psRoot);
+    check(scanned.map((f) => f.path).join() === 'moh.ps1,scripts/build.ps1' && scanned[1].text.length === PWSH_MAX_BYTES, 'pwsh scan: *.ps1 at the root and one folder down only (node_modules skipped), each read up to its cap');
+    const shown = withPwshProfile({ theme: 'dark', profiles: { defaults: { font: {} } } }, true);
+    const shownList = shown?.profiles;
+    const tweaked = { profiles: { list: [{ guid: 'other' }, { guid: PWSH_PROFILE_GUID.toUpperCase(), name: 'My pwsh', fontSize: 14 }] } };
+    const hidden = withPwshProfile(tweaked, false)?.profiles;
+    check(shownList?.list.length === 1 && shownList.list[0].guid === PWSH_PROFILE_GUID && String(shownList.list[0].commandline).includes('pwsh.exe') && Boolean(shownList.defaults) && shown?.theme === 'dark' && withPwshProfile(shown, true) === null && withPwshProfile({ profiles: { defaults: {} } }, false) === null, 'Windows Terminal: a PowerShell 7 profile is added once pwsh is installed, nothing rewritten when already there or never wanted');
+    check(hidden?.list[1].hidden === true && hidden.list[1].name === 'My pwsh' && hidden.list[1].fontSize === 14 && hidden.list.length === 2 && (withPwshProfile({ profiles: [{ guid: 'a' }] }, true)?.profiles).list.length === 2, 'Windows Terminal: turning pwsh off hides the profile, keeping the user\'s edits; the old array form of "profiles" works');
+    const wtData = path.join(t.temp, 'wt-data');
+    const wtSettings = write(path.join(wtData, 'tools', 'terminal', 'settings', 'settings.json'), '// edited in the sandbox\n{ "theme": "light", "profiles": { "list": [{ "guid": "{x}", }] } }');
+    syncPwshProfile(wtData, true);
+    const before = fs.readFileSync(wtSettings, 'utf8');
+    write(path.join(wtData, 'tools', 'pwsh', 'pwsh.exe'), 'MZ');
+    syncPwshProfile(wtData, true);
+    const after = JSON.parse(fs.readFileSync(wtSettings, 'utf8'));
+    syncPwshProfile(wtData, false);
+    const off = JSON.parse(fs.readFileSync(wtSettings, 'utf8'));
+    write(path.join(wtData, 'tools', 'terminal', 'settings', 'settings.json'), '{ not json');
+    syncPwshProfile(wtData, true);
+    check(before.startsWith('// edited') && after.theme === 'light' && after.profiles.list.map((p) => p.guid).join() === '{x},' + PWSH_PROFILE_GUID && off.profiles.list[1].hidden === true && fs.readFileSync(wtSettings, 'utf8') === '{ not json', 'Windows Terminal settings.json (JSONC): untouched until pwsh is installed, then the profile is added, hidden when off; an unreadable file is left alone');
+};

package/dist/selftest/host.test.d.ts

@@ -0,0 +1,2 @@
+import type { Harness } from './harness.js';
+export declare const hostTests: (t: Harness) => void;

package/dist/selftest/host.test.js

@@ -0,0 +1,71 @@
+// Runs every command and shortcut binary as a separate process in a simulated HOST: none of the sandbox-only folders
+// or variables exist (C:\AgentLaunch, C:\AgentData, CLAUDE_CONFIG_DIR, ...), with a fresh home and storage. Tests
+// usually run inside a sandbox, where those exist, so this is what catches code that only works there. Every command
+// must either succeed or fail with a friendly "Error:" message; a crash or stack trace fails.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { ensureDir } from '../core/util.js';
+const SANDBOX_ONLY_VARS = ['CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'GEMINI_CLI_HOME', 'AGENT_WORKSPACE', 'AGENT_DATA', 'AGENT_TOOLS', 'AGENT_PROJECT', 'NVM_HOME', 'NVM_SYMLINK', 'BASH_ENV', 'CLAUDE_CODE_GIT_BASH_PATH', 'AGENT_GIT_ACCESS', 'AGENT_REAL_GIT', 'AGENT_SANDBOX_CONFIG'];
+export const hostTests = (t) => {
+    t.section('simulated host: every command, outside a sandbox');
+    const home = path.join(t.temp, 'host-sim-home');
+    const project = path.join(t.temp, 'host-sim-project');
+    const storage = path.join(t.temp, 'host-sim-storage');
+    for (const dir of [home, project, storage])
+        ensureDir(dir);
+    const config = t.write(path.join(t.temp, 'host-sim-config.json'), JSON.stringify({ storage: { root: storage }, personalization: { enabled: false }, provisioning: { terminal: { enabled: false } } }));
+    const env = {
+        ...Object.fromEntries(Object.entries(process.env).filter(([k]) => !SANDBOX_ONLY_VARS.includes(k))),
+        AGENT_SANDBOX_HOME: home,
+        AGENT_LAUNCH_DIR: path.join(t.temp, 'no-agent-launch'),
+        AGENT_DATA_DIR: path.join(t.temp, 'no-agent-data'),
+        AGENT_HOST_TOOLS_DIR: path.join(t.temp, 'no-host-tools'),
+        NO_COLOR: '1',
+        // This test may itself run inside a sandbox: the CLI must behave as it would on a PC.
+        AGENT_SANDBOX_HOST_ONLY: '1',
+    };
+    const bin = (name) => path.join(t.packageRoot, 'dist', 'bin', name + '.js');
+    const runs = [
+        ['agent-sandbox', '--help', ['--help']],
+        ['agent-sandbox', 'status', ['status', '--config', config]],
+        ['agent-sandbox', 'status --json', ['status', '--json', '--config', config]],
+        ['agent-sandbox', 'sessions', ['sessions', '--config', config]],
+        ['agent-sandbox', 'doctor', ['doctor', '--config', config]],
+        ['agent-sandbox', 'account list', ['account', 'list', '--config', config]],
+        ['agent-sandbox', 'account use nobody', ['account', 'use', 'nobody', '--config', config]],
+        ['agent-sandbox', 'config path', ['config', 'path']],
+        ['agent-sandbox', 'config show', ['config', 'show', '--config', config]],
+        ['agent-sandbox', 'config schema', ['config', 'schema']],
+        ['agent-sandbox', 'config init', ['config', 'init']],
+        ['agent-sandbox', 'config init (again)', ['config', 'init']],
+        ['agent-sandbox', 'clean', ['clean', '--config', config]],
+        ['agent-sandbox', 'sync', ['sync', '--config', config]],
+        ['agent-sandbox', 'logs', ['logs', '--config', config]],
+        ['agent-sandbox', 'attach', ['attach', '--config', config]],
+        ['agent-sandbox', 'exec', ['exec', '--config', config, '--', 'echo', 'hi']],
+        ['agent-sandbox', 'restart', ['restart', '--config', config]],
+        ['agent-sandbox', 'stop', ['stop', '--config', config]],
+        ['agent-sandbox', 'show', ['show', '--config', config]],
+        ['agent-sandbox', 'hide', ['hide', '--config', config]],
+        ['agent-sandbox', 'generate', ['generate', '--config', config]],
+        ['agent-sandbox', 'launch', ['launch', '--config', config]],
+        ['agent-sandbox', 'unknown command', ['frobnicate']],
+        ['claude-sbx', 'claude-sbx --headless --continue', ['--headless', '--continue', '--config', config]],
+        ['codex-sbx', 'codex-sbx', ['--config', config]],
+        ['gemini-sbx', 'gemini-sbx', ['--config', config]],
+        ['sbx-show', 'sbx-show', ['--config', config]],
+        ['claude-host', 'claude-host --version', ['--version']],
+    ];
+    const broken = [];
+    for (const [name, label, args] of runs) {
+        const r = spawnSync(process.execPath, [bin(name), ...args], { cwd: project, env, encoding: 'utf8', timeout: 120000 });
+        const output = ((r.stdout ?? '') + (r.stderr ?? '')).replace(/\x1b\[[0-9;]*m/g, '');
+        const crashed = r.status === null || r.status > 1 || /Unexpected error|node:internal|^\s+at .+:\d+:\d+\)?$/m.test(output);
+        const unexplained = r.status === 1 && !/(^|\n)(Error: |error: )/.test(output) && name !== 'claude-host';
+        if (crashed || unexplained)
+            broken.push(label + ' (exit ' + r.status + '): ' + output.trim().split('\n').slice(0, 4).join(' | '));
+    }
+    t.check(broken.length === 0, 'all ' + runs.length + ' commands work or fail with a clear message when run outside a sandbox' + (broken.length ? ':\n    ' + broken.join('\n    ') : ''));
+    t.check(fs.existsSync(path.join(home, 'config.json')) && fs.existsSync(path.join(home, 'config.schema.json')) && fs.existsSync(path.join(home, 'sandbox-config.schema.json')), 'on a fresh PC, config init and the local schema files are created');
+};

package/dist/selftest/index.d.ts

@@ -0,0 +1 @@
+export declare const selfTest: (packageRoot: string) => Promise<number>;

package/dist/selftest/index.js

@@ -0,0 +1,56 @@
+// `agent-sandbox self-test`: offline logic and security tests, plus live tests of the session daemon, ptyhost and
+// the git guard when running on Windows (they need csc.exe and ConPTY, both part of Windows 10/11).
+import { errMsg } from '../core/util.js';
+import { configTests } from './config.test.js';
+import { cliTests } from './cli.test.js';
+import { dataTests } from './data.test.js';
+import { detectTests } from './detect.test.js';
+import { mirrorTests } from './mirror.test.js';
+import { createFixtures } from './fixtures.js';
+import { guestTests } from './guest.test.js';
+import { createHarness } from './harness.js';
+import { helperTests } from './helpers.test.js';
+import { hostTests } from './host.test.js';
+import { daemonTests, gitGuardTests, liveTestsAvailable } from './live.test.js';
+import { securityTests } from './security.test.js';
+import { setupTests } from './setup.test.js';
+import { syncTests } from './sync.test.js';
+export const selfTest = async (packageRoot) => {
+    const t = createHarness(packageRoot);
+    const saved = { home: process.env.AGENT_SANDBOX_HOME, windir: process.env.WINDIR };
+    process.env.AGENT_SANDBOX_HOME = t.temp + '\\user-home';
+    try {
+        const f = createFixtures(t);
+        await configTests(t, f);
+        const launchPath = await guestTests(t, f);
+        await syncTests(t, f);
+        await mirrorTests(t, f);
+        await securityTests(t, f);
+        helperTests(t);
+        detectTests(t);
+        setupTests(t);
+        hostTests(t);
+        dataTests(t);
+        cliTests(t);
+        if (liveTestsAvailable()) {
+            await daemonTests(t, f, launchPath);
+            await gitGuardTests(t, f, launchPath);
+        }
+        else
+            console.log('SKIP  live tests (need Windows with the .NET Framework compiler)');
+    }
+    catch (e) {
+        t.check(false, 'unexpected error: ' + errMsg(e) + (e instanceof Error && e.stack ? '\n' + e.stack : ''));
+    }
+    finally {
+        if (saved.home === undefined)
+            delete process.env.AGENT_SANDBOX_HOME;
+        else
+            process.env.AGENT_SANDBOX_HOME = saved.home;
+        process.env.WINDIR = saved.windir;
+        t.dispose();
+    }
+    const failures = t.failures();
+    console.log(failures === 0 ? '\nALL TESTS PASSED' : '\n' + failures + ' TEST(S) FAILED');
+    return failures === 0 ? 0 : 1;
+};

package/dist/selftest/live.test.d.ts

@@ -0,0 +1,7 @@
+import type { Fixtures } from './fixtures.js';
+import type { Harness } from './harness.js';
+export declare const liveTestsAvailable: () => boolean;
+/** Drives the real daemon through the run folder exactly like the host does, with cmd.exe standing in for claude. */
+export declare const daemonTests: (t: Harness, f: Fixtures, launchPath: string) => Promise<void>;
+/** Compiles gitshim.cs and runs real git through it in a scratch repository, as git.exe and through Git Bash. */
+export declare const gitGuardTests: (t: Harness, f: Fixtures, launchPath: string) => Promise<void>;

package/dist/selftest/live.test.js

@@ -0,0 +1,127 @@
+// Live tests on Windows: the real guest session daemon + ptyhost (ConPTY), and the compiled git guard on a real repo.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { ensureDir, findOnPath, sleep } from '../core/util.js';
+import { connect, encodeFrame, fixWindowsKeys, FrameReader, FrameType, helloFrame, queryViewers } from '../shared/pty-client.js';
+import { readJsonFile, writeJsonAtomic } from '../shared/rundir.js';
+const CSC = path.join(process.env.WINDIR ?? 'C:\\Windows', 'Microsoft.NET', 'Framework64', 'v4.0.30319', 'csc.exe');
+export const liveTestsAvailable = () => process.platform === 'win32' && fs.existsSync(CSC);
+/** Drives the real daemon through the run folder exactly like the host does, with cmd.exe standing in for claude. */
+export const daemonTests = async (t, f, launchPath) => {
+    const { check, waitFor } = t;
+    t.section('live: session daemon + ptyhost');
+    const data = f.at('live-data');
+    const workspace = f.workA;
+    ensureDir(path.join(data, 'tools', 'agents', 'claude'));
+    fs.copyFileSync(path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32', 'cmd.exe'), path.join(data, 'tools', 'agents', 'claude', 'claude.exe'));
+    const sessionFile = path.join(launchPath, 'session.json');
+    const session = f.readJson(sessionFile);
+    Object.assign(session, { workspace, attach: { enabled: true } });
+    Object.assign(session.harness, { arguments: ['/d', '/k', 'echo LIVE-AGENT-READY'], resumeArguments: ['/d', '/k', 'echo LIVE-AGENT-RESUMED'] });
+    fs.writeFileSync(sessionFile, JSON.stringify(session));
+    const env = { ...process.env, AGENT_LAUNCH_DIR: launchPath, AGENT_DATA_DIR: data, AGENT_WORKSPACE: workspace, AGENT_LOCAL_DIR: f.at('local'), AGENT_LOG_PREFIX: 'daemon', AGENT_NO_TABS: '1' };
+    const daemon = spawn(process.execPath, [path.join(launchPath, 'runtime', 'daemon.js')], { env, stdio: 'ignore', windowsHide: true });
+    const run = path.join(data, 'run');
+    const request = (body) => writeJsonAtomic(path.join(run, 'requests', body.id + '.json'), { createdAt: new Date().toISOString(), ...body });
+    const response = (id) => waitFor(() => readJsonFile(path.join(run, 'responses', id + '.json')));
+    try {
+        request({ kind: 'session', id: 'live1', harness: 'claude', args: [], cwd: workspace });
+        const s = await waitFor(() => { const v = readJsonFile(path.join(run, 'sessions', 'live1.json')); return v && v.phase !== 'starting' ? v : null; }, 60000);
+        check(s?.phase === 'running' && Boolean(s.attach?.port), 'daemon compiles ptyhost and starts a session on request' + (s?.phase === 'failed' ? ' (' + s.message + ')' : ''));
+        if (!s?.attach)
+            return;
+        const socket = await connect({ ...s.attach, addresses: ['127.0.0.1'] });
+        const reader = new FrameReader();
+        let out = '';
+        let exitCode = null;
+        socket.on('data', (c) => { for (const fr of reader.push(c)) {
+            if (fr.type === FrameType.Output)
+                out += fr.payload.toString();
+            if (fr.type === FrameType.Exit)
+                exitCode = fr.payload.readInt32LE(0);
+        } });
+        socket.write(helloFrame(s.attach.token, 100, 30));
+        check(Boolean(await waitFor(() => out.includes('LIVE-AGENT-READY'), 10000)), 'an attached client sees the agent\'s screen');
+        socket.write(encodeFrame(FrameType.Input, Buffer.from('echo TYPED-%USERNAME:~0,0%OK\r')));
+        check(Boolean(await waitFor(() => out.includes('TYPED-OK'), 10000)), 'keystrokes reach the agent');
+        const badClient = await connect({ ...s.attach, addresses: ['127.0.0.1'] });
+        const badReader = new FrameReader();
+        let denied = '';
+        badClient.on('data', (c) => { for (const fr of badReader.push(c))
+            if (fr.type === FrameType.Error)
+                denied = fr.payload.toString(); });
+        badClient.write(helloFrame('wrong-token', 80, 24));
+        check(Boolean(await waitFor(() => denied, 20000)) && denied.includes('denied'), 'a client with the wrong token is refused');
+        const local = { ...s.attach, addresses: ['127.0.0.1'] };
+        const first = await queryViewers(local);
+        const second = await connect(local);
+        second.on('data', () => undefined);
+        second.write(helloFrame(s.attach.token, 60, 20));
+        const both = await waitFor(async () => ((await queryViewers(local))?.viewers === 2 ? true : null), 5000);
+        second.destroy();
+        const after = await waitFor(async () => { const v = await queryViewers(local); return v?.viewers === 1 ? v : null; }, 5000);
+        const still = readJsonFile(path.join(run, 'sessions', 'live1.json'));
+        check(first?.viewers === 1 && first.remote === 0 && Boolean(both) && after?.remote === 0 && still?.phase === 'running', 'viewers are counted live: a closed terminal stops counting at once and the session keeps running');
+        check(await queryViewers({ ...local, token: 'wrong-token' }) === null, 'the viewer query needs the session token too');
+        check(fixWindowsKeys(Buffer.from([0x61, 0x08, 0x7f, 0x1b])).equals(Buffer.from([0x61, 0x7f, 0x08, 0x1b])), 'Windows console Backspace (^H) reaches the agent as DEL, so it deletes one character, not a word');
+        request({ kind: 'exec', id: 'exec1', command: ['echo', 'hello from exec'], cwd: workspace, timeoutSeconds: 30 });
+        const ex = await response('exec1');
+        check(Boolean(ex?.ok && ex.stdout?.includes('hello from exec')), 'exec runs a command in the sandbox and returns its output');
+        request({ kind: 'exec', id: 'exec2', command: ['dir'], cwd: 'C:\\Windows', timeoutSeconds: 30 });
+        const ex2 = await response('exec2');
+        check(ex2?.ok === false && ex2.message.includes('not inside the sandbox workspace'), 'exec refuses folders outside the workspace');
+        request({ kind: 'shell', id: 'evil', command: 'calc' });
+        request({ kind: 'ping', id: 'ping1' });
+        const ping = await response('ping1');
+        check(Boolean(ping?.ok) && !fs.existsSync(path.join(run, 'responses', 'evil.json')) && !fs.existsSync(path.join(run, 'requests', 'evil.json')), 'ping answers; unknown request kinds are deleted unanswered');
+        request({ kind: 'restart', id: 'restart1', harness: 'claude' });
+        check(Boolean(await waitFor(() => out.includes('LIVE-AGENT-RESUMED'), 15000)), 'restart relaunches the agent with its resume arguments while attached');
+        socket.write(encodeFrame(FrameType.Input, Buffer.from('exit 3\r')));
+        await waitFor(() => exitCode !== null, 10000);
+        const ended = await waitFor(() => { const v = readJsonFile(path.join(run, 'sessions', 'live1.json')); return v?.phase === 'exited' ? v : null; });
+        check(exitCode === 3 && ended?.exitCode === 3, 'the agent\'s exit code reaches the client and the session status');
+        socket.destroy();
+        badClient.destroy();
+    }
+    finally {
+        daemon.kill();
+        await sleep(500);
+    }
+};
+/** Compiles gitshim.cs and runs real git through it in a scratch repository, as git.exe and through Git Bash. */
+export const gitGuardTests = async (t, f, launchPath) => {
+    const realGit = findOnPath(['git.exe']);
+    t.section('live: git access guard');
+    if (!realGit) {
+        console.log('SKIP  git guard (no git.exe on PATH)');
+        return;
+    }
+    const shimDir = f.at('gitshim');
+    ensureDir(shimDir);
+    const compiled = spawnSync(CSC, ['/nologo', '/optimize', '/out:' + path.join(shimDir, 'git.exe'), path.join(launchPath, 'sandbox', 'gitshim.cs')], { encoding: 'utf8' });
+    t.check(compiled.status === 0, 'gitshim.cs compiles with the .NET Framework compiler' + (compiled.status === 0 ? '' : ': ' + compiled.stdout));
+    if (compiled.status !== 0)
+        return;
+    const repo = f.at('guard-repo');
+    ensureDir(repo);
+    spawnSync(realGit, ['init', '-q'], { cwd: repo });
+    fs.writeFileSync(path.join(repo, 'a.txt'), 'hello');
+    const guard = path.join(launchPath, 'runtime', 'gitguard.js');
+    const env = (access) => ({ ...process.env, PATH: shimDir + path.delimiter + process.env.PATH, AGENT_GIT_ACCESS: access, AGENT_REAL_GIT: access === 'readonly' ? realGit : '', AGENT_GUARD_NODE: process.execPath, AGENT_GUARD_SCRIPT: guard, GIT_CONFIG_NOSYSTEM: '1' });
+    const git = (access, args) => spawnSync('git', args, { cwd: repo, env: env(access), encoding: 'utf8' });
+    const status = git('readonly', ['status', '--porcelain']);
+    t.check(status.status === 0 && status.stdout.includes('a.txt'), 'readonly: `git status` works through the git.exe stand-in (exact arguments preserved)');
+    const add = git('readonly', ['add', 'a.txt']);
+    t.check(add.status === 128 && add.stderr.includes('read-only') && git('readonly', ['status', '--porcelain']).stdout.includes('??'), 'readonly: `git add` is refused and nothing changes');
+    const none = git('none', ['status']);
+    t.check(none.status === 128 && none.stderr.includes('disabled'), 'none: every git call is refused');
+    const bash = [path.join(path.dirname(path.dirname(realGit)), 'bin', 'bash.exe'), path.join(path.dirname(path.dirname(realGit)), 'usr', 'bin', 'bash.exe')].find((b) => fs.existsSync(b));
+    if (bash) {
+        const bashEnv = t.write(f.at('gitshim', 'bashenv.sh'), 'git() { "' + process.execPath.replace(/\\/g, '/') + '" "' + guard.replace(/\\/g, '/') + '" "$@"; }\nexport -f git\n');
+        const viaBash = spawnSync(bash, ['-c', 'git commit -m x'], { cwd: repo, env: { ...env('readonly'), BASH_ENV: bashEnv.replace(/\\/g, '/') }, encoding: 'utf8' });
+        t.check(viaBash.status === 128 && viaBash.stderr.includes('read-only'), 'readonly: git inside Git Bash goes through the guard too (BASH_ENV)');
+    }
+    else
+        console.log('SKIP  Git Bash check (no bash.exe next to git)');
+};

package/dist/selftest/mirror.test.d.ts

@@ -0,0 +1,3 @@
+import type { Fixtures } from './fixtures.js';
+import type { Harness } from './harness.js';
+export declare const mirrorTests: (t: Harness, f: Fixtures) => Promise<void>;

package/dist/selftest/mirror.test.js

@@ -0,0 +1,74 @@
+// Guest paths on other drive letters (C:\Mirror\<letter> + subst) and guestWorkspace "mirror".
+import fs from 'node:fs';
+import path from 'node:path';
+import { Config, Mapping } from '../core/schema.js';
+import { guestPathFor } from '../cli/commands/context.js';
+import { buildWsb } from '../host/generate.js';
+import { guestDrive, isValidGuestPath, planMirrorWorkspace, sandboxFolder, substDrives } from '../shared/guest-paths.js';
+import { guestWorkspaceAliases, projectFolderName } from '../shared/paths.js';
+import { syncHistoryIn, syncHistoryOut } from '../sync/history.js';
+export const mirrorTests = async (t, f) => {
+    const { check, rejects, write } = t;
+    t.section('mirrored guest paths (other drive letters)');
+    check(['C:\\Assets', 'C:\\Workspace\\x', 'F:\\SteamLibrary\\steamapps\\common\\Game', 'f:\\x', 'Z:\\a b\\c (1)'].every(isValidGuestPath), 'guest paths under C:\\ or on D: to Z: are accepted');
+    check(!['C:\\', 'F:\\', 'F:', 'C:\\Windows\\x', 'C:\\Users\\me', 'c:\\program files\\x', 'C:\\AgentData\\x', 'C:\\Mirror', 'C:\\Mirror\\F\\x', 'A:\\x', 'B:\\x', 'C:\\a\\..\\Windows', 'F:\\a\\..\\b', 'F:\\a:b', 'F:\\a/b', 'F:\\a\\\\b', 'F:\\a.\\b', 'F:\\a|b', 'F:\\a\nb', '\\\\server\\share\\x', 'relative\\x', 'F:x'].some(isValidGuestPath), 'drive roots, reserved folders, C:\\Mirror, A:/B:, .., streams, odd characters and UNC paths are refused');
+    const mapping = (guest) => Mapping.safeParse({ host: 'E:\\Games', guest, readOnly: true }).success;
+    check(mapping('F:\\SteamLibrary\\Game') && !mapping('C:\\Mirror\\F\\x') && mapping('C:\\F') && !mapping('F:\\'), 'schema: mappings[].guest may be on another drive letter, never C:\\Mirror or a drive root');
+    check(Config.safeParse({ ...f.makeConfig(), guestWorkspace: 'mirror' }).success && Config.safeParse({ ...f.makeConfig(), guestWorkspace: 'F:\\AgentProjects\\x' }).success && !Config.safeParse({ ...f.makeConfig(), guestWorkspace: 'C:\\Users\\x' }).success, 'schema: guestWorkspace accepts "mirror" and D:-Z: paths, refuses reserved ones');
+    check(guestDrive('f:\\x') === 'F' && guestDrive('\\\\s\\x') === null, 'drive letter of a guest path');
+    check(sandboxFolder('F:\\SteamLibrary\\Game') === 'C:\\Mirror\\F\\SteamLibrary\\Game' && sandboxFolder('f:\\x') === 'C:\\Mirror\\F\\x' && sandboxFolder('C:\\Assets') === 'C:\\Assets', 'F:\\x really lives at C:\\Mirror\\F\\x; C: paths stay as they are');
+    check(JSON.stringify(substDrives(['C:\\a', 'G:\\z', 'F:\\x', 'f:\\y'])) === JSON.stringify([{ letter: 'F', target: 'C:\\Mirror\\F' }, { letter: 'G', target: 'C:\\Mirror\\G' }]), 'one subst drive per used letter (never C:), sorted');
+    check(JSON.stringify(guestWorkspaceAliases('F:\\AgentProjects\\mw2')) === JSON.stringify(['C:\\Mirror\\F\\AgentProjects\\mw2', 'F:\\AgentProjects\\mw2']) && guestWorkspaceAliases('C:\\Workspace\\x').length === 1, 'a mirrored workspace is also known by its real C:\\Mirror path');
+    const wsb = buildWsb(f.baseConfig, 4096, [{ host: 'E:\\SteamLibrary\\steamapps\\common\\Game', guest: 'F:\\SteamLibrary\\steamapps\\common\\Game', readOnly: true }, { host: 'D:\\Assets', guest: 'C:\\Assets', readOnly: false }]);
+    check(wsb.includes('<SandboxFolder>C:\\Mirror\\F\\SteamLibrary\\steamapps\\common\\Game</SandboxFolder>') && wsb.includes('<SandboxFolder>C:\\Assets</SandboxFolder>') && !wsb.includes('<SandboxFolder>F:'), 'the .wsb maps F:\\ guests under C:\\Mirror\\F');
+    t.section('guestWorkspace "mirror"');
+    const fallback = 'C:\\Workspace\\mw2-agent';
+    const onF = planMirrorWorkspace('F:\\AgentProjects\\mw2-agent', fallback);
+    check(onF.guest === 'F:\\AgentProjects\\mw2-agent' && (onF.note ?? '').includes('C:\\Mirror\\F\\AgentProjects\\mw2-agent'), 'a workspace on F: appears at its PC path (mirror + subst), with a note');
+    check(planMirrorWorkspace('f:\\AgentProjects\\x\\', fallback).guest === 'F:\\AgentProjects\\x', 'trailing backslash and lower-case letter are normalised');
+    const onC = planMirrorWorkspace('C:\\dev\\mw2-agent', fallback);
+    check(onC.guest === 'C:\\dev\\mw2-agent' && onC.note === null, 'a workspace on C: outside reserved folders keeps its path');
+    const reserved = planMirrorWorkspace('C:\\Users\\josh\\mw2-agent', fallback);
+    check(reserved.guest === fallback && (reserved.note ?? '').includes('reserved'), 'C:\\Users\\... falls back to C:\\Workspace\\<name> with a note');
+    check(planMirrorWorkspace('\\\\server\\share\\mw2-agent', fallback).guest === fallback && planMirrorWorkspace('A:\\mw2-agent', fallback).guest === fallback, 'UNC paths and A:/B: fall back too');
+    const mirrorConfig = { ...f.makeConfig(), guestWorkspace: 'mirror' };
+    const resolved = await f.run({}, mirrorConfig);
+    const expected = planMirrorWorkspace(f.workA, 'C:\\Workspace\\work-a');
+    check(resolved.config.guestWorkspace === expected.guest && (expected.note === null || resolved.notes.includes(expected.note)), 'resolveRun turns "mirror" into a concrete guest path (and explains a fallback in run.notes)');
+    t.section('generate: mirrored mappings and workspace');
+    const game = f.at('steam', 'Game');
+    fs.mkdirSync(game, { recursive: true });
+    const base = await f.run();
+    const run = { ...base, config: { ...base.config, guestWorkspace: 'G:\\Projects\\work-a', mappings: [{ host: game, guest: 'F:\\SteamLibrary\\steamapps\\common\\Game', readOnly: true }] } };
+    const generated = f.generate(run);
+    const session = f.readJson(generated.sessionPath);
+    const text = fs.readFileSync(generated.wsbPath, 'utf8');
+    check(session.workspace === 'G:\\Projects\\work-a' && JSON.stringify(session.substDrives) === JSON.stringify([{ letter: 'F', target: 'C:\\Mirror\\F' }, { letter: 'G', target: 'C:\\Mirror\\G' }]), 'session.json: workspace at its drive-letter path, subst drives listed for bootstrap.ps1');
+    check(text.includes('<SandboxFolder>C:\\Mirror\\G\\Projects\\work-a</SandboxFolder>') && text.includes('<SandboxFolder>C:\\Mirror\\F\\SteamLibrary\\steamapps\\common\\Game</SandboxFolder>'), '.wsb: workspace and mapping under C:\\Mirror');
+    check(JSON.stringify(f.readJson(f.generate(base).sessionPath).substDrives) === '[]', 'no other drive letters: no subst drives');
+    check(await rejects(() => f.generate({ ...run, config: { ...run.config, mappings: [{ host: game, guest: 'C:\\Mirror\\F\\x', readOnly: true }] } }), 'not a usable sandbox folder'), 'a mapping straight into C:\\Mirror is refused');
+    check(await rejects(() => f.generate({ ...run, config: { ...run.config, mappings: [{ host: game, guest: 'C:\\Windows\\x', readOnly: true }] } }), 'not a usable sandbox folder'), 'a reserved guest folder is refused by the host too (not only the schema)');
+    check(await rejects(() => f.generate({ ...run, config: { ...run.config, mappings: [{ host: game, guest: 'g:\\projects\\work-a\\game', readOnly: true }] } }), 'overlapping'), 'mappings overlapping on the same mirrored drive are refused');
+    t.section('exec / attach cwd and history for a mirrored workspace');
+    const ws = 'F:\\AgentProjects\\mw2-agent';
+    check(guestPathFor(ws + '\\crates\\engine', ws, ws) === ws + '\\crates\\engine', 'a host folder maps to the same guest folder');
+    const hostDot = f.at('mirror-host-claude');
+    const guestDot = f.at('mirror-guest-claude');
+    const project = projectFolderName(ws);
+    check(project === 'F--AgentProjects-mw2-agent', 'Claude project folder for F:\\AgentProjects\\mw2-agent is F--AgentProjects-mw2-agent on both sides');
+    write(path.join(hostDot, 'projects', project, 's1.jsonl'), '{"cwd":"F:\\\\AgentProjects\\\\mw2-agent","t":1}\n');
+    write(path.join(hostDot, 'history.jsonl'), '{"display":"hi","timestamp":1,"project":"F:\\\\AgentProjects\\\\mw2-agent"}\n');
+    const paths = { hostClaudeDir: hostDot, guestClaudeDir: guestDot, hostWorkspace: ws, guestWorkspace: ws };
+    syncHistoryIn(paths);
+    check(fs.readFileSync(path.join(guestDot, 'projects', project, 's1.jsonl'), 'utf8').includes('F:\\\\AgentProjects\\\\mw2-agent') && fs.readdirSync(path.join(guestDot, 'projects')).length === 1, 'history in: same folder name, paths unchanged');
+    write(path.join(guestDot, 'projects', project, 's2.jsonl'), '{"cwd":"F:\\\\AgentProjects\\\\mw2-agent","t":2}\n');
+    write(path.join(guestDot, 'projects', 'C--Mirror-F-AgentProjects-mw2-agent', 's3.jsonl'), '{"cwd":"C:\\\\Mirror\\\\F\\\\AgentProjects\\\\mw2-agent","f":"C:/Mirror/F/AgentProjects/mw2-agent/src/main.rs"}\n');
+    fs.appendFileSync(path.join(guestDot, 'history.jsonl'), '{"display":"real path","timestamp":2,"project":"C:\\\\Mirror\\\\F\\\\AgentProjects\\\\mw2-agent"}\n');
+    syncHistoryOut(paths);
+    const s3 = path.join(hostDot, 'projects', project, 's3.jsonl');
+    check(fs.existsSync(path.join(hostDot, 'projects', project, 's2.jsonl')) && fs.existsSync(s3) && !fs.existsSync(path.join(hostDot, 'projects', 'C--Mirror-F-AgentProjects-mw2-agent')), 'history out: transcripts under the real C:\\Mirror path come back into the PC project folder');
+    const s3Text = fs.existsSync(s3) ? fs.readFileSync(s3, 'utf8') : '';
+    check(s3Text.includes('"cwd":"F:\\\\AgentProjects\\\\mw2-agent"') && s3Text.includes('F:/AgentProjects/mw2-agent/src/main.rs') && !s3Text.includes('Mirror'), 'history out: C:\\Mirror\\F\\... paths are translated back to F:\\...');
+    const hist = fs.readFileSync(path.join(hostDot, 'history.jsonl'), 'utf8');
+    check(hist.includes('"project":"F:\\\\AgentProjects\\\\mw2-agent"}') && !hist.includes('Mirror'), 'prompt history out: real paths translated too');
+};

package/dist/selftest/security.test.d.ts

@@ -0,0 +1,3 @@
+import type { Fixtures } from './fixtures.js';
+import type { Harness } from './harness.js';
+export declare const securityTests: (t: Harness, f: Fixtures) => Promise<void>;