windows-development-sandbox 0.0.0-stage → 1.0.5

package/dist/host/secrets.js

@@ -0,0 +1,133 @@
+// Keeps credentials on this PC. Everything copied into the sandbox from your Claude settings (settings.json "env",
+// MCP servers' env / headers / args in .claude.json) goes through here first: cloud and production credentials are
+// removed unless you let them through with secrets.allow. Pure functions, so they are easy to test.
+import fs from 'node:fs';
+import path from 'node:path';
+/** Variable names that are credentials by definition: cloud providers, hosting, CI, registries, payment, AI APIs, ... */
+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, ... */
+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. */
+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
+];
+/** "AWS_REGION", "MY_*", "*_URL": * matches anything. Case-insensitive, like Windows variable names. */
+const globMatch = (pattern, name) => new RegExp('^' + pattern.split('*').map((p) => p.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$', 'i').test(name);
+export const 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 const isSecretValue = (value) => SECRET_VALUES.some((r) => r.test(value));
+/** Whether a variable (name and value) may go into the sandbox. secrets.allow always wins. */
+export const 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 const 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 const 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. */
+const 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 const 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;
+};
+/** Files in the workspace 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 const 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/terminal.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+export declare const terminalDir: (dataPath: string) => string;
+export declare const terminalExe: (dataPath: string) => string;
+/** Our own profile id, so the profile is found again (and user edits to it are kept) on later launches. */
+export declare const PWSH_PROFILE_GUID = "{5f3a6c1e-7d2b-4e8a-9c41-0b6d2a8f7e93}";
+declare const TerminalSettings: z.ZodObject<{
+    profiles: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
+        guid: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>, z.ZodObject<{
+        list: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            guid: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>]>>;
+}, z.core.$loose>;
+/**
+ * settings.json with the "PowerShell 7" profile shown when `visible`, else hidden (never deleted: a user's tweaks to it
+ * survive turning pwsh off and on). Pure: returns null when nothing changes.
+ */
+export declare const withPwshProfile: (settings: z.output<typeof TerminalSettings>, visible: boolean) => z.output<typeof TerminalSettings> | null;
+/**
+ * Shows the PowerShell 7 profile once pwsh is installed in this data folder (and `allowed`, i.e. toolchains.pwsh is
+ * not off), hides it otherwise. settings.json is written by the sandbox too: read with a size cap, through no links,
+ * shape-checked, only rewritten when the profile changes; a file that does not parse is left alone.
+ */
+export declare const syncPwshProfile: (dataPath: string, allowed: boolean) => void;
+export declare const ensureTerminal: (dataPath: string, refresh: boolean, options?: {
+    pwsh?: boolean;
+}) => Promise<{
+    exe: string | null;
+    message: string;
+}>;
+export {};

package/dist/host/terminal.js

@@ -0,0 +1,127 @@
+// Windows Terminal for the sandbox window. The host downloads the portable build once into persistent storage, so
+// logon.cmd can open it the moment the sandbox logs in (no PowerShell window first).
+import fs from 'node:fs';
+import path from 'node:path';
+import { githubAsset, installArchive } from '../shared/download.js';
+import { safeRemove } from '../shared/safe-remove.js';
+import { z } from 'zod';
+import { assertNoLinks, errMsg, fileExists, parseJsonc, writeJson } from '../core/util.js';
+export const terminalDir = (dataPath) => path.join(dataPath, 'tools', 'terminal');
+export const terminalExe = (dataPath) => path.join(terminalDir(dataPath), 'WindowsTerminal.exe');
+/**
+ * Sandbox-friendly defaults; only written when there is no settings.json yet (first download), so edits made inside
+ * the sandbox stick, also across a refresh (which keeps the settings folder).
+ */
+const SETTINGS = {
+    $schema: 'https://aka.ms/terminal-profiles-schema',
+    theme: 'dark',
+    firstWindowPreference: 'defaultProfile',
+    confirmCloseAllTabs: false,
+    // New tabs pick up the PATH and variables the runner writes machine-wide after the window opened.
+    compatibility: { reloadEnvironmentVariables: true },
+    warning: { confirmCloseAllTabs: false, largePaste: false, multiLinePaste: false },
+    profiles: { defaults: { font: { face: 'Cascadia Mono' }, startingDirectory: '%AGENT_WORKSPACE%', closeOnExit: 'graceful' } },
+};
+/** Our own profile id, so the profile is found again (and user edits to it are kept) on later launches. */
+export const PWSH_PROFILE_GUID = '{5f3a6c1e-7d2b-4e8a-9c41-0b6d2a8f7e93}';
+/** pwsh.exe as the sandbox sees it (toolchains/pwsh.ts installs it to tools\pwsh). */
+const GUEST_PWSH = 'C:\\AgentData\\tools\\pwsh\\pwsh.exe';
+const MAX_SETTINGS_BYTES = 1024 * 1024;
+const TerminalSettings = z.looseObject({
+    profiles: z.union([z.array(z.looseObject({ guid: z.string().optional() })), z.looseObject({ list: z.array(z.looseObject({ guid: z.string().optional() })).optional() })]).optional(),
+});
+/**
+ * settings.json with the "PowerShell 7" profile shown when `visible`, else hidden (never deleted: a user's tweaks to it
+ * survive turning pwsh off and on). Pure: returns null when nothing changes.
+ */
+export const withPwshProfile = (settings, visible) => {
+    const profiles = Array.isArray(settings.profiles) ? { list: settings.profiles } : { ...settings.profiles };
+    const list = [...(profiles.list ?? [])];
+    const at = list.findIndex((p) => p.guid?.toLowerCase() === PWSH_PROFILE_GUID);
+    if (at === -1 && !visible)
+        return null;
+    if (at === -1)
+        list.push({ guid: PWSH_PROFILE_GUID, name: 'PowerShell 7', commandline: '"' + GUEST_PWSH + '" -NoLogo', icon: GUEST_PWSH, hidden: false });
+    else if ((list[at].hidden === true) === !visible)
+        return null;
+    else
+        list[at] = { ...list[at], hidden: !visible };
+    return { ...settings, profiles: { ...profiles, list } };
+};
+/**
+ * Shows the PowerShell 7 profile once pwsh is installed in this data folder (and `allowed`, i.e. toolchains.pwsh is
+ * not off), hides it otherwise. settings.json is written by the sandbox too: read with a size cap, through no links,
+ * shape-checked, only rewritten when the profile changes; a file that does not parse is left alone.
+ */
+export const syncPwshProfile = (dataPath, allowed) => {
+    const file = path.join(terminalDir(dataPath), 'settings', 'settings.json');
+    assertNoLinks(dataPath, file);
+    if (!fileExists(file) || fs.statSync(file).size > MAX_SETTINGS_BYTES)
+        return;
+    const visible = allowed && fileExists(path.join(dataPath, 'tools', 'pwsh', 'pwsh.exe'));
+    let parsed;
+    try {
+        const result = TerminalSettings.safeParse(parseJsonc(fs.readFileSync(file, 'utf8'), file));
+        if (!result.success)
+            return;
+        parsed = result.data;
+    }
+    catch {
+        return;
+    }
+    const next = withPwshProfile(parsed, visible);
+    if (next)
+        writeJson(file, next);
+};
+export const ensureTerminal = async (dataPath, refresh, options = {}) => {
+    const result = await installTerminal(dataPath, refresh);
+    if (result.exe) {
+        // The profile is a nicety: a settings problem never costs the sandbox its terminal.
+        try {
+            syncPwshProfile(dataPath, options.pwsh ?? false);
+        }
+        catch (e) {
+            return { ...result, message: result.message + ' (PowerShell 7 profile not updated: ' + errMsg(e) + ')' };
+        }
+    }
+    return result;
+};
+const installTerminal = async (dataPath, refresh) => {
+    const exe = terminalExe(dataPath);
+    const dir = terminalDir(dataPath);
+    const settings = path.join(dir, 'settings');
+    // installArchive replaces tools\terminal: the portable settings folder waits here meanwhile (and goes back also when
+    // the download fails). One still parked from an interrupted earlier run is the one to keep.
+    const parked = path.join(dataPath, 'tools', 'terminal-settings.parked');
+    assertNoLinks(dataPath, settings);
+    assertNoLinks(dataPath, parked);
+    if (fileExists(exe) && !refresh)
+        return { exe, message: 'cached' };
+    try {
+        if (fs.existsSync(settings)) {
+            safeRemove(parked, path.dirname(parked));
+            fs.renameSync(settings, parked);
+        }
+        try {
+            const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
+            const asset = await githubAsset('microsoft/terminal', new RegExp('^Microsoft\\.WindowsTerminal_[\\d.]+_' + arch + '\\.zip$'));
+            await installArchive(asset.url, dir, { sha256: asset.sha256, locate: 'WindowsTerminal.exe', fileName: asset.name });
+            fs.writeFileSync(path.join(dir, '.portable'), '');
+            return { exe, message: 'downloaded ' + asset.name };
+        }
+        finally {
+            if (fs.existsSync(parked)) {
+                fs.mkdirSync(dir, { recursive: true });
+                safeRemove(settings, path.dirname(settings));
+                fs.renameSync(parked, settings);
+            }
+            const settingsFile = path.join(settings, 'settings.json');
+            assertNoLinks(dataPath, settingsFile);
+            if (fileExists(path.join(dir, '.portable')) && !fs.existsSync(settingsFile))
+                writeJson(settingsFile, SETTINGS);
+        }
+    }
+    catch (e) {
+        return { exe: null, message: 'download failed, the sandbox will use a plain PowerShell window (' + errMsg(e) + ')' };
+    }
+};

package/dist/host/window.d.ts

@@ -0,0 +1,4 @@
+/** Waits for the sandbox window and hides it; keeps watching briefly in case Windows re-shows it while connecting. */
+export declare const hideSandboxWindow: (storageRoot: string, waitSeconds?: number) => Promise<boolean>;
+/** Shows the sandbox window again (the ones we hid, or any hidden Windows Sandbox window). */
+export declare const showSandboxWindow: (storageRoot: string) => boolean;

package/dist/host/window.js

@@ -0,0 +1,68 @@
+// Headless mode: Windows Sandbox always opens its client window, so we hide it (ShowWindow SW_HIDE) as soon as it
+// appears. The VM and the logged-in session keep running; `sbx-show` brings the window back.
+import path from 'node:path';
+import { isWin, runPowerShell, runPowerShellAsync, tryReadJson, writeJson } from '../core/util.js';
+const PRELUDE = `
+$ErrorActionPreference = 'Stop'
+Add-Type -Namespace AgentSandbox -Name Win -MemberDefinition @'
+public delegate bool EnumProc(System.IntPtr hWnd, System.IntPtr lParam);
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern bool EnumWindows(EnumProc cb, System.IntPtr lParam);
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(System.IntPtr hWnd, out uint pid);
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern bool IsWindowVisible(System.IntPtr hWnd);
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern bool IsWindow(System.IntPtr hWnd);
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern System.IntPtr GetWindow(System.IntPtr hWnd, uint cmd);
+[System.Runtime.InteropServices.DllImport("user32.dll", CharSet = System.Runtime.InteropServices.CharSet.Unicode)] public static extern int GetWindowText(System.IntPtr hWnd, System.Text.StringBuilder s, int n);
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern bool ShowWindow(System.IntPtr hWnd, int cmd);
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern bool SetForegroundWindow(System.IntPtr hWnd);
+'@
+function Get-SandboxWindows([bool]$visibleOnly) {
+  $pids = @(Get-Process | Where-Object { $_.ProcessName -like 'WindowsSandbox*' } | ForEach-Object { [uint32]$_.Id })
+  $found = New-Object System.Collections.ArrayList
+  if ($pids.Count -eq 0) { return $found }
+  $cb = [AgentSandbox.Win+EnumProc]{ param($h, $l)
+    $p = [uint32]0; [void][AgentSandbox.Win]::GetWindowThreadProcessId($h, [ref]$p)
+    if ($pids -contains $p -and [AgentSandbox.Win]::GetWindow($h, 4) -eq [IntPtr]::Zero) {
+      $sb = New-Object System.Text.StringBuilder 256; [void][AgentSandbox.Win]::GetWindowText($h, $sb, 256)
+      $title = $sb.ToString()
+      if ($title -like '*Sandbox*' -and (-not $visibleOnly -or [AgentSandbox.Win]::IsWindowVisible($h))) { [void]$found.Add([int64]$h) }
+    }
+    return $true }
+  [void][AgentSandbox.Win]::EnumWindows($cb, [IntPtr]::Zero)
+  return $found
+}
+`;
+const stateFile = (storageRoot) => path.join(storageRoot, 'run', 'hidden-windows.json');
+/** Waits for the sandbox window and hides it; keeps watching briefly in case Windows re-shows it while connecting. */
+export const hideSandboxWindow = async (storageRoot, waitSeconds = 180) => {
+    if (!isWin)
+        return false;
+    const script = PRELUDE + `
+$hidden = New-Object System.Collections.ArrayList
+$deadline = (Get-Date).AddSeconds(${waitSeconds}); $settle = $null
+while ((Get-Date) -lt $deadline) {
+  foreach ($h in (Get-SandboxWindows $true)) { [void][AgentSandbox.Win]::ShowWindow([IntPtr]$h, 0); if (-not $hidden.Contains($h)) { [void]$hidden.Add($h) } }
+  if ($hidden.Count -gt 0 -and $null -eq $settle) { $settle = (Get-Date).AddSeconds(15) }
+  if ($null -ne $settle -and (Get-Date) -gt $settle) { break }
+  Start-Sleep -Milliseconds 200
+}
+ConvertTo-Json -Compress @($hidden)`;
+    const stdout = await runPowerShellAsync(script);
+    const handles = JSON.parse(stdout.trim() || '[]').filter((h) => Number.isSafeInteger(h));
+    writeJson(stateFile(storageRoot), { handles });
+    return handles.length > 0;
+};
+/** Shows the sandbox window again (the ones we hid, or any hidden Windows Sandbox window). */
+export const showSandboxWindow = (storageRoot) => {
+    if (!isWin)
+        return false;
+    // Only integers go into the script, whatever the file contains.
+    const recorded = (tryReadJson(stateFile(storageRoot))?.handles ?? []).filter((h) => Number.isSafeInteger(h));
+    const script = PRELUDE + `
+$handles = @(${recorded.join(',')}) | Where-Object { [AgentSandbox.Win]::IsWindow([IntPtr]$_) }
+if (-not $handles) { $handles = Get-SandboxWindows $false }
+foreach ($h in $handles) { [void][AgentSandbox.Win]::ShowWindow([IntPtr]$h, 5); [void][AgentSandbox.Win]::ShowWindow([IntPtr]$h, 9); [void][AgentSandbox.Win]::SetForegroundWindow([IntPtr]$h) }
+@($handles).Count`;
+    const { stdout } = runPowerShell(script, true);
+    writeJson(stateFile(storageRoot), { handles: [] });
+    return Number(stdout.trim()) > 0;
+};