windows-development-sandbox 1.18.4 → 1.23.0

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

@@ -0,0 +1,252 @@
+import type { BootTaskDef } from './runner.js';
+export declare const STAGES = 9;
+/** The titles of the nine stages (the host shows the short form without the brackets). */
+export declare function stageTitle(stage: number, who?: {
+    vpnServer?: string;
+    agent?: string;
+}): string;
+/** The boot state the tasks share. */
+export type BootStateKey = 'ptyHost' | 'lan' | 'tools' | 'dbBin' | 'allowSummary' | 'vscodeSummary' | 'env' | 'toolVars' | 'summary' | 'headroom' | 'later';
+export interface BootTaskInfo {
+    readonly writes: readonly BootStateKey[];
+    readonly reads: readonly BootStateKey[];
+}
+export declare const BOOT_TASKS: readonly [{
+    readonly id: "ptyhost";
+    readonly stage: 1;
+    readonly title: "Session host";
+    readonly after: readonly [];
+    readonly critical: false;
+    readonly writes: readonly ["ptyHost"];
+    readonly reads: readonly [];
+}, {
+    readonly id: "network";
+    readonly stage: 1;
+    readonly title: "Private-network blocking";
+    readonly after: readonly ["ptyhost"];
+    readonly critical: false;
+    readonly writes: readonly ["lan"];
+    readonly reads: readonly ["ptyHost"];
+}, {
+    readonly id: "audit";
+    readonly stage: 1;
+    readonly title: "Process audit";
+    readonly after: readonly [];
+    readonly critical: false;
+    readonly writes: readonly [];
+    readonly reads: readonly [];
+}, {
+    readonly id: "hooksPreProvision";
+    readonly stage: 2;
+    readonly title: "Pre-provision hooks";
+    readonly after: readonly ["network"];
+    readonly critical: true;
+    readonly writes: readonly [];
+    readonly reads: readonly [];
+}, {
+    readonly id: "desktop";
+    readonly stage: 2;
+    readonly title: "Personalisation";
+    readonly after: readonly [];
+    readonly critical: false;
+    readonly writes: readonly [];
+    readonly reads: readonly [];
+}, {
+    readonly id: "browserGpu";
+    readonly stage: 2;
+    readonly title: "Browsers without the GPU";
+    readonly after: readonly [];
+    readonly critical: false;
+    readonly writes: readonly [];
+    readonly reads: readonly [];
+}, {
+    readonly id: "toolchains";
+    readonly stage: 3;
+    readonly title: "Developer tools";
+    readonly after: readonly ["network", "hooksPreProvision"];
+    readonly critical: true;
+    readonly writes: readonly ["tools"];
+    readonly reads: readonly [];
+}, {
+    readonly id: "dbCommands";
+    readonly stage: 3;
+    readonly title: "Tool commands";
+    readonly after: readonly [];
+    readonly critical: true;
+    readonly writes: readonly ["dbBin"];
+    readonly reads: readonly [];
+}, {
+    readonly id: "allowOnly";
+    readonly stage: 3;
+    readonly title: "Network: allow only some hosts";
+    readonly after: readonly ["toolchains"];
+    readonly critical: false;
+    readonly writes: readonly ["allowSummary"];
+    readonly reads: readonly [];
+}, {
+    readonly id: "vscode";
+    readonly stage: 3;
+    readonly title: "VS Code setup";
+    readonly after: readonly ["toolchains", "allowOnly"];
+    readonly critical: false;
+    readonly writes: readonly ["vscodeSummary"];
+    readonly reads: readonly ["tools"];
+}, {
+    readonly id: "env";
+    readonly stage: 3;
+    readonly title: "Environment";
+    readonly after: readonly ["toolchains", "dbCommands", "allowOnly"];
+    readonly critical: true;
+    readonly writes: readonly ["env", "toolVars"];
+    readonly reads: readonly ["tools", "dbBin"];
+}, {
+    readonly id: "bootEnv";
+    readonly stage: 3;
+    readonly title: "Boot summary files";
+    readonly after: readonly ["env", "vscode"];
+    readonly critical: false;
+    readonly writes: readonly ["summary"];
+    readonly reads: readonly ["tools", "toolVars", "lan", "allowSummary", "vscodeSummary"];
+}, {
+    readonly id: "vpn";
+    readonly stage: 4;
+    readonly title: "VPN";
+    readonly after: readonly ["toolchains", "allowOnly", "ptyhost"];
+    readonly critical: false;
+    readonly writes: readonly [];
+    readonly reads: readonly ["ptyHost"];
+}, {
+    readonly id: "gitConfig";
+    readonly stage: 5;
+    readonly title: "Git config";
+    readonly after: readonly ["env"];
+    readonly critical: false;
+    readonly writes: readonly [];
+    readonly reads: readonly ["env"];
+}, {
+    readonly id: "githubLogin";
+    readonly stage: 5;
+    readonly title: "GitHub token";
+    readonly after: readonly ["vpn", "gitConfig"];
+    readonly critical: false;
+    readonly writes: readonly [];
+    readonly reads: readonly ["env"];
+}, {
+    readonly id: "claudeProfile";
+    readonly stage: 6;
+    readonly title: "Claude settings";
+    readonly after: readonly [];
+    readonly critical: false;
+    readonly writes: readonly [];
+    readonly reads: readonly [];
+}, {
+    readonly id: "claudeMem";
+    readonly stage: 6;
+    readonly title: "claude-mem restore";
+    readonly after: readonly [];
+    readonly critical: false;
+    readonly writes: readonly [];
+    readonly reads: readonly [];
+}, {
+    readonly id: "agentState";
+    readonly stage: 6;
+    readonly title: "Agent state";
+    readonly after: readonly [];
+    readonly critical: false;
+    readonly writes: readonly [];
+    readonly reads: readonly [];
+}, {
+    readonly id: "headroomSpawn";
+    readonly stage: 6;
+    readonly title: "Headroom start";
+    readonly after: readonly ["network"];
+    readonly critical: false;
+    readonly writes: readonly [];
+    readonly reads: readonly [];
+}, {
+    readonly id: "mcpServers";
+    readonly stage: 6;
+    readonly title: "MCP servers from Apps";
+    readonly after: readonly ["toolchains", "claudeProfile"];
+    readonly critical: false;
+    readonly writes: readonly [];
+    readonly reads: readonly [];
+}, {
+    readonly id: "headroomReady";
+    readonly stage: 6;
+    readonly title: "Headroom proxy";
+    readonly after: readonly ["headroomSpawn", "toolchains"];
+    readonly critical: false;
+    readonly writes: readonly ["headroom"];
+    readonly reads: readonly [];
+}, {
+    readonly id: "managedSettings";
+    readonly stage: 6;
+    readonly title: "Claude managed settings";
+    readonly after: readonly ["headroomReady", "toolchains"];
+    readonly critical: false;
+    readonly writes: readonly [];
+    readonly reads: readonly ["headroom"];
+}, {
+    readonly id: "guide";
+    readonly stage: 6;
+    readonly title: "Sandbox guide for the agent";
+    readonly after: readonly ["bootEnv", "managedSettings", "mcpServers", "network", "vscode"];
+    readonly critical: false;
+    readonly writes: readonly [];
+    readonly reads: readonly ["summary", "lan"];
+}, {
+    readonly id: "profileLinks";
+    readonly stage: 7;
+    readonly title: "Agent logins";
+    readonly after: readonly ["agentState"];
+    readonly critical: true;
+    readonly writes: readonly [];
+    readonly reads: readonly [];
+}, {
+    readonly id: "agentProvision";
+    readonly stage: 7;
+    readonly title: "Agent install";
+    readonly after: readonly ["env", "vpn", "profileLinks"];
+    readonly critical: true;
+    readonly writes: readonly [];
+    readonly reads: readonly ["env"];
+}, {
+    readonly id: "hooksPreAgent";
+    readonly stage: 8;
+    readonly title: "Pre-agent hooks";
+    readonly after: readonly ["ptyhost", "network", "audit", "hooksPreProvision", "desktop", "browserGpu", "toolchains", "dbCommands", "allowOnly", "vscode", "env", "bootEnv", "vpn", "gitConfig", "githubLogin", "claudeProfile", "claudeMem", "agentState", "headroomSpawn", "mcpServers", "headroomReady", "managedSettings", "guide", "profileLinks", "agentProvision"];
+    readonly critical: true;
+    readonly exclusive: true;
+    readonly writes: readonly [];
+    readonly reads: readonly ["env"];
+}, {
+    readonly id: "session";
+    readonly stage: 9;
+    readonly title: "Session";
+    readonly after: readonly ["hooksPreAgent"];
+    readonly critical: true;
+    readonly writes: readonly [];
+    readonly reads: readonly ["env"];
+}, {
+    readonly id: "toolchainsLater";
+    readonly stage: 3;
+    readonly title: "Visual Studio and what needs it";
+    readonly after: readonly ["session"];
+    readonly critical: false;
+    readonly background: true;
+    readonly writes: readonly ["later"];
+    readonly reads: readonly ["tools", "env", "toolVars", "lan"];
+}, {
+    readonly id: "prune";
+    readonly stage: 3;
+    readonly title: "Cleaning old tool builds";
+    readonly after: readonly ["session"];
+    readonly critical: false;
+    readonly background: true;
+    readonly writes: readonly [];
+    readonly reads: readonly [];
+}];
+export type BootTaskId = (typeof BOOT_TASKS)[number]['id'];
+/** The graph as the runner takes it (mutable arrays, ids widened). */
+export declare const BOOT_DEFS: readonly BootTaskDef<BootTaskId>[];

package/dist/guest/boot/graph.js

@@ -0,0 +1,257 @@
+export const STAGES = 9;
+/** The titles of the nine stages (the host shows the short form without the brackets). */
+export function stageTitle(stage, who = {}) {
+    switch (stage) {
+        case 1:
+            return 'Network and session host';
+        case 2:
+            return 'Pre-provision hooks and desktop';
+        case 3:
+            return 'Developer tools (the first start downloads them once; later starts are quick)';
+        case 4:
+            return who.vpnServer ? 'VPN (' + who.vpnServer + ')' : 'VPN (off)';
+        case 5:
+            return 'Git identity';
+        case 6:
+            return 'Claude settings, history and claude-mem';
+        case 7:
+            return 'Agent: ' + (who.agent ?? 'none');
+        case 8:
+            return 'Pre-agent hooks';
+        default:
+            return 'Starting ' + (who.agent ?? 'the agent');
+    }
+}
+export const BOOT_TASKS = [
+    // Stage 1 - network and session host
+    { id: 'ptyhost', stage: 1, title: 'Session host', after: [], critical: false, writes: ['ptyHost'], reads: [] },
+    {
+        id: 'network',
+        stage: 1,
+        title: 'Private-network blocking',
+        after: ['ptyhost'],
+        critical: false,
+        writes: ['lan'],
+        reads: ['ptyHost'],
+    },
+    { id: 'audit', stage: 1, title: 'Process audit', after: [], critical: false, writes: [], reads: [] },
+    // Stage 2 - pre-provision hooks and desktop
+    {
+        id: 'hooksPreProvision',
+        stage: 2,
+        title: 'Pre-provision hooks',
+        after: ['network'],
+        critical: true,
+        writes: [],
+        reads: [],
+    },
+    { id: 'desktop', stage: 2, title: 'Personalisation', after: [], critical: false, writes: [], reads: [] },
+    { id: 'browserGpu', stage: 2, title: 'Browsers without the GPU', after: [], critical: false, writes: [], reads: [] },
+    // Stage 3 - developer tools
+    {
+        id: 'toolchains',
+        stage: 3,
+        title: 'Developer tools',
+        after: ['network', 'hooksPreProvision'],
+        critical: true,
+        writes: ['tools'],
+        reads: [],
+    },
+    { id: 'dbCommands', stage: 3, title: 'Tool commands', after: [], critical: true, writes: ['dbBin'], reads: [] },
+    {
+        id: 'allowOnly',
+        stage: 3,
+        title: 'Network: allow only some hosts',
+        after: ['toolchains'],
+        critical: false,
+        writes: ['allowSummary'],
+        reads: [],
+    },
+    {
+        id: 'vscode',
+        stage: 3,
+        title: 'VS Code setup',
+        after: ['toolchains', 'allowOnly'],
+        critical: false,
+        writes: ['vscodeSummary'],
+        reads: ['tools'],
+    },
+    {
+        id: 'env',
+        stage: 3,
+        title: 'Environment',
+        after: ['toolchains', 'dbCommands', 'allowOnly'],
+        critical: true,
+        writes: ['env', 'toolVars'],
+        reads: ['tools', 'dbBin'],
+    },
+    {
+        id: 'bootEnv',
+        stage: 3,
+        title: 'Boot summary files',
+        after: ['env', 'vscode'],
+        critical: false,
+        writes: ['summary'],
+        reads: ['tools', 'toolVars', 'lan', 'allowSummary', 'vscodeSummary'],
+    },
+    // Stage 4 - VPN
+    {
+        id: 'vpn',
+        stage: 4,
+        title: 'VPN',
+        after: ['toolchains', 'allowOnly', 'ptyhost'],
+        critical: false,
+        writes: [],
+        reads: ['ptyHost'],
+    },
+    // Stage 5 - git
+    {
+        id: 'gitConfig',
+        stage: 5,
+        title: 'Git config',
+        after: ['env'],
+        critical: false,
+        writes: [],
+        reads: ['env'],
+    },
+    {
+        id: 'githubLogin',
+        stage: 5,
+        title: 'GitHub token',
+        after: ['vpn', 'gitConfig'],
+        critical: false,
+        writes: [],
+        reads: ['env'],
+    },
+    // Stage 6 - Claude settings
+    { id: 'claudeProfile', stage: 6, title: 'Claude settings', after: [], critical: false, writes: [], reads: [] },
+    { id: 'claudeMem', stage: 6, title: 'claude-mem restore', after: [], critical: false, writes: [], reads: [] },
+    { id: 'agentState', stage: 6, title: 'Agent state', after: [], critical: false, writes: [], reads: [] },
+    {
+        id: 'headroomSpawn',
+        stage: 6,
+        title: 'Headroom start',
+        after: ['network'],
+        critical: false,
+        writes: [],
+        reads: [],
+    },
+    {
+        id: 'mcpServers',
+        stage: 6,
+        title: 'MCP servers from Apps',
+        after: ['toolchains', 'claudeProfile'],
+        critical: false,
+        writes: [],
+        reads: [],
+    },
+    {
+        id: 'headroomReady',
+        stage: 6,
+        title: 'Headroom proxy',
+        after: ['headroomSpawn', 'toolchains'],
+        critical: false,
+        writes: ['headroom'],
+        reads: [],
+    },
+    {
+        id: 'managedSettings',
+        stage: 6,
+        title: 'Claude managed settings',
+        after: ['headroomReady', 'toolchains'],
+        critical: false,
+        writes: [],
+        reads: ['headroom'],
+    },
+    {
+        id: 'guide',
+        stage: 6,
+        title: 'Sandbox guide for the agent',
+        after: ['bootEnv', 'managedSettings', 'mcpServers', 'network', 'vscode'],
+        critical: false,
+        writes: [],
+        reads: ['summary', 'lan'],
+    },
+    // Stage 7 - agent
+    // After the agent state is restored (both work in the persistent state folders).
+    { id: 'profileLinks', stage: 7, title: 'Agent logins', after: ['agentState'], critical: true, writes: [], reads: [] },
+    {
+        id: 'agentProvision',
+        stage: 7,
+        title: 'Agent install',
+        after: ['env', 'vpn', 'profileLinks'],
+        critical: true,
+        writes: [],
+        reads: ['env'],
+    },
+    // Stage 8 - pre-agent hooks: after every foreground task (the hooks inherit the terminal)
+    {
+        id: 'hooksPreAgent',
+        stage: 8,
+        title: 'Pre-agent hooks',
+        after: [
+            'ptyhost',
+            'network',
+            'audit',
+            'hooksPreProvision',
+            'desktop',
+            'browserGpu',
+            'toolchains',
+            'dbCommands',
+            'allowOnly',
+            'vscode',
+            'env',
+            'bootEnv',
+            'vpn',
+            'gitConfig',
+            'githubLogin',
+            'claudeProfile',
+            'claudeMem',
+            'agentState',
+            'headroomSpawn',
+            'mcpServers',
+            'headroomReady',
+            'managedSettings',
+            'guide',
+            'profileLinks',
+            'agentProvision',
+        ],
+        critical: true,
+        exclusive: true,
+        writes: [],
+        reads: ['env'],
+    },
+    // Stage 9 - start
+    {
+        id: 'session',
+        stage: 9,
+        title: 'Session',
+        after: ['hooksPreAgent'],
+        critical: true,
+        writes: [],
+        reads: ['env'],
+    },
+    // Background: after the first session runs
+    {
+        id: 'toolchainsLater',
+        stage: 3,
+        title: 'Visual Studio and what needs it',
+        after: ['session'],
+        critical: false,
+        background: true,
+        writes: ['later'],
+        reads: ['tools', 'env', 'toolVars', 'lan'],
+    },
+    {
+        id: 'prune',
+        stage: 3,
+        title: 'Cleaning old tool builds',
+        after: ['session'],
+        critical: false,
+        background: true,
+        writes: [],
+        reads: [],
+    },
+];
+/** The graph as the runner takes it (mutable arrays, ids widened). */
+export const BOOT_DEFS = BOOT_TASKS;

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

@@ -0,0 +1,25 @@
+/** A folder mapped from the PC at boot for other projects (a project root, or a single project). */
+export interface MappedFolder {
+    readonly host: string;
+    readonly guest: string;
+    /** A project root: every folder in it is a project of this sandbox. */
+    readonly root?: boolean;
+}
+/** A project registered after boot, with the tools it got. */
+export interface GuideProject {
+    guest: string;
+    host: string;
+    name?: string;
+    tools?: readonly string[];
+}
+/**
+ * Where the agent can write and what persists: the launch folder, then every mapped project root as `<guest>\*` = host
+ * `<host>\*` (any folder in it is a project, yours or another agent's) and every project mapped at boot, then the
+ * projects registered since.
+ */
+export declare function projectFolderLines(workspace: string, workspaceHost: string, mapped: readonly MappedFolder[], projects: readonly GuideProject[]): string[];
+/**
+ * The tools: one line for the launch folder's project; with other projects in the sandbox each line names its project
+ * (a project that has not been set up yet is not listed: its tools are decided from its own files).
+ */
+export declare function toolLines(primaryName: string, toolSummary: readonly string[], projects: readonly GuideProject[]): string[];

package/dist/guest/boot/guide-lines.js

@@ -0,0 +1,41 @@
+// The folder and tool lines of the sandbox guide. Pure (no guest state), so the self-test can import it.
+import path from 'node:path';
+const within = (parent, child) => {
+    const rel = path.win32.relative(parent.toLowerCase(), child.toLowerCase());
+    return rel === '' || (!rel.startsWith('..') && !path.win32.isAbsolute(rel));
+};
+/**
+ * Where the agent can write and what persists: the launch folder, then every mapped project root as `<guest>\*` = host
+ * `<host>\*` (any folder in it is a project, yours or another agent's) and every project mapped at boot, then the
+ * projects registered since.
+ */
+export function projectFolderLines(workspace, workspaceHost, mapped, projects) {
+    const roots = mapped.filter((m) => m.root);
+    const insideRoot = roots.some((r) => within(r.guest, workspace));
+    const line = (guest, host, note = '') => '- RW, persists: `' + guest + '` = host folder ' + host + note;
+    return [
+        ...(insideRoot ? [] : [line(workspace, workspaceHost)]),
+        ...roots.map((r) => line(path.win32.join(r.guest, '*'), path.win32.join(r.host, '*'), ' (project root: every project in it persists, your own is `%AGENT_WORKSPACE%`)')),
+        ...mapped
+            .filter((m) => !m.root && !within(workspace, m.guest) && !roots.some((r) => within(r.guest, m.guest)))
+            .map((m) => line(m.guest, m.host, ' (another project in this sandbox)')),
+        // Projects started from other folders while this sandbox runs: every agent here can see them.
+        ...projects
+            .filter((p) => !roots.some((r) => within(r.guest, p.guest)) && !within(workspace, p.guest))
+            .map((p) => line(p.guest, p.host, ' (another project in this sandbox; your own is `%AGENT_WORKSPACE%`)')),
+    ];
+}
+/**
+ * The tools: one line for the launch folder's project; with other projects in the sandbox each line names its project
+ * (a project that has not been set up yet is not listed: its tools are decided from its own files).
+ */
+export function toolLines(primaryName, toolSummary, projects) {
+    const others = projects.filter((p) => p.tools?.length && p.name && p.name !== primaryName);
+    if (!others.length)
+        return ['- Tools: ' + toolSummary.join(' · ')];
+    return [
+        '- Tools (' + primaryName + '): ' + toolSummary.join(' · '),
+        ...others.map((p) => '- Tools (' + p.name + '): ' + p.tools.join(' · ')),
+        "- Tools by project: each project gets the tools its own files ask for; python and rust already installed here are on every project's PATH.",
+    ];
+}

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

@@ -1,8 +1,5 @@
+import { type GuideProject } from './guide-lines.js';
 /** 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[], 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

@@ -6,6 +6,7 @@ import { claudeDir, session, stateDir, workspace } from '../runtime/session.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';
+import { projectFolderLines, toolLines } from './guide-lines.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). */
@@ -22,18 +23,15 @@ const mirrorLine = () => {
             '`; real-path tools may print that form).',
     ];
 };
+/** Folders mapped for other projects at boot; launch folders from before mappedProjects only list the guest side. */
+const mappedFolders = () => session.mappedProjects ?? (session.roots ?? []).map((guest) => ({ host: 'a folder on the PC', guest }));
+/** Deliberately tiny: it is loaded into every conversation. */
 export function sandboxGuide(toolSummary, lan = 'blocked', projects = [], addons = []) {
     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%`)'),
+        ...projectFolderLines(workspace, session.workspaceHost, mappedFolders(), projects),
         '- RW, persists: `' +
             toolsDir +
             '` (toolchains) — put portable exes in `' +
@@ -46,7 +44,7 @@ export function sandboxGuide(toolSummary, lan = 'blocked', projects = [], addons
             '`',
         '- RO: `' + launchDir + "` (this boot's scripts) · lost on close: everything else, incl. `C:\\nvm` (Node symlink)",
         ...mirrorLine(),
-        '- Tools: ' + toolSummary.join(' · '),
+        ...toolLines(session.project, toolSummary, projects),
         // 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).',