windows-development-sandbox 1.4.1 → 1.4.3

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

@@ -0,0 +1,211 @@
+// `launch` / `generate`, and what sandbox claude runs: start a sandbox, or another session in the running one. From a
+// folder the running sandbox does not have yet, the folder joins it (no restart) when it can, and otherwise a
+// restart that adds it is offered (restart.ts).
+import path from 'node:path';
+import _ from 'lodash';
+import { generateSandbox } from '../../../host/launch/index.js';
+import { findSecretFiles } from '../../../host/profile/index.js';
+import { RepoGuardStore } from '../../../host/guard/index.js';
+import { assertCanLaunch, isSandboxRunning, spawnDetached, startSandbox, probeHost, hideSandboxWindow, } from '../../../host/sandbox/index.js';
+import { KnownProjects, ProjectRegistry } from '../../../host/projects/index.js';
+import { LifeRecord } from '../../../host/life/index.js';
+import { isWithin } from '../../../shared/paths/index.js';
+import { watcherRunning } from '../../../sync/index.js';
+import { protectionsOf } from '../../../core/local-config/index.js';
+import { errMsg } from '../../../core/util/index.js';
+import { askYesNo } from '../../../core/prompt.js';
+import { resolveRun } from '../../../core/run/index.js';
+import { c, table } from '../../output/index.js';
+import { syncAgentCommands } from '../agent-commands.js';
+import { requireOnPc } from '../context.js';
+import { joinHere } from '../projects/index.js';
+import { startIntoRunning, launchIntoRunning, contextFor, waitForBoot, attachHere, waitForStart, openSession, readySandbox, } from './running.js';
+import { maybeAddRoot } from './add-root.js';
+import { prepare, firstBootNotice } from './prepare.js';
+import { bootWantsFor } from './boot-wants.js';
+import { launchSummary } from './summary.js';
+/** One launch (or `generate`): from the command line to a started sandbox, a session in it, or the written files. */
+class Launcher {
+    ctx;
+    generateOnly;
+    extras;
+    options;
+    constructor(ctx, generateOnly, extras) {
+        this.ctx = ctx;
+        this.generateOnly = generateOnly;
+        this.extras = extras;
+        this.options = ctx.options;
+    }
+    async run() {
+        const { options, generateOnly } = this;
+        // attach.auto: an agent started from an interactive terminal attaches it, as with -t.
+        if (this.ctx.loaded.config.attach.auto && !options.noAgent && process.stdin.isTTY && process.stdout.isTTY)
+            options.terminal = true;
+        if (!generateOnly)
+            requireOnPc('launch');
+        if (!generateOnly)
+            this.syncAgentCommands();
+        if (!generateOnly && isSandboxRunning())
+            return options.noAgent ? startIntoRunning(this.ctx, RELAUNCHER) : launchIntoRunning(this.ctx, RELAUNCHER);
+        if (options.sessions.length)
+            return this.launchSessions();
+        return this.launchHere();
+    }
+    /** agentCommands (Beta) follows the config: a setting changed in the file takes effect here too. Never blocks. */
+    syncAgentCommands() {
+        try {
+            syncAgentCommands(this.ctx, this.ctx.loaded.config);
+        }
+        catch (e) {
+            console.warn('Agent commands (Beta): ' + errMsg(e));
+        }
+    }
+    /**
+     * Several sessions: the sandbox starts from the first one's folder with the others' folders mapped too, then they
+     * all open in it (each project is set up on demand, in parallel). One --session is an ordinary launch.
+     */
+    async launchSessions() {
+        const { ctx, generateOnly, extras } = this;
+        const wants = this.options.sessions;
+        if (wants.length === 1)
+            return launch(contextFor(ctx, wants[0]), generateOnly, extras);
+        const first = contextFor(ctx, wants[0]);
+        const others = _.uniqBy(wants
+            .slice(1)
+            .map((w) => w.folder)
+            .filter((f) => !isWithin(wants[0].folder, f)), (f) => f.toLowerCase());
+        const started = await launch({ ...first, options: { ...first.options, terminal: false } }, generateOnly, {
+            ...extras,
+            extraProjects: [...(extras.extraProjects ?? []), ...others],
+            autoSession: false,
+            waitUntilReady: true,
+        });
+        return generateOnly || started !== 0 ? started : launchIntoRunning(ctx, RELAUNCHER);
+    }
+    resolve() {
+        const { options } = this;
+        return resolveRun({
+            packageRoot: this.ctx.packageRoot,
+            loaded: this.ctx.loaded,
+            cwd: process.cwd(),
+            workspace: options.workspace,
+            harness: options.harness,
+            noAgent: options.noAgent,
+            noLocalConfig: options.noLocalConfig,
+            trustConfig: options.trustConfig,
+            scripts: options.scripts,
+            databases: options.databases,
+            headless: options.headless,
+            nodeVersion: options.node,
+            pythonVersion: options.python,
+            ask: askYesNo,
+        });
+    }
+    /** One sandbox for this folder: resolve, prepare, write the launch files, then (unless generate) start it. */
+    async launchHere() {
+        const { ctx, generateOnly, extras } = this;
+        const run = await this.resolve();
+        const { config } = run;
+        if (!generateOnly)
+            assertCanLaunch();
+        if (!generateOnly && !extras.extraProjects)
+            await maybeAddRoot(ctx, run);
+        const prepared = generateOnly ? null : await prepare(ctx, run);
+        const bootWants = await bootWantsFor(ctx, run, extras.extraProjects);
+        const generated = generateSandbox({
+            packageRoot: ctx.packageRoot,
+            run,
+            harnessArgs: this.options.passthrough,
+            probe: probeHost(config, run.harnessName),
+            extraProjects: extras.extraProjects,
+            autoSession: extras.autoSession,
+            bootWants: bootWants.wants,
+        });
+        const notes = [...run.notes, ...bootWants.notes, ...generated.projects.notes, ...generated.mappingNotes];
+        for (const note of notes)
+            console.log(note);
+        this.warnSecretFiles(run);
+        table(launchSummary(run, generated, prepared));
+        if (generateOnly)
+            return 0;
+        this.record(run, generated);
+        startSandbox(generated.wsbPath);
+        this.startWatcher();
+        return this.afterStart(run, generated);
+    }
+    warnSecretFiles(run) {
+        const secretFiles = run.config.secrets.warnFiles ? findSecretFiles(run.workspaceHost) : [];
+        if (!secretFiles.length)
+            return;
+        const shown = secretFiles.slice(0, 12).join(', ') + (secretFiles.length > 12 ? ', ...' : '');
+        console.warn(c.yellow('Heads-up: the agent can read these files in your workspace, which often hold secrets: ' +
+            shown +
+            '. Move real credentials out of the folder (or use test ones). Silence with secrets.warnFiles = false.'));
+    }
+    /**
+     * Every folder the sandbox can write is snapshotted before it starts (the guard compares against this), and the
+     * projects it starts with are recorded host-side for the commands that run later.
+     */
+    record(run, generated) {
+        const { dataPath, storageRoot } = this.ctx;
+        const { config } = run;
+        const { roots, projects } = generated.projects;
+        new RepoGuardStore(dataPath).save(run.workspaceHost, projects.map((p) => p.host), roots.map((r) => r.host));
+        new ProjectRegistry(storageRoot).start({
+            launchId: generated.launchId,
+            protections: protectionsOf(generated.bootConfig),
+            primary: { host: run.workspaceHost, guest: config.guestWorkspace },
+            roots,
+            boot: projects,
+            atBoot: { memoryMb: generated.memoryMb, mappings: generated.mappings, widened: generated.widened },
+        });
+        new KnownProjects(storageRoot).remember(run.workspaceHost);
+        new LifeRecord(storageRoot, dataPath).start(config.sandbox.keepAwake);
+    }
+    /** Absolute: the watcher runs from another folder, and a relative --config there would make it exit silently. */
+    startWatcher() {
+        const { config } = this.options;
+        if (!watcherRunning(this.ctx.dataPath))
+            spawnDetached(this.ctx.entry, ['_watch', ...(config ? ['--config', path.resolve(config)] : [])]);
+    }
+    /** Waits for the boot and attaches when asked to; otherwise says where the agent opens. */
+    async afterStart(run, generated) {
+        const { ctx, options, extras } = this;
+        const { dataPath, storageRoot } = ctx;
+        const { config } = run;
+        // Hiding runs alongside; a failure to find the window must never break the launch or an attach.
+        const hidden = config.sandbox.headless ? hideSandboxWindow(storageRoot).catch(() => false) : null;
+        const headsUp = firstBootNotice(dataPath, generated, config);
+        if (options.terminal || options.noAgent || extras.waitUntilReady) {
+            if (headsUp)
+                console.log(headsUp);
+            await waitForBoot(dataPath, generated.launchId, Boolean(headsUp));
+            if (extras.waitUntilReady)
+                return 0;
+            // Without an agent there is no session to attach to: the sandbox itself is the result.
+            if (options.noAgent) {
+                console.log('Sandbox ready. Its window has a terminal in ' +
+                    config.guestWorkspace +
+                    '; from here: sandbox exec -- <command>, sandbox stop.');
+                return 0;
+            }
+            return attachHere(ctx, await waitForStart(ctx, generated.launchId, 'Starting ' + run.harnessName));
+        }
+        if (headsUp)
+            console.log(headsUp + '\nFollow along: sandbox logs -f');
+        if (hidden)
+            console.log((await hidden)
+                ? 'Sandbox running headless. Open the window: sbx-show   Attach here: sandbox claude -t'
+                : 'Could not find the sandbox window to hide (it may still be starting); run sandbox hide in a moment.');
+        else
+            console.log('Sandbox starting. ' +
+                run.harnessName +
+                ' opens in Windows Terminal inside it. Attach here any time: sandbox claude -t');
+        return 0;
+    }
+}
+export function launch(ctx, generateOnly = false, extras = {}) {
+    return new Launcher(ctx, generateOnly, extras).run();
+}
+/** What a restart (restart.ts) uses to start the sandbox again and reopen its sessions. */
+const RELAUNCHER = { launch, readySandbox, joinHere, openSession };

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

@@ -0,0 +1,23 @@
+import type { Config, ResolvedRun } from '../../../core/types.js';
+import { type Context } from '../context.js';
+/** Nothing has been installed into this data set yet: the first start downloads every toolchain once. */
+export declare function firstBoot(dataPath: string): boolean;
+/** The first-start heads-up (also when this project needs tools not downloaded yet), or null. */
+export declare function firstBootNotice(dataPath: string, generated: {
+    toolchains: Record<string, {
+        on: boolean;
+    }>;
+    databases: {
+        database: string;
+    }[];
+}, config: Config): string | null;
+/** What prepare did, for the launch summary. */
+export interface Prepared {
+    readonly account: string | null;
+    readonly terminal: string;
+    readonly history: string;
+    readonly pruned: string;
+    readonly filter: string;
+}
+/** Everything a real launch does before the sandbox starts (skipped by `generate`, which only writes files). */
+export declare function prepare(ctx: Context, run: ResolvedRun): Promise<Prepared>;

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

@@ -0,0 +1,109 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { AccountStore } from '../../../host/profile/index.js';
+import { SandboxChannel } from '../../../host/channel/index.js';
+import { describePrune, pruneStorage } from '../../../host/storage/index.js';
+import { RepoGuardStore, readDataSize, saveMarkedProjects } from '../../../host/guard/index.js';
+import { ensureConpty, ensureTerminal } from '../../../host/tools/index.js';
+import { planView, viewSkipped, saveActiveViews, WorkspaceView } from '../../../host/workspace-view/index.js';
+import { saveForwards } from '../../../host/network/index.js';
+import { saveAuditSettings } from '../../../host/audit/collect.js';
+import { humanBytes } from '../../../core/disk.js';
+import { syncBeforeLaunch, watcherRunning } from '../../../sync/index.js';
+import { errMsg } from '../../../core/util/index.js';
+import { c, working } from '../../output/index.js';
+import { firstStartNotice, pendingDownloads } from './first-start.js';
+import { LifeRecord, UPDATE_RESTART_WARNING, updateRestartPending } from '../../../host/life/index.js';
+/** Nothing has been installed into this data set yet: the first start downloads every toolchain once. */
+export function firstBoot(dataPath) {
+    return !fs.existsSync(path.join(dataPath, 'tools', 'resolved-versions.json'));
+}
+/** The first-start heads-up (also when this project needs tools not downloaded yet), or null. */
+export function firstBootNotice(dataPath, generated, config) {
+    const wanted = [
+        'node',
+        ...Object.entries(generated.toolchains)
+            .filter(([, d]) => d.on)
+            .map(([name]) => name),
+        ...(config.toolchains.vscode.enabled ? ['vscode'] : []),
+        ...generated.databases.map((d) => d.database),
+    ];
+    return firstStartNotice(firstBoot(dataPath), pendingDownloads(wanted, (dir) => fs.existsSync(path.join(dataPath, 'tools', dir))));
+}
+function syncSummary(config, dataPath, workspaceHost) {
+    try {
+        const s = syncBeforeLaunch(config, dataPath, workspaceHost);
+        return s.history + ' file(s) of history in, claude-mem ' + s.claudeMem;
+    }
+    catch (e) {
+        return 'FAILED: ' + errMsg(e);
+    }
+}
+/**
+ * workspaceFilter: brings the project's filtered view in step before the sandbox maps it, and tells the background
+ * watcher to keep it in step while the sandbox runs. Returns the line for the launch table.
+ */
+async function prepareWorkspaceView(ctx, run) {
+    const plan = planView(run.config, ctx.storageRoot, run.workspaceHost);
+    saveActiveViews(ctx.storageRoot, ctx.dataPath, plan ? [plan.options] : []);
+    saveForwards(ctx.storageRoot, ctx.dataPath, run.config.sandbox.networking ? run.config.network.forwardPorts : []);
+    saveAuditSettings(ctx.storageRoot, ctx.dataPath, { ...run.config.audit, projects: [run.workspaceHost] });
+    saveMarkedProjects(ctx.storageRoot, ctx.dataPath, run.config.storage.markSandboxFiles ? [run.workspaceHost] : []);
+    const size = readDataSize(ctx.storageRoot, ctx.dataPath);
+    const limit = run.config.storage.warnDataGb;
+    if (limit > 0 && size && size.bytes > limit * 1024 ** 3)
+        console.warn(c.yellow('The persisted data takes ' +
+            humanBytes(size.bytes) +
+            ' (more than storage.warnDataGb, ' +
+            limit +
+            ' GB). See what: sandbox data; free space: sandbox data clean <what>.'));
+    if (!plan)
+        return (viewSkipped(run.config, run.workspaceHost) ??
+            'off (git-ignored files are visible in the sandbox; workspaceFilter.enabled keeps them out)');
+    const stats = await working('Preparing the workspace without its git-ignored files', () => new WorkspaceView(plan.options).prepare());
+    return ('on: git-ignored files stay on this PC' +
+        (stats.toView || stats.toHost
+            ? ' (' +
+                stats.toView +
+                ' copied in, ' +
+                stats.toHost +
+                ' out' +
+                (stats.conflicts ? ', ' + stats.conflicts + ' conflicts kept next to the file' : '') +
+                ')'
+            : '') +
+        '; ' +
+        plan.options.view);
+}
+/** Everything a real launch does before the sandbox starts (skipped by `generate`, which only writes files). */
+export async function prepare(ctx, run) {
+    const { options, dataPath, storageRoot } = ctx;
+    const { config } = run;
+    const accounts = new AccountStore(storageRoot);
+    const account = options.account ?? accounts.defaultName();
+    if (account && run.harnessName === 'claude' && account !== accounts.activeFor(dataPath))
+        accounts.activate(dataPath, account);
+    const terminal = config.provisioning.terminal.enabled
+        ? await ensureTerminal(dataPath, config.provisioning.refresh, { pwsh: config.toolchains.pwsh.enabled !== false })
+        : { exe: null, message: 'disabled' };
+    const conpty = config.provisioning.conpty.enabled ? await ensureConpty(dataPath, config.provisioning.refresh) : 'off';
+    const history = syncSummary(config, dataPath, run.workspaceHost);
+    const guarded = new RepoGuardStore(dataPath).check();
+    if (guarded.length)
+        console.warn(c.yellow('SECURITY: neutralised ' +
+            guarded.length +
+            ' change(s) the last sandbox made that could run code on this PC (see sandbox status).'));
+    const stopped = new LifeRecord(storageRoot, dataPath).lastStopWarning(watcherRunning(dataPath));
+    if (stopped)
+        console.warn(c.yellow(stopped));
+    if (updateRestartPending())
+        console.warn(c.yellow(UPDATE_RESTART_WARNING));
+    new SandboxChannel(dataPath).reset();
+    const filter = await prepareWorkspaceView(ctx, run);
+    return {
+        account,
+        terminal: terminal.message + '; pseudo console: ' + conpty,
+        history,
+        pruned: describePrune(pruneStorage(storageRoot)),
+        filter,
+    };
+}

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

@@ -0,0 +1,45 @@
+import { attachTerminal } from '../../../host/channel/index.js';
+import type { SandboxStatus, SessionStatus } from '../../../core/types.js';
+import type { Context } from '../context.js';
+import { type Joined, type Relauncher } from '../projects/index.js';
+/** How openSession starts a session; restart.ts reopens sessions with reuse off and the agent's resume arguments. */
+export interface OpenSessionOptions {
+    readonly attach: boolean;
+    readonly harness?: string;
+    readonly args?: string[];
+    readonly reuse?: boolean;
+}
+/** A session to open: an agent (the default one when not given), a folder, arguments of its own. */
+interface Want {
+    readonly harness?: string;
+    readonly folder: string;
+    readonly args?: string[];
+}
+/**
+ * Attaches this terminal; with attach.autoHide the sandbox window hides meanwhile (best effort, never fails the
+ * attach).
+ */
+export declare function attachHere(ctx: Context, session: Parameters<typeof attachTerminal>[0]): Promise<number>;
+/** The sandbox writes sandbox.json a few seconds into its boot; a second launch right after the first waits for it. */
+export declare function runningSandboxStatus(dataPath: string): Promise<SandboxStatus>;
+/**
+ * Waits for the boot with its current step and what it sets up on one line (plain lines without a terminal).
+ * timed: say how long it took (a first start, where that is worth knowing).
+ */
+export declare function waitForBoot(dataPath: string, launchId: string | null, timed?: boolean): Promise<SandboxStatus>;
+/** The running sandbox, once it is ready. */
+export declare function readySandbox(dataPath: string): Promise<SandboxStatus>;
+/** Waits for a session to start (its project's setup, the agent's install) with its progress on a spinner. */
+export declare function waitForStart(ctx: Context, requestId: string, what: string): Promise<SessionStatus>;
+/**
+ * Starts (or picks back up) a session in the folder `joined` describes. attach: show it in this terminal.
+ * Exported for restart.ts, which reopens the sessions a restart ended.
+ */
+export declare function openSession(ctx: Context, ready: SandboxStatus, joined: Joined, o: OpenSessionOptions): Promise<number>;
+/** The same command, for one of its sessions (its folder, agent, and the arguments after -- plus its own). */
+export declare function contextFor(ctx: Context, want: Want): Context;
+/** A sandbox is already running: open the sessions in it (new tabs inside; optionally attach here). */
+export declare function launchIntoRunning(ctx: Context, relauncher: Relauncher): Promise<number>;
+/** `sandbox start` while one runs: this folder joins it (set up, no agent), or a restart that adds it is offered. */
+export declare function startIntoRunning(ctx: Context, relauncher: Relauncher): Promise<number>;
+export {};

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

@@ -0,0 +1,218 @@
+// A sandbox that is already running: wait for it, open sessions in it, attach this terminal to one.
+import _ from 'lodash';
+import { attachTerminal, findUnwatchedSession, SandboxChannel } from '../../../host/channel/index.js';
+import { insideSandbox, hideSandboxWindow, showSandboxWindow } from '../../../host/sandbox/index.js';
+import { NeedsRestart } from '../../../host/projects/index.js';
+import { RunDir } from '../../../shared/channel/index.js';
+import { errMsg, fail, sleep } from '../../../core/util/index.js';
+import { c, follow, working, table } from '../../output/index.js';
+import { bootLine, readyIn, stillWorking } from './boot-progress.js';
+import { hereDir, joinHere, readyHere, offerRestart } from '../projects/index.js';
+/** How long a session may take to start (its project's setup, the agent's install). */
+const SESSION_START_MS = 60 * 60 * 1000;
+/**
+ * Attaches this terminal; with attach.autoHide the sandbox window hides meanwhile (best effort, never fails the
+ * attach).
+ */
+export function attachHere(ctx, session) {
+    if (ctx.loaded.config.attach.autoHide && !insideSandbox())
+        void hideSandboxWindow(ctx.storageRoot, 120).catch(() => false);
+    return attachTerminal(session);
+}
+/** The sandbox writes sandbox.json a few seconds into its boot; a second launch right after the first waits for it. */
+export async function runningSandboxStatus(dataPath) {
+    const run = new RunDir(dataPath);
+    for (let i = 0; i < 60; i++) {
+        const status = run.readSandboxStatus();
+        if (status)
+            return status;
+        await sleep(1000);
+    }
+    return fail('A Windows Sandbox is running that this tool did not start (or that uses another storage.dataName).', 'Close that sandbox window first, then run sandbox claude again.');
+}
+/**
+ * Waits for the boot with its current step and what it sets up on one line (plain lines without a terminal).
+ * timed: say how long it took (a first start, where that is worth knowing).
+ */
+export async function waitForBoot(dataPath, launchId, timed = false) {
+    let status = null;
+    const start = Date.now();
+    const ready = await follow(() => bootLine(status), () => new SandboxChannel(dataPath).waitForReady(launchId, () => undefined, (s) => {
+        if (s.phase !== 'failed')
+            status = s;
+    }), { stall: stillWorking });
+    if (timed)
+        console.log(readyIn(Date.now() - start));
+    return ready;
+}
+/** The running sandbox, once it is ready. */
+export async function readySandbox(dataPath) {
+    const status = await runningSandboxStatus(dataPath);
+    return status.phase === 'ready' ? status : waitForBoot(dataPath, status.launchId);
+}
+/** Waits for a session to start (its project's setup, the agent's install) with its progress on a spinner. */
+export function waitForStart(ctx, requestId, what) {
+    let step = 'starting';
+    const shown = () => ({ line: what + ': ' + step, key: step, what: step });
+    return follow(shown, () => new SandboxChannel(ctx.dataPath).waitForSession(requestId, SESSION_START_MS, (m) => {
+        step = m;
+    }), { stall: stillWorking });
+}
+/** Asks the sandbox for a session; the agent's definition goes along (the sandbox may have booted with another). */
+function requestSession(ctx, channel, harness, args, joined) {
+    const harnessSpec = ctx.loaded.config.harnesses[harness];
+    return channel.requestSession(harness, args, joined.guestDir, {
+        ...(joined.spec ? { project: joined.spec } : {}),
+        ...(harnessSpec ? { harnessSpec } : {}),
+    });
+}
+/**
+ * Starts (or picks back up) a session in the folder `joined` describes. attach: show it in this terminal.
+ * Exported for restart.ts, which reopens the sessions a restart ended.
+ */
+export async function openSession(ctx, ready, joined, o) {
+    const { options, loaded, dataPath } = ctx;
+    const cwd = joined.guestDir;
+    const harness = o.harness ?? options.harness ?? joined.harness ?? loaded.config.defaultHarness;
+    const args = o.args ?? options.passthrough;
+    // -t with nothing new for the agent: pick up this folder's session if no terminal on this PC shows it (its tab was
+    // closed, or you detached). Someone already attached, --new, or agent arguments: a new session, as before.
+    const reuse = (o.reuse ?? true) && o.attach && !options.newSession && args.length === 0 && loaded.config.attach.reuseSession;
+    const existing = reuse ? await findUnwatchedSession(dataPath, harness, cwd) : null;
+    if (existing) {
+        console.log('Reattaching to ' +
+            harness +
+            ' session ' +
+            existing.id +
+            ' in ' +
+            cwd +
+            ' (no other terminal is attached; --new starts another).');
+        return attachHere(ctx, existing);
+    }
+    console.log(joined.spec
+        ? 'Starting ' +
+            harness +
+            ' for ' +
+            joined.project?.host +
+            ' in the running sandbox (' +
+            cwd +
+            '; the first time sets up what it needs).'
+        : 'Sandbox already running: starting another ' + harness + ' session in ' + cwd);
+    const requestId = requestSession(ctx, new SandboxChannel(dataPath), harness, args, joined);
+    const session = await waitForStart(ctx, requestId, 'Starting ' + harness + ' in ' + cwd);
+    if (o.attach)
+        return attachHere(ctx, session);
+    console.log('Session ' +
+        session.id +
+        ' opened in a new tab inside the sandbox. Attach here with: sandbox attach ' +
+        session.id +
+        (ready.headless ? '   (headless: sbx-show opens the window)' : ''));
+    return 0;
+}
+/** The sessions a launch asks for: each --session, else one (the agent, in this folder). */
+function wantedSessions(ctx) {
+    return ctx.options.sessions.length ? ctx.options.sessions : [{ harness: ctx.options.harness, folder: hereDir(ctx) }];
+}
+/** The same command, for one of its sessions (its folder, agent, and the arguments after -- plus its own). */
+export function contextFor(ctx, want) {
+    return {
+        ...ctx,
+        options: {
+            ...ctx.options,
+            workspace: want.folder,
+            harness: want.harness,
+            sessions: [],
+            passthrough: [...ctx.options.passthrough, ...(want.args ?? [])],
+        },
+    };
+}
+/**
+ * Several sessions at once: all requested together (projects set up in parallel), then listed; -t attaches the first.
+ */
+async function openSessions(ctx, ready, list) {
+    const { loaded, options } = ctx;
+    const channel = new SandboxChannel(ctx.dataPath);
+    const requests = list.map(({ ctx: at, joined }) => {
+        const harness = at.options.harness ?? joined.harness ?? loaded.config.defaultHarness;
+        const id = requestSession(ctx, channel, harness, at.options.passthrough, joined);
+        return { id, harness, folder: at.options.workspace ?? joined.guestDir, cwd: joined.guestDir };
+    });
+    let started = 0;
+    const results = await working(() => 'Starting ' + requests.length + ' sessions (' + started + ' running)', () => Promise.allSettled(requests.map(async (r) => {
+        const s = await channel.waitForSession(r.id, SESSION_START_MS, () => undefined);
+        started++;
+        return s;
+    })));
+    table([
+        ['SESSION', 'AGENT', 'FOLDER', ''],
+        ...requests.map((r, i) => {
+            const result = results[i];
+            return [
+                r.id,
+                r.harness,
+                r.folder,
+                result.status === 'fulfilled' ? 'running   sandbox attach ' + r.id : c.red('FAILED: ' + errMsg(result.reason)),
+            ];
+        }),
+    ]);
+    const first = results.find((r) => r.status === 'fulfilled');
+    if (options.terminal && first)
+        return attachHere(ctx, first.value);
+    if (!first)
+        return 1;
+    console.log('Each has its own tab inside the sandbox' +
+        (ready.headless ? ' (headless: sbx-show opens the window)' : '') +
+        '. Attach to any of them, from any terminal: sandbox attach');
+    return results.every((r) => r.status === 'fulfilled') ? 0 : 1;
+}
+/** A sandbox is already running: open the sessions in it (new tabs inside; optionally attach here). */
+export async function launchIntoRunning(ctx, relauncher) {
+    const ready = await readySandbox(ctx.dataPath);
+    // Every folder joins first: when one needs a restart, nothing has been started that the restart would end.
+    const joined = [];
+    const needs = [];
+    for (const want of wantedSessions(ctx)) {
+        const at = ctx.options.sessions.length ? contextFor(ctx, want) : ctx;
+        try {
+            joined.push({ ctx: at, joined: await joinHere(at, ready) });
+        }
+        catch (e) {
+            if (!(e instanceof NeedsRestart))
+                throw e;
+            if (!needs.some((n) => n.hostDir.toLowerCase() === e.hostDir.toLowerCase()))
+                needs.push(e);
+        }
+    }
+    if (needs.length)
+        return offerRestart(ctx, needs, () => launchIntoRunning(ctx, relauncher), relauncher);
+    for (const note of _.uniq(joined.flatMap((j) => j.joined.notes)))
+        console.log(note);
+    if (joined.length === 1)
+        return openSession(joined[0].ctx, ready, joined[0].joined, { attach: ctx.options.terminal });
+    return openSessions(ctx, ready, joined);
+}
+/** `sandbox start` while one runs: this folder joins it (set up, no agent), or a restart that adds it is offered. */
+export async function startIntoRunning(ctx, relauncher) {
+    const ready = await readySandbox(ctx.dataPath);
+    let joined;
+    try {
+        joined = await readyHere(ctx, ready);
+    }
+    catch (e) {
+        if (e instanceof NeedsRestart)
+            return offerRestart(ctx, [e], () => startIntoRunning(ctx, relauncher), relauncher);
+        throw e;
+    }
+    const where = joined.spec
+        ? ' This folder is ready in it as ' +
+            joined.guestDir +
+            ' (sbx-shell ' +
+            joined.spec.name +
+            ' opens a terminal there inside).'
+        : '';
+    console.log('A sandbox is already running' +
+        (showSandboxWindow(ctx.storageRoot) ? '; its window is in front now.' : '.') +
+        where +
+        ' Start an agent in it with sandbox claude (or sandbox <agent>); stop it with sandbox stop.');
+    return 0;
+}

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

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