windows-development-sandbox 0.0.0-stage → 1.1.0

package/dist/host/platform.d.ts

@@ -0,0 +1,19 @@
+import type { Config, HostProbe } from '../core/types.js';
+/** What can be copied from this PC instead of downloaded inside the sandbox. */
+export declare const probeHost: (config: Config, harnessName: string) => HostProbe;
+/**
+ * Running INSIDE a Windows Sandbox this tool started (its launch folder and data folder are mapped in): then the CLI
+ * talks to the sandbox it is in, through C:\\AgentData and loopback, instead of looking for one on a PC.
+ */
+export declare const insideSandbox: () => boolean;
+export declare const GUEST_DATA_DIR = "C:\\AgentData";
+export declare const isSandboxRunning: () => boolean;
+export declare const sandboxFeatureInstalled: () => boolean;
+export declare const assertCanLaunch: () => void;
+/** cmd.exe expands %VAR% and ^ even inside quotes, and a quote ends them: such a path could run something else. */
+export declare const assertCmdSafePath: (file: string) => void;
+export declare const startSandbox: (wsbPath: string) => void;
+/** Runs a detached copy of this CLI (used for the background history/claude-mem sync watcher). */
+export declare const spawnDetached: (entry: string, args: string[]) => void;
+export declare const hostClaude: (storageRoot: string, personal: boolean, args: string[]) => number;
+export declare const doctorRows: (config: Config, harnessName: string, storageRoot: string, configPath: string | null) => [string, string][];

package/dist/host/platform.js

@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import os from 'node:os';
+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 { commandsDir, realAgent } from './agent-commands.js';
+import { dirExists, ensureDir, fail, fileExists, findOnPath, homeDir, isWin, realPath } from '../core/util.js';
+const findHarnessExe = (config, harnessName) => {
+    const harness = config.harnesses[harnessName];
+    if (!harness?.hostExecutable)
+        return null;
+    const explicit = harness.hostDir && harness.hostDir !== 'auto' ? path.join(harness.hostDir, harness.hostExecutable) : null;
+    const found = explicit
+        ? (fileExists(explicit) ? explicit : null)
+        : findOnPath([harness.hostExecutable]) ?? [path.join(homeDir(), '.local', 'bin', harness.hostExecutable)].find(fileExists) ?? null;
+    if (!found)
+        return null;
+    const real = realPath(found);
+    return { dir: path.dirname(real), file: path.basename(real) };
+};
+/** Git for Windows root (the folder with cmd\git.exe and bin\bash.exe), from git on PATH. */
+const findGitRoot = () => {
+    const git = findOnPath(['git.exe']);
+    if (!git)
+        return null;
+    const root = path.resolve(path.dirname(realPath(git)), '..');
+    return fileExists(path.join(root, 'bin', 'bash.exe')) ? root : null;
+};
+/** What can be copied from this PC instead of downloaded inside the sandbox. */
+export const probeHost = (config, harnessName) => {
+    const nodeDir = isWin ? path.dirname(process.execPath) : null;
+    const copy = config.provisioning.copyFromHost;
+    const nvmHome = process.env.NVM_HOME;
+    const nvmDir = copy && nvmHome && dirExists(nvmHome) ? realPath(nvmHome) : null;
+    const hasNode = (dir) => fileExists(path.join(dir, 'node.exe')) && fileExists(path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js'));
+    // One source for Node: nvm's copy of this version when there is one, otherwise the Node folder itself.
+    const nvmNode = Boolean(nvmDir && hasNode(path.join(nvmDir, process.version)));
+    return {
+        nodeDir: copy && !nvmNode && nodeDir && hasNode(nodeDir) ? realPath(nodeDir) : null,
+        harnessExe: copy ? findHarnessExe(config, harnessName) : null,
+        gitDir: copy && config.provisioning.git.enabled ? findGitRoot() : null,
+        nvmDir,
+        hostNodeVersion: process.version,
+        nvmNode,
+        volta: Boolean(process.env.VOLTA_HOME),
+        pyenv: Boolean(process.env.PYENV ?? process.env.PYENV_ROOT ?? process.env.PYENV_HOME),
+    };
+};
+const SANDBOX_PROCESSES = ['WindowsSandboxClient.exe', 'WindowsSandboxRemoteSession.exe', 'WindowsSandbox.exe'];
+/**
+ * Running INSIDE a Windows Sandbox this tool started (its launch folder and data folder are mapped in): then the CLI
+ * talks to the sandbox it is in, through C:\\AgentData and loopback, instead of looking for one on a PC.
+ */
+export const insideSandbox = () => isWin && !process.env.AGENT_SANDBOX_HOST_ONLY && fs.existsSync('C:\\AgentLaunch\\session.json') && fs.existsSync('C:\\AgentData\\run');
+export const GUEST_DATA_DIR = 'C:\\AgentData';
+export const isSandboxRunning = () => {
+    if (!isWin)
+        return false;
+    if (insideSandbox())
+        return true;
+    const result = spawnSync(SYSTEM.tasklist(), ['/NH', '/FO', 'CSV'], { encoding: 'utf8', windowsHide: true });
+    const out = (result.stdout ?? '').toLowerCase();
+    return SANDBOX_PROCESSES.some((image) => out.includes('"' + image.toLowerCase() + '"'));
+};
+export const sandboxFeatureInstalled = () => isWin && fileExists(path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32', 'WindowsSandbox.exe'));
+export const assertCanLaunch = () => {
+    if (!isWin)
+        fail('Windows Sandbox only runs on Windows.', 'Use sandbox generate to only write the files.');
+    if (!sandboxFeatureInstalled())
+        fail('Windows Sandbox is not enabled on this PC.', 'Run in an admin PowerShell, then reboot: Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All  (needs Windows Pro, Enterprise or Education)');
+    if (isSandboxRunning())
+        fail('A Windows Sandbox is already running (Windows allows one at a time).', 'Attach to it with sandbox claude -t, show it with sbx-show, or shut it down with sandbox stop.');
+};
+/** cmd.exe expands %VAR% and ^ even inside quotes, and a quote ends them: such a path could run something else. */
+export const assertCmdSafePath = (file) => {
+    if (/[%"^\r\n]/.test(file))
+        fail('The storage folder path has a character that cannot be started safely: ' + file, 'Set storage.root to a folder without % " ^ in its path.');
+};
+export const startSandbox = (wsbPath) => {
+    refuseInSelfTest('start Windows Sandbox');
+    assertCmdSafePath(wsbPath);
+    const result = spawnSync(SYSTEM.cmd(), ['/d', '/c', 'start', '""', '"' + wsbPath + '"'], { stdio: 'inherit', windowsVerbatimArguments: true });
+    if (result.error)
+        throw result.error;
+};
+/** Runs a detached copy of this CLI (used for the background history/claude-mem sync watcher). */
+export const spawnDetached = (entry, args) => {
+    refuseInSelfTest('start background programs');
+    // cwd = the install folder: the caller's folder is the workspace, which the sandbox can write.
+    spawn(process.execPath, [entry, ...args], { cwd: path.dirname(entry), detached: true, stdio: 'ignore', windowsHide: true }).unref();
+};
+export const hostClaude = (storageRoot, personal, args) => {
+    refuseInSelfTest('run Claude Code on this PC');
+    // Never this tool's own forwarding command (agentCommands), which would start a sandbox instead.
+    const exe = realAgent('claude', commandsDir(storageRoot));
+    if (!exe)
+        fail('Claude Code is not installed on this PC (no claude.exe or claude.cmd on PATH).', 'Install it: npm install -g @anthropic-ai/claude-code');
+    const env = { ...process.env };
+    if (!personal) {
+        const profile = path.join(storageRoot, 'host', 'claude');
+        ensureDir(profile);
+        env.CLAUDE_CONFIG_DIR = profile;
+        console.warn('Host Claude is NOT sandboxed. Using separate profile: ' + profile + ' (pass --personal to use your normal one).');
+    }
+    const result = exe.toLowerCase().endsWith('.cmd') ? spawnSync(SYSTEM.cmd(), ['/d', '/c', exe, ...args], { stdio: 'inherit', env }) : spawnSync(exe, args, { stdio: 'inherit', env });
+    if (result.error)
+        throw result.error;
+    return result.status ?? 1;
+};
+export const doctorRows = (config, harnessName, storageRoot, configPath) => {
+    const probe = probeHost(config, harnessName);
+    return [
+        ['Config file', configPath ?? '(none; built-in defaults; create one with: sandbox config init)'],
+        ['Windows', isWin ? 'yes' : 'NO (launch needs Windows)'],
+        ['Windows Sandbox feature', sandboxFeatureInstalled() ? 'enabled' : 'NOT enabled'],
+        ['Sandbox running', isSandboxRunning() ? 'YES' : 'no'],
+        ['Free host RAM (MB)', String(Math.floor(os.freemem() / 1048576))],
+        ['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)'],
+        ['Host ' + harnessName, probe.harnessExe ? path.join(probe.harnessExe.dir, probe.harnessExe.file) : '(none; will npm install)'],
+        ['Host Git for Windows', probe.gitDir ?? '(none with bash; PortableGit will be downloaded)'],
+        ['Storage root', storageRoot + (dirExists(storageRoot) ? '' : ' (will be created)')],
+    ];
+};

package/dist/host/project-scan.d.ts

@@ -0,0 +1,7 @@
+import { type ProjectFile } from '../core/detect-databases.js';
+/** Manifest-type files in the project, up to 3 folders deep. Links are not followed (the workspace may be guest-written). */
+export declare const readProjectFiles: (root: string, depth?: number) => ProjectFile[];
+/** File names in the project and its direct sub-folders ("api/go.mod"), for toolchain detection. No links followed. */
+export declare const projectEntries: (root: string) => string[];
+/** Scripts in the project root or one folder down that set up MSVC (vcvars*.bat, vswhere): read with bounded effort. */
+export declare const msvcHint: (root: string) => string | undefined;

package/dist/host/project-scan.js

@@ -0,0 +1,89 @@
+// Reads a project the way detect-databases.ts and detect-toolchains.ts need it (only manifest/config files, bounded).
+import fs from 'node:fs';
+import path from 'node:path';
+import { INTERESTING_FILE } from '../core/detect-databases.js';
+const SKIP = /^(node_modules|\.git|\.hg|\.svn|vendor|target|bin|obj|dist|build|out|\.next|\.nuxt|\.venv|venv|env|__pycache__|\.gradle|\.idea|\.vs|coverage|packages)$/i;
+const MAX_FILES = 400;
+const MAX_BYTES = 256 * 1024;
+const MAX_FOLDERS = 2000;
+/** Reads a file through one handle, only if that handle is a regular file of at most MAX_BYTES. */
+const readSmallFile = (file) => {
+    let fd = null;
+    try {
+        fd = fs.openSync(file, 'r');
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || stat.size > MAX_BYTES)
+            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);
+    }
+};
+/** Manifest-type files in the project, up to 3 folders deep. Links are not followed (the workspace may be guest-written). */
+export const readProjectFiles = (root, depth = 3) => {
+    const files = [];
+    let folders = 0;
+    const walk = (dir, level) => {
+        if (++folders > MAX_FOLDERS)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (files.length >= MAX_FILES)
+                return;
+            const full = path.join(dir, entry.name);
+            if (entry.isFile() && INTERESTING_FILE.test(entry.name)) {
+                const text = readSmallFile(full);
+                if (text !== null)
+                    files.push({ path: path.relative(root, full), text });
+            }
+            else if (entry.isDirectory() && level < depth && !SKIP.test(entry.name))
+                walk(full, level + 1);
+        }
+    };
+    walk(root, 0);
+    return files;
+};
+/** File names in the project and its direct sub-folders ("api/go.mod"), for toolchain detection. No links followed. */
+export const projectEntries = (root) => {
+    const list = (dir) => { try {
+        return fs.readdirSync(dir, { withFileTypes: true }).slice(0, 2000);
+    }
+    catch {
+        return [];
+    } };
+    const top = list(root);
+    const below = top.filter((d) => d.isDirectory() && !d.name.startsWith('.') && !SKIP.test(d.name)).slice(0, 200)
+        .flatMap((d) => list(path.join(root, d.name)).filter((f) => f.isFile()).map((f) => d.name + '/' + f.name));
+    return [...top.filter((d) => d.isFile()).map((d) => d.name), ...below];
+};
+/** Scripts in the project root or one folder down that set up MSVC (vcvars*.bat, vswhere): read with bounded effort. */
+export const msvcHint = (root) => {
+    const scripts = projectEntries(root).filter((e) => /\.(ps1|cmd|bat|psm1)$/i.test(e)).slice(0, 60);
+    for (const rel of scripts) {
+        let text = '';
+        try {
+            const file = path.join(root, rel);
+            if (fs.statSync(file).size <= 256 * 1024)
+                text = fs.readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (/vcvars(all|64|32)?\.bat|vswhere(\.exe)?/i.test(text))
+            return rel + ' sets up MSVC';
+    }
+    return undefined;
+};

package/dist/host/projects.d.ts

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+import { PROJECTS_GUEST, type ProjectEntry, type RootMapping } from '../shared/projects.js';
+import { type Wsb } from './wsb.js';
+export { PROJECTS_GUEST };
+export type { ProjectEntry };
+declare const Entry: z.ZodObject<{
+    name: z.ZodString;
+    host: z.ZodString;
+    guest: z.ZodString;
+    primary: z.ZodBoolean;
+    mechanism: z.ZodEnum<{
+        root: "root";
+        launch: "launch";
+        boot: "boot";
+        wsb: "wsb";
+    }>;
+    registeredAt: z.ZodString;
+}, z.core.$strict>;
+declare const Registry: z.ZodObject<{
+    launchId: z.ZodString;
+    protections: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    roots: z.ZodArray<z.ZodObject<{
+        host: z.ZodString;
+        guest: z.ZodString;
+    }, z.core.$strict>>;
+    projects: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        host: z.ZodString;
+        guest: z.ZodString;
+        primary: z.ZodBoolean;
+        mechanism: z.ZodEnum<{
+            root: "root";
+            launch: "launch";
+            boot: "boot";
+            wsb: "wsb";
+        }>;
+        registeredAt: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type RegistryEntry = z.output<typeof Entry>;
+export type ProjectRegistry = z.output<typeof Registry>;
+export declare const readRegistry: (storageRoot: string) => ProjectRegistry | null;
+/** At launch: the launch folder, the projects mapped with it, and the roots. */
+export declare const startRegistry: (storageRoot: string, o: {
+    launchId: string;
+    protections: ProjectRegistry["protections"];
+    primary: RootMapping;
+    roots: RootMapping[];
+    boot: RootMapping[];
+}) => RegistryEntry;
+/** Why a folder cannot join the running sandbox without a restart (the caller offers one). */
+export declare class NeedsRestart extends Error {
+    readonly hostDir: string;
+    readonly reason: string;
+    constructor(hostDir: string, reason: string);
+}
+export interface ProjectMapper {
+    /** The projects of the running sandbox (the launch folder first). */
+    list(): RegistryEntry[];
+    /** Makes a folder of this PC a project of the running sandbox; throws NeedsRestart when that needs a restart. */
+    register(hostDir: string): RegistryEntry;
+    /** Forgets a project (never the launch folder). Its folder stays visible until the next start if it is mapped. */
+    unregister(name: string): void;
+}
+export interface MapperOptions {
+    storageRoot: string;
+    packageRoot: string;
+    wsbShare: boolean;
+    detect?: () => Wsb | null;
+}
+/** Roots first (instant), then `wsb share` where the Windows Sandbox CLI exists, else NeedsRestart. */
+export declare const projectMapper: (o: MapperOptions) => ProjectMapper;
+/** Which project of the running sandbox a folder on this PC is in, and where that folder is inside. */
+export interface ProjectHere {
+    project: RegistryEntry;
+    guestDir: string;
+}
+export declare const projectHere: (storageRoot: string, hostDir: string) => ProjectHere | null;
+/** The running sandbox's root containing this folder, if any. */
+export declare const rootHere: (storageRoot: string, hostDir: string) => RootMapping | null;
+declare const Known: z.ZodObject<{
+    projects: z.ZodArray<z.ZodObject<{
+        host: z.ZodString;
+        lastUsed: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type KnownProject = z.output<typeof Known>['projects'][number];
+export declare const readKnown: (storageRoot: string) => KnownProject[];
+export declare const rememberProject: (storageRoot: string, hostDir: string) => void;
+export declare const forgetProject: (storageRoot: string, hostDir: string) => boolean;
+/**
+ * projects.all: the known projects mapped at boot on their own (existing folders, not excluded, not the launch folder,
+ * not inside it or a root, which already show them). Pure apart from checking that the folders exist.
+ */
+export declare const allProjectsToMap: (known: string[], o: {
+    primary: string;
+    roots: string[];
+    exclude: string[];
+    exists?: (p: string) => boolean;
+}) => string[];

package/dist/host/projects.js

@@ -0,0 +1,147 @@
+// The projects of the running sandbox, and how another folder joins it (shared/projects.ts explains the ways in).
+// Two host-only files under the storage folder, never in the data folder the sandbox can write:
+//  - run\projects.json: the running sandbox's projects, roots and machine-wide protections (written at launch, then
+//    as folders join);
+//  - known-projects.json: every folder this tool has started a project in (for projects.all and `sandbox projects`).
+// Everything about HOW a folder becomes visible is behind ProjectMapper, so the mechanisms can change independently.
+import path from 'node:path';
+import { z } from 'zod';
+import { assertSafeWorkspace } from '../core/safe-paths.js';
+import { dirExists, fail } from '../core/util.js';
+import { Id } from '../shared/schema.js';
+import { readValid, writeJsonAtomic } from '../shared/rundir.js';
+import { guestDirFor, hubName, isWithin, PROJECTS_GUEST, projectForHostDir } from '../shared/projects.js';
+import { detectWsb, runningSandboxId, shareFolder } from './wsb.js';
+export { PROJECTS_GUEST };
+const AbsolutePath = z.string().max(1024).refine((p) => path.isAbsolute(p), 'must be an absolute path');
+const Entry = z.strictObject({
+    name: Id, host: AbsolutePath, guest: z.string().max(1024), primary: z.boolean(),
+    mechanism: z.enum(['launch', 'root', 'boot', 'wsb']), registeredAt: z.string().max(64),
+});
+const Registry = z.strictObject({
+    launchId: z.string().max(64),
+    /** The running sandbox's protections (core/project-policy.ts), fixed at boot. */
+    protections: z.record(z.string(), z.union([z.boolean(), z.string()])),
+    roots: z.array(z.strictObject({ host: AbsolutePath, guest: z.string().max(1024) })).max(64),
+    projects: z.array(Entry).max(1024),
+});
+const registryFile = (storageRoot) => path.join(storageRoot, 'run', 'projects.json');
+export const readRegistry = (storageRoot) => readValid(Registry, registryFile(storageRoot));
+const saveRegistry = (storageRoot, registry) => writeJsonAtomic(registryFile(storageRoot), registry);
+/** At launch: the launch folder, the projects mapped with it, and the roots. */
+export const startRegistry = (storageRoot, o) => {
+    const at = new Date().toISOString();
+    const primary = { name: hubName(o.primary.host, []), host: o.primary.host, guest: o.primary.guest, primary: true, mechanism: 'launch', registeredAt: at };
+    const names = [primary.name];
+    const boot = o.boot.map((b) => { const name = hubName(b.host, names); names.push(name); return { name, host: b.host, guest: b.guest, primary: false, mechanism: 'boot', registeredAt: at }; });
+    saveRegistry(storageRoot, { launchId: o.launchId, protections: o.protections, roots: o.roots, projects: [primary, ...boot] });
+    return primary;
+};
+/** Why a folder cannot join the running sandbox without a restart (the caller offers one). */
+export class NeedsRestart extends Error {
+    hostDir;
+    reason;
+    constructor(hostDir, reason) {
+        super(reason);
+        this.hostDir = hostDir;
+        this.reason = reason;
+    }
+}
+/** Roots first (instant), then `wsb share` where the Windows Sandbox CLI exists, else NeedsRestart. */
+export const projectMapper = (o) => {
+    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.');
+    const add = (reg, host, guest, mechanism, name) => {
+        const entry = { name, host, guest, primary: false, mechanism, registeredAt: new Date().toISOString() };
+        // Re-read right before writing: another terminal may have registered something meanwhile.
+        const latest = readRegistry(o.storageRoot) ?? reg;
+        const same = latest.projects.find((p) => p.host.toLowerCase() === host.toLowerCase());
+        if (same)
+            return same;
+        saveRegistry(o.storageRoot, { ...latest, projects: [...latest.projects, entry] });
+        return entry;
+    };
+    return {
+        list: () => readRegistry(o.storageRoot)?.projects ?? [],
+        register: (hostDir) => {
+            const host = path.resolve(hostDir);
+            const reg = registry();
+            const known = reg.projects.find((p) => p.host.toLowerCase() === host.toLowerCase());
+            if (known)
+                return known;
+            assertSafeWorkspace(host, o.packageRoot, o.storageRoot);
+            if (!dirExists(host))
+                fail('The folder does not exist: ' + host);
+            const name = hubName(host, reg.projects.map((p) => p.name));
+            // Inside a root: visible already (also a project created after the sandbox started).
+            const root = projectForHostDir(reg.roots, host);
+            if (root)
+                return add(reg, host, guestDirFor(root, host), 'root', name);
+            if (!o.wsbShare)
+                throw new NeedsRestart(host, 'it is not inside a project root (projects.roots), and adding folders with wsb share is off (projects.wsbShare)');
+            const wsb = (o.detect ?? detectWsb)();
+            if (!wsb?.has('share'))
+                throw new NeedsRestart(host, 'it is not inside a project root (projects.roots), and this Windows has no Windows Sandbox command line (wsb share needs Windows 11 24H2+ with the updated Windows Sandbox)');
+            const sandbox = runningSandboxId(wsb);
+            if (!sandbox.id)
+                throw new NeedsRestart(host, 'wsb share could not find the running sandbox: ' + sandbox.error);
+            const guest = path.win32.join(PROJECTS_GUEST, name);
+            const shared = shareFolder(wsb, sandbox.id, host, guest);
+            if (!shared.ok)
+                throw new NeedsRestart(host, 'wsb share failed (untested on this Windows): ' + shared.error);
+            return add(reg, host, guest, 'wsb', name);
+        },
+        unregister: (name) => {
+            const reg = registry();
+            const entry = reg.projects.find((p) => p.name.toLowerCase() === name.toLowerCase());
+            if (!entry)
+                fail('No project "' + name + '" in the running sandbox.', 'sandbox projects lists them.');
+            if (entry.primary)
+                fail(entry.host + ' is the folder the sandbox started from; it stays until the sandbox stops.');
+            saveRegistry(o.storageRoot, { ...reg, projects: reg.projects.filter((p) => p !== entry) });
+        },
+    };
+};
+export const projectHere = (storageRoot, hostDir) => {
+    const project = projectForHostDir(readRegistry(storageRoot)?.projects ?? [], hostDir);
+    return project ? { project, guestDir: guestDirFor(project, hostDir) } : null;
+};
+/** The running sandbox's root containing this folder, if any. */
+export const rootHere = (storageRoot, hostDir) => projectForHostDir(readRegistry(storageRoot)?.roots ?? [], hostDir);
+// ---- known projects (every folder a project was started in) ------------------------------------------------------
+const Known = z.strictObject({ projects: z.array(z.strictObject({ host: AbsolutePath, lastUsed: z.string().max(64) })).max(2000) });
+const knownFile = (storageRoot) => path.join(storageRoot, 'known-projects.json');
+export const readKnown = (storageRoot) => readValid(Known, knownFile(storageRoot))?.projects ?? [];
+export const rememberProject = (storageRoot, hostDir) => {
+    const host = path.resolve(hostDir);
+    const rest = readKnown(storageRoot).filter((p) => p.host.toLowerCase() !== host.toLowerCase());
+    try {
+        writeJsonAtomic(knownFile(storageRoot), { projects: [{ host, lastUsed: new Date().toISOString() }, ...rest].slice(0, 2000) });
+    }
+    catch { /* a convenience list */ }
+};
+export const forgetProject = (storageRoot, hostDir) => {
+    const host = path.resolve(hostDir);
+    const all = readKnown(storageRoot);
+    const rest = all.filter((p) => p.host.toLowerCase() !== host.toLowerCase());
+    if (rest.length !== all.length)
+        writeJsonAtomic(knownFile(storageRoot), { projects: rest });
+    return rest.length !== all.length;
+};
+/**
+ * projects.all: the known projects mapped at boot on their own (existing folders, not excluded, not the launch folder,
+ * not inside it or a root, which already show them). Pure apart from checking that the folders exist.
+ */
+export const allProjectsToMap = (known, o) => {
+    const exists = o.exists ?? dirExists;
+    const out = [];
+    for (const host of known.map((k) => path.resolve(k))) {
+        if (o.exclude.some((e) => isWithin(path.resolve(e), host)))
+            continue;
+        if (isWithin(o.primary, host) || o.roots.some((r) => isWithin(r, host)))
+            continue;
+        if (out.some((x) => isWithin(x, host) || isWithin(host, x)) || !exists(host))
+            continue;
+        out.push(host);
+    }
+    return out;
+};

package/dist/host/repo-guard.d.ts

@@ -0,0 +1,36 @@
+export interface RepoSnapshot {
+    gitDir: boolean;
+    config: string[];
+    hooks: Record<string, string>;
+    redirects: string[];
+    commands: Record<string, string>;
+}
+export interface RepoFinding {
+    kind: 'hook' | 'config' | 'git' | 'command';
+    detail: string;
+}
+export declare const snapshotRepo: (workspace: string) => RepoSnapshot;
+/**
+ * Compares the workspace with its pre-launch snapshot and neutralises anything new that would execute on this PC.
+ * Returns what was found (and fixed). Never touches what was already there before the sandbox ran.
+ */
+export declare const guardRepo: (workspace: string, before: RepoSnapshot) => RepoFinding[];
+/**
+ * At launch: every folder the sandbox will be able to write. The launch folder, projects mapped with it and every
+ * project already inside a project root are snapshotted as they are now, before the sandbox can touch them.
+ */
+export declare const saveRepoSnapshot: (dataPath: string, workspace: string, more?: string[], roots?: string[]) => void;
+/**
+ * A project that joins the running sandbox: snapshotted before its first session, then guarded like the launch
+ * folder. A project already guarded keeps its first snapshot (what was there before the sandbox could touch it).
+ */
+export declare const addRepoSnapshot: (dataPath: string, workspace: string, o?: {
+    empty?: boolean;
+}) => void;
+/** The folders being guarded (for status). */
+export declare const guardedProjects: (dataPath: string) => string[];
+/** Re-checks every project of the current/last launch; findings are kept in a host-only file for `status`. Returns the new ones. */
+export declare const checkRepo: (dataPath: string) => RepoFinding[];
+export declare const repoFindings: (dataPath: string) => (RepoFinding & {
+    at?: string;
+})[];