windows-development-sandbox 1.4.1 → 1.5.0

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 not downloaded yet (`has`: does a folder in <data>\tools exist), 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,11 @@
+import { type Context } from '../context.js';
+import { type Relauncher } from '../sessions/reopen.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>;
+/** What a restart (restart.ts) uses to start the sandbox again and reopen its sessions. */
+export declare const RELAUNCHER: Relauncher;

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

@@ -0,0 +1,273 @@
+// `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, SessionLedger } 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 { useSharedSandbox } from '../shared-use.js';
+import { beginSharing, currentUserName, currentUserSid, listProcesses, runningOwner, sessionOf, sharingDeps, takeSharingNotice, } from '../../../host/sharing/index.js';
+import { packageVersion } from '../../../core/package-info.js';
+import { reopenedText, reopenSessions } from '../sessions/reopen.js';
+import { sessionsToResume } from './resume-offer.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()) {
+            // Another user's sandbox: an agent session in a project it has, when it is shared; nothing else.
+            const ctx = await useSharedSandbox(this.ctx, options.noAgent ? { kind: 'owner-only', what: 'start a sandbox' } : { kind: 'use' });
+            return options.noAgent ? startIntoRunning(ctx, RELAUNCHER) : launchIntoRunning(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(isSandboxRunning() ? runningOwner() : undefined);
+        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;
+        // A restart or sandbox resume reopens sessions itself (they pass the projects they keep).
+        const reopen = extras.extraProjects ? [] : await sessionsToResume(ctx, run);
+        this.record(run, generated);
+        this.share(generated);
+        startSandbox(generated.wsbPath);
+        this.startWatcher();
+        if (reopen.length)
+            await this.reopenAfterBoot(generated.launchId, reopen);
+        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);
+        new SessionLedger(storageRoot, dataPath).startLaunch({
+            primary: run.workspaceHost,
+            harness: this.options.noAgent ? null : run.harnessName,
+            projects: projects.map((p) => p.host).filter((host) => host.toLowerCase() !== run.workspaceHost.toLowerCase()),
+            headless: config.sandbox.headless,
+            configPath: this.options.config ? path.resolve(this.options.config) : null,
+        });
+    }
+    /**
+     * An all-users install: whose sandbox this is (the record other users read) and, when sharing is on, the folder
+     * permissions that let the group use it. Done before the sandbox starts, so it never runs unrecorded.
+     */
+    share(generated) {
+        const deps = sharingDeps(this.ctx.packageRoot);
+        if (!deps)
+            return;
+        // Only the shared tree may be opened to the group: never a storage folder of your own (your profile, say).
+        const inSharedTree = isWithin(deps.usersDir, this.ctx.dataPath);
+        if (this.ctx.loaded.config.sharing.otherUsers && !inSharedTree)
+            console.log(c.yellow('This sandbox is not shared: its data is in ' +
+                this.ctx.dataPath +
+                ', outside ' +
+                deps.usersDir +
+                '. Remove storage.root from your config to use the shared folder.'));
+        const shared = this.ctx.loaded.config.sharing.otherUsers && inSharedTree;
+        const rows = listProcesses();
+        beginSharing(deps, {
+            user: currentUserName(),
+            sid: currentUserSid(),
+            windowsSession: sessionOf(rows) ?? 0,
+            dataPath: this.ctx.dataPath,
+            shared,
+            version: packageVersion(),
+            projects: generated.projects.projects.map((p) => ({
+                id: path.basename(p.host),
+                hostPath: p.host,
+                guestPath: p.guest,
+            })),
+        });
+        const notice = shared ? takeSharingNotice(this.ctx.storageRoot) : null;
+        if (notice)
+            console.log(c.yellow(notice));
+    }
+    /** Waits for the boot, then opens the sessions of the last sandbox in it (each in its own tab). */
+    async reopenAfterBoot(launchId, reopen) {
+        const { ctx } = this;
+        const ready = await waitForBoot(ctx.dataPath, launchId);
+        const opened = await reopenSessions(ctx, ready, reopen, RELAUNCHER);
+        console.log(reopenedText(opened, reopen.length, reopen));
+    }
+    /** 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);
+        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. */
+export const RELAUNCHER = { launch, readySandbox, joinHere, openSession };

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

@@ -0,0 +1,23 @@
+import type { 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;
+    }[];
+}): 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,108 @@
+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) {
+    const wanted = [
+        'node',
+        ...Object.entries(generated.toolchains)
+            .filter(([, d]) => d.on)
+            .map(([name]) => name),
+        ...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/resume-offer.d.ts

@@ -0,0 +1,8 @@
+import type { ResolvedRun } from '../../../core/types.js';
+import type { Context } from '../context.js';
+import { type Reopen } from '../sessions/reopen.js';
+/**
+ * The sessions to open once this launch's sandbox is ready: none unless resume.sessions says so (and, for "ask", you
+ * say yes). Call it before the launch overwrites the record of how the last sandbox lived.
+ */
+export declare function sessionsToResume(ctx: Context, run: ResolvedRun): Promise<Reopen[]>;

package/dist/cli/commands/launch/resume-offer.js

@@ -0,0 +1,41 @@
+// A launch after a sandbox that had agent sessions: say what ran last time and, as `resume.sessions` says, ask whether
+// to open it again, do it, or only name the command. The sessions open once the new sandbox is ready (launch.ts).
+import { askYesNo } from '../../../core/prompt.js';
+import { describeLast, LifeRecord, SessionLedger, shouldReopen } from '../../../host/life/index.js';
+import { watcherRunning } from '../../../sync/index.js';
+import { c } from '../../output/index.js';
+import { ledgerToReopen, notRunningYet } from '../sessions/reopen.js';
+/** Says the watcher gave up restarting the sandbox by itself (once). */
+function sayGaveUp(ledger) {
+    if (ledger.takeGaveUp())
+        console.log(c.yellow('The sandbox ended unexpectedly three times in six hours, so it was not started again by itself (resume.restartAfterCrash). sandbox resume starts it and reopens its sessions.'));
+}
+/**
+ * The sessions to open once this launch's sandbox is ready: none unless resume.sessions says so (and, for "ask", you
+ * say yes). Call it before the launch overwrites the record of how the last sandbox lived.
+ */
+export async function sessionsToResume(ctx, run) {
+    const { storageRoot, dataPath } = ctx;
+    const store = new SessionLedger(storageRoot, dataPath);
+    sayGaveUp(store);
+    const saved = store.read();
+    const life = new LifeRecord(storageRoot, dataPath).read();
+    const decision = shouldReopen(ctx.loaded.config.resume.sessions, life, saved, watcherRunning(dataPath));
+    if (decision === 'no' || !saved)
+        return [];
+    // The session this launch starts by itself is not opened twice.
+    const mine = ctx.options.noAgent ? [] : [{ harness: run.harnessName, hostDir: run.workspaceHost }];
+    const reopen = notRunningYet(ledgerToReopen(saved.sessions), mine);
+    if (!reopen.length)
+        return [];
+    const last = describeLast(saved.sessions);
+    if (decision === 'reopen') {
+        console.log('Last time: ' + last + '.');
+        return reopen;
+    }
+    if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+        console.log('Last time: ' + last + '. To open them again: sandbox resume');
+        return [];
+    }
+    return (await askYesNo('Last time: ' + last + '. Reopen them?', true)) ? reopen : [];
+}

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 {};