windows-development-sandbox 1.4.1 → 1.4.3

package/dist/cli/commands/projects/here.js

@@ -0,0 +1,145 @@
+// 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 { select } from '@inquirer/prompts';
+import { describeMissing, missingTip } from '../../../core/local-config/index.js';
+import { askYesNo } from '../../../core/prompt.js';
+import { isInsideOrEqual } from '../../../core/util/index.js';
+import { resolveRun } from '../../../core/run/index.js';
+import { SandboxChannel } from '../../../host/channel/index.js';
+import { ProjectRegistry, joinRunning } from '../../../host/projects/index.js';
+import { c, working } from '../../output/index.js';
+import { describeSessions } from './describe-sessions.js';
+import { guestPathFor } from '../context.js';
+/** The folder the command is about: --workspace, else the current one. */
+export function hereDir(ctx) {
+    return 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 function locateHere(ctx, status) {
+    const dir = hereDir(ctx);
+    const here = new ProjectRegistry(ctx.storageRoot).here(dir);
+    if (here)
+        return here;
+    // A sandbox started before projects existed: only its launch folder.
+    if (!new ProjectRegistry(ctx.storageRoot).read() && status && isInsideOrEqual(status.workspaceHost, dir))
+        return { project: null, guestDir: guestPathFor(dir, status.workspaceHost, status.guestWorkspace) };
+    return { project: null, guestDir: null };
+}
+let restartedOnce = false;
+/** restart.ts: the sandbox was restarted for a project in this command. */
+export function markRestarted() {
+    restartedOnce = true;
+}
+/**
+ * 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) when that is impossible without a restart.
+ */
+export async function joinHere(ctx, status, o = {}) {
+    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 (!new ProjectRegistry(storageRoot).read())
+        return {
+            project: null,
+            guestDir: guestPathFor(dir, status.workspaceHost, status.guestWorkspace),
+            spec: null,
+            harness: null,
+            notes: [],
+        };
+    let shown = false;
+    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,
+        }),
+        // Its own settings are stricter than the sandbox's: --yes or a "yes" in a terminal joins with the sandbox's.
+        acceptStricter: async (name, stricter) => {
+            if (options.yes)
+                return true;
+            if (!process.stdin.isTTY || !process.stdout.isTTY)
+                return false;
+            console.log(c.yellow(name +
+                "'s settings are stricter than this sandbox's (they apply to every session in it):\n  " +
+                stricter.join('\n  ')));
+            return askYesNo("Join with the sandbox's settings?");
+        },
+        // Something it wants only comes with a restart: --yes restarts, a terminal asks, anything else continues.
+        decide: async (name, missing) => {
+            // Once per command: what a restart could not give (see the launch notes) never restarts it again.
+            if (o.noRestart || restartedOnce)
+                return 'continue';
+            if (options.yes)
+                return 'restart';
+            if (!process.stdin.isTTY || !process.stdout.isTTY)
+                return 'continue';
+            console.log(c.yellow(describeMissing(name, missing)));
+            shown = true;
+            const sessions = new SandboxChannel(dataPath).currentSessions();
+            const ending = sessions.length ? describeSessions(sessions) + ' will end' : 'no session is running';
+            return select({
+                message: 'What now?',
+                choices: [
+                    { name: 'Continue anyway (join without them)', value: 'continue' },
+                    { name: 'Restart with them (' + ending + ')', value: 'restart' },
+                    { name: 'Cancel', value: 'cancel' },
+                ],
+                default: 'continue',
+            });
+        },
+    });
+    const harness = joined.run && joined.run.harnessName !== 'none' ? joined.run.harnessName : null;
+    const notes = joined.missing
+        ? [...joined.notes, ...missingNotes(ctx, joined.project.name, joined.project.host, joined.missing, shown)]
+        : joined.notes;
+    return { project: joined.project, guestDir: joined.guestDir, spec: joined.spec, harness, notes };
+}
+/** The command that restarts the running sandbox with this folder's boot wishes (consent given by --yes). */
+export function restartCommand(ctx, host) {
+    const agent = ctx.options.noAgent ? 'start' : (ctx.options.harness ?? ctx.loaded.config.defaultHarness);
+    return 'sandbox ' + agent + ' --workspace "' + host + '" --yes';
+}
+/** Joined without what it wants at boot: what is missing, how to restart with it, and how to always have it. */
+export function missingNotes(ctx, name, host, missing, shown = false) {
+    return [
+        ...(shown ? [] : [c.yellow(describeMissing(name, missing))]),
+        'Joined without them. To restart the sandbox with them (its sessions end): ' + restartCommand(ctx, host),
+        c.dim(missingTip(missing)),
+    ];
+}
+/** Waits until the sandbox has set a project up, with its progress on a spinner (plain lines without a terminal). */
+export async function provisionJoined(ctx, joined) {
+    if (!joined.spec)
+        return;
+    const spec = joined.spec;
+    let step = 'starting';
+    await working(() => 'Setting up ' + spec.name + ' in the running sandbox: ' + step, () => new SandboxChannel(ctx.dataPath).prepareProject(spec, (m) => {
+        step = m;
+    }));
+}
+/** joinHere, then (for another project) waits until the sandbox has set it up. */
+export async function readyHere(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/index.d.ts

@@ -0,0 +1,4 @@
+export * from './here.js';
+export * from './projects.js';
+export * from './restart.js';
+export * from './describe-sessions.js';

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

@@ -0,0 +1,4 @@
+export * from './here.js';
+export * from './projects.js';
+export * from './restart.js';
+export * from './describe-sessions.js';

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

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

package/dist/cli/commands/projects/projects.js

@@ -0,0 +1,213 @@
+// `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/index.js';
+import { isSandboxRunning } from '../../../host/sandbox/index.js';
+import { KnownProjects, projectMapper, ProjectRegistry } from '../../../host/projects/index.js';
+import { isWithin } from '../../../shared/paths/index.js';
+import { c, pageSizeFor, shortenMiddle, termWidth, printJson, table } from '../../output/index.js';
+import { hereDir } from './here.js';
+import { addToList, removeFromList, setSetting } from '../user-config.js';
+function 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 function projectRows(ctx) {
+    const s = settings(ctx);
+    const registry = isSandboxRunning() ? new ProjectRegistry(ctx.storageRoot).read() : null;
+    const here = hereDir(ctx);
+    const known = new KnownProjects(ctx.storageRoot).list();
+    const folders = [...known.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: known.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.';
+function runningNote() {
+    return 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. */
+function 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;
+}
+function 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. */
+async function choose(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;
+}
+function add(ctx, value) {
+    const dir = checkFolder(ctx, value, 'a project');
+    new KnownProjects(ctx.storageRoot).remember(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;
+}
+function remove(ctx, value) {
+    const dir = path.resolve(value);
+    const forgot = new KnownProjects(ctx.storageRoot).forget(dir);
+    // The running sandbox forgets it too (its folder stays visible until the sandbox stops, if it was mapped).
+    const registered = isSandboxRunning()
+        ? new ProjectRegistry(ctx.storageRoot)
+            .read()
+            ?.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;
+}
+function includeOrExclude(ctx, action, value) {
+    const dir = path.resolve(value);
+    const changed = action === 'exclude'
+        ? addToList(ctx, ['projects', 'exclude'], dir)
+        : removeFromList(ctx, ['projects', 'exclude'], dir);
+    if (action === 'include')
+        new KnownProjects(ctx.storageRoot).remember(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;
+}
+function all(ctx, value) {
+    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;
+}
+function roots(ctx, value, folder) {
+    if (!value || value === 'list') {
+        const list = settings(ctx).roots;
+        console.log(list.length ? list.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;
+}
+export async function projects(ctx) {
+    const [action = 'list', value, folder] = ctx.options.positionals;
+    switch (action) {
+        case 'list':
+            return list(ctx);
+        case 'choose':
+            return choose(ctx);
+        case 'add':
+            return add(ctx, value);
+        case 'remove':
+            return remove(ctx, value);
+        case 'include':
+        case 'exclude':
+            return includeOrExclude(ctx, action, value);
+        case 'all':
+            return all(ctx, value);
+        case 'roots':
+            return roots(ctx, value, folder);
+        default:
+            return fail('Unknown projects action "' + action + '".');
+    }
+}

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

@@ -0,0 +1,15 @@
+import type { SandboxStatus } from '../../../core/types.js';
+import { type NeedsRestart } from '../../../host/projects/index.js';
+import type { Context } from '../context.js';
+import type { LaunchExtras, OpenSessionOptions } from '../launch/index.js';
+import { type Joined } from './here.js';
+/** What a restart needs from launch (launch imports this file, so it is handed in rather than imported). */
+export interface Relauncher {
+    launch(ctx: Context, generateOnly: boolean, extras: LaunchExtras): Promise<number>;
+    readySandbox(dataPath: string): Promise<SandboxStatus>;
+    joinHere(ctx: Context, status: SandboxStatus, o?: {
+        noRestart?: boolean;
+    }): Promise<Joined>;
+    openSession(ctx: Context, ready: SandboxStatus, joined: Joined, o: OpenSessionOptions): Promise<number>;
+}
+export declare function offerRestart(ctx: Context, needs: NeedsRestart[], then: () => Promise<number>, relauncher: Relauncher): Promise<number>;

package/dist/cli/commands/projects/restart.js

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

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

@@ -0,0 +1,3 @@
+import type { Context } from './context.js';
+export type Handler = (ctx: Context) => number | Promise<number | void>;
+export declare const HANDLERS: Readonly<Partial<Record<string, Handler>>>;

package/dist/cli/commands/registry.js

@@ -0,0 +1,34 @@
+import { launch } from './launch/index.js';
+import { setup } from './setup/index.js';
+import { data } from './data/index.js';
+import { attach, db, exec, hide, restart, sessions, show, status, stop } from './sessions/index.js';
+import { account } from './accounts.js';
+import { projects } from './projects/index.js';
+import { audit, claudeHost, clean, config, doctor, logs, sync, watcher } from './maintenance/index.js';
+import { agentCommandsCommand } from './agent-commands.js';
+export const HANDLERS = {
+    launch: (ctx) => launch(ctx),
+    generate: (ctx) => launch(ctx, true),
+    attach: attach,
+    sessions: sessions,
+    status: status,
+    exec: exec,
+    'agent-commands': agentCommandsCommand,
+    db: db,
+    restart: restart,
+    stop: stop,
+    show: show,
+    hide: hide,
+    account: account,
+    projects: projects,
+    sync: sync,
+    logs: logs,
+    audit: audit,
+    clean: clean,
+    config: config,
+    doctor: doctor,
+    setup: setup,
+    data: data,
+    'host-claude': claudeHost,
+    _watch: watcher,
+};