windows-development-sandbox 1.11.7 → 1.13.0

package/dist/core/schema/web.js

@@ -1,6 +1,50 @@
-// The web UI settings (sandbox web): not part of LocalOverrides, a repo never turns a way into your agents on.
+// The web UI settings (sandbox web): not part of LocalOverrides, a repo never turns a way into your agents on. The
+// remote group (other Windows users of this PC, devices on your network) is off by default: design/remote-access.md.
 import { z } from 'zod';
 export const WEB_DEFAULT_PORT = 47800;
+export const WEB_LAN_DEFAULT_PORT = 47801;
+export const REMOTE_ROLES = ['view', 'control'];
+/** A Windows account name: "bob", "PC\bob" or "DOMAIN\bob" (no paths, quotes or wildcards). */
+export const WindowsUserNameSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(120)
+    .regex(/^(?:[A-Za-z0-9][A-Za-z0-9._ -]{0,62}\\)?[^\\/"[\]:;|=,+*?<>@]{1,64}$/, 'a Windows user name (name or DOMAIN\\name)');
+export const RemoteUserSchema = z.strictObject({
+    name: WindowsUserNameSchema.describe('The Windows user (name, or DOMAIN\\name)'),
+    role: z
+        .enum(REMOTE_ROLES)
+        .describe('view: sees everything, terminals read-only. control: everything but remote access, logins and tokens.'),
+});
+export const WebLanSchema = z.strictObject({
+    enabled: z
+        .boolean()
+        .describe('(Beta) Devices on your network (a phone): an HTTPS address on this PC for devices you pair with a one-time code (sandbox web pair). Needs a firewall rule (sandbox web lan on asks Windows once). Off: every paired device is signed out.'),
+    port: z.number().int().min(1024).max(65535).describe('HTTPS port for paired devices on your network.'),
+    address: z
+        .string()
+        .trim()
+        .max(15)
+        .regex(/^$|^\d{1,3}(\.\d{1,3}){3}$/, 'an IPv4 address or empty')
+        .describe("This PC's private address to listen on. Empty: the one of its network adapter (never a public one)."),
+});
+export const WebRemoteSchema = z.strictObject({
+    windowsSignIn: z
+        .boolean()
+        .describe('(Beta) Other Windows users of this PC named in web.remote.users sign in to your web UI (and sandbox remote) with their own Windows account: no password, no link.'),
+    users: z
+        .array(RemoteUserSchema)
+        .max(32)
+        .describe('Who else may sign in with Windows, and their role (view or control).'),
+    rememberDays: z
+        .number()
+        .int()
+        .min(1)
+        .max(90)
+        .describe('How many days a paired device or a Windows sign-in stays signed in (from when it signed in, not renewed).'),
+    lan: WebLanSchema,
+});
 export const WebSchema = z.strictObject({
     enabled: z
         .boolean()
@@ -14,4 +58,5 @@ export const WebSchema = z.strictObject({
     openOnLaunch: z
         .boolean()
         .describe('(Beta) With the web UI on: open it in your browser, already signed in, every time a sandbox starts.'),
+    remote: WebRemoteSchema.describe('(Beta) Access for other Windows users of this PC and for paired devices.'),
 });

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

@@ -3,6 +3,11 @@ 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>;
+/**
+ * A file the sandbox or a repo may have written, read through one handle and only if that handle is a regular file of
+ * at most `maxBytes` (null otherwise): a multi-gigabyte .nvmrc must not stop a launch.
+ */
+export declare function readSmallFile(file: string, maxBytes?: number): string | null;
 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

@@ -28,6 +28,29 @@ export async function fileExistsAsync(p) {
         return false;
     }
 }
+/**
+ * A file the sandbox or a repo may have written, read through one handle and only if that handle is a regular file of
+ * at most `maxBytes` (null otherwise): a multi-gigabyte .nvmrc must not stop a launch.
+ */
+export function readSmallFile(file, maxBytes = 256 * 1024) {
+    let fd = null;
+    try {
+        fd = fs.openSync(file, 'r');
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || stat.size > maxBytes)
+            return null;
+        const buffer = Buffer.alloc(stat.size);
+        fs.readSync(fd, buffer, 0, stat.size, 0);
+        return buffer.toString('utf8');
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== null)
+            fs.closeSync(fd);
+    }
+}
 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, fileExistsAsync, readJson, tryReadJson, writeJson, realPath } from './fs.js';
+export { ensureDir, dirExists, fileExists, fileExistsAsync, readJson, readSmallFile, 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, fileExistsAsync, readJson, tryReadJson, writeJson, realPath } from './fs.js';
+export { ensureDir, dirExists, fileExists, fileExistsAsync, readJson, readSmallFile, 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/apps/app-installer.js

@@ -5,12 +5,13 @@ import path from 'node:path';
 import { appsToInstall } from '../../shared/apps/index.js';
 import { downloader, moveIntoPlace, stagingFolder } from '../../shared/download/index.js';
 import { safeRemove } from '../../shared/io/safe-remove.js';
-import { dryRun } from '../runtime/paths.js';
+import { dryRun, launchDir } from '../runtime/paths.js';
 import { execAsync } from '../runtime/process.js';
 import { exists, mkdirp } from '../runtime/fs.js';
 import { log, warn } from '../runtime/log.js';
 import { errMsg } from '../../core/util/errors.js';
 import { tool } from '../toolchains/tool-env.js';
+import { uvVars } from '../toolchains/runtimes.js';
 import { afterInstall } from './after-install.js';
 import { findExe } from './find-exe.js';
 import { shortcuts } from './shortcuts.js';
@@ -58,9 +59,10 @@ export class AppInstaller {
             if (!exe)
                 throw new Error(entry.exe + ' not found in the download');
             await afterInstall(entry, exe);
-            if (entry.cli || entry.id === 'sysinternals')
+            // A proxy or MCP server (agent add-ons) is started by the sandbox or the agent: no PATH entry, no shortcut.
+            if (!entry.service && (entry.cli || entry.id === 'sysinternals'))
                 this.env.prepend.push(path.dirname(exe));
-            if (!entry.cli)
+            if (!entry.cli && !entry.service)
                 this.gui.push({ name: entry.name, exe });
             this.installed.push(entry.name);
         }
@@ -74,7 +76,11 @@ export class AppInstaller {
         const work = stagingFolder(dest);
         const out = path.join(work, 'out');
         try {
-            if ('npm' in entry.source) {
+            if ('locked' in entry.source) {
+                log('Installing ' + entry.name + ' ' + entry.source.version + ' (pinned, every file checked) ...');
+                await installLocked(entry.id, entry.source.locked, mkdirp(out));
+            }
+            else if ('npm' in entry.source) {
                 const npmCli = path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
                 log('Installing ' + entry.name + ' (npm) ...');
                 await execAsync(process.execPath, [
@@ -103,6 +109,46 @@ export class AppInstaller {
         }
     }
 }
+/** The Python the uv lock files were made for (sandbox\addons\<id>\requirements.txt). */
+const LOCKED_PYTHON = '3.13';
+/**
+ * Installs a pinned package from its lock file in the launch folder (sandbox\addons\<id>) into `out`. npm: `npm ci`
+ * checks every tarball against the lock file's integrity, and runs no install scripts. uv: a relocatable venv (the
+ * folder moves into place afterwards) and `--require-hashes`, so every wheel must match its SHA-256 in the file; no
+ * source builds.
+ */
+async function installLocked(id, kind, out) {
+    const lock = path.join(launchDir, 'sandbox', 'addons', id);
+    if (kind === 'npm') {
+        for (const f of ['package.json', 'package-lock.json'])
+            fs.copyFileSync(path.join(lock, f), path.join(out, f));
+        const npmCli = path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+        await execAsync(process.execPath, [npmCli, 'ci', '--ignore-scripts', '--no-audit', '--no-fund', '--loglevel=error'], { cwd: out });
+        return;
+    }
+    const uv = findExe(tool('uv'), 'uv.exe');
+    if (!uv)
+        throw new Error('uv is not installed (the uv step failed)');
+    const env = { ...process.env, ...uvVars() };
+    const venv = path.join(out, 'venv');
+    await execAsync(uv, ['venv', '--relocatable', '--python', LOCKED_PYTHON, '--python-preference', 'only-managed', venv], {
+        env,
+    });
+    await execAsync(uv, [
+        'pip',
+        'install',
+        '--python',
+        path.join(venv, 'Scripts', 'python.exe'),
+        '--require-hashes',
+        '--no-deps',
+        '--only-binary',
+        ':all:',
+        '--link-mode',
+        'copy',
+        '-r',
+        path.join(lock, 'requirements.txt'),
+    ], { env });
+}
 /** Installs apps.install and apps.custom (skipped ones are listed in the summary). */
 export async function setupApps(env, apps, o) {
     const { entries, skipped } = appsToInstall(apps, o.gitAccess);

package/dist/guest/apps/index.d.ts

@@ -1,3 +1,3 @@
-export { appsNeedMesa } from '../../shared/apps/index.js';
+export { appsNeedMesa, appsNeedUv } from '../../shared/apps/index.js';
 export { setupApps, type AppsOptions } from './app-installer.js';
 export { findExe } from './find-exe.js';

package/dist/guest/apps/index.js

@@ -1,6 +1,6 @@
 // Installs the apps you chose (apps.install from the catalogue, apps.custom of your own) into C:\AgentData\tools\apps.
 // Installers are never run: archives are unpacked, NSIS installers opened with 7-Zip and MSIs extracted (msiexec /a),
 // so nothing is registered and nothing is lost when the sandbox closes.
-export { appsNeedMesa } from '../../shared/apps/index.js';
+export { appsNeedMesa, appsNeedUv } from '../../shared/apps/index.js';
 export { setupApps } from './app-installer.js';
 export { findExe } from './find-exe.js';

package/dist/guest/apps/sources.js

@@ -9,7 +9,7 @@ export async function resolve(entry) {
     }
     if ('url' in s) {
         const name = decodeURIComponent(new URL(s.url).pathname.split('/').pop() || entry.id);
-        return { url: s.url, fileName: /\.\w{2,5}$/.test(name) ? name : name + '.zip' };
+        return { url: s.url, fileName: /\.\w{2,5}$/.test(name) ? name : name + '.zip', sha256: s.sha256 };
     }
     if ('resolve' in s && RESOLVERS[s.resolve])
         return RESOLVERS[s.resolve]();

package/dist/guest/audit/parse.d.ts

@@ -1,7 +1,37 @@
 /** Background programs of Windows itself: never what an agent ran. */
 export declare const NOISE: Set<string>;
-/** The events in wevtutil's XML output as audit lines, with the newest record id seen. */
-export declare function parseProcessEvents(xml: string): {
+/** A session's ptyhost: everything it starts (and what those start) is that session's. */
+export interface SessionRoot {
+    readonly session: string;
+    readonly pid: number;
+    /** When the ptyhost started and ended (ms); a reused process id outside this window is not the session's. */
+    readonly from: number;
+    readonly to?: number;
+}
+/**
+ * Follows the process tree through the events themselves: a program belongs to a session when its parent is that
+ * session's ptyhost, or a program that belongs to it. Every new process id is recorded (as no session's when its
+ * parent is not one's), so an id Windows gives to another process later never inherits a session. A program whose
+ * parent was never seen is no session's: nothing is guessed.
+ */
+export declare class Attributor {
+    private readonly owner;
+    /** The session of a new process (pid, started by ppid at time t), or undefined. */
+    attribute(e: {
+        readonly pid: number;
+        readonly ppid: number;
+        readonly t: number;
+    }, roots: readonly SessionRoot[]): string | undefined;
+}
+/**
+ * The events in wevtutil's XML output as audit lines, with the newest record id seen. With an attributor and the
+ * sessions' roots, each line says which session started it (s), when that is known. Every event goes through the
+ * attributor, Windows' own background programs too (they are left out of the lines only afterwards).
+ */
+export declare function parseProcessEvents(xml: string, attribution?: {
+    readonly attributor: Attributor;
+    readonly roots: readonly SessionRoot[];
+}): {
     lines: string[];
     last: number;
 };

package/dist/guest/audit/parse.js

@@ -1,5 +1,5 @@
-// Reading Windows process-creation events (Security log, 4688, as wevtutil prints them) into audit lines. Pure, so
-// the self-test can check it on the PC side.
+// Reading Windows process-creation events (Security log, 4688, as wevtutil prints them) into audit lines, and which
+// agent session each program belongs to. Pure, so the self-test can check it on the PC side.
 import path from 'node:path';
 /** Background programs of Windows itself: never what an agent ran. */
 export const NOISE = new Set([
@@ -28,6 +28,29 @@ export const NOISE = new Set([
     'usoclient.exe',
     'musnotification.exe',
 ]);
+/** Windows' clocks and ours differ by a moment: a root counts this long around its window. */
+const ROOT_SLACK_MS = 5000;
+/** Most process ids remembered (the oldest are forgotten first). */
+const MAX_KNOWN = 50000;
+/**
+ * Follows the process tree through the events themselves: a program belongs to a session when its parent is that
+ * session's ptyhost, or a program that belongs to it. Every new process id is recorded (as no session's when its
+ * parent is not one's), so an id Windows gives to another process later never inherits a session. A program whose
+ * parent was never seen is no session's: nothing is guessed.
+ */
+export class Attributor {
+    owner = new Map();
+    /** The session of a new process (pid, started by ppid at time t), or undefined. */
+    attribute(e, roots) {
+        const root = roots.find((r) => r.pid === e.ppid && e.t >= r.from - ROOT_SLACK_MS && (r.to === undefined || e.t <= r.to + ROOT_SLACK_MS));
+        const session = root?.session ?? this.owner.get(e.ppid) ?? undefined;
+        this.owner.delete(e.pid);
+        this.owner.set(e.pid, session ?? null);
+        if (this.owner.size > MAX_KNOWN)
+            this.owner.delete(this.owner.keys().next().value);
+        return session;
+    }
+}
 const decode = (s) => s
     .replace(/&lt;/g, '<')
     .replace(/&gt;/g, '>')
@@ -35,8 +58,17 @@ const decode = (s) => s
     .replace(/&apos;/g, "'")
     .replace(/&amp;/g, '&');
 const field = (event, name) => decode(new RegExp("<Data Name='" + name + "'>([^<]*)</Data>").exec(event)?.[1] ?? '');
-/** The events in wevtutil's XML output as audit lines, with the newest record id seen. */
-export function parseProcessEvents(xml) {
+/** A process id as the event writes it (0x1a2c). */
+const pidOf = (text) => {
+    const n = /^0x[0-9a-f]{1,8}$/i.test(text) ? parseInt(text, 16) : /^\d{1,10}$/.test(text) ? Number(text) : 0;
+    return Number.isSafeInteger(n) ? n : 0;
+};
+/**
+ * The events in wevtutil's XML output as audit lines, with the newest record id seen. With an attributor and the
+ * sessions' roots, each line says which session started it (s), when that is known. Every event goes through the
+ * attributor, Windows' own background programs too (they are left out of the lines only afterwards).
+ */
+export function parseProcessEvents(xml, attribution) {
     const lines = [];
     let last = 0;
     for (const event of xml.split('</Event>')) {
@@ -45,15 +77,21 @@ export function parseProcessEvents(xml) {
             continue;
         last = Math.max(last, id);
         const program = field(event, 'NewProcessName');
+        const t = /SystemTime='([^']+)'/.exec(event)?.[1] ?? new Date().toISOString();
+        const pid = pidOf(field(event, 'NewProcessId'));
+        const ppid = pidOf(field(event, 'ProcessId'));
+        const session = attribution && pid && ppid
+            ? attribution.attributor.attribute({ pid, ppid, t: Date.parse(t) || Date.now() }, attribution.roots)
+            : undefined;
         if (!program || NOISE.has(path.win32.basename(program).toLowerCase()))
             continue;
-        const t = /SystemTime='([^']+)'/.exec(event)?.[1] ?? new Date().toISOString();
         lines.push(JSON.stringify({
             t,
             k: 'proc',
             p: program.slice(0, 1024),
             c: field(event, 'CommandLine').slice(0, 2000),
             pp: field(event, 'ParentProcessName').slice(0, 1024),
+            ...(session ? { s: session } : {}),
         }));
     }
     return { lines, last };

package/dist/guest/audit/process-audit.d.ts

@@ -1,6 +1,8 @@
+import { type SessionRoot } from './parse.js';
 /** Turns on process-creation auditing with command lines (the registry is new every boot). */
 export declare function enableProcessAudit(): void;
 /**
  * Reads new process events every 15 s for the daemon's life (from the moment it started: older ones are boot noise).
+ * `roots` gives the sessions' ptyhosts, so each program is linked to the session that started it (parse.ts).
  */
-export declare function startProcessCollector(): void;
+export declare function startProcessCollector(roots?: () => readonly SessionRoot[]): void;

package/dist/guest/audit/process-audit.js

@@ -1,12 +1,13 @@
 // audit.processes, sandbox side: Windows records every program started (Security log, event 4688, with its command
-// line); the daemon reads the new events every 15 s and leaves them in run\audit\ as small .jsonl files, which the
-// host takes into its own log (and deletes). Windows' own background programs are left out. The host treats all of it
-// as untrusted (it is checked line by line there).
+// line and process ids); the daemon reads the new events every 15 s, links each to the agent session whose ptyhost
+// started it (directly or further down), and leaves them in run\audit\ as small .jsonl files, which the host takes
+// into its own log (and deletes). Windows' own background programs are left out. The host treats all of it as
+// untrusted (it is checked line by line there, and a session it does not know is dropped).
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { SYSTEM } from '../../shared/system.js';
-import { parseProcessEvents } from './parse.js';
+import { Attributor, parseProcessEvents } from './parse.js';
 import { dryRun, isWin, run } from '../runtime/paths.js';
 import { log, warn } from '../runtime/log.js';
 import { mkdirp } from '../runtime/fs.js';
@@ -44,11 +45,13 @@ const newestRecord = () => {
 };
 /**
  * Reads new process events every 15 s for the daemon's life (from the moment it started: older ones are boot noise).
+ * `roots` gives the sessions' ptyhosts, so each program is linked to the session that started it (parse.ts).
  */
-export function startProcessCollector() {
+export function startProcessCollector(roots = () => []) {
     if (!auditOn())
         return;
     let last = newestRecord();
+    const attributor = new Attributor();
     const pass = () => {
         try {
             const r = spawnSync(wevtutil(), [
@@ -58,7 +61,7 @@ export function startProcessCollector() {
                 '/f:xml',
                 '/c:' + MAX_PER_PASS,
             ], { encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
-            const { lines, last: newest } = parseProcessEvents(r.stdout ?? '');
+            const { lines, last: newest } = parseProcessEvents(r.stdout ?? '', { attributor, roots: roots() });
             if (newest)
                 last = newest;
             if (lines.length)

package/dist/guest/boot/boot.js

@@ -16,6 +16,8 @@ import { runHooks } from '../setup/hooks.js';
 import { applyAllowOnly, proxyEnv } from '../network/allow-only.js';
 import { applyNetworkPolicy, networkProblems } from '../network/firewall.js';
 import { writeManagedSettings } from '../setup/managed-policy.js';
+import { writeAddonMcpServers } from '../setup/addon-mcp.js';
+import { startHeadroom } from '../setup/headroom.js';
 import { applyPersonalization } from '../setup/desktop.js';
 import { setupGitConfig } from '../setup/git-identity.js';
 import { loginGithub, prepareGithubFolder } from '../setup/github-token.js';
@@ -144,7 +146,7 @@ export class Boot {
         const { tools, env } = await this.developerTools();
         await this.vpn();
         await this.gitIdentity(env);
-        await this.claude(tools);
+        await this.claude(tools, env);
         await this.agent(env);
         this.preAgentHooks(env);
         await this.start(env);
@@ -230,15 +232,22 @@ export class Boot {
             await soft('GitHub token', () => loginGithub(token, env));
         }
     }
-    async claude(tools) {
+    async claude(tools, env) {
         step(6, 'Claude settings, history and claude-mem');
         if (session.harnessName === 'claude')
             await soft('Claude settings', () => syncClaudeProfile(this.secrets.claudeCredentials));
         await soft('claude-mem restore', restoreClaudeMem);
         await soft('Agent files of the last sandbox', resetMachineBound);
         await soft('Agent databases restore', restoreLocalState);
+        // Agent add-ons: MCP servers in the sandbox's Claude Code, and the Headroom proxy before the managed settings point
+        // Claude Code at it (the guide reads them back, so it comes last).
+        let headroom = null;
+        await soft('MCP servers from Apps', writeAddonMcpServers);
+        await soft('Headroom proxy', async () => {
+            headroom = await startHeadroom(env);
+        });
+        await soft('Claude managed settings', () => writeManagedSettings(this.gitAccess, headroom));
         await soft('Sandbox guide for the agent', () => writeGuides(tools.summary, this.lan));
-        await soft('Claude managed settings', () => writeManagedSettings(this.gitAccess));
     }
     async agent(env) {
         step(7, 'Agent: ' + session.harnessName);

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

@@ -3,7 +3,7 @@ export interface GuideProject {
     guest: string;
     host: string;
 }
-export declare function sandboxGuide(toolSummary: string[], lan?: 'blocked' | 'open' | 'offline', projects?: GuideProject[]): string;
+export declare function sandboxGuide(toolSummary: string[], lan?: 'blocked' | 'open' | 'offline', projects?: GuideProject[], addons?: string[]): 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;
 /**

package/dist/guest/boot/guide.js

@@ -3,7 +3,9 @@
 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';
+import { dataDir, launchDir, logsDir, toolsDir } from '../runtime/paths.js';
+import { addonGuideLine, APPS, headroomGuideLine, RTK_GUIDE_LINE } from '../../shared/apps/index.js';
+import { installedAddon, installedRtk } from '../setup/agent-addons.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). */
@@ -20,7 +22,7 @@ const mirrorLine = () => {
             '`; real-path tools may print that form).',
     ];
 };
-export function sandboxGuide(toolSummary, lan = 'blocked', projects = []) {
+export function sandboxGuide(toolSummary, lan = 'blocked', projects = [], addons = []) {
     return [
         BEGIN,
         '## Sandbox manifest — you are in a DISPOSABLE Windows Sandbox',
@@ -45,6 +47,8 @@ export function sandboxGuide(toolSummary, lan = 'blocked', projects = []) {
         '- RO: `' + launchDir + "` (this boot's scripts) · lost on close: everything else, incl. `C:\\nvm` (Node symlink)",
         ...mirrorLine(),
         '- Tools: ' + toolSummary.join(' · '),
+        // Agent add-ons that change how the agent works (rtk, Headroom, MCP servers, ccusage).
+        ...addons,
         '- 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: ' +
@@ -75,8 +79,28 @@ export function upsertGuide(file, guide) {
 export function managedClaudeMd() {
     return path.join(process.env.AGENT_MANAGED_DIR ?? path.join(process.env.ProgramFiles ?? 'C:\\Program Files', 'ClaudeCode'), 'CLAUDE.md');
 }
+/** Whether the managed settings point Claude Code at the Headroom proxy (written just before the guide). */
+const headroomRuns = () => {
+    try {
+        const file = path.join(path.dirname(managedClaudeMd()), 'managed-settings.json');
+        const settings = JSON.parse(fs.readFileSync(file, 'utf8'));
+        return typeof settings.env?.ANTHROPIC_BASE_URL === 'string';
+    }
+    catch {
+        return false; // no managed settings: nothing points at the proxy
+    }
+};
+/** The lines for the agent add-ons that are on and installed (rtk, Headroom, MCP servers, ccusage). */
+function addonLines() {
+    const mcp = APPS.flatMap((a) => (a.mcp && installedAddon(a.id) ? [a.mcp.name] : []));
+    return [
+        ...(installedRtk() ? [RTK_GUIDE_LINE] : []),
+        ...(installedAddon('headroom') && headroomRuns() ? [headroomGuideLine(path.join(logsDir, 'headroom.log'))] : []),
+        ...addonGuideLine(mcp, Boolean(installedAddon('ccusage'))),
+    ];
+}
 export function writeGuides(toolSummary, lan, projects = []) {
-    const guide = sandboxGuide(toolSummary, lan, projects);
+    const guide = sandboxGuide(toolSummary, lan, projects, addonLines());
     const managed = managedClaudeMd();
     fs.mkdirSync(path.dirname(managed), { recursive: true });
     fs.writeFileSync(managed, guide + '\n', 'utf8');

package/dist/guest/daemon/daemon.js

@@ -54,6 +54,8 @@ export class Daemon {
                 return execCommand(req);
             case 'restart':
                 return sessions.restart(req);
+            case 'close':
+                return sessions.close(req);
             case 'pressure':
                 // No response: the host repeats it every few seconds while its memory stays low.
                 return governor.hostPressure(req.seconds, req.reason, req.level ?? 'slow');

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

@@ -1,4 +1,5 @@
-// A headless sandbox with nothing running (or starting) only wastes RAM, so it shuts itself down.
+// A headless sandbox with nothing running (or starting) only wastes RAM, so it shuts itself down. Every open session
+// counts, a plain shell as much as an agent: whether it is busy cannot be told from outside, and closing it says so.
 import { spawnSync } from 'node:child_process';
 import { SYSTEM } from '../../shared/system.js';
 import { saveClaudeMem } from '../setup/claude-mem.js';

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

@@ -1,4 +1,5 @@
 import type { GuestRequest } from '../../core/types.js';
+import type { SessionRoot } from '../audit/parse.js';
 type SessionRequest = Extract<GuestRequest, {
     kind: 'session';
 }>;
@@ -14,9 +15,18 @@ export declare class SessionManager {
     /** Sessions and projects being set up right now (a headless sandbox must not shut down under them). */
     private starting;
     private readonly idle;
+    /** Each session's ptyhost (process id and when it ran), for linking the programs it starts to it (audit). */
+    private readonly ptyHosts;
     /** How many sessions are running. */
     get count(): number;
-    /** `session` requests: an agent in its own ptyhost, in the launch folder's project or a registered one. */
+    /** The sessions' ptyhosts, running or ended within ROOTS_KEPT_MS (audit events arrive after they happen). */
+    roots(): SessionRoot[];
+    private rootStarted;
+    private rootEnded;
+    /**
+     * `session` requests: an agent (or a plain shell) in its own ptyhost, in the launch folder's project or a registered
+     * one.
+     */
     start(req: SessionRequest): Promise<void>;
     /**
      * `project` requests: provision a registered project without an agent (sandbox start / exec / db from its folder).
@@ -24,10 +34,21 @@ export declare class SessionManager {
     prepare(req: Extract<GuestRequest, {
         kind: 'project';
     }>): Promise<void>;
-    /** `restart` requests: the matching sessions restart their agent (continuing the conversation where it can). */
+    /**
+     * `restart` requests: the matching sessions restart their agent (continuing the conversation where it can). Shells
+     * are left alone: restarting one would only throw away what it was doing.
+     */
     restart(req: Extract<GuestRequest, {
         kind: 'restart';
     }>): Promise<void>;
+    /**
+     * `close` requests: the session's ptyhost ends its program and everything it started (ProcessTree), then exits as
+     * if the program had. One that does not end in time has its ptyhost ended instead (closing the pseudo console ends
+     * what is attached to it).
+     */
+    close(req: Extract<GuestRequest, {
+        kind: 'close';
+    }>): Promise<void>;
     /**
      * Finds out which of Claude's conversation files this session writes (it appears with the first message) and puts
      * it in the status, so the host can reopen this very conversation. A reopened session starts with the one it was