windows-development-sandbox 1.4.0 → 1.4.3

package/dist/cli/commands/launch/running.js

@@ -0,0 +1,218 @@
+// A sandbox that is already running: wait for it, open sessions in it, attach this terminal to one.
+import _ from 'lodash';
+import { attachTerminal, findUnwatchedSession, SandboxChannel } from '../../../host/channel/index.js';
+import { insideSandbox, hideSandboxWindow, showSandboxWindow } from '../../../host/sandbox/index.js';
+import { NeedsRestart } from '../../../host/projects/index.js';
+import { RunDir } from '../../../shared/channel/index.js';
+import { errMsg, fail, sleep } from '../../../core/util/index.js';
+import { c, follow, working, table } from '../../output/index.js';
+import { bootLine, readyIn, stillWorking } from './boot-progress.js';
+import { hereDir, joinHere, readyHere, offerRestart } from '../projects/index.js';
+/** How long a session may take to start (its project's setup, the agent's install). */
+const SESSION_START_MS = 60 * 60 * 1000;
+/**
+ * Attaches this terminal; with attach.autoHide the sandbox window hides meanwhile (best effort, never fails the
+ * attach).
+ */
+export function attachHere(ctx, session) {
+    if (ctx.loaded.config.attach.autoHide && !insideSandbox())
+        void hideSandboxWindow(ctx.storageRoot, 120).catch(() => false);
+    return attachTerminal(session);
+}
+/** The sandbox writes sandbox.json a few seconds into its boot; a second launch right after the first waits for it. */
+export async function runningSandboxStatus(dataPath) {
+    const run = new RunDir(dataPath);
+    for (let i = 0; i < 60; i++) {
+        const status = run.readSandboxStatus();
+        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 and what it sets up on one line (plain lines without a terminal).
+ * timed: say how long it took (a first start, where that is worth knowing).
+ */
+export async function waitForBoot(dataPath, launchId, timed = false) {
+    let status = null;
+    const start = Date.now();
+    const ready = await follow(() => bootLine(status), () => new SandboxChannel(dataPath).waitForReady(launchId, () => undefined, (s) => {
+        if (s.phase !== 'failed')
+            status = s;
+    }), { stall: stillWorking });
+    if (timed)
+        console.log(readyIn(Date.now() - start));
+    return ready;
+}
+/** The running sandbox, once it is ready. */
+export async function readySandbox(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. */
+export function waitForStart(ctx, requestId, what) {
+    let step = 'starting';
+    const shown = () => ({ line: what + ': ' + step, key: step, what: step });
+    return follow(shown, () => new SandboxChannel(ctx.dataPath).waitForSession(requestId, SESSION_START_MS, (m) => {
+        step = m;
+    }), { stall: stillWorking });
+}
+/** Asks the sandbox for a session; the agent's definition goes along (the sandbox may have booted with another). */
+function requestSession(ctx, channel, harness, args, joined) {
+    const harnessSpec = ctx.loaded.config.harnesses[harness];
+    return channel.requestSession(harness, args, joined.guestDir, {
+        ...(joined.spec ? { project: joined.spec } : {}),
+        ...(harnessSpec ? { harnessSpec } : {}),
+    });
+}
+/**
+ * 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 async function openSession(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);
+    const requestId = requestSession(ctx, new SandboxChannel(dataPath), harness, args, joined);
+    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). */
+function wantedSessions(ctx) {
+    return 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). */
+export function contextFor(ctx, want) {
+    return {
+        ...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.
+ */
+async function openSessions(ctx, ready, list) {
+    const { loaded, options } = ctx;
+    const channel = new SandboxChannel(ctx.dataPath);
+    const requests = list.map(({ ctx: at, joined }) => {
+        const harness = at.options.harness ?? joined.harness ?? loaded.config.defaultHarness;
+        const id = requestSession(ctx, channel, harness, at.options.passthrough, joined);
+        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 channel.waitForSession(r.id, SESSION_START_MS, () => 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). */
+export async function launchIntoRunning(ctx, relauncher) {
+    const ready = await readySandbox(ctx.dataPath);
+    // 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 wantedSessions(ctx)) {
+        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, relauncher), relauncher);
+    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. */
+export async function startIntoRunning(ctx, relauncher) {
+    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, relauncher), relauncher);
+        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;
+}

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

@@ -0,0 +1,8 @@
+import type { Generated, ResolvedRun } from '../../../core/types.js';
+import type { Prepared } from './prepare.js';
+/** What generateSandbox returned. */
+export type GeneratedSandbox = Generated & {
+    readonly personalization: string;
+};
+/** The launch summary rows, in the order they are printed. */
+export declare function launchSummary(run: ResolvedRun, generated: GeneratedSandbox, prepared: Prepared | null): string[][];

package/dist/cli/commands/launch/summary.js

@@ -0,0 +1,98 @@
+function agentRow(run, generated, prepared) {
+    const { config } = run;
+    // What the sandbox boots with (the launch folder's settings plus what the other projects at boot want).
+    const booted = generated.bootConfig;
+    return (run.harnessName +
+        (prepared?.account ? '  (account: ' + prepared.account + ')' : '') +
+        '   Memory: ' +
+        generated.memoryMb +
+        ' MB   CPU: ' +
+        (config.sandbox.cpuLimit === 'none' ? 'all' : 'max ' + config.sandbox.cpuLimit + '%') +
+        '   Network: ' +
+        booted.sandbox.networking +
+        (booted.sandbox.vGpu ? '   vGPU' : '') +
+        (config.sandbox.headless ? '   HEADLESS' : ''));
+}
+function versionsRow(run) {
+    const { node, python } = run.versions;
+    return node.spec + ' (' + node.source + ')   Python: ' + python.spec + ' (' + python.source + ')';
+}
+function preparedRows(prepared) {
+    return prepared
+        ? [
+            ['Ignored files', prepared.filter],
+            ['Terminal', prepared.terminal],
+            ['History', prepared.history],
+            ['Cleanup', prepared.pruned],
+        ]
+        : [];
+}
+function toolchainsRow(generated) {
+    return (Object.entries(generated.toolchains)
+        .filter(([, d]) => d.on)
+        .map(([name, d]) => name + ' (' + d.reason + ')')
+        .join(', ') || 'Node only (nothing else used by this project)');
+}
+function databaseRows(generated) {
+    if (!generated.databases.length)
+        return [['Databases', 'none needed (databases.<name>.enabled = true adds one)']];
+    return 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)' : ''),
+    ]);
+}
+function claudeRow(generated) {
+    const { profile } = generated;
+    return profile.staged.length
+        ? profile.staged.join(', ') + (profile.credentials ? '  (INCLUDING YOUR LOGIN)' : '')
+        : 'no settings copied';
+}
+function secretsRow(run, generated) {
+    if (!run.config.secrets.strip)
+        return 'NOT stripped (secrets.strip is off)';
+    const removed = generated.profile.secretsRemoved;
+    return removed.length
+        ? 'kept on this PC: ' + removed.join(', ') + '  (secrets.allow lets one through)'
+        : 'none found in what is copied';
+}
+/** Project roots, boot-mapped projects, then any other folder mapped (not the tool's own nor the workspace). */
+function mappingRows(run, generated) {
+    const { roots, projects } = generated.projects;
+    return [
+        ...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(2)
+            .filter((m) => m.guest !== run.config.guestWorkspace && ![...roots, ...projects].some((p) => p.guest === m.guest))
+            .map((m) => [
+            '  map ' + (m.readOnly ? 'ro' : 'rw'),
+            m.host + '  ->  ' + m.guest + (m.label ? '  (' + m.label + ')' : ''),
+        ]),
+    ];
+}
+/** The launch summary rows, in the order they are printed. */
+export function launchSummary(run, generated, prepared) {
+    const { config } = run;
+    return [
+        ['Workspace', run.workspaceHost + '  ->  ' + config.guestWorkspace + (config.readOnly ? '  (read-only)' : '')],
+        ['Agent', agentRow(run, generated, prepared)],
+        ['Node', versionsRow(run)],
+        ...preparedRows(prepared),
+        ['Toolchains', toolchainsRow(generated)],
+        ...databaseRows(generated),
+        ['Desktop', generated.personalization],
+        ['Claude', claudeRow(generated)],
+        ['Secrets', secretsRow(run, generated)],
+        ...mappingRows(run, generated),
+        ['Generated', generated.wsbPath],
+    ];
+}

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

@@ -0,0 +1,3 @@
+import { type Context } from '../context.js';
+/** `sandbox audit`: the audit log of the last days (audit.enabled), newest last. */
+export declare function audit(ctx: Context): Promise<number>;

package/dist/cli/commands/maintenance/audit.js

@@ -0,0 +1,58 @@
+import path from 'node:path';
+import { fail, plainText } from '../../../core/util/index.js';
+import { humanBytes } from '../../../core/disk.js';
+import { AuditLog } from '../../../host/audit/log.js';
+import { printJson, c } from '../../output/index.js';
+const KINDS = ['proc', 'file', 'session', 'guard', 'note'];
+const KIND_LABEL = {
+    proc: 'program',
+    file: 'file',
+    session: 'session',
+    guard: 'GUARD',
+    note: 'note',
+};
+/** `sandbox audit`: the audit log of the last days (audit.enabled), newest last. */
+export async function audit(ctx) {
+    const settings = ctx.loaded.config.audit;
+    const kind = ctx.options.kind;
+    if (kind && !KINDS.includes(kind))
+        fail('Unknown kind "' + kind + '".', 'Use one of: ' + KINDS.join(', '));
+    const log = new AuditLog(AuditLog.dirFor(ctx.storageRoot, ctx.dataPath), settings);
+    const events = log.read({
+        days: ctx.options.days,
+        kinds: kind ? [kind] : undefined,
+        grep: ctx.options.grep,
+    });
+    if (printJson(ctx, events))
+        return 0;
+    if (!events.length) {
+        console.log(settings.enabled
+            ? 'Nothing in the audit log for the last ' + ctx.options.days + ' day(s).'
+            : 'The audit log is off. Turn it on in the menu (Settings > Security & privacy > Audit log) or with audit.enabled in your config.');
+        return 0;
+    }
+    for (const e of events) {
+        // What the sandbox reported is text from the sandbox: no control codes reach your terminal.
+        const [p, cmd, parent, dir, act] = [e.p, e.c, e.pp, e.w, e.a].map((v) => plainText(v ?? ''));
+        const what = e.k === 'proc'
+            ? (cmd || p) + (parent ? c.dim('  <- ' + path.win32.basename(parent)) : '')
+            : e.k === 'file'
+                ? act + ' ' + p + c.dim('  in ' + dir)
+                : e.k === 'session'
+                    ? act + ' ' + p + c.dim('  ' + dir + ' ' + cmd)
+                    : p;
+        console.log(c.dim(new Date(e.t).toLocaleString()) +
+            '  ' +
+            (e.k === 'guard' ? c.yellow(KIND_LABEL[e.k].padEnd(8)) : KIND_LABEL[e.k].padEnd(8)) +
+            what +
+            (e.n && e.n > 1 ? c.dim('  x' + e.n) : ''));
+    }
+    console.log(c.dim('\n' +
+        events.length +
+        ' event(s); the log takes ' +
+        humanBytes(log.bytes()) +
+        ' (' +
+        AuditLog.dirFor(ctx.storageRoot, ctx.dataPath) +
+        ').'));
+    return 0;
+}

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

@@ -0,0 +1,2 @@
+import { type Context } from '../context.js';
+export declare function clean(ctx: Context): number;

package/dist/cli/commands/maintenance/clean.js

@@ -0,0 +1,10 @@
+import _ from 'lodash';
+import { describePrune, pruneStorage } from '../../../host/storage/index.js';
+import { isSandboxRunning } from '../../../host/sandbox/index.js';
+import { RunDir } from '../../../shared/channel/index.js';
+export function clean(ctx) {
+    const running = isSandboxRunning() ? new RunDir(ctx.dataPath).readSandboxStatus()?.launchId : undefined;
+    console.log('Cleanup: ' +
+        describePrune(pruneStorage(ctx.storageRoot, { launchDays: ctx.options.days, keep: _.compact([running]) })));
+    return 0;
+}

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

@@ -0,0 +1,2 @@
+import { type Context } from '../context.js';
+export declare function config(ctx: Context): number;

package/dist/cli/commands/maintenance/config.js

@@ -0,0 +1,145 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { DEFAULTS, userConfigPath, userDir } from '../../../core/config/index.js';
+import { allowedAnswer, allowStorePath, applyOverrides, describeOverrides, isTrusted, LOCAL_CONFIG_NAME, loosenedRequests, normalizeOverrides, OUTSIDE_FOLDER, outsideKey, outsideMappings, readLocalConfig, trustStorePath, } from '../../../core/local-config/index.js';
+import { guestWorkspaceOf, previewGuest } from '../../../core/run/index.js';
+import { dirExists, fail, safeText, writeJson } from '../../../core/util/index.js';
+import { c, table } from '../../output/index.js';
+function 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).
+ */
+function 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.
+ */
+function 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, dir))
+        console.log('  ' + safeText(line));
+    previewFolders(ctx, dir, file.path, overrides);
+    return 0;
+}
+/** What a launch from here would do with each folder and each looser setting, without launching. */
+function previewFolders(ctx, dir, filePath, overrides) {
+    const config = ctx.loaded.config;
+    const store = allowStorePath(ctx.storageRoot);
+    const workspaceGuest = guestWorkspaceOf(applyOverrides(config, overrides), dir).guest;
+    const outside = outsideMappings(dir, overrides.mappings);
+    const policy = config.projects.allowOutsideMappings;
+    const statusOf = (m) => {
+        if (!dirExists(m.host))
+            return m.optional
+                ? 'not on this PC: skipped'
+                : c.red('the folder does not exist: create it, fix the path, or add "optional": true');
+        if (!outside.includes(m))
+            return m.guest ? 'inside the project' : 'inside the project (already in the sandbox there)';
+        if (policy === true)
+            return 'outside the project, allowed (projects.allowOutsideMappings is true)';
+        if (policy === false)
+            return c.red('outside the project: refused (projects.allowOutsideMappings is false)');
+        return allowedAnswer(store, filePath, OUTSIDE_FOLDER, outsideKey(m)) === true
+            ? 'outside the project, allowed (you said yes)'
+            : c.yellow('outside the project: the next interactive launch asks you');
+    };
+    const rows = (overrides.mappings ?? []).map((m) => {
+        const where = previewGuest(m, dir, workspaceGuest);
+        return [(m.readOnly ? 'ro ' : 'rw ') + safeText(m.host), '->  ' + safeText(where.guest), statusOf(m)];
+    });
+    if (rows.length) {
+        console.log('\nFolders (where they appear in the sandbox):');
+        table(rows);
+    }
+    for (const m of overrides.mappings ?? []) {
+        const note = dirExists(m.host) ? previewGuest(m, dir, workspaceGuest).note : null;
+        if (note)
+            console.log('  ' + safeText(note));
+    }
+    const looser = loosenedRequests(config, overrides);
+    if (looser.length)
+        console.log('\nLooser than your settings (used only if you allow it for this project):');
+    for (const a of looser) {
+        const answer = allowedAnswer(store, filePath, a.key, a.wanted);
+        console.log('  ' +
+            a.key +
+            ' = ' +
+            JSON.stringify(a.wanted) +
+            ': ' +
+            (answer === true
+                ? 'allowed (you said yes)'
+                : answer === false
+                    ? 'not used (you said no)'
+                    : 'the next interactive launch asks you'));
+    }
+}
+export function 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');
+    }
+}

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

@@ -0,0 +1,2 @@
+import { type Context } from '../context.js';
+export declare function doctor(ctx: Context): number;

package/dist/cli/commands/maintenance/doctor.js

@@ -0,0 +1,52 @@
+import { expandPath } from '../../../core/util/index.js';
+import { KnownProjects, ProjectRegistry } from '../../../host/projects/index.js';
+import { detectWsb, doctorRows, insideSandbox, isSandboxRunning } from '../../../host/sandbox/index.js';
+import { table } from '../../output/index.js';
+export function 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() ? new ProjectRegistry(ctx.storageRoot).read() : 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: ' +
+                    new KnownProjects(ctx.storageRoot).list().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;
+}

package/dist/cli/commands/maintenance/host-claude.d.ts

@@ -0,0 +1,2 @@
+import { type Context } from '../context.js';
+export declare function claudeHost(ctx: Context): number;

package/dist/cli/commands/maintenance/host-claude.js

@@ -0,0 +1,4 @@
+import { hostClaude } from '../../../host/sandbox/index.js';
+export function claudeHost(ctx) {
+    return hostClaude(ctx.storageRoot, ctx.options.personal, ctx.options.passthrough);
+}

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

@@ -0,0 +1,8 @@
+export * from './sync.js';
+export * from './logs.js';
+export * from './clean.js';
+export * from './config.js';
+export * from './doctor.js';
+export * from './host-claude.js';
+export * from './watch.js';
+export * from './audit.js';

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

@@ -0,0 +1,9 @@
+// sync, logs, clean, config, doctor, host-claude and the internal sync watcher.
+export * from './sync.js';
+export * from './logs.js';
+export * from './clean.js';
+export * from './config.js';
+export * from './doctor.js';
+export * from './host-claude.js';
+export * from './watch.js';
+export * from './audit.js';

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

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