windows-development-sandbox 1.0.5 → 1.1.0

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

@@ -0,0 +1,61 @@
+// `sandbox repair`: finds and fixes common problems. Each check (checks.ts) either confirms all is well (OK), fixes the
+// problem itself (FIXED), or says what you need to do (NEEDS YOU). Toolchain and run-state fixes wait until no
+// sandbox is running.
+import path from 'node:path';
+import _ from 'lodash';
+import { DEFAULTS, loadConfig, userDir } from '../../../core/config.js';
+import { errMsg, expandPath, UserError } from '../../../core/util.js';
+import { isSandboxRunning } from '../../../host/platform.js';
+import { createContext, printJson, table } from '../context.js';
+import { CHECKS } from './checks.js';
+const LABEL = { ok: 'OK', fixed: 'FIXED', 'needs-you': 'NEEDS YOU', warn: 'WARNING', skipped: 'SKIPPED' };
+/** Runs every check in order; a check that throws is reported, never stops the rest. */
+export const runChecks = (env, checks = CHECKS) => checks.map((check) => {
+    try {
+        return { name: check.name, ...check.run(env) };
+    }
+    catch (e) {
+        const fix = e instanceof UserError && e.fix ? ' ' + e.fix : '';
+        return { name: check.name, status: 'needs-you', detail: 'check failed: ' + errMsg(e) + fix };
+    }
+});
+export const repair = (ctx, configError = null) => {
+    const env = { ctx, running: isSandboxRunning(), dataPath: ctx.dataPath, storageRoot: ctx.storageRoot, toolsDir: path.join(ctx.dataPath, 'tools'), configError };
+    // Re-check the config file even when the context loaded (it may have been edited since, or come from --config).
+    if (!env.configError) {
+        try {
+            loadConfig(ctx.options.config);
+        }
+        catch (e) {
+            if (e instanceof UserError)
+                env.configError = e;
+            else
+                throw e;
+        }
+    }
+    const results = runChecks(env);
+    if (printJson(ctx, results))
+        return results.some((r) => r.status === 'needs-you') ? 1 : 0;
+    table(results.map((r) => [LABEL[r.status], r.name, r.detail]));
+    const counts = _.countBy(results, 'status');
+    console.log('\n' + (counts['needs-you'] ? counts['needs-you'] + ' thing(s) need you (see NEEDS YOU above).' : 'All good' + (counts.fixed ? ': fixed ' + counts.fixed + ' problem(s).' : '.')));
+    return counts['needs-you'] ? 1 : 0;
+};
+/**
+ * Entry point that works even when the config file is broken (createContext would throw): falls back to the built-in
+ * defaults so the other checks still run, and reports the config problem as the first check.
+ */
+export const repairCommand = (packageRoot, entry, options) => {
+    let ctx;
+    try {
+        ctx = createContext(packageRoot, entry, options);
+    }
+    catch (e) {
+        if (!(e instanceof UserError))
+            throw e;
+        const loaded = { config: structuredClone(DEFAULTS), configPath: null, base: userDir() };
+        const storageRoot = expandPath(loaded.config.storage.root, loaded.base);
+        return repair({ packageRoot, entry, options, loaded, storageRoot, dataPath: path.join(storageRoot, 'data', loaded.config.storage.dataName) }, e);
+    }
+    return repair(ctx);
+};

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

@@ -3,8 +3,9 @@ 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`, which knows this project's database versions and ports. */
+/** `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;

package/dist/cli/commands/sessions.js

@@ -1,110 +1,254 @@
-// Working with a running sandbox: attach, sessions, status, exec, restart, stop, show/hide.
+// 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, sessionViewers, waitForReady } from '../../host/channel.js';
-import { isSandboxRunning } from '../../host/platform.js';
-import { repoFindings } from '../../host/repo-guard.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 { listSessions, readSandboxStatus } from '../../shared/rundir.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 { currentGuestDir, printJson, requireRunning, sandboxAlive, table } from './context.js';
-import { attachHere } from './launch.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');
-    await waitForReady(ctx.dataPath, null, sandboxAlive);
+    const ready = await readySandbox(ctx.dataPath);
     const id = ctx.options.positionals[0];
     if (!id && runningSessions(ctx.dataPath).length === 0)
         await sleep(1500);
-    return attachHere(ctx, pickSession(ctx.dataPath, id));
+    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));
 };
-const viewerText = (v) => (v === undefined ? '-' : v === null ? 'unknown (older session)' : v.remote + ' here, ' + (v.viewers - v.remote) + ' in sandbox');
-// harness, cwd and times are written by the sandbox: printed through safeText.
-const sessionRow = (s) => [s.id, safeText(s.harness), s.phase + (s.exitCode !== undefined ? ' (' + s.exitCode + ')' : ''), viewerText(s.viewers), safeText(s.cwd), safeText(new Date(s.startedAt).toLocaleTimeString())];
-export const sessions = async (ctx) => {
+/** 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 list = await Promise.all(listSessions(ctx.dataPath).map(async (s) => (ask.has(s.id) ? { ...s, viewers: await sessionViewers(s) } : s)));
+    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.');
-    else
-        table([['ID', 'AGENT', 'STATE', 'ATTACHED', 'FOLDER', 'STARTED'], ...list.map(sessionRow)]);
+    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 daemon = running && sandbox?.phase === 'ready' ? await pingSandbox(ctx.dataPath, sandboxAlive).then((r) => r.message, (e) => 'no answer (' + errMsg(e) + ')') : '-';
+    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 = {
-        running, phase: running ? sandbox?.phase ?? 'unknown' : 'stopped', message: sandbox?.message, workspace: sandbox?.workspaceHost, headless: sandbox?.headless,
-        daemon, account: activeAccount(ctx.dataPath), sessions: running ? runningSessions(ctx.dataPath).length : 0, syncWatcher: watcherRunning(ctx.dataPath),
-        repoGuard: findings.length ? findings.map((x) => x.kind + ': ' + x.detail).join('; ') : 'nothing from the sandbox needed neutralising',
+        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))
-        table(Object.entries(info).map(([k, v]) => [_.startCase(k), safeText(String(v ?? '-'))]));
+    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 ready = await waitForReady(ctx.dataPath, null, sandboxAlive);
-    const result = await execInSandbox(ctx.dataPath, command, currentGuestDir(ctx, ready.workspaceHost, ready.guestWorkspace), ctx.options.timeout, sandboxAlive);
-    if (!printJson(ctx, 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);
-    }
+    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`, which knows this project's database versions and ports. */
+/** `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 ready = await waitForReady(ctx.dataPath, null, sandboxAlive);
+    const cwd = await guestFolderHere(ctx, 'db');
     // Starting can download the database the first time.
-    const result = await execInSandbox(ctx.dataPath, ['sbx-db', action, ...(name ? [name] : [])], ready.guestWorkspace, 1800, sandboxAlive);
-    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);
+    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();
-    console.log((await restartSessions(ctx.dataPath, ctx.options.harness ?? null, sandboxAlive)).message);
+    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.');
-    await execInSandbox(ctx.dataPath, ['C:\\Windows\\System32\\shutdown.exe', '/s', '/t', '2'], sandbox.guestWorkspace, 30, sandboxAlive);
+    // 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).');

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.d.ts → setup/facts.d.ts}

@@ -1,11 +1,4 @@
 import { z } from 'zod';
-import { type Context } from './context.js';
-export type CheckStatus = 'ok' | 'warn' | 'action';
-export interface Check {
-    name: string;
-    status: CheckStatus;
-    detail: string;
-}
 export type FeatureState = 'enabled' | 'pending' | 'disabled' | 'unknown';
 export type EditionSupport = 'supported' | 'home' | 'unsupported' | 'unknown';
 export interface MachineFacts {
@@ -24,22 +17,15 @@ export interface MachineFacts {
 export declare const ENABLE_COMMAND: string;
 /** `reg query <key>` output to { valueName: data }. */
 export declare const parseRegQuery: (text: string) => Record<string, 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;
 /** 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;
-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;
-/** Turns what we learnt about the PC into the checklist (pure, so it can be tested). */
-export declare const buildChecks: (f: MachineFacts) => Check[];
 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 setup: (ctx: Context) => Promise<number>;
+export declare const gatherFacts: (storageRoot: string) => MachineFacts;
 export {};