windows-development-sandbox 0.0.0-stage → 1.1.0

package/dist/guest/daemon/exec.js

@@ -0,0 +1,32 @@
+// `exec` requests: a command run for the host in the workspace.
+import { spawn } from 'node:child_process';
+import { SYSTEM } from '../../shared/system.js';
+import { errMsg, exists } from '../env.js';
+import { provisionedFor } from './project.js';
+import { insideWorkspace, respond } from './state.js';
+const MAX_OUTPUT = 1024 * 1024;
+const quoteForCmd = (a) => (/[\s"&|<>^]/.test(a) ? '"' + a.replace(/"/g, '""') + '"' : a);
+const cap = (s) => (s.length > MAX_OUTPUT ? s.slice(0, MAX_OUTPUT) + '\n[output truncated]' : s);
+/** Runs a command for the host without blocking the daemon (other requests and pings keep being answered). */
+export const execCommand = (req) => {
+    if (!insideWorkspace(req.cwd) || !exists(req.cwd)) {
+        respond(req.id, { ok: false, message: 'Folder is not inside the sandbox workspace: ' + req.cwd });
+        return;
+    }
+    // chcp 65001 first: console programs then write UTF-8 (not the OEM code page) into the pipes.
+    // In a project registered after boot, its own environment (its Node, Python, database variables).
+    const env = provisionedFor(req.cwd)?.env ?? process.env;
+    const child = spawn(SYSTEM.cmd(), ['/d', '/s', '/c', '"chcp 65001>nul & ' + req.command.map(quoteForCmd).join(' ') + '"'], { cwd: req.cwd, env, windowsHide: true, windowsVerbatimArguments: true });
+    const output = { stdout: '', stderr: '' };
+    // setEncoding decodes across chunks: a multi-byte character split between two reads is not mangled.
+    const collect = (key) => (d) => { if (output[key].length < MAX_OUTPUT)
+        output[key] += d; };
+    child.stdout.setEncoding('utf8').on('data', collect('stdout'));
+    child.stderr.setEncoding('utf8').on('data', collect('stderr'));
+    const timer = setTimeout(() => child.kill(), Math.min(req.timeoutSeconds, 3600) * 1000);
+    child.on('error', (e) => { clearTimeout(timer); respond(req.id, { ok: false, message: 'Could not run the command: ' + errMsg(e) }); });
+    child.on('close', (code) => {
+        clearTimeout(timer);
+        respond(req.id, { ok: code === 0, message: code === null ? 'stopped after ' + req.timeoutSeconds + ' s' : 'exit ' + code, exitCode: code ?? -1, stdout: cap(output.stdout), stderr: cap(output.stderr) });
+    });
+};

package/dist/guest/daemon/project.d.ts

@@ -0,0 +1,14 @@
+import type { ProjectSpecT } from '../../shared/schema.js';
+export interface Provisioned {
+    spec: ProjectSpecT;
+    env: NodeJS.ProcessEnv;
+    summary: string[];
+}
+/** The provisioned project containing this folder, if any (exec in its folders uses its environment). */
+export declare const provisionedFor: (cwd: string) => Provisioned | null;
+export declare const provisionedProjects: () => Provisioned[];
+/**
+ * Provisions a project (or joins the run already doing it: two sessions requested at once wait for the same one).
+ * `say` gets the progress lines.
+ */
+export declare const provisionProject: (spec: ProjectSpecT, say: (message: string) => void) => Promise<Provisioned>;

package/dist/guest/daemon/project.js

@@ -0,0 +1,132 @@
+// Projects registered after boot (sandbox claude from another folder on the PC, which the host links into the hub).
+// Each is provisioned once, on demand, while every other session keeps running: the toolchain steps it needs that are
+// not installed yet (installOnce markers and installed folders make the rest free), its Node/Python versions, its
+// databases and hooks. Its sessions get ITS environment, built from the boot's base environment rather than the boot
+// project's: nothing machine-wide is switched under the sessions already running (no nvm symlink switch, machine
+// variables only added, never replaced). A failure is that project's alone.
+import fs from 'node:fs';
+import path from 'node:path';
+import { isWithin } from '../../shared/projects.js';
+import { insideWorkspace } from './state.js';
+import { baseEnvFor, readBootEnv } from '../boot-env.js';
+import { dryRun, errMsg, exists, localDir, log, mkdirp, session, warn } from '../env.js';
+import { writeGuides } from '../guide.js';
+import { withProject } from '../project-context.js';
+import { saveProjectStatus } from '../project-status.js';
+import { addMachineEnvironment, agentEnv } from '../setup/environment.js';
+import { projectHooks, runHooksAsync } from '../setup/hooks.js';
+import { setupToolchains } from '../toolchains/index.js';
+/** By project name (lower case). The same spec again is free; a changed one (its config was edited) provisions again. */
+const projects = new Map();
+/** The last finished provisioning of each project (kept while a changed spec provisions again). */
+const ready = new Map();
+/** The provisioned project containing this folder, if any (exec in its folders uses its environment). */
+export const provisionedFor = (cwd) => [...ready.values()].filter((p) => isWithin(p.spec.workspace, cwd)).sort((a, b) => b.spec.workspace.length - a.spec.workspace.length)[0] ?? null;
+export const provisionedProjects = () => [...ready.values()];
+/** `set` lines for a .cmd file. Values are quoted; a value with a line break cannot be set this way and is left out. */
+const cmdSet = (env, names) => names.filter((n) => env[n] !== undefined && !/[\r\n]/.test(String(env[n]))).map((n) => '@set "' + n + '=' + String(env[n]).replace(/%/g, '%%') + '"');
+/**
+ * A terminal for the project inside the sandbox: `sbx-shell <name>` (from any terminal tab) opens cmd in its folder with
+ * its environment. Written to the sandbox's own disk.
+ */
+const writeShell = (spec, env, names) => {
+    const dir = mkdirp(path.join(localDir, 'projects', spec.name));
+    fs.writeFileSync(path.join(dir, 'env.cmd'), [...cmdSet(env, [...names, 'PATH']), ''].join('\r\n'));
+    fs.writeFileSync(path.join(dir, 'shell.cmd'), ['@call "' + path.join(dir, 'env.cmd') + '"', '@cd /d "' + spec.workspace + '"', '@title ' + spec.name, ''].join('\r\n'));
+    const bin = mkdirp(path.join(localDir, 'bin'));
+    fs.writeFileSync(path.join(bin, 'sbx-shell.cmd'), [
+        '@if "%~1"=="" (echo Usage: sbx-shell ^<project^>   ^(a terminal in that project with its tools^) & dir /b "' + path.join(localDir, 'projects') + '" & exit /b 2)',
+        '@if not exist "' + path.join(localDir, 'projects') + '\\%~1\\shell.cmd" (echo No project %~1 in this sandbox. & exit /b 2)',
+        '@cmd /k ""' + path.join(localDir, 'projects') + '\\%~1\\shell.cmd""',
+        '',
+    ].join('\r\n'));
+};
+/** The guide every agent reads lists every project in the sandbox (they can all see each other's folders). */
+const refreshGuide = async () => {
+    // The self-test must never rewrite this machine's real managed CLAUDE.md.
+    if (dryRun || (process.env.AGENT_SANDBOX_SELFTEST === '1' && !process.env.AGENT_MANAGED_DIR))
+        return;
+    const boot = readBootEnv();
+    if (!boot)
+        return;
+    const list = provisionedProjects().map((p) => ({ guest: p.spec.workspace, host: p.spec.workspaceHost }));
+    try {
+        writeGuides(boot.summary, boot.lan, list);
+    }
+    catch (e) {
+        warn('Could not update the sandbox guide: ' + errMsg(e));
+    }
+};
+const provision = async (spec, say) => {
+    if (!insideWorkspace(spec.workspace) || !exists(spec.workspace)) {
+        throw new Error('Project folder ' + spec.workspace + ' (' + spec.workspaceHost + ') is not visible inside the sandbox. Stop the sandbox (sandbox stop) and start it from that folder, or add its parent folder to projects.roots.');
+    }
+    saveProjectStatus(spec.name, spec.workspace, 'provisioning', 'Setting up ' + spec.name, spec.databases, []);
+    log('Project ' + spec.name + ': setting up ' + spec.workspace + ' (' + spec.workspaceHost + ')');
+    const boot = readBootEnv();
+    const base = baseEnvFor(boot);
+    const hooks = projectHooks(spec.name, spec.workspace);
+    if (spec.hooks) {
+        say('Pre-provision hooks');
+        await runHooksAsync('pre-provision', base, hooks);
+    }
+    const tools = await withProject({ workspace: spec.workspace, duringSession: true }, () => setupToolchains(spec.toolchains, spec.versions, {
+        gitEnabled: session.provisioning.git.enabled,
+        // Git access is machine-wide: the host refuses a project that needs a stricter one, so the sandbox's applies.
+        gitAccess: session.provisioning.git.access ?? 'full',
+        hostGit: session.hostTools.git,
+        refresh: false,
+        databases: spec.databases,
+    }, { report: (m) => { saveProjectStatus(spec.name, spec.workspace, 'provisioning', m, spec.databases, []); say(m); }, reuse: boot?.steps }));
+    tools.prepend.push(path.join(localDir, 'bin'));
+    const env = agentEnv(tools, { workspace: spec.workspace, project: spec.name, base });
+    const specFile = path.join(mkdirp(path.join(localDir, 'projects', spec.name)), 'project.json');
+    fs.writeFileSync(specFile, JSON.stringify(spec));
+    env.AGENT_PROJECT_FILE = specFile;
+    // New terminal tabs see the new tools too, after everything the boot project has (never in place of it).
+    addMachineEnvironment(tools.vars, [...tools.prepend, ...tools.append], true);
+    try {
+        writeShell(spec, env, [...Object.keys(tools.vars), 'AGENT_WORKSPACE', 'AGENT_PROJECT', 'AGENT_SANDBOX_WORKSPACE', 'AGENT_PROJECT_FILE']);
+    }
+    catch (e) {
+        warn('sbx-shell for ' + spec.name + ': ' + errMsg(e));
+    }
+    if (spec.hooks) {
+        say('Pre-agent hooks');
+        await runHooksAsync('pre-agent', env, hooks);
+    }
+    for (const line of tools.summary)
+        log('  [' + spec.name + '] ' + line);
+    saveProjectStatus(spec.name, spec.workspace, 'ready', 'Ready', spec.databases, tools.summary);
+    return { spec, env, summary: tools.summary };
+};
+/**
+ * Provisions a project (or joins the run already doing it: two sessions requested at once wait for the same one).
+ * `say` gets the progress lines.
+ */
+export const provisionProject = (spec, say) => {
+    const id = spec.name.toLowerCase();
+    const key = JSON.stringify(spec);
+    const known = projects.get(id);
+    if (known && known.key === key) {
+        known.listeners.add(say);
+        return known.work.finally(() => known.listeners.delete(say));
+    }
+    const listeners = new Set([say]);
+    const broadcast = (message) => { for (const l of listeners)
+        try {
+            l(message);
+        }
+        catch { /* a listener's write failing never stops provisioning */ } };
+    const work = provision(spec, broadcast);
+    const entry = { key, work, listeners };
+    projects.set(id, entry);
+    work.then((done) => { entry.done = done; ready.set(id, done); return refreshGuide(); }, (e) => {
+        warn('Project ' + spec.name + ' could not be set up: ' + errMsg(e));
+        saveProjectStatus(spec.name, spec.workspace, 'failed', errMsg(e), spec.databases, []);
+        // The next session for it tries again.
+        if (projects.get(id) === entry)
+            projects.delete(id);
+    });
+    return work;
+};

package/dist/guest/daemon/session.d.ts

@@ -0,0 +1,13 @@
+import type { GuestRequest } from '../../core/types.js';
+type SessionRequest = Extract<GuestRequest, {
+    kind: 'session';
+}>;
+export declare const startSession: (req: SessionRequest) => Promise<void>;
+/** `project` requests: provision a registered project without an agent (sandbox start / exec / db from its folder). */
+export declare const prepareProject: (req: Extract<GuestRequest, {
+    kind: "project";
+}>) => Promise<void>;
+export declare const restartSessions: (req: Extract<GuestRequest, {
+    kind: "restart";
+}>) => Promise<void>;
+export {};

package/dist/guest/daemon/session.js

@@ -0,0 +1,139 @@
+// `session` and `restart` requests: agent sessions, each in its own ptyhost process. A session runs in the launch
+// folder's project (the boot environment) or in a project registered later, which is provisioned first (daemon/project).
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { FrameType, sendControl } from '../../shared/pty-client.js';
+import { isWithin } from '../../shared/projects.js';
+import { now } from '../../shared/rundir.js';
+import { SYSTEM } from '../../shared/system.js';
+import { commandLine } from '../cmdline.js';
+import { freePort } from '../ports.js';
+import { primaryProject } from '../project-status.js';
+import { ensurePtyHost, ptyHostLogTail, startPtyHost, waitForPtyHost } from '../ptyhost.js';
+import { provisionHarness, resolveLaunch } from '../setup/agents.js';
+import { saveClaudeMem } from '../setup/claude.js';
+import { projectHooks, runHooks, runHooksAsync } from '../setup/hooks.js';
+import { guestAddresses } from '../setup/network.js';
+import { dataDir, errMsg, exists, log, session, toolsDir, warn, workspace } from '../env.js';
+import { provisionProject } from './project.js';
+import { maybeShutdown } from './shutdown.js';
+import { insidePrimary, live, pending, respond, safely, saveStatus } from './state.js';
+const terminalTab = (id, title, cwd) => {
+    const view = [process.execPath, path.join(path.dirname(process.argv[1]), 'view.js'), id];
+    const wt = path.join(toolsDir, 'terminal', 'wt.exe');
+    if (exists(wt))
+        spawn(wt, ['-w', '0', 'nt', '--title', title, '-d', cwd, ...view], { detached: true, stdio: 'ignore' }).unref();
+    else
+        spawn(SYSTEM.cmd(), ['/d', '/c', 'start', title, ...view], { detached: true, stdio: 'ignore', cwd }).unref();
+};
+const onExit = (running, place) => (code) => {
+    live.delete(running.id);
+    const tail = code === 0 ? '' : ptyHostLogTail(running.id, 6);
+    saveStatus({ ...running, phase: 'exited', message: running.harness + ' exited with code ' + code + (tail ? '. Last output:\n' + tail : ''), exitCode: code ?? 1, attach: undefined });
+    log('Session ' + running.id + ' ended (exit ' + code + ')');
+    if (place.hooks)
+        void runHooksAsync('post-agent', place.env, place.hooks).catch((e) => warn('post-agent hooks failed: ' + errMsg(e)));
+    else
+        safely('post-agent hooks', () => runHooks('post-agent', process.env));
+    safely('claude-mem save', saveClaudeMem);
+    maybeShutdown();
+};
+/**
+ * The agent's definition: the one the sandbox booted with, the one the host sent along (another agent, e.g.
+ * sandbox codex in a sandbox started for claude), or one the project's config names.
+ */
+const harnessFor = (req) => {
+    if (req.harness === session.harnessName && session.harness)
+        return session.harness;
+    const sent = req.harnessSpec ?? req.project?.harnesses[req.harness];
+    if (sent)
+        return sent;
+    throw new Error('Agent "' + req.harness + '" is not configured for this sandbox (it runs ' + session.harnessName + ').');
+};
+/** Starts ptyhost for the agent and waits until it listens; a failure carries the tail of ptyhost's own log. */
+const launchPtyHost = async (req, remote, env, say) => {
+    const harness = harnessFor(req);
+    // Never refresh here: main already did, and replacing a running agent's executable would fail.
+    say('Preparing ' + req.harness);
+    await provisionHarness(req.harness, harness, env, false);
+    const launch = resolveLaunch(req.harness, harness);
+    const base = [...launch.args, ...harness.arguments];
+    const port = await freePort();
+    const token = crypto.randomBytes(24).toString('base64url');
+    const child = startPtyHost({
+        exe: ensurePtyHost(), port, token, cols: 120, rows: 32, id: req.id, cwd: req.cwd, env: { ...env, ...harness.environment }, remote,
+        command: commandLine(launch.file, [...base, ...req.args]), restartCommand: commandLine(launch.file, [...base, ...(harness.resumeArguments ?? [])]),
+    });
+    try {
+        await waitForPtyHost(child, port, 15000);
+    }
+    catch (e) {
+        const tail = ptyHostLogTail(req.id);
+        throw new Error(errMsg(e) + (tail ? '. From its log:\n' + tail : '') + '\nLog: ' + path.join(dataDir, 'logs', 'ptyhost-' + req.id + '.log'));
+    }
+    return { child, port, token };
+};
+/** The launch folder's project, or the registered project this session is for (provisioned first if needed). */
+const placeFor = async (req, say) => {
+    if (!req.project) {
+        if (!insidePrimary(req.cwd) || !exists(req.cwd))
+            throw new Error('Folder is not inside the sandbox workspace ' + workspace + ': ' + req.cwd);
+        return { env: process.env, hooks: null, project: primaryProject() };
+    }
+    if (!isWithin(req.project.workspace, req.cwd))
+        throw new Error('Folder ' + req.cwd + ' is not inside project ' + req.project.name + ' (' + req.project.workspace + ').');
+    const ready = await provisionProject(req.project, say);
+    if (!exists(req.cwd))
+        throw new Error('Folder does not exist in the sandbox: ' + req.cwd);
+    return { env: ready.env, hooks: req.project.hooks ? projectHooks(req.project.name, req.project.workspace) : null, project: req.project.name };
+};
+export const startSession = async (req) => {
+    let status = { id: req.id, launchId: session.launchId, harness: req.harness, cwd: req.cwd, ...(req.project ? { project: req.project.name } : {}), phase: 'starting', message: 'Starting ' + req.harness, updatedAt: now(), startedAt: now() };
+    saveStatus(status);
+    // Progress goes into the session's status: the host prints it while it waits, and the tab inside shows it.
+    const say = (message) => { status = { ...status, message }; saveStatus(status); };
+    pending.starting++;
+    // Sessions after the first get their own tab right away (it shows the setup progress until the agent starts).
+    if (req.id !== session.launchId && process.env.AGENT_NO_TABS !== '1')
+        safely('terminal tab', () => terminalTab(req.id, req.harness + ' ' + path.basename(req.cwd), req.cwd));
+    try {
+        const place = await placeFor(req, say);
+        const remote = session.networking && session.attach.enabled;
+        const { child, port, token } = await launchPtyHost(req, remote, place.env, say);
+        const running = { ...status, project: place.project, phase: 'running', message: req.harness + ' is running', attach: { addresses: remote ? guestAddresses() : [], port, token } };
+        live.set(req.id, { status: running, child });
+        child.once('exit', onExit(running, place));
+        saveStatus(running);
+        log('Session ' + req.id + ' started (' + req.harness + ' in ' + req.cwd + ', project ' + place.project + ', port ' + port + ')');
+    }
+    catch (e) {
+        saveStatus({ ...status, phase: 'failed', message: errMsg(e) });
+        warn('Session ' + req.id + ' failed: ' + errMsg(e));
+        maybeShutdown();
+    }
+    finally {
+        pending.starting--;
+    }
+};
+/** `project` requests: provision a registered project without an agent (sandbox start / exec / db from its folder). */
+export const prepareProject = async (req) => {
+    pending.starting++;
+    try {
+        const ready = await provisionProject(req.project, () => undefined);
+        respond(req.id, { ok: true, message: 'Project ' + req.project.name + ' is ready in ' + req.project.workspace + '\n' + ready.summary.join('\n') });
+    }
+    catch (e) {
+        respond(req.id, { ok: false, message: 'Project ' + req.project.name + ' could not be set up: ' + errMsg(e) });
+    }
+    finally {
+        pending.starting--;
+        maybeShutdown();
+    }
+};
+export const restartSessions = async (req) => {
+    const targets = [...live.values()].filter((s) => s.status.attach && (req.harness === null || s.status.harness === req.harness) && (!req.cwd || isWithin(req.cwd, s.status.cwd)));
+    for (const s of targets)
+        await sendControl({ addresses: ['127.0.0.1'], port: s.status.attach.port, token: s.status.attach.token }, FrameType.Restart);
+    respond(req.id, { ok: true, message: 'restarted ' + targets.length + ' session(s)' });
+};

package/dist/guest/daemon/shutdown.d.ts

@@ -0,0 +1 @@
+export declare const maybeShutdown: () => void;

package/dist/guest/daemon/shutdown.js

@@ -0,0 +1,21 @@
+// A headless sandbox with nothing running (or starting) only wastes RAM, so it shuts itself down.
+import { spawnSync } from 'node:child_process';
+import { SYSTEM } from '../../shared/system.js';
+import { scanRequests } from '../../shared/rundir.js';
+import { saveClaudeMem } from '../setup/claude.js';
+import { dataDir, isWin, log, session } from '../env.js';
+import { live, pending, safely } from './state.js';
+export const maybeShutdown = () => {
+    if (!session.headless || !isWin)
+        return;
+    const idle = () => live.size === 0 && pending.starting === 0 && scanRequests(dataDir).valid.length === 0;
+    if (!idle())
+        return;
+    setTimeout(() => {
+        if (!idle())
+            return;
+        log('Headless sandbox has no sessions left; shutting down.');
+        safely('claude-mem save', saveClaudeMem);
+        spawnSync(SYSTEM.shutdown(), ['/s', '/t', '5'], { windowsHide: true });
+    }, 15000);
+};

package/dist/guest/daemon/state.d.ts

@@ -0,0 +1,17 @@
+import type { ChildProcess } from 'node:child_process';
+import type { GuestResponse, SessionStatus } from '../../core/types.js';
+export declare const live: Map<string, {
+    status: SessionStatus;
+    child: ChildProcess;
+}>;
+/** Sessions being started right now (a headless sandbox must not shut down under them). */
+export declare const pending: {
+    starting: number;
+};
+/** Inside the launch folder's workspace. */
+export declare const insidePrimary: (cwd: string) => boolean;
+/** Inside any project of this sandbox: the launch folder, a project root, or C:\Projects\<name> (older launch folders: only the first). */
+export declare const insideWorkspace: (cwd: string) => boolean;
+export declare const respond: (id: string, result: Omit<GuestResponse, "id" | "finishedAt">) => void;
+export declare const saveStatus: (status: SessionStatus) => void;
+export declare const safely: (what: string, work: () => void) => void;

package/dist/guest/daemon/state.js

@@ -0,0 +1,31 @@
+// What the daemon's request handlers share: the running sessions and best-effort status/response writes.
+import path from 'node:path';
+import { now, writeJsonAtomic } from '../../shared/rundir.js';
+import { insideProjects } from '../../shared/projects.js';
+import { errMsg, run, session, warn, workspace } from '../env.js';
+const MAX_MESSAGE = 3500;
+export const live = new Map();
+/** Sessions being started right now (a headless sandbox must not shut down under them). */
+export const pending = { starting: 0 };
+/** Inside the launch folder's workspace. */
+export const insidePrimary = (cwd) => {
+    const rel = path.relative(workspace.toLowerCase(), path.resolve(cwd).toLowerCase());
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+};
+/** Inside any project of this sandbox: the launch folder, a project root, or C:\Projects\<name> (older launch folders: only the first). */
+export const insideWorkspace = (cwd) => insidePrimary(cwd) || (session.projectsDir !== undefined && insideProjects(path.resolve(cwd), session.roots ?? [], session.projectsDir));
+/** Status/response writes are best-effort: a briefly locked file (antivirus, the host's sync) must not kill the daemon. */
+const tryWrite = (file, value) => { try {
+    writeJsonAtomic(file, value);
+}
+catch (e) {
+    warn('Could not write ' + file + ': ' + errMsg(e));
+} };
+export const respond = (id, result) => tryWrite(run.response(id), { id, ...result, message: result.message.slice(0, MAX_MESSAGE), finishedAt: now() });
+export const saveStatus = (status) => tryWrite(run.session(status.id), { ...status, message: status.message.slice(0, MAX_MESSAGE), updatedAt: now() });
+export const safely = (what, work) => { try {
+    work();
+}
+catch (e) {
+    warn(what + ' failed: ' + errMsg(e));
+} };

package/dist/guest/daemon.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/guest/daemon.js

@@ -0,0 +1,53 @@
+// Session daemon (runs detached inside the sandbox for its whole life). It is the only thing that acts on host
+// requests, and it only knows four request kinds: start a session, run a command, restart sessions, ping.
+// It must never die quietly: every iteration is guarded, and anything unexpected is written to its log.
+// The handlers live in daemon/ (session, exec); this file is the polling loop.
+import fs from 'node:fs';
+import { readSession, scanRequests } from '../shared/rundir.js';
+import { saveClaudeMem } from './setup/claude.js';
+import { execCommand } from './daemon/exec.js';
+import { prepareProject, restartSessions, startSession } from './daemon/session.js';
+import { live, respond, safely } from './daemon/state.js';
+import { dataDir, errMsg, log, run, warn } from './env.js';
+let lastMemSave = Date.now();
+process.on('uncaughtException', (e) => warn('daemon: unexpected error (continuing): ' + (e.stack ?? errMsg(e))));
+process.on('unhandledRejection', (e) => warn('daemon: unexpected error (continuing): ' + errMsg(e)));
+const handle = (req) => {
+    switch (req.kind) {
+        case 'session': return startSession(req);
+        case 'project': return prepareProject(req);
+        case 'exec': return execCommand(req);
+        case 'restart': return restartSessions(req);
+        case 'ping': return respond(req.id, { ok: true, message: 'pong (' + live.size + ' session(s) running)' });
+    }
+};
+const tick = () => {
+    const { valid, invalid } = scanRequests(dataDir);
+    // Anything in requests/ that is not a valid request (wrong kind, bad id, junk) is deleted unread.
+    for (const file of invalid)
+        safely('removing an invalid request', () => fs.rmSync(file, { recursive: true, force: true }));
+    for (const req of valid) {
+        safely('claiming a request', () => fs.rmSync(run.request(req.id), { force: true }));
+        if (readSession(dataDir, req.id))
+            continue;
+        // Not awaited: starting a session or running a command must not hold up other requests.
+        void Promise.resolve(handle(req)).catch((e) => respond(req.id, { ok: false, message: errMsg(e) }));
+    }
+    if (Date.now() - lastMemSave > 120000) {
+        lastMemSave = Date.now();
+        safely('claude-mem save', saveClaudeMem);
+    }
+};
+const loop = () => {
+    try {
+        tick();
+    }
+    catch (e) {
+        warn('daemon loop: ' + errMsg(e));
+    }
+    finally {
+        setTimeout(loop, 400);
+    }
+};
+log('Session daemon started (pid ' + process.pid + ').');
+loop();

package/dist/guest/db.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/guest/db.js

@@ -0,0 +1,75 @@
+// `sbx-db`: list, start and stop the sandbox's databases from a terminal inside it (`sandbox db` on the PC runs it too).
+// Usage: sbx-db [list] | sbx-db start <name> | sbx-db stop <name>
+import fs from 'node:fs';
+import { ProjectSpec } from '../shared/schema.js';
+import { portOpen } from './ports.js';
+import { DATABASE_NAMES, setupDatabase, stopDatabase } from './toolchains/databases/index.js';
+import { emptyEnv } from './toolchains/common.js';
+import { addMachineEnvironment } from './setup/environment.js';
+import { errMsg, session } from './env.js';
+const USAGE = 'Usage: sbx-db [list] | sbx-db start <name> | sbx-db stop <name>';
+/** In a project registered after boot (its terminals and exec have AGENT_PROJECT_FILE): that project's database plan. */
+const projectPlans = () => {
+    const file = process.env.AGENT_PROJECT_FILE;
+    if (!file)
+        return null;
+    try {
+        return ProjectSpec.safeParse(JSON.parse(fs.readFileSync(file, 'utf8'))).data?.databases ?? null;
+    }
+    catch {
+        return null;
+    }
+};
+/** The project's own plans first (their versions and ports were chosen for it), then everything else. */
+const plans = () => {
+    const boot = projectPlans() ?? session.databases ?? [];
+    return [...boot, ...(session.databaseCatalog ?? []).filter((c) => !boot.some((b) => b.database === c.database))];
+};
+const find = (name) => {
+    const all = plans();
+    const plan = all.find((p) => p.database === name?.toLowerCase());
+    if (!plan)
+        throw new Error((name ? 'Unknown database "' + name + '". ' : '') + 'Choose one of: ' + all.map((p) => p.database).join(', '));
+    if (plan.database === 'sqlserver')
+        throw new Error('SQL Server cannot run inside Windows Sandbox.');
+    return plan;
+};
+const list = async () => {
+    for (const p of plans().filter((x) => x.database !== 'sqlserver')) {
+        const state = (await portOpen(p.port)) ? 'running' : 'stopped';
+        console.log(p.database.padEnd(10) + state.padEnd(9) + 'port ' + p.port + '  ' + DATABASE_NAMES[p.database]);
+    }
+    return 0;
+};
+const start = async (name) => {
+    const plan = find(name);
+    if (await portOpen(plan.port)) {
+        console.log(plan.database + ' is already running on port ' + plan.port + '.');
+        return 0;
+    }
+    console.log('Starting ' + DATABASE_NAMES[plan.database] + ' (the first time downloads it) ...');
+    const env = emptyEnv();
+    await setupDatabase(env, plan);
+    addMachineEnvironment(env.vars, env.prepend);
+    for (const line of env.summary)
+        console.log('  ' + line);
+    console.log('New terminal tabs have its variables and tools; this one does not.');
+    return 0;
+};
+const stop = async (name) => {
+    const plan = find(name);
+    console.log((await stopDatabase(plan)) ? 'Stopped ' + plan.database + '.' : plan.database + ' was not running.');
+    return 0;
+};
+const main = (args) => {
+    const [action = 'list', name] = args;
+    if (action === 'list')
+        return list();
+    if (action === 'start')
+        return start(name);
+    if (action === 'stop')
+        return stop(name);
+    console.error(USAGE);
+    return Promise.resolve(2);
+};
+main(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (e) => { console.error(errMsg(e)); process.exitCode = 1; });

package/dist/guest/env.d.ts

@@ -0,0 +1,51 @@
+import { type SpawnOptions, type SpawnSyncOptions } from 'node:child_process';
+import type { GuestSession, SandboxStatus } from '../core/types.js';
+export declare const isWin: boolean;
+export declare const dryRun: boolean;
+/** Real provisioning, but nothing machine-wide (environment variables): for end-to-end tests outside a sandbox. */
+export declare const testMode: boolean;
+export declare const launchDir: string;
+export declare const dataDir: string;
+export declare const hostToolsDir: string;
+/** Folders that must stay on the sandbox's own disk (symlinks, SQLite) rather than in a mapped folder. */
+export declare const localDir: string;
+export declare const toolsDir: string;
+export declare const logsDir: string;
+export declare const run: {
+    run: string;
+    sandbox: string;
+    requests: string;
+    responses: string;
+    sessions: string;
+    projects: string;
+    request: (id: string) => string;
+    response: (id: string) => string;
+    session: (id: string) => string;
+    project: (id: string) => string;
+};
+export declare const session: GuestSession;
+export declare const workspace: string;
+export declare const stateDir: string;
+export declare const claudeDir: string;
+export declare const log: (message: string) => void;
+export declare const warn: (message: string) => void;
+export declare const errMsg: (e: unknown) => string;
+export declare const exists: (p: string) => boolean;
+export declare const mkdirp: (p: string) => string;
+export declare const logPath: string;
+/** Best-effort: progress reporting must never be what breaks the boot. */
+export declare const setSandboxStatus: (phase: SandboxStatus["phase"], message: string) => void;
+/** Runs a program, streaming output, and throws with a readable message when it fails. */
+export declare const exec: (file: string, args: string[], options?: SpawnSyncOptions) => void;
+/** exec without blocking: other toolchains keep downloading while this one runs an installer. */
+export declare const execAsync: (file: string, args: string[], options?: SpawnOptions) => Promise<void>;
+export declare const execOutput: (file: string, args: string[], options?: SpawnSyncOptions) => string;
+export declare const powershell: (script: string) => void;
+/** Copies a folder with robocopy (fast, restartable), or just the named files in it; exit codes below 8 mean success. */
+export declare const robocopy: (from: string, to: string, files?: string[]) => void;
+/**
+ * A Node install without its global packages (nvm keeps those per version: often tens of thousands of small files,
+ * which is what made copying from this PC slow). Same file list as Copy-NodeFromHost in sandbox/bootstrap.ps1.
+ * Copied into a staging folder and renamed into place: node.exe alone (an interrupted copy) must not look like a full install.
+ */
+export declare const copyNode: (from: string, to: string) => void;