windows-development-sandbox 1.4.0 → 1.4.3

package/dist/host/profile/secret-files.js

@@ -0,0 +1,25 @@
+// Secret-looking files in a workspace, for a warning at launch (the agent can read them: the folder is mapped).
+import fs from 'node:fs';
+import path from 'node:path';
+/** Files that usually hold secrets. The agent CAN read them (the whole folder is mapped); we only warn. */
+const SECRET_FILES = /^(\.env(\..+)?|\.envrc|.*\.(pem|key|p12|pfx|jks|keystore|kdbx|tfvars|ovpn)|credentials(\.json)?|secrets?\.(json|ya?ml|toml)|service[-_]?account.*\.json|id_(rsa|ed25519|ecdsa)|\.npmrc|\.pypirc|\.netrc|\.git-credentials)$/i;
+const TEMPLATE = /\.(example|sample|template|dist|defaults?)$/i;
+/** Secret-looking files in the workspace root and one folder down (skipping dependency folders). */
+export function findSecretFiles(workspace) {
+    const list = (dir) => {
+        try {
+            return fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+    };
+    const hit = (name) => SECRET_FILES.test(name) && !TEMPLATE.test(name);
+    const top = list(workspace);
+    const below = top
+        .filter((d) => d.isDirectory() && !/^(node_modules|\.git|vendor|target|dist|build|\.venv|venv)$/i.test(d.name))
+        .flatMap((d) => list(path.join(workspace, d.name))
+        .filter((f) => f.isFile() && hit(f.name))
+        .map((f) => d.name + '\\' + f.name));
+    return [...top.filter((d) => d.isFile() && hit(d.name)).map((d) => d.name), ...below];
+}

package/dist/host/profile/secret-patterns.d.ts

@@ -0,0 +1,6 @@
+/** Variable names that are credentials by definition: cloud, hosting, CI, registries, payment, AI APIs, ... */
+export declare const SECRET_NAMES: readonly RegExp[];
+/** Any name that says what it holds: ..._TOKEN, ..._SECRET, PASSWORD, API_KEY, PRIVATE_KEY, connection strings. */
+export declare const SECRET_WORDS: RegExp;
+/** Values that are credentials whatever they are called. */
+export declare const SECRET_VALUES: readonly RegExp[];

package/dist/host/profile/secret-patterns.js

@@ -0,0 +1,128 @@
+// What counts as a credential: variable names, words in names, and values that are credentials whatever their name.
+/** Variable names that are credentials by definition: cloud, hosting, CI, registries, payment, AI APIs, ... */
+export const SECRET_NAMES = [
+    /^AWS_/,
+    /^AMAZON_/,
+    /^AZURE_/,
+    /^ARM_(CLIENT|TENANT|SUBSCRIPTION|ACCESS)_/,
+    /^MSAL_/,
+    /^CLOUDFLARE_/,
+    /^CF_(API|ACCOUNT|ZONE|ACCESS)/,
+    /^GOOGLE_(APPLICATION_CREDENTIALS|API_KEY|CLOUD_|CLIENT_SECRET)/,
+    /^GCP_/,
+    /^GCLOUD_/,
+    /^GOOGLE_GHA_/,
+    /^FIREBASE_/,
+    /^DIGITALOCEAN_/,
+    /^DO_(API|AUTH)_/,
+    /^LINODE_/,
+    /^HCLOUD_/,
+    /^OCI_/,
+    /^ALIBABA_CLOUD_/,
+    /^ALICLOUD_/,
+    /^IBMCLOUD_/,
+    /^HEROKU_/,
+    /^VERCEL_/,
+    /^NETLIFY_/,
+    /^RENDER_API/,
+    /^FLY_(API|ACCESS)_/,
+    /^RAILWAY_/,
+    /^SUPABASE_/,
+    /^NEON_/,
+    /^PLANETSCALE_/,
+    /^GITHUB_TOKEN$/,
+    /^GH_TOKEN$/,
+    /^GH_ENTERPRISE_TOKEN$/,
+    /^GITHUB_PAT/,
+    /^GITLAB_/,
+    /^BITBUCKET_/,
+    /^CIRCLE_TOKEN$/,
+    /^TRAVIS_/,
+    /^BUILDKITE_/,
+    /^NPM_TOKEN$/,
+    /^NODE_AUTH_TOKEN$/,
+    /^YARN_NPM_AUTH/,
+    /^NUGET_(API_KEY|AUTH)/,
+    /^PYPI_/,
+    /^TWINE_/,
+    /^CARGO_REGISTRY_TOKEN$/,
+    /^GEM_HOST_API_KEY$/,
+    /^DOCKER_(PASSWORD|TOKEN|AUTH)/,
+    /^REGISTRY_(PASSWORD|TOKEN)/,
+    /^KUBECONFIG$/,
+    /^KUBE_TOKEN$/,
+    /^HELM_/,
+    /^VAULT_/,
+    /^CONSUL_HTTP_TOKEN$/,
+    /^NOMAD_TOKEN$/,
+    /^TF_VAR_/,
+    /^TF_TOKEN_/,
+    /^TFE_TOKEN$/,
+    /^PULUMI_ACCESS_TOKEN$/,
+    /^SPACELIFT_/,
+    /^ANSIBLE_VAULT/,
+    /^STRIPE_/,
+    /^PAYPAL_/,
+    /^BRAINTREE_/,
+    /^SQUARE_/,
+    /^ADYEN_/,
+    /^TWILIO_/,
+    /^SENDGRID_/,
+    /^MAILGUN_/,
+    /^POSTMARK_/,
+    /^MAILCHIMP_/,
+    /^RESEND_/,
+    /^SLACK_/,
+    /^DISCORD_(TOKEN|BOT|WEBHOOK)/,
+    /^TELEGRAM_BOT/,
+    /^SENTRY_(AUTH|DSN)/,
+    /^DATADOG_/,
+    /^DD_(API|APP)_KEY$/,
+    /^NEW_RELIC_/,
+    /^HONEYCOMB_/,
+    /^OPENAI_/,
+    /^ANTHROPIC_(API_KEY|AUTH_TOKEN)$/,
+    /^CLAUDE_CODE_OAUTH_TOKEN$/,
+    /^GEMINI_API_KEY$/,
+    /^MISTRAL_API_KEY$/,
+    /^COHERE_API_KEY$/,
+    /^GROQ_API_KEY$/,
+    /^HF_TOKEN$/,
+    /^HUGGING_?FACE_/,
+    /^REPLICATE_API/,
+    /^PINECONE_/,
+    /^ELEVENLABS_/,
+    /^DATABASE_URL$/,
+    /^.*_DATABASE_URL$/,
+    /^(PG|POSTGRES|MYSQL|MARIADB|MSSQL|MONGO(DB)?|REDIS|ELASTIC(SEARCH)?|RABBITMQ|SNOWFLAKE|DATABRICKS)_/,
+    /^SSH_AUTH_SOCK$/,
+    /^GPG_/,
+    /^OP_(SERVICE_ACCOUNT|CONNECT)_/,
+    /^BWS_ACCESS_TOKEN$/,
+    /^DOPPLER_/,
+    /^INFISICAL_/,
+];
+/** Any name that says what it holds: ..._TOKEN, ..._SECRET, PASSWORD, API_KEY, PRIVATE_KEY, connection strings. */
+export const SECRET_WORDS = /(^|_)(PROD|PRODUCTION|LIVE|SECRETS?|TOKENS?|PASSWORDS?|PASSWD|PWD|PASS|API_?KEYS?|ACCESS_?KEYS?|PRIVATE_?KEYS?|SIGNING_?KEYS?|CREDENTIALS?|CREDS|AUTH|AUTHORIZATION|BEARER|COOKIES?|SESSION_?KEYS?|CONN(ECTION)?_?STR(ING)?|DSN|WEBHOOK(_URL)?|CLIENT_?SECRET|SAS|SALT|PAT)(_|$)/;
+/** Values that are credentials whatever they are called. */
+export const SECRET_VALUES = [
+    /\b(AKIA|ASIA|AGPA|AIDA|AROA)[0-9A-Z]{16}\b/, // AWS access key ids
+    /\bgh[pousr]_[A-Za-z0-9]{30,}/,
+    /\bgithub_pat_[A-Za-z0-9_]{40,}/,
+    /\bglpat-[A-Za-z0-9_-]{20,}/,
+    /\bxox[abposr]-[A-Za-z0-9-]{10,}/,
+    /\bsk-(ant-|proj-|live_|test_)?[A-Za-z0-9_-]{20,}/,
+    /\b[rs]k_live_[A-Za-z0-9]{20,}/,
+    /\bAIza[0-9A-Za-z_-]{35}\b/,
+    /\bya29\.[0-9A-Za-z_-]{20,}/,
+    /\bnpm_[A-Za-z0-9]{36}\b/,
+    /\bhf_[A-Za-z0-9]{30,}/,
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+    /AccountKey=[A-Za-z0-9+/=]{20,}/i,
+    /SharedAccessSignature=|[?&]sig=[A-Za-z0-9%+/=]{20,}/i,
+    /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:[^\s@/]+@/i, // user:password@host in any URL (database URLs, registries)
+    /\bBearer\s+\S{16,}/i,
+    /\bBasic\s+[A-Za-z0-9+/=]{12,}/i,
+    /[?&](api[_-]?key|apikey|access[_-]?token|token|key|secret|password|sig|signature|auth)=[^&\s]{8,}/i, // credentials in a URL
+    /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/, // JWTs
+];

package/dist/host/profile/secrets.d.ts

@@ -0,0 +1,12 @@
+import type { Config } from '../../core/types.js';
+export type SecretsConfig = Config['secrets'];
+export declare function isSecretName(name: string, secrets: SecretsConfig): boolean;
+export declare function isSecretValue(value: string): boolean;
+/** Whether a variable (name and value) may go into the sandbox. secrets.allow always wins. */
+export declare function mayPass(name: string, value: unknown, secrets: SecretsConfig): boolean;
+/** A copy of an env/headers map without the secrets; the names removed are added to `removed` (with `where`). */
+export declare function stripVariables(vars: unknown, secrets: SecretsConfig, where: string, removed: string[]): unknown;
+/** settings.json for the sandbox: secrets out of "env", credential helper commands removed. */
+export declare function stripSettings(settings: Record<string, unknown>, secrets: SecretsConfig, removed: string[]): Record<string, unknown>;
+/** Every MCP server in a .claude.json-shaped object (top level and per project). */
+export declare function stripMcpServers(state: Record<string, unknown>, secrets: SecretsConfig, removed: string[]): Record<string, unknown>;

package/dist/host/profile/secrets.js

@@ -0,0 +1,100 @@
+import { SECRET_NAMES, SECRET_VALUES, SECRET_WORDS } from './secret-patterns.js';
+/** "AWS_REGION", "MY_*", "*_URL": * matches anything. Case-insensitive, like Windows variable names. */
+function globMatch(pattern, name) {
+    return new RegExp('^' +
+        pattern
+            .split('*')
+            .map((p) => p.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+            .join('.*') +
+        '$', 'i').test(name);
+}
+export function isSecretName(name, secrets) {
+    // X-API-Key, x-auth-token, api.key: compared as X_API_KEY, X_AUTH_TOKEN, API_KEY.
+    const upper = name.toUpperCase().replace(/[-\s.]/g, '_');
+    return (SECRET_NAMES.some((r) => r.test(upper)) ||
+        SECRET_WORDS.test(upper) ||
+        secrets.patterns.some((p) => globMatch(p, name)));
+}
+export function isSecretValue(value) {
+    return SECRET_VALUES.some((r) => r.test(value));
+}
+/** Whether a variable (name and value) may go into the sandbox. secrets.allow always wins. */
+export function mayPass(name, value, secrets) {
+    if (!secrets.strip || secrets.allow.some((p) => globMatch(p, name)))
+        return true;
+    return !isSecretName(name, secrets) && !(typeof value === 'string' && isSecretValue(value));
+}
+/** A copy of an env/headers map without the secrets; the names removed are added to `removed` (with `where`). */
+export function stripVariables(vars, secrets, where, removed) {
+    if (typeof vars !== 'object' || vars === null || Array.isArray(vars))
+        return vars;
+    return Object.fromEntries(Object.entries(vars).filter(([name, value]) => {
+        const ok = mayPass(name, value, secrets);
+        if (!ok)
+            removed.push(where + name);
+        return ok;
+    }));
+}
+/** Claude settings keys that run commands to fetch credentials on this PC (they cannot work in the sandbox anyway). */
+const CREDENTIAL_HELPERS = ['apiKeyHelper', 'awsAuthRefresh', 'awsCredentialExport', 'otelHeadersHelper'];
+/** settings.json for the sandbox: secrets out of "env", credential helper commands removed. */
+export function stripSettings(settings, secrets, removed) {
+    if (!secrets.strip)
+        return settings;
+    const out = { ...settings };
+    for (const key of CREDENTIAL_HELPERS.filter((k) => k in out)) {
+        delete out[key];
+        removed.push('settings.json ' + key);
+    }
+    if ('env' in out)
+        out.env = stripVariables(out.env, secrets, 'settings.json env.', removed);
+    return out;
+}
+/** One MCP server: secret env vars and headers removed, and secret-looking command-line arguments blanked. */
+function stripServer(server, secrets, where, removed) {
+    if (typeof server !== 'object' || server === null)
+        return server;
+    const out = { ...server };
+    if ('env' in out)
+        out.env = stripVariables(out.env, secrets, where + ' env.', removed);
+    if ('headers' in out)
+        out.headers = stripVariables(out.headers, secrets, where + ' header ', removed);
+    if (typeof out.url === 'string' && secrets.strip && isSecretValue(out.url)) {
+        removed.push(where + ' url (it carried a credential)');
+        out.url = out.url.replace(/([?&])[^=&#]+=[^&#]*/g, (m, sep) => isSecretValue('?' + m.slice(1)) ? sep + m.slice(1).split('=')[0] + '=REMOVED' : m);
+    }
+    if (Array.isArray(out.args) && secrets.strip) {
+        out.args = out.args.map((arg, i) => {
+            const previous = i > 0 ? String(out.args[i - 1]) : '';
+            const [flag, inline] = typeof arg === 'string' && /^--?[\w-]+=/.test(arg)
+                ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)]
+                : [null, null];
+            const secretFlag = (f) => /^--?[\w-]+$/.test(f) && isSecretName(f.replace(/^-+/, ''), secrets);
+            const flagged = typeof arg === 'string' &&
+                (isSecretValue(arg) || (flag !== null && (secretFlag(flag) || isSecretValue(inline))) || secretFlag(previous));
+            if (flagged)
+                removed.push(where + ' argument ' + (i + 1));
+            return flagged ? '[removed by agent-sandbox]' : arg;
+        });
+    }
+    return out;
+}
+/** Every MCP server in a .claude.json-shaped object (top level and per project). */
+export function stripMcpServers(state, secrets, removed) {
+    if (!secrets.strip)
+        return state;
+    const servers = (owner, where) => {
+        const list = owner.mcpServers;
+        if (typeof list !== 'object' || list === null)
+            return owner;
+        return {
+            ...owner,
+            mcpServers: Object.fromEntries(Object.entries(list).map(([name, s]) => [name, stripServer(s, secrets, where + 'MCP ' + name, removed)])),
+        };
+    };
+    const top = servers(state, '');
+    const projects = top.projects;
+    return projects
+        ? { ...top, projects: Object.fromEntries(Object.entries(projects).map(([key, p]) => [key, servers(p, '')])) }
+        : top;
+}

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

@@ -0,0 +1,4 @@
+export * from './registry.js';
+export * from './mapper.js';
+export * from './known.js';
+export * from './join.js';

package/dist/host/projects/index.js

@@ -0,0 +1,4 @@
+export * from './registry.js';
+export * from './mapper.js';
+export * from './known.js';
+export * from './join.js';

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

@@ -0,0 +1,38 @@
+import type { ResolvedRun } from '../../core/types.js';
+import { type Missing } from '../../core/local-config/index.js';
+import { type ProjectSpec } from '../../shared/channel/index.js';
+import { type RegistryEntry } from './registry.js';
+import { type ProjectMapper } from './mapper.js';
+/** The launch folder of the running sandbox (host-only storage; its id comes from the guest, so it is checked). */
+export declare function runningLaunchPath(storageRoot: string, dataPath: string): string | null;
+/** What a session or command from this folder needs: where it is inside, and (for another project) its spec. */
+export interface Joined {
+    project: RegistryEntry;
+    guestDir: string;
+    spec: ProjectSpec | 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 function projectSpec(run: ResolvedRun, entry: RegistryEntry, hooks: boolean): ProjectSpec;
+/**
+ * Makes `hostDir` usable in the running sandbox. The launch folder (or a folder below it) needs nothing; any other
+ * folder is resolved with `resolve` (the caller's resolveRun, with the approval prompt), checked, and registered.
+ */
+export declare function joinRunning(o: {
+    storageRoot: string;
+    dataPath: string;
+    packageRoot: string;
+    hostDir: string;
+    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>;
+    /** Asked when the project's own settings are stricter than the running sandbox's (default: refuse). */
+    acceptStricter?: (name: string, stricter: string[]) => Promise<boolean>;
+}): Promise<Joined>;

package/dist/host/projects/join.js

@@ -0,0 +1,119 @@
+// Joining the running sandbox from another folder. The folder's run is resolved exactly as a fresh launch would
+// 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: 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. 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, missingAtBoot, nothingMissing, protectionsOf, } from '../../core/local-config/index.js';
+import { resolveToolchains } from '../../core/detect/index.js';
+import { assertNoLinks, dirExists, fail } from '../../core/util/index.js';
+import { IdSchema, RunDir } from '../../shared/channel/index.js';
+import { syncProjectIn } from '../../sync/index.js';
+import { decideProjectToolchains, planDatabases, stageScripts } from '../launch/index.js';
+import { RepoGuardStore } from '../guard/index.js';
+import { ProjectRegistry } from './registry.js';
+import { NeedsRestart, projectMapper } from './mapper.js';
+import { KnownProjects } from './known.js';
+/** The launch folder of the running sandbox (host-only storage; its id comes from the guest, so it is checked). */
+export function runningLaunchPath(storageRoot, dataPath) {
+    const launchId = new RunDir(dataPath).readSandboxStatus()?.launchId;
+    if (!launchId ||
+        !/^\d+-[0-9a-f]{6}$/.test(launchId) ||
+        new ProjectRegistry(storageRoot).read()?.launchId !== launchId)
+        return null;
+    const launchPath = path.join(storageRoot, 'launches', launchId);
+    assertNoLinks(storageRoot, launchPath);
+    return fs.existsSync(path.join(launchPath, 'session.json')) ? launchPath : null;
+}
+/** The project spec the guest provisions from (scans the project folder like a launch does). */
+export function projectSpec(run, entry, hooks) {
+    const { config } = run;
+    const toolchains = resolveToolchains(config.toolchains, decideProjectToolchains({ run }));
+    const harness = run.harnessName === 'none' ? null : config.harnesses[run.harnessName];
+    return {
+        name: IdSchema.parse(entry.name),
+        workspace: entry.guest,
+        workspaceHost: entry.host,
+        toolchains,
+        versions: run.versions,
+        databases: planDatabases(config.databases, run.workspaceHost).slice(0, 8),
+        harnesses: harness ? { [run.harnessName]: harness } : {},
+        hooks,
+    };
+}
+/**
+ * Makes `hostDir` usable in the running sandbox. The launch folder (or a folder below it) needs nothing; any other
+ * folder is resolved with `resolve` (the caller's resolveRun, with the approval prompt), checked, and registered.
+ */
+export async function joinRunning(o) {
+    const registryFile = new ProjectRegistry(o.storageRoot);
+    const here = registryFile.here(o.hostDir);
+    if (here?.project.primary)
+        return { ...here, spec: null, run: null, notes: [], missing: null };
+    const registry = registryFile.read() ??
+        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), Object.keys(registry.atBoot?.widened ?? {}));
+    // Machine-wide settings cannot change for one project, so it either runs with the sandbox's (your consent) or not
+    // at all.
+    const name = here?.project.name ?? path.basename(root);
+    const accepted = check.stricter.length > 0 && (await o.acceptStricter?.(name, check.stricter)) === true;
+    if (check.stricter.length && !accepted) {
+        fail("This project's settings are stricter than the running sandbox's, and those settings are machine-wide:\n  " +
+            check.stricter.join('\n  '), "Join with the sandbox's settings: answer yes in a terminal, or add --yes. Or 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 = registryFile.bootRecord(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(name, 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.
+    // Anything else is snapshotted before it becomes visible.
+    new RepoGuardStore(o.dataPath).add(root, {
+        empty: Boolean(here) || Boolean(registryFile.rootHere(root)),
+    });
+    const entry = mapper.register(root);
+    new KnownProjects(o.storageRoot).remember(entry.host);
+    // 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.
+    const hooks = Boolean(launchPath) && run.scripts.length > 0;
+    if (launchPath && hooks)
+        stageScripts(path.join(launchPath, 'projects', entry.name, 'hooks', 'pre-agent'), run.scripts);
+    try {
+        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 + '.'),
+        ...(accepted ? ["Runs with the sandbox's settings (you agreed): " + check.stricter.join('; ') + '.'] : []),
+        ...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/projects/known.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+declare const KnownSchema: z.ZodObject<{
+    projects: z.ZodArray<z.ZodObject<{
+        host: z.ZodString;
+        lastUsed: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type Known = z.output<typeof KnownSchema>;
+export type KnownProject = Known['projects'][number];
+/** known-projects.json under the storage folder: every folder a project was started in. */
+export declare class KnownProjects {
+    private readonly file;
+    constructor(storageRoot: string);
+    list(): KnownProject[];
+    remember(hostDir: string): void;
+    forget(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 function allProjectsToMap(known: readonly string[], o: {
+    readonly primary: string;
+    readonly roots: readonly string[];
+    readonly exclude: readonly string[];
+    readonly exists?: (p: string) => boolean;
+}): string[];
+export {};

package/dist/host/projects/known.js

@@ -0,0 +1,55 @@
+import path from 'node:path';
+import { z } from 'zod';
+import { dirExists } from '../../core/util/index.js';
+import { JsonFile } from '../../shared/io/index.js';
+import { isWithin } from '../../shared/paths/index.js';
+import { AbsolutePathSchema } from './registry.js';
+const KnownSchema = z.strictObject({
+    projects: z.array(z.strictObject({ host: AbsolutePathSchema, lastUsed: z.string().max(64) })).max(2000),
+});
+/** known-projects.json under the storage folder: every folder a project was started in. */
+export class KnownProjects {
+    file;
+    constructor(storageRoot) {
+        this.file = new JsonFile(KnownSchema, path.join(storageRoot, 'known-projects.json'));
+    }
+    list() {
+        return this.file.read()?.projects ?? [];
+    }
+    remember(hostDir) {
+        const host = path.resolve(hostDir);
+        const rest = this.list().filter((p) => p.host.toLowerCase() !== host.toLowerCase());
+        try {
+            this.file.write({ projects: [{ host, lastUsed: new Date().toISOString() }, ...rest].slice(0, 2000) });
+        }
+        catch {
+            /* a convenience list */
+        }
+    }
+    forget(hostDir) {
+        const host = path.resolve(hostDir);
+        const all = this.list();
+        const rest = all.filter((p) => p.host.toLowerCase() !== host.toLowerCase());
+        if (rest.length !== all.length)
+            this.file.write({ 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 function 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/projects/mapper.d.ts

@@ -0,0 +1,29 @@
+import type { Missing } from '../../core/local-config/index.js';
+import { type Wsb } from '../sandbox/index.js';
+import { type RegistryEntry } from './registry.js';
+/**
+ * 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/local-config/boot-wants.ts).
+ */
+export declare class NeedsRestart extends Error {
+    readonly hostDir: string;
+    readonly 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). */
+    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;

package/dist/host/projects/mapper.js

@@ -0,0 +1,88 @@
+import path from 'node:path';
+import { assertSafeWorkspace } from '../../core/safe-paths.js';
+import { dirExists, fail } from '../../core/util/index.js';
+import { guestDirFor, hubName, ownGuestFolder, projectForHostDir } from '../../shared/paths/index.js';
+import { detectWsb, runningSandboxId, shareFolder } from '../sandbox/index.js';
+import { ProjectRegistry } from './registry.js';
+/**
+ * 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/local-config/boot-wants.ts).
+ */
+export class NeedsRestart extends Error {
+    hostDir;
+    reason;
+    missing;
+    constructor(hostDir, reason, missing) {
+        super(reason);
+        this.hostDir = hostDir;
+        this.reason = reason;
+        this.missing = missing;
+    }
+}
+/** Roots first (instant), then `wsb share` where the Windows Sandbox CLI exists, else NeedsRestart. */
+export const projectMapper = (o) => {
+    const store = new ProjectRegistry(o.storageRoot);
+    const registry = () => store.read() ??
+        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 = store.read() ?? reg;
+        const same = latest.projects.find((p) => p.host.toLowerCase() === host.toLowerCase());
+        if (same)
+            return same;
+        store.save({ ...latest, projects: [...latest.projects, entry] });
+        return entry;
+    };
+    return {
+        list: () => store.read()?.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);
+            // Where it is as a launch folder too (C:\Workspace\<name>), unless another project already uses that place.
+            const guest = ownGuestFolder(host, false, [
+                ...reg.projects.map((p) => p.guest),
+                ...reg.roots.map((r) => r.guest),
+            ]);
+            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.');
+            store.save({ ...reg, projects: reg.projects.filter((p) => p !== entry) });
+        },
+    };
+};