windows-development-sandbox 1.1.0 → 1.4.1

package/dist/host/generate.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { decideToolchains, resolveToolchains } from '../core/detect-toolchains.js';
 import { readPwshScripts, usesPwsh } from '../core/detect-pwsh.js';
+import { widenForProjects } from '../core/project-policy.js';
 import { dirExists, ensureDir, fail, writeJson } from '../core/util.js';
 import { substDrives } from '../shared/guest-paths.js';
 import { PROJECTS_GUEST, hubName } from '../shared/projects.js';
@@ -37,7 +38,18 @@ const hostToolsOf = (probe) => ({
     volta: Boolean(probe.volta),
     pyenv: Boolean(probe.pyenv),
 });
-export const generateSandbox = (o) => {
+/**
+ * env.cmd, which logon.cmd calls before it opens Windows Terminal: Terminal expands "%AGENT_WORKSPACE%" (the starting
+ * folder of new tabs) from its own environment, and the runtime only sets the variable machine-wide after Terminal
+ * started. `%` is doubled for cmd; a Windows path holds no quotes.
+ */
+export const logonEnv = (workspace) => '@set "AGENT_WORKSPACE=' + workspace.replace(/[\r\n"]/g, '').replace(/%/g, '%%') + '"\r\n';
+export const generateSandbox = (given) => {
+    // Several projects at boot: the sandbox also gets what the others want and you allowed (core/project-policy.ts).
+    const others = given.bootWants?.projects ?? [];
+    const boot = planBootProjects({ run: given.run, packageRoot: given.packageRoot, extraProjects: given.extraProjects, knownProjects: given.knownProjects });
+    const wide = widenForProjects(given.run.config, others, { keepOff: given.bootWants?.keepOff, exists: dirExists });
+    const o = { ...given, run: { ...given.run, config: wide.config } };
     const { config, dataPath, workspaceHost, harnessName, storageRoot } = o.run;
     const harness = harnessName === 'none' ? null : config.harnesses[harnessName] ?? fail('Unknown agent: ' + harnessName, 'Configured agents: ' + Object.keys(config.harnesses).join(', '));
     if (!dirExists(workspaceHost))
@@ -45,13 +57,13 @@ export const generateSandbox = (o) => {
     assertTestWritable(storageRoot);
     assertTestWritable(dataPath);
     // Checked before anything is written, so a refusal leaves nothing behind.
-    const memoryMb = resolveMemoryMb(config.sandbox, o.freeMemoryBytes);
+    const memoryMb = Math.max(resolveMemoryMb(config.sandbox, o.freeMemoryBytes), ...others.map((p) => typeof p.config.sandbox.memoryMb === 'number' ? p.config.sandbox.memoryMb : 0));
     const launchId = Date.now() + '-' + crypto.randomBytes(3).toString('hex');
     const launchPath = path.join(storageRoot, 'launches', launchId);
     ensureDir(launchPath);
     ensureDir(dataPath);
-    const boot = planBootProjects({ run: o.run, packageRoot: o.packageRoot, extraProjects: o.extraProjects, knownProjects: o.knownProjects });
-    const mappings = collectMappings(o, launchPath, boot);
+    const mappingNotes = [];
+    const mappings = collectMappings(o, launchPath, boot, mappingNotes);
     const profile = harnessName === 'claude' ? stageClaudeProfile(config.claudeProfile, launchPath, workspaceHost, config.secrets) : NO_PROFILE;
     stageGitIdentity(launchPath);
     const personalization = config.personalization.enabled ? capturePersonalization(launchPath) : 'disabled';
@@ -64,7 +76,8 @@ export const generateSandbox = (o) => {
         workspace: config.guestWorkspace,
         workspaceHost,
         projectsDir: PROJECTS_GUEST,
-        roots: boot.roots.map((r) => r.guest),
+        // Every folder mapped for other projects (roots and projects mapped at boot): the guest accepts projects in them.
+        roots: [...boot.roots, ...boot.projects].map((r) => r.guest),
         ...(o.autoSession === false ? { autoSession: false } : {}),
         harnessName,
         harness,
@@ -87,12 +100,16 @@ export const generateSandbox = (o) => {
         personalization: fs.existsSync(path.join(launchPath, 'personalize', 'personalize.reg')),
         substDrives: substDrives(mappings.map((m) => m.guest)),
         cpuLimitPercent: config.sandbox.cpuLimit === 'none' ? null : config.sandbox.cpuLimit,
+        pageFileMb: config.sandbox.pageFileMb,
+        apps: config.apps,
+        auditProcesses: config.audit.enabled && config.audit.processes,
     };
     const sessionPath = path.join(launchPath, 'session.json');
     writeJson(sessionPath, session);
+    fs.writeFileSync(path.join(launchPath, 'env.cmd'), logonEnv(session.workspace), 'utf8');
     copyRuntime(o.packageRoot, launchPath);
     stageHooks(o.packageRoot, launchPath, o.run.scripts);
     const wsbPath = path.join(launchPath, 'agent.wsb');
     fs.writeFileSync(wsbPath, buildWsb(config, memoryMb, mappings), 'utf8');
-    return { wsbPath, launchPath, launchId, sessionPath, memoryMb, mappings, profile, personalization, databases, toolchains: toolchainDecisions, projects: boot };
+    return { wsbPath, launchPath, launchId, sessionPath, memoryMb, bootConfig: config, widened: wide.widened, mappings, profile, personalization, databases, toolchains: toolchainDecisions, projects: { ...boot, notes: [...boot.notes, ...wide.notes] }, mappingNotes };
 };

package/dist/host/join.d.ts

@@ -1,4 +1,5 @@
 import type { ResolvedRun } from '../core/types.js';
+import { type Missing } from '../core/project-policy.js';
 import { type ProjectSpecT } from '../shared/schema.js';
 import { type ProjectMapper, type RegistryEntry } from './projects.js';
 /** The launch folder of the running sandbox (host-only storage; its id comes from the guest, so it is checked). */
@@ -10,7 +11,11 @@ export interface Joined {
     spec: ProjectSpecT | null;
     run: ResolvedRun | null;
     notes: string[];
+    /** What it wants at boot that the running sandbox started without (it joined without them). */
+    missing: Missing | null;
 }
+/** What to do when a joining project wants something the running sandbox started without. */
+export type MissingChoice = 'continue' | 'restart' | 'cancel';
 /** The project spec the guest provisions from (scans the project folder like a launch does). */
 export declare const projectSpec: (run: ResolvedRun, entry: RegistryEntry, hooks: boolean) => ProjectSpecT;
 /**
@@ -25,4 +30,6 @@ export declare const joinRunning: (o: {
     wsbShare: boolean;
     resolve: (projectRoot: string) => Promise<ResolvedRun>;
     mapper?: ProjectMapper;
+    /** Asked before anything is registered when something is missing (default: continue without it). */
+    decide?: (name: string, missing: Missing) => Promise<MissingChoice>;
 }) => Promise<Joined>;

package/dist/host/join.js

@@ -2,18 +2,20 @@
 // resolve it (its approved .sandbox-config.json, versions, toolchain detection, database plan), checked against the
 // running sandbox's machine-wide protections, made visible inside (host/projects.ts: a project root, a project
 // mapped at boot, or wsb share) and described to the guest, which provisions what is missing before its session.
-// When none of those can make it visible, NeedsRestart reaches the caller, which offers a restart.
+// When none of those can make it visible, NeedsRestart reaches the caller, which offers a restart. So does a project
+// that wants what the sandbox only gets at its start (a .wsb device, more memory, its mappings) when you choose to
+// restart for it; otherwise it joins without them and they are named.
 import fs from 'node:fs';
 import path from 'node:path';
-import { checkJoin, protectionsOf } from '../core/project-policy.js';
+import { checkJoin, missingAtBoot, nothingMissing, protectionsOf } from '../core/project-policy.js';
 import { resolveToolchains } from '../core/detect-toolchains.js';
-import { assertNoLinks, fail } from '../core/util.js';
+import { assertNoLinks, dirExists, fail } from '../core/util.js';
 import { Id } from '../shared/schema.js';
 import { readSandboxStatus } from '../shared/rundir.js';
 import { syncProjectIn } from '../sync/watcher.js';
 import { planDatabases } from './database-plan.js';
 import { decideProjectToolchains } from './generate.js';
-import { projectHere, projectMapper, readRegistry, rememberProject, rootHere } from './projects.js';
+import { bootRecordOf, NeedsRestart, projectHere, projectMapper, readRegistry, rememberProject, rootHere } from './projects.js';
 import { stageScripts } from './launch/stage.js';
 import { addRepoSnapshot } from './repo-guard.js';
 /** The launch folder of the running sandbox (host-only storage; its id comes from the guest, so it is checked). */
@@ -44,15 +46,27 @@ export const projectSpec = (run, entry, hooks) => {
 export const joinRunning = async (o) => {
     const here = projectHere(o.storageRoot, o.hostDir);
     if (here?.project.primary)
-        return { ...here, spec: null, run: null, notes: [] };
+        return { ...here, spec: null, run: null, notes: [], missing: null };
     const registry = readRegistry(o.storageRoot) ?? fail('The running sandbox was started by an older version, so it cannot take another folder.', 'Stop it (sandbox stop) and start it again.');
     // A folder below a project already in the sandbox uses that project; anything else becomes a project of its own.
     const root = here?.project.host ?? path.resolve(o.hostDir);
     const run = await o.resolve(root);
-    const check = checkJoin(registry.protections, protectionsOf(run.config));
+    const check = checkJoin(registry.protections, protectionsOf(run.config), Object.keys(registry.atBoot?.widened ?? {}));
     if (check.stricter.length) {
         fail('This project needs stricter protection than the running sandbox has, and those settings are machine-wide:\n  ' + check.stricter.join('\n  '), 'Its sessions cannot get them without changing them for the sessions already running. Stop the sandbox (sandbox stop) and start it from ' + root + '.');
     }
+    // Boot-only wishes (a .wsb device you allowed for it, more memory, its mappings) the running sandbox lacks.
+    const launchPath = runningLaunchPath(o.storageRoot, o.dataPath);
+    const boot = bootRecordOf(o.storageRoot, launchPath);
+    const found = boot ? missingAtBoot(registry.protections, boot, run.config, dirExists) : null;
+    const missing = found && !nothingMissing(found) ? found : null;
+    if (missing) {
+        const choice = o.decide ? await o.decide(here?.project.name ?? path.basename(root), missing) : 'continue';
+        if (choice === 'cancel')
+            fail('Cancelled: nothing changed.');
+        if (choice === 'restart')
+            throw new NeedsRestart(root, 'it wants what the sandbox only gets at its start', missing);
+    }
     const mapper = o.mapper ?? projectMapper({ storageRoot: o.storageRoot, packageRoot: o.packageRoot, wsbShare: o.wsbShare });
     // Guarded from now on. A folder the sandbox could already write (inside a root, or mapped at boot) and that has no
     // snapshot from the launch gets an empty one: what is there now may have been planted, so it counts as new.
@@ -60,7 +74,6 @@ export const joinRunning = async (o) => {
     addRepoSnapshot(o.dataPath, root, { empty: Boolean(here) || Boolean(rootHere(o.storageRoot, root)) });
     const entry = mapper.register(root);
     rememberProject(o.storageRoot, entry.host);
-    const launchPath = runningLaunchPath(o.storageRoot, o.dataPath);
     // Your hooks in ~/.agent-sandbox/hooks ran at boot (once per sandbox); the project's own scripts ("scripts" in its
     // .sandbox-config.json, --script) run before its first agent. The launch folder is read-only for the sandbox, but
     // this side can still add them to it.
@@ -71,6 +84,7 @@ export const joinRunning = async (o) => {
         syncProjectIn(o.dataPath, { hostWorkspace: entry.host, guestWorkspace: entry.guest });
     }
     catch { /* history is a convenience; never block the session */ }
-    const notes = [...run.notes, ...check.looser.map((l) => 'The running sandbox is stricter: ' + l + '.')];
-    return { project: entry, guestDir: here ? here.guestDir : entry.guest, spec: projectSpec(run, entry, hooks), run, notes };
+    const notes = [...run.notes, ...check.looser.map((l) => 'The running sandbox is stricter: ' + l + '.'),
+        ...check.shared.map((s) => s + ' is on in this sandbox for another of its projects (you allowed it there); this project shares it.')];
+    return { project: entry, guestDir: here ? here.guestDir : entry.guest, spec: projectSpec(run, entry, hooks), run, notes, missing };
 };

package/dist/host/launch/mappings.d.ts

@@ -1,3 +1,8 @@
 import type { GenerateOptions, ResolvedMapping } from '../../core/types.js';
-import type { BootProjects } from './projects.js';
-export declare const collectMappings: (o: GenerateOptions, launchPath: string, boot?: BootProjects) => ResolvedMapping[];
+import { type BootProjects } from './projects.js';
+/**
+ * Every mapping, placed. Your extra folders never stop a launch because of their guest path: one the sandbox cannot
+ * use (reserved, invalid, or already in use) goes to C:\Mapped\<drive>\<path>, and `notes` says where and why. What
+ * does stop it (a folder that is not there, a whole drive, this tool's own folders) is listed in one message.
+ */
+export declare const collectMappings: (o: GenerateOptions, launchPath: string, boot?: BootProjects, notes?: string[]) => ResolvedMapping[];

package/dist/host/launch/mappings.js

@@ -1,34 +1,84 @@
+// Which folders are mapped into the sandbox: the launch folder, the data folder, the workspace, your extra folders and
+// the tools copied from this PC. Everything is checked before it can reach the .wsb.
+import path from 'node:path';
 import { assertNoGuestOverlap } from '../../core/config.js';
 import { assertSafeMapping } from '../../core/safe-paths.js';
-import { dirExists, fail } from '../../core/util.js';
-import { isValidGuestPath, sandboxFolder } from '../../shared/guest-paths.js';
+import { dirExists, errMsg, fail, isInsideOrEqual, UserError } from '../../core/util.js';
+import { shownByRoot } from './projects.js';
+import { deriveGuest, isValidGuestPath, placeGuest, sandboxFolder, tidyGuestPath } from '../../shared/guest-paths.js';
+import { PROJECTS_GUEST } from '../../shared/projects.js';
 import { GUEST } from './wsb.js';
-export const collectMappings = (o, launchPath, boot = { roots: [], projects: [], notes: [] }) => {
+import { guestGitDir, planView } from '../workspace-view/index.js';
+/**
+ * Every mapping, placed. Your extra folders never stop a launch because of their guest path: one the sandbox cannot
+ * use (reserved, invalid, or already in use) goes to C:\Mapped\<drive>\<path>, and `notes` says where and why. What
+ * does stop it (a folder that is not there, a whole drive, this tool's own folders) is listed in one message.
+ */
+export const collectMappings = (o, launchPath, boot = { roots: [], projects: [], notes: [] }, notes = []) => {
     const { config, dataPath, workspaceHost, harnessName } = o.run;
     assertGuestPath(config.guestWorkspace, 'guestWorkspace');
+    // workspaceFilter: the sandbox gets the project's filtered view (no git-ignored files) and its real .git beside it.
+    const view = planView(config, o.run.storageRoot, workspaceHost);
+    // A launch folder inside a project root is shown by the root, at the place it has whichever project starts the sandbox.
+    const inRoot = !view && shownByRoot(boot.roots, workspaceHost, config.guestWorkspace);
     const mappings = [
         { host: launchPath, guest: GUEST.launch, readOnly: true },
         { host: dataPath, guest: GUEST.data, readOnly: false },
-        { host: workspaceHost, guest: config.guestWorkspace, readOnly: config.readOnly },
+        ...(inRoot ? [] : [{ host: view ? view.options.view : workspaceHost, guest: config.guestWorkspace, readOnly: config.readOnly }]),
+        ...(view?.hostGit ? [{ host: view.hostGit, guest: guestGitDir(config.guestWorkspace), readOnly: config.readOnly }] : []),
     ];
+    // Project roots and other projects, so they can join the running sandbox without a restart (launch/projects.ts).
+    const projects = [];
+    for (const m of [...boot.roots, ...boot.projects]) {
+        assertGuestPath(m.guest, 'project folder for ' + m.host);
+        projects.push({ host: m.host, guest: m.guest, readOnly: false });
+    }
+    const taken = [
+        { guest: config.guestWorkspace, what: 'the project' },
+        ...(view?.hostGit ? [{ guest: guestGitDir(config.guestWorkspace), what: 'the project\'s .git' }] : []),
+        { guest: PROJECTS_GUEST, what: 'the other projects' },
+        ...projects.map((p) => ({ guest: p.guest, what: p.host })),
+    ];
+    const outside = new Set((o.run.outsideMappings ?? []).map((h) => path.resolve(h).toLowerCase()));
+    const problems = [];
+    const missing = [];
+    const extra = [];
     for (const m of config.mappings) {
         const host = m.host;
-        assertGuestPath(m.guest, 'mappings[].guest for ' + host);
         if (!dirExists(host)) {
-            if (m.optional) {
-                console.warn('Skipping optional mapping (folder not found): ' + host);
-                continue;
-            }
-            fail('A mapped folder does not exist: ' + host, 'Create it, fix the path in your config, or mark the mapping "optional": true.');
+            if (m.optional)
+                missing.push(host);
+            else
+                problems.push(host + ': the folder does not exist. Fix: create it, correct the path, or mark the mapping "optional": true.');
+            continue;
         }
-        assertSafeMapping(host, o.packageRoot, o.run.storageRoot);
-        mappings.push({ host, guest: m.guest, readOnly: m.readOnly });
-    }
-    // Project roots and other projects, so they can join the running sandbox without a restart (launch/projects.ts).
-    for (const m of [...boot.roots, ...boot.projects]) {
-        assertGuestPath(m.guest, 'project folder for ' + m.host);
-        mappings.push({ host: m.host, guest: m.guest, readOnly: false });
+        try {
+            assertSafeMapping(host, o.packageRoot, o.run.storageRoot);
+        }
+        catch (e) {
+            problems.push(errMsg(e) + (e instanceof UserError && e.fix ? ' Fix: ' + e.fix : ''));
+            continue;
+        }
+        // A folder inside the project with no guest path of its own is already there (unless the filtered view hides it).
+        if (!m.guest && !view && isInsideOrEqual(workspaceHost, host)) {
+            notes.push(host + ' is inside the project, so it is already in the sandbox at ' + deriveGuest(host, workspaceHost, config.guestWorkspace) + '.');
+            continue;
+        }
+        const wanted = tidyGuestPath(m.guest ?? deriveGuest(host, workspaceHost, config.guestWorkspace));
+        // The same folder at the same place twice (your settings and the project file): once is enough.
+        if (extra.some((x) => x.host.toLowerCase() === host.toLowerCase() && x.guest.toLowerCase() === wanted.toLowerCase()))
+            continue;
+        const placed = placeGuest(host, wanted, [...taken, ...extra.map((x) => ({ guest: x.guest, what: x.host }))]);
+        if (placed.note)
+            notes.push(placed.note);
+        const label = outside.has(path.resolve(host).toLowerCase()) ? 'outside the project, allowed' : undefined;
+        extra.push({ host, guest: placed.guest, readOnly: m.readOnly, ...(label ? { label } : {}) });
     }
+    if (problems.length)
+        fail((problems.length === 1 ? 'A mapped folder cannot be used:\n  ' : problems.length + ' mapped folders cannot be used:\n  ') + problems.join('\n  '));
+    if (missing.length)
+        notes.push('Skipped ' + (missing.length === 1 ? 'an optional folder' : missing.length + ' optional folders') + ' not on this PC: ' + missing.join(', '));
+    mappings.push(...extra, ...projects);
     const { probe } = o;
     if (probe.nodeDir)
         mappings.push({ host: probe.nodeDir, guest: GUEST.hostTools + '\\node', readOnly: true });
@@ -38,8 +88,8 @@ export const collectMappings = (o, launchPath, boot = { roots: [], projects: [],
         mappings.push({ host: probe.gitDir, guest: GUEST.hostTools + '\\git', readOnly: true });
     if (probe.nvmDir)
         mappings.push({ host: probe.nvmDir, guest: GUEST.hostTools + '\\nvm', readOnly: true });
+    // Placement keeps extra folders apart; this guards the rest (and where the folders really are: F:\x is C:\Mirror\F\x).
     assertNoGuestOverlap(mappings);
-    // Same check on where the folders really are (F:\x and C:\Mirror\F\x are one place).
     assertNoGuestOverlap(mappings.map((m) => ({ guest: sandboxFolder(m.guest) })));
     return mappings;
 };

package/dist/host/launch/projects.d.ts

@@ -13,3 +13,5 @@ export declare const planBootProjects: (o: {
     extraProjects?: string[];
     knownProjects?: string[];
 }) => BootProjects;
+/** The launch folder is inside a mapped root and placed under it (core/workspace.ts): the root shows it, no own mapping. */
+export declare const shownByRoot: (roots: RootMapping[], workspaceHost: string, guestWorkspace: string) => boolean;

package/dist/host/launch/projects.js

@@ -4,7 +4,7 @@
 import path from 'node:path';
 import { assertSafeMapping, assertSafeWorkspace } from '../../core/safe-paths.js';
 import { dirExists, errMsg, fail } from '../../core/util.js';
-import { isWithin, planProjectMappings } from '../../shared/projects.js';
+import { guestDirFor, isWithin, planProjectMappings, projectForHostDir, usableRoots } from '../../shared/projects.js';
 import { allProjectsToMap, readKnown } from '../projects.js';
 /** More folders than this would make the .wsb (and every boot) unwieldy; the rest join with a restart later. */
 export const MAX_BOOT_PROJECTS = 48;
@@ -21,7 +21,6 @@ export const planBootProjects = (o) => {
             return errMsg(e);
         }
     };
-    const roots = [];
     for (const root of config.projects.roots.map((r) => path.resolve(r))) {
         if (!dirExists(root)) {
             notes.push('Project root not found, skipped: ' + root);
@@ -30,9 +29,9 @@ export const planBootProjects = (o) => {
         const refusal = safe(root);
         if (refusal)
             fail('projects.roots: ' + refusal, 'Use a folder that holds your projects, e.g. F:\\Code (not a drive, your profile or a system folder).');
-        if (!roots.some((r) => isWithin(r, root)))
-            roots.push(root);
     }
+    // The same list resolveRun used to place a launch folder that is inside a root (core/workspace.ts).
+    const roots = usableRoots(config.projects.roots, dirExists);
     const known = o.knownProjects ?? readKnown(storageRoot).map((k) => k.host);
     const wanted = [...(o.extraProjects ?? []), ...(config.projects.all ? allProjectsToMap(known, { primary: workspaceHost, roots, exclude: config.projects.exclude }) : [])];
     const projects = [];
@@ -52,5 +51,12 @@ export const planBootProjects = (o) => {
         }
         projects.push(folder);
     }
-    return { ...planProjectMappings(roots, projects, Boolean(o.run.mirror)), notes };
+    // Projects mapped on their own sit where they would as the launch folder (C:\Workspace\<name>), never on top of it.
+    const taken = [config.guestWorkspace, ...config.mappings.flatMap((m) => (m.guest ? [m.guest] : []))];
+    return { ...planProjectMappings(roots, projects, Boolean(o.run.mirror), taken), notes };
+};
+/** The launch folder is inside a mapped root and placed under it (core/workspace.ts): the root shows it, no own mapping. */
+export const shownByRoot = (roots, workspaceHost, guestWorkspace) => {
+    const root = projectForHostDir(roots, workspaceHost);
+    return root !== null && guestDirFor(root, workspaceHost).toLowerCase() === guestWorkspace.replace(/[\\/]+$/, '').toLowerCase();
 };

package/dist/host/launch/stage.js

@@ -25,7 +25,7 @@ export const stageScripts = (target, scripts) => {
         fs.copyFileSync(script, path.join(target, '90-extra-' + index + '-' + path.basename(script)));
     });
 };
-export const RUNTIME_FILES = ['main.js', 'daemon.js', 'view.js', 'gitguard.js', 'db.js'];
+export const RUNTIME_FILES = ['main.js', 'daemon.js', 'view.js', 'gitguard.js', 'db.js', 'netproxy.js'];
 /** The bundled sandbox runtime (dist/runtime: one self-contained file per entry point) and the sandbox/ scripts. */
 export const copyRuntime = (packageRoot, launchPath) => {
     const runtime = path.join(packageRoot, 'dist', 'runtime');

package/dist/host/motw.d.ts

@@ -0,0 +1,17 @@
+/** What Windows runs when you open it (not source files such as .js or .py: those need a program you choose). */
+export declare const RISKY: RegExp;
+/** Marks one file if it is a program or script (and a plain file, not a link). Returns true when it marked it. */
+export declare const markFromSandbox: (file: string) => boolean;
+/** Has this file the mark? */
+export declare const isMarked: (file: string) => boolean;
+/** Watches the projects while the sandbox runs and marks what appears or changes; returns a function that stops it. */
+export declare const watchAndMark: (projects: string[], note?: (message: string) => void) => (() => void);
+/** The projects to watch and mark (empty: storage.markSandboxFiles is off). */
+export declare const saveMarkedProjects: (storageRoot: string, dataPath: string, projects: string[]) => void;
+export declare const readMarkedProjects: (storageRoot: string, dataPath: string) => string[];
+/** The data folder's size, measured by the watcher when a sandbox closes (measuring at launch would be slow). */
+export declare const saveDataSize: (storageRoot: string, dataPath: string, bytes: number) => void;
+export declare const readDataSize: (storageRoot: string, dataPath: string) => {
+    bytes: number;
+    at: string;
+} | null;

package/dist/host/motw.js

@@ -0,0 +1,74 @@
+// storage.markSandboxFiles: programs and scripts that appear or change in a project while a sandbox runs get Windows'
+// "downloaded from the internet" mark (the Zone.Identifier stream, zone 3). Running one on this PC then goes through
+// SmartScreen, and PowerShell's RemoteSigned policy refuses an unsigned marked script. So something an agent planted is
+// not run by a double-click or a habit. Runs in the background watcher; only the mark is written, never the file.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { readValid, writeJsonAtomic } from '../shared/rundir.js';
+/** What Windows runs when you open it (not source files such as .js or .py: those need a program you choose). */
+export const RISKY = /\.(exe|dll|com|scr|pif|msi|msix|msp|appx|appxbundle|bat|cmd|ps1|psm1|psd1|vbs|vbe|wsf|wsh|hta|lnk|url|jar|reg|cpl|application|gadget|chm)$/i;
+const MARK = '[ZoneTransfer]\r\nZoneId=3\r\nHostUrl=about:windows-development-sandbox\r\n';
+/** Folders not worth watching closely (git's own files; dependency and build folders are still marked). */
+const SKIP = /(^|[\\/])\.git([\\/]|$)/i;
+/** Marks one file if it is a program or script (and a plain file, not a link). Returns true when it marked it. */
+export const markFromSandbox = (file) => {
+    if (!RISKY.test(file) || SKIP.test(file))
+        return false;
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile())
+            return false;
+        fs.writeFileSync(file + ':Zone.Identifier', MARK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Has this file the mark? */
+export const isMarked = (file) => {
+    try {
+        return fs.readFileSync(file + ':Zone.Identifier', 'utf8').includes('ZoneId=3');
+    }
+    catch {
+        return false;
+    }
+};
+/** Watches the projects while the sandbox runs and marks what appears or changes; returns a function that stops it. */
+export const watchAndMark = (projects, note = () => undefined) => {
+    const pending = new Set();
+    let timer;
+    const flush = () => {
+        timer = undefined;
+        const marked = [...pending].filter(markFromSandbox);
+        pending.clear();
+        if (marked.length)
+            note('marked as from the sandbox (SmartScreen asks before they run here): ' + marked.slice(0, 10).map((f) => path.basename(f)).join(', ') + (marked.length > 10 ? ' and ' + (marked.length - 10) + ' more' : ''));
+    };
+    const watchers = projects.flatMap((project) => {
+        try {
+            return [fs.watch(project, { recursive: true }, (_event, file) => {
+                    const rel = file ? String(file) : '';
+                    if (!rel || !RISKY.test(rel) || SKIP.test(rel))
+                        return;
+                    pending.add(path.join(project, rel));
+                    timer ??= setTimeout(flush, 1000);
+                })];
+        }
+        catch {
+            return [];
+        }
+    });
+    return () => { watchers.forEach((w) => w.close()); clearTimeout(timer); if (pending.size)
+        flush(); };
+};
+// ---- what the watcher marks, and the size of the persisted data (host-only files next to the sync state) ----------
+const marksFile = (storageRoot, dataPath) => path.join(storageRoot, 'sync', path.basename(dataPath) + '-mark.json');
+const sizeFile = (storageRoot, dataPath) => path.join(storageRoot, 'sync', path.basename(dataPath) + '-size.json');
+/** The projects to watch and mark (empty: storage.markSandboxFiles is off). */
+export const saveMarkedProjects = (storageRoot, dataPath, projects) => writeJsonAtomic(marksFile(storageRoot, dataPath), projects);
+export const readMarkedProjects = (storageRoot, dataPath) => readValid(z.array(z.string().max(1024)).max(64), marksFile(storageRoot, dataPath)) ?? [];
+/** The data folder's size, measured by the watcher when a sandbox closes (measuring at launch would be slow). */
+export const saveDataSize = (storageRoot, dataPath, bytes) => writeJsonAtomic(sizeFile(storageRoot, dataPath), { bytes, at: new Date().toISOString() });
+export const readDataSize = (storageRoot, dataPath) => readValid(z.object({ bytes: z.number().min(0), at: z.string().max(40) }), sizeFile(storageRoot, dataPath));

package/dist/host/platform.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { SYSTEM } from '../shared/system.js';
 import { refuseInSelfTest } from './test-guard.js';
+import { updateRestartPending } from './stops.js';
 import { commandsDir, realAgent } from './agent-commands.js';
 import { dirExists, ensureDir, fail, fileExists, findOnPath, homeDir, isWin, realPath } from '../core/util.js';
 const findHarnessExe = (config, harnessName) => {
@@ -116,6 +117,8 @@ export const doctorRows = (config, harnessName, storageRoot, configPath) => {
         ['Windows Sandbox feature', sandboxFeatureInstalled() ? 'enabled' : 'NOT enabled'],
         ['Sandbox running', isSandboxRunning() ? 'YES' : 'no'],
         ['Free host RAM (MB)', String(Math.floor(os.freemem() / 1048576))],
+        ['Update restart pending', updateRestartPending() ? 'YES (Windows may restart on its own and close the sandbox; restart first or pause updates)' : 'no'],
+        ['Keep this PC awake', config.sandbox.keepAwake ? 'yes, while a sandbox runs' : 'no (sandbox.keepAwake is off: the PC may sleep under running agents)'],
         ['Provisioning', config.provisioning.copyFromHost ? 'copy from this PC' + (config.provisioning.fallbackToInstall ? ', fall back to download' : ', no fallback') : 'download inside sandbox'],
         ['Host Node (runner)', probe.nvmNode ? 'nvm ' + probe.hostNodeVersion : probe.nodeDir ?? '(none; will download)'],
         ['Host nvm versions', probe.nvmDir ?? '(no NVM_HOME; versions will be downloaded)'],

package/dist/host/port-forward.d.ts

@@ -0,0 +1,8 @@
+import { type PortForward } from '../shared/netpolicy.js';
+/** Host-only: the forwards of the running sandbox (written at launch, read by the watcher). */
+export declare const saveForwards: (storageRoot: string, dataPath: string, forwards: PortForward[]) => void;
+export declare const readForwards: (storageRoot: string, dataPath: string) => PortForward[];
+/** The sandbox's address on this PC's Hyper-V network, from its status (null until it has one). */
+export declare const sandboxAddress: (dataPath: string) => string | null;
+/** Starts one listener per forward; returns a function that stops them. */
+export declare const startPortForwards: (forwards: PortForward[], address: () => string | null, note?: (message: string) => void) => (() => void);

package/dist/host/port-forward.js

@@ -0,0 +1,37 @@
+// network.forwardPorts, PC side: http://localhost:<pc> on this PC reaches <sandbox> inside the sandbox while it runs.
+// Runs in the background watcher. Listens on 127.0.0.1 only (nothing else on your network can use it), and connects
+// only to an address the sandbox published that is on this PC's Hyper-V network (isSandboxAddress). Bytes are passed
+// through, never looked at. No admin rights needed (no netsh portproxy).
+import net from 'node:net';
+import path from 'node:path';
+import { z } from 'zod';
+import { relayPort } from '../shared/netpolicy.js';
+import { readSandboxStatus, readValid, writeJsonAtomic } from '../shared/rundir.js';
+import { isSandboxAddress } from './attach.js';
+const Forwards = z.array(z.object({ pc: z.number().int().min(1).max(65535), sandbox: z.number().int().min(1).max(65535) })).max(64);
+const forwardsFile = (storageRoot, dataPath) => path.join(storageRoot, 'sync', path.basename(dataPath) + '-forwards.json');
+/** Host-only: the forwards of the running sandbox (written at launch, read by the watcher). */
+export const saveForwards = (storageRoot, dataPath, forwards) => writeJsonAtomic(forwardsFile(storageRoot, dataPath), forwards);
+export const readForwards = (storageRoot, dataPath) => readValid(Forwards, forwardsFile(storageRoot, dataPath)) ?? [];
+/** The sandbox's address on this PC's Hyper-V network, from its status (null until it has one). */
+export const sandboxAddress = (dataPath) => readSandboxStatus(dataPath)?.addresses?.find((a) => isSandboxAddress(a)) ?? null;
+/** Starts one listener per forward; returns a function that stops them. */
+export const startPortForwards = (forwards, address, note = () => undefined) => {
+    const servers = forwards.map((f, i) => {
+        const server = net.createServer((client) => {
+            const ip = address();
+            if (!ip) {
+                client.destroy();
+                return;
+            }
+            const target = net.connect(relayPort(i), ip);
+            client.pipe(target).pipe(client);
+            target.on('error', () => client.destroy());
+            client.on('error', () => target.destroy());
+        });
+        server.on('error', (e) => note('localhost:' + f.pc + ' could not be forwarded' + (e.code === 'EADDRINUSE' ? ': something on this PC already uses that port' : ': ' + e.message)));
+        server.listen(f.pc, '127.0.0.1', () => note('localhost:' + f.pc + ' -> sandbox port ' + f.sandbox));
+        return server;
+    });
+    return () => servers.forEach((s) => s.close());
+};

package/dist/host/projects.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { Missing } from '../core/project-policy.js';
 import { PROJECTS_GUEST, type ProjectEntry, type RootMapping } from '../shared/projects.js';
 import { type Wsb } from './wsb.js';
 export { PROJECTS_GUEST };
@@ -36,7 +37,17 @@ declare const Registry: z.ZodObject<{
         }>;
         registeredAt: z.ZodString;
     }, z.core.$strict>>;
+    atBoot: z.ZodOptional<z.ZodObject<{
+        memoryMb: z.ZodNullable<z.ZodNumber>;
+        mappings: z.ZodArray<z.ZodObject<{
+            host: z.ZodString;
+            guest: z.ZodString;
+            readOnly: z.ZodBoolean;
+        }, z.core.$strict>>;
+        widened: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
+export type AtBoot = NonNullable<z.output<typeof Registry>['atBoot']>;
 export type RegistryEntry = z.output<typeof Entry>;
 export type ProjectRegistry = z.output<typeof Registry>;
 export declare const readRegistry: (storageRoot: string) => ProjectRegistry | null;
@@ -47,12 +58,24 @@ export declare const startRegistry: (storageRoot: string, o: {
     primary: RootMapping;
     roots: RootMapping[];
     boot: RootMapping[];
+    atBoot?: AtBoot;
 }) => RegistryEntry;
-/** Why a folder cannot join the running sandbox without a restart (the caller offers one). */
+/** Reads the memory and mapped folders back from a .wsb this tool wrote (host-only launch folder; bounded). */
+export declare const parseWsbBoot: (xml: string) => AtBoot;
+/**
+ * What the running sandbox booted with. A sandbox started by 1.4.0 or older has no record: it is read from the .wsb in
+ * its launch folder (host-only storage) and recorded. null when neither is there.
+ */
+export declare const bootRecordOf: (storageRoot: string, launchPath: string | null) => AtBoot | null;
+/**
+ * Why a folder cannot join the running sandbox without a restart (the caller offers one). With `missing`: it could
+ * join, but you chose to restart for what it wants at boot (core/project-policy.ts).
+ */
 export declare class NeedsRestart extends Error {
     readonly hostDir: string;
     readonly reason: string;
-    constructor(hostDir: string, reason: string);
+    readonly missing?: Missing | undefined;
+    constructor(hostDir: string, reason: string, missing?: Missing | undefined);
 }
 export interface ProjectMapper {
     /** The projects of the running sandbox (the launch folder first). */