windows-development-sandbox 1.5.0 → 1.9.0

package/dist/core/schema/web.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+export declare const WEB_DEFAULT_PORT = 47800;
+export declare const WebSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    port: z.ZodNumber;
+}, z.core.$strict>;

package/dist/core/schema/web.js

@@ -0,0 +1,14 @@
+// The web UI settings (sandbox web): not part of LocalOverrides, a repo never turns a way into your agents on.
+import { z } from 'zod';
+export const WEB_DEFAULT_PORT = 47800;
+export const WebSchema = z.strictObject({
+    enabled: z
+        .boolean()
+        .describe('(Beta) Allow the web UI: your sandbox sessions in a browser on this PC. Off by default, and nothing starts it by itself yet: sandbox web start works either way and runs it until sandbox web stop (or a restart of the PC).'),
+    port: z
+        .number()
+        .int()
+        .min(1024)
+        .max(65535)
+        .describe('Port of the web UI on 127.0.0.1 (this PC only). Pick another when it is taken.'),
+});

package/dist/core/types.d.ts

@@ -102,6 +102,19 @@ export interface DatabasePlan {
     port: number;
     adminPort?: number;
 }
+/** The VPN decided at launch (host/vpn/prepare.ts): its checked profile, and the login for the one-shot file. */
+export interface PreparedVpn {
+    session: GuestVpn;
+    /** openvpn: the profile text, already checked (goes in the launch folder). */
+    profile?: string;
+    /** openvpn: the login (one-shot file). */
+    credentials?: {
+        username: string;
+        password: string;
+    };
+    /** wireguard-file: the checked config; holds the private key (one-shot file only). */
+    wireguardConfig?: string;
+}
 /** databases / pcLanguages: use these instead of scanning (tests). */
 export interface GenerateOptions {
     packageRoot: string;
@@ -109,6 +122,8 @@ export interface GenerateOptions {
     harnessArgs: string[];
     probe: HostProbe;
     freeMemoryBytes?: number;
+    /** This PC's unused commit (RAM plus paging file) in MB from HostTools memory-status; omitted = not checked. */
+    commitAvailableMb?: number | null;
     databases?: DatabasePlan[];
     pcLanguages?: AutoToolchain[];
     /**
@@ -124,6 +139,10 @@ export interface GenerateOptions {
         projects: BootWant[];
         keepOff: string[];
     };
+    /** The VPN for this launch (vpn.enabled); its profile goes in the launch folder, its login in the one-shot file. */
+    vpn?: PreparedVpn;
+    /** The data set's mappings from a storage provider (contained storage); else the data folder is one mapping. */
+    dataMappings?: ResolvedMapping[];
 }
 export interface Generated {
     wsbPath: string;
@@ -131,6 +150,8 @@ export interface Generated {
     launchId: string;
     sessionPath: string;
     memoryMb: number;
+    /** Plain words when the PC's commit made the memory much smaller than free RAM allowed. */
+    memoryNote: string | null;
     /** The config the sandbox boots with: the launch folder's plus what the other projects mapped at boot want. */
     bootConfig: Config;
     /** Boot settings turned on for another project (setting -> project). */
@@ -162,6 +183,16 @@ export interface ProfileResult {
     credentials: boolean;
     secretsRemoved: string[];
 }
+/** The VPN of one launch: what the guest needs besides the login (which comes in the one-shot secrets file). */
+export interface GuestVpn {
+    provider: Config['vpn']['provider'];
+    protocol: Config['vpn']['protocol'];
+    killSwitch: boolean;
+    /** The server's name, for messages. */
+    server: string;
+    /** openvpn: the checked profile, relative to the launch folder (none for wireguard-file: its config is a secret). */
+    profile?: string;
+}
 /** Written by the host to C:\AgentLaunch\session.json (read-only for the guest): everything the guest needs to know. */
 export interface GuestSession {
     launchId: string;
@@ -196,6 +227,8 @@ export interface GuestSession {
     attach: Config['attach'];
     hooks: Config['hooks'];
     downloads: Config['downloads'];
+    /** Set when the VPN is on for this launch (older launch folders lack it). */
+    vpn?: GuestVpn;
     /** nodeVersion: this PC's Node (e.g. 22.11.0), found under nvm\v<version> when nvm is mapped, else under node. */
     /** volta / pyenv: this PC uses them (their "auto" settings turn them on in the sandbox too). */
     hostTools: {
@@ -229,6 +262,15 @@ export interface GuestSession {
     cpuLimitPercent?: number | null;
     /** sandbox.pageFileMb (0 = Windows' own); sandbox\scripts\set-page-file.ps1 applies it at logon. */
     pageFileMb?: number;
+    /**
+     * sandbox.agentMemoryHeadroomMb as a limit: the most memory (MB) everything the agents start may use together
+     * (the sandbox's memory minus the headroom); null = no limit. ptyhost puts each agent in a job object with it.
+     */
+    agentMemoryLimitMb?: number | null;
+    /** "gentle" when vGPU is on: the governor and the watchdog act earlier, compilers run below normal. */
+    loadProfile?: 'normal' | 'gentle';
+    /** sandbox.pressureResponse: the daemon slows builds down when memory runs low. */
+    pressureResponse?: boolean;
     /** Apps to install (catalogue ids and your own programs); missing in launch folders of older versions. */
     apps?: Config['apps'];
     /** audit.enabled and audit.processes: the sandbox reports the programs it starts (host keeps the log). */
@@ -237,4 +279,6 @@ export interface GuestSession {
     agentHomes?: Record<string, string>;
     /** Per agent: folders of the user profile (.qwen ...) linked into the persistent state at boot. */
     agentProfileDirs?: Record<string, string[]>;
+    /** Every configured agent (without its environment): a terminal command each; older launch folders lack it. */
+    agents?: Record<string, Harness>;
 }

package/dist/core/util/fs.d.ts

@@ -1,6 +1,8 @@
 export declare function ensureDir(p: string): void;
 export declare function dirExists(p: string): boolean;
 export declare function fileExists(p: string): boolean;
+/** fileExists without blocking the program (the menu looks for programs while it stays responsive). */
+export declare function fileExistsAsync(p: string): Promise<boolean>;
 export declare function readJson<T>(p: string): T;
 export declare function tryReadJson<T>(p: string): T | null;
 /** Atomic (a crash or a second command never leaves half a file); refused outside temp during the self-test. */

package/dist/core/util/fs.js

@@ -19,6 +19,15 @@ export function fileExists(p) {
         return false;
     }
 }
+/** fileExists without blocking the program (the menu looks for programs while it stays responsive). */
+export async function fileExistsAsync(p) {
+    try {
+        return (await fs.promises.stat(p)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 export function readJson(p) {
     return JSON.parse(fs.readFileSync(p, 'utf8').replace(/^\uFEFF/, ''));
 }

package/dist/core/util/index.d.ts

@@ -1,7 +1,7 @@
 export { isWin, sleep, captureOutput } from './process.js';
 export { UserError, fail, errMsg } from './errors.js';
 export { parseJsonc, readJsonc } from './jsonc.js';
-export { ensureDir, dirExists, fileExists, readJson, tryReadJson, writeJson, realPath } from './fs.js';
+export { ensureDir, dirExists, fileExists, fileExistsAsync, readJson, tryReadJson, writeJson, realPath } from './fs.js';
 export { xmlEscape, safeText, plainText } from './text.js';
 export { homeDir, expandPath, expandVariables, isRootPath, isUserProfile, isInsideOrEqual, findOnPath, } from './paths.js';
 export { isLink, removeLink, assertNoLinks } from './links.js';

package/dist/core/util/index.js

@@ -1,7 +1,7 @@
 export { isWin, sleep, captureOutput } from './process.js';
 export { UserError, fail, errMsg } from './errors.js';
 export { parseJsonc, readJsonc } from './jsonc.js';
-export { ensureDir, dirExists, fileExists, readJson, tryReadJson, writeJson, realPath } from './fs.js';
+export { ensureDir, dirExists, fileExists, fileExistsAsync, readJson, tryReadJson, writeJson, realPath } from './fs.js';
 export { xmlEscape, safeText, plainText } from './text.js';
 export { homeDir, expandPath, expandVariables, isRootPath, isUserProfile, isInsideOrEqual, findOnPath, } from './paths.js';
 export { isLink, removeLink, assertNoLinks } from './links.js';

package/dist/guest/agents/agent-files.d.ts

@@ -0,0 +1,54 @@
+import type { Harness } from '../../core/types.js';
+/** Where an agent lives in persistent storage: its folder, and the program (an .exe, or an npm .cmd) in it. */
+export interface AgentPaths {
+    readonly dir: string;
+    readonly exe: string | null;
+    readonly cmd: string | null;
+}
+export declare function agentPaths(toolsDir: string, name: string, harness: Harness): AgentPaths;
+/** The word a user types for this agent (`claude`, `codex` ...). */
+export declare function agentCommand(name: string, harness: Harness): string;
+/** What a terminal needs to run the agent by name: the command, and the program it runs once installed. */
+export interface AgentShim {
+    readonly name: string;
+    readonly command: string;
+    readonly target: string;
+}
+/** One shim per configured agent that can be installed here (a name that is not a plain command word is skipped). */
+export declare function agentShims(toolsDir: string, agents: Readonly<Record<string, Harness>>): AgentShim[];
+/**
+ * The text of `<command>.cmd`: runs the installed agent, or installs it first (`install` = node + installer script).
+ * The agent's own arguments pass through %* untouched.
+ */
+export declare function shimText(shim: AgentShim, install: {
+    node: string;
+    script: string;
+}): string;
+/** The `sbx-agent` command: `sbx-agent install <agent>` / `sbx-agent list`. */
+export declare function sbxAgentText(install: {
+    node: string;
+    script: string;
+}): string;
+/** A SQLite folder an agent runs from the sandbox's disk: the variable that points to `local`, and its saved copy. */
+export interface LocalState {
+    readonly agent: string;
+    readonly env: string;
+    /** The saved copy in persistent storage (state\<agent>\<folder>). */
+    readonly store: string;
+    /** The working copy on the sandbox's own disk. */
+    readonly local: string;
+    /** Image names of the programs that hold the databases open while they run. */
+    readonly processes: readonly string[];
+    /** Where the agent kept the databases before this existed (its state folder itself). */
+    readonly legacy: string;
+}
+export declare function localStateEntries(agents: Readonly<Record<string, Harness>>, stateDir: string, localRoot: string): LocalState[];
+/** Every agent's bootReset paths, absolute below its state folder (the schema allows only plain relative paths). */
+export declare function bootResetPaths(agents: Readonly<Record<string, Harness>>, stateDir: string): {
+    agent: string;
+    path: string;
+}[];
+/** A SQLite database file or one of its -wal / -shm siblings. */
+export declare const isDatabaseFile: (name: string) => boolean;
+/** Files that make a consistent copy: the databases and their -wal (the -shm is rebuilt by SQLite). */
+export declare const isCopyableDatabaseFile: (name: string) => boolean;

package/dist/guest/agents/agent-files.js

@@ -0,0 +1,67 @@
+// Pure parts of the agents' files: where an agent is installed, the command that starts it in a terminal tab, and the
+// SQLite folders it runs from the sandbox's own disk. No side effects: the self-test imports this file.
+import path from 'node:path';
+export function agentPaths(toolsDir, name, harness) {
+    const dir = path.join(toolsDir, 'agents', name);
+    const exe = harness.hostExecutable ?? (harness.uvBin ? harness.uvBin + '.exe' : null);
+    return {
+        dir,
+        exe: exe ? path.join(dir, exe) : null,
+        cmd: harness.npmBin ? path.join(dir, harness.npmBin + '.cmd') : null,
+    };
+}
+/** The word a user types for this agent (`claude`, `codex` ...). */
+export function agentCommand(name, harness) {
+    return harness.npmBin ?? harness.uvBin ?? (harness.hostExecutable ?? name).replace(/\.exe$/i, '');
+}
+/** One shim per configured agent that can be installed here (a name that is not a plain command word is skipped). */
+export function agentShims(toolsDir, agents) {
+    return Object.entries(agents).flatMap(([name, harness]) => {
+        const p = agentPaths(toolsDir, name, harness);
+        const target = p.exe ?? p.cmd;
+        const command = agentCommand(name, harness);
+        return target && /^[A-Za-z0-9_-]+$/.test(command) && /^[A-Za-z0-9_-]+$/.test(name)
+            ? [{ name, command, target }]
+            : [];
+    });
+}
+/**
+ * The text of `<command>.cmd`: runs the installed agent, or installs it first (`install` = node + installer script).
+ * The agent's own arguments pass through %* untouched.
+ */
+export function shimText(shim, install) {
+    return [
+        '@echo off',
+        'setlocal',
+        'set "SBX_REAL=' + shim.target + '"',
+        'if exist "%SBX_REAL%" goto run',
+        'echo ' + shim.command + ' is not installed in this sandbox yet. Installing it now (one time)...',
+        '"' + install.node + '" "' + install.script + '" install ' + shim.name,
+        'if errorlevel 1 exit /b 1',
+        ':run',
+        'endlocal & "%SBX_REAL%" %*',
+        '',
+    ].join('\r\n');
+}
+/** The `sbx-agent` command: `sbx-agent install <agent>` / `sbx-agent list`. */
+export function sbxAgentText(install) {
+    return '@"' + install.node + '" "' + install.script + '" %*\r\n';
+}
+export function localStateEntries(agents, stateDir, localRoot) {
+    return Object.entries(agents).flatMap(([agent, harness]) => Object.entries(harness.localState ?? {}).map(([env, folder]) => ({
+        agent,
+        env,
+        store: path.join(stateDir, agent, folder),
+        local: path.join(localRoot, agent, folder),
+        processes: [agentCommand(agent, harness) + '.exe'],
+        legacy: path.join(stateDir, agent),
+    })));
+}
+/** Every agent's bootReset paths, absolute below its state folder (the schema allows only plain relative paths). */
+export function bootResetPaths(agents, stateDir) {
+    return Object.entries(agents).flatMap(([agent, harness]) => (harness.bootReset ?? []).map((rel) => ({ agent, path: path.join(stateDir, agent, rel) })));
+}
+/** A SQLite database file or one of its -wal / -shm siblings. */
+export const isDatabaseFile = (name) => /\.(sqlite3?|db)(-wal|-shm)?$/i.test(name);
+/** Files that make a consistent copy: the databases and their -wal (the -shm is rebuilt by SQLite). */
+export const isCopyableDatabaseFile = (name) => isDatabaseFile(name) && !/-shm$/i.test(name);

package/dist/guest/agents/agent-installer.js

@@ -11,16 +11,9 @@ import { exists, mkdirp } from '../runtime/fs.js';
 import { log, warn } from '../runtime/log.js';
 import { session } from '../runtime/session.js';
 import { addMachineEnvironment } from '../setup/environment.js';
+import { agentPaths as paths } from './agent-files.js';
 import { linkHarnessProfile } from './profile-links.js';
-function agentPaths(name, harness) {
-    const dir = path.join(toolsDir, 'agents', name);
-    const exe = harness.hostExecutable ?? (harness.uvBin ? harness.uvBin + '.exe' : null);
-    return {
-        dir,
-        exe: exe ? path.join(dir, exe) : null,
-        cmd: harness.npmBin ? path.join(dir, harness.npmBin + '.cmd') : null,
-    };
-}
+const agentPaths = (name, harness) => paths(toolsDir, name, harness);
 /** npm install with the runner's own npm into tools\agents\<name> (no global state outside persistent storage). */
 async function installViaNpm(name, harness, dir, env) {
     if (!harness.npmPackage)

package/dist/guest/agents/local-state.d.ts

@@ -0,0 +1,14 @@
+import { type LocalState } from './agent-files.js';
+/** Every SQLite folder of every configured agent (none in launch folders that predate the agents list). */
+export declare function agentLocalStates(): LocalState[];
+/** Variable -> working folder, for the agent environment (and the machine environment of new terminal tabs). */
+export declare function localStateVars(): Record<string, string>;
+/** Boot: what an agent sealed to the last sandbox (bootReset) is deleted, so it sets it up again. Links are left. */
+export declare function resetMachineBound(): void;
+/** Boot: the saved databases of every configured agent are copied to the sandbox's disk, where the agent runs them. */
+export declare function restoreLocalState(): void;
+/**
+ * Copies the working databases back to persistent storage (staging folder + swap). While the agent runs they are
+ * snapshotted with SQLite's online backup instead (see snapshotWhileRunning); nothing is done when nothing changed.
+ */
+export declare function saveLocalState(): void;

package/dist/guest/agents/local-state.js

@@ -0,0 +1,218 @@
+// Agents that keep SQLite databases (codex ...): SQLite cannot map its shared memory in a mapped folder (error 8714,
+// "disk I/O error"), so they run from a copy on the sandbox's own disk. The copy comes from persistent storage at boot
+// and goes back when no agent process holds the files, so the data lives on between sandboxes.
+import fs from 'node:fs';
+import path from 'node:path';
+import { SYSTEM } from '../../shared/system.js';
+import { dryRun, isWin, localDir } from '../runtime/paths.js';
+import { exists, mkdirp } from '../runtime/fs.js';
+import { execOutput } from '../runtime/process.js';
+import { log, warn } from '../runtime/log.js';
+import { session, stateDir } from '../runtime/session.js';
+import { errMsg } from '../../core/util/errors.js';
+import { bootResetPaths, isCopyableDatabaseFile, isDatabaseFile, localStateEntries, } from './agent-files.js';
+const SQLITE_HEADER = 'SQLite format 3\0';
+/** The sandbox-disk folder that holds the working copies. */
+const localRoot = () => path.join(localDir, 'agent-state');
+/** Every SQLite folder of every configured agent (none in launch folders that predate the agents list). */
+export function agentLocalStates() {
+    return localStateEntries(session.agents ?? {}, stateDir, localRoot());
+}
+/** Variable -> working folder, for the agent environment (and the machine environment of new terminal tabs). */
+export function localStateVars() {
+    return Object.fromEntries(agentLocalStates().map((s) => [s.env, s.local]));
+}
+const databaseFiles = (dir, keep) => exists(dir)
+    ? fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isFile() && keep(e.name) ? [e.name] : []))
+    : [];
+/** A database file that starts like SQLite (an empty or cut-off file must never replace a saved copy). */
+const looksLikeSqlite = (file) => {
+    const fd = fs.openSync(file, 'r');
+    try {
+        const head = Buffer.alloc(16);
+        return fs.readSync(fd, head, 0, 16, 0) === 16 && head.toString('latin1') === SQLITE_HEADER;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+};
+const copyFiles = (from, to, names) => {
+    fs.rmSync(to, { recursive: true, force: true });
+    mkdirp(to);
+    for (const name of names)
+        fs.copyFileSync(path.join(from, name), path.join(to, name));
+};
+/** Replaces the folder `store` with the staged `incoming` folder; the old one is only removed once the new is in. */
+const swapIn = (incoming, store) => {
+    const previous = store + '.previous';
+    fs.rmSync(previous, { recursive: true, force: true });
+    if (exists(store))
+        fs.renameSync(store, previous);
+    try {
+        fs.renameSync(incoming, store);
+    }
+    catch (e) {
+        if (exists(previous))
+            fs.renameSync(previous, store);
+        throw e;
+    }
+    fs.rmSync(previous, { recursive: true, force: true });
+};
+/**
+ * Databases an agent kept in its state folder before (codex: state_5.sqlite ...) move into the saved copy. The
+ * originals
+ * go only after the copy is in place and has the same sizes.
+ */
+function adoptLegacy(s) {
+    if (exists(s.store))
+        return;
+    const names = databaseFiles(s.legacy, isDatabaseFile);
+    if (!names.length)
+        return;
+    const copyable = names.filter(isCopyableDatabaseFile);
+    const incoming = s.store + '.incoming';
+    copyFiles(s.legacy, incoming, copyable);
+    swapIn(incoming, s.store);
+    const same = copyable.every((n) => fs.statSync(path.join(s.store, n)).size === fs.statSync(path.join(s.legacy, n)).size);
+    if (!same) {
+        warn(s.agent + ': the copied databases differ in size from the originals; the originals were kept.');
+        return;
+    }
+    for (const n of names)
+        fs.rmSync(path.join(s.legacy, n), { force: true });
+    log(s.agent + ': moved ' + copyable.length + ' database file(s) to ' + s.store + '.');
+}
+/** Boot: what an agent sealed to the last sandbox (bootReset) is deleted, so it sets it up again. Links are left. */
+export function resetMachineBound() {
+    if (dryRun)
+        return;
+    for (const { agent, path: target } of bootResetPaths(session.agents ?? {}, stateDir)) {
+        try {
+            const stat = fs.lstatSync(target, { throwIfNoEntry: false });
+            if (!stat || stat.isSymbolicLink())
+                continue;
+            fs.rmSync(target, { recursive: true, force: true });
+            log(agent +
+                ': removed ' +
+                path.relative(path.join(stateDir, agent), target) +
+                ' (it only worked in the last sandbox).');
+        }
+        catch (e) {
+            warn(agent + ': could not remove ' + target + ' (' + errMsg(e) + ').');
+        }
+    }
+}
+/** Boot: the saved databases of every configured agent are copied to the sandbox's disk, where the agent runs them. */
+export function restoreLocalState() {
+    if (dryRun)
+        return;
+    for (const s of agentLocalStates()) {
+        try {
+            adoptLegacy(s);
+            mkdirp(s.local);
+            const names = databaseFiles(s.store, isCopyableDatabaseFile);
+            for (const n of names)
+                fs.copyFileSync(path.join(s.store, n), path.join(s.local, n));
+            if (names.length)
+                log(s.agent + ': databases restored to ' + s.local + '.');
+        }
+        catch (e) {
+            warn(s.agent + ': could not restore its databases (' + errMsg(e) + '); it starts with empty ones.');
+        }
+    }
+}
+/** True while one of the programs that open the databases runs. */
+function held(s) {
+    if (!isWin)
+        return false;
+    return s.processes.some((image) => execOutput(SYSTEM.tasklist(), ['/FI', 'IMAGENAME eq ' + image, '/NH', '/FO', 'CSV'])
+        .toLowerCase()
+        .includes(image.toLowerCase()));
+}
+const fingerprint = (dir) => databaseFiles(dir, isCopyableDatabaseFile)
+    .sort()
+    .map((n) => {
+    const st = fs.statSync(path.join(dir, n));
+    return n + ':' + st.size + ':' + st.mtimeMs;
+})
+    .join('|');
+/** The working copies as of the last save by this process. */
+const saved = new Map();
+/** Snapshots in progress (one per working folder) and whether the missing online backup was said already. */
+const snapshotting = new Set();
+let saidNoBackup = false;
+/**
+ * While the agent runs its databases are never copied as files (the -wal and the database would not match): SQLite's
+ * online backup writes a consistent snapshot into the staging folder, which is then swapped in. Needs node:sqlite
+ * (newer Node); without it the save waits until the agent has exited.
+ */
+function snapshotWhileRunning(s, print) {
+    if (snapshotting.has(s.local))
+        return;
+    snapshotting.add(s.local);
+    void (async () => {
+        try {
+            const sqlite = await import('node:sqlite').catch(() => null);
+            if (!sqlite || typeof sqlite.backup !== 'function') {
+                if (!saidNoBackup)
+                    log(s.agent + ': this Node has no SQLite online backup; its databases are saved when it exits.');
+                saidNoBackup = true;
+                return;
+            }
+            const incoming = s.store + '.incoming';
+            fs.rmSync(incoming, { recursive: true, force: true });
+            mkdirp(incoming);
+            for (const name of databaseFiles(s.local, (n) => isCopyableDatabaseFile(n) && !/-wal$/i.test(n))) {
+                const db = new sqlite.DatabaseSync(path.join(s.local, name), { readOnly: true });
+                try {
+                    await sqlite.backup(db, path.join(incoming, name));
+                }
+                finally {
+                    db.close();
+                }
+            }
+            swapIn(incoming, s.store);
+            saved.set(s.local, print);
+        }
+        catch (e) {
+            warn(s.agent + ': could not snapshot its running databases: ' + errMsg(e));
+        }
+        finally {
+            snapshotting.delete(s.local);
+        }
+    })();
+}
+/**
+ * Copies the working databases back to persistent storage (staging folder + swap). While the agent runs they are
+ * snapshotted with SQLite's online backup instead (see snapshotWhileRunning); nothing is done when nothing changed.
+ */
+export function saveLocalState() {
+    if (dryRun)
+        return;
+    for (const s of agentLocalStates()) {
+        try {
+            if (!exists(s.local))
+                continue;
+            const print = fingerprint(s.local);
+            if (!print || (saved.get(s.local) === print && exists(s.store)))
+                continue;
+            if (held(s)) {
+                snapshotWhileRunning(s, print);
+                continue;
+            }
+            const names = databaseFiles(s.local, isCopyableDatabaseFile);
+            const bad = names.filter((n) => !/-wal$/i.test(n) && !looksLikeSqlite(path.join(s.local, n)));
+            if (bad.length) {
+                warn(s.agent + ': ' + bad.join(', ') + ' do not look like SQLite databases, so they were not saved.');
+                continue;
+            }
+            const incoming = s.store + '.incoming';
+            copyFiles(s.local, incoming, names);
+            swapIn(incoming, s.store);
+            saved.set(s.local, print);
+        }
+        catch (e) {
+            warn(s.agent + ': could not save its databases: ' + errMsg(e));
+        }
+    }
+}

package/dist/guest/agents/sbx-agent.d.ts

@@ -0,0 +1,2 @@
+/** Runs one sbx-agent command; returns the exit code. Prints, as the command line tool it is. */
+export declare function runSbxAgent(argv: readonly string[]): Promise<number>;

package/dist/guest/agents/sbx-agent.js

@@ -0,0 +1,35 @@
+// `sbx-agent`: install a configured agent from a terminal inside the sandbox (the agent commands call it the first
+// time). Usage: sbx-agent list | sbx-agent install <agent>
+import { agents } from './agent-installer.js';
+import { agentCommand, agentPaths } from './agent-files.js';
+import { toolsDir } from '../runtime/paths.js';
+import { exists } from '../runtime/fs.js';
+import { session } from '../runtime/session.js';
+/** Runs one sbx-agent command; returns the exit code. Prints, as the command line tool it is. */
+export async function runSbxAgent(argv) {
+    const known = session.agents ?? {};
+    const [verb, name] = argv;
+    if (verb === 'list' || verb === undefined) {
+        for (const [agent, harness] of Object.entries(known)) {
+            const p = agentPaths(toolsDir, agent, harness);
+            const installed = (p.exe !== null && exists(p.exe)) || (p.cmd !== null && exists(p.cmd));
+            console.log(agentCommand(agent, harness).padEnd(14) + (installed ? 'installed' : 'not installed yet'));
+        }
+        return 0;
+    }
+    const harness = verb === 'install' && name ? known[name] : undefined;
+    if (!harness) {
+        console.error(verb === 'install' && name
+            ? 'Unknown agent "' + name + '". Configured agents: ' + Object.keys(known).join(', ')
+            : 'Usage: sbx-agent list | sbx-agent install <agent>');
+        return 1;
+    }
+    try {
+        await agents.provision(name, harness, process.env, false);
+    }
+    catch (e) {
+        console.error('Could not install ' + name + ': ' + (e instanceof Error ? e.message : String(e)));
+        return 1;
+    }
+    return 0;
+}

package/dist/guest/boot/boot.d.ts

@@ -3,11 +3,15 @@ export declare class Boot {
     private ptyHost;
     private lan;
     private readonly gitAccess;
+    /** What the host handed over in its one-shot file (read and deleted at the start of run()). */
+    private secrets;
     run(): Promise<void>;
     private networkAndSessionHost;
     private hooksAndDesktop;
     /** Toolchains, databases, apps, the network proxy and VS Code; then the agent environment, saved machine-wide. */
     private developerTools;
+    /** vpn.enabled: the tunnel and its kill switch, before anything else uses the network (git, the agent). */
+    private vpn;
     private gitIdentity;
     private claude;
     private agent;