windows-development-sandbox 0.0.0-stage → 1.1.0

package/dist/cli/commands/repair/types.d.ts

@@ -0,0 +1,26 @@
+import type { UserError } from '../../../core/util.js';
+import type { Context } from '../context.js';
+export type RepairStatus = 'ok' | 'fixed' | 'needs-you' | 'warn' | 'skipped';
+export interface RepairResult {
+    name: string;
+    status: RepairStatus;
+    detail: string;
+}
+export interface RepairEnv {
+    ctx: Context;
+    running: boolean;
+    dataPath: string;
+    storageRoot: string;
+    toolsDir: string;
+    configError: UserError | null;
+}
+export interface RepairCheck {
+    name: string;
+    run: (env: RepairEnv) => Omit<RepairResult, 'name'>;
+}
+export declare const ok: (detail: string) => Omit<RepairResult, "name">;
+/** For fixes that must not touch folders a running sandbox may be using. */
+export declare const whileRunning: {
+    status: "skipped";
+    detail: string;
+};

package/dist/cli/commands/repair/types.js

@@ -0,0 +1,3 @@
+export const ok = (detail) => ({ status: 'ok', detail });
+/** For fixes that must not touch folders a running sandbox may be using. */
+export const whileRunning = { status: 'skipped', detail: 'a sandbox is running and may be using it; run repair again once it is closed' };

package/dist/cli/commands/restart.d.ts

@@ -0,0 +1,6 @@
+import type { SessionStatus } from '../../core/types.js';
+import { type NeedsRestart } from '../../host/projects.js';
+import { type Context } from './context.js';
+/** "2 sessions (claude in api, codex in web)". */
+export declare const describeSessions: (sessions: Pick<SessionStatus, "harness" | "cwd" | "project">[]) => string;
+export declare const offerRestart: (ctx: Context, needs: NeedsRestart[], then: () => Promise<number>) => Promise<number>;

package/dist/cli/commands/restart.js

@@ -0,0 +1,85 @@
+// The last way in for a folder the running sandbox cannot show (not in a project root, no `wsb share`): restart it
+// with that folder mapped as well. Only ever with your consent (a prompt, or --yes): it lists what will end, stops
+// the sandbox cleanly (history and claude-mem sync back as on any close), starts it again from the same launch
+// folder with the projects it had plus the new one, reopens the sessions it ended (continuing their conversations
+// where the agent supports it) and then starts the new project's session.
+import path from 'node:path';
+import _ from 'lodash';
+import { askYesNo } from '../../core/prompt.js';
+import { fail, safeText, sleep } from '../../core/util.js';
+import { currentSessions, execInSandbox } from '../../host/channel.js';
+import { isSandboxRunning } from '../../host/platform.js';
+import { readRegistry } from '../../host/projects.js';
+import { hostDirFor, projectForGuestDir } from '../../shared/projects.js';
+import { readSandboxStatus } from '../../shared/rundir.js';
+import { watcherRunning } from '../../sync/watcher.js';
+import { c } from '../colors.js';
+import { working } from '../progress.js';
+import { sandboxAlive } from './context.js';
+/** "2 sessions (claude in api, codex in web)". */
+export const describeSessions = (sessions) => sessions.length === 0 ? 'no sessions' : sessions.length + ' session' + (sessions.length === 1 ? '' : 's') + ' (' + sessions.map((s) => safeText(s.harness) + ' in ' + safeText(s.project ?? path.win32.basename(s.cwd))).join(', ') + ')';
+/** The command to run again with consent, for a non-interactive terminal. */
+const againWithYes = (ctx) => 'sandbox ' + (ctx.options.noAgent ? 'start' : ctx.options.harness ?? ctx.loaded.config.defaultHarness) + (ctx.options.terminal ? ' -t' : '') + ' --yes';
+/** Where each running session is on this PC, so it can be reopened after the restart. */
+const sessionsToReopen = (registry, sessions) => sessions.flatMap((s) => {
+    const project = projectForGuestDir([...registry.projects, ...registry.roots.map((r) => ({ ...r }))], s.cwd);
+    return project ? [{ harness: s.harness, hostDir: hostDirFor(project, s.cwd) }] : [];
+});
+/** Shuts the sandbox down and waits until it (and the background sync's final pass) is gone. */
+const stopAndWait = async (ctx) => {
+    const status = readSandboxStatus(ctx.dataPath);
+    await working('Stopping the sandbox (history syncs back)', async () => {
+        await execInSandbox(ctx.dataPath, ['C:\\Windows\\System32\\shutdown.exe', '/s', '/t', '0'], status?.guestWorkspace ?? 'C:\\', 30, sandboxAlive).catch(() => null);
+        for (let i = 0; i < 180 && isSandboxRunning(); i++)
+            await sleep(1000);
+        if (isSandboxRunning())
+            fail('The sandbox did not shut down within 3 minutes.', 'Close its window yourself, then run the command again.');
+        // The watcher syncs history back a few seconds after the window closes; the next start needs it gone.
+        for (let i = 0; i < 60 && watcherRunning(ctx.dataPath); i++)
+            await sleep(1000);
+    });
+};
+export const offerRestart = async (ctx, needs, then) => {
+    const folders = needs.map((n) => n.hostDir);
+    const registry = readRegistry(ctx.storageRoot) ?? fail('The running sandbox was started by an older version, so it cannot take another folder.', 'Stop it (sandbox stop) and start it again from ' + folders[0] + '.');
+    const primary = registry.projects.find((p) => p.primary) ?? fail('The running sandbox has no launch folder on record.', 'Stop it (sandbox stop) and start it again.');
+    const sessions = currentSessions(ctx.dataPath);
+    for (const need of needs)
+        console.log(c.yellow('Windows Sandbox cannot add ' + need.hostDir + ' while it runs: ' + need.reason + '.'));
+    console.log('A restart maps ' + (needs.length === 1 ? 'it' : 'them') + ' as well (and keeps ' + registry.projects.map((p) => p.host).join(', ') + '). ' +
+        (sessions.length ? describeSessions(sessions) + ' will end' : 'No session is running') + '; your files, tools, databases and logins are kept. It takes about a minute.');
+    for (const parent of _.uniq(folders.map((f) => path.dirname(f))))
+        console.log(c.dim('No restart next time for folders in ' + parent + ': sandbox projects roots add "' + parent + '"'));
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    if (!ctx.options.yes) {
+        if (!interactive)
+            fail('Not restarting without your consent.', 'Run it again with --yes to restart: ' + againWithYes(ctx));
+        if (!(await askYesNo('Restart the sandbox now?'))) {
+            console.log('Nothing changed.');
+            return 1;
+        }
+    }
+    const reopen = sessionsToReopen(registry, sessions);
+    const resume = reopen.length > 0 && (ctx.options.yes || (await askYesNo('Reopen the ' + reopen.length + ' session(s) afterwards (continuing their conversations where the agent supports it)?', true)));
+    await stopAndWait(ctx);
+    // Imported here: launch.ts imports this file.
+    const { launch, openSession, readySandbox } = await import('./launch.js');
+    const { joinHere } = await import('./project.js');
+    const keep = registry.projects.filter((p) => !p.primary && p.mechanism !== 'root').map((p) => p.host);
+    const relaunch = { ...ctx, options: { ...ctx.options, workspace: primary.host, harness: ctx.options.harness ?? ctx.options.sessions[0]?.harness, terminal: false, noAgent: false, newSession: true, passthrough: [], sessions: [] } };
+    await launch(relaunch, false, { extraProjects: [...keep, ...folders], autoSession: false, waitUntilReady: true });
+    const ready = await readySandbox(ctx.dataPath);
+    if (resume) {
+        for (const s of reopen) {
+            const at = { ...ctx, options: { ...ctx.options, workspace: s.hostDir, harness: s.harness, terminal: false, newSession: true, passthrough: [], sessions: [] } };
+            try {
+                const joined = await joinHere(at, ready);
+                await openSession(at, ready, joined, { attach: false, harness: s.harness, args: ctx.loaded.config.harnesses[s.harness]?.resumeArguments ?? [], reuse: false });
+            }
+            catch (e) {
+                console.warn(c.yellow('Could not reopen ' + s.harness + ' in ' + s.hostDir + ': ' + (e instanceof Error ? e.message : String(e))));
+            }
+        }
+    }
+    return then();
+};

package/dist/cli/commands/sessions.d.ts

@@ -0,0 +1,12 @@
+import { type Context } from './context.js';
+export declare const attach: (ctx: Context) => Promise<number>;
+export declare const sessions: (ctx: Context) => Promise<number>;
+export declare const status: (ctx: Context) => Promise<number>;
+export declare const exec: (ctx: Context) => Promise<number>;
+/** `sandbox db`: runs the sandbox's own `sbx-db` in this folder's project, which knows its database versions and ports. */
+export declare const db: (ctx: Context) => Promise<number>;
+/** Restarts this folder's project's sessions (--all: every session). */
+export declare const restart: (ctx: Context) => Promise<number>;
+export declare const stop: (ctx: Context) => Promise<number>;
+export declare const show: (ctx: Context) => number;
+export declare const hide: (ctx: Context) => Promise<number>;

package/dist/cli/commands/sessions.js

@@ -0,0 +1,257 @@
+// Working with a running sandbox: attach, sessions, status, exec, restart, stop, show/hide. Each knows which project
+// you run it from (project.ts): attach and sessions put that project's sessions first, exec and db run in it, restart
+// restarts its sessions, stop warns about the other projects' sessions.
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { select } from '@inquirer/prompts';
+import _ from 'lodash';
+import { askYesNo } from '../../core/prompt.js';
+import { activeAccount } from '../../host/accounts.js';
+import { execInSandbox, pickSession, pingSandbox, restartSessions, currentSessions, runningSessions, sessionsFirstIn } from '../../host/channel.js';
+import { sessionViewers } from '../../host/attach.js';
+import { insideSandbox, isSandboxRunning } from '../../host/platform.js';
+import { NeedsRestart, readRegistry } from '../../host/projects.js';
+import { guardedProjects, repoFindings } from '../../host/repo-guard.js';
+import { hideSandboxWindow, showSandboxWindow } from '../../host/window.js';
+import { isWithin, projectForGuestDir } from '../../shared/projects.js';
+import { listProjectStatus, listSessions, readSandboxStatus } from '../../shared/rundir.js';
+import { watcherRunning } from '../../sync/watcher.js';
+import { errMsg, fail, safeText, sleep } from '../../core/util.js';
+import { printJson, requireOnPc, requireRunning, sandboxAlive, table } from './context.js';
+import { attachHere, readySandbox } from './launch.js';
+import { hereDir, joinHere, locateHere, provisionJoined } from './project.js';
+import { working } from '../progress.js';
+import { ago, c, shortenMiddle, termWidth } from '../colors.js';
+const viewerText = (v) => (v === undefined ? '-' : v === null ? 'unknown (older session)' : v.remote + ' here, ' + (v.viewers - v.remote) + ' in sandbox');
+const projectOf = (projects, s) => s.project ?? projectForGuestDir(projects, s.cwd)?.name ?? '-';
+export const attach = async (ctx) => {
+    requireOnPc('attach');
+    requireRunning('Start one with: sandbox claude --terminal');
+    const ready = await readySandbox(ctx.dataPath);
+    const id = ctx.options.positionals[0];
+    if (!id && runningSessions(ctx.dataPath).length === 0)
+        await sleep(1500);
+    const here = locateHere(ctx, ready);
+    if (id)
+        return attachHere(ctx, pickSession(ctx.dataPath, id));
+    // Several sessions: choose, this folder's project first (the newest is the default).
+    const running = sessionsFirstIn(runningSessions(ctx.dataPath), here.guestDir);
+    if (running.length > 1 && process.stdin.isTTY && process.stdout.isTTY) {
+        const projects = readRegistry(ctx.storageRoot)?.projects ?? [];
+        const chosen = await select({
+            message: 'Which session?' + (here.project ? ' (' + here.project.name + ' first)' : ''),
+            choices: running.map((s) => ({ value: s.id, name: (here.guestDir && isWithin(here.guestDir, s.cwd) ? '* ' : '  ') + safeText(s.harness).padEnd(9) + ' ' + projectOf(projects, s).padEnd(16) + ' ' + ago(s.startedAt).padEnd(11) + ' ' + s.id })),
+        });
+        return attachHere(ctx, pickSession(ctx.dataPath, chosen));
+    }
+    return attachHere(ctx, pickSession(ctx.dataPath, undefined, here.guestDir));
+};
+/** Sessions with who is watching them; `here` marks the ones in the project of the current folder. */
+const listedSessions = async (ctx) => {
+    // Who is attached comes from each session itself, so a terminal that was closed is never counted.
+    const live = isSandboxRunning();
+    // Only this sandbox's sessions are asked (and at most MAX_QUERIED_SESSIONS): the sandbox writes these files.
+    const ask = new Set(live ? currentSessions(ctx.dataPath).map((s) => s.id) : []);
+    const here = live ? locateHere(ctx, readSandboxStatus(ctx.dataPath)) : { guestDir: null };
+    const projects = readRegistry(ctx.storageRoot)?.projects ?? [];
+    return Promise.all(listSessions(ctx.dataPath).map(async (s) => ({
+        ...s, projectName: projectOf(projects, s), here: Boolean(here.guestDir && isWithin(here.guestDir, s.cwd)),
+        ...(ask.has(s.id) ? { viewers: await sessionViewers(s) } : {}),
+    })));
+};
+export const sessions = async (ctx) => {
+    const list = await listedSessions(ctx);
+    if (printJson(ctx, list.map((s) => _.omit(s, 'attach'))))
+        return 0;
+    if (list.length === 0) {
+        console.log('No sessions. Start one with: sandbox claude');
+        return 0;
+    }
+    // This folder's project first, newest first within each group; harness, cwd and times are written by the sandbox.
+    const ordered = [..._.sortBy(list.filter((s) => s.here), (s) => s.startedAt).reverse(), ..._.sortBy(list.filter((s) => !s.here), (s) => s.startedAt).reverse()];
+    const folderWidth = Math.max(16, termWidth() - 80);
+    table([['', 'ID', 'AGENT', 'PROJECT', 'STATE', 'ATTACHED', 'FOLDER', 'STARTED'], ...ordered.map((s) => [
+            s.here ? '*' : '', s.id, safeText(s.harness), safeText(s.projectName ?? '-'), s.phase + (s.exitCode !== undefined ? ' (' + s.exitCode + ')' : ''), viewerText(s.viewers), shortenMiddle(safeText(s.cwd), folderWidth), ago(s.startedAt),
+        ])]);
+    if (list.some((s) => s.here))
+        console.log(c.dim('* = the project of this folder'));
+    return 0;
+};
+/** Running databases by port, from the sandbox's own `sbx-db list` (best effort: unknown when it does not answer). */
+const runningPorts = async (ctx, cwd) => {
+    try {
+        const r = await execInSandbox(ctx.dataPath, ['sbx-db', 'list'], cwd, 30, sandboxAlive);
+        return new Set((r.stdout ?? '').split(/\r?\n/).filter((l) => /\brunning\b/.test(l)).map((l) => Number(/port (\d+)/.exec(l)?.[1])).filter((n) => n > 0));
+    }
+    catch {
+        return null;
+    }
+};
+export const status = async (ctx) => {
+    const running = isSandboxRunning();
+    const sandbox = readSandboxStatus(ctx.dataPath);
+    const registry = running ? readRegistry(ctx.storageRoot) : null;
+    const ready = running && sandbox?.phase === 'ready';
+    const daemon = ready ? await pingSandbox(ctx.dataPath, sandboxAlive).then((r) => r.message, (e) => 'no answer (' + errMsg(e) + ')') : '-';
+    const here = running ? locateHere(ctx, sandbox) : { project: null, guestDir: null };
+    const sessionList = running ? await listedSessions(ctx) : [];
+    const provisioning = running ? listProjectStatus(ctx.dataPath) : [];
+    const ports = ready && sandbox ? await runningPorts(ctx, sandbox.guestWorkspace) : null;
+    const findings = repoFindings(ctx.dataPath);
+    const startedAt = Number(/^(\d+)-/.exec(registry?.launchId ?? sandbox?.launchId ?? '')?.[1]) || null;
+    const projects = (registry?.projects ?? []).map((p) => {
+        const prov = provisioning.find((s) => s.name.toLowerCase() === p.name.toLowerCase());
+        const own = sessionList.filter((s) => s.phase === 'running' && projectForGuestDir(registry?.projects ?? [], s.cwd)?.name === p.name);
+        return {
+            name: p.name, host: p.host, guest: p.guest, mechanism: p.mechanism, here: here.project?.name === p.name,
+            setup: prov ? { phase: prov.phase, message: safeText(prov.message) } : { phase: 'not set up yet', message: 'set up when you first start a session or command there' },
+            databases: (prov?.databases ?? []).map((d) => ({ database: safeText(d.database), port: d.port, state: ports ? (ports.has(d.port) ? 'running' : 'stopped') : 'unknown' })),
+            sessions: own.map((s) => ({ id: s.id, harness: safeText(s.harness), viewers: viewerText(s.viewers), started: s.startedAt })),
+            // With several guarded folders each finding starts with its folder.
+            repoGuard: findings.filter((f) => f.detail.toLowerCase().startsWith(p.host.toLowerCase() + ':')).map((f) => f.kind + ': ' + safeText(f.detail)),
+        };
+    });
+    const info = {
+        sandbox: {
+            running, phase: running ? sandbox?.phase ?? 'unknown' : 'stopped', message: sandbox?.message, headless: sandbox?.headless,
+            uptime: running && startedAt ? ago(startedAt).replace(' ago', '') : null, daemon, account: activeAccount(ctx.dataPath), syncWatcher: watcherRunning(ctx.dataPath),
+        },
+        here: { folder: hereDir(ctx), project: here.project?.name ?? null, guest: here.guestDir },
+        roots: registry?.roots ?? [],
+        projects,
+        otherSessions: sessionList.filter((s) => s.phase === 'running' && !projects.some((p) => p.sessions.some((x) => x.id === s.id))).map((s) => ({ id: s.id, harness: safeText(s.harness), cwd: safeText(s.cwd) })),
+        repoGuard: { guarded: guardedProjects(ctx.dataPath).length, findings: findings.map((f) => f.kind + ': ' + f.detail) },
+    };
+    if (printJson(ctx, info))
+        return 0;
+    const yesNo = (v) => (typeof v === 'boolean' ? (v ? 'yes' : 'no') : String(v ?? '-'));
+    table(Object.entries(info.sandbox).map(([k, v]) => [_.startCase(k), safeText(yesNo(v))]));
+    if (!running)
+        return 0;
+    console.log('\n' + c.bold('Projects') + c.dim('  (* = this folder: ' + info.here.folder + (info.here.project ? '' : ', not in this sandbox') + ')'));
+    for (const p of projects) {
+        console.log((p.here ? '* ' : '  ') + c.bold(p.name) + '  ' + p.host + '  ->  ' + p.guest + c.dim('  (' + (p.mechanism === 'launch' ? 'started from here' : p.mechanism === 'root' ? 'in a project root' : p.mechanism === 'boot' ? 'mapped at start' : 'wsb share') + ')'));
+        console.log('      setup: ' + p.setup.phase + (p.setup.phase === 'ready' ? '' : ' - ' + shortenMiddle(p.setup.message, termWidth() - 20)));
+        if (p.databases.length)
+            console.log('      databases: ' + p.databases.map((d) => d.database + ' :' + d.port + ' ' + d.state).join(', '));
+        for (const s of p.sessions)
+            console.log('      session ' + s.id + '  ' + s.harness + '  ' + s.viewers + '  ' + ago(s.started));
+        for (const f of p.repoGuard)
+            console.log('      ' + c.yellow('guard: ' + f));
+    }
+    for (const r of info.roots)
+        console.log('  root  ' + r.host + '  ->  ' + r.guest + c.dim('  (every project in it opens without a restart)'));
+    for (const s of info.otherSessions)
+        console.log('  session ' + s.id + '  ' + s.harness + '  ' + s.cwd);
+    console.log('\n' + c.bold('Repo guard') + '  ' + info.repoGuard.guarded + ' folder(s) guarded; ' + (findings.length ? c.yellow(findings.length + ' change(s) neutralised:') : 'nothing from the sandbox needed neutralising'));
+    for (const f of info.repoGuard.findings.slice(-10))
+        console.log('  ' + c.yellow(safeText(f)));
+    return 0;
+};
+/** What a command run in the sandbox printed (text from the sandbox: through safeText), or why it failed. */
+const printExecResult = (result) => {
+    if (result.stdout)
+        process.stdout.write(safeText(result.stdout));
+    if (result.stderr)
+        process.stderr.write(safeText(result.stderr));
+    if (!result.ok && !result.stdout && !result.stderr)
+        console.error(result.message);
+};
+/** The guest folder for this folder, joining the running sandbox (and setting the project up) when needed. */
+const guestFolderHere = async (ctx, what) => {
+    const ready = await readySandbox(ctx.dataPath);
+    try {
+        const joined = await joinHere(ctx, ready);
+        for (const note of joined.notes)
+            console.error(note);
+        await provisionJoined(ctx, joined);
+        return joined.guestDir;
+    }
+    catch (e) {
+        if (!(e instanceof NeedsRestart))
+            throw e;
+        return fail(hereDir(ctx) + ' is not in the running sandbox (' + e.reason + '), so "sandbox ' + what + '" cannot run there.', 'sandbox claude (or sandbox start) from that folder offers a restart that adds it; or add its parent folder as a root: sandbox projects roots add "' + path.dirname(e.hostDir) + '"');
+    }
+};
+export const exec = async (ctx) => {
+    const command = [...ctx.options.positionals, ...ctx.options.passthrough];
+    if (command.length === 0)
+        fail('No command given.', 'Usage: sandbox exec [--timeout <s>] -- <command> [args...]');
+    requireOnPc('exec');
+    requireRunning();
+    const cwd = await guestFolderHere(ctx, 'exec');
+    const result = await execInSandbox(ctx.dataPath, command, cwd, ctx.options.timeout, sandboxAlive);
+    if (!printJson(ctx, result))
+        printExecResult(result);
+    return result.exitCode ?? 1;
+};
+/** `sandbox db`: runs the sandbox's own `sbx-db` in this folder's project, which knows its database versions and ports. */
+export const db = async (ctx) => {
+    const [action = 'list', name] = ctx.options.positionals;
+    if (!['list', 'start', 'stop'].includes(action))
+        fail('Unknown db action "' + action + '".', 'Use: sandbox db  (list)  or  sandbox db start|stop <postgres|mysql|mongodb|redis|dynamodb>');
+    if (action !== 'list' && !name)
+        fail('Which database?', 'Usage: sandbox db ' + action + ' <postgres|mysql|mongodb|redis|dynamodb>');
+    // Already inside the sandbox: run the database tool here instead of asking the sandbox from outside.
+    if (insideSandbox())
+        return spawnSync(process.execPath, [path.join(ctx.packageRoot, 'dist', 'runtime', 'db.js'), action, ...(name ? [name] : [])], { stdio: 'inherit', windowsHide: true }).status ?? 1;
+    requireRunning('Start one with: sandbox start --database <name>');
+    const cwd = await guestFolderHere(ctx, 'db');
+    // Starting can download the database the first time.
+    const result = await working((action === 'list' ? 'Asking' : action === 'start' ? 'Starting' : 'Stopping') + ' the database' + (name ? ' ' + name : 's') + ' in the sandbox', () => execInSandbox(ctx.dataPath, ['sbx-db', action, ...(name ? [name] : [])], cwd, 1800, sandboxAlive));
+    printExecResult(result);
+    return result.exitCode ?? 1;
+};
+/** Restarts this folder's project's sessions (--all: every session). */
+export const restart = async (ctx) => {
+    requireOnPc('restart');
+    requireRunning();
+    const here = locateHere(ctx, readSandboxStatus(ctx.dataPath));
+    const scope = ctx.options.all || !here.project ? undefined : here.project.guest;
+    if (!scope && !ctx.options.all)
+        console.log(c.dim(hereDir(ctx) + ' is not a project of the running sandbox: restarting every session.'));
+    console.log((await working('Restarting the agents' + (scope ? ' of ' + here.project?.name : ''), () => restartSessions(ctx.dataPath, ctx.options.harness ?? null, sandboxAlive, scope))).message);
+    return 0;
+};
+export const stop = async (ctx) => {
+    requireOnPc('stop');
+    if (!isSandboxRunning()) {
+        console.log('No Windows Sandbox is running.');
+        return 0;
+    }
+    const sandbox = readSandboxStatus(ctx.dataPath) ?? fail('This sandbox was not started by this tool.', 'Close its window instead.');
+    // Stopping ends every project's sessions, not just this folder's: say which, and ask when others would end too.
+    const here = locateHere(ctx, sandbox);
+    const running = currentSessions(ctx.dataPath);
+    const others = running.filter((s) => !(here.guestDir && isWithin(here.project?.guest ?? here.guestDir, s.cwd)));
+    if (running.length)
+        console.log('Stopping ends ' + running.length + ' session(s): ' + running.map((s) => safeText(s.harness) + ' in ' + safeText(s.project ?? path.win32.basename(s.cwd))).join(', ') + '.');
+    if (others.length && !ctx.options.yes) {
+        // A script must never end other projects' sessions by accident: without a terminal to ask in, it needs --yes.
+        const interactive = process.stdin.isTTY && process.stdout.isTTY;
+        if (!interactive)
+            fail(others.length + ' of these sessions belong to other projects, so the sandbox was not stopped.', 'Stop it anyway with: sandbox stop --yes');
+        if (!(await askYesNo(others.length + ' of them belong to other projects. Stop the whole sandbox?'))) {
+            console.log('Nothing changed.');
+            return 1;
+        }
+    }
+    await working('Asking the sandbox to shut down', () => execInSandbox(ctx.dataPath, ['C:\\Windows\\System32\\shutdown.exe', '/s', '/t', '2'], sandbox.guestWorkspace, 30, sandboxAlive));
+    console.log('Sandbox is shutting down; history and claude-mem sync back when it closes.');
+    return 0;
+};
+export const show = (ctx) => {
+    requireOnPc('show');
+    requireRunning();
+    if (!showSandboxWindow(ctx.storageRoot))
+        fail('Could not find the Windows Sandbox window.', 'It may still be starting; try again in a few seconds.');
+    return 0;
+};
+export const hide = async (ctx) => {
+    requireOnPc('hide');
+    requireRunning();
+    if (!(await hideSandboxWindow(ctx.storageRoot, 5)))
+        fail('Could not find a visible Windows Sandbox window.', 'It may already be hidden (sbx-show brings it back).');
+    console.log('Sandbox window hidden. Bring it back with: sbx-show');
+    return 0;
+};

package/dist/cli/commands/setup/checks.d.ts

@@ -0,0 +1,13 @@
+import { type EditionSupport, type MachineFacts } from './facts.js';
+export type CheckStatus = 'ok' | 'warn' | 'action';
+export interface Check {
+    name: string;
+    status: CheckStatus;
+    detail: string;
+}
+/** Windows Sandbox needs Pro, Enterprise or Education (build 18305+); Home ("Core*") and Server cannot run it. */
+export declare const editionSupport: (edition: string | null) => EditionSupport;
+export declare const nodeMajor: (version: string) => number;
+/** Offer to enable the feature only when it is off and this edition can have it. */
+export declare const canEnableFeature: (f: MachineFacts) => boolean;
+export declare const buildChecks: (f: MachineFacts) => Check[];

package/dist/cli/commands/setup/checks.js

@@ -0,0 +1,71 @@
+// Turns what `sandbox setup` learnt about the PC into a checklist. Pure, so it can be tested.
+import { GB } from '../../../core/disk.js';
+import { ENABLE_COMMAND } from './facts.js';
+/** Windows Sandbox needs Pro, Enterprise or Education (build 18305+); Home ("Core*") and Server cannot run it. */
+export const editionSupport = (edition) => {
+    if (!edition)
+        return 'unknown';
+    if (/^Core/i.test(edition))
+        return 'home';
+    if (/^Server/i.test(edition))
+        return 'unsupported';
+    return /^(Professional|Enterprise|Education|IoTEnterprise)/i.test(edition) ? 'supported' : 'unknown';
+};
+export const nodeMajor = (version) => Number(/^v?(\d+)/.exec(version.trim())?.[1] ?? 0);
+/** Offer to enable the feature only when it is off and this edition can have it. */
+export const canEnableFeature = (f) => f.feature !== 'enabled' && f.feature !== 'pending' && !f.sandboxExe && ['supported', 'unknown'].includes(editionSupport(f.edition));
+const formatGb = (bytes) => (bytes / GB).toFixed(1) + ' GB';
+const check = (name, status, detail) => ({ name, status, detail });
+const editionCheck = (f) => {
+    const support = editionSupport(f.edition);
+    const edition = (f.edition ?? 'unknown edition') + (f.build ? ', build ' + f.build : '');
+    const name = 'Windows edition';
+    if (support === 'supported' && (f.build ?? 18305) >= 18305)
+        return check(name, 'ok', edition);
+    if (support === 'home')
+        return check(name, 'action', edition + ': Windows Home cannot run Windows Sandbox. Upgrade to Pro (Settings > System > Activation).');
+    if (support === 'unsupported')
+        return check(name, 'action', edition + ': Windows Sandbox needs Windows 10/11 Pro, Enterprise or Education.');
+    if (support === 'supported')
+        return check(name, 'action', edition + ': too old; Windows Sandbox needs Windows 10 version 1903 or newer.');
+    return check(name, 'warn', edition + ': not sure this edition has Windows Sandbox (it needs Pro, Enterprise or Education).');
+};
+const virtualizationCheck = (f) => {
+    const name = 'CPU virtualization';
+    const virt = f.hypervisorPresent || f.virtualizationFirmware;
+    if (virt)
+        return check(name, 'ok', f.hypervisorPresent ? 'on (hypervisor running)' : 'on');
+    if (virt === false)
+        return check(name, 'action', 'off. Turn on Intel VT-x / AMD-V (SVM) in your PC\'s BIOS/UEFI settings, then run this again.');
+    return check(name, 'warn', 'could not tell; if Windows Sandbox will not start, turn on VT-x / AMD-V in the BIOS/UEFI.');
+};
+const featureCheck = (f) => {
+    const name = 'Windows Sandbox feature';
+    if (f.feature === 'enabled' && f.sandboxExe)
+        return check(name, 'ok', 'enabled');
+    if (f.feature === 'pending' || f.feature === 'enabled')
+        return check(name, 'action', 'enabled, but Windows needs a restart to finish.');
+    if (f.sandboxExe)
+        return check(name, 'ok', 'installed');
+    return check(name, 'action', 'not enabled. In an admin PowerShell: ' + ENABLE_COMMAND + ', then restart.');
+};
+const memoryCheck = (f) => {
+    const gb = formatGb(f.totalRamBytes);
+    if (f.totalRamBytes < 4 * GB)
+        return check('Memory', 'action', gb + ': Windows Sandbox needs at least 4 GB.');
+    if (f.totalRamBytes < 8 * GB)
+        return check('Memory', 'warn', gb + ': works, but 8 GB or more is recommended.');
+    return check('Memory', 'ok', gb);
+};
+const diskCheck = (f) => {
+    if (f.freeDiskBytes === null)
+        return check('Free disk', 'warn', 'could not check the drive of ' + f.storageRoot);
+    const free = formatGb(f.freeDiskBytes) + ' free for ' + f.storageRoot;
+    if (f.freeDiskBytes < 5 * GB)
+        return check('Free disk', 'action', free + ': free up space (toolchains need several GB).');
+    if (f.freeDiskBytes < 20 * GB)
+        return check('Free disk', 'warn', free + ': getting low; toolchains and caches can use several GB.');
+    return check('Free disk', 'ok', free);
+};
+const nodeCheck = (f) => nodeMajor(f.nodeVersion) >= 20 ? check('Node.js', 'ok', f.nodeVersion) : check('Node.js', 'action', f.nodeVersion + ': needs 20 or newer (winget install OpenJS.NodeJS.LTS).');
+export const buildChecks = (f) => [editionCheck(f), virtualizationCheck(f), featureCheck(f), memoryCheck(f), diskCheck(f), nodeCheck(f)];

package/dist/cli/commands/setup/facts.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+export type FeatureState = 'enabled' | 'pending' | 'disabled' | 'unknown';
+export type EditionSupport = 'supported' | 'home' | 'unsupported' | 'unknown';
+export interface MachineFacts {
+    edition: string | null;
+    build: number | null;
+    feature: FeatureState;
+    /** WindowsSandbox.exe exists (it appears only after the restart that follows enabling the feature). */
+    sandboxExe: boolean;
+    virtualizationFirmware: boolean | null;
+    hypervisorPresent: boolean | null;
+    totalRamBytes: number;
+    freeDiskBytes: number | null;
+    storageRoot: string;
+    nodeVersion: string;
+}
+export declare const ENABLE_COMMAND: string;
+/** `reg query <key>` output to { valueName: data }. */
+export declare const parseRegQuery: (text: string) => Record<string, string>;
+/** The "State : ..." line of `Dism /Get-FeatureInfo` (English output only; anything else is unknown). */
+export declare const parseDismState: (text: string) => FeatureState;
+/** Win32_OptionalFeature.InstallState: 1 enabled, 2 disabled, 3 absent. */
+export declare const featureFromInstallState: (state: number | null | undefined) => FeatureState;
+declare const Probe: z.ZodObject<{
+    virtualizationFirmware: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    hypervisorPresent: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    installState: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+export declare const parseProbe: (text: string) => z.infer<typeof Probe>;
+export declare const gatherFacts: (storageRoot: string) => MachineFacts;
+export {};

package/dist/cli/commands/setup/facts.js

@@ -0,0 +1,60 @@
+// What `sandbox setup` learns about this PC: the Windows edition, CPU virtualization and the Windows Sandbox feature.
+import os from 'node:os';
+import _ from 'lodash';
+import { z } from 'zod';
+import { freeBytesAt } from '../../../core/disk.js';
+import { captureOutput, fileExists } from '../../../core/util.js';
+import { SYSTEM, system32 } from '../../../shared/system.js';
+const FEATURE = 'Containers-DisposableClientVM';
+export const ENABLE_COMMAND = 'Enable-WindowsOptionalFeature -Online -FeatureName ' + FEATURE + ' -All -NoRestart';
+/** `reg query <key>` output to { valueName: data }. */
+export const parseRegQuery = (text) => Object.fromEntries(_.compact(text.split(/\r?\n/).map((line) => /^\s+(\S+)\s+REG_\w+\s+(.*)$/.exec(line)?.slice(1, 3))));
+/** The "State : ..." line of `Dism /Get-FeatureInfo` (English output only; anything else is unknown). */
+export const parseDismState = (text) => {
+    const state = /^State\s*:\s*(.+?)\s*$/im.exec(text)?.[1].toLowerCase() ?? '';
+    if (state === 'enabled')
+        return 'enabled';
+    if (state.includes('pending'))
+        return 'pending';
+    return state.startsWith('disabled') ? 'disabled' : 'unknown';
+};
+/** Win32_OptionalFeature.InstallState: 1 enabled, 2 disabled, 3 absent. */
+export const featureFromInstallState = (state) => state === 1 ? 'enabled' : state === 2 || state === 3 ? 'disabled' : 'unknown';
+// Fixed script (no outside data): CPU/hypervisor facts and the feature state, readable without admin rights.
+const PROBE = [
+    '$ErrorActionPreference = "SilentlyContinue"',
+    '$cpu = @(Get-CimInstance Win32_Processor)',
+    '$cs = Get-CimInstance Win32_ComputerSystem',
+    '$f = Get-CimInstance Win32_OptionalFeature -Filter "Name=\'' + FEATURE + '\'"',
+    '$v = $null; if ($cpu.Count) { $v = [bool]($cpu | Where-Object { $_.VirtualizationFirmwareEnabled }) }',
+    '$h = $null; if ($cs) { $h = [bool]$cs.HypervisorPresent }',
+    '$s = $null; if ($f) { $s = [int]$f.InstallState }',
+    '@{ virtualizationFirmware = $v; hypervisorPresent = $h; installState = $s } | ConvertTo-Json -Compress',
+].join('; ');
+const Probe = z.object({ virtualizationFirmware: z.boolean().nullable(), hypervisorPresent: z.boolean().nullable(), installState: z.number().nullable() }).partial();
+export const parseProbe = (text) => {
+    try {
+        return Probe.parse(JSON.parse(_.last(text.trim().split(/\r?\n/)) ?? ''));
+    }
+    catch {
+        return {};
+    }
+};
+export const gatherFacts = (storageRoot) => {
+    const reg = parseRegQuery(captureOutput(SYSTEM.reg(), ['query', 'HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion']));
+    const probe = parseProbe(captureOutput(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-Command', PROBE]));
+    // DISM knows about a pending restart but needs admin rights; the CIM state works for everyone.
+    const dism = parseDismState(captureOutput(SYSTEM.dism(), ['/English', '/Online', '/Get-FeatureInfo', '/FeatureName:' + FEATURE]));
+    return {
+        edition: reg.EditionID ?? null,
+        build: Number(reg.CurrentBuildNumber ?? reg.CurrentBuild) || null,
+        feature: dism === 'unknown' ? featureFromInstallState(probe.installState) : dism,
+        sandboxExe: fileExists(system32('WindowsSandbox.exe')),
+        virtualizationFirmware: probe.virtualizationFirmware ?? null,
+        hypervisorPresent: probe.hypervisorPresent ?? null,
+        totalRamBytes: os.totalmem(),
+        freeDiskBytes: freeBytesAt(storageRoot),
+        storageRoot,
+        nodeVersion: process.version,
+    };
+};

package/dist/cli/commands/setup/index.d.ts

@@ -0,0 +1,2 @@
+import { type Context } from '../context.js';
+export declare const setup: (ctx: Context) => Promise<number>;

package/dist/cli/commands/setup/index.js

@@ -0,0 +1,43 @@
+// `sandbox setup`: checks this PC can run Windows Sandbox and offers to turn the feature on.
+import { spawnSync } from 'node:child_process';
+import { askYesNo } from '../../../core/prompt.js';
+import { fail, isWin } from '../../../core/util.js';
+import { refuseInSelfTest } from '../../../host/test-guard.js';
+import { SYSTEM } from '../../../shared/system.js';
+import { c } from '../../colors.js';
+import { table } from '../context.js';
+import { buildChecks, canEnableFeature } from './checks.js';
+import { ENABLE_COMMAND, gatherFacts } from './facts.js';
+const LABEL = { ok: c.green('OK'), warn: c.yellow('WARNING'), action: c.red('ACTION NEEDED') };
+const print = (checks) => table(checks.map((check) => [LABEL[check.status], check.name, check.detail]));
+/** Runs the enable command in an elevated PowerShell (Windows asks for permission); true if it worked. */
+const enableFeature = () => {
+    refuseInSelfTest('turn on Windows features');
+    const inner = "'-NoProfile','-Command','" + ENABLE_COMMAND + " | Out-Null'";
+    const outer = "try { $p = Start-Process -FilePath '" + SYSTEM.powershell() + "' -Verb RunAs -Wait -PassThru -WindowStyle Hidden -ArgumentList " + inner + '; exit $p.ExitCode } catch { exit 1 }';
+    return spawnSync(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-Command', outer], { stdio: 'inherit' }).status === 0;
+};
+export const setup = async (ctx) => {
+    if (!isWin)
+        fail('Windows Sandbox only runs on Windows.', 'Run sandbox setup on a Windows 10/11 Pro, Enterprise or Education PC.');
+    console.log('Checking this PC for Windows Sandbox...\n');
+    const facts = gatherFacts(ctx.storageRoot);
+    let checks = buildChecks(facts);
+    print(checks);
+    if (canEnableFeature(facts)) {
+        console.log('');
+        if (await askYesNo('Turn on Windows Sandbox now? Windows will ask for admin permission.')) {
+            console.log('Enabling Windows Sandbox (this can take a minute)...');
+            if (!enableFeature())
+                fail('Windows Sandbox could not be enabled (or the admin prompt was declined).', 'In an admin PowerShell run: ' + ENABLE_COMMAND + ', then restart Windows.');
+            console.log('Done. Restart Windows to finish, then run sandbox setup again.\n');
+            checks = buildChecks(gatherFacts(ctx.storageRoot));
+            print(checks);
+        }
+        else
+            console.log('To do it yourself, in an admin PowerShell run:\n  ' + ENABLE_COMMAND + '\nthen restart Windows.');
+    }
+    const todo = checks.filter((check) => check.status === 'action').length;
+    console.log('\n' + (todo ? todo + ' thing(s) to fix before the sandbox can start (see ACTION NEEDED above).' : 'This PC is ready. cd into a project and run sandbox claude (or sandbox for no agent).'));
+    return todo ? 1 : 0;
+};