windows-development-sandbox 1.0.5 → 1.1.0

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;

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

@@ -0,0 +1,127 @@
+// Live: the real session daemon + ptyhost with two projects at once. The launch folder (A) and a project in a root
+// (B) each get two sessions requested at the same moment; each runs in its own folder with its own environment; B is
+// set up once for both; viewers attach, detach and reattach, two at a time; exec and restart follow the project.
+// Toolchain installers run as a dry run (no downloads); everything else is real. cmd.exe stands in for the agent.
+import fs from 'node:fs';
+import path from 'node:path';
+import { projectSpec } from '../host/join.js';
+import { resizeFrame } from '../shared/pty-client.js';
+import { readJsonFile } from '../shared/rundir.js';
+import { copyCmdAsFakeAgent, openViewer, sees, startDaemon, tail, viewersWhen } from './live.js';
+export const liveProjectsSuite = {
+    name: 'live-projects',
+    title: 'live: two projects, several sessions, several viewers',
+    live: true,
+    timeoutMs: 480000,
+    run: async (t, f) => {
+        const gen = await f.launch();
+        const data = t.at('live-multi-data');
+        const root = t.dir('live-root');
+        const projB = t.dir('live-root', 'projB');
+        copyCmdAsFakeAgent(data);
+        const session = f.readJson(gen.sessionPath);
+        // B's root appears at its own path here (like guestWorkspace "mirror"), so host and guest paths are the same.
+        Object.assign(session, { workspace: f.workA, attach: { enabled: true }, projectsDir: t.at('live-projects'), roots: [root], projectId: 'work-a' });
+        Object.assign(session.harness, { arguments: ['/d', '/k', 'echo AGENT-READY'], resumeArguments: ['/d', '/k', 'echo AGENT-RESUMED'] });
+        t.writeJson(gen.sessionPath, session);
+        const local = t.at('live-multi-local');
+        const daemon = startDaemon(t, f, { launchPath: gen.launchPath, data, workspace: f.workA, env: { AGENT_LOCAL_DIR: local, AGENT_DRY_RUN: '1', AGENT_MANAGED_DIR: t.at('live-managed') } });
+        const viewers = [];
+        const view = async (attach, cols = 100) => {
+            const v = await openViewer(attach, { cols });
+            viewers.push(v);
+            return v;
+        };
+        try {
+            t.section('live: four sessions at once');
+            const cfg = structuredClone(f.baseConfig);
+            cfg.toolchains.environment = { LIVE_B: 'b-env' };
+            const spec = projectSpec(await f.run({ cwd: projB, trustConfig: true }, cfg), { name: 'projB', host: projB, guest: projB, primary: false, mechanism: 'root', registeredAt: '' }, false);
+            // All four at the same moment: two in the launch folder, two in B (whose setup they share).
+            daemon.request({ kind: 'session', id: 'a1', harness: 'claude', args: [], cwd: f.workA });
+            daemon.request({ kind: 'session', id: 'b1', harness: 'claude', args: [], cwd: projB, project: spec });
+            daemon.request({ kind: 'session', id: 'b2', harness: 'claude', args: [], cwd: projB, project: spec });
+            daemon.request({ kind: 'session', id: 'a2', harness: 'claude', args: [], cwd: f.workA });
+            const [a1, a2, b1, b2] = await Promise.all(['a1', 'a2', 'b1', 'b2'].map((id) => daemon.started(id)));
+            const all = [a1, a2, b1, b2];
+            const notRunning = all.filter((s) => s?.phase !== 'running' || !s.attach);
+            t.check(notRunning.length === 0, 'four sessions requested at once all start (two per project)', notRunning.map((s) => s?.id + ': ' + s?.phase + ' ' + s?.message).join('\n') + '\n' + daemon.diagnostics());
+            if (notRunning.length > 0)
+                return;
+            t.equal([a1.project, b1.project, b2.project], ['work-a', 'projB', 'projB'], 'each session knows its project');
+            const log = fs.readdirSync(path.join(data, 'logs')).filter((n) => n.startsWith('daemon')).map((n) => fs.readFileSync(path.join(data, 'logs', n), 'utf8')).join('\n');
+            t.equal((log.match(/Project projB: setting up/g) ?? []).length, 1, 'two sessions for the same new project at once share one setup (no second provisioning run)');
+            t.equal(readJsonFile(path.join(daemon.run, 'projects', 'projB.json'))?.phase, 'ready', 'the project\'s setup status is written for the host (sandbox status)');
+            t.section('live: each session has its own folder and environment');
+            const views = await Promise.all(all.map((s) => view(s.attach)));
+            for (const v of views)
+                await sees(t, v, 'AGENT-READY');
+            for (const v of views)
+                v.type('echo P=%AGENT_PROJECT% W=%AGENT_WORKSPACE% B=[%LIVE_B%]');
+            const bSees = await sees(t, views[2], 'P=projB W=' + projB + ' B=[b-env]');
+            t.check(Boolean(bSees), 'B\'s first session runs with B\'s workspace, project and variables', tail(views[2].output()));
+            t.check(Boolean(await sees(t, views[3], 'B=[b-env]')), 'B\'s second session runs with B\'s variables', tail(views[3].output()));
+            // (The daemon here runs without the boot's environment, so A's own AGENT_* variables are not set at all.)
+            t.check(Boolean(await sees(t, views[0], 'B=[%LIVE_B%]')), 'A\'s first session is untouched by B (B\'s variables never reach it)', tail(views[0].output()));
+            t.check(Boolean(await sees(t, views[1], 'B=[%LIVE_B%]')), 'A\'s second session is untouched by B', tail(views[1].output()));
+            views[2].type('echo CWD=%CD%.');
+            t.check(Boolean(await sees(t, views[2], 'CWD=' + projB + '.')), 'B\'s session starts in B\'s folder', tail(views[2].output()));
+            t.section('live: several viewers on one session');
+            const second = await view(b1.attach, 60);
+            const two = await viewersWhen(t, b1.attach, (v) => v.viewers === 2);
+            t.check(two !== null, 'a second viewer attaches to the same session');
+            second.socket.write(resizeFrame(90, 25));
+            views[2].type('echo TWO-VIEWERS-OK');
+            t.check(Boolean(await sees(t, views[2], 'TWO-VIEWERS-OK')), 'the first viewer sees what it typed (after the second one resized)', tail(views[2].output()));
+            t.check(Boolean(await sees(t, second, 'TWO-VIEWERS-OK')), 'the second viewer sees it too', tail(second.output()));
+            second.type('echo FROM-SECOND');
+            t.check(Boolean(await sees(t, views[2], 'FROM-SECOND')), 'input from the second viewer reaches the agent and the first viewer', tail(views[2].output()));
+            views[2].close();
+            second.close();
+            const none = await viewersWhen(t, b1.attach, (v) => v.viewers === 0);
+            t.check(none !== null, 'closing every viewer is noticed');
+            t.equal(daemon.status('b1')?.phase, 'running', 'closing every viewer never ends the session');
+            for (let round = 1; round <= 3; round++) {
+                const again = await view(b1.attach);
+                again.type('echo REATTACHED-' + round);
+                t.check(Boolean(await sees(t, again, 'REATTACHED-' + round)), 'reattach ' + round + ': a new viewer works on the same session', tail(again.output()));
+                again.close();
+            }
+            t.section('live: exec, restart and refusals follow the projects');
+            daemon.request({ kind: 'exec', id: 'xb', command: ['echo', '%LIVE_B%'], cwd: projB, timeoutSeconds: 30 });
+            daemon.request({ kind: 'exec', id: 'xa', command: ['echo', '[%LIVE_B%]'], cwd: f.workA, timeoutSeconds: 30 });
+            const [xb, xa] = await Promise.all([daemon.response('xb'), daemon.response('xa')]);
+            t.check(Boolean(xb?.stdout?.includes('b-env')), 'exec in B\'s folder gets B\'s environment', JSON.stringify(xb));
+            t.check(Boolean(xa?.stdout?.includes('[%LIVE_B%]')), 'exec in A\'s folder gets A\'s', JSON.stringify(xa));
+            daemon.request({ kind: 'session', id: 'bad1', harness: 'claude', args: [], cwd: f.workB, project: { ...spec, name: 'outside', workspace: f.workB } });
+            const bad = await daemon.started('bad1');
+            t.check(bad?.phase === 'failed' && bad.message.includes('not visible inside the sandbox'), 'a project outside the launch folder, the roots and C:\\Projects is refused', JSON.stringify(bad));
+            daemon.request({ kind: 'session', id: 'bad2', harness: 'claude', args: [], cwd: f.workA, project: spec });
+            const claimed = await daemon.started('bad2');
+            t.includes(claimed?.message ?? '', 'not inside project projB', 'a session cannot claim a project its folder is not in');
+            daemon.request({ kind: 'restart', id: 'rb', harness: null, cwd: projB });
+            t.equal((await daemon.response('rb'))?.message, 'restarted 2 session(s)', 'restart scoped to a project restarts only its sessions');
+            t.check(fs.existsSync(path.join(local, 'projects', 'projB', 'shell.cmd')), 'sbx-shell projB has a shell script');
+            t.includes(fs.readFileSync(path.join(local, 'projects', 'projB', 'env.cmd'), 'utf8'), 'LIVE_B=b-env', 'sbx-shell projB opens with B\'s environment');
+            t.check(fs.existsSync(path.join(local, 'bin', 'sbx-shell.cmd')), 'sbx-shell is on the sandbox\'s PATH');
+        }
+        finally {
+            for (const v of viewers)
+                v.close();
+            // End every agent: a fresh viewer types exit into each still-running session.
+            for (const id of ['a1', 'a2', 'b1', 'b2']) {
+                const s = daemon.status(id);
+                if (s?.phase !== 'running' || !s.attach)
+                    continue;
+                try {
+                    const v = await openViewer(s.attach);
+                    v.type('exit');
+                    await t.waitFor(() => v.exitCode() !== null, 10000);
+                    v.close();
+                }
+                catch { /* already gone */ }
+            }
+            await daemon.stop();
+        }
+    },
+};

package/dist/selftest/live.d.ts

@@ -0,0 +1,65 @@
+import { type ChildProcess } from 'node:child_process';
+import type net from 'node:net';
+import type { GuestResponse, SessionStatus } from '../core/types.js';
+import { type Endpoint, type Viewers } from '../shared/pty-client.js';
+import type { Fixtures } from './fixtures.js';
+import type { Harness } from './harness.js';
+export declare const CSC: string;
+/** Live suites need Windows (ConPTY) and the .NET Framework compiler that ships with it. */
+export declare const liveTestsAvailable: () => boolean;
+/** Deadlines, in ms. Generous on purpose: they only matter when something is really wrong. */
+export declare const WAIT: {
+    readonly start: 120000;
+    readonly screen: 45000;
+    readonly response: 60000;
+    readonly viewers: 45000;
+    readonly exit: 45000;
+};
+export declare const tail: (text: string, chars?: number) => string;
+/** Connects, retrying until `ms`: a connection attempt can time out while the machine is busy. */
+export declare const connectPatiently: (endpoint: Endpoint, ms?: number) => Promise<net.Socket>;
+/** One connection to a session's ptyhost, collecting what the server sends. */
+export interface Viewer {
+    socket: net.Socket;
+    /** Everything the agent has printed since this viewer connected. */
+    output: () => string;
+    /** The exit code frame, once the agent ended. */
+    exitCode: () => number | null;
+    /** The error frame ("access denied"), if the server sent one. */
+    error: () => string;
+    /** True once the server closed the connection. */
+    closed: () => boolean;
+    type: (text: string) => void;
+    close: () => void;
+}
+/** Connects like a terminal tab would (`token` can be wrong on purpose) and says hello. */
+export declare const openViewer: (attach: Endpoint, options?: {
+    token?: string;
+    cols?: number;
+    rows?: number;
+}) => Promise<Viewer>;
+/** Polls until the viewer's screen shows `needle`. */
+export declare const sees: (t: Harness, viewer: Viewer, needle: string, ms?: number) => Promise<true | null>;
+/** Polls the session's viewer count until `accept` is satisfied; null when it never was. A query that gets no answer is retried. */
+export declare const viewersWhen: (t: Harness, attach: Endpoint, accept: (v: Viewers) => boolean, ms?: number) => Promise<Viewers | null>;
+export declare const copyCmdAsFakeAgent: (dataPath: string) => void;
+/** A real session daemon (guest runtime) working on a generated launch folder, driven through the run folder like the host does. */
+export interface LiveDaemon {
+    run: string;
+    child: ChildProcess;
+    request: (body: Record<string, unknown>) => void;
+    response: (id: string, ms?: number) => Promise<GuestResponse | null>;
+    status: (id: string) => SessionStatus | null;
+    /** Waits until a session has left "starting". */
+    started: (id: string, ms?: number) => Promise<SessionStatus | null>;
+    /** The daemon's stdout/stderr and its log files, for failure messages. */
+    diagnostics: () => string;
+    /** Ends the daemon. */
+    stop: () => Promise<void>;
+}
+export declare const startDaemon: (t: Harness, f: Fixtures, options: {
+    launchPath: string;
+    data: string;
+    workspace: string;
+    env?: Record<string, string>;
+}) => LiveDaemon;

package/dist/selftest/live.js

@@ -0,0 +1,109 @@
+// Helpers for the live suites: they run the real session daemon, ptyhost (ConPTY) and the compiled git shim on Windows.
+//
+// Timing rule: a live test never sleeps for a fixed time and never gives up early. It polls until the condition holds,
+// with a generous deadline (a busy machine, a cold csc.exe or an antivirus scan can make any step 10x slower), and a
+// failure prints what was seen (the viewer's screen, the daemon's log) so the cause is visible.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { ensureDir, sleep } from '../core/util.js';
+import { connect, encodeFrame, FrameReader, FrameType, helloFrame, queryViewers } from '../shared/pty-client.js';
+import { readJsonFile, writeJsonAtomic } from '../shared/rundir.js';
+const WINDIR = process.env.WINDIR ?? 'C:\\Windows';
+export const CSC = path.join(WINDIR, 'Microsoft.NET', 'Framework64', 'v4.0.30319', 'csc.exe');
+/** Live suites need Windows (ConPTY) and the .NET Framework compiler that ships with it. */
+export const liveTestsAvailable = () => process.platform === 'win32' && fs.existsSync(CSC);
+/** Deadlines, in ms. Generous on purpose: they only matter when something is really wrong. */
+export const WAIT = { start: 120000, screen: 45000, response: 60000, viewers: 45000, exit: 45000 };
+export const tail = (text, chars = 500) => (text.length > chars ? '...' + text.slice(-chars) : text).replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '');
+/** Connects, retrying until `ms`: a connection attempt can time out while the machine is busy. */
+export const connectPatiently = async (endpoint, ms = 60000) => {
+    const end = Date.now() + ms;
+    for (;;) {
+        try {
+            return await connect(endpoint, 10000);
+        }
+        catch (e) {
+            if (Date.now() >= end)
+                throw e;
+            await sleep(250);
+        }
+    }
+};
+/** Connects like a terminal tab would (`token` can be wrong on purpose) and says hello. */
+export const openViewer = async (attach, options = {}) => {
+    const socket = await connectPatiently({ ...attach, addresses: ['127.0.0.1'] });
+    const reader = new FrameReader();
+    let output = '';
+    let exitCode = null;
+    let error = '';
+    let closed = false;
+    socket.on('data', (chunk) => {
+        for (const frame of reader.push(chunk)) {
+            if (frame.type === FrameType.Output)
+                output += frame.payload.toString();
+            else if (frame.type === FrameType.Exit)
+                exitCode = frame.payload.readInt32LE(0);
+            else if (frame.type === FrameType.Error)
+                error = frame.payload.toString();
+        }
+    });
+    socket.on('error', () => undefined);
+    socket.on('close', () => { closed = true; });
+    socket.write(helloFrame(options.token ?? attach.token, options.cols ?? 100, options.rows ?? 30));
+    return {
+        socket,
+        output: () => output,
+        exitCode: () => exitCode,
+        error: () => error,
+        closed: () => closed,
+        type: (text) => { socket.write(encodeFrame(FrameType.Input, Buffer.from(text + '\r'))); },
+        close: () => socket.destroy(),
+    };
+};
+/** Polls until the viewer's screen shows `needle`. */
+export const sees = (t, viewer, needle, ms = WAIT.screen) => t.waitFor(() => viewer.output().includes(needle), ms);
+/** Polls the session's viewer count until `accept` is satisfied; null when it never was. A query that gets no answer is retried. */
+export const viewersWhen = (t, attach, accept, ms = WAIT.viewers) => t.waitFor(async () => {
+    const v = await queryViewers({ ...attach, addresses: ['127.0.0.1'] }, 5000);
+    return v && accept(v) ? v : null;
+}, ms);
+export const copyCmdAsFakeAgent = (dataPath) => {
+    const agentDir = path.join(dataPath, 'tools', 'agents', 'claude');
+    ensureDir(agentDir);
+    fs.copyFileSync(path.join(WINDIR, 'System32', 'cmd.exe'), path.join(agentDir, 'claude.exe'));
+};
+export const startDaemon = (t, f, options) => {
+    const { launchPath, data } = options;
+    const output = t.at(path.basename(data) + '-daemon.out');
+    const fd = fs.openSync(output, 'w');
+    const env = { ...process.env, AGENT_LAUNCH_DIR: launchPath, AGENT_DATA_DIR: data, AGENT_WORKSPACE: options.workspace, AGENT_LOCAL_DIR: f.at(path.basename(data) + '-local'), AGENT_LOG_PREFIX: 'daemon', AGENT_NO_TABS: '1', ...options.env };
+    const child = spawn(process.execPath, [path.join(launchPath, 'runtime', 'daemon.js')], { env, stdio: ['ignore', fd, fd], windowsHide: true });
+    let exited = false;
+    child.on('exit', () => { exited = true; });
+    const run = path.join(data, 'run');
+    const status = (id) => readJsonFile(path.join(run, 'sessions', id + '.json'));
+    return {
+        run,
+        child,
+        request: (body) => writeJsonAtomic(path.join(run, 'requests', body.id + '.json'), { createdAt: new Date().toISOString(), ...body }),
+        response: (id, ms = WAIT.response) => t.waitFor(() => readJsonFile(path.join(run, 'responses', id + '.json')), ms),
+        status,
+        started: (id, ms = WAIT.start) => t.waitFor(() => { const s = status(id); return s && s.phase !== 'starting' ? s : null; }, ms),
+        diagnostics: () => {
+            const logs = path.join(data, 'logs');
+            const files = fs.existsSync(logs) ? fs.readdirSync(logs).filter((n) => n.startsWith('daemon')) : [];
+            const logText = files.map((n) => fs.readFileSync(path.join(logs, n), 'utf8')).join('\n');
+            return 'daemon output: ' + tail(fs.readFileSync(output, 'utf8'), 600) + '\ndaemon log: ' + tail(logText, 1200);
+        },
+        stop: async () => {
+            if (!exited)
+                child.kill();
+            await t.waitFor(() => exited, 10000);
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* already closed */ }
+        },
+    };
+};

package/dist/selftest/local-config.test.d.ts

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