windows-development-sandbox 0.0.0-stage → 1.1.0

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

@@ -0,0 +1,45 @@
+// `sandbox data`: what persists between sandboxes (toolchains, databases, agent state, logs, host storage) and
+// removing chosen parts of it. Everything under the data folder is sandbox-writable: sizes and deletes never follow
+// links, and targets resolve strictly inside the data folder.
+import _ from 'lodash';
+import { diskUsage, humanBytes } from '../../../core/disk.js';
+import { fail } from '../../../core/util.js';
+import { printJson, table } from '../context.js';
+import { working } from '../../progress.js';
+import { dataClean } from './clean.js';
+import { collectDataEntries } from './collect.js';
+const AREA_LABEL = { tools: 'Toolchains', databases: 'Databases', state: 'Agent state', logs: 'Logs', data: 'Other', host: 'On this PC' };
+export const dataInfo = async (ctx) => {
+    const entries = await working('Measuring the saved data (big folders take a moment)', () => collectDataEntries(ctx.dataPath, ctx.storageRoot), !ctx.options.json);
+    const total = _.sumBy(entries, 'bytes');
+    const disks = diskUsage(ctx.storageRoot);
+    if (printJson(ctx, { dataPath: ctx.dataPath, storageRoot: ctx.storageRoot, totalBytes: total, entries, disks }))
+        return 0;
+    console.log('Disks\n');
+    table([['DRIVE', 'USED', 'FREE', 'SIZE', ''], ...disks.map((d) => [d.drive, humanBytes(d.usedBytes) + ' (' + Math.round((d.usedBytes / d.totalBytes) * 100) + '%)', humanBytes(d.freeBytes), humanBytes(d.totalBytes), d.holdsStorage ? '<- sandbox storage (' + humanBytes(total) + ' of it)' : ''])]);
+    console.log('');
+    console.log('Persistent data for the sandbox: ' + ctx.dataPath + ' (C:\\AgentData inside)\n');
+    if (!entries.length) {
+        console.log('Nothing stored yet. Toolchains, databases and agent logins appear here after the first start.');
+        return 0;
+    }
+    const rows = _.flatMap(_.groupBy(entries, 'area'), (group, area) => [
+        [AREA_LABEL[area], humanBytes(_.sumBy(group, 'bytes')), ''],
+        ...group.map((e) => ['  ' + e.name, humanBytes(e.bytes), e.path]),
+    ]);
+    table([...rows, ['', '', ''], ['Total', humanBytes(total), '']]);
+    console.log('\nFree space with: sandbox data clean <target...>  (e.g. tools/go, databases/postgres-18, logs, launches)');
+    return 0;
+};
+/** `sandbox data [info|clean] [targets...]`. */
+export const data = (ctx) => {
+    const [action = 'info'] = ctx.options.positionals;
+    switch (action) {
+        case 'info':
+        case 'show':
+        case 'list': return dataInfo(ctx);
+        case 'clean':
+        case 'remove': return dataClean(ctx);
+        default: return fail('Unknown data action "' + action + '".', 'Use: sandbox data  (what is stored)  or  sandbox data clean <target...>');
+    }
+};

package/dist/cli/commands/data/remove.d.ts

@@ -0,0 +1,2 @@
+/** Deletes p (strictly inside root): links inside are removed first and never followed; see shared/safe-remove.ts. */
+export declare const removeTree: (p: string, root: string) => void;

package/dist/cli/commands/data/remove.js

@@ -0,0 +1,30 @@
+// Deleting inside the data folder. The sandbox can write there, so links are removed themselves and never followed.
+import fs from 'node:fs';
+import path from 'node:path';
+import { dirExists, isLink, removeLink } from '../../../core/util.js';
+import { removeRefusal, safeRemove } from '../../../shared/safe-remove.js';
+/** Deletes p (strictly inside root): links inside are removed first and never followed; see shared/safe-remove.ts. */
+export const removeTree = (p, root) => {
+    const unlinkInside = (dir) => {
+        for (const d of fs.readdirSync(dir, { withFileTypes: true })) {
+            const child = path.join(dir, d.name);
+            if (d.isSymbolicLink() || isLink(child))
+                removeLink(child);
+            else if (d.isDirectory())
+                unlinkInside(child);
+        }
+    };
+    if (isLink(p)) {
+        removeLink(p);
+        return;
+    }
+    if (!fs.existsSync(p))
+        return;
+    // Refused before anything is touched (safeRemove below checks again).
+    const refusal = removeRefusal(p, root);
+    if (refusal)
+        throw new Error('Refusing to delete ' + p + ': ' + refusal);
+    if (dirExists(p))
+        unlinkInside(p);
+    safeRemove(p, root);
+};

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

@@ -0,0 +1,10 @@
+export { createContext, type Context } from './context.js';
+export { launch } from './launch.js';
+export { setup } from './setup/index.js';
+export { data } from './data/index.js';
+export { repairCommand } from './repair/index.js';
+export { attach, db, exec, hide, restart, sessions, show, status, stop } from './sessions.js';
+export { account } from './accounts.js';
+export { projects } from './projects.js';
+export { claudeHost, clean, config, doctor, logs, sync, watcher } from './maintenance.js';
+export { agentCommandsCommand, syncAgentCommands } from './agent-commands.js';

package/dist/cli/commands/index.js

@@ -0,0 +1,10 @@
+export { createContext } from './context.js';
+export { launch } from './launch.js';
+export { setup } from './setup/index.js';
+export { data } from './data/index.js';
+export { repairCommand } from './repair/index.js';
+export { attach, db, exec, hide, restart, sessions, show, status, stop } from './sessions.js';
+export { account } from './accounts.js';
+export { projects } from './projects.js';
+export { claudeHost, clean, config, doctor, logs, sync, watcher } from './maintenance.js';
+export { agentCommandsCommand, syncAgentCommands } from './agent-commands.js';

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

@@ -0,0 +1,29 @@
+import { attachTerminal } from '../../host/attach.js';
+import type { SandboxStatus } from '../../core/types.js';
+import { type Context } from './context.js';
+import { type Joined } from './project.js';
+/** Attaches this terminal; with attach.autoHide the sandbox window hides meanwhile (best effort, never fails the attach). */
+export declare const attachHere: (ctx: Context, session: Parameters<typeof attachTerminal>[0]) => Promise<number>;
+/** The sandbox writes sandbox.json a few seconds into its boot; a second launch right after the first waits for it. */
+export declare const runningSandboxStatus: (dataPath: string) => Promise<SandboxStatus>;
+/** Waits for the boot with its current step on a spinner (plain lines without a terminal). */
+export declare const waitForBoot: (dataPath: string, launchId: string | null) => Promise<SandboxStatus>;
+/** The running sandbox, once it is ready. */
+export declare const readySandbox: (dataPath: string) => Promise<SandboxStatus>;
+/**
+ * Starts (or picks back up) a session in the folder `joined` describes. attach: show it in this terminal.
+ * Exported for restart.ts, which reopens the sessions a restart ended.
+ */
+export declare const openSession: (ctx: Context, ready: SandboxStatus, joined: Joined, o: {
+    attach: boolean;
+    harness?: string;
+    args?: string[];
+    reuse?: boolean;
+}) => Promise<number>;
+/** A restart that adds a project: map these too, start no session at boot (restart.ts opens them), wait until ready. */
+export interface LaunchExtras {
+    extraProjects?: string[];
+    autoSession?: boolean;
+    waitUntilReady?: boolean;
+}
+export declare const launch: (ctx: Context, generateOnly?: boolean, extras?: LaunchExtras) => Promise<number>;

package/dist/cli/commands/launch.js

@@ -0,0 +1,333 @@
+// `launch` / `generate`, and what sandbox claude runs: start a sandbox, or another session in the running one. From a
+// folder the running sandbox does not have yet, the folder joins it (no restart) when it can, and otherwise a
+// restart that adds it is offered (restart.ts).
+import path from 'node:path';
+import fs from 'node:fs';
+import { select } from '@inquirer/prompts';
+import { activateAccount, activeAccount, defaultAccount } from '../../host/accounts.js';
+import { attachTerminal, findUnwatchedSession } from '../../host/attach.js';
+import { requestSession, resetRunDir, waitForReady, waitForSession } from '../../host/channel.js';
+import { describePrune, pruneStorage } from '../../host/cleanup.js';
+import { generateSandbox } from '../../host/generate.js';
+import { findSecretFiles } from '../../host/secrets.js';
+import { checkRepo, saveRepoSnapshot } from '../../host/repo-guard.js';
+import { assertCanLaunch, insideSandbox, isSandboxRunning, probeHost, spawnDetached, startSandbox } from '../../host/platform.js';
+import { NeedsRestart, rememberProject, startRegistry } from '../../host/projects.js';
+import { ensureTerminal } from '../../host/terminal.js';
+import { hideSandboxWindow, showSandboxWindow } from '../../host/window.js';
+import { readSandboxStatus } from '../../shared/rundir.js';
+import { isWithin } from '../../shared/projects.js';
+import { syncBeforeLaunch, watcherRunning } from '../../sync/watcher.js';
+import { protectionsOf } from '../../core/project-policy.js';
+import { assertSafeMapping, assertSafeWorkspace } from '../../core/safe-paths.js';
+import { errMsg, fail, isRootPath, sleep } from '../../core/util.js';
+import { syncAgentCommands } from './agent-commands.js';
+import { askYesNo } from '../../core/prompt.js';
+import { resolveRun } from '../../core/workspace.js';
+import { c } from '../colors.js';
+import { working } from '../progress.js';
+import { requireOnPc, sandboxAlive, table } from './context.js';
+import _ from 'lodash';
+import { hereDir, joinHere, readyHere } from './project.js';
+import { offerRestart } from './restart.js';
+import { addToList, setSetting } from './user-config.js';
+/** Attaches this terminal; with attach.autoHide the sandbox window hides meanwhile (best effort, never fails the attach). */
+export const attachHere = (ctx, session) => {
+    if (ctx.loaded.config.attach.autoHide && !insideSandbox())
+        void hideSandboxWindow(ctx.storageRoot, 120).catch(() => false);
+    return attachTerminal(session);
+};
+/** Nothing has been installed into this data set yet: the first start downloads every toolchain once. */
+const firstBoot = (dataPath) => !fs.existsSync(path.join(dataPath, 'tools', 'resolved-versions.json'));
+const FIRST_BOOT = 'First start for this storage: the sandbox downloads and installs the toolchains, databases and agent this project needs.\n' +
+    'That takes a few minutes, once. Everything is kept, so every later start reuses it and takes seconds.';
+/** The sandbox writes sandbox.json a few seconds into its boot; a second launch right after the first waits for it. */
+export const runningSandboxStatus = async (dataPath) => {
+    for (let i = 0; i < 60; i++) {
+        const status = readSandboxStatus(dataPath);
+        if (status)
+            return status;
+        await sleep(1000);
+    }
+    return fail('A Windows Sandbox is running that this tool did not start (or that uses another storage.dataName).', 'Close that sandbox window first, then run sandbox claude again.');
+};
+/** Waits for the boot with its current step on a spinner (plain lines without a terminal). */
+export const waitForBoot = (dataPath, launchId) => {
+    let step = 'starting Windows Sandbox';
+    return working(() => 'Waiting for the sandbox: ' + step, () => waitForReady(dataPath, launchId, sandboxAlive, (m) => { step = m; }));
+};
+/** The running sandbox, once it is ready. */
+export const readySandbox = async (dataPath) => {
+    const status = await runningSandboxStatus(dataPath);
+    return status.phase === 'ready' ? status : waitForBoot(dataPath, status.launchId);
+};
+/** Waits for a session to start (its project's setup, the agent's install) with its progress on a spinner. */
+const waitForStart = (ctx, requestId, what) => {
+    let step = 'starting';
+    return working(() => what + ': ' + step, () => waitForSession(ctx.dataPath, requestId, sandboxAlive, 60 * 60 * 1000, (m) => { step = m; }));
+};
+/**
+ * Starts (or picks back up) a session in the folder `joined` describes. attach: show it in this terminal.
+ * Exported for restart.ts, which reopens the sessions a restart ended.
+ */
+export const openSession = async (ctx, ready, joined, o) => {
+    const { options, loaded, dataPath } = ctx;
+    const cwd = joined.guestDir;
+    const harness = o.harness ?? options.harness ?? joined.harness ?? loaded.config.defaultHarness;
+    const args = o.args ?? options.passthrough;
+    // -t with nothing new for the agent: pick up this folder's session if no terminal on this PC shows it (its tab was
+    // closed, or you detached). Someone already attached, --new, or agent arguments: a new session, as before.
+    const reuse = (o.reuse ?? true) && o.attach && !options.newSession && args.length === 0 && loaded.config.attach.reuseSession;
+    const existing = reuse ? await findUnwatchedSession(dataPath, harness, cwd) : null;
+    if (existing) {
+        console.log('Reattaching to ' + harness + ' session ' + existing.id + ' in ' + cwd + ' (no other terminal is attached; --new starts another).');
+        return attachHere(ctx, existing);
+    }
+    console.log(joined.spec
+        ? 'Starting ' + harness + ' for ' + joined.project?.host + ' in the running sandbox (' + cwd + '; the first time sets up what it needs).'
+        : 'Sandbox already running: starting another ' + harness + ' session in ' + cwd);
+    // The agent's definition goes along: the sandbox may have booted with another agent.
+    const harnessSpec = loaded.config.harnesses[harness];
+    const requestId = requestSession(dataPath, harness, args, cwd, { ...(joined.spec ? { project: joined.spec } : {}), ...(harnessSpec ? { harnessSpec } : {}) });
+    const session = await waitForStart(ctx, requestId, 'Starting ' + harness + ' in ' + cwd);
+    if (o.attach)
+        return attachHere(ctx, session);
+    console.log('Session ' + session.id + ' opened in a new tab inside the sandbox. Attach here with: sandbox attach ' + session.id + (ready.headless ? '   (headless: sbx-show opens the window)' : ''));
+    return 0;
+};
+/** The sessions a launch asks for: each --session, else one (the agent, in this folder). */
+const wantedSessions = (ctx) => ctx.options.sessions.length ? ctx.options.sessions : [{ harness: ctx.options.harness, folder: hereDir(ctx) }];
+/** The same command, for one of its sessions (its folder, agent, and the arguments after -- plus its own). */
+const contextFor = (ctx, want) => ({ ...ctx, options: { ...ctx.options, workspace: want.folder, harness: want.harness, sessions: [], passthrough: [...ctx.options.passthrough, ...(want.args ?? [])] } });
+/** Several sessions at once: all requested together (projects set up in parallel), then listed; -t attaches the first. */
+const openSessions = async (ctx, ready, list) => {
+    const { dataPath, loaded, options } = ctx;
+    const requests = list.map(({ ctx: at, joined }) => {
+        const harness = at.options.harness ?? joined.harness ?? loaded.config.defaultHarness;
+        const harnessSpec = loaded.config.harnesses[harness];
+        const id = requestSession(dataPath, harness, at.options.passthrough, joined.guestDir, { ...(joined.spec ? { project: joined.spec } : {}), ...(harnessSpec ? { harnessSpec } : {}) });
+        return { id, harness, folder: at.options.workspace ?? joined.guestDir, cwd: joined.guestDir };
+    });
+    let started = 0;
+    const results = await working(() => 'Starting ' + requests.length + ' sessions (' + started + ' running)', () => Promise.allSettled(requests.map(async (r) => {
+        const s = await waitForSession(dataPath, r.id, sandboxAlive, 60 * 60 * 1000, () => undefined);
+        started++;
+        return s;
+    })));
+    table([['SESSION', 'AGENT', 'FOLDER', ''], ...requests.map((r, i) => {
+            const result = results[i];
+            return [r.id, r.harness, r.folder, result.status === 'fulfilled' ? 'running   sandbox attach ' + r.id : c.red('FAILED: ' + errMsg(result.reason))];
+        })]);
+    const first = results.find((r) => r.status === 'fulfilled');
+    if (options.terminal && first)
+        return attachHere(ctx, first.value);
+    if (!first)
+        return 1;
+    console.log('Each has its own tab inside the sandbox' + (ready.headless ? ' (headless: sbx-show opens the window)' : '') + '. Attach to any of them, from any terminal: sandbox attach');
+    return results.every((r) => r.status === 'fulfilled') ? 0 : 1;
+};
+/** A sandbox is already running: open the sessions in it (new tabs inside; optionally attach here). */
+const launchIntoRunning = async (ctx) => {
+    const ready = await readySandbox(ctx.dataPath);
+    const wants = wantedSessions(ctx);
+    // Every folder joins first: when one needs a restart, nothing has been started that the restart would end.
+    const joined = [];
+    const needs = [];
+    for (const want of wants) {
+        const at = ctx.options.sessions.length ? contextFor(ctx, want) : ctx;
+        try {
+            joined.push({ ctx: at, joined: await joinHere(at, ready) });
+        }
+        catch (e) {
+            if (!(e instanceof NeedsRestart))
+                throw e;
+            if (!needs.some((n) => n.hostDir.toLowerCase() === e.hostDir.toLowerCase()))
+                needs.push(e);
+        }
+    }
+    if (needs.length)
+        return offerRestart(ctx, needs, () => launchIntoRunning(ctx));
+    for (const note of _.uniq(joined.flatMap((j) => j.joined.notes)))
+        console.log(note);
+    if (joined.length === 1)
+        return openSession(joined[0].ctx, ready, joined[0].joined, { attach: ctx.options.terminal });
+    return openSessions(ctx, ready, joined);
+};
+/** `sandbox start` while one runs: this folder joins it (set up, no agent), or a restart that adds it is offered. */
+const startIntoRunning = async (ctx) => {
+    const ready = await readySandbox(ctx.dataPath);
+    let joined;
+    try {
+        joined = await readyHere(ctx, ready);
+    }
+    catch (e) {
+        if (e instanceof NeedsRestart)
+            return offerRestart(ctx, [e], () => startIntoRunning(ctx));
+        throw e;
+    }
+    const where = joined.spec ? ' This folder is ready in it as ' + joined.guestDir + ' (sbx-shell ' + joined.spec.name + ' opens a terminal there inside).' : '';
+    console.log('A sandbox is already running' + (showSandboxWindow(ctx.storageRoot) ? '; its window is in front now.' : '.') + where + ' Start an agent in it with sandbox claude (or sandbox <agent>); stop it with sandbox stop.');
+    return 0;
+};
+const syncSummary = (config, dataPath, workspaceHost) => {
+    try {
+        const s = syncBeforeLaunch(config, dataPath, workspaceHost);
+        return s.history + ' file(s) of history in, claude-mem ' + s.claudeMem;
+    }
+    catch (e) {
+        return 'FAILED: ' + errMsg(e);
+    }
+};
+/**
+ * Asked once per parent folder: map it at every start (a project root), so the projects next to this one open in the
+ * running sandbox without a restart. The answer is saved to your config.
+ */
+const maybeAddRoot = async (ctx, run) => {
+    const { projects } = run.config;
+    const parent = path.dirname(run.workspaceHost);
+    if (!projects.askToAddRoot || ctx.options.yes || !process.stdin.isTTY || !process.stdout.isTTY)
+        return;
+    if (projects.roots.some((r) => isWithin(r, run.workspaceHost)) || projects.declinedRoots.some((d) => isWithin(d, parent) && isWithin(parent, d)))
+        return;
+    if (isRootPath(parent))
+        return;
+    try {
+        assertSafeWorkspace(parent, ctx.packageRoot, run.storageRoot);
+        assertSafeMapping(parent, ctx.packageRoot, run.storageRoot);
+    }
+    catch {
+        return;
+    }
+    const answer = await select({
+        message: 'Map ' + parent + ' at every start, so other projects there (also new ones) open in the running sandbox without a restart? Agents in the sandbox can then see every project in it.',
+        choices: [
+            { name: 'Yes, from now on', value: 'yes' },
+            { name: 'No (and do not ask again for this folder)', value: 'no' },
+            { name: 'Never ask this again', value: 'never' },
+        ],
+    });
+    if (answer === 'yes') {
+        addToList(ctx, ['projects', 'roots'], parent);
+        run.config.projects.roots.push(parent);
+        console.log('Added ' + parent + ' to projects.roots (sandbox projects roots remove ' + parent + ' undoes it).');
+    }
+    if (answer === 'no')
+        addToList(ctx, ['projects', 'declinedRoots'], parent);
+    if (answer === 'never')
+        setSetting(ctx, ['projects', 'askToAddRoot'], false);
+};
+/** Everything a real launch does before the sandbox starts (skipped by `generate`, which only writes files). */
+const prepare = async (ctx, run) => {
+    const { options, dataPath, storageRoot } = ctx;
+    const { config } = run;
+    const account = options.account ?? defaultAccount(storageRoot);
+    if (account && run.harnessName === 'claude' && account !== activeAccount(dataPath))
+        activateAccount(storageRoot, dataPath, account);
+    const terminal = config.provisioning.terminal.enabled ? await ensureTerminal(dataPath, config.provisioning.refresh, { pwsh: config.toolchains.pwsh.enabled !== false }) : { exe: null, message: 'disabled' };
+    const history = syncSummary(config, dataPath, run.workspaceHost);
+    const guarded = checkRepo(dataPath);
+    if (guarded.length)
+        console.warn(c.yellow('SECURITY: neutralised ' + guarded.length + ' change(s) the last sandbox made that could run code on this PC (see sandbox status).'));
+    resetRunDir(dataPath);
+    return { account, terminal: terminal.message, history, pruned: describePrune(pruneStorage(storageRoot)) };
+};
+export const launch = async (ctx, generateOnly = false, extras = {}) => {
+    const { options, loaded, packageRoot, dataPath, storageRoot } = ctx;
+    // attach.auto: an agent started from an interactive terminal attaches it, as with -t.
+    if (loaded.config.attach.auto && !options.noAgent && process.stdin.isTTY && process.stdout.isTTY)
+        options.terminal = true;
+    if (!generateOnly)
+        requireOnPc('launch');
+    // agentCommands (Beta) follows the config: a setting changed in the file takes effect here too. Never blocks a launch.
+    if (!generateOnly) {
+        try {
+            syncAgentCommands(ctx, loaded.config);
+        }
+        catch (e) {
+            console.warn('Agent commands (Beta): ' + errMsg(e));
+        }
+    }
+    if (!generateOnly && isSandboxRunning())
+        return options.noAgent ? startIntoRunning(ctx) : launchIntoRunning(ctx);
+    // Several sessions: the sandbox starts from the first one's folder with the others' folders mapped too, then
+    // they all open in it (each project is set up on demand, in parallel). One --session is an ordinary launch.
+    const wants = options.sessions;
+    if (wants.length === 1)
+        return launch(contextFor(ctx, wants[0]), generateOnly, extras);
+    if (wants.length > 1) {
+        const first = contextFor(ctx, wants[0]);
+        const others = _.uniqBy(wants.slice(1).map((w) => w.folder).filter((f) => !isWithin(wants[0].folder, f)), (f) => f.toLowerCase());
+        const started = await launch({ ...first, options: { ...first.options, terminal: false } }, generateOnly, { ...extras, extraProjects: [...(extras.extraProjects ?? []), ...others], autoSession: false, waitUntilReady: true });
+        return generateOnly || started !== 0 ? started : launchIntoRunning(ctx);
+    }
+    const run = await resolveRun({
+        packageRoot, loaded, cwd: process.cwd(), workspace: options.workspace, harness: options.harness, noAgent: options.noAgent,
+        noLocalConfig: options.noLocalConfig, trustConfig: options.trustConfig, scripts: options.scripts, databases: options.databases, headless: options.headless,
+        nodeVersion: options.node, pythonVersion: options.python, ask: askYesNo,
+    });
+    const { config } = run;
+    if (!generateOnly)
+        assertCanLaunch();
+    if (!generateOnly && !extras.extraProjects)
+        await maybeAddRoot(ctx, run);
+    const prepared = generateOnly ? null : await prepare(ctx, run);
+    const generated = generateSandbox({ packageRoot, run, harnessArgs: options.passthrough, probe: probeHost(config, run.harnessName), extraProjects: extras.extraProjects, autoSession: extras.autoSession });
+    for (const note of [...run.notes, ...generated.projects.notes])
+        console.log(note);
+    const secretFiles = config.secrets.warnFiles ? findSecretFiles(run.workspaceHost) : [];
+    if (secretFiles.length) {
+        const shown = secretFiles.slice(0, 12).join(', ') + (secretFiles.length > 12 ? ', ...' : '');
+        console.warn(c.yellow('Heads-up: the agent can read these files in your workspace, which often hold secrets: ' + shown + '. Move real credentials out of the folder (or use test ones). Silence with secrets.warnFiles = false.'));
+    }
+    const { roots, projects } = generated.projects;
+    table([
+        ['Workspace', run.workspaceHost + '  ->  ' + config.guestWorkspace + (config.readOnly ? '  (read-only)' : '')],
+        ['Agent', run.harnessName + (prepared?.account ? '  (account: ' + prepared.account + ')' : '') + '   Memory: ' + generated.memoryMb + ' MB   CPU: ' + (config.sandbox.cpuLimit === 'none' ? 'all' : 'max ' + config.sandbox.cpuLimit + '%') + '   Network: ' + config.sandbox.networking + (config.sandbox.headless ? '   HEADLESS' : '')],
+        ['Node', run.versions.node.spec + ' (' + run.versions.node.source + ')   Python: ' + run.versions.python.spec + ' (' + run.versions.python.source + ')'],
+        ...(prepared ? [['Terminal', prepared.terminal], ['History', prepared.history], ['Cleanup', prepared.pruned]] : []),
+        ['Toolchains', Object.entries(generated.toolchains).filter(([, d]) => d.on).map(([name, d]) => name + ' (' + d.reason + ')').join(', ') || 'Node only (nothing else used by this project)'],
+        ...(generated.databases.length
+            ? generated.databases.map((d, i) => [i ? '' : 'Databases', d.database + (d.database === 'sqlserver' ? ' (cannot run in the sandbox; use Postgres or SQLite for local work)' : ' on port ' + d.port) + '  because ' + d.reasons[0] + (d.reasons.length > 1 ? ' (+' + (d.reasons.length - 1) + ' more)' : '')])
+            : [['Databases', 'none needed (databases.<name>.enabled = true adds one)']]),
+        ['Desktop', generated.personalization],
+        ['Claude', generated.profile.staged.length ? generated.profile.staged.join(', ') + (generated.profile.credentials ? '  (INCLUDING YOUR LOGIN)' : '') : 'no settings copied'],
+        ['Secrets', !config.secrets.strip ? 'NOT stripped (secrets.strip is off)' : generated.profile.secretsRemoved.length ? 'kept on this PC: ' + generated.profile.secretsRemoved.join(', ') + '  (secrets.allow lets one through)' : 'none found in what is copied'],
+        ...roots.map((r, i) => [i ? '' : 'Project roots', r.host + '  ->  ' + r.guest + '  (every project in it opens without a restart)']),
+        ...projects.map((p, i) => [i ? '' : 'Projects', p.host + '  ->  ' + p.guest]),
+        ...generated.mappings.slice(3).filter((m) => ![...roots, ...projects].some((p) => p.guest === m.guest)).map((m) => ['  map ' + (m.readOnly ? 'ro' : 'rw'), m.host + '  ->  ' + m.guest]),
+        ['Generated', generated.wsbPath],
+    ]);
+    if (generateOnly)
+        return 0;
+    // Every folder the sandbox can write is snapshotted before it starts (the guard compares against this), and the
+    // projects it starts with are recorded host-side for the commands that run later.
+    saveRepoSnapshot(dataPath, run.workspaceHost, projects.map((p) => p.host), roots.map((r) => r.host));
+    startRegistry(storageRoot, { launchId: generated.launchId, protections: protectionsOf(config), primary: { host: run.workspaceHost, guest: config.guestWorkspace }, roots, boot: projects });
+    rememberProject(storageRoot, run.workspaceHost);
+    startSandbox(generated.wsbPath);
+    // Absolute: the watcher runs from another folder, and a relative --config there would make it exit silently.
+    if (!watcherRunning(dataPath))
+        spawnDetached(ctx.entry, ['_watch', ...(options.config ? ['--config', path.resolve(options.config)] : [])]);
+    // Hiding runs alongside; a failure to find the window must never break the launch or an attach.
+    const hidden = config.sandbox.headless ? hideSandboxWindow(storageRoot).catch(() => false) : null;
+    if (options.terminal || options.noAgent || extras.waitUntilReady) {
+        if (firstBoot(dataPath))
+            console.log(FIRST_BOOT);
+        await waitForBoot(dataPath, generated.launchId);
+        if (extras.waitUntilReady)
+            return 0;
+        // Without an agent there is no session to attach to: the sandbox itself is the result.
+        if (options.noAgent) {
+            console.log('Sandbox ready. Its window has a terminal in ' + config.guestWorkspace + '; from here: sandbox exec -- <command>, sandbox stop.');
+            return 0;
+        }
+        return attachHere(ctx, await waitForStart(ctx, generated.launchId, 'Starting ' + run.harnessName));
+    }
+    if (firstBoot(dataPath))
+        console.log(FIRST_BOOT);
+    if (hidden)
+        console.log(await hidden ? 'Sandbox running headless. Open the window: sbx-show   Attach here: sandbox claude -t' : 'Could not find the sandbox window to hide (it may still be starting); run sandbox hide in a moment.');
+    else
+        console.log('Sandbox starting. ' + run.harnessName + ' opens in Windows Terminal inside it. Attach here any time: sandbox claude -t');
+    return 0;
+};

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

@@ -0,0 +1,8 @@
+import { type Context } from './context.js';
+export declare const sync: (ctx: Context) => number;
+export declare const logs: (ctx: Context) => Promise<number>;
+export declare const clean: (ctx: Context) => number;
+export declare const config: (ctx: Context) => number;
+export declare const doctor: (ctx: Context) => number;
+export declare const claudeHost: (ctx: Context) => number;
+export declare const watcher: (ctx: Context) => Promise<void>;

package/dist/cli/commands/maintenance.js

@@ -0,0 +1,154 @@
+// sync, logs, clean, config, doctor, host-claude and the internal sync watcher.
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import _ from 'lodash';
+import { DEFAULTS, userConfigPath, userDir } from '../../core/config.js';
+import { describeOverrides, isTrusted, LOCAL_CONFIG_NAME, normalizeOverrides, readLocalConfig, trustStorePath } from '../../core/local-config.js';
+import { expandPath, fail, safeText, sleep, writeJson } from '../../core/util.js';
+import { readKnown, readRegistry } from '../../host/projects.js';
+import { detectWsb } from '../../host/wsb.js';
+import { describePrune, pruneStorage } from '../../host/cleanup.js';
+import { doctorRows, hostClaude, insideSandbox, isSandboxRunning } from '../../host/platform.js';
+import { readSandboxStatus } from '../../shared/rundir.js';
+import { syncBack, watch } from '../../sync/watcher.js';
+import { table } from './context.js';
+export const sync = (ctx) => {
+    const running = isSandboxRunning();
+    const result = syncBack(ctx.dataPath, !running);
+    console.log('History: ' + result.history + ' item(s) synced back. claude-mem: ' + result.claudeMem + (running ? ' (claude-mem syncs when the sandbox closes)' : ''));
+    return 0;
+};
+const newestLog = (dir) => {
+    if (!fs.existsSync(dir))
+        return null;
+    const logs = fs.readdirSync(dir).filter((f) => /^(guest|daemon|bootstrap)-.*\.log$/.test(f) && fs.lstatSync(path.join(dir, f)).isFile());
+    const newest = _.maxBy(logs, (f) => fs.statSync(path.join(dir, f)).mtimeMs);
+    return newest ? path.join(dir, newest) : null;
+};
+export const logs = async (ctx) => {
+    const dir = path.join(ctx.dataPath, 'logs');
+    const file = newestLog(dir) ?? fail('No sandbox logs yet in ' + dir + '.', 'Logs appear after the first start (sandbox claude).');
+    console.log('== ' + file + ' ==');
+    let printed = 0;
+    // The log is written inside the sandbox: read only its tail, and make it safe for your terminal.
+    const print = () => {
+        const size = fs.statSync(file).size;
+        const from = printed === 0 ? Math.max(0, size - 64 * 1024) : printed;
+        if (size <= from)
+            return;
+        const fd = fs.openSync(file, 'r');
+        const buffer = Buffer.alloc(Math.min(size - from, 4 * 1024 * 1024));
+        fs.readSync(fd, buffer, 0, buffer.length, from);
+        fs.closeSync(fd);
+        const text = safeText(buffer.toString('utf8'));
+        process.stdout.write(printed === 0 ? text.split('\n').slice(-120).join('\n') : text);
+        printed = from + buffer.length;
+    };
+    print();
+    if (ctx.options.follow)
+        console.error('(following; Ctrl+C to stop)');
+    while (ctx.options.follow) {
+        await sleep(1000);
+        print();
+    }
+    return 0;
+};
+export const clean = (ctx) => {
+    const running = isSandboxRunning() ? readSandboxStatus(ctx.dataPath)?.launchId : undefined;
+    console.log('Cleanup: ' + describePrune(pruneStorage(ctx.storageRoot, { launchDays: ctx.options.days, keep: _.compact([running]) })));
+    return 0;
+};
+const initConfig = () => {
+    const file = userConfigPath();
+    if (fs.existsSync(file))
+        fail(file + ' already exists.');
+    fs.mkdirSync(path.join(userDir(), 'hooks', 'pre-agent'), { recursive: true });
+    // The schema sits next to the file (a local path), so editors trust it and show docs and autocomplete.
+    writeJson(file, { $schema: './config.schema.json', ...DEFAULTS });
+    console.log('Created ' + file + '. It lists every setting with its default; delete the ones you do not change.');
+    console.log('Your own hook scripts go in ' + path.join(userDir(), 'hooks') + '\\{pre-provision,pre-agent,post-agent}.');
+    console.log('For editor help in every project\'s .sandbox-config.json, run: sandbox config schema');
+    return 0;
+};
+/**
+ * VS Code setting that maps every .sandbox-config.json (and the user config) to the local schema files, so project
+ * files need no "$schema" line and nothing is fetched from the internet (remote schemas need trusting).
+ */
+const printSchemaSettings = () => {
+    const url = (name) => pathToFileURL(path.join(userDir(), name)).href;
+    const setting = {
+        'json.schemas': [
+            { fileMatch: ['**/.sandbox-config.json'], url: url('sandbox-config.schema.json') },
+            { fileMatch: ['**/.agent-sandbox/config.json'], url: url('config.schema.json') },
+        ],
+    };
+    console.log('Add this to your VS Code settings.json (Ctrl+Shift+P > "Preferences: Open User Settings (JSON)"):\n');
+    console.log(JSON.stringify(setting, null, 2).slice(2, -2));
+    console.log('\nThe schema files live in ' + userDir() + ' and are refreshed whenever the sandbox command runs.');
+    return 0;
+};
+/**
+ * `sandbox config check`: the folder's .sandbox-config.json validated and described (risky settings flagged, approval
+ * state), without launching. Fails with the same message a launch would give when the file is not valid.
+ */
+const checkLocalConfig = (ctx) => {
+    const dir = path.resolve(ctx.options.workspace ?? process.cwd());
+    const file = readLocalConfig(dir);
+    if (!file) {
+        console.log('No ' + LOCAL_CONFIG_NAME + ' in ' + dir + '; the sandbox uses your own settings only.');
+        return 0;
+    }
+    const overrides = normalizeOverrides(file.data, dir, file.path);
+    const approved = isTrusted(trustStorePath(ctx.storageRoot), file.path, file.hash);
+    console.log(file.path + ': valid. ' + (approved ? 'Approved (this exact version).' : 'Not approved yet: the next launch asks you.') + '\n');
+    for (const line of describeOverrides(overrides))
+        console.log('  ' + safeText(line));
+    return 0;
+};
+export const config = (ctx) => {
+    const [action = 'summary'] = ctx.options.positionals;
+    switch (action) {
+        case 'summary':
+            table([
+                ['Settings file', ctx.loaded.configPath ?? userConfigPath() + '  (does not exist yet; sandbox config init creates it)'],
+                ['Default agent', ctx.loaded.config.defaultHarness],
+                ['Storage', ctx.storageRoot],
+                ['Memory', String(ctx.loaded.config.sandbox.memoryMb) + (ctx.loaded.config.sandbox.memoryMb === 'auto' ? '' : ' MB')],
+            ]);
+            console.log('\nChange settings in the menu (sandbox > Settings). All of them as JSON: sandbox config show');
+            return 0;
+        case 'path':
+            console.log(ctx.loaded.configPath ?? userConfigPath() + '  (does not exist yet)');
+            return 0;
+        case 'init': return initConfig();
+        case 'show':
+            console.log(JSON.stringify(ctx.loaded.config, null, 2));
+            return 0;
+        case 'schema': return printSchemaSettings();
+        case 'check': return checkLocalConfig(ctx);
+        default: fail('Unknown config action "' + action + '".', 'Use one of: sandbox config show | path | init | schema | check');
+    }
+};
+export const doctor = (ctx) => {
+    const rows = doctorRows(ctx.loaded.config, ctx.options.harness ?? ctx.loaded.config.defaultHarness, ctx.storageRoot, ctx.loaded.configPath);
+    // Inside a sandbox the feature and "running" rows describe the sandbox itself, and the host rows describe nothing useful.
+    if (insideSandbox()) {
+        table([['Where', 'inside a Windows Sandbox started by this tool (run doctor on your PC to check the PC)'], ...rows.filter(([name]) => name === 'Config file')]);
+        return 0;
+    }
+    // Several projects: the roots mapped at every start, what the running sandbox has, and whether wsb share is there.
+    const p = ctx.loaded.config.projects;
+    const registry = isSandboxRunning() ? readRegistry(ctx.storageRoot) : null;
+    const wsb = p.wsbShare ? detectWsb() : null;
+    table([
+        ...rows,
+        ['Project roots', p.roots.length ? p.roots.map((r) => expandPath(r, ctx.loaded.base)).join(', ') : 'none (sandbox projects roots add <folder>)'],
+        ['All projects', p.all ? 'on: ' + readKnown(ctx.storageRoot).length + ' known project(s) mapped at every start (' + p.exclude.length + ' excluded)' : 'off'],
+        ['Projects running', registry ? registry.projects.map((x) => x.name + ' (' + x.mechanism + ')').join(', ') : '-'],
+        ['wsb share', !p.wsbShare ? 'off (projects.wsbShare)' : wsb ? 'available: ' + wsb.exe + (wsb.version ? ' ' + wsb.version : '') + ' (untested; a failure offers a restart instead)' : 'not on this Windows (needs Windows 11 24H2+ with the updated Windows Sandbox): folders outside your roots need a restart'],
+    ]);
+    return 0;
+};
+export const claudeHost = (ctx) => hostClaude(ctx.storageRoot, ctx.options.personal, ctx.options.passthrough);
+export const watcher = (ctx) => watch(ctx.dataPath);