windows-development-sandbox 0.0.0-stage → 1.1.0

package/dist/selftest/harness.js

@@ -0,0 +1,77 @@
+// Minimal test harness: PASS/FAIL lines (a failure shows what was expected and what was found), assertion helpers,
+// and a temp folder that is always removed. Every test writes only below `t.temp`.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { inspect, isDeepStrictEqual } from 'node:util';
+import { ensureDir, errMsg, sleep } from '../core/util.js';
+const show = (value) => inspect(value, { depth: 6, breakLength: 110, maxStringLength: 600, maxArrayLength: 40 });
+const indent = (text) => text.split('\n').map((line) => '        ' + line).join('\n');
+const clip = (text, max = 800) => (text.length > max ? text.slice(0, max) + ' ... (' + text.length + ' characters)' : text);
+export const createHarness = (packageRoot) => {
+    let failed = 0;
+    let total = 0;
+    const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-sandbox-test-'));
+    const check = (ok, name, detail) => {
+        total++;
+        console.log((ok ? '\x1b[32mPASS\x1b[0m  ' : '\x1b[31mFAIL\x1b[0m  ') + name);
+        if (ok)
+            return;
+        failed++;
+        if (detail)
+            console.log(indent(detail));
+    };
+    /** Runs `fn` once; the message includes the `fix` hint of a UserError. */
+    const attempt = async (fn) => {
+        try {
+            await fn();
+            return { threw: false };
+        }
+        catch (e) {
+            return { threw: true, message: (errMsg(e) + ' ' + (e.fix ?? '')).trim() };
+        }
+    };
+    const thrownMessage = async (fn) => {
+        const outcome = await attempt(fn);
+        return outcome.threw ? outcome.message : '';
+    };
+    const write = (file, content) => { ensureDir(path.dirname(file)); fs.writeFileSync(file, content); return file; };
+    return {
+        packageRoot,
+        temp,
+        failures: () => failed,
+        checks: () => total,
+        check,
+        equal: (actual, expected, name) => check(isDeepStrictEqual(actual, expected), name, 'expected: ' + show(expected) + '\nactual:   ' + show(actual)),
+        includes: (text, needle, name) => check(text.includes(needle), name, 'expected to contain: ' + show(needle) + '\nactual: ' + show(clip(text))),
+        excludes: (text, needle, name) => check(!text.includes(needle), name, 'expected NOT to contain: ' + show(needle) + '\nactual: ' + show(clip(text))),
+        matches: (text, pattern, name) => check(pattern.test(text), name, 'expected to match: ' + String(pattern) + '\nactual: ' + show(clip(text))),
+        throws: async (fn, expected, name) => {
+            const outcome = await attempt(fn);
+            const message = outcome.threw ? outcome.message : '';
+            const ok = outcome.threw && (typeof expected === 'string' ? message.includes(expected) : expected.test(message));
+            check(ok, name, 'expected an error containing: ' + String(expected) + '\n' + (outcome.threw ? 'actual error: ' + show(clip(message)) : 'but nothing was thrown'));
+        },
+        thrownMessage,
+        section: (title) => console.log('\n\x1b[36m-- ' + title + '\x1b[0m'),
+        skip: (what) => console.log('SKIP  ' + what),
+        at: (...parts) => path.join(temp, ...parts),
+        dir: (...parts) => { const p = path.join(temp, ...parts); ensureDir(p); return p; },
+        write,
+        writeJson: (file, value) => write(file, JSON.stringify(value)),
+        readJson: (file) => JSON.parse(fs.readFileSync(file, 'utf8')),
+        touch: (file, secondsFromNow = 10) => { const when = new Date(Date.now() + secondsFromNow * 1000); fs.utimesSync(file, when, when); },
+        waitFor: async (read, ms = 30000, everyMs = 100) => {
+            const end = Date.now() + ms;
+            for (;;) {
+                const value = await read();
+                if (value)
+                    return value;
+                if (Date.now() >= end)
+                    return null;
+                await sleep(everyMs);
+            }
+        },
+        dispose: () => fs.rmSync(temp, { recursive: true, force: true, maxRetries: 5, retryDelay: 300 }),
+    };
+};

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

@@ -0,0 +1,2 @@
+import type { Suite } from './suite.js';
+export declare const hostSimSuite: Suite;

package/dist/selftest/host-sim.test.js

@@ -0,0 +1,93 @@
+// 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.
+//
+// Each command gets its own home and storage folder, so they cannot disturb each other and run several at a time
+// (every one is a fresh Node process, which is what makes this the slowest suite when run one by one).
+import fs from 'node:fs';
+import path from 'node:path';
+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'];
+const PARALLEL = 2;
+const sandbox = (label, ...args) => ({ bin: 'agent-sandbox', label, args, config: true });
+const COMMANDS = [
+    { bin: 'agent-sandbox', label: '--help', args: ['--help'] },
+    sandbox('status', 'status'),
+    sandbox('status --json', 'status', '--json'),
+    sandbox('sessions', 'sessions'),
+    sandbox('doctor', 'doctor'),
+    sandbox('account list', 'account', 'list'),
+    sandbox('account use nobody', 'account', 'use', 'nobody'),
+    { bin: 'agent-sandbox', label: 'config path', args: ['config', 'path'] },
+    sandbox('config show', 'config', 'show'),
+    { bin: 'agent-sandbox', label: 'config schema', args: ['config', 'schema'] },
+    sandbox('clean', 'clean'),
+    sandbox('sync', 'sync'),
+    sandbox('logs', 'logs'),
+    sandbox('attach', 'attach'),
+    { bin: 'agent-sandbox', label: 'exec', args: ['exec'], after: ['--', 'echo', 'hi'], config: true },
+    sandbox('restart', 'restart'),
+    sandbox('stop', 'stop'),
+    sandbox('show', 'show'),
+    sandbox('hide', 'hide'),
+    sandbox('generate', 'generate'),
+    sandbox('launch', 'launch'),
+    { bin: 'agent-sandbox', label: 'unknown command', args: ['frobnicate'] },
+    { bin: 'claude-sbx', label: 'claude-sbx --headless --continue', args: ['--headless', '--continue'], config: true },
+    { bin: 'codex-sbx', label: 'codex-sbx', args: [], config: true },
+    { bin: 'gemini-sbx', label: 'gemini-sbx', args: [], config: true },
+    { bin: 'sbx-show', label: 'sbx-show', args: [], config: true },
+    { bin: 'claude-host', label: 'claude-host --version', args: ['--version'] },
+];
+export const hostSimSuite = {
+    name: 'host-sim',
+    title: 'every command run as its own process on a simulated host PC',
+    timeoutMs: 300000,
+    run: async (t, f) => {
+        t.section('every command outside a sandbox');
+        const baseEnv = Object.fromEntries(Object.entries(process.env).filter(([k]) => !SANDBOX_ONLY_VARS.includes(k)));
+        const project = t.dir('host-sim-project');
+        const envFor = (home) => ({
+            ...baseEnv,
+            AGENT_SANDBOX_HOME: home,
+            AGENT_LAUNCH_DIR: t.at('no-agent-launch'),
+            AGENT_DATA_DIR: t.at('no-agent-data'),
+            AGENT_HOST_TOOLS_DIR: t.at('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',
+        });
+        /** A fresh home, storage and config file for one command. */
+        const freshPc = (name) => {
+            const home = t.dir('host-sim', name, 'home');
+            const storage = t.dir('host-sim', name, 'storage');
+            const config = t.writeJson(t.at('host-sim', name, 'config.json'), { storage: { root: storage }, personalization: { enabled: false }, provisioning: { terminal: { enabled: false } } });
+            return { home, config };
+        };
+        const broken = [];
+        const runOne = async (command, index, pc = freshPc('c' + index)) => {
+            const args = command.config ? [...command.args, '--config', pc.config, ...(command.after ?? [])] : command.args;
+            const r = await f.runBin(command.bin, args, { cwd: project, env: envFor(pc.home), timeoutMs: 120000 });
+            const crashed = r.status === null || r.status > 1 || /Unexpected error|node:internal|^\s+at .+:\d+:\d+\)?$/m.test(r.out);
+            const unexplained = r.status === 1 && !/(^|\n)(Error: |error: )/.test(r.out) && command.bin !== 'claude-host';
+            if (crashed || unexplained)
+                broken.push(command.label + ' (exit ' + r.status + (r.timedOut ? ', timed out' : '') + '): ' + r.out.trim().split('\n').slice(0, 4).join(' | '));
+        };
+        // `config init` twice must see the same home (the second run finds the files the first one made).
+        const initPc = freshPc('init');
+        const queue = COMMANDS.map((command, index) => ({ command, index }));
+        const workers = Array.from({ length: PARALLEL }, async () => {
+            for (let next = queue.shift(); next; next = queue.shift())
+                await runOne(next.command, next.index);
+        });
+        const initRuns = (async () => {
+            await runOne({ bin: 'agent-sandbox', label: 'config init', args: ['config', 'init'] }, 1000, initPc);
+            await runOne({ bin: 'agent-sandbox', label: 'config init (again)', args: ['config', 'init'] }, 1001, initPc);
+        })();
+        await Promise.all([...workers, initRuns]);
+        t.equal(broken, [], 'all ' + (COMMANDS.length + 2) + ' commands work or fail with a clear message when run outside a sandbox');
+        for (const file of ['config.json', 'config.schema.json', 'sandbox-config.schema.json']) {
+            t.check(fs.existsSync(path.join(initPc.home, file)), 'on a fresh PC, config init creates ' + file);
+        }
+    },
+};

package/dist/selftest/hostile-input.test.d.ts

@@ -0,0 +1,2 @@
+import type { Suite } from './suite.js';
+export declare const hostileInputSuite: Suite;

package/dist/selftest/hostile-input.test.js

@@ -0,0 +1,54 @@
+// Names, paths and text coming from a hostile sandbox or workspace: file names, deletes, printed text, mappings, state
+// files and the launch path.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { assertCmdSafePath } from '../host/platform.js';
+import { assertSafeMapping } from '../core/safe-paths.js';
+import { safeText } from '../core/util.js';
+import { isSafeFileName } from '../shared/paths.js';
+import { removeRefusal, safeRemove } from '../shared/safe-remove.js';
+import { writeJsonAtomic } from '../shared/rundir.js';
+export const hostileInputSuite = {
+    name: 'hostile-input',
+    title: 'file names, deletes, printed text, mappings and state files from an untrusted sandbox',
+    run: async (t) => {
+        t.section('file names');
+        const unsafe = ['CON.jsonl', 'nul', 'aux.json', 'COM1.txt', 'a:b', 'x.jsonl.', 'x ', '..', 'a\\b', 'LPT3'];
+        t.equal(unsafe.filter(isSafeFileName), [], 'device names, streams and trailing dots are not valid names to copy into this PC');
+        const fine = ['C--Workspace-app', 'a.jsonl', '.credentials.json', 'console.jsonl'];
+        t.equal(fine.filter((name) => !isSafeFileName(name)), [], 'ordinary names (even ones that merely contain a device name) are valid');
+        t.section('deletes');
+        const profile = os.homedir();
+        const root = t.at('safe-root');
+        const targets = {
+            'your profile': profile,
+            'a folder above your profile': path.dirname(profile),
+            'a drive root': 'C:\\',
+            Windows: 'C:\\Windows',
+            'an empty path': '',
+            'a relative path': 'relative\\folder',
+            'a path outside the root': t.at('outside-root', 'x'),
+        };
+        for (const [what, target] of Object.entries(targets))
+            t.check(removeRefusal(target, root) !== null, 'a delete is refused for ' + what);
+        t.check(removeRefusal('\\\\?\\C:\\Users\\someone\\x', '\\\\?\\C:\\Users\\someone') !== null, 'a delete is refused for \\\\?\\ paths');
+        t.check(removeRefusal('C:\\Windows\\Temp\\x', 'C:\\Windows\\Temp') !== null, 'a delete is refused inside Windows');
+        t.check(removeRefusal('C:\\Program Files\\x\\y', 'C:\\Program Files\\x') !== null, 'a delete is refused inside Program Files');
+        const allowedTarget = path.join(root, 'tools', 'go');
+        t.write(path.join(allowedTarget, 'go.exe'), 'x');
+        safeRemove(allowedTarget, root);
+        t.check(!fs.existsSync(allowedTarget), 'a folder inside its root is deleted');
+        t.section('text, mappings, state files, launch path');
+        t.equal(safeText('ok \x1b[31mred\x1b[0m \x1b]52;c;ZXZpbA==\x07\x1b]0;title\x07\x1b[2J\x07end'), 'ok \x1b[31mred\x1b[0m end', 'sandbox text printed on this PC keeps colours but loses every other escape sequence');
+        await t.throws(() => assertSafeMapping(path.join(t.packageRoot, 'dist'), t.packageRoot, t.at('storage')), 'overlaps', 'extra mappings may not reach the install folder');
+        await t.throws(() => assertSafeMapping(t.at('storage', 'data'), t.packageRoot, t.at('storage')), 'overlaps', 'extra mappings may not reach the storage folder');
+        const atomicFile = t.at('atomic', 'state.json');
+        writeJsonAtomic(atomicFile, { a: 1 });
+        writeJsonAtomic(atomicFile, { a: 2 });
+        t.equal(t.readJson(atomicFile).a, 2, 'state files are replaced whole...');
+        t.equal(fs.readdirSync(path.dirname(atomicFile)).length, 1, '... with no temp files left behind');
+        await t.throws(() => assertCmdSafePath('C:\\a\\%TEMP%\\agent.wsb'), 'cannot be started safely', 'a launch path with %VAR% (which cmd.exe would expand) is refused');
+        await t.throws(() => assertCmdSafePath('C:\\a"&calc&"\\agent.wsb'), 'cannot be started safely', 'a launch path with quotes and & is refused');
+    },
+};

package/dist/selftest/index.d.ts

@@ -0,0 +1,8 @@
+import type { Suite } from './suite.js';
+/** Every suite, in the order they run. The live ones come last: they are the slowest and need Windows. */
+export declare const SUITES: Suite[];
+/** Windows Sandbox (its user is always WDAGUtilityAccount) or a GitHub Actions runner: never someone's PC. */
+export declare const onThrowawayMachine: () => boolean;
+/** Resolves "a,b" / ["a", "b"] to suites; throws with the list of valid names for an unknown one. */
+export declare const pickSuites: (names: string[]) => Suite[];
+export declare const selfTest: (packageRoot: string, suiteNames?: string[]) => Promise<number>;

package/dist/selftest/index.js

@@ -0,0 +1,155 @@
+// `agent-sandbox self-test [suite...]`: 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).
+// They start real processes (the guest runtime, the daemon, csc, git), so they only run on a throwaway machine.
+//
+// Each area is one suite in its own *.test.ts file; the list below is the order they run in. Give suite names (or a
+// comma-separated list) to run only those: `sandbox self-test config`, `npm test -- live-daemon`.
+import os from 'node:os';
+import path from 'node:path';
+import { errMsg } from '../core/util.js';
+import { createFixtures } from './fixtures.js';
+import { createHarness } from './harness.js';
+import { liveTestsAvailable } from './live.js';
+import { accountsSuite } from './accounts.test.js';
+import { agentCommandsSuite } from './agent-commands.test.js';
+import { channelSuite } from './channel.test.js';
+import { cliSuite } from './cli.test.js';
+import { cmdlineSuite } from './cmdline.test.js';
+import { configSuite } from './config.test.js';
+import { dataSuite } from './data.test.js';
+import { detectSuite } from './detect.test.js';
+import { generateSuite } from './generate.test.js';
+import { gitAccessSuite } from './git-access.test.js';
+import { guestBootSuite } from './guest-boot.test.js';
+import { hostileInputSuite } from './hostile-input.test.js';
+import { hostSimSuite } from './host-sim.test.js';
+import { linksSuite } from './links.test.js';
+import { liveDaemonSuite } from './live-daemon.test.js';
+import { liveGitSuite } from './live-git.test.js';
+import { liveProjectsSuite } from './live-projects.test.js';
+import { localConfigSuite } from './local-config.test.js';
+import { mirrorSuite } from './mirror.test.js';
+import { networkSuite } from './network.test.js';
+import { personalizationSuite } from './personalization.test.js';
+import { projectsSuite } from './projects.test.js';
+import { repairSuite } from './repair.test.js';
+import { repoGuardSuite } from './repo-guard.test.js';
+import { secretsSuite } from './secrets.test.js';
+import { setupSuite } from './setup.test.js';
+import { syncSuite } from './sync.test.js';
+import { testGuardSuite } from './test-guard.test.js';
+import { toolchainsSuite } from './toolchains.test.js';
+import { workspaceSuite } from './workspace.test.js';
+/** Every suite, in the order they run. The live ones come last: they are the slowest and need Windows. */
+export const SUITES = [
+    // settings and project files
+    configSuite, workspaceSuite, localConfigSuite,
+    // the generated sandbox and the guest that boots it
+    generateSuite, guestBootSuite, mirrorSuite, projectsSuite,
+    // syncing with this PC
+    syncSuite, accountsSuite,
+    // an untrusted sandbox: what the host refuses to do with what it finds
+    linksSuite, channelSuite, gitAccessSuite, repoGuardSuite, secretsSuite, hostileInputSuite, testGuardSuite,
+    // pure helpers and the command line
+    toolchainsSuite, detectSuite, networkSuite, personalizationSuite, cmdlineSuite, setupSuite, dataSuite, repairSuite, cliSuite, agentCommandsSuite,
+    // every command as its own process
+    hostSimSuite,
+    // real processes
+    liveDaemonSuite, liveProjectsSuite, liveGitSuite,
+];
+/** Windows Sandbox (its user is always WDAGUtilityAccount) or a GitHub Actions runner: never someone's PC. */
+export const onThrowawayMachine = () => os.userInfo().username.toLowerCase() === 'wdagutilityaccount' || process.env.GITHUB_ACTIONS === 'true';
+const withDeadline = async (work, ms, what) => {
+    let timer;
+    const deadline = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(what + ' did not finish within ' + Math.round(ms / 1000) + ' s')), ms); });
+    try {
+        return await Promise.race([work, deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+const runSuite = async (suite, t, f) => {
+    const checksBefore = t.checks();
+    const failedBefore = t.failures();
+    const started = Date.now();
+    let note;
+    if (suite.live && !liveTestsAvailable()) {
+        t.section(suite.name);
+        t.skip(suite.title + ' (needs Windows with the .NET Framework compiler)');
+        note = 'skipped';
+    }
+    else {
+        try {
+            await withDeadline(Promise.resolve(suite.run(t, f)), suite.timeoutMs ?? 120000, 'suite "' + suite.name + '"');
+        }
+        catch (e) {
+            t.check(false, 'suite "' + suite.name + '" stopped with an unexpected error', errMsg(e) + (e instanceof Error && e.stack ? '\n' + e.stack : ''));
+        }
+    }
+    return { suite, checks: t.checks() - checksBefore, failed: t.failures() - failedBefore, seconds: (Date.now() - started) / 1000, note };
+};
+const printSummary = (results) => {
+    const width = Math.max(...results.map((r) => r.suite.name.length));
+    console.log('\n\x1b[36m-- summary\x1b[0m');
+    for (const r of results) {
+        const state = r.note ?? (r.failed ? r.failed + ' FAILED' : 'ok');
+        console.log('  ' + r.suite.name.padEnd(width) + '  ' + String(r.checks).padStart(4) + ' checks  ' + r.seconds.toFixed(1).padStart(6) + ' s  ' + state);
+    }
+    const total = results.reduce((sum, r) => sum + r.checks, 0);
+    console.log('  ' + 'total'.padEnd(width) + '  ' + String(total).padStart(4) + ' checks  ' + results.reduce((sum, r) => sum + r.seconds, 0).toFixed(1).padStart(6) + ' s');
+};
+/** Resolves "a,b" / ["a", "b"] to suites; throws with the list of valid names for an unknown one. */
+export const pickSuites = (names) => {
+    const wanted = names.flatMap((n) => n.split(',')).map((n) => n.trim()).filter(Boolean);
+    if (wanted.length === 0)
+        return SUITES;
+    const unknown = wanted.filter((name) => !SUITES.some((s) => s.name === name));
+    if (unknown.length)
+        throw new Error('No test suite called ' + unknown.join(', ') + '. Suites: ' + SUITES.map((s) => s.name).join(', '));
+    return SUITES.filter((s) => wanted.includes(s.name));
+};
+export const selfTest = async (packageRoot, suiteNames = []) => {
+    if (!onThrowawayMachine()) {
+        console.error('The self-test only runs inside a Windows Sandbox, so it can never change this PC.\nRun it there: `sandbox start` in this folder, then `npm test` in the sandbox\'s terminal.');
+        return 1;
+    }
+    let chosen;
+    try {
+        chosen = pickSuites(suiteNames);
+    }
+    catch (e) {
+        console.error(errMsg(e));
+        return 1;
+    }
+    // Defence in depth (shared/test-guard.ts): with this set, host code refuses outward actions and writes outside temp.
+    process.env.AGENT_SANDBOX_SELFTEST = '1';
+    const t = createHarness(packageRoot);
+    const saved = { home: process.env.AGENT_SANDBOX_HOME, windir: process.env.WINDIR };
+    process.env.AGENT_SANDBOX_HOME = path.join(t.temp, 'user-home');
+    const results = [];
+    try {
+        const f = createFixtures(t);
+        for (const suite of chosen)
+            results.push(await runSuite(suite, t, f));
+    }
+    catch (e) {
+        t.check(false, 'unexpected error: ' + errMsg(e), e instanceof Error ? e.stack : undefined);
+    }
+    finally {
+        if (saved.home === undefined)
+            delete process.env.AGENT_SANDBOX_HOME;
+        else
+            process.env.AGENT_SANDBOX_HOME = saved.home;
+        if (saved.windir === undefined)
+            delete process.env.WINDIR;
+        else
+            process.env.WINDIR = saved.windir;
+        t.dispose();
+    }
+    if (results.length > 1)
+        printSummary(results);
+    const failures = t.failures();
+    console.log(failures === 0 ? '\nALL TESTS PASSED' : '\n' + failures + ' TEST(S) FAILED');
+    return failures === 0 ? 0 : 1;
+};

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

@@ -0,0 +1,2 @@
+import type { Suite } from './suite.js';
+export declare const linksSuite: Suite;

package/dist/selftest/links.test.js

@@ -0,0 +1,50 @@
+// Links (junctions and symlinks) planted by a compromised sandbox in the folders this PC reads and writes: the host
+// must never write, delete or walk through them.
+import fs from 'node:fs';
+import path from 'node:path';
+import { activateAccount, saveAccount } from '../host/accounts.js';
+import { resetRunDir, sendRequest } from '../host/channel.js';
+import { pruneStorage } from '../host/cleanup.js';
+import { assertNoLinks } from '../core/util.js';
+import { syncHistoryIn } from '../sync/history.js';
+export const linksSuite = {
+    name: 'links',
+    title: 'links planted by the sandbox are never followed',
+    run: async (t) => {
+        const victim = t.at('victim');
+        const precious = t.write(path.join(victim, 'precious.txt'), 'keep me');
+        const storage = t.at('evil-storage');
+        const data = t.dir('evil-storage', 'data', 'd');
+        t.dir('evil-storage', 'data', 'd', 'state');
+        t.section('writes under the data folder');
+        fs.symlinkSync(victim, path.join(data, 'state', 'claude'), 'junction');
+        await t.throws(() => assertNoLinks(data, path.join(data, 'state', 'claude', 'x.json')), 'is a link', 'any host write under the data folder through a junction is refused');
+        await t.throws(() => activateAccount(storage, data, 'any'), 'Unknown account', 'accounts never read through a sandbox junction');
+        await t.throws(() => saveAccount(storage, data, 'a', null), 'is a link', 'accounts never write through a sandbox junction');
+        t.section('history sync');
+        const sides = { hostClaudeDir: t.at('link-host'), guestClaudeDir: t.at('link-guest'), hostWorkspace: 'D:\\Code\\my-app', guestWorkspace: 'C:\\Workspace\\my-app' };
+        t.dir('link-guest', 'projects');
+        fs.symlinkSync(victim, path.join(sides.guestClaudeDir, 'projects', 'C--Workspace-my-app'), 'junction');
+        t.write(path.join(sides.hostClaudeDir, 'projects', 'D--Code-my-app', 's.jsonl'), '{}\n');
+        syncHistoryIn(sides);
+        t.check(!fs.existsSync(path.join(victim, 's.jsonl')), 'history sync never writes through a junction inside the sandbox state');
+        fs.symlinkSync(precious, path.join(sides.guestClaudeDir, 'history.jsonl'), 'file');
+        t.write(path.join(sides.hostClaudeDir, 'history.jsonl'), '{"display":"x","timestamp":1}\n');
+        syncHistoryIn(sides);
+        t.equal(fs.readFileSync(precious, 'utf8'), 'keep me', 'a file symlink planted in place of history.jsonl is replaced, not written through');
+        t.section('the run folder and cleanup');
+        t.dir('evil-storage', 'data', 'd', 'run');
+        fs.symlinkSync(victim, path.join(data, 'run', 'requests'), 'junction');
+        await t.throws(() => sendRequest(data, { kind: 'ping', id: 'p1', createdAt: '' }), 'is a link', 'requests are never written through a junction');
+        t.check(!fs.existsSync(path.join(victim, 'p1.json')), 'nothing was written into the junction\'s target');
+        fs.symlinkSync(victim, path.join(data, 'run', 'sessions'), 'junction');
+        resetRunDir(data);
+        t.check(!fs.existsSync(path.join(data, 'run', 'sessions')), 'resetting the run folder removes a junction itself...');
+        t.check(fs.existsSync(precious), '... never its target');
+        fs.symlinkSync(victim, path.join(data, 'logs'), 'junction');
+        const longAgo = new Date(Date.now() - 60 * 86400000);
+        fs.utimesSync(precious, longAgo, longAgo);
+        pruneStorage(storage);
+        t.check(fs.existsSync(precious), 'cleanup never walks into a junction (old files on this PC stay)');
+    },
+};

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

@@ -0,0 +1,2 @@
+import type { Suite } from './suite.js';
+export declare const liveDaemonSuite: Suite;

package/dist/selftest/live-daemon.test.js

@@ -0,0 +1,91 @@
+// Live: the real guest session daemon + ptyhost (ConPTY), driven through the run folder exactly like the host does, with
+// cmd.exe standing in for the agent. One daemon serves all the checks below, in order (compiling ptyhost is slow).
+import fs from 'node:fs';
+import path from 'node:path';
+import { queryViewers } from '../shared/pty-client.js';
+import { copyCmdAsFakeAgent, openViewer, sees, startDaemon, tail, viewersWhen, WAIT } from './live.js';
+export const liveDaemonSuite = {
+    name: 'live-daemon',
+    title: 'live: session daemon + ptyhost (start, attach, viewers, exec, restart, exit)',
+    live: true,
+    timeoutMs: 360000,
+    run: async (t, f) => {
+        const gen = await f.launch();
+        const data = t.at('live-data');
+        const workspace = f.workA;
+        copyCmdAsFakeAgent(data);
+        const session = f.readJson(gen.sessionPath);
+        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'] });
+        t.writeJson(gen.sessionPath, session);
+        const daemon = startDaemon(t, f, { launchPath: gen.launchPath, data, workspace });
+        const viewers = [];
+        try {
+            t.section('live: starting a session');
+            daemon.request({ kind: 'session', id: 'live1', harness: 'claude', args: [], cwd: workspace });
+            const started = await daemon.started('live1');
+            const running = started?.phase === 'running' && Boolean(started.attach?.port);
+            t.check(running, 'the daemon compiles ptyhost and starts a session on request', 'phase: ' + started?.phase + ' ' + (started?.message ?? '(no status written)') + '\n' + daemon.diagnostics());
+            if (!started?.attach)
+                return;
+            const attach = started.attach;
+            const local = { ...attach, addresses: ['127.0.0.1'] };
+            t.section('live: attached clients');
+            const viewer = await openViewer(attach);
+            viewers.push(viewer);
+            const sawReady = await sees(t, viewer, 'LIVE-AGENT-READY');
+            t.check(Boolean(sawReady), 'an attached client sees the agent\'s screen', 'screen so far: ' + tail(viewer.output()) + '\n' + daemon.diagnostics());
+            viewer.type('echo TYPED-%USERNAME:~0,0%OK');
+            const sawTyped = await sees(t, viewer, 'TYPED-OK');
+            t.check(Boolean(sawTyped), 'keystrokes reach the agent', 'screen so far: ' + tail(viewer.output()));
+            const intruder = await openViewer(attach, { token: 'wrong-token', cols: 80, rows: 24 });
+            viewers.push(intruder);
+            const denied = await t.waitFor(() => intruder.error(), WAIT.viewers);
+            t.check(Boolean(denied) && denied.includes('denied'), 'a client with the wrong token is refused', 'error frame: ' + JSON.stringify(denied) + ', connection closed: ' + intruder.closed());
+            t.check(!intruder.output().includes('LIVE-AGENT'), 'a client with the wrong token sees nothing of the session', tail(intruder.output()));
+            t.section('live: counting viewers');
+            // Each count is polled: a query that gets no answer yet is asked again, and the number must settle on the expected value.
+            const one = await viewersWhen(t, attach, (v) => v.viewers === 1);
+            t.check(one !== null, 'a single attached terminal is counted as one viewer', 'last answer: ' + JSON.stringify(await queryViewers(local, 5000)));
+            t.equal(one?.remote, 0, 'a viewer on loopback (inside the sandbox) is not counted as remote');
+            const second = await openViewer(attach, { cols: 60, rows: 20 });
+            viewers.push(second);
+            const two = await viewersWhen(t, attach, (v) => v.viewers === 2);
+            t.check(two !== null, 'a second attached terminal is counted too', 'last answer: ' + JSON.stringify(await queryViewers(local, 5000)));
+            second.close();
+            const backToOne = await viewersWhen(t, attach, (v) => v.viewers === 1);
+            t.check(backToOne !== null, 'a closed terminal stops counting at once', 'last answer: ' + JSON.stringify(await queryViewers(local, 5000)));
+            t.equal(backToOne?.remote, 0, 'the remaining viewer is still not remote');
+            t.equal(daemon.status('live1')?.phase, 'running', 'the session keeps running when a terminal closes');
+            t.equal(await queryViewers({ ...local, token: 'wrong-token' }, 10000), null, 'the viewer query needs the session token too');
+            t.section('live: exec and requests');
+            daemon.request({ kind: 'exec', id: 'exec1', command: ['echo', 'hello from exec'], cwd: workspace, timeoutSeconds: 30 });
+            const exec = await daemon.response('exec1');
+            t.check(Boolean(exec?.ok && exec.stdout?.includes('hello from exec')), 'exec runs a command in the sandbox and returns its output', JSON.stringify(exec));
+            daemon.request({ kind: 'exec', id: 'exec2', command: ['dir'], cwd: 'C:\\Windows', timeoutSeconds: 30 });
+            const outside = await daemon.response('exec2');
+            t.check(outside?.ok === false && outside.message.includes('not inside the sandbox workspace'), 'exec refuses folders outside the workspace', JSON.stringify(outside));
+            daemon.request({ kind: 'shell', id: 'evil', command: 'calc' });
+            daemon.request({ kind: 'ping', id: 'ping1' });
+            const ping = await daemon.response('ping1');
+            t.check(Boolean(ping?.ok), 'ping is answered', JSON.stringify(ping));
+            // Requests are handled in order, so by the time the ping is answered the unknown one has been dealt with.
+            t.check(!fs.existsSync(path.join(daemon.run, 'responses', 'evil.json')), 'an unknown request kind gets no answer...');
+            t.check(!fs.existsSync(path.join(daemon.run, 'requests', 'evil.json')), '... and is deleted');
+            t.section('live: restart and exit');
+            daemon.request({ kind: 'restart', id: 'restart1', harness: 'claude' });
+            const sawResumed = await sees(t, viewer, 'LIVE-AGENT-RESUMED');
+            t.check(Boolean(sawResumed), 'restart relaunches the agent with its resume arguments while attached', 'screen so far: ' + tail(viewer.output()) + '\n' + daemon.diagnostics());
+            viewer.type('exit 3');
+            const gotExit = await t.waitFor(() => viewer.exitCode() !== null, WAIT.exit);
+            const ended = await t.waitFor(() => { const s = daemon.status('live1'); return s?.phase === 'exited' ? s : null; }, WAIT.exit);
+            t.equal(gotExit ? viewer.exitCode() : null, 3, 'the agent\'s exit code reaches the attached client');
+            t.equal(ended?.exitCode, 3, 'the agent\'s exit code reaches the session status');
+        }
+        finally {
+            for (const v of viewers)
+                v.close();
+            await daemon.stop();
+        }
+    },
+};

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

@@ -0,0 +1,2 @@
+import type { Suite } from './suite.js';
+export declare const liveGitSuite: Suite;

package/dist/selftest/live-git.test.js

@@ -0,0 +1,60 @@
+// Live: compiles gitshim.cs with the .NET Framework compiler and runs real git through it in a scratch repository,
+// as git.exe and through Git Bash, in each git access mode.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { findOnPath } from '../core/util.js';
+import { CSC } from './live.js';
+export const liveGitSuite = {
+    name: 'live-git',
+    title: 'live: the git access guard (compiled git.exe stand-in, Git Bash)',
+    live: true,
+    run: async (t, f) => {
+        const realGit = findOnPath(['git.exe']);
+        if (!realGit) {
+            t.skip('git guard (no git.exe on PATH)');
+            return;
+        }
+        const gen = await f.launch();
+        const shimDir = t.dir('gitshim');
+        const compiled = spawnSync(CSC, ['/nologo', '/optimize', '/out:' + path.join(shimDir, 'git.exe'), path.join(gen.launchPath, 'sandbox', 'gitshim.cs')], { encoding: 'utf8' });
+        t.check(compiled.status === 0, 'gitshim.cs compiles with the .NET Framework compiler', compiled.stdout + compiled.stderr);
+        if (compiled.status !== 0)
+            return;
+        const repo = t.dir('guard-repo');
+        spawnSync(realGit, ['init', '-q'], { cwd: repo });
+        fs.writeFileSync(path.join(repo, 'a.txt'), 'hello');
+        const guard = path.join(gen.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',
+        });
+        // `git` is found through PATH, where the shim comes first (that is the point of the test).
+        const git = (access, args) => spawnSync('git', args, { cwd: repo, env: env(access), encoding: 'utf8' });
+        t.section('git.exe stand-in');
+        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)', 'exit ' + status.status + ' ' + status.stdout + status.stderr);
+        const add = git('readonly', ['add', 'a.txt']);
+        t.check(add.status === 128, 'readonly: `git add` is refused with exit code 128', 'exit ' + add.status);
+        t.includes(add.stderr, 'read-only', 'readonly: the refusal says why');
+        t.includes(git('readonly', ['status', '--porcelain']).stdout, '??', 'readonly: after the refused `git add` nothing has changed');
+        const none = git('none', ['status']);
+        t.check(none.status === 128 && none.stderr.includes('disabled'), 'none: every git call is refused', 'exit ' + none.status + ' ' + none.stderr);
+        t.section('Git Bash');
+        const gitRoot = path.dirname(path.dirname(realGit));
+        const bash = [path.join(gitRoot, 'bin', 'bash.exe'), path.join(gitRoot, 'usr', 'bin', 'bash.exe')].find((b) => fs.existsSync(b));
+        if (!bash) {
+            t.skip('Git Bash check (no bash.exe next to git)');
+            return;
+        }
+        const posix = (p) => p.replace(/\\/g, '/');
+        const bashEnv = t.write(t.at('gitshim', 'bashenv.sh'), 'git() { "' + posix(process.execPath) + '" "' + posix(guard) + '" "$@"; }\nexport -f git\n');
+        const viaBash = spawnSync(bash, ['-c', 'git commit -m x'], { cwd: repo, env: { ...env('readonly'), BASH_ENV: posix(bashEnv) }, encoding: 'utf8' });
+        t.check(viaBash.status === 128 && viaBash.stderr.includes('read-only'), 'readonly: git inside Git Bash goes through the guard too (BASH_ENV)', 'exit ' + viaBash.status + ' ' + viaBash.stderr);
+    },
+};

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

@@ -0,0 +1,2 @@
+import type { Suite } from './suite.js';
+export declare const liveProjectsSuite: Suite;