windows-development-sandbox 0.0.0-stage → 1.1.0

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

@@ -0,0 +1,29 @@
+import type { SandboxStatus } from '../../core/types.js';
+import { type RegistryEntry } from '../../host/projects.js';
+import type { ProjectSpecT } from '../../shared/schema.js';
+import { type Context } from './context.js';
+/** The folder the command is about: --workspace, else the current one. */
+export declare const hereDir: (ctx: Context) => string;
+export interface Located {
+    project: RegistryEntry | null;
+    guestDir: string | null;
+}
+/** Where this folder is in the running sandbox, if it is in it at all (nothing is registered). */
+export declare const locateHere: (ctx: Context, status: SandboxStatus | null) => Located;
+export interface Joined {
+    project: RegistryEntry | null;
+    guestDir: string;
+    spec: ProjectSpecT | null;
+    harness: string | null;
+    notes: string[];
+}
+/**
+ * Makes this folder a project of the running sandbox (nothing to do for the launch folder and projects already in
+ * it): its .sandbox-config.json is approved like at a launch, its protections are checked, and it is made visible.
+ * Throws NeedsRestart (host/projects.ts) when that is impossible without a restart.
+ */
+export declare const joinHere: (ctx: Context, status: SandboxStatus) => Promise<Joined>;
+/** Waits until the sandbox has set a project up, with its progress on a spinner (plain lines without a terminal). */
+export declare const provisionJoined: (ctx: Context, joined: Joined) => Promise<void>;
+/** joinHere, then (for another project) waits until the sandbox has set it up. */
+export declare const readyHere: (ctx: Context, status: SandboxStatus) => Promise<Joined>;

package/dist/cli/commands/project.js

@@ -0,0 +1,63 @@
+// Which project of the running sandbox a command is run from. Every command that works on a running sandbox uses
+// these, so they all agree: `locateHere` only looks (attach, sessions, status, restart), `joinHere` also makes the
+// folder a project of the running sandbox when it can without a restart (launch, start, exec, db).
+import path from 'node:path';
+import { askYesNo } from '../../core/prompt.js';
+import { isInsideOrEqual } from '../../core/util.js';
+import { resolveRun } from '../../core/workspace.js';
+import { prepareProject } from '../../host/channel.js';
+import { projectHere, readRegistry } from '../../host/projects.js';
+import { joinRunning } from '../../host/join.js';
+import { working } from '../progress.js';
+import { guestPathFor, sandboxAlive } from './context.js';
+/** The folder the command is about: --workspace, else the current one. */
+export const hereDir = (ctx) => path.resolve(ctx.options.workspace ?? process.cwd());
+/** Where this folder is in the running sandbox, if it is in it at all (nothing is registered). */
+export const locateHere = (ctx, status) => {
+    const dir = hereDir(ctx);
+    const here = projectHere(ctx.storageRoot, dir);
+    if (here)
+        return here;
+    // A sandbox started before projects existed: only its launch folder.
+    if (!readRegistry(ctx.storageRoot) && status && isInsideOrEqual(status.workspaceHost, dir))
+        return { project: null, guestDir: guestPathFor(dir, status.workspaceHost, status.guestWorkspace) };
+    return { project: null, guestDir: null };
+};
+/**
+ * Makes this folder a project of the running sandbox (nothing to do for the launch folder and projects already in
+ * it): its .sandbox-config.json is approved like at a launch, its protections are checked, and it is made visible.
+ * Throws NeedsRestart (host/projects.ts) when that is impossible without a restart.
+ */
+export const joinHere = async (ctx, status) => {
+    const { options, loaded, packageRoot, storageRoot, dataPath } = ctx;
+    const dir = hereDir(ctx);
+    // A sandbox started before projects existed: only its launch folder (guestPathFor explains why otherwise).
+    if (!readRegistry(storageRoot))
+        return { project: null, guestDir: guestPathFor(dir, status.workspaceHost, status.guestWorkspace), spec: null, harness: null, notes: [] };
+    const joined = await joinRunning({
+        storageRoot, dataPath, packageRoot, hostDir: dir, wsbShare: loaded.config.projects.wsbShare,
+        resolve: (root) => resolveRun({
+            packageRoot, loaded, cwd: root, workspace: root, harness: options.harness, noAgent: options.noAgent,
+            noLocalConfig: options.noLocalConfig, trustConfig: options.trustConfig, scripts: options.scripts, databases: options.databases,
+            nodeVersion: options.node, pythonVersion: options.python, ask: askYesNo,
+        }),
+    });
+    const harness = joined.run && joined.run.harnessName !== 'none' ? joined.run.harnessName : null;
+    return { project: joined.project, guestDir: joined.guestDir, spec: joined.spec, harness, notes: joined.notes };
+};
+/** Waits until the sandbox has set a project up, with its progress on a spinner (plain lines without a terminal). */
+export const provisionJoined = async (ctx, joined) => {
+    if (!joined.spec)
+        return;
+    const spec = joined.spec;
+    let step = 'starting';
+    await working(() => 'Setting up ' + spec.name + ' in the running sandbox: ' + step, () => prepareProject(ctx.dataPath, spec, sandboxAlive, (m) => { step = m; }));
+};
+/** joinHere, then (for another project) waits until the sandbox has set it up. */
+export const readyHere = async (ctx, status) => {
+    const joined = await joinHere(ctx, status);
+    for (const note of joined.notes)
+        console.log(note);
+    await provisionJoined(ctx, joined);
+    return joined;
+};

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

@@ -0,0 +1,14 @@
+import { type Context } from './context.js';
+interface Row {
+    folder: string;
+    here: boolean;
+    known: boolean;
+    root: string | null;
+    excluded: boolean;
+    mappedAtStart: boolean;
+    running: string | null;
+}
+/** Every project worth listing: known ones, the running sandbox's, and this folder. */
+export declare const projectRows: (ctx: Context) => Row[];
+export declare const projects: (ctx: Context) => Promise<number>;
+export {};

package/dist/cli/commands/projects.js

@@ -0,0 +1,146 @@
+// `sandbox projects`: which projects a sandbox can open without a restart. Project roots (whole folders of projects),
+// the projects this tool has started before, and projects.all / projects.exclude. Changes to what is mapped take
+// effect at the next start; a project you start while a sandbox runs joins it when it can (projects.ts in host/).
+import path from 'node:path';
+import { checkbox } from '@inquirer/prompts';
+import { assertSafeMapping, assertSafeWorkspace } from '../../core/safe-paths.js';
+import { dirExists, expandPath, fail, isRootPath } from '../../core/util.js';
+import { isSandboxRunning } from '../../host/platform.js';
+import { forgetProject, projectMapper, readKnown, readRegistry, rememberProject } from '../../host/projects.js';
+import { isWithin } from '../../shared/projects.js';
+import { c, pageSizeFor, shortenMiddle, termWidth } from '../colors.js';
+import { printJson, table } from './context.js';
+import { hereDir } from './project.js';
+import { addToList, removeFromList, setSetting } from './user-config.js';
+const settings = (ctx) => {
+    const p = ctx.loaded.config.projects;
+    const expand = (list) => list.map((x) => expandPath(x, ctx.loaded.base));
+    return { all: p.all, roots: expand(p.roots), exclude: expand(p.exclude) };
+};
+/** Every project worth listing: known ones, the running sandbox's, and this folder. */
+export const projectRows = (ctx) => {
+    const s = settings(ctx);
+    const registry = isSandboxRunning() ? readRegistry(ctx.storageRoot) : null;
+    const here = hereDir(ctx);
+    const folders = [...readKnown(ctx.storageRoot).map((k) => k.host), ...(registry?.projects.map((p) => p.host) ?? [])];
+    const unique = folders.filter((f, i) => folders.findIndex((g) => g.toLowerCase() === f.toLowerCase()) === i);
+    return unique.map((folder) => {
+        const root = s.roots.find((r) => isWithin(r, folder)) ?? null;
+        const excluded = s.exclude.some((e) => isWithin(e, folder));
+        const inSandbox = registry?.projects.find((p) => p.host.toLowerCase() === folder.toLowerCase());
+        return {
+            folder, here: isWithin(folder, here), known: readKnown(ctx.storageRoot).some((k) => k.host.toLowerCase() === folder.toLowerCase()), root, excluded,
+            mappedAtStart: root !== null || (s.all && !excluded && dirExists(folder)), running: inSandbox ? inSandbox.name + ' (' + inSandbox.mechanism + ')' : null,
+        };
+    });
+};
+const NEXT_START = 'This changes what is mapped from the next start.';
+const runningNote = () => (isSandboxRunning() ? ' The running sandbox keeps what it has; start a project in it (sandbox claude there) and it joins without a restart when it can, or you are offered one.' : '');
+/** A folder for roots: it holds projects, so it must pass the same checks as a workspace and must not be a drive. */
+const checkFolder = (ctx, folder, what) => {
+    const dir = path.resolve(folder);
+    if (!dirExists(dir))
+        fail('The folder ' + dir + ' does not exist.', 'Check the path.');
+    if (isRootPath(dir))
+        fail('A whole drive cannot be ' + what + ': ' + dir, 'Use the folder that holds your projects, e.g. F:\\Code.');
+    assertSafeWorkspace(dir, ctx.packageRoot, ctx.storageRoot);
+    assertSafeMapping(dir, ctx.packageRoot, ctx.storageRoot);
+    return dir;
+};
+const list = (ctx) => {
+    const rows = projectRows(ctx);
+    const s = settings(ctx);
+    if (printJson(ctx, { all: s.all, roots: s.roots, exclude: s.exclude, projects: rows }))
+        return 0;
+    console.log(c.bold('projects.all') + ': ' + (s.all ? 'on (every project below is mapped at every start, except excluded ones)' : 'off') + c.dim('   sandbox projects all on|off'));
+    console.log(c.bold('Roots') + ': ' + (s.roots.length ? s.roots.join(', ') : c.dim('none (sandbox projects roots add <folder>)')));
+    if (!rows.length) {
+        console.log('No projects yet: start one with sandbox claude in its folder.');
+        return 0;
+    }
+    const width = Math.max(20, termWidth() - 46);
+    table([['', 'FOLDER', 'AT START', 'RUNNING SANDBOX'], ...rows.map((r) => [
+            r.here ? '*' : '', shortenMiddle(r.folder, width), r.root ? 'root' : r.excluded ? 'excluded' : r.mappedAtStart ? 'mapped' : '-', r.running ?? '-',
+        ])]);
+    console.log(c.dim('* = this folder.  Choose with: sandbox projects choose'));
+    return 0;
+};
+/** Ticks the projects mapped at every start (turns projects.all on when any is ticked); the rest are excluded. */
+const choose = async (ctx) => {
+    const rows = projectRows(ctx).filter((r) => !r.root);
+    if (!rows.length) {
+        console.log('No projects to choose from yet (projects in a root are always mapped with it). Start one with sandbox claude in its folder.');
+        return 0;
+    }
+    if (!process.stdin.isTTY)
+        fail('sandbox projects choose needs an interactive terminal.', 'Use sandbox projects include|exclude <folder> instead.');
+    const s = settings(ctx);
+    const picked = await checkbox({
+        message: 'Projects mapped at every start, so they open without a restart (every agent in the sandbox can see them):',
+        pageSize: pageSizeFor(rows.length),
+        choices: rows.map((r) => ({ value: r.folder, name: shortenMiddle(r.folder, termWidth() - 12) + (r.here ? c.dim('  (this folder)') : ''), checked: s.all && !r.excluded })),
+    });
+    const exclude = rows.filter((r) => !picked.includes(r.folder)).map((r) => r.folder);
+    setSetting(ctx, ['projects', 'exclude'], [...s.exclude.filter((e) => !rows.some((r) => r.folder.toLowerCase() === e.toLowerCase())), ...exclude]);
+    setSetting(ctx, ['projects', 'all'], picked.length > 0);
+    console.log(picked.length + ' project(s) mapped at every start, ' + exclude.length + ' excluded. ' + NEXT_START + runningNote());
+    return 0;
+};
+export const projects = async (ctx) => {
+    const [action = 'list', value, folder] = ctx.options.positionals;
+    switch (action) {
+        case 'list': return list(ctx);
+        case 'choose': return choose(ctx);
+        case 'add': {
+            const dir = checkFolder(ctx, value, 'a project');
+            rememberProject(ctx.storageRoot, dir);
+            console.log('Added ' + dir + ' to your projects.' + (settings(ctx).all ? ' ' + NEXT_START : ' It is mapped at every start once projects.all is on (sandbox projects all on).'));
+            return 0;
+        }
+        case 'remove': {
+            const dir = path.resolve(value);
+            const forgot = forgetProject(ctx.storageRoot, dir);
+            // The running sandbox forgets it too (its folder stays visible until the sandbox stops, if it was mapped).
+            const registered = isSandboxRunning() ? readRegistry(ctx.storageRoot)?.projects.find((p) => !p.primary && p.host.toLowerCase() === dir.toLowerCase()) : undefined;
+            if (registered)
+                projectMapper({ storageRoot: ctx.storageRoot, packageRoot: ctx.packageRoot, wsbShare: false }).unregister(registered.name);
+            console.log(forgot || registered ? 'Removed ' + dir + ' from your projects (nothing in the folder was touched).' : dir + ' was not in your projects.');
+            return 0;
+        }
+        case 'include':
+        case 'exclude': {
+            const dir = path.resolve(value);
+            const changed = action === 'exclude' ? addToList(ctx, ['projects', 'exclude'], dir) : removeFromList(ctx, ['projects', 'exclude'], dir);
+            if (action === 'include')
+                rememberProject(ctx.storageRoot, dir);
+            console.log((changed ? (action === 'exclude' ? 'Excluded ' : 'Included ') + dir + '. ' + NEXT_START : 'Nothing changed.') + (action === 'include' && !settings(ctx).all ? ' projects.all is off: sandbox projects all on maps your projects at every start.' : '') + (changed ? runningNote() : ''));
+            return 0;
+        }
+        case 'all': {
+            if (value === undefined) {
+                console.log('projects.all is ' + (settings(ctx).all ? 'on' : 'off') + '.');
+                return 0;
+            }
+            setSetting(ctx, ['projects', 'all'], value === 'on');
+            console.log('projects.all is ' + value + '. ' + NEXT_START + (value === 'on' ? ' Every agent in the sandbox can then see all of those projects.' : '') + runningNote());
+            return 0;
+        }
+        case 'roots': {
+            if (!value || value === 'list') {
+                const roots = settings(ctx).roots;
+                console.log(roots.length ? roots.join('\n') : 'No project roots. Add one: sandbox projects roots add <folder>');
+                return 0;
+            }
+            if (value === 'add') {
+                const dir = checkFolder(ctx, folder, 'a project root');
+                const added = addToList(ctx, ['projects', 'roots'], dir);
+                console.log(added ? 'Added the project root ' + dir + ': every project in it (also new ones) opens without a restart. Every agent in the sandbox can see all of them. ' + NEXT_START + runningNote() : dir + ' is a root already.');
+                return 0;
+            }
+            const dir = path.resolve(folder);
+            console.log(removeFromList(ctx, ['projects', 'roots'], dir) ? 'Removed the project root ' + dir + '. ' + NEXT_START : dir + ' was not a root.');
+            return 0;
+        }
+        default: return fail('Unknown projects action "' + action + '".');
+    }
+};

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

@@ -0,0 +1,2 @@
+import { type RepairCheck } from './types.js';
+export declare const CHECKS: RepairCheck[];

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

@@ -0,0 +1,170 @@
+// The repair checks, in the order they run. Each either confirms all is well, fixes the problem itself, or says what
+// you need to do. Nothing under the data folder is followed through a link.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import _ from 'lodash';
+import { GB, freeBytesAt, humanBytes } from '../../../core/disk.js';
+import { assertTestWritable } from '../../../shared/test-guard.js';
+import { assertNoLinks, fileExists, isLink, isWin, removeLink } from '../../../core/util.js';
+import { resetRunDir } from '../../../host/channel.js';
+import { sandboxFeatureInstalled } from '../../../host/platform.js';
+import { listSessions, runPaths, scanRequests } from '../../../shared/rundir.js';
+import { removeTree } from '../data/remove.js';
+import { deadPidFiles, findHalfInstalled, findLinks, findStagingLeftovers, globalPackages, resolvedVersionsValid } from './finders.js';
+import { ok, whileRunning } from './types.js';
+const rel = (root, p) => path.relative(root, p) || '.';
+/** Fails (throws) unless every folder from the data folder to `p` is real. */
+const guard = (env, p) => assertNoLinks(path.dirname(env.dataPath), p);
+export const CHECKS = [
+    {
+        name: 'Config file',
+        run: (env) => (env.configError
+            ? { status: 'needs-you', detail: env.configError.message + (env.configError.fix ? ' ' + env.configError.fix : '') + ' (repair never rewrites your config; built-in defaults were used for the other checks.)' }
+            : ok(env.ctx.loaded.configPath ? env.ctx.loaded.configPath + ' is valid.' : 'none; using the built-in defaults.')),
+    },
+    {
+        name: 'Windows Sandbox feature',
+        run: () => (sandboxFeatureInstalled() ? ok('enabled.') : { status: 'needs-you', detail: (isWin ? 'Windows Sandbox is not turned on.' : 'This is not Windows.') + ' Run: sandbox setup (it checks this PC and offers to turn it on).' }),
+    },
+    {
+        name: 'Links in the data folder',
+        run: (env) => {
+            if (isLink(env.dataPath))
+                return { status: 'needs-you', detail: env.dataPath + ' itself is a link or junction. agent-sandbox refuses to work through links; point storage.root at the real folder instead (sandbox config path).' };
+            // A running sandbox can swap folders for links while we look; only check a stopped one.
+            if (env.running)
+                return whileRunning;
+            const links = findLinks(env.dataPath);
+            if (!links.length)
+                return ok('none (nothing in ' + env.dataPath + ' points elsewhere).');
+            // A link here can only have been made inside the sandbox; it could point at this PC's own files. Remove the link
+            // itself, and only if every folder above it is still real.
+            for (const link of links) {
+                guard(env, path.dirname(link));
+                removeLink(link);
+            }
+            return { status: 'fixed', detail: 'removed ' + links.length + ' link(s)/junction(s) the sandbox created, without following them: ' + links.map((l) => rel(env.dataPath, l)).join(', ') };
+        },
+    },
+    {
+        name: 'Sandbox run state',
+        run: (env) => {
+            if (env.running)
+                return ok('a sandbox is running; its state is in use.');
+            if (isLink(runPaths(env.dataPath).run)) {
+                resetRunDir(env.dataPath);
+                return { status: 'fixed', detail: 'the run folder was a link; removed the link itself.' };
+            }
+            // The last sandbox's status file is normal after it closes; sessions still marked running or unanswered requests are not.
+            const ghosts = listSessions(env.dataPath).filter((s) => s.phase === 'running' || s.phase === 'starting').length;
+            const requests = scanRequests(env.dataPath);
+            const pending = requests.valid.length + requests.invalid.length;
+            if (!ghosts && !pending)
+                return ok('clean.');
+            resetRunDir(env.dataPath);
+            return { status: 'fixed', detail: 'no sandbox is running, but ' + _.compact([ghosts && ghosts + ' session(s) were still marked running', pending && pending + ' request(s) were never answered']).join(' and ') + '; cleared the run state so status/attach do not show ghosts.' };
+        },
+    },
+    {
+        name: 'Hidden-window state',
+        run: (env) => {
+            const file = path.join(env.storageRoot, 'run', 'hidden-windows.json');
+            if (!fs.existsSync(file) && !isLink(file))
+                return ok('clean.');
+            if (env.running)
+                return ok('a sandbox is running; kept.');
+            assertTestWritable(file);
+            fs.rmSync(file, { force: true });
+            return { status: 'fixed', detail: 'removed the saved hidden-window list from a sandbox that is no longer running.' };
+        },
+    },
+    {
+        name: 'Sync watcher',
+        run: (env) => {
+            const dead = deadPidFiles(path.join(env.storageRoot, 'run'));
+            if (!dead.length)
+                return ok('no stale watcher records.');
+            for (const f of dead) {
+                assertTestWritable(f);
+                fs.rmSync(f, { force: true });
+            }
+            return { status: 'fixed', detail: 'removed ' + dead.length + ' record(s) of a history sync watcher that is no longer running (the next launch starts a new one).' };
+        },
+    },
+    {
+        name: 'Interrupted downloads',
+        run: (env) => {
+            if (env.running)
+                return whileRunning;
+            guard(env, env.toolsDir);
+            const found = findStagingLeftovers(env.toolsDir);
+            if (!found.length)
+                return ok('none.');
+            for (const p of found)
+                removeTree(p, env.dataPath);
+            return { status: 'fixed', detail: 'removed ' + found.length + ' half-finished download/copy folder(s): ' + found.map((p) => rel(env.toolsDir, p)).join(', ') };
+        },
+    },
+    {
+        name: 'Half-installed toolchains',
+        run: (env) => {
+            if (env.running)
+                return whileRunning;
+            guard(env, env.toolsDir);
+            const found = findHalfInstalled(env.toolsDir);
+            if (!found.length)
+                return ok('every toolchain folder has its program.');
+            for (const f of found)
+                removeTree(f.path, env.dataPath);
+            return { status: 'fixed', detail: 'removed ' + found.map((f) => rel(env.toolsDir, f.path) + ' (no ' + f.missing + ')').join(', ') + '; the next sandbox reinstalls them.' };
+        },
+    },
+    {
+        name: 'Resolved versions cache',
+        run: (env) => {
+            const file = path.join(env.toolsDir, 'resolved-versions.json');
+            if (!fs.existsSync(file) && !isLink(file))
+                return ok('not created yet.');
+            if (env.running)
+                return whileRunning;
+            guard(env, env.toolsDir);
+            if (isLink(file)) {
+                removeLink(file);
+                return { status: 'fixed', detail: 'removed a link in place of tools\\resolved-versions.json.' };
+            }
+            if (fs.statSync(file).size < 4 * 1024 * 1024 && resolvedVersionsValid(fs.readFileSync(file, 'utf8')))
+                return ok('valid.');
+            assertTestWritable(file);
+            fs.rmSync(file, { force: true });
+            return { status: 'fixed', detail: 'tools\\resolved-versions.json was damaged; removed it (versions are looked up again on the next start).' };
+        },
+    },
+    {
+        name: 'Installed packages',
+        run: () => {
+            const npmCli = path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+            if (!fileExists(npmCli))
+                return { status: 'skipped', detail: 'npm not found next to this Node (' + npmCli + ').' };
+            // cwd = Node's own folder: npm reads .npmrc from the current folder, which could be a sandbox-writable workspace.
+            const result = spawnSync(process.execPath, [npmCli, 'ls', '-g', '--json', '--depth=0'], { cwd: path.dirname(process.execPath), encoding: 'utf8', windowsHide: true, timeout: 60000, maxBuffer: 16 * 1024 * 1024 });
+            const names = globalPackages(result.stdout ?? '');
+            if (!names.length)
+                return { status: 'skipped', detail: 'could not read the global npm packages.' };
+            if (names.includes('agent-sandbox') && names.includes('windows-development-sandbox'))
+                return { status: 'needs-you', detail: 'the old agent-sandbox package is still installed next to windows-development-sandbox, and their commands clash. Run: npm uninstall -g agent-sandbox' };
+            return ok(names.includes('agent-sandbox') ? 'agent-sandbox installed (the old name; fine on its own).' : 'no old agent-sandbox package.');
+        },
+    },
+    {
+        name: 'Free disk',
+        run: (env) => {
+            const free = freeBytesAt(env.storageRoot);
+            if (free === null)
+                return { status: 'skipped', detail: 'could not check the drive of ' + env.storageRoot };
+            if (free >= 20 * GB)
+                return ok(humanBytes(free) + ' free.');
+            return { status: 'warn', detail: humanBytes(free) + ' free on the drive of ' + env.storageRoot + (free < 5 * GB ? ': toolchains need several GB.' : ': getting low.') + ' See what is stored with: sandbox data, and free space with: sandbox data clean <target>' };
+        },
+    },
+];

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

@@ -0,0 +1,30 @@
+/** Interrupted downloads and copies: `<name>.staging-<hex>` and `node-staging`, in tools\ and one folder down (tools\go\1.23.staging-ab12). */
+export declare const findStagingLeftovers: (toolsDir: string) => string[];
+/**
+ * A toolchain folder and the program it must contain. `versions` means one folder per installed version (tools\go\1.23.2);
+ * `match` limits which version folders count (tools\nvm also holds settings and nvm.exe).
+ */
+export interface ToolRule {
+    folder: string;
+    exe: string[];
+    versions?: boolean;
+    match?: RegExp;
+}
+export declare const TOOL_RULES: ToolRule[];
+/** Toolchain folders that exist but lack their main program (an install that stopped half way). Never enters links. */
+export declare const findHalfInstalled: (toolsDir: string, rules?: ToolRule[]) => {
+    path: string;
+    missing: string;
+}[];
+/**
+ * Every link or junction under `root` (the links themselves; nothing behind them is visited). Before descending into
+ * a folder its real path must still be inside root: a folder swapped for a junction between two looks is not followed.
+ */
+export declare const findLinks: (root: string) => string[];
+/** tools\resolved-versions.json is a JSON object (anything else makes the guest stumble). */
+export declare const resolvedVersionsValid: (text: string) => boolean;
+/** Package names from `npm ls -g --json`; [] when the output is not what npm prints. */
+export declare const globalPackages: (json: string) => string[];
+export declare const pidAlive: (pid: number) => boolean;
+/** Sync-watcher pid files (storage\run\watcher-*.pid) whose process is gone (or whose content is not a pid). */
+export declare const deadPidFiles: (runDir: string, alive?: (pid: number) => boolean) => string[];

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

@@ -0,0 +1,108 @@
+// Pure finders the repair checks use (exported for tests): they look, they never change anything.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { dirExists, fileExists, isLink } from '../../../core/util.js';
+/** Interrupted downloads and copies: `<name>.staging-<hex>` and `node-staging`, in tools\ and one folder down (tools\go\1.23.staging-ab12). */
+export const findStagingLeftovers = (toolsDir) => {
+    const isStaging = (name) => /\.staging-[0-9a-f]+$/i.test(name) || name.toLowerCase() === 'node-staging';
+    const realChildren = (dir) => (dirExists(dir) && !isLink(dir) ? fs.readdirSync(dir).map((n) => path.join(dir, n)) : []);
+    return realChildren(toolsDir).flatMap((p) => (isStaging(path.basename(p)) ? [p] : isLink(p) ? [] : realChildren(p).filter((c) => isStaging(path.basename(c)))));
+};
+export const TOOL_RULES = [
+    { folder: 'nvm', exe: ['nvm.exe'] },
+    { folder: 'nvm', exe: ['node.exe'], versions: true, match: /^v\d+\.\d+\.\d+$/ },
+    { folder: 'node', exe: ['node.exe'] },
+    { folder: 'git', exe: ['bin', 'bash.exe'] },
+    { folder: 'dotnet', exe: ['dotnet.exe'] },
+    { folder: 'go', exe: ['bin', 'go.exe'], versions: true },
+    { folder: 'java', exe: ['bin', 'java.exe'], versions: true },
+    { folder: 'python', exe: ['python.exe'], versions: true },
+];
+/** Toolchain folders that exist but lack their main program (an install that stopped half way). Never enters links. */
+export const findHalfInstalled = (toolsDir, rules = TOOL_RULES) => {
+    const realDir = (p) => dirExists(p) && !isLink(p);
+    const staging = (name) => /\.staging-[0-9a-f]+$/i.test(name) || name.toLowerCase() === 'node-staging';
+    return rules.flatMap((rule) => {
+        const base = path.join(toolsDir, rule.folder);
+        if (!realDir(base))
+            return [];
+        const folders = rule.versions
+            ? fs.readdirSync(base).filter((n) => !staging(n) && (!rule.match || rule.match.test(n))).map((n) => path.join(base, n)).filter(realDir)
+            : [base];
+        return folders.filter((f) => !fileExists(path.join(f, ...rule.exe))).map((f) => ({ path: f, missing: path.join(...rule.exe) }));
+    });
+};
+/**
+ * Every link or junction under `root` (the links themselves; nothing behind them is visited). Before descending into
+ * a folder its real path must still be inside root: a folder swapped for a junction between two looks is not followed.
+ */
+export const findLinks = (root) => {
+    if (isLink(root))
+        return [root];
+    const real = (p) => { try {
+        return fs.realpathSync.native(p).toLowerCase();
+    }
+    catch {
+        return '';
+    } };
+    const top = real(root);
+    const inside = (p) => { const r = real(p); return r !== '' && (r === top || r.startsWith(top + path.sep)); };
+    const walk = (dir) => {
+        if (!inside(dir))
+            return [];
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        return entries.flatMap((d) => {
+            const p = path.join(dir, d.name);
+            if (d.isSymbolicLink() || isLink(p))
+                return [p];
+            return d.isDirectory() ? walk(p) : [];
+        });
+    };
+    return dirExists(root) ? walk(root) : [];
+};
+const ResolvedVersions = z.record(z.string(), z.unknown());
+/** tools\resolved-versions.json is a JSON object (anything else makes the guest stumble). */
+export const resolvedVersionsValid = (text) => {
+    try {
+        return ResolvedVersions.safeParse(JSON.parse(text.replace(/^/, ''))).success;
+    }
+    catch {
+        return false;
+    }
+};
+const NpmList = z.object({ dependencies: z.record(z.string(), z.unknown()).optional() });
+/** Package names from `npm ls -g --json`; [] when the output is not what npm prints. */
+export const globalPackages = (json) => {
+    try {
+        return Object.keys(NpmList.parse(JSON.parse(json)).dependencies ?? {});
+    }
+    catch {
+        return [];
+    }
+};
+const Pid = z.coerce.number().int().positive();
+export const pidAlive = (pid) => { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch (e) {
+    return e.code === 'EPERM';
+} };
+/** Sync-watcher pid files (storage\run\watcher-*.pid) whose process is gone (or whose content is not a pid). */
+export const deadPidFiles = (runDir, alive = pidAlive) => (dirExists(runDir) ? fs.readdirSync(runDir) : [])
+    .filter((n) => /^watcher-.*\.pid$/i.test(n))
+    .map((n) => path.join(runDir, n))
+    .filter((f) => { try {
+    const pid = Pid.safeParse(fs.readFileSync(f, 'utf8').trim());
+    return !pid.success || !alive(pid.data);
+}
+catch {
+    return false;
+} });

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

@@ -0,0 +1,12 @@
+import { UserError } from '../../../core/util.js';
+import type { CliOptions } from '../../args.js';
+import { type Context } from '../context.js';
+import type { RepairCheck, RepairEnv, RepairResult } from './types.js';
+/** Runs every check in order; a check that throws is reported, never stops the rest. */
+export declare const runChecks: (env: RepairEnv, checks?: RepairCheck[]) => RepairResult[];
+export declare const repair: (ctx: Context, configError?: UserError | null) => number;
+/**
+ * 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 declare const repairCommand: (packageRoot: string, entry: string, options: CliOptions) => number;

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);
+};