windows-development-sandbox 1.4.1 → 1.4.3

package/dist/host/secrets.js

@@ -1,133 +0,0 @@
-// 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/stops.d.ts

@@ -1,67 +0,0 @@
-import { type ChildProcess } from 'node:child_process';
-import { z } from 'zod';
-declare const Life: z.ZodObject<{
-    started: z.ZodString;
-    lastSeen: z.ZodString;
-    keepAwake: z.ZodBoolean;
-    ended: z.ZodOptional<z.ZodObject<{
-        at: z.ZodString;
-        cause: z.ZodNullable<z.ZodObject<{
-            kind: z.ZodEnum<{
-                restart: "restart";
-                updates: "updates";
-                crash: "crash";
-                sleep: "sleep";
-                memory: "memory";
-                sandboxCrash: "sandboxCrash";
-            }>;
-            at: z.ZodString;
-            text: z.ZodString;
-        }, z.core.$strip>>;
-    }, z.core.$strip>>;
-    reported: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip>;
-type LifeT = z.infer<typeof Life>;
-export declare const readLife: (storageRoot: string, dataPath: string) => LifeT | null;
-/** At launch: a fresh record (the previous one has been reported by then). */
-export declare const startLife: (storageRoot: string, dataPath: string, keepAwake: boolean, now?: Date) => void;
-/** Every minute while the sandbox runs. */
-export declare const beatLife: (storageRoot: string, dataPath: string, now?: Date) => void;
-/** The watcher saw the sandbox close while this PC kept running: closed by you (no cause), or by sleep / low memory. */
-export declare const endLife: (storageRoot: string, dataPath: string, cause: StopCause | null, now?: Date) => void;
-export interface StopEvent {
-    at: string;
-    id: number;
-    provider: string;
-    process: string;
-}
-export type StopKind = 'updates' | 'restart' | 'crash' | 'sleep' | 'memory' | 'sandboxCrash';
-export interface StopCause {
-    kind: StopKind;
-    at: string;
-    text: string;
-}
-/**
- * The first event that ends a running sandbox (pure): Windows inside the sandbox crashing (Hyper-V 18590; `process`
- * holds its message with the stop code), a restart or shutdown, a crash or power loss, sleep, low memory. Switching
- * user does not end it (seen on 13 Oct 2026: the sandbox ran on after a switch).
- */
-export declare const explainStop: (events: StopEvent[]) => StopCause | null;
-/** System log and Hyper-V events since `since` that can end a sandbox (Windows only; empty when the logs cannot be read). */
-export declare const readStopEvents: (since: Date) => StopEvent[];
-/** Looking back from the last time the sandbox was seen running (a minute between checks, plus margin). */
-export declare const causeSince: (lastSeen: string) => StopCause | null;
-/**
- * At launch: one warning when the last sandbox ended without anyone closing it (the PC restarted, crashed, slept or ran
- * out of memory), then never again for that run. `watcherAlive` = its watcher is still running (then it did not end).
- */
-export declare const lastStopWarning: (storageRoot: string, dataPath: string, watcherAlive: boolean, find?: (lastSeen: string) => StopCause | null) => string | null;
-/** Windows has installed updates and waits to restart: it may do so on its own, outside your active hours. */
-export declare const updateRestartPending: () => boolean;
-export declare const UPDATE_RESTART_WARNING = "Windows is waiting to restart for updates and may do so on its own (often overnight), which closes the sandbox. Restart first, or pause updates: Settings > Windows Update > Pause updates.";
-/**
- * sandbox.keepAwake: asks Windows not to sleep while the sandbox runs (as a video player does; the screen may still turn
- * off). A small PowerShell holds the request until `ownerPid` exits, so it never outlives the watcher.
- */
-export declare const keepAwake: (ownerPid: number) => ChildProcess | null;
-export {};

package/dist/host/stops.js

@@ -1,126 +0,0 @@
-// Why the last sandbox stopped, when nobody stopped it. The background watcher writes a host-only "life" record (when
-// the sandbox started, when it was last seen running, how it ended) and keeps this PC awake while it runs
-// (sandbox.keepAwake). When the PC restarts, sleeps or crashes, the watcher stops too and the record has no end: the
-// next launch reads Windows' System log from that moment on and says what happened, and what keeps it from happening.
-import { spawn, spawnSync } from 'node:child_process';
-import path from 'node:path';
-import { z } from 'zod';
-import { SYSTEM } from '../shared/system.js';
-import { readValid, writeJsonAtomic } from '../shared/rundir.js';
-import { isWin } from '../core/util.js';
-import { refuseInSelfTest } from './test-guard.js';
-const Iso = z.string().max(40);
-const Life = z.object({
-    started: Iso, lastSeen: Iso, keepAwake: z.boolean(),
-    ended: z.object({ at: Iso, cause: z.object({ kind: z.enum(['updates', 'restart', 'crash', 'sleep', 'memory', 'sandboxCrash']), at: Iso, text: z.string().max(400) }).nullable() }).optional(),
-    reported: z.boolean().optional(),
-});
-const lifeFile = (storageRoot, dataPath) => path.join(storageRoot, 'sync', path.basename(dataPath) + '-life.json');
-export const readLife = (storageRoot, dataPath) => readValid(Life, lifeFile(storageRoot, dataPath));
-const writeLife = (storageRoot, dataPath, life) => writeJsonAtomic(lifeFile(storageRoot, dataPath), life);
-/** At launch: a fresh record (the previous one has been reported by then). */
-export const startLife = (storageRoot, dataPath, keepAwake, now = new Date()) => writeLife(storageRoot, dataPath, { started: now.toISOString(), lastSeen: now.toISOString(), keepAwake });
-/** Every minute while the sandbox runs. */
-export const beatLife = (storageRoot, dataPath, now = new Date()) => {
-    const life = readLife(storageRoot, dataPath);
-    if (life && !life.ended)
-        writeLife(storageRoot, dataPath, { ...life, lastSeen: now.toISOString() });
-};
-/** The watcher saw the sandbox close while this PC kept running: closed by you (no cause), or by sleep / low memory. */
-export const endLife = (storageRoot, dataPath, cause, now = new Date()) => {
-    const life = readLife(storageRoot, dataPath);
-    if (life && !life.ended)
-        writeLife(storageRoot, dataPath, { ...life, ended: { at: now.toISOString(), cause } });
-};
-const StopEvents = z.array(z.object({ at: Iso, id: z.number().int(), provider: z.string().max(200), process: z.string().max(400).nullable().transform((p) => p ?? '') })).max(100);
-const UPDATERS = /^(trustedinstaller|mousocoreworker|musnotification(ux)?|usoclient|wuauclt|tiworker|updateorchestrator)\.exe$/i;
-/**
- * The first event that ends a running sandbox (pure): Windows inside the sandbox crashing (Hyper-V 18590; `process`
- * holds its message with the stop code), a restart or shutdown, a crash or power loss, sleep, low memory. Switching
- * user does not end it (seen on 13 Oct 2026: the sandbox ran on after a switch).
- */
-export const explainStop = (events) => {
-    const causes = events.flatMap((e) => {
-        const p = e.provider.toLowerCase();
-        if (e.id === 1074 && p.includes('user32')) {
-            const exe = e.process.split(/[\\/]/).pop()?.replace(/\s*\(.*$/, '') ?? '';
-            return UPDATERS.test(exe)
-                ? [{ kind: 'updates', at: e.at, text: 'Windows restarted this PC to install updates' }]
-                : [{ kind: 'restart', at: e.at, text: 'this PC was restarted or shut down' + (exe ? ' (by ' + exe + ')' : '') }];
-        }
-        if ((e.id === 41 && p.includes('kernel-power')) || (e.id === 6008 && p.includes('eventlog')))
-            return [{ kind: 'crash', at: e.at, text: 'Windows stopped unexpectedly (a crash, a power cut, or the power button held down)' }];
-        if (e.id === 42 && p.includes('kernel-power'))
-            return [{ kind: 'sleep', at: e.at, text: 'this PC went to sleep or hibernated' }];
-        if (e.id === 2004 && p.includes('resource-exhaustion'))
-            return [{ kind: 'memory', at: e.at, text: 'this PC ran out of memory' }];
-        if (e.id === 18590 && p.includes('hyper-v-worker')) {
-            const code = /ErrorCode0:\s*(0x[0-9a-f]{1,8})/i.exec(e.process)?.[1];
-            const sub = /ErrorCode1:\s*(0x[0-9a-f]{1,16})/i.exec(e.process)?.[1];
-            return [{ kind: 'sandboxCrash', at: e.at, text: 'Windows inside the sandbox crashed' + (code ? ' (stop code ' + code + (sub ? ', ' + sub : '') + ')' : '') }];
-        }
-        return [];
-    });
-    return causes.sort((a, b) => Date.parse(a.at) - Date.parse(b.at))[0] ?? null;
-};
-const ADVICE = {
-    updates: 'Before leaving agents overnight, restart for pending updates first or pause them (Settings > Windows Update > Pause updates).',
-    restart: 'If that was not you, check Settings > Windows Update and Event Viewer > Windows Logs > System.',
-    crash: 'Event Viewer > Windows Logs > System has the details; a laptop also needs to stay plugged in.',
-    sleep: 'sandbox.keepAwake keeps this PC awake while a sandbox runs (closing a laptop lid still sleeps it). Check it is on, and that sleep is not forced by a policy.',
-    sandboxCrash: 'C:\\AgentData\\logs\\memory-*.log shows what used memory just before. Fewer builds at once inside the sandbox (e.g. cargo build.jobs) makes it less likely.',
-    memory: 'Give the sandbox less RAM (sandbox.maxMemoryMb, sandbox.reserveHostMb) or run fewer builds at once inside it.',
-};
-/** System log and Hyper-V events since `since` that can end a sandbox (Windows only; empty when the logs cannot be read). */
-export const readStopEvents = (since) => {
-    if (!isWin)
-        return [];
-    refuseInSelfTest('read the Windows event log');
-    const script = "$ErrorActionPreference='SilentlyContinue'; $t=[datetime]::Parse('" + since.toISOString() + "').ToLocalTime(); $e = Get-WinEvent -FilterHashtable @(@{LogName='System'; Id=1074,6008,41,42,2004; StartTime=$t}, @{LogName='Microsoft-Windows-Hyper-V-Worker-Admin'; Id=18590; StartTime=$t}) -MaxEvents 100 | ForEach-Object { [pscustomobject]@{ at=$_.TimeCreated.ToUniversalTime().ToString('o'); id=$_.Id; provider=$_.ProviderName; process=$(if ($_.Id -eq 1074) { [string]$_.Properties[0].Value } elseif ($_.Id -eq 18590) { ([string]$_.Message).Substring(0, [math]::Min(390, ([string]$_.Message).Length)) } else { '' }) } }; ConvertTo-Json -Compress -InputObject @($e)";
-    const result = spawnSync(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')], { encoding: 'utf8', windowsHide: true, timeout: 60000 });
-    try {
-        return StopEvents.parse(JSON.parse(result.stdout || '[]'));
-    }
-    catch {
-        return [];
-    }
-};
-/** Looking back from the last time the sandbox was seen running (a minute between checks, plus margin). */
-export const causeSince = (lastSeen) => explainStop(readStopEvents(new Date(Date.parse(lastSeen) - 2 * 60 * 1000)));
-const when = (iso) => new Date(iso).toLocaleString(undefined, { weekday: 'short', hour: '2-digit', minute: '2-digit' });
-/**
- * At launch: one warning when the last sandbox ended without anyone closing it (the PC restarted, crashed, slept or ran
- * out of memory), then never again for that run. `watcherAlive` = its watcher is still running (then it did not end).
- */
-export const lastStopWarning = (storageRoot, dataPath, watcherAlive, find = causeSince) => {
-    const life = readLife(storageRoot, dataPath);
-    if (!life || life.reported || watcherAlive)
-        return null;
-    writeLife(storageRoot, dataPath, { ...life, reported: true });
-    if (life.ended && !life.ended.cause)
-        return null;
-    const cause = life.ended ? life.ended.cause : find(life.lastSeen);
-    const what = cause ? cause.text + ' at ' + when(cause.at) + '. ' + ADVICE[cause.kind] : 'this PC stopped (Windows logged no reason). ' + ADVICE.crash;
-    return 'The last sandbox did not close normally: it was last seen running at ' + when(life.lastSeen) + ', and ' + what + ' Agent conversations are kept: /resume in Claude picks one up.';
-};
-// ---- Windows Update and keeping awake ----------------------------------------------------------------------------
-/** Windows has installed updates and waits to restart: it may do so on its own, outside your active hours. */
-export const updateRestartPending = () => isWin && [
-    'HKLM\\SOFTWARE\\Microsoft\\WindowsUpdate\\Auto Update\\RebootRequired',
-    'HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Component Based Servicing\\RebootPending',
-].some((key) => spawnSync(SYSTEM.reg(), ['query', key], { windowsHide: true, stdio: 'ignore', timeout: 15000 }).status === 0);
-export const UPDATE_RESTART_WARNING = 'Windows is waiting to restart for updates and may do so on its own (often overnight), which closes the sandbox. Restart first, or pause updates: Settings > Windows Update > Pause updates.';
-/**
- * sandbox.keepAwake: asks Windows not to sleep while the sandbox runs (as a video player does; the screen may still turn
- * off). A small PowerShell holds the request until `ownerPid` exits, so it never outlives the watcher.
- */
-export const keepAwake = (ownerPid) => {
-    if (!isWin)
-        return null;
-    refuseInSelfTest('keep this PC awake');
-    const script = "Add-Type -Name Power -Namespace AgentSandbox -MemberDefinition '[DllImport(\"kernel32.dll\")] public static extern uint SetThreadExecutionState(uint f);'; "
-        + '[void][AgentSandbox.Power]::SetThreadExecutionState([uint32]2147483649); Wait-Process -Id ' + Math.trunc(ownerPid) + ' -ErrorAction SilentlyContinue';
-    const child = spawn(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')], { stdio: 'ignore', windowsHide: true });
-    child.on('error', () => undefined);
-    return child;
-};

package/dist/shared/apps.js

@@ -1,114 +0,0 @@
-export const APP_CATEGORIES = [
-    { id: 'editors', label: 'Editors & IDEs', description: 'Code and text editors (VS Code is a setting of its own and on by default).' },
-    { id: 'databases', label: 'Database clients', description: 'GUIs for the databases the sandbox runs (PostgreSQL, MySQL, MongoDB, Redis, SQLite, DynamoDB).' },
-    { id: 'api', label: 'API clients', description: 'Send HTTP, REST and GraphQL requests to what you are building.' },
-    { id: 'git', label: 'Git tools', description: 'Git GUIs and terminal UIs. They use the sandbox\'s git, so its git access rules apply.' },
-    { id: 'utilities', label: 'Utilities', description: 'Archives, comparing files, finding files, process tools, hex editing.' },
-    { id: 'browsers', label: 'Browsers', description: 'Browsers for testing web apps (Edge is already in Windows).' },
-    { id: 'gamedev', label: 'Game development', description: 'Engines and editors. They draw with OpenGL on the CPU (Mesa) when the sandbox has no GPU.' },
-    { id: 'cloud', label: 'Cloud & Kubernetes', description: 'Command-line tools for clouds, Kubernetes and infrastructure as code.' },
-    { id: 'diagrams', label: 'Diagrams & docs', description: 'Diagrams and document conversion.' },
-    { id: 'network', label: 'Network & HTTP', description: 'Inspect and test HTTP traffic and APIs.' },
-    { id: 'cli', label: 'Command-line tools', description: 'Small tools developers reach for: JSON and YAML, search, diff, builds, media, load testing ...' },
-];
-const gh = (github, asset) => ({ github, asset });
-export const APPS = [
-    // ---- editors
-    { id: 'vscode', name: 'Visual Studio Code', category: 'editors', about: 'Code editor with debugging, set up for the sandbox\'s languages.', size: '150 MB', source: { resolve: 'setting' }, exe: 'Code.exe', setting: 'toolchains.vscode.enabled' },
-    { id: 'windows-terminal', name: 'Windows Terminal', category: 'utilities', about: 'The sandbox window: tabs, panes, PowerShell 7 profile.', size: '40 MB', source: { resolve: 'setting' }, exe: 'WindowsTerminal.exe', setting: 'provisioning.terminal.enabled' },
-    { id: 'notepadpp', name: 'Notepad++', category: 'editors', about: 'Fast text and code editor.', size: '8 MB', source: gh('notepad-plus-plus/notepad-plus-plus', '^npp\\.[\\d.]+\\.portable\\.x64\\.zip$'), exe: 'notepad++.exe' },
-    { id: 'sublime', name: 'Sublime Text', category: 'editors', about: 'Fast code editor (paid licence, free to evaluate).', size: '28 MB', source: { resolve: 'sublime' }, exe: 'sublime_text.exe' },
-    { id: 'neovim', name: 'Neovim', category: 'editors', about: 'Terminal text editor (nvim).', size: '12 MB', source: gh('neovim/neovim', '^nvim-win64\\.zip$'), exe: 'nvim.exe', cli: true },
-    // ---- database clients
-    { id: 'dbeaver', name: 'DBeaver Community', category: 'databases', about: 'Universal database client: PostgreSQL, MySQL, SQLite, SQL Server and more.', size: '120 MB', source: gh('dbeaver/dbeaver', '^dbeaver-ce-[\\d.]+-windows-x86_64\\.zip$'), exe: 'dbeaver.exe' },
-    { id: 'pgadmin', name: 'pgAdmin 4', category: 'databases', about: 'The PostgreSQL admin GUI (from the PostgreSQL binaries zip).', size: '330 MB', source: { resolve: 'pgadmin' }, exe: 'pgAdmin4.exe' },
-    { id: 'heidisql', name: 'HeidiSQL', category: 'databases', about: 'Light client for MySQL, MariaDB, PostgreSQL and SQL Server.', size: '28 MB', source: gh('HeidiSQL/HeidiSQL', '^HeidiSQL_[\\d.]+_64_Portable\\.zip$'), exe: 'heidisql.exe' },
-    { id: 'sqlitebrowser', name: 'DB Browser for SQLite', category: 'databases', about: 'Open, browse and edit SQLite files.', size: '21 MB', source: gh('sqlitebrowser/sqlitebrowser', '^DB\\.Browser\\.for\\.SQLite-v?[\\d.]+-win64\\.zip$'), exe: 'DB Browser for SQLite.exe' },
-    { id: 'compass', name: 'MongoDB Compass', category: 'databases', about: 'The MongoDB GUI.', size: '220 MB', source: gh('mongodb-js/compass', '^mongodb-compass-[\\d.]+-win32-x64\\.zip$'), exe: 'MongoDBCompass.exe' },
-    { id: 'redisinsight', name: 'Redis Insight', category: 'databases', about: 'The Redis GUI.', size: '110 MB', source: gh('redis/RedisInsight', '^Redis-Insight-win-installer\\.exe$'), unpack: 'nsis', exe: 'Redis Insight.exe', needs: ['7zip'] },
-    { id: 'dbgate', name: 'DbGate', category: 'databases', about: 'Database manager for SQL and NoSQL databases.', size: '180 MB', source: gh('dbgate/dbgate', '^dbgate-[\\d.]+-win_x64\\.zip$'), exe: 'DbGate.exe' },
-    { id: 'beekeeper', name: 'Beekeeper Studio', category: 'databases', about: 'SQL editor and database manager.', size: '245 MB', source: gh('beekeeper-studio/beekeeper-studio', '^Beekeeper-Studio-[\\d.]+-portable\\.exe$'), unpack: 'nsis', exe: 'Beekeeper Studio.exe', needs: ['7zip'] },
-    { id: 'dynamodb-admin', name: 'dynamodb-admin', category: 'databases', about: 'Web GUI for DynamoDB Local: run dynamodb-admin, then open http://localhost:8001.', size: '5 MB', source: { npm: 'dynamodb-admin' }, exe: 'dynamodb-admin.cmd', cli: true },
-    // ---- API clients
-    { id: 'bruno', name: 'Bruno', category: 'api', about: 'Offline, git-friendly API client (collections are files in your repo).', size: '175 MB', source: gh('usebruno/bruno', '^bruno_[\\d.]+_x64_win\\.zip$'), exe: 'Bruno.exe' },
-    { id: 'insomnia', name: 'Insomnia', category: 'api', about: 'REST, GraphQL and gRPC client.', size: '590 MB', source: gh('Kong/insomnia', '^insomnia-[\\d.]+-full\\.nupkg$'), exe: 'Insomnia.exe' },
-    // ---- git
-    { id: 'sourcegit', name: 'SourceGit', category: 'git', about: 'Fast open-source Git GUI.', size: '26 MB', source: gh('sourcegit-scm/sourcegit', '^sourcegit_[\\d.]+\\.win-x64\\.zip$'), exe: 'SourceGit.exe' },
-    { id: 'githubdesktop', name: 'GitHub Desktop', category: 'git', about: 'Simple Git GUI from GitHub. It has its own git, so it needs provisioning.git.access "full".', size: '300 MB', source: gh('desktop/desktop', '^GitHubDesktop-[\\d.]+-x64-full\\.nupkg$'), exe: 'GitHubDesktop.exe', fullGitOnly: true },
-    { id: 'lazygit', name: 'lazygit', category: 'git', about: 'Git in the terminal.', size: '7 MB', source: gh('jesseduffield/lazygit', '^lazygit_[\\d.]+_windows_x86_64\\.zip$'), exe: 'lazygit.exe', cli: true },
-    // ---- utilities
-    { id: '7zip', name: '7-Zip', category: 'utilities', about: 'Archive manager (7z, zip, rar, tar ...). Also unpacks installers for other apps.', size: '2 MB', source: { resolve: '7zip' }, exe: '7zFM.exe' },
-    { id: 'winmerge', name: 'WinMerge', category: 'utilities', about: 'Compare and merge files and folders.', size: '23 MB', source: gh('WinMerge/winmerge', '^winmerge-[\\d.]+-x64-exe\\.zip$'), exe: 'WinMergeU.exe' },
-    { id: 'everything', name: 'Everything', category: 'utilities', about: 'Finds files by name instantly.', size: '2 MB', source: { resolve: 'everything' }, exe: 'Everything.exe' },
-    { id: 'sysinternals', name: 'Sysinternals Suite', category: 'utilities', about: 'Process Explorer, Process Monitor, Autoruns, TCPView and more (on PATH).', size: '200 MB', source: { url: 'https://download.sysinternals.com/files/SysinternalsSuite.zip' }, exe: 'procexp64.exe' },
-    { id: 'imhex', name: 'ImHex', category: 'utilities', about: 'Hex editor for reverse engineering and binary formats.', size: '80 MB', source: gh('WerWolv/ImHex', '^imhex-[\\d.]+-Windows-Portable-NoGPU-x86_64\\.zip$'), exe: 'imhex-gui.exe' },
-    // ---- browsers
-    { id: 'chrome', name: 'Chrome for Testing', category: 'browsers', about: 'Chrome build made for automated tests (with chromedriver on PATH).', size: '170 MB', source: { resolve: 'chrome' }, exe: 'chrome.exe' },
-    { id: 'firefox', name: 'Firefox', category: 'browsers', about: 'Firefox for testing.', size: '75 MB', source: { resolve: 'firefox' }, unpack: 'nsis', exe: 'firefox.exe', needs: ['7zip'] },
-    // ---- game development
-    { id: 'godot', name: 'Godot', category: 'gamedev', about: 'Open-source 2D and 3D game engine.', size: '80 MB', source: gh('godotengine/godot', '^Godot_v[\\d.]+-stable_win64\\.exe\\.zip$'), exe: '/^Godot_v[\\d.]+-stable_win64\\.exe$/', needs: ['mesa'] },
-    { id: 'blender', name: 'Blender', category: 'gamedev', about: '3D modelling, animation and rendering.', size: '400 MB', source: { resolve: 'blender' }, exe: 'blender.exe', needs: ['mesa'] },
-    { id: 'love', name: 'LÖVE', category: 'gamedev', about: 'Lua framework for 2D games.', size: '4 MB', source: gh('love2d/love', '^love-[\\d.]+-win64\\.zip$'), exe: 'love.exe', needs: ['mesa'] },
-    { id: 'defold', name: 'Defold', category: 'gamedev', about: 'Free 2D/3D game engine and editor.', size: '330 MB', source: gh('defold/defold', '^Defold-x86_64-win32\\.zip$'), exe: 'Defold.exe', needs: ['mesa'] },
-    { id: 'pixelorama', name: 'Pixelorama', category: 'gamedev', about: 'Pixel-art and sprite editor.', size: '40 MB', source: gh('Orama-Interactive/Pixelorama', '^Pixelorama-Windows-64bit\\.zip$'), exe: 'Pixelorama.exe', needs: ['mesa'] },
-    { id: 'tiled', name: 'Tiled', category: 'gamedev', about: 'Tile map editor.', size: '22 MB', source: gh('mapeditor/tiled', '^Tiled-[\\d.]+_Windows-10\\+_x86_64\\.msi$'), unpack: 'msi', exe: 'tiled.exe' },
-    // ---- cloud
-    { id: 'kubectl', name: 'kubectl', category: 'cloud', about: 'Kubernetes command line.', size: '60 MB', source: { resolve: 'kubectl' }, unpack: 'file', exe: 'kubectl.exe', cli: true },
-    { id: 'helm', name: 'Helm', category: 'cloud', about: 'Kubernetes package manager.', size: '20 MB', source: { resolve: 'helm' }, exe: 'helm.exe', cli: true },
-    { id: 'k9s', name: 'k9s', category: 'cloud', about: 'Kubernetes cluster UI in the terminal.', size: '40 MB', source: gh('derailed/k9s', '^k9s_Windows_amd64\\.zip$'), exe: 'k9s.exe', cli: true },
-    { id: 'terraform', name: 'Terraform', category: 'cloud', about: 'Infrastructure as code.', size: '30 MB', source: { resolve: 'terraform' }, exe: 'terraform.exe', cli: true },
-    { id: 'azure-cli', name: 'Azure CLI', category: 'cloud', about: 'Manage Azure (az).', size: '90 MB', source: { url: 'https://aka.ms/installazurecliwindowszipx64' }, exe: 'az.cmd', cli: true },
-    { id: 'gcloud', name: 'Google Cloud CLI', category: 'cloud', about: 'Manage Google Cloud (gcloud, gsutil, bq).', size: '120 MB', source: { url: 'https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-windows-x86_64-bundled-python.zip' }, exe: 'gcloud.cmd', cli: true },
-    { id: 'aws-cli', name: 'AWS CLI', category: 'cloud', about: 'Manage AWS (aws).', size: '50 MB', source: { url: 'https://awscli.amazonaws.com/AWSCLIV2.msi' }, unpack: 'msi', exe: 'aws.exe', cli: true },
-    // ---- diagrams and docs
-    { id: 'drawio', name: 'draw.io', category: 'diagrams', about: 'Diagram editor (flowcharts, architecture, UML).', size: '170 MB', source: gh('jgraph/drawio-desktop', '^draw\\.io-[\\d.]+-windows\\.zip$'), exe: 'draw.io.exe' },
-    { id: 'pandoc', name: 'Pandoc', category: 'diagrams', about: 'Convert documents between Markdown, HTML, Word, PDF ...', size: '35 MB', source: gh('jgm/pandoc', '^pandoc-[\\d.]+-windows-x86_64\\.zip$'), exe: 'pandoc.exe', cli: true },
-    // ---- network
-    { id: 'mitmproxy', name: 'mitmproxy', category: 'network', about: 'Intercepting HTTPS proxy (mitmweb opens a web UI).', size: '90 MB', source: { resolve: 'mitmproxy' }, exe: 'mitmweb.exe', cli: true },
-    { id: 'xh', name: 'xh', category: 'network', about: 'Friendly HTTP requests from the terminal (like HTTPie).', size: '5 MB', source: gh('ducaale/xh', '^xh-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'xh.exe', cli: true },
-    { id: 'grpcurl', name: 'grpcurl', category: 'network', about: 'curl for gRPC servers.', size: '10 MB', source: gh('fullstorydev/grpcurl', '^grpcurl_[\\d.]+_windows_x86_64\\.zip$'), exe: 'grpcurl.exe', cli: true },
-    { id: 'k6', name: 'k6', category: 'network', about: 'Load testing with JavaScript scripts.', size: '30 MB', source: gh('grafana/k6', '^k6-v[\\d.]+-windows-amd64\\.zip$'), exe: 'k6.exe', cli: true },
-    // ---- command-line tools
-    { id: 'jq', name: 'jq', category: 'cli', about: 'Query and reshape JSON.', size: '1 MB', source: gh('jqlang/jq', '^jq-windows-amd64\\.exe$'), unpack: 'file', exe: 'jq.exe', cli: true },
-    { id: 'yq', name: 'yq', category: 'cli', about: 'Query and edit YAML, JSON, XML and TOML.', size: '10 MB', source: gh('mikefarah/yq', '^yq_windows_amd64\\.exe$'), unpack: 'file', exe: 'yq.exe', cli: true },
-    { id: 'ripgrep', name: 'ripgrep', category: 'cli', about: 'Very fast recursive search (rg).', size: '2 MB', source: gh('BurntSushi/ripgrep', '^ripgrep-[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'rg.exe', cli: true },
-    { id: 'fd', name: 'fd', category: 'cli', about: 'Fast, friendly alternative to find.', size: '2 MB', source: gh('sharkdp/fd', '^fd-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'fd.exe', cli: true },
-    { id: 'bat', name: 'bat', category: 'cli', about: 'cat with syntax highlighting and git changes.', size: '3 MB', source: gh('sharkdp/bat', '^bat-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'bat.exe', cli: true },
-    { id: 'fzf', name: 'fzf', category: 'cli', about: 'Fuzzy finder for the terminal.', size: '2 MB', source: gh('junegunn/fzf', '^fzf-[\\d.]+-windows_amd64\\.zip$'), exe: 'fzf.exe', cli: true },
-    { id: 'delta', name: 'delta', category: 'cli', about: 'Readable git diffs with syntax highlighting.', size: '3 MB', source: gh('dandavison/delta', '^delta-[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'delta.exe', cli: true },
-    { id: 'just', name: 'just', category: 'cli', about: 'Command runner (a simpler make for project tasks).', size: '2 MB', source: gh('casey/just', '^just-[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'just.exe', cli: true },
-    { id: 'hyperfine', name: 'hyperfine', category: 'cli', about: 'Benchmark commands.', size: '1 MB', source: gh('sharkdp/hyperfine', '^hyperfine-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'hyperfine.exe', cli: true },
-    { id: 'watchexec', name: 'watchexec', category: 'cli', about: 'Run a command when files change.', size: '5 MB', source: gh('watchexec/watchexec', '^watchexec-[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'watchexec.exe', cli: true },
-    { id: 'protoc', name: 'protoc', category: 'cli', about: 'Protocol Buffers compiler.', size: '3 MB', source: gh('protocolbuffers/protobuf', '^protoc-[\\d.]+-win64\\.zip$'), exe: 'protoc.exe', cli: true },
-    { id: 'ninja', name: 'Ninja', category: 'cli', about: 'Small, fast build system (CMake\'s favourite generator).', size: '1 MB', source: gh('ninja-build/ninja', '^ninja-win\\.zip$'), exe: 'ninja.exe', cli: true },
-    { id: 'ffmpeg', name: 'FFmpeg', category: 'cli', about: 'Convert and process audio and video.', size: '200 MB', source: gh('BtbN/FFmpeg-Builds', '^ffmpeg-master-latest-win64-gpl\\.zip$'), exe: 'ffmpeg.exe', cli: true },
-    { id: 'sqlite', name: 'SQLite tools', category: 'cli', about: 'sqlite3 command-line shell.', size: '5 MB', source: { resolve: 'sqlite' }, exe: 'sqlite3.exe', cli: true },
-    { id: 'shellcheck', name: 'ShellCheck', category: 'cli', about: 'Finds bugs in shell scripts.', size: '10 MB', source: gh('koalaman/shellcheck', '^shellcheck-v[\\d.]+\\.zip$'), exe: 'shellcheck.exe', cli: true },
-    { id: 'gitleaks', name: 'Gitleaks', category: 'cli', about: 'Finds secrets committed to git.', size: '8 MB', source: gh('gitleaks/gitleaks', '^gitleaks_[\\d.]+_windows_x64\\.zip$'), exe: 'gitleaks.exe', cli: true },
-];
-export const appById = (id) => APPS.find((a) => a.id === id);
-/** A catalogue `exe` that is a regex ("/.../") matches names with a version in them. */
-export const exeMatcher = (exe) => {
-    const regex = /^\/(.+)\/$/.exec(exe);
-    if (regex) {
-        const r = new RegExp(regex[1], 'i');
-        return (name) => r.test(name);
-    }
-    return (name) => name.toLowerCase() === exe.toLowerCase();
-};
-/** Your own program as a catalogue entry (its folder is apps\custom\<id>). */
-const customEntry = (id, app) => ({
-    id: 'custom/' + id, name: app.name, category: 'utilities', about: 'Your own program.', size: '?',
-    source: app.github && app.asset ? { github: app.github, asset: app.asset } : { url: app.url },
-    unpack: app.unpack, exe: app.exe, cli: app.cli,
-});
-/** The apps to install, in order: 7-Zip first when anything needs it to unpack. */
-export const appsToInstall = (apps, gitAccess) => {
-    const chosen = apps.install.flatMap((id) => { const e = appById(id); return e && !e.setting ? [e] : []; });
-    const skipped = chosen.filter((e) => e.fullGitOnly && gitAccess !== 'full').map((e) => e.name + ' (needs provisioning.git.access "full")');
-    const allowed = [...chosen.filter((e) => !(e.fullGitOnly && gitAccess !== 'full')), ...Object.entries(apps.custom).map(([id, app]) => customEntry(id, app))];
-    const needs7zip = allowed.some((e) => e.needs?.includes('7zip') || e.unpack === 'nsis') && !allowed.some((e) => e.id === '7zip');
-    return { entries: [...(needs7zip ? [appById('7zip')] : []), ...allowed], skipped };
-};
-/** Does any chosen app draw with OpenGL (so the Mesa step must run first)? */
-export const appsNeedMesa = (apps) => Boolean(apps?.install.some((id) => appById(id)?.needs?.includes('mesa')));

package/dist/shared/download.d.ts

@@ -1,63 +0,0 @@
-/**
- * A fresh `<destination>.staging-<hex>` folder next to `destination`: fill it, then moveIntoPlace. An interrupted copy
- * or extraction leaves only the staging folder (cleanup/repair remove those), never a half-filled destination.
- */
-export declare const stagingFolder: (destination: string) => string;
-/** Replaces `destination` with the finished `work` folder (a folder rename: the destination is never half there). */
-export declare const moveIntoPlace: (work: string, destination: string) => void;
-/** fetch with retries (the sandbox network can take a few seconds to come up) and a timeout per attempt. */
-export declare const fetchRetry: (url: string, init?: RequestInit, attempts?: number, timeoutMs?: number) => Promise<Response>;
-/** Small lookups fail fast (2 tries, 20 s each) so an offline boot falls back to cached versions quickly. */
-export declare const fetchJson: <T>(url: string) => Promise<T>;
-export declare const fetchText: (url: string) => Promise<string>;
-/** Expected checksums of a download; any that are given must match. */
-export interface Checksums {
-    sha256?: string | null;
-    sha512?: string | null;
-}
-/** downloads.requireChecksum: from then on download() refuses anything it has no expected hash for. The guest sets it from session.json. */
-export declare const setChecksumRequired: (on: boolean) => void;
-/** Who wants coarse download progress: called as a download starts (in the caller's async context), returns its reporter. */
-export type DownloadWatcher = () => ((fraction: number) => void) | null;
-export declare const watchDownloads: (watcher: DownloadWatcher | null) => void;
-/**
- * Streams a download to disk, hashing as it goes: big archives (PostgreSQL is ~330 MB) never sit in memory, and the
- * event loop stays free so other toolchains keep downloading meanwhile. A mismatch (or any failure) leaves no file behind.
- */
-export declare const download: (url: string, destination: string, expected?: string | null | Checksums) => Promise<void>;
-/** Runs a program without blocking the event loop (parallel downloads keep going); resolves with its exit code. */
-export declare const spawnAsync: (file: string, args: string[], options?: import("node:child_process").SpawnOptions) => Promise<number>;
-export interface ReleaseAsset {
-    url: string;
-    name: string;
-    sha256: string | null;
-}
-/**
- * Finds an asset in the latest GitHub release of `repo` (with its published sha256 when available). With
- * `searchOlder`, falls back to the newest stable release that still ships a matching asset (projects drop assets).
- */
-export declare const githubAsset: (repo: string, pattern: RegExp, searchOlder?: boolean) => Promise<ReleaseAsset>;
-/** A release's assets from github.com's expanded_assets page (no API rate limit): each download link, then its sha256. */
-export declare const parseReleasePage: (html: string) => ReleaseAsset[];
-/** The latest release's tag, from github.com's own redirect (no API, no rate limit). */
-export declare const latestGithubTag: (repo: string) => Promise<string>;
-/** Release tags in the order github.com's /<repo>/releases page lists them (newest first), without duplicates. */
-export declare const parseReleaseTags: (html: string, repo: string) => string[];
-/**
- * Extracts .zip / .nupkg / .7z / .tar.gz with the tar.exe that ships with Windows, falling back to Expand-Archive.
- * `members` limits it to those paths inside the archive (e.g. skip pgAdmin in the PostgreSQL zip).
- */
-export declare const extractArchive: (archive: string, destination: string, members?: string[]) => Promise<void>;
-export declare const findFile: (root: string, name: string, maxDepth?: number) => string | null;
-/**
- * Downloads + extracts into `destination` atomically (staging folder, then rename). With `locate`, only the folder holding
- * that file is kept (`up` folders above it, e.g. locate ruby.exe with up 1 keeps the folder around bin).
- */
-export declare const installArchive: (url: string, destination: string, options?: {
-    sha256?: string | null;
-    sha512?: string | null;
-    locate?: string;
-    up?: number;
-    fileName?: string;
-    members?: string[];
-}) => Promise<void>;