windows-development-sandbox 1.4.1 → 1.5.0

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

@@ -0,0 +1,18 @@
+/** One boot of the sandbox, step by step: each step is a method, in the order they run. */
+export declare class Boot {
+    private ptyHost;
+    private lan;
+    private readonly gitAccess;
+    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;
+    private gitIdentity;
+    private claude;
+    private agent;
+    private preAgentHooks;
+    /** Ready: starts the session daemon and, with an agent, its first session, shown in this window. */
+    private start;
+}
+export declare function runBoot(): Promise<void>;

package/dist/guest/boot/boot.js

@@ -0,0 +1,242 @@
+// The boot inside the sandbox: network, hooks, developer tools, Git, Claude, the agent, then its first session.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { writeGuides } from './guide.js';
+import { setupToolchains } from '../toolchains/index.js';
+import { agents } from '../agents/agent-installer.js';
+import { linkProfileDirs } from '../agents/profile-links.js';
+import { restoreClaudeMem } from '../setup/claude-mem.js';
+import { syncClaudeProfile } from '../setup/claude-profile.js';
+import { agentEnv, persistEnvironment } from '../setup/environment.js';
+import { runHooks } from '../setup/hooks.js';
+import { applyAllowOnly, proxyEnv } from '../network/allow-only.js';
+import { applyNetworkPolicy } from '../network/firewall.js';
+import { writeManagedSettings } from '../setup/managed-policy.js';
+import { applyPersonalization } from '../setup/desktop.js';
+import { setupGitConfig } from '../setup/git-identity.js';
+import { ensurePtyHost } from '../sessions/pty-host.js';
+import { pruneToolLeftovers } from '../toolchains/leftovers.js';
+import { wanted } from '../toolchains/detect.js';
+import { configureVscode } from '../toolchains/tools/vscode.js';
+import { enableProcessAudit } from '../audit/process-audit.js';
+import { now } from '../../shared/channel/run-dir.js';
+import { writeJsonAtomic } from '../../shared/io/json.js';
+import { viewSession } from '../sessions/viewer.js';
+import { saveBootEnv } from './boot-env.js';
+import { primaryProject, saveProjectStatus } from './project-status.js';
+import { dryRun, isWin, localDir, logsDir, run, toolsDir } from '../runtime/paths.js';
+import { log, logPath, warn } from '../runtime/log.js';
+import { mkdirp } from '../runtime/fs.js';
+import { session, workspace } from '../runtime/session.js';
+import { setSandboxStatus } from '../runtime/status.js';
+import { errMsg } from '../../core/util/errors.js';
+const STEPS = 8;
+const PRIMARY_POLLS = 600;
+const POLL_MS = 500;
+const VSCODE_LANGUAGES = ['python', 'java', 'go', 'rust', 'cpp', 'msvc', 'dotnet', 'ruby', 'php', 'deno', 'pwsh'];
+/** Step n of STEPS: a line in the window and the host's progress (the short title, with what is set up in it). */
+function step(n, title) {
+    log('\n\x1b[36m[' + n + '/' + STEPS + '] ' + title + '\x1b[0m');
+    setSandboxStatus(n === 1 ? 'booting' : 'provisioning', '[' + n + '/' + STEPS + '] ' + title, {
+        step: n,
+        steps: STEPS,
+        title: title.replace(/ \(.*\)$/, ''),
+        active: [],
+        done: 0,
+        total: 0,
+    });
+}
+/** Runs work that may fail without stopping the boot (a warning says what failed). */
+async function soft(what, work) {
+    try {
+        await work();
+    }
+    catch (e) {
+        warn(what + ' failed (continuing): ' + errMsg(e));
+    }
+}
+function startDaemon(env) {
+    spawn(process.execPath, [path.join(path.dirname(process.argv[1]), 'daemon.js')], {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+        env: { ...env, AGENT_LOG_PREFIX: 'daemon' },
+    }).unref();
+}
+/**
+ * `sbx-db` for terminals and `sandbox db`: this boot's Node running runtime\db.js (on the sandbox's disk, rewritten
+ * each boot).
+ */
+function writeDbCommand() {
+    const dir = mkdirp(path.join(localDir, 'bin'));
+    const db = path.join(path.dirname(process.argv[1]), 'db.js');
+    fs.writeFileSync(path.join(dir, 'sbx-db.cmd'), '@setlocal\r\n@set AGENT_LOG_PREFIX=db\r\n@"' + process.execPath + '" "' + db + '" %*\r\n');
+    return dir;
+}
+async function waitForPrimary() {
+    for (let i = 0; i < PRIMARY_POLLS; i++) {
+        const s = run.readSession(session.launchId);
+        if (s?.phase === 'running')
+            return true;
+        if (s?.phase === 'failed' || s?.phase === 'exited') {
+            warn(s.message);
+            return false;
+        }
+        await new Promise((r) => setTimeout(r, POLL_MS));
+    }
+    return false;
+}
+/** The languages VS Code gets extensions for: every language toolchain this project uses. */
+function vscodeLanguages() {
+    const toolchains = session.toolchains;
+    return VSCODE_LANGUAGES.filter((t) => wanted(toolchains[t]?.enabled ?? false, t));
+}
+/** One boot of the sandbox, step by step: each step is a method, in the order they run. */
+export class Boot {
+    ptyHost = null;
+    lan = session.networking ? 'open' : 'offline';
+    gitAccess = session.provisioning.git.access ?? 'full';
+    async run() {
+        log('Agent sandbox: ' +
+            session.project +
+            ' | workspace ' +
+            workspace +
+            ' | agent ' +
+            session.harnessName +
+            ' | log ' +
+            logPath);
+        if (!fs.statSync(workspace, { throwIfNoEntry: false })?.isDirectory())
+            throw new Error('Workspace folder is missing in the sandbox: ' + workspace);
+        mkdirp(toolsDir);
+        mkdirp(run.root);
+        await this.networkAndSessionHost();
+        await this.hooksAndDesktop();
+        const { tools, env } = await this.developerTools();
+        await this.gitIdentity(env);
+        await this.claude(tools);
+        await this.agent(env);
+        this.preAgentHooks(env);
+        await this.start(env);
+    }
+    async networkAndSessionHost() {
+        step(1, 'Network and session host');
+        if (isWin && !dryRun && session.attach.enabled)
+            await soft('Building the session host', () => {
+                this.ptyHost = ensurePtyHost();
+            });
+        await soft('Private-network blocking', async () => {
+            this.lan = await applyNetworkPolicy(this.ptyHost);
+        });
+        await soft('Audit', enableProcessAudit);
+    }
+    async hooksAndDesktop() {
+        step(2, 'Pre-provision hooks and desktop');
+        runHooks('pre-provision', process.env);
+        await soft('Personalisation', applyPersonalization);
+    }
+    /** Toolchains, databases, apps, the network proxy and VS Code; then the agent environment, saved machine-wide. */
+    async developerTools() {
+        step(3, 'Developer tools (the first start downloads them once; later starts are quick)');
+        const basePath = process.env.PATH ?? '';
+        const tools = await setupToolchains(session.toolchains, session.versions, {
+            gitEnabled: session.provisioning.git.enabled,
+            gitAccess: this.gitAccess,
+            hostGit: session.hostTools.git,
+            refresh: session.provisioning.refresh,
+            databases: session.databases ?? [],
+            apps: session.apps,
+        });
+        if (!dryRun)
+            tools.prepend.push(writeDbCommand());
+        // network.allowOnly / network.proxy: everything started from now on uses the proxy.
+        Object.assign(tools.vars, proxyEnv());
+        await soft('Network: allow only some hosts', async () => {
+            if (await applyAllowOnly())
+                tools.summary.push('network: only network.allowOnly hosts (refused: logs\\netproxy.log)');
+        });
+        const vscode = session.toolchains.vscode;
+        if (vscode.enabled && vscode.setup !== false)
+            await soft('VS Code setup', () => configureVscode(tools, {
+                toolchains: ['node', ...vscodeLanguages()],
+                databases: (session.databases ?? []).map((d) => d.database),
+                config: vscode,
+                workspace,
+            }));
+        const env = agentEnv(tools);
+        persistEnvironment(env, Object.keys(tools.vars));
+        saveBootEnv({
+            basePath,
+            toolVars: Object.keys(tools.vars),
+            steps: tools.steps,
+            summary: tools.summary,
+            lan: this.lan,
+        });
+        saveProjectStatus(primaryProject(), workspace, 'ready', 'Ready', session.databases ?? [], tools.summary);
+        for (const line of tools.summary)
+            log('  ' + line);
+        await soft('Cleaning old tool builds', () => pruneToolLeftovers());
+        return { tools, env };
+    }
+    async gitIdentity(env) {
+        step(4, 'Git identity');
+        await soft('Git config', () => setupGitConfig(env));
+    }
+    async claude(tools) {
+        step(5, 'Claude settings, history and claude-mem');
+        if (session.harnessName === 'claude')
+            await soft('Claude settings', syncClaudeProfile);
+        await soft('claude-mem restore', restoreClaudeMem);
+        await soft('Sandbox guide for the agent', () => writeGuides(tools.summary, this.lan));
+        await soft('Claude managed settings', () => writeManagedSettings(this.gitAccess));
+    }
+    async agent(env) {
+        step(6, 'Agent: ' + session.harnessName);
+        linkProfileDirs(session.agentProfileDirs ?? {});
+        if (session.harness)
+            await agents.provision(session.harnessName, session.harness, env);
+    }
+    preAgentHooks(env) {
+        step(7, 'Pre-agent hooks');
+        runHooks('pre-agent', env);
+    }
+    /** Ready: starts the session daemon and, with an agent, its first session, shown in this window. */
+    async start(env) {
+        step(8, 'Starting ' + session.harnessName);
+        setSandboxStatus('ready', 'Ready');
+        // No agent, or a restart that adds a project (the host opens its sessions itself once the sandbox is ready).
+        if (!session.harness || session.autoSession === false) {
+            if (!dryRun)
+                startDaemon(env);
+            log('Ready' + (session.harness ? '' : ' (no agent requested)') + '. Workspace: ' + workspace);
+            return;
+        }
+        if (dryRun) {
+            const launch = agents.resolveLaunch(session.harnessName, session.harness);
+            log('(dry run) would run: ' +
+                [launch.file, ...launch.args, ...session.harness.arguments, ...session.harnessArguments].join(' ') +
+                ' | cwd=' +
+                workspace);
+            runHooks('post-agent', env);
+            return;
+        }
+        startDaemon(env);
+        writeJsonAtomic(run.requestFile(session.launchId), {
+            kind: 'session',
+            id: session.launchId,
+            harness: session.harnessName,
+            args: session.harnessArguments,
+            cwd: workspace,
+            createdAt: now(),
+        });
+        if (!(await waitForPrimary()))
+            throw new Error('The agent session did not start. Logs: ' + logsDir);
+        log('If Claude asks you to sign in, do it once; the login is saved in persistent storage.');
+        if (process.stdin.isTTY)
+            await viewSession(session.launchId);
+        log('\nThis window stays open in ' + workspace + '. Other sessions keep running in their own tabs.');
+    }
+}
+export function runBoot() {
+    return new Boot().run();
+}

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

@@ -0,0 +1,16 @@
+/** Deliberately tiny: it is loaded into every conversation. */
+export interface GuideProject {
+    guest: string;
+    host: string;
+}
+export declare function sandboxGuide(toolSummary: string[], lan?: 'blocked' | 'open' | 'offline', projects?: GuideProject[]): string;
+/** Inserts or replaces the generated section, keeping whatever else the file contains (the host's CLAUDE.md). */
+export declare function upsertGuide(file: string, guide: string): void;
+/**
+ * Claude Code loads the machine-wide managed memory (C:\Program Files\ClaudeCode\CLAUDE.md on Windows) before the
+ * user and project CLAUDE.md, in every session. The sandbox is disposable and we are admin, so the manifest lives
+ * there: the user's own global CLAUDE.md and every project's CLAUDE.md stay exactly as they are.
+ * Codex/Gemini have no machine-level file, so the block goes into their sandbox-only global instruction files.
+ */
+export declare function managedClaudeMd(): string;
+export declare function writeGuides(toolSummary: string[], lan: 'blocked' | 'open' | 'offline', projects?: GuideProject[]): string;

package/dist/guest/boot/guide.js

@@ -0,0 +1,98 @@
+// Tells the agent where it is. A generated section (between markers, rewritten every boot) is added to the agent's
+// global instructions: Claude's CLAUDE.md and Codex's AGENTS.md inside the sandbox. It never travels back to this PC.
+import fs from 'node:fs';
+import path from 'node:path';
+import { claudeDir, session, stateDir, workspace } from '../runtime/session.js';
+import { dataDir, launchDir, toolsDir } from '../runtime/paths.js';
+const BEGIN = '<!-- agent-sandbox:begin (generated every boot, do not edit) -->';
+const END = '<!-- agent-sandbox:end -->';
+/** Drives other than C: are subst drives onto C:\Mirror\<letter> (mapped folders shown at their PC paths). */
+const mirrorLine = () => {
+    // Only the ones bootstrap.ps1 could create (a letter already in use is reported there and skipped).
+    const drives = (session.substDrives ?? []).filter((d) => fs.existsSync(d.letter + ':\\'));
+    if (!drives.length)
+        return [];
+    return [
+        '- ' +
+            drives.map((d) => d.letter + ':').join(', ') +
+            ' = mapped folders at their PC paths (subst onto `' +
+            drives.map((d) => d.target).join('`, `') +
+            '`; real-path tools may print that form).',
+    ];
+};
+export function sandboxGuide(toolSummary, lan = 'blocked', projects = []) {
+    return [
+        BEGIN,
+        '## Sandbox manifest — you are in a DISPOSABLE Windows Sandbox',
+        'Wiped on close: everything except the paths below (installers, winget/choco, C:\\Users, Program Files, registry).',
+        '- RW, persists: `' + workspace + '` = host folder ' + session.workspaceHost,
+        // Projects started from other folders while this sandbox runs: every agent here can see them.
+        ...projects.map((p) => '- RW, persists: `' +
+            p.guest +
+            '` = host folder ' +
+            p.host +
+            ' (another project in this sandbox; your own is `%AGENT_WORKSPACE%`)'),
+        '- RW, persists: `' +
+            toolsDir +
+            '` (toolchains) — put portable exes in `' +
+            path.join(toolsDir, 'bin') +
+            '` (on PATH)',
+        '- RW, persists: `' +
+            stateDir +
+            '` (agent config/history; do not edit logins) · logs: `' +
+            path.join(dataDir, 'logs') +
+            '`',
+        '- RO: `' + launchDir + "` (this boot's scripts) · lost on close: everything else, incl. `C:\\nvm` (Node symlink)",
+        ...mirrorLine(),
+        '- Tools: ' + toolSummary.join(' · '),
+        '- Persistent installs: `npm i -g` (per nvm version), `pip`, `cargo install`, `dotnet tool -g`, `uv tool`, `bun add -g`. Real installers must re-run each boot via a hook (ask the user).',
+        '- Mapped folders (workspace, C:\\AgentData) allow NO symlinks or junctions: pnpm runs hoisted (set), npm workspaces / `file:` deps and deno node_modules dirs fail there (use a folder on C:\\ outside them), bun cannot save its lockfile there (`bun install --no-save`).',
+        '- Network: ' +
+            (lan === 'offline'
+                ? 'OFF'
+                : lan === 'blocked'
+                    ? 'internet yes, host LAN blocked'
+                    : 'internet yes, host LAN NOT blocked this time') +
+            '. Other sessions may share this workspace; the user may be typing from the host.',
+        END,
+    ].join('\n');
+}
+/** Inserts or replaces the generated section, keeping whatever else the file contains (the host's CLAUDE.md). */
+export function upsertGuide(file, guide) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    const start = current.indexOf(BEGIN);
+    const end = current.indexOf(END);
+    const without = start >= 0 && end > start ? current.slice(0, start) + current.slice(end + END.length) : current;
+    fs.writeFileSync(file, without.trimEnd() + (without.trim() ? '\n\n' : '') + guide + '\n', 'utf8');
+}
+/**
+ * Claude Code loads the machine-wide managed memory (C:\Program Files\ClaudeCode\CLAUDE.md on Windows) before the
+ * user and project CLAUDE.md, in every session. The sandbox is disposable and we are admin, so the manifest lives
+ * there: the user's own global CLAUDE.md and every project's CLAUDE.md stay exactly as they are.
+ * Codex/Gemini have no machine-level file, so the block goes into their sandbox-only global instruction files.
+ */
+export function managedClaudeMd() {
+    return path.join(process.env.AGENT_MANAGED_DIR ?? path.join(process.env.ProgramFiles ?? 'C:\\Program Files', 'ClaudeCode'), 'CLAUDE.md');
+}
+export function writeGuides(toolSummary, lan, projects = []) {
+    const guide = sandboxGuide(toolSummary, lan, projects);
+    const managed = managedClaudeMd();
+    fs.mkdirSync(path.dirname(managed), { recursive: true });
+    fs.writeFileSync(managed, guide + '\n', 'utf8');
+    fs.writeFileSync(path.join(dataDir, 'SANDBOX.md'), guide + '\n', 'utf8');
+    upsertGuide(path.join(stateDir, 'codex', 'AGENTS.md'), guide);
+    upsertGuide(path.join(stateDir, 'gemini', '.gemini', 'GEMINI.md'), guide);
+    removeGuide(path.join(claudeDir, 'CLAUDE.md'));
+    return managed;
+}
+/** Older versions put the block into the user's CLAUDE.md; take it out again. */
+const removeGuide = (file) => {
+    if (!fs.existsSync(file))
+        return;
+    const current = fs.readFileSync(file, 'utf8');
+    const start = current.indexOf(BEGIN);
+    const end = current.indexOf(END);
+    if (start >= 0 && end > start)
+        fs.writeFileSync(file, (current.slice(0, start) + current.slice(end + END.length)).trim() + '\n', 'utf8');
+};

package/dist/guest/boot/project-env.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+export declare const BootEnvSchema: z.ZodObject<{
+    basePath: z.ZodString;
+    toolVars: z.ZodArray<z.ZodString>;
+    steps: z.ZodRecord<z.ZodString, z.ZodObject<{
+        vars: z.ZodRecord<z.ZodString, z.ZodString>;
+        prepend: z.ZodArray<z.ZodString>;
+        append: z.ZodArray<z.ZodString>;
+        summary: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    summary: z.ZodArray<z.ZodString>;
+    lan: z.ZodEnum<{
+        open: "open";
+        blocked: "blocked";
+        offline: "offline";
+    }>;
+}, z.core.$strip>;
+export type BootEnv = z.output<typeof BootEnvSchema>;
+/** The environment a later project starts from: the daemon's own, without the boot project's toolchains. */
+export declare function baseEnvFor(boot: BootEnv | null, current?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/guest/boot/project-env.js

@@ -0,0 +1,28 @@
+// Pure (no guest state): the environment a project that joined after boot starts from. Kept apart from boot-env.ts,
+// which reads the guest's session, so the host-side tests can import it.
+import { z } from 'zod';
+const EnvSchema = z.object({
+    vars: z.record(z.string(), z.string()),
+    prepend: z.array(z.string()),
+    append: z.array(z.string()),
+    summary: z.array(z.string()),
+});
+export const BootEnvSchema = z.object({
+    basePath: z.string(),
+    toolVars: z.array(z.string()),
+    steps: z.record(z.string(), EnvSchema),
+    /** The boot's tool summary and LAN state, for the agent guide that lists every project. */
+    summary: z.array(z.string()),
+    lan: z.enum(['blocked', 'open', 'offline']),
+});
+/** Variables the boot set for its own project (its workspace, its toolchains): never inherited by another project. */
+const PROJECT_VARS = /^(AGENT_WORKSPACE|AGENT_PROJECT|AGENT_SANDBOX_WORKSPACE|AGENT_PROJECT_FILE|CARGO_TARGET_DIR|VIRTUAL_ENV)$/i;
+/** The environment a later project starts from: the daemon's own, without the boot project's toolchains. */
+export function baseEnvFor(boot, current = process.env) {
+    if (!boot)
+        return { ...current };
+    const drop = new Set(boot.toolVars.map((v) => v.toLowerCase()));
+    // Windows spells it Path; a plain object would keep both spellings.
+    const base = Object.fromEntries(Object.entries(current).filter(([k]) => !drop.has(k.toLowerCase()) && !PROJECT_VARS.test(k) && k.toLowerCase() !== 'path'));
+    return { ...base, PATH: boot.basePath };
+}

package/dist/guest/boot/project-status.d.ts

@@ -0,0 +1,5 @@
+import type { DatabasePlan } from '../../core/types.js';
+import type { ProjectStatus } from '../../shared/channel/schema.js';
+/** The launch folder's project id (older launch folders: derived from its name). */
+export declare function primaryProject(): string;
+export declare function saveProjectStatus(name: string, workspace: string, phase: ProjectStatus['phase'], message: string, databases: DatabasePlan[], summary: string[]): void;

package/dist/guest/boot/project-status.js

@@ -0,0 +1,30 @@
+import { now } from '../../shared/channel/run-dir.js';
+import { writeJsonAtomic } from '../../shared/io/json.js';
+import { hubName } from '../../shared/paths/projects.js';
+import { run } from '../runtime/paths.js';
+import { session } from '../runtime/session.js';
+import { warn } from '../runtime/log.js';
+import { errMsg } from '../../core/util/errors.js';
+/** The launch folder's project id (older launch folders: derived from its name). */
+export function primaryProject() {
+    return session.projectId ?? hubName(session.workspaceHost || session.project, []);
+}
+export function saveProjectStatus(name, workspace, phase, message, databases, summary) {
+    try {
+        writeJsonAtomic(run.projectFile(name), {
+            name,
+            workspace,
+            phase,
+            message: message.slice(0, 3500),
+            updatedAt: now(),
+            databases: databases
+                .filter((d) => d.database !== 'sqlserver')
+                .slice(0, 16)
+                .map((d) => ({ database: d.database, port: d.port })),
+            summary: summary.slice(0, 64).map((s) => s.slice(0, 500)),
+        });
+    }
+    catch (e) {
+        warn('Could not write the status of project ' + name + ': ' + errMsg(e));
+    }
+}

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

@@ -0,0 +1,7 @@
+export declare class Daemon {
+    private lastMemSave;
+    /** Polls for requests for the rest of the sandbox's life; one failing iteration never stops it. */
+    start(): void;
+    private tick;
+    private handle;
+}

package/dist/guest/daemon/daemon.js

@@ -0,0 +1,57 @@
+// The session daemon's polling loop: claims each valid request in run\requests and hands it to its handler.
+import fs from 'node:fs';
+import { saveClaudeMem } from '../setup/claude-mem.js';
+import { execCommand } from './exec.js';
+import { sessions } from './sessions.js';
+import { respond, safely } from './state.js';
+import { run } from '../runtime/paths.js';
+import { warn } from '../runtime/log.js';
+import { errMsg } from '../../core/util/errors.js';
+const POLL_MS = 400;
+const MEM_SAVE_MS = 120000;
+export class Daemon {
+    lastMemSave = Date.now();
+    /** Polls for requests for the rest of the sandbox's life; one failing iteration never stops it. */
+    start() {
+        try {
+            this.tick();
+        }
+        catch (e) {
+            warn('daemon loop: ' + errMsg(e));
+        }
+        finally {
+            setTimeout(() => this.start(), POLL_MS);
+        }
+    }
+    tick() {
+        const { valid, invalid } = run.scanRequests();
+        // 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.requestFile(req.id), { force: true }));
+            if (run.readSession(req.id))
+                continue;
+            // Not awaited: starting a session or running a command must not hold up other requests.
+            void Promise.resolve(this.handle(req)).catch((e) => respond(req.id, { ok: false, message: errMsg(e) }));
+        }
+        if (Date.now() - this.lastMemSave > MEM_SAVE_MS) {
+            this.lastMemSave = Date.now();
+            safely('claude-mem save', saveClaudeMem);
+        }
+    }
+    handle(req) {
+        switch (req.kind) {
+            case 'session':
+                return sessions.start(req);
+            case 'project':
+                return sessions.prepare(req);
+            case 'exec':
+                return execCommand(req);
+            case 'restart':
+                return sessions.restart(req);
+            case 'ping':
+                return respond(req.id, { ok: true, message: 'pong (' + sessions.count + ' session(s) running)' });
+        }
+    }
+}

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

@@ -1,5 +1,5 @@
 import type { GuestRequest } from '../../core/types.js';
 /** Runs a command for the host without blocking the daemon (other requests and pings keep being answered). */
-export declare const execCommand: (req: Extract<GuestRequest, {
-    kind: "exec";
-}>) => void;
+export declare function execCommand(req: Extract<GuestRequest, {
+    kind: 'exec';
+}>): void;

package/dist/guest/daemon/exec.js

@@ -1,32 +1,48 @@
 // `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 { exists } from '../runtime/fs.js';
+import { errMsg } from '../../core/util/errors.js';
+import { provisioner } from './project-provisioner.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);
+function quoteForCmd(a) {
+    return /[\s"&|<>^]/.test(a) ? '"' + a.replace(/"/g, '""') + '"' : a;
+}
+function cap(s) {
+    return 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) => {
+export function 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 env = provisioner.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; };
+    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('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) });
+        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/idle-shutdown.d.ts

@@ -0,0 +1,8 @@
+export declare class IdleShutdown {
+    private readonly busy;
+    /** `busy`: a session runs or is starting. */
+    constructor(busy: () => boolean);
+    /** After a session ended or failed: shuts a headless sandbox down if it stays idle for a moment. */
+    check(): void;
+    private idle;
+}

package/dist/guest/daemon/idle-shutdown.js

@@ -0,0 +1,34 @@
+// 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 { saveClaudeMem } from '../setup/claude-mem.js';
+import { isWin, run } from '../runtime/paths.js';
+import { log } from '../runtime/log.js';
+import { session } from '../runtime/session.js';
+import { safely } from './state.js';
+/** How long the sandbox must stay idle before it shuts down. */
+const GRACE_MS = 15000;
+export class IdleShutdown {
+    busy;
+    /** `busy`: a session runs or is starting. */
+    constructor(busy) {
+        this.busy = busy;
+    }
+    /** After a session ended or failed: shuts a headless sandbox down if it stays idle for a moment. */
+    check() {
+        if (!session.headless || !isWin)
+            return;
+        if (!this.idle())
+            return;
+        setTimeout(() => {
+            if (!this.idle())
+                return;
+            log('Headless sandbox has no sessions left; shutting down.');
+            safely('claude-mem save', saveClaudeMem);
+            spawnSync(SYSTEM.shutdown(), ['/s', '/t', '5'], { windowsHide: true });
+        }, GRACE_MS);
+    }
+    idle() {
+        return !this.busy() && run.scanRequests().valid.length === 0;
+    }
+}