windows-development-sandbox 1.4.1 → 1.4.3

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

@@ -4,9 +4,9 @@ import path from 'node:path';
 import _ from 'lodash';
 import { humanBytes, sizeOf } from '../../../core/disk.js';
 import { askTyped, askYesNo } from '../../../core/prompt.js';
-import { assertNoLinks, fail, isInsideOrEqual, isLink } from '../../../core/util.js';
-import { isSandboxRunning } from '../../../host/platform.js';
-import { table } from '../context.js';
+import { assertNoLinks, fail, isInsideOrEqual, isLink } from '../../../core/util/index.js';
+import { isSandboxRunning } from '../../../host/sandbox/index.js';
+import { table } from '../../output/index.js';
 import { removeTree } from './remove.js';
 const DATA_AREAS = ['tools', 'databases', 'state', 'logs'];
 const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._ +@-]*$/;
@@ -16,7 +16,7 @@ const ALL_WARNING = 'removes EVERYTHING the sandbox keeps: toolchains, databases
  * Turns `sandbox data clean` arguments into folders. Pure (no disk access); throws a UserError for anything that is
  * not a plain relative target inside the data folder: absolute paths, drive letters, `..`, wildcards, unknown areas.
  */
-export const resolveCleanTargets = (inputs, dataPath, storageRoot) => {
+export function resolveCleanTargets(inputs, dataPath, storageRoot) {
     const usage = 'Targets: all | tools | tools/<name> | tools/agents/<name> | databases | databases/<name> | state | state/<agent> | logs | launches | views. See them with: sandbox data';
     if (!inputs.length)
         fail('Say what to remove.', usage);
@@ -42,7 +42,12 @@ export const resolveCleanTargets = (inputs, dataPath, storageRoot) => {
         if (area === 'views') {
             if (rest.length)
                 fail('Remove all views ("views"), not single ones.', usage);
-            return { target, path: path.join(storageRoot, 'views'), root: storageRoot, warning: 'Views are the copies of your projects without their git-ignored files (workspaceFilter). Your projects are not touched; what the sandbox built or installed in them (node_modules, build output) goes, and the next start copies the projects again.' };
+            return {
+                target,
+                path: path.join(storageRoot, 'views'),
+                root: storageRoot,
+                warning: 'Views are the copies of your projects without their git-ignored files (workspaceFilter). Your projects are not touched; what the sandbox built or installed in them (node_modules, build output) goes, and the next start copies the projects again.',
+            };
         }
         if (area === 'accounts' || area === 'sync')
             fail('"' + area + '" is kept on this PC on purpose and is not removed here.', area === 'accounts' ? 'Remove a saved login with: sandbox account remove <name>' : usage);
@@ -52,7 +57,12 @@ export const resolveCleanTargets = (inputs, dataPath, storageRoot) => {
             fail('Remove all logs ("logs"), not single files.', usage);
         if (rest.length > (area === 'tools' && rest[0]?.toLowerCase() === 'agents' ? 2 : 1))
             fail('Refusing "' + raw + '": too deep.', usage);
-        return { target, path: path.join(dataPath, area, ...rest), root: dataPath, ...(area === 'state' ? { warning: LOGIN_WARNING } : {}) };
+        return {
+            target,
+            path: path.join(dataPath, area, ...rest),
+            root: dataPath,
+            ...(area === 'state' ? { warning: LOGIN_WARNING } : {}),
+        };
     });
     // "all" covers everything; otherwise drop targets inside another target (tools + tools/go = tools).
     const all = resolved.find((t) => t.target === 'all');
@@ -60,12 +70,13 @@ export const resolveCleanTargets = (inputs, dataPath, storageRoot) => {
         return [all, { target: 'launches', path: path.join(storageRoot, 'launches'), root: storageRoot }];
     const unique = _.uniqBy(resolved, (t) => t.path.toLowerCase());
     return unique.filter((t) => !unique.some((o) => o !== t && isInsideOrEqual(o.path, t.path)));
-};
-export const dataClean = async (ctx) => {
+}
+export async function dataClean(ctx) {
     const targets = resolveCleanTargets(ctx.options.positionals.slice(1), ctx.dataPath, ctx.storageRoot);
     if (isSandboxRunning())
         fail('A Windows Sandbox is running, and it uses these folders.', 'Close it first (sandbox stop), then run this again.');
-    // Every folder from the root down to the target's parent must be real; a link in place of the target is removed itself.
+    // Every folder from the root down to the target's parent must be real; a link in place of the target is removed
+    // itself.
     for (const t of targets)
         assertNoLinks(t.root, path.dirname(t.path));
     const present = targets.filter((t) => fs.existsSync(t.path) || isLink(t.path));
@@ -99,8 +110,13 @@ export const dataClean = async (ctx) => {
         }
     }
     const freed = total - _.sumBy(sized, (t) => sizeOf(t.path));
-    console.log('Freed ' + humanBytes(freed) + '. ' + (sized.some((t) => t.root === ctx.dataPath || t.target === 'all') ? 'The next sandbox reinstalls what it needs.' : ''));
+    console.log('Freed ' +
+        humanBytes(freed) +
+        '. ' +
+        (sized.some((t) => t.root === ctx.dataPath || t.target === 'all')
+            ? 'The next sandbox reinstalls what it needs.'
+            : ''));
     if (failed.length)
         fail('Could not remove everything: ' + failed.join('; '), 'Close programs using those folders and run the same command again.');
     return 0;
-};
+}

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

@@ -6,6 +6,9 @@ export interface DataEntry {
     bytes: number;
 }
 /** Every row of `sandbox data`: the sandbox's data folder by area, then what this PC keeps for it. */
-export declare const collectDataEntries: (dataPath: string, storageRoot: string) => DataEntry[];
-/** The `sandbox data clean` target for a listed row, or null when that row is not removable (kept on this PC on purpose). */
-export declare const cleanTargetOf: (entry: DataEntry) => string | null;
+export declare function collectDataEntries(dataPath: string, storageRoot: string): DataEntry[];
+/**
+ * The `sandbox data clean` target for a listed row, or null when that row is not removable (kept on this PC on
+ * purpose).
+ */
+export declare function cleanTargetOf(entry: DataEntry): string | null;

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

@@ -3,26 +3,39 @@ import fs from 'node:fs';
 import path from 'node:path';
 import _ from 'lodash';
 import { sizeOf } from '../../../core/disk.js';
-import { dirExists, isLink } from '../../../core/util.js';
+import { dirExists, isLink } from '../../../core/util/index.js';
 const AREA_ORDER = ['tools', 'databases', 'state', 'logs', 'data', 'host'];
 /** Folders of the data folder that get one row per child; anything else at the top level is listed as itself. */
 const PER_CHILD = ['tools', 'databases', 'state'];
 /** Real (non-link) children of a real folder; a link in place of the folder yields nothing. */
-const entriesOf = (dir) => (dirExists(dir) && !isLink(dir) ? fs.readdirSync(dir, { withFileTypes: true }).filter((d) => !d.isSymbolicLink()) : []);
-const toolRows = (toolsDir) => {
+function entriesOf(dir) {
+    return dirExists(dir) && !isLink(dir)
+        ? fs.readdirSync(dir, { withFileTypes: true }).filter((d) => !d.isSymbolicLink())
+        : [];
+}
+function toolRows(toolsDir) {
     const entries = entriesOf(toolsDir);
     const folders = entries.filter((d) => d.isDirectory());
     const files = entries.filter((d) => !d.isDirectory());
     const row = (name, p) => ({ area: 'tools', name, path: p, bytes: sizeOf(p) });
     return [
-        ...folders.flatMap((d) => (d.name.toLowerCase() === 'agents'
+        ...folders.flatMap((d) => d.name.toLowerCase() === 'agents'
             ? entriesOf(path.join(toolsDir, d.name)).map((a) => row('agents/' + a.name, path.join(toolsDir, d.name, a.name)))
-            : [row(d.name, path.join(toolsDir, d.name))])),
-        ...(files.length ? [{ area: 'tools', name: '(files in tools)', path: toolsDir, bytes: _.sumBy(files, (f) => sizeOf(path.join(toolsDir, f.name))) }] : []),
+            : [row(d.name, path.join(toolsDir, d.name))]),
+        ...(files.length
+            ? [
+                {
+                    area: 'tools',
+                    name: '(files in tools)',
+                    path: toolsDir,
+                    bytes: _.sumBy(files, (f) => sizeOf(path.join(toolsDir, f.name))),
+                },
+            ]
+            : []),
     ];
-};
+}
 /** Every row of `sandbox data`: the sandbox's data folder by area, then what this PC keeps for it. */
-export const collectDataEntries = (dataPath, storageRoot) => {
+export function collectDataEntries(dataPath, storageRoot) {
     const inData = entriesOf(dataPath);
     const rows = inData.flatMap((d) => {
         const p = path.join(dataPath, d.name);
@@ -30,18 +43,36 @@ export const collectDataEntries = (dataPath, storageRoot) => {
         if (area === 'tools')
             return toolRows(p);
         if (PER_CHILD.includes(area))
-            return entriesOf(p).map((c) => ({ area, name: area + '/' + c.name, path: path.join(p, c.name), bytes: sizeOf(path.join(p, c.name)) }));
+            return entriesOf(p).map((c) => ({
+                area,
+                name: area + '/' + c.name,
+                path: path.join(p, c.name),
+                bytes: sizeOf(path.join(p, c.name)),
+            }));
         return [{ area: area === 'logs' ? 'logs' : 'data', name: d.name, path: p, bytes: sizeOf(p) }];
     });
     const otherData = entriesOf(path.join(storageRoot, 'data')).filter((d) => d.isDirectory() && path.join(storageRoot, 'data', d.name).toLowerCase() !== path.resolve(dataPath).toLowerCase());
     const host = [
-        ...['launches', 'views', 'accounts', 'sync', 'logs', 'run', 'host'].map((name) => ({ area: 'host', name, path: path.join(storageRoot, name), bytes: sizeOf(path.join(storageRoot, name)) })),
-        ...otherData.map((d) => ({ area: 'host', name: 'other data folder: ' + d.name, path: path.join(storageRoot, 'data', d.name), bytes: sizeOf(path.join(storageRoot, 'data', d.name)) })),
+        ...['launches', 'views', 'accounts', 'sync', 'logs', 'run', 'host'].map((name) => ({
+            area: 'host',
+            name,
+            path: path.join(storageRoot, name),
+            bytes: sizeOf(path.join(storageRoot, name)),
+        })),
+        ...otherData.map((d) => ({
+            area: 'host',
+            name: 'other data folder: ' + d.name,
+            path: path.join(storageRoot, 'data', d.name),
+            bytes: sizeOf(path.join(storageRoot, 'data', d.name)),
+        })),
     ].filter((r) => fs.existsSync(r.path));
     return _.sortBy([...rows, ...host], (r) => AREA_ORDER.indexOf(r.area), (r) => -r.bytes, (r) => r.name.toLowerCase());
-};
-/** The `sandbox data clean` target for a listed row, or null when that row is not removable (kept on this PC on purpose). */
-export const cleanTargetOf = (entry) => {
+}
+/**
+ * The `sandbox data clean` target for a listed row, or null when that row is not removable (kept on this PC on
+ * purpose).
+ */
+export function cleanTargetOf(entry) {
     if (entry.area === 'tools')
         return entry.name.startsWith('(') ? null : 'tools/' + entry.name;
     if (entry.area === 'databases' || entry.area === 'state')
@@ -51,4 +82,4 @@ export const cleanTargetOf = (entry) => {
     if (entry.area === 'host' && (entry.name === 'launches' || entry.name === 'views'))
         return entry.name;
     return null;
-};
+}

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

@@ -1,4 +1,4 @@
 import { type Context } from '../context.js';
-export declare const dataInfo: (ctx: Context) => Promise<number>;
+export declare function dataInfo(ctx: Context): Promise<number>;
 /** `sandbox data [info|clean] [targets...]`. */
-export declare const data: (ctx: Context) => number | Promise<number>;
+export declare function data(ctx: Context): number | Promise<number>;

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

@@ -3,20 +3,35 @@
 // links, and targets resolve strictly inside the data folder.
 import _ from 'lodash';
 import { diskUsage, humanBytes } from '../../../core/disk.js';
-import { fail } from '../../../core/util.js';
-import { printJson, table } from '../context.js';
-import { working } from '../../progress.js';
+import { fail } from '../../../core/util/index.js';
+import { printJson, table, working } from '../../output/index.js';
 import { dataClean } from './clean.js';
 import { collectDataEntries } from './collect.js';
-const AREA_LABEL = { tools: 'Toolchains', databases: 'Databases', state: 'Agent state', logs: 'Logs', data: 'Other', host: 'On this PC' };
-export const dataInfo = async (ctx) => {
+const AREA_LABEL = {
+    tools: 'Toolchains',
+    databases: 'Databases',
+    state: 'Agent state',
+    logs: 'Logs',
+    data: 'Other',
+    host: 'On this PC',
+};
+export async function dataInfo(ctx) {
     const entries = await working('Measuring the saved data (big folders take a moment)', () => collectDataEntries(ctx.dataPath, ctx.storageRoot), !ctx.options.json);
     const total = _.sumBy(entries, 'bytes');
     const disks = diskUsage(ctx.storageRoot);
     if (printJson(ctx, { dataPath: ctx.dataPath, storageRoot: ctx.storageRoot, totalBytes: total, entries, disks }))
         return 0;
     console.log('Disks\n');
-    table([['DRIVE', 'USED', 'FREE', 'SIZE', ''], ...disks.map((d) => [d.drive, humanBytes(d.usedBytes) + ' (' + Math.round((d.usedBytes / d.totalBytes) * 100) + '%)', humanBytes(d.freeBytes), humanBytes(d.totalBytes), d.holdsStorage ? '<- sandbox storage (' + humanBytes(total) + ' of it)' : ''])]);
+    table([
+        ['DRIVE', 'USED', 'FREE', 'SIZE', ''],
+        ...disks.map((d) => [
+            d.drive,
+            humanBytes(d.usedBytes) + ' (' + Math.round((d.usedBytes / d.totalBytes) * 100) + '%)',
+            humanBytes(d.freeBytes),
+            humanBytes(d.totalBytes),
+            d.holdsStorage ? '<- sandbox storage (' + humanBytes(total) + ' of it)' : '',
+        ]),
+    ]);
     console.log('');
     console.log('Persistent data for the sandbox: ' + ctx.dataPath + ' (C:\\AgentData inside)\n');
     if (!entries.length) {
@@ -30,16 +45,19 @@ export const dataInfo = async (ctx) => {
     table([...rows, ['', '', ''], ['Total', humanBytes(total), '']]);
     console.log('\nFree space with: sandbox data clean <target...>  (e.g. tools/go, databases/postgres-18, logs, launches)');
     return 0;
-};
+}
 /** `sandbox data [info|clean] [targets...]`. */
-export const data = (ctx) => {
+export function data(ctx) {
     const [action = 'info'] = ctx.options.positionals;
     switch (action) {
         case 'info':
         case 'show':
-        case 'list': return dataInfo(ctx);
+        case 'list':
+            return dataInfo(ctx);
         case 'clean':
-        case 'remove': return dataClean(ctx);
-        default: return fail('Unknown data action "' + action + '".', 'Use: sandbox data  (what is stored)  or  sandbox data clean <target...>');
+        case 'remove':
+            return dataClean(ctx);
+        default:
+            return fail('Unknown data action "' + action + '".', 'Use: sandbox data  (what is stored)  or  sandbox data clean <target...>');
     }
-};
+}

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

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

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

@@ -1,10 +1,10 @@
 // Deleting inside the data folder. The sandbox can write there, so links are removed themselves and never followed.
 import fs from 'node:fs';
 import path from 'node:path';
-import { dirExists, isLink, removeLink } from '../../../core/util.js';
-import { removeRefusal, safeRemove } from '../../../shared/safe-remove.js';
+import { dirExists, isLink, removeLink } from '../../../core/util/index.js';
+import { removeRefusal, safeRemove } from '../../../shared/io/index.js';
 /** Deletes p (strictly inside root): links inside are removed first and never followed; see shared/safe-remove.ts. */
-export const removeTree = (p, root) => {
+export function removeTree(p, root) {
     const unlinkInside = (dir) => {
         for (const d of fs.readdirSync(dir, { withFileTypes: true })) {
             const child = path.join(dir, d.name);
@@ -27,4 +27,4 @@ export const removeTree = (p, root) => {
     if (dirExists(p))
         unlinkInside(p);
     safeRemove(p, root);
-};
+}

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

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

package/dist/cli/commands/index.js

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

package/dist/cli/commands/launch/add-root.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedRun } from '../../../core/types.js';
+import { type Context } from '../context.js';
+/**
+ * Asked once per parent folder: map it at every start (a project root), so the projects next to this one open in the
+ * running sandbox without a restart. The answer is saved to your config.
+ */
+export declare function maybeAddRoot(ctx: Context, run: ResolvedRun): Promise<void>;

package/dist/cli/commands/launch/add-root.js

@@ -0,0 +1,64 @@
+import path from 'node:path';
+import { select } from '@inquirer/prompts';
+import { isWithin, planMirrorWorkspace } from '../../../shared/paths/index.js';
+import { assertSafeMapping, assertSafeWorkspace } from '../../../core/safe-paths.js';
+import { isRootPath } from '../../../core/util/index.js';
+import { autoGuestWorkspace, placeInRoot } from '../../../core/run/index.js';
+import { addToList, setSetting } from '../user-config.js';
+/**
+ * Asked once per parent folder: map it at every start (a project root), so the projects next to this one open in the
+ * running sandbox without a restart. The answer is saved to your config.
+ */
+export async function maybeAddRoot(ctx, run) {
+    const { projects } = run.config;
+    const parent = path.dirname(run.workspaceHost);
+    if (!projects.askToAddRoot || ctx.options.yes || !process.stdin.isTTY || !process.stdout.isTTY)
+        return;
+    if (projects.roots.some((r) => isWithin(r, run.workspaceHost)) ||
+        projects.declinedRoots.some((d) => isWithin(d, parent) && isWithin(parent, d)))
+        return;
+    if (isRootPath(parent))
+        return;
+    try {
+        assertSafeWorkspace(parent, ctx.packageRoot, run.storageRoot);
+        assertSafeMapping(parent, ctx.packageRoot, run.storageRoot);
+    }
+    catch {
+        return;
+    }
+    const answer = await select({
+        message: 'Map ' +
+            parent +
+            ' at every start, so other projects there (also new ones) open in the running sandbox without a restart? Agents in the sandbox can then see every project in it.',
+        choices: [
+            { name: 'Yes, from now on', value: 'yes' },
+            { name: 'No (and do not ask again for this folder)', value: 'no' },
+            { name: 'Never ask this again', value: 'never' },
+        ],
+    });
+    if (answer === 'yes') {
+        addToList(ctx, ['projects', 'roots'], parent);
+        run.config.projects.roots.push(parent);
+        console.log('Added ' + parent + ' to projects.roots (sandbox projects roots remove ' + parent + ' undoes it).');
+        moveUnderRoot(run);
+    }
+    if (answer === 'no')
+        addToList(ctx, ['projects', 'declinedRoots'], parent);
+    if (answer === 'never')
+        setSetting(ctx, ['projects', 'askToAddRoot'], false);
+}
+/** From now on this project is under the root's folder inside the sandbox, from this start on (one move, not two). */
+function moveUnderRoot(run) {
+    const before = run.config.guestWorkspace;
+    const auto = autoGuestWorkspace(run.workspaceHost);
+    const derived = [auto, planMirrorWorkspace(run.workspaceHost, auto).guest];
+    // In place: the caller holds run.config already.
+    if (derived.some((g) => g.toLowerCase() === before.toLowerCase()))
+        run.config.guestWorkspace = placeInRoot(run.config, run.workspaceHost, Boolean(run.mirror), run.notes).guestWorkspace;
+    if (run.config.guestWorkspace !== before)
+        console.log('Inside the sandbox this project is now at ' +
+            run.config.guestWorkspace +
+            ' (was ' +
+            before +
+            '): git worktrees made at the old place need `git worktree repair` once.');
+}

package/dist/cli/commands/launch/boot-progress.d.ts

@@ -0,0 +1,7 @@
+import type { SandboxStatus } from '../../../core/types.js';
+import { type Progressing } from '../../output/index.js';
+/** "[3/8] Developer tools: downloading rust 40%, setting up go (2 of 6 done)". */
+export declare function bootLine(status: SandboxStatus | null, fallback?: string): Progressing;
+/** Nothing new for a while: say so, and where the details are. */
+export declare function stillWorking(what: string, ms: number): string;
+export declare function readyIn(ms: number): string;

package/dist/cli/commands/launch/boot-progress.js

@@ -0,0 +1,48 @@
+// One line of progress from the guest's status while a sandbox starts. Pure: the status is guest-written, so every
+// bit of it is made safe and short here.
+import { plainText } from '../../../core/util/index.js';
+import { elapsed } from '../../output/index.js';
+function clean(text, max) {
+    return plainText(text).replace(/\s+/g, ' ').trim().slice(0, max);
+}
+/** "[3/8] Developer tools: downloading rust 40%, setting up go (2 of 6 done)". */
+export function bootLine(status, fallback = 'Starting Windows Sandbox') {
+    if (!status)
+        return { line: fallback, key: fallback, what: fallback.toLowerCase() };
+    const p = status.progress;
+    if (!p) {
+        const line = clean(status.message, 200) || fallback;
+        return { line, key: line, what: line };
+    }
+    const title = clean(p.title, 60);
+    const items = p.active.slice(0, 8).map((a) => ({ name: clean(a.name, 40), percent: a.percent }));
+    const loading = items.filter((a) => a.percent !== undefined && a.percent < 100);
+    const others = items.filter((a) => !loading.includes(a));
+    const parts = [
+        ...(loading.length ? ['downloading ' + loading.map((a) => a.name + ' ' + a.percent + '%').join(', ')] : []),
+        ...(others.length ? ['setting up ' + others.map((a) => a.name).join(', ')] : []),
+    ];
+    const count = p.total > 0 && items.length ? ' (' + Math.min(p.done, p.total) + ' of ' + p.total + ' done)' : '';
+    const head = '[' + p.step + '/' + p.steps + '] ' + title;
+    return {
+        line: (head + (parts.length ? ': ' + parts.join('; ') : '') + count).slice(0, 240),
+        key: head +
+            '|' +
+            items
+                .map((a) => a.name)
+                .sort()
+                .join(','),
+        what: items.length ? items.map((a) => a.name).join(', ') : title,
+    };
+}
+/** Nothing new for a while: say so, and where the details are. */
+export function stillWorking(what, ms) {
+    return ('Still working on ' +
+        clean(what, 80) +
+        ' (' +
+        Math.max(1, Math.round(ms / 60000)) +
+        ' min). Full log: sandbox logs -f');
+}
+export function readyIn(ms) {
+    return 'Ready in ' + elapsed(ms) + '.';
+}

package/dist/cli/commands/launch/boot-wants.d.ts

@@ -0,0 +1,11 @@
+import type { GenerateOptions, ResolvedRun } from '../../../core/types.js';
+import type { Context } from '../context.js';
+/**
+ * The other projects mapped at boot (a restart's, --session's, projects.all's, and the known projects in your roots),
+ * with their effective configs: only approved .sandbox-config.json files and the looser values you allowed for each
+ * (nothing is asked here). The sandbox boots with what they want too (host/launch/generate.ts).
+ */
+export declare function bootWantsFor(ctx: Context, run: ResolvedRun, extraProjects: string[] | undefined): Promise<{
+    wants: NonNullable<GenerateOptions['bootWants']>;
+    notes: string[];
+}>;

package/dist/cli/commands/launch/boot-wants.js

@@ -0,0 +1,48 @@
+// What the other projects mapped at boot want from the sandbox (a .wsb device, memory, their mappings).
+import path from 'node:path';
+import _ from 'lodash';
+import { planBootProjects } from '../../../host/launch/index.js';
+import { KnownProjects } from '../../../host/projects/index.js';
+import { isWithin } from '../../../shared/paths/index.js';
+import { BOOT_SETTINGS, LOCAL_CONFIG_NAME } from '../../../core/local-config/index.js';
+import { resolveRun } from '../../../core/run/index.js';
+import { dirExists, errMsg, fileExists } from '../../../core/util/index.js';
+/**
+ * The other projects mapped at boot (a restart's, --session's, projects.all's, and the known projects in your roots),
+ * with their effective configs: only approved .sandbox-config.json files and the looser values you allowed for each
+ * (nothing is asked here). The sandbox boots with what they want too (host/launch/generate.ts).
+ */
+export async function bootWantsFor(ctx, run, extraProjects) {
+    const { roots } = run.config.projects;
+    const planned = planBootProjects({ run, packageRoot: ctx.packageRoot, extraProjects }).projects.map((p) => p.host);
+    const inRoots = new KnownProjects(run.storageRoot)
+        .list()
+        .map((k) => k.host)
+        .filter((h) => roots.some((r) => isWithin(path.resolve(r), h)));
+    const folders = _.uniqBy([...(extraProjects ?? []).map((p) => path.resolve(p)), ...planned, ...inRoots], (f) => f.toLowerCase())
+        .filter((f) => !isWithin(run.workspaceHost, f) && dirExists(f))
+        .slice(0, 200);
+    const projects = [];
+    const notes = [];
+    for (const folder of folders) {
+        try {
+            const other = await resolveRun({
+                packageRoot: ctx.packageRoot,
+                loaded: ctx.loaded,
+                cwd: folder,
+                workspace: folder,
+                noAgent: true,
+                noLocalConfig: false,
+                trustConfig: false,
+                scripts: [],
+            });
+            projects.push({ name: path.basename(folder), config: other.config });
+        }
+        catch (e) {
+            if (fileExists(path.join(folder, LOCAL_CONFIG_NAME)))
+                notes.push('What ' + path.basename(folder) + ' asks for at boot is not included: ' + errMsg(e).split('\n')[0]);
+        }
+    }
+    const keepOff = BOOT_SETTINGS.filter((s) => _.get(ctx.loaded.config, s) === true && _.get(run.config, s) === false);
+    return { wants: { projects, keepOff }, notes };
+}

package/dist/cli/commands/launch/first-start.d.ts

@@ -0,0 +1,10 @@
+/** The wanted tools that are not downloaded yet (`has` says whether a folder in <data>\tools exists), with their rough size. */
+export declare function pendingDownloads(wanted: readonly string[], has: (dir: string) => boolean): {
+    names: string[];
+    mb: number;
+};
+/** The heads-up before the wait, or null when everything is already downloaded. first: nothing was ever installed. */
+export declare function firstStartNotice(first: boolean, pending: {
+    names: string[];
+    mb: number;
+}): string | null;

package/dist/cli/commands/launch/first-start.js

@@ -0,0 +1,53 @@
+// The first-start heads-up: what a start downloads once (the tools this project needs) and roughly how much.
+/** What a first start downloads, by setting name: its folder in <data>\tools, rough size and a readable name. */
+const DOWNLOADS = {
+    node: { dir: 'nvm', mb: 30 },
+    python: { dir: 'python', mb: 30 },
+    rust: { dir: 'rust', mb: 300 },
+    msvc: { dir: 'msvc', mb: 1500, label: 'MSVC' },
+    cpp: { dir: 'mingw', mb: 270, label: 'C/C++' },
+    dotnet: { dir: 'dotnet', mb: 250, label: '.NET' },
+    go: { dir: 'go', mb: 80 },
+    java: { dir: 'java', mb: 200 },
+    ruby: { dir: 'ruby', mb: 100 },
+    php: { dir: 'php', mb: 30 },
+    deno: { dir: 'deno', mb: 40 },
+    pwsh: { dir: 'pwsh', mb: 100, label: 'PowerShell 7' },
+    vscode: { dir: 'vscode', mb: 150, label: 'VS Code' },
+    postgres: { dir: 'postgres', mb: 330, label: 'PostgreSQL' },
+    mysql: { dir: 'mariadb', mb: 90, label: 'MariaDB' },
+    mongodb: { dir: 'mongodb', mb: 450, label: 'MongoDB' },
+    redis: { dir: 'redis', mb: 10 },
+    dynamodb: { dir: 'dynamodb-local', mb: 80, label: 'DynamoDB Local' },
+};
+/** The wanted tools that are not downloaded yet (`has` says whether a folder in <data>\tools exists), with their rough size. */
+export function pendingDownloads(wanted, has) {
+    const missing = [...new Set(wanted)].filter((w) => Object.hasOwn(DOWNLOADS, w) && !has(DOWNLOADS[w].dir));
+    return {
+        names: missing.map((w) => DOWNLOADS[w].label ?? w),
+        mb: missing.reduce((sum, w) => sum + DOWNLOADS[w].mb, 0),
+    };
+}
+function roughSize(mb) {
+    return mb >= 950 ? Math.round(mb / 100) / 10 + ' GB' : Math.max(10, Math.round(mb / 10) * 10) + ' MB';
+}
+/** The heads-up before the wait, or null when everything is already downloaded. first: nothing was ever installed. */
+export function firstStartNotice(first, pending) {
+    if (!first && !pending.names.length)
+        return null;
+    const what = pending.names.length
+        ? ' (about ' +
+            roughSize(pending.mb) +
+            ': ' +
+            pending.names.slice(0, 8).join(', ') +
+            (pending.names.length > 8 ? ', ...' : '') +
+            ')'
+        : '';
+    return first
+        ? 'First start: the sandbox downloads the tools this project needs once' +
+            what +
+            '. This can take 5-20 minutes depending on your connection; later starts take about a minute.'
+        : 'New tools for this project: the sandbox downloads them once' +
+            what +
+            '. This can take a few minutes; later starts skip it.';
+}

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

@@ -0,0 +1,6 @@
+export * from './launch.js';
+export * from './running.js';
+export * from './prepare.js';
+export * from './add-root.js';
+export { bootLine, readyIn, stillWorking } from './boot-progress.js';
+export { firstStartNotice, pendingDownloads } from './first-start.js';

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

@@ -0,0 +1,6 @@
+export * from './launch.js';
+export * from './running.js';
+export * from './prepare.js';
+export * from './add-root.js';
+export { bootLine, readyIn, stillWorking } from './boot-progress.js';
+export { firstStartNotice, pendingDownloads } from './first-start.js';

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

@@ -0,0 +1,8 @@
+import { type Context } from '../context.js';
+/** A restart that adds a project: map these too, start no session at boot (restart.ts opens them), wait until ready. */
+export interface LaunchExtras {
+    readonly extraProjects?: string[];
+    readonly autoSession?: boolean;
+    readonly waitUntilReady?: boolean;
+}
+export declare function launch(ctx: Context, generateOnly?: boolean, extras?: LaunchExtras): Promise<number>;