tau-all-agent 0.3.1 → 0.4.0

package/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-manager.js

@@ -0,0 +1,2054 @@
+import { hasNameReading, literalReadLists, literalWriteLists, reExposedBy, readRulesOf, samePathEntries, spelledOf, withOtherReadings, writeRootsOf, } from './path-entries.js';
+import { createHttpProxyServer } from './http-proxy.js';
+import { createSocksProxyServer } from './socks-proxy.js';
+import { createMuxProxyServer } from './mux-proxy.js';
+import { listenInRange } from './listen-in-range.js';
+import { SentinelRegistry } from './credential-sentinel.js';
+import { MaskedFileStore, buildMaskedFileBinds, } from './credential-mask-files.js';
+import { buildMaskedEnvVars } from './credential-mask-env.js';
+import { AwsPairRegistry, createSigv4Planner, registerAwsPairs, } from './credential-aws-pairs.js';
+import { certThumbprint, createMitmCA, CRL_PATH, disposeMitmCA, } from './mitm-ca.js';
+import { logForDebugging } from '../utils/debug.js';
+import { whichSync } from '../utils/which.js';
+import { getPlatform, getWslVersion } from '../utils/platform.js';
+import * as fs from 'fs';
+import { randomBytes } from 'node:crypto';
+import { WorkingDirectoryChanged, wrapCommandWithSandboxLinux, initializeLinuxNetworkBridge, checkLinuxDependencies, cleanupBwrapMountPoints, linuxGetCwdMandatoryDenyPaths, } from './linux-sandbox-utils.js';
+import { expandReadDenyGlobLinuxSteps } from './read-deny-glob.js';
+import { wrapCommandWithSandboxMacOS, startMacOSSandboxLogMonitor, } from './macos-sandbox-utils.js';
+import { startLinuxSandboxViolationMonitor, } from './linux-violation-monitor.js';
+import { checkWindowsDependencies, checkWindowsDependenciesAsync, wrapCommandWithSandboxWindows, parseWindowsBinShell, expandWindowsFsPaths, stampWindowsAcl, restoreWindowsAcl, grantWindowsAcl, revokeWindowsAcl, getWindowsSandboxUserStatusAsync, getWindowsSandboxCaCert, ensurePersistentWindowsCa, verifyWindowsWfpEgress, resolveSrtWin, WindowsSandboxError, DEFAULT_WINDOWS_PROXY_PORT_RANGE, } from './windows-sandbox-utils.js';
+import { getDefaultWritePaths, containsGlobChars, globPatternBaseDir, normalizePathForSandbox, removeTrailingGlobSuffix, walkGlobPatternSteps, workingDirectory, finish, finishInTurns, attributionKeyFor, decodeSandboxedCommand, encodeSandboxedCommand, } from './sandbox-utils.js';
+import { SandboxViolationStore, sanitizeUnregisteredCommandKey, shouldIgnoreViolation, } from './sandbox-violation-store.js';
+import { canonicalizeHost, isValidHost, redactUrl, resolveParentProxy, } from './parent-proxy.js';
+import { matchesDomainPattern, matchesDomainPatternWithPort, stripDomainPatternPort, } from './domain-pattern.js';
+import { createResolvedAddressGuard, isResolvedAddressDenied, } from './resolved-address-guard.js';
+import { EOL } from 'node:os';
+import { dirname } from 'node:path';
+import { getJavaProxyAgentJarPathAsync } from './java-proxy-agent.js';
+import { getApplySeccompBinaryPathAsync } from './generate-seccomp-filter.js';
+// ============================================================================
+// Private Module State
+// ============================================================================
+let config;
+/** How many times a configuration has been installed. A wrap tells by this
+ *  as well as by the object: initialize() keeps the caller's own, which can
+ *  be handed to it again. */
+let configInstalls = 0;
+let httpProxyServer;
+let socksProxyServer;
+let muxProxyServer;
+let managerContext;
+let initializationPromise;
+let cleanupRegistered = false;
+let logMonitorShutdown;
+let linuxMonitor;
+let parentProxy;
+/** Read live through {@link directLookup}, so a config update applies to the next dial. */
+let resolvedAddressGuard = createResolvedAddressGuard();
+let mitmCA;
+/**
+ * Resolved path of the JVM proxy agent jar (see java-proxy-agent.ts); set
+ * while a proxy is advertised to the sandbox, undefined if the jar is not
+ * shipped/found (JVMs then just aren't proxy-aware, as before).
+ */
+let javaAgentJarPath;
+// Per-session proxy auth token. Generated at proxy start, exported only into
+// the sandbox child env, checked on every CONNECT/request — so a host process
+// dialing 127.0.0.1:<proxyPort> can't reach the filter callback.
+let proxyAuthToken;
+// Windows: the resolved access set that was actually applied at
+// initialize(). `undefined` means no stamp/grant was applied
+// (gates running `acl restore`/`acl revoke` at reset()).
+let windowsFsStampedSet;
+// The sandbox user SID captured at initialize(). reset() uses this
+// so a config change between init and reset can't strand ACEs
+// under a different SID.
+let windowsFsSbUserSid;
+// The RAW config inputs that produced `windowsFsStampedSet`.
+// updateConfig() compares these (not the resolved set) so it never
+// re-expands globs — see `sameWindowsStampSet`.
+let windowsFsRawInputs;
+// `verifyWindowsWfpEgress()` is once per PROCESS (it spawns a
+// CreateProcessWithLogonW runner; first call may create the sandbox
+// user's profile). The WFP fence is install-scoped, not config- or
+// session-scoped — reset() does NOT clear this, so updateConfig()'s
+// reset+reinit and the test suite's per-test reset() don't re-verify.
+let windowsWfpVerified = false;
+// Resolved once at initialize() (`resolveSrtWin` stats the disk).
+// Captured so wrapWithSandboxArgv/reset() don't re-resolve per call
+// and so reset()'s revoke/restore addresses the SAME binary the
+// grants/stamps were applied with even if `config` mutated between.
+let srtWinSpawn;
+const sandboxViolationStore = new SandboxViolationStore();
+// Per-session sentinel↔real-value map for masked credentials. Lives only in
+// process memory; never written to disk or logged. Cleared on reset().
+const sentinelRegistry = new SentinelRegistry();
+// Per-session linked AWS credential pairs for SigV4 re-signing, keyed by
+// the fake access key id. Same lifecycle and secrecy posture as the
+// sentinel registry.
+const awsPairRegistry = new AwsPairRegistry();
+// Temp dir holding the sentinel-content fake files for masked credential
+// files. Created lazily on first masked file; removed on reset().
+const maskedFileStore = new MaskedFileStore();
+// ============================================================================
+// Private Helper Functions (not exported)
+// ============================================================================
+function registerCleanup() {
+    if (cleanupRegistered) {
+        return;
+    }
+    const cleanupHandler = () => reset().catch(e => {
+        logForDebugging(`Cleanup failed in registerCleanup ${e}`, {
+            level: 'error',
+        });
+    });
+    process.once('exit', cleanupHandler);
+    process.once('SIGINT', cleanupHandler);
+    process.once('SIGTERM', cleanupHandler);
+    cleanupRegistered = true;
+}
+/**
+ * Attribution key to command text for every wrapped invocation, so each
+ * producer can report (and ignoreViolations can match) the command an event
+ * belongs to rather than the opaque key. Keys are held decoded because that
+ * is the form the carriers deliver. Bounded FIFO: the violation store itself
+ * only retains the last 100 events, so long-gone invocations need no entry.
+ */
+const MAX_COMMAND_TEXTS = 1024;
+const commandTextsByKey = new Map();
+/** Exported for testing. */
+export function registerCommandText(command, options) {
+    const key = decodeSandboxedCommand(encodeSandboxedCommand(attributionKeyFor(command, options?.commandId)));
+    const text = options?.commandText ?? command;
+    commandTextsByKey.delete(key);
+    commandTextsByKey.set(key, text);
+    while (commandTextsByKey.size > MAX_COMMAND_TEXTS) {
+        const oldest = commandTextsByKey.keys().next().value;
+        if (oldest === undefined)
+            break;
+        commandTextsByKey.delete(oldest);
+    }
+}
+/**
+ * The command text for a decoded attribution key. Keys arrive over carriers
+ * the sandboxed process can write (the observe socket's event field, the
+ * macOS log tag, the proxy username), so only a key this process registered
+ * carries the embedder's own text; anything else is untrusted bytes.
+ * Exported for testing.
+ */
+export function resolveCommandText(decodedKey) {
+    return (commandTextsByKey.get(decodedKey) ??
+        sanitizeUnregisteredCommandKey(decodedKey));
+}
+/**
+ * Record a proxy-side denial in the violation store so the model sees a
+ * structured <sandbox_violations> block alongside the raw 403 / SOCKS
+ * failure in stderr — parity with the macOS seatbelt log monitor and the
+ * Linux seccomp observer. The proxy is the only component that knows the
+ * destination host of a network deny, so neither of those can produce
+ * this line. `encodedCommand` (from the proxy username) attributes it to
+ * the invocation; without one the event is stored unattributed.
+ */
+function recordProxyViolation(line, encodedCommand) {
+    const command = encodedCommand
+        ? resolveCommandText(decodeSandboxedCommand(encodedCommand))
+        : undefined;
+    // Same suppression the seatbelt / seccomp monitors apply, so a
+    // configured ignoreViolations pattern silences the event no matter
+    // which producer saw it.
+    if (shouldIgnoreViolation(line, command, config?.ignoreViolations)) {
+        return;
+    }
+    sandboxViolationStore.addViolation({
+        line,
+        encodedCommand,
+        command,
+        timestamp: new Date(),
+    });
+}
+function recordOutboundDeny(host, port, reason, encodedCommand) {
+    recordProxyViolation(`deny network-outbound ${host}:${port} (${reason})`, encodedCommand);
+}
+/** Direct-dial `lookup` for the proxies: the current guard's, with a refusal recorded as a violation. */
+const directLookup = (port, encodedCommand) => (hostname, options, callback) => resolvedAddressGuard.lookupFor(port)(hostname, options, (err, address, family) => {
+    if (isResolvedAddressDenied(err)) {
+        recordOutboundDeny(hostname, port, err.reason, encodedCommand);
+    }
+    callback(err, address, family);
+});
+/**
+ * The request URL as it should appear in a model-visible violation line:
+ * origin + path, with any query string reduced to a `?…` marker (origin
+ * carries no userinfo, so an embedded `name:pass@` is dropped too). Query
+ * strings routinely carry credentials (api_key=, access_token=, signed
+ * URLs) that the sandboxed client interpolated at runtime and that were
+ * never in the model's context, so they must not enter the transcript via
+ * the <sandbox_violations> block. The full URL still reaches the embedder's
+ * filterRequest callback and its own debug logging.
+ */
+function redactUrlForViolation(url) {
+    try {
+        const u = new URL(url);
+        return `${u.origin}${u.pathname}${u.search ? '?…' : ''}`;
+    }
+    catch {
+        // Not an absolute URL (shouldn't happen for proxy requests) — drop
+        // anything after '?' rather than risk leaking it.
+        const q = url.indexOf('?');
+        return q === -1 ? url : `${url.slice(0, q)}?…`;
+    }
+}
+async function filterNetworkRequest(port, host, sandboxAskCallback, encodedCommand) {
+    const denied = (reason) => {
+        recordOutboundDeny(host, port, reason, encodedCommand);
+        return false;
+    };
+    if (!config) {
+        logForDebugging('No config available, denying network request');
+        return denied('sandbox policy unavailable');
+    }
+    // Reject hosts containing control characters before pattern matching.
+    // `matchesDomainPattern` uses string suffix matching which is trivially
+    // fooled by e.g. `evil.com\x00.allowed.com` — the null byte passes
+    // `.endsWith()` but truncates at the libc DNS layer. The SOCKS path is the
+    // main exposure (DOMAINNAME is unvalidated bytes); HTTP is protected by
+    // llhttp/URL parsing, but we check here for defence in depth.
+    if (!isValidHost(host)) {
+        logForDebugging(`Denying malformed host: ${JSON.stringify(host)}:${port}`, {
+            level: 'error',
+        });
+        return denied('malformed host');
+    }
+    // Canonicalize so string comparisons match what getaddrinfo() will dial.
+    // Without this, inet_aton shorthand like `2852039166` (= 169.254.169.254)
+    // or `127.1` slips past a denylist entry for the dotted-decimal form.
+    const canonicalHost = canonicalizeHost(host) ?? host;
+    // Check denied domains first
+    for (const deniedDomain of config.network.deniedDomains) {
+        if (matchesDomainPatternWithPort(canonicalHost, port, deniedDomain)) {
+            logForDebugging(`Denied by config rule: ${host}:${port}`);
+            // The matched entry's own reason when the caller supplied one, so the
+            // model reads why this destination is off-limits (and the sanctioned
+            // alternative) instead of a generic deny; keyed by the exact entry.
+            return denied(config.network.deniedDomainReasons?.[deniedDomain] ??
+                'host is on the deny list');
+        }
+    }
+    // Check allowed domains
+    for (const allowedDomain of config.network.allowedDomains) {
+        if (matchesDomainPatternWithPort(canonicalHost, port, allowedDomain)) {
+            logForDebugging(`Allowed by config rule: ${host}:${port}`);
+            return true;
+        }
+    }
+    // No matching rules - ask user or deny. strictAllowlist makes the
+    // allowlist deterministic enforcement: never fall through to the callback.
+    if (!sandboxAskCallback || config.network.strictAllowlist) {
+        logForDebugging(`No matching config rule, denying: ${host}:${port}`);
+        return denied('host is not on the allow list');
+    }
+    logForDebugging(`No matching config rule, asking user: ${host}:${port}`);
+    try {
+        const userAllowed = await sandboxAskCallback({ host, port });
+        if (userAllowed) {
+            logForDebugging(`User allowed: ${host}:${port}`);
+            return true;
+        }
+        logForDebugging(`User denied: ${host}:${port}`);
+        return denied('user denied');
+    }
+    catch (error) {
+        logForDebugging(`Error in permission callback: ${error}`, {
+            level: 'error',
+        });
+        return denied('permission prompt failed');
+    }
+}
+/**
+ * Build the header-mutation callback that substitutes sentinel→real for
+ * masked credentials. Returns undefined when no `credentials` block is
+ * configured — wiring the seam at all is unnecessary then.
+ *
+ * Per-host gating happens inside the registry: each sentinel carries its
+ * own injectHosts list and substitutes independently, so credential A's
+ * sentinel cannot be laundered through credential B's allowed host. The
+ * returned closure does not log header values; the registry holds the only
+ * copy of the real value.
+ */
+function buildCredentialInjector() {
+    if (!config?.credentials)
+        return undefined;
+    return (headers, destHost) => {
+        sentinelRegistry.substituteInHeaders(headers, destHost, matchesDomainPattern);
+    };
+}
+/**
+ * Body counterpart of {@link buildCredentialInjector}: per-destination
+ * sentinel→real pairs for streaming substitution in request bodies, with
+ * the same per-credential injectHosts gating applied inside the registry.
+ */
+function buildBodyCredentialInjector() {
+    if (!config?.credentials)
+        return undefined;
+    return destHost => sentinelRegistry.sentinelsForHost(destHost, matchesDomainPattern);
+}
+/**
+ * Build the per-request SigV4 hook for the TLS-terminating proxy.
+ * Returns undefined when no `credentials` block is configured. The hook
+ * consults {@link awsPairRegistry} at request time, so pairs registered
+ * later (wrapWithSandbox runs after the proxy starts) are picked up.
+ */
+function buildSigv4Planner() {
+    if (!config?.credentials)
+        return undefined;
+    // Re-read the policies per request (not captured at proxy start) so an
+    // updateConfig() that changes credentials.sigv4 takes effect without a
+    // proxy restart, matching how the injector sees live registry state.
+    return (method, requestTarget, headers, destHost) => createSigv4Planner(awsPairRegistry, config?.credentials?.sigv4, matchesDomainPattern)(method, requestTarget, headers, destHost);
+}
+/**
+ * Get the MITM proxy socket path for a given host, if configured.
+ * Returns the socket path if the host matches any MITM domain pattern,
+ * otherwise returns undefined.
+ *
+ * Matches the canonicalized hostname, like the allow/deny filter
+ * (filterNetworkRequest) and the tlsTerminate exclusion below. This site
+ * fails OPEN on a miss — a host that matches no MITM pattern is dialed
+ * directly — so it must accept exactly the set of spellings the allowlist
+ * accepts: otherwise `api.example.com.` (trailing-dot FQDN, same name to
+ * DNS) passes the allowlist as `api.example.com` but misses every MITM
+ * pattern and skips the MITM proxy entirely. The proxies already hand this
+ * hook the canonical spelling; canonicalizing again here is defence in
+ * depth for any other caller.
+ */
+function getMitmSocketPath(host) {
+    if (!config?.network.mitmProxy) {
+        return undefined;
+    }
+    const { socketPath, domains } = config.network.mitmProxy;
+    const canonicalHost = canonicalizeHost(host) ?? host;
+    for (const pattern of domains) {
+        if (matchesDomainPattern(canonicalHost, pattern)) {
+            logForDebugging(`Host ${host} matches MITM pattern ${pattern}`);
+            return socketPath;
+        }
+    }
+    return undefined;
+}
+/**
+ * Per-host TLS-termination opt-out from network.tlsTerminate.excludeDomains.
+ * Only consulted by the HTTP proxy when tlsTerminate is enabled; exempted
+ * hosts fall back to the opaque CONNECT tunnel (still allowlist-filtered),
+ * so mTLS / cert-pinning clients can complete their own handshake.
+ *
+ * Matches the canonicalized hostname, like the allow/deny filter
+ * (filterNetworkRequest) — otherwise a spelling the allowlist accepts after
+ * canonicalization (`127.1`, a trailing-dot FQDN) would dodge the exclusion
+ * and get terminated anyway.
+ */
+function shouldTerminateTLSForHost(host) {
+    const excludeDomains = config?.network.tlsTerminate?.excludeDomains;
+    if (!excludeDomains?.length)
+        return true;
+    const canonicalHost = canonicalizeHost(host) ?? host;
+    for (const pattern of excludeDomains) {
+        if (!matchesDomainPattern(canonicalHost, pattern))
+            continue;
+        logForDebugging(`Host ${host} matches tlsTerminate.excludeDomains pattern ${pattern}; skipping TLS termination`);
+        // Masked-credential substitution only happens on the terminated path,
+        // so a credential whose injectHosts cover this host can never be
+        // injected here — the upstream gets the placeholder. Config validation
+        // rejects the fully-contradictory spellings; this flags the partial
+        // ones (e.g. default injectHosts = allowedDomains) at the moment they
+        // actually bite.
+        const masked = sentinelRegistry.namesInjectableAt(canonicalHost, matchesDomainPattern);
+        if (masked.length > 0) {
+            logForDebugging(`tlsTerminate.excludeDomains: masked credential(s) ${masked.join(', ')} ` +
+                `are configured for injection at ${host}, but its connections are ` +
+                `not terminated, so the upstream will receive the placeholder`, { level: 'error' });
+        }
+        return false;
+    }
+    return true;
+}
+async function startMuxProxyServer(sandboxAskCallback, portRange) {
+    const injectCredentials = buildCredentialInjector();
+    const injectBodyCredentials = buildBodyCredentialInjector();
+    httpProxyServer = createHttpProxyServer({
+        filter: (port, host, _socket, encodedCommand) => filterNetworkRequest(port, host, sandboxAskCallback, encodedCommand),
+        getMitmSocketPath,
+        mitmCA,
+        shouldTerminateTLS: shouldTerminateTLSForHost,
+        filterRequest: config?.network.filterRequest,
+        onFilterRequestDenied: ({ method, url, reason, encodedCommand }) => {
+            recordProxyViolation(`deny http-request ${method} ${redactUrlForViolation(url)} (${reason})`, encodedCommand);
+        },
+        // TLS-terminated path always gets the injector; the plain-HTTP path
+        // only when explicitly opted in. Without the opt-in, a sentinel sent
+        // over plain HTTP reaches the upstream unchanged (fails closed).
+        mutateHeaders: injectCredentials,
+        mutateHeadersPlaintext: config?.credentials?.allowPlaintextInject
+            ? injectCredentials
+            : undefined,
+        getBodySubstitutions: injectBodyCredentials,
+        getBodySubstitutionsPlaintext: config?.credentials?.allowPlaintextInject
+            ? injectBodyCredentials
+            : undefined,
+        // SigV4 re-signing is TLS-terminated-path only, like credential
+        // injection: the real signature must not travel over plaintext.
+        planSigv4: buildSigv4Planner(),
+        parentProxy,
+        lookupFor: directLookup,
+        proxyAuthToken,
+    });
+    socksProxyServer = createSocksProxyServer({
+        filter: (port, host, encodedCommand) => filterNetworkRequest(port, host, sandboxAskCallback, encodedCommand),
+        parentProxy,
+        lookupFor: directLookup,
+        proxyAuthToken,
+        probeUnauthenticated: async (port, host) => {
+            // Explicit deny rules only: an unauthenticated peer must never reach
+            // the ask callback, and a merely off-list host gets the generic
+            // cannot-authenticate refusal rather than a policy claim.
+            if (!config)
+                return {};
+            const canonical = canonicalizeHost(host) ?? host;
+            for (const entry of config.network.deniedDomains) {
+                if (matchesDomainPatternWithPort(canonical, port, entry)) {
+                    const reason = config.network.deniedDomainReasons?.[entry] ??
+                        'host is on the deny list';
+                    recordOutboundDeny(host, port, reason);
+                    return { deniedReason: reason };
+                }
+            }
+            return {};
+        },
+    });
+    muxProxyServer = createMuxProxyServer({
+        httpServer: httpProxyServer,
+        handleSocksConnection: s => socksProxyServer.handleConnection(s),
+        httpBackendPortRange: portRange,
+    });
+    const mux = muxProxyServer;
+    // Backend first so the front-end never accepts a connection that would
+    // dispatch to an unbound backend. On Windows the backend's port is
+    // excluded when binding the front-end in the same WFP range.
+    const backendPort = await mux.listenHttpBackend();
+    await listenInRange(mux.server, p => mux.server.listen(p, '127.0.0.1'), portRange, backendPort !== undefined ? new Set([backendPort]) : new Set());
+    const muxPort = mux.getPort();
+    if (muxPort === undefined) {
+        throw new Error('Failed to get mux proxy server port');
+    }
+    mux.unref();
+    logForDebugging(`Mux proxy (HTTP+SOCKS) listening on localhost:${muxPort}`);
+    return muxPort;
+}
+// ============================================================================
+// Public Module Functions (will be exported via namespace)
+// ============================================================================
+async function initialize(runtimeConfig, sandboxAskCallback, enableLogMonitor = false) {
+    // Return if already initializing
+    if (initializationPromise) {
+        await initializationPromise;
+        return;
+    }
+    // Store config for use by other functions
+    config = runtimeConfig;
+    configInstalls++;
+    // Resolve parent/upstream proxy from config or HTTP_PROXY env before we
+    // start our own listeners (which will later shadow those vars in the child).
+    parentProxy = resolveParentProxy(runtimeConfig.network.parentProxy);
+    if (parentProxy) {
+        logForDebugging(`Parent proxy configured: http=${redactUrl(parentProxy.httpUrl)} ` +
+            `https=${redactUrl(parentProxy.httpsUrl)}`);
+    }
+    resolvedAddressGuard = createResolvedAddressGuard(runtimeConfig.network);
+    // Load TLS-termination CA if configured. Throws on unreadable/non-PEM —
+    // tlsTerminate is explicit opt-in, so a bad config is a hard error.
+    if (runtimeConfig.network.tlsTerminate && runtimeConfig.network.mitmProxy) {
+        throw new Error('network.tlsTerminate and network.mitmProxy are mutually exclusive');
+    }
+    // On Windows with tlsTerminate and no explicit caCertPath/caKeyPath,
+    // defer CA creation until the Windows block below has resolved
+    // srt-win and fetched user status — the persistent CA is
+    // generated-if-absent under windowsStateDir()/ca and
+    // trusted in the sandbox user's Root store, then loaded here.
+    // Explicit paths (or non-Windows) go straight to createMitmCA.
+    const tlsTerminate = runtimeConfig.network.tlsTerminate;
+    const useWindowsPersistentCa = getPlatform() === 'windows' &&
+        tlsTerminate !== undefined &&
+        !tlsTerminate.caCertPath &&
+        !tlsTerminate.caKeyPath;
+    mitmCA =
+        tlsTerminate && !useWindowsPersistentCa
+            ? createMitmCA(tlsTerminate)
+            : undefined;
+    // Check dependencies
+    const deps = await checkDependenciesAsync();
+    if (deps.errors.length > 0) {
+        throw new Error(`Sandbox dependencies not available: ${deps.errors.join(', ')}`);
+    }
+    // Start log monitor for macOS if enabled
+    if (enableLogMonitor && getPlatform() === 'macos') {
+        logMonitorShutdown = startMacOSSandboxLogMonitor(sandboxViolationStore.addViolation.bind(sandboxViolationStore), config.ignoreViolations, resolveCommandText);
+        logForDebugging('Started macOS sandbox log monitor');
+    }
+    if (enableLogMonitor && getPlatform() === 'linux') {
+        // The monitor compares paths the kernel reported, so its lists are
+        // expanded the way the wrapper expands them (getFsWriteConfig folds in
+        // the default write paths and drops the patterns, so only names are left;
+        // normalizePathForSandbox resolves `~`, relative spellings and symlinks),
+        // plus the built-in write denies the wrapper always applies.
+        // It does not reproduce the wrapper's existence and boundary-symlink
+        // filters, nor the ripgrep scan for nested dangerous paths; and it still
+        // reports writes bwrap permits through `--dev`, `--proc` and the tmpfs
+        // over each read-denied directory. Started once, so both lists are fixed
+        // at the cwd and configuration of this call, and at the disk as it is
+        // now: an entry with glob characters that becomes the name of a path
+        // later is applied by the next wrap and stays unknown here.
+        const monitoredWrites = getFsWriteConfig();
+        linuxMonitor = startLinuxSandboxViolationMonitor(sandboxViolationStore.addViolation.bind(sandboxViolationStore), {
+            // apply-seccomp's observer reports every write-intent syscall
+            // (allowed or not). Only paths bwrap would actually refuse — outside
+            // allowWrite or inside a denyWrite carve-out — go to the store. With
+            // the policy on, the default write paths are listed in full rather
+            // than as getFsWriteConfig() narrowed them: a home directory it leaves
+            // out because it is read-denied sits under that deny's writable
+            // tmpfs, so a write there is permitted and is not a violation.
+            allowWritePaths: [
+                ...writeRootsOf(monitoredWrites),
+                ...(config.filesystem.disabled ? [] : getDefaultWritePaths()),
+            ].map(p => normalizePathForSandbox(p, { literal: true })),
+            denyWritePaths: [
+                ...monitoredWrites.denyWithinAllow.map(p => normalizePathForSandbox(p, { literal: true })),
+                ...(monitoredWrites.literalDenyWithinAllow ?? []).map(p => normalizePathForSandbox(p, { literal: true })),
+                // filesystem.disabled reaches the wrapper as `writeConfig ===
+                // undefined`, which skips every bind and the built-in denies with
+                // them, so the monitor must not judge by them either.
+                ...(config.filesystem.disabled
+                    ? []
+                    : linuxGetCwdMandatoryDenyPaths(getAllowGitConfig())),
+            ],
+            ignoreViolations: config.ignoreViolations,
+            resolveCommandText,
+        });
+        // Don't block initialization on listen() — wrap-time checks
+        // fs.existsSync(observeSocketPath) and degrades gracefully.
+        void linuxMonitor.ready;
+        logForDebugging('Started Linux seccomp violation monitor');
+    }
+    // Register cleanup handlers first time
+    registerCleanup();
+    // Windows: validate provisioning + filesystem config BEFORE any
+    // sandboxed child can be spawned. Doing this at initialize() (not
+    // wrap-time) means the host gets a single actionable error before
+    // any per-exec work happens, instead of exit-15 on every command.
+    if (getPlatform() === 'windows') {
+        // Resolve once (stats disk); captured module-level for wrap/reset.
+        srtWinSpawn = resolveSrtWin(runtimeConfig.windows?.srtWin);
+        const srtWin = srtWinSpawn;
+        const u = await getWindowsSandboxUserStatusAsync({ srtWin });
+        if (!u.provisioned || !u.credPresent) {
+            config = undefined;
+            throw new WindowsSandboxError('not_provisioned', `Windows sandbox user is not provisioned (user=` +
+                `${u.provisioned}, cred=${u.credPresent}). Run \`npx ` +
+                `sandbox-runtime windows-install\` (one UAC prompt) to ` +
+                `provision it.`);
+        }
+        // Behavioral proof the WFP egress fence is active for the
+        // sandbox user — BFE enumeration (`wfp status`) is admin-gated,
+        // so this is the non-elevated readiness check. Fails closed: a
+        // stale install (user provisioned but filters since removed)
+        // throws here instead of running every exec with full egress.
+        // After the user-status check so the not-provisioned message is
+        // the actionable one. Once per process — the fence is install-
+        // scoped, not session-scoped.
+        if (!windowsWfpVerified) {
+            try {
+                await verifyWindowsWfpEgress({
+                    proxyPortRange: runtimeConfig.windows?.proxyPortRange,
+                    srtWin,
+                });
+            }
+            catch (e) {
+                config = undefined;
+                throw e;
+            }
+            windowsWfpVerified = true;
+        }
+        // Persistent-CA branch (see the deferral comment above).
+        // `ensurePersistentWindowsCa` reconciles the registry thumb
+        // itself (so initialize() after uninstall→reinstall repairs
+        // trust) and may make `u.caCertThumb` stale — hence the
+        // explicit-path thumb check below skips this branch.
+        if (useWindowsPersistentCa && tlsTerminate) {
+            try {
+                const p = await ensurePersistentWindowsCa({ status: u, srtWin });
+                mitmCA = createMitmCA({
+                    caCertPem: p.certPem,
+                    caKeyPem: p.keyPem,
+                    caCertPath: p.certPath,
+                    caKeyPath: p.keyPath,
+                    extraCaCertPaths: tlsTerminate.extraCaCertPaths,
+                });
+            }
+            catch (e) {
+                config = undefined;
+                throw e;
+            }
+        }
+        // Explicit-path branch: schannel clients (System32 curl, IWR,
+        // .NET, default-backend git) only trust what's in the sandbox
+        // user's `CurrentUser\Root` — which `srt-win exec` does not (and
+        // must not) write. Compare thumbprints so a stale install-time
+        // CA doesn't pass the gate while schannel rejects the session's
+        // proxy-minted leaves.
+        if (tlsTerminate && mitmCA && !useWindowsPersistentCa) {
+            const installed = getWindowsSandboxCaCert(u);
+            const sessionThumb = certThumbprint(mitmCA.certPem);
+            if (!installed) {
+                config = undefined;
+                throw new WindowsSandboxError('trust_ca_not_installed', `tlsTerminate on Windows requires the sandbox to be ` +
+                    `installed with this CA (thumb=${sessionThumb}): run ` +
+                    `\`srt-win user trust-ca ${mitmCA.certPath}\`. Per-exec ` +
+                    `installs into the sandbox user's Root store are not ` +
+                    `supported.`);
+            }
+            if (installed.thumb !== sessionThumb) {
+                config = undefined;
+                throw new WindowsSandboxError('trust_ca_thumbprint_mismatch', `tlsTerminate on Windows: the sandbox's installed CA ` +
+                    `(thumb=${installed.thumb}) doesn't match this ` +
+                    `session's CA (thumb=${sessionThumb}). Run \`srt-win ` +
+                    `user trust-ca ${mitmCA.certPath}\` to update it.`);
+            }
+        }
+        // Filesystem grants/denies — additive sandbox-user ACEs.
+        try {
+            const acc = computeWindowsFsAccessSet(runtimeConfig);
+            // The trust bundle the CA-trust env vars point at
+            // (NODE_EXTRA_CA_CERTS etc.) must be readable by the
+            // srt-sandbox child. It's written into the broker's %TEMP%,
+            // which the sandbox user has no inherent rights on, so it
+            // rides the same session-level `acl grant` read-set as the
+            // working tree. Granted on the mkdtemp DIR (not the file)
+            // so the (OI)(CI) ACE covers both the file open AND the
+            // parent-directory list that cmd's `type`/`FindFirstFile`
+            // does before opening. Mirrors the mac/linux
+            // `expandedAllowRead` push in wrapWithSandbox.
+            if (mitmCA) {
+                acc.grantRead.push(dirname(mitmCA.trustBundlePath));
+            }
+            // `u` was fetched once above for the provisioning gate; the
+            // same status carries the SID — don't re-spawn `srt-win user
+            // status` here.
+            if (!u.sid) {
+                throw new Error('sandbox user SID missing from `srt-win user status` ' +
+                    '(provisioned but in an inconsistent state)');
+            }
+            const sb = u.sid;
+            // Record module-level state BEFORE the first acl call so the
+            // catch's best-effort revoke/restore can address whatever
+            // partially landed.
+            windowsFsSbUserSid = sb;
+            // Grant FIRST so the sandbox user has working-tree access by
+            // the time the deny stamp runs. The two are independent
+            // refcounted state-DB sets keyed on the same holder PID.
+            if (acc.grantRead.length > 0 || acc.grantWrite.length > 0) {
+                grantWindowsAcl({
+                    sandboxUserSid: sb,
+                    read: acc.grantRead,
+                    write: acc.grantWrite,
+                    srtWin,
+                });
+            }
+            if (acc.denyRead.length > 0 || acc.denyWrite.length > 0) {
+                stampWindowsAcl({
+                    sandboxUserSid: sb,
+                    denyRead: acc.denyRead,
+                    denyWrite: acc.denyWrite,
+                    srtWin,
+                });
+            }
+            // Only record when something was actually applied — gates
+            // running revoke/restore at reset(). Recorded AFTER success —
+            // the catch below clears `config`, and a non-undefined
+            // stampedSet would leave reset()/updateConfig() seeing state
+            // that never landed.
+            const anyApplied = acc.grantRead.length > 0 ||
+                acc.grantWrite.length > 0 ||
+                acc.denyRead.length > 0 ||
+                acc.denyWrite.length > 0;
+            if (anyApplied) {
+                windowsFsStampedSet = acc;
+                logForDebugging(`[Sandbox Windows] fs applied: ` +
+                    `${acc.grantWrite.length} grantWrite, ` +
+                    `${acc.grantRead.length} grantRead, ` +
+                    `${acc.denyRead.length} denyRead, ` +
+                    `${acc.denyWrite.length} denyWrite`);
+            }
+            windowsFsRawInputs = rawWindowsFsInputs(runtimeConfig);
+        }
+        catch (e) {
+            // Best-effort release of whatever WAS applied before the
+            // failure (exit-2 partial stamps/grants the resolvable
+            // inputs; harmless if nothing was — no holds for this PID).
+            if (windowsFsSbUserSid) {
+                revokeWindowsAcl({ sandboxUserSid: windowsFsSbUserSid, srtWin });
+                restoreWindowsAcl({ sandboxUserSid: windowsFsSbUserSid, srtWin });
+            }
+            windowsFsSbUserSid = undefined;
+            config = undefined;
+            throw e;
+        }
+    }
+    // Initialize network infrastructure
+    initializationPromise = (async () => {
+        try {
+            // On Windows the WFP loopback permit covers a fixed port
+            // range, so the proxies must bind inside it. Other platforms
+            // bake the actual ephemeral port into the sandbox profile, so
+            // they keep using port 0.
+            const portRange = getPlatform() === 'windows'
+                ? (config.windows?.proxyPortRange ?? DEFAULT_WINDOWS_PROXY_PORT_RANGE)
+                : undefined;
+            // The auth token is only set when this process owns the proxy; an
+            // external proxy (config.network.httpProxyPort) handles its own auth,
+            // and embedding our token in its URL would be wrong.
+            proxyAuthToken =
+                config.network.httpProxyPort !== undefined
+                    ? undefined
+                    : randomBytes(16).toString('hex');
+            // The mux front-end serves both protocols on one port. Each side's
+            // reported port is the external override if configured, else the mux
+            // port — so the public config.network.{http,socks}ProxyPort contract
+            // is unchanged. The mux is skipped only when BOTH are external.
+            const needLocalProxy = config.network.httpProxyPort === undefined ||
+                config.network.socksProxyPort === undefined;
+            const muxPort = needLocalProxy
+                ? await startMuxProxyServer(sandboxAskCallback, portRange)
+                : undefined;
+            const httpProxyPort = config.network.httpProxyPort ?? muxPort;
+            const socksProxyPort = config.network.socksProxyPort ?? muxPort;
+            // JVMs read neither HTTPS_PROXY nor its credential; the agent bridges
+            // both. Resolved once here, advertised via JAVA_TOOL_OPTIONS per command.
+            // Async: the global-npm fallback spawns `npm root -g`.
+            javaAgentJarPath =
+                (await getJavaProxyAgentJarPathAsync(config.javaAgentJarPath)) ??
+                    undefined;
+            // Leaves are minted lazily per-CONNECT (after this point), so setting
+            // the CDP URL now means every leaf carries it. See MitmCA.crlUrl.
+            // Windows-only: on Linux the child runs under bwrap --unshare-net and
+            // reaches the proxy via a socat bridge on a fixed netns port, so a
+            // host-namespace mux port would be unreachable — worse than no CDP,
+            // since a Schannel-analog client (Java, OpenSSL with CRL_CHECK) then
+            // hard-fails "CRL fetch error" instead of soft-passing "no CDP". macOS
+            // has no in-tree Schannel-analog client. Also gated on `muxPort`: an
+            // external `network.httpProxyPort` doesn't answer /srt.crl.
+            if (mitmCA && muxPort !== undefined && getPlatform() === 'windows') {
+                mitmCA.crlUrl = `http://127.0.0.1:${muxPort}${CRL_PATH}`;
+            }
+            if (config.network.httpProxyPort !== undefined) {
+                logForDebugging(`Using external HTTP proxy on port ${httpProxyPort}`);
+            }
+            if (config.network.socksProxyPort !== undefined) {
+                logForDebugging(`Using external SOCKS proxy on port ${socksProxyPort}`);
+            }
+            // Initialize platform-specific infrastructure
+            let linuxBridge;
+            if (getPlatform() === 'linux') {
+                linuxBridge = await initializeLinuxNetworkBridge(httpProxyPort, socksProxyPort, config.socatPath);
+            }
+            const context = {
+                httpProxyPort,
+                socksProxyPort,
+                linuxBridge,
+            };
+            managerContext = context;
+            logForDebugging('Network infrastructure initialized');
+            return context;
+        }
+        catch (error) {
+            // Clear state on error so initialization can be retried
+            initializationPromise = undefined;
+            managerContext = undefined;
+            reset().catch(e => {
+                logForDebugging(`Cleanup failed in initializationPromise ${e}`, {
+                    level: 'error',
+                });
+            });
+            throw error;
+        }
+    })();
+    await initializationPromise;
+}
+function isSupportedPlatform() {
+    const platform = getPlatform();
+    if (platform === 'linux') {
+        // WSL1 doesn't support bubblewrap
+        return getWslVersion() !== '1';
+    }
+    return platform === 'macos' || platform === 'windows';
+}
+function isSandboxingEnabled() {
+    // Sandboxing is enabled if config has been set (via initialize())
+    return config !== undefined;
+}
+/**
+ * Platform-independent part of the dependency check. Returns either
+ * a finished result (POSIX, unsupported platform, or a Windows
+ * srt-win resolution failure) or the inputs for the Windows probe —
+ * the only platform where the sync and async variants differ.
+ */
+function checkDependenciesCommon(ripgrepConfig) {
+    if (!isSupportedPlatform()) {
+        return { done: { errors: ['Unsupported platform'], warnings: [] } };
+    }
+    const errors = [];
+    const warnings = [];
+    const platform = getPlatform();
+    if (platform === 'linux') {
+        // ripgrep is Linux-only: it's used by linuxGetMandatoryDenyPaths() to
+        // expand glob deny-patterns to concrete paths for bwrap. macOS seatbelt
+        // profiles take regex patterns directly, so rg is never invoked there.
+        const rgToCheck = ripgrepConfig ?? config?.ripgrep ?? { command: 'rg' };
+        if (whichSync(rgToCheck.command) === null) {
+            errors.push(`ripgrep (${rgToCheck.command}) not found`);
+        }
+        const linuxDeps = checkLinuxDependencies({
+            seccompConfig: config?.seccomp,
+            bwrapPath: config?.bwrapPath,
+            socatPath: config?.socatPath,
+        });
+        errors.push(...linuxDeps.errors);
+        warnings.push(...linuxDeps.warnings);
+    }
+    else if (platform === 'windows') {
+        let srtWin;
+        try {
+            srtWin = resolveSrtWin(config?.windows?.srtWin);
+        }
+        catch (e) {
+            errors.push(e.message);
+            return { done: { errors, warnings } };
+        }
+        return {
+            windows: {
+                sublayerGuid: config?.windows?.sublayerGuid ?? config?.windows?.wfpSublayerGuid,
+                srtWin,
+            },
+        };
+    }
+    return { done: { errors, warnings } };
+}
+/**
+ * Check sandbox dependencies for the current platform
+ * @param ripgrepConfig - Ripgrep command to check. If not provided, uses config from initialization or defaults to 'rg'
+ * @returns { warnings, errors } - errors mean sandbox cannot run, warnings mean degraded functionality
+ */
+function checkDependencies(ripgrepConfig) {
+    const common = checkDependenciesCommon(ripgrepConfig);
+    if ('done' in common)
+        return common.done;
+    return checkWindowsDependencies(common.windows);
+}
+/**
+ * Async variant of {@link checkDependencies} — same result for the
+ * same underlying state. On Windows the srt-win probes run via
+ * `spawn` (never blocking the event loop) and concurrently; on other
+ * platforms the checks are native and this simply wraps the sync
+ * result. Windows callers should prefer this variant.
+ */
+async function checkDependenciesAsync(ripgrepConfig) {
+    // Linux: resolve apply-seccomp first so its global-npm fallback
+    // (`npm root -g`) runs off the event loop; the sync check below then
+    // hits the shared path cache.
+    if (getPlatform() === 'linux' && !config?.seccomp?.argv0) {
+        await getApplySeccompBinaryPathAsync(config?.seccomp?.applyPath);
+    }
+    const common = checkDependenciesCommon(ripgrepConfig);
+    if ('done' in common)
+        return common.done;
+    return checkWindowsDependenciesAsync(common.windows);
+}
+/**
+ * Build the read-deny / env-unset / env-set maps implied by the
+ * `credentials` config.
+ *
+ * Only explicitly declared sources are restricted: `mode: 'deny'` file
+ * entries join the read-deny set, `mode: 'deny'` env vars are unset, and
+ * `mode: 'mask'` env vars are set to a fake value (whole-value sentinel,
+ * the real value with extract-captured spans swapped for sentinels, or a
+ * JWT-shaped fake for `decode: 'jwt'` / `maskClaims` entries) registered
+ * in {@link sentinelRegistry} — see {@link buildMaskedEnvVars}.
+ */
+function getCredentialRestrictions(credentials, allowedDomains) {
+    if (!credentials) {
+        return {
+            denyReadPaths: [],
+            unsetEnvVars: [],
+            setEnvVars: {},
+            maskedFileBinds: [],
+            maskedFileStoreDir: undefined,
+            degradeToDenyPaths: [],
+        };
+    }
+    const denyReadPaths = getCredentialDenyReadPaths(credentials);
+    // Default injectHosts (= allowedDomains) is host-scoped: drop any
+    // `:port` suffixes, otherwise the sentinel would carry an entry no bare
+    // destination host can ever match and the credential would never inject.
+    const defaultInjectHosts = [
+        ...new Set((allowedDomains ?? []).map(stripDomainPatternPort)),
+    ];
+    const unsetEnvVars = [];
+    for (const v of credentials.envVars ?? []) {
+        if (v.mode === 'deny')
+            unsetEnvVars.push(v.name);
+    }
+    // Masked env vars: read the real value from the host environment,
+    // register sentinel(s), and set the variable to the fake value inside
+    // the sandbox. degradeToUnsetNames carries variables whose extract
+    // pattern matched nothing with onExtractNoMatch: "deny" — merged into
+    // unsetEnvVars below so the value is withheld rather than exposed.
+    const { setEnvVars, degradeToUnsetNames } = buildMaskedEnvVars(credentials.envVars ?? [], defaultInjectHosts, sentinelRegistry);
+    unsetEnvVars.push(...degradeToUnsetNames);
+    // Link masked AWS credentials into pairs so the proxy can re-sign
+    // SigV4 requests (the signature is derived from the secret; header
+    // substitution alone cannot fix it).
+    registerAwsPairs(credentials.envVars ?? [], credentials.awsPairs, defaultInjectHosts, setEnvVars, awsPairRegistry);
+    // Masked files: read the real bytes on the host, register a sentinel,
+    // write it to a fake file in the manager-owned temp dir. Missing/unreadable
+    // entries are skipped (same posture as an unset masked env var).
+    // degradeToDenyPaths carries paths whose extract pattern matched
+    // nothing with onExtractNoMatch: "deny" — merged into denyReadPaths
+    // below so both the read-deny config and the platform builders see
+    // them, and carried separately so they stay literal on the way there.
+    const files = credentials.files ?? [];
+    const { binds: maskedFileBinds, degradeToDenyPaths } = buildMaskedFileBinds(files, defaultInjectHosts, sentinelRegistry, maskedFileStore);
+    return {
+        denyReadPaths: [...new Set([...denyReadPaths, ...degradeToDenyPaths])],
+        unsetEnvVars: [...new Set(unsetEnvVars)],
+        setEnvVars,
+        maskedFileBinds,
+        maskedFileStoreDir: maskedFileStore.dirPath,
+        degradeToDenyPaths,
+    };
+}
+/**
+ * Pure (side-effect-free) chokepoint for credential file-deny
+ * paths — `credentials.files` entries with `mode: 'deny'`. Any
+ * code that needs the credential→denyRead contribution routes
+ * through here so a comparison predicate can read it without
+ * touching {@link sentinelRegistry}.
+ */
+function getCredentialDenyReadPaths(credentials) {
+    const files = credentials?.files ?? [];
+    return [...new Set(files.filter(f => f.mode === 'deny').map(f => f.path))];
+}
+/**
+ * The default write paths under a filesystem policy's read rules, for
+ * getFsWriteConfig() and wrapWithSandbox() alike. Fed the entries as
+ * configured, through the pure {@link getCredentialDenyReadPaths}: no glob
+ * expansion and no credential masking, because getFsWriteConfig() is a
+ * getter callers reach from permission checks and render paths. A mask entry
+ * that degrades to a deny is a file and cannot cover a directory, so
+ * leaving those out changes nothing. An entry with glob characters that is
+ * also the name of a path counts as that name too.
+ */
+function defaultWritePathsUnder({ denyRead, allowRead, credentials, }) {
+    return getDefaultWritePaths(readRulesOf(denyRead, allowRead, getCredentialDenyReadPaths(credentials)));
+}
+/**
+ * Union the explicit `filesystem.denyRead` with credential-derived
+ * deny paths. The single source of "what files does this config
+ * want read-denied" — all platforms route through here so a new
+ * credential kind that contributes deny paths reaches every
+ * backend.
+ */
+function unionDenyReadPaths(denyRead, credentialRestrictions) {
+    return [...new Set([...denyRead, ...credentialRestrictions.denyReadPaths])];
+}
+/**
+ * Strip a trailing `/**` from each read-path entry and, on Linux, replace
+ * any remaining glob with what `expandGlob` returns for it (bubblewrap takes
+ * concrete paths only). Other platforms match globs natively.
+ * On Linux the entry's other readings are added (see `withOtherReadings`);
+ * elsewhere the backend decides them. Entries the caller marked literal are
+ * not in the result: they travel in the `literal…` lists.
+ *
+ * `literalPaths` are the ones the library resolved itself (a masked
+ * credential file that degraded to deny) — each names one file on disk, so
+ * it is passed through whatever characters it contains. Expanded as a
+ * pattern, a name holding `[` matches nothing and the deny is lost.
+ *
+ * Each path once, where it first came up: every `**` pattern over one base
+ * returns the directories it could not list, and the Linux wrapper looks at
+ * every entry it is given.
+ */
+function* resolveReadPathEntries(kind, paths, expandGlob, literalPaths = []) {
+    const literal = new Set(literalPaths);
+    const resolved = new Set();
+    for (const p of spelledOf(paths)) {
+        const stripped = removeTrailingGlobSuffix(p);
+        if (getPlatform() === 'linux' &&
+            !literal.has(p) &&
+            containsGlobChars(stripped)) {
+            for (const found of yield* withOtherReadings(p, stripped, kind, expandGlob)) {
+                resolved.add(found);
+            }
+        }
+        else {
+            resolved.add(stripped);
+        }
+    }
+    return [...resolved];
+}
+/**
+ * Strip a trailing `/**` and drop what is still a glob on Linux: bwrap needs
+ * real paths. macOS subpath matching is recursive, so the strip is harmless
+ * there and the filter never fires.
+ * A glob that is also the name of a path that exists is kept, as that name.
+ * Marked entries are not in the result, as in {@link resolveReadPathEntries}.
+ */
+function stripWriteGlobs(kind, paths) {
+    return spelledOf(paths)
+        .map(p => removeTrailingGlobSuffix(p))
+        .filter(p => {
+        if (getPlatform() === 'linux' &&
+            containsGlobChars(p) &&
+            !hasNameReading(p, kind)) {
+            logForDebugging(`[Sandbox] Skipping glob write pattern on Linux: ${p}`);
+            return false;
+        }
+        return true;
+    });
+}
+function* expandAllowReadGlob(pattern, anchor) {
+    const expanded = (yield* walkGlobPatternSteps(pattern, { anchor })).matches;
+    logForDebugging(`[Sandbox] Expanded allowRead glob pattern "${pattern}" to ${expanded.length} paths on Linux`);
+    return expanded;
+}
+/**
+ * The read policy of the initialized config, for inspection and display.
+ * On Linux, denyRead globs are collapsed to covering directory mounts against
+ * this config's allowRead and {@link getFsWriteConfig}'s write roots, so
+ * `denyOnly` is only sound alongside that write config and must not be handed
+ * to wrapCommandWithSandboxLinux with a different one. Marked entries are
+ * in the `literal…` lists, as spelled: pass the object on whole.
+ */
+function getFsReadConfig() {
+    if (!config || config.filesystem.disabled) {
+        return { denyOnly: [], allowWithinDeny: [] };
+    }
+    // Credential deny paths are unioned with the caller's denyRead — never
+    // replacing it — so explicit filesystem restrictions always survive.
+    const credentialRestrictions = getCredentialRestrictions(config.credentials, config.network.allowedDomains);
+    // allowRead (re-allow within denied regions) is resolved first: the
+    // denyRead glob expansion collapses against it.
+    const allowPaths = finish(resolveReadPathEntries('allow', config.filesystem.allowRead ?? [], expandAllowReadGlob));
+    const reExposedPaths = reExposedBy(allowPaths, config.filesystem.allowRead, getFsWriteConfig());
+    const unlistableDenyDirs = new Set();
+    const listings = new Map();
+    const denyPaths = finish(resolveReadPathEntries('deny', unionDenyReadPaths(spelledOf(config.filesystem.denyRead), credentialRestrictions), (pattern, anchor) => expandReadDenyGlobLinuxSteps(pattern, reExposedPaths, unlistableDenyDirs, { anchor, listings }), credentialRestrictions.degradeToDenyPaths));
+    return {
+        denyOnly: denyPaths,
+        allowWithinDeny: allowPaths,
+        unlistableDenyDirs: [...unlistableDenyDirs],
+        ...literalReadLists(config.filesystem.denyRead, config.filesystem.allowRead),
+    };
+}
+function getFsWriteConfig() {
+    if (!config) {
+        return { allowOnly: getDefaultWritePaths(), denyWithinAllow: [] };
+    }
+    if (config.filesystem.disabled) {
+        return { allowOnly: ['/'], denyWithinAllow: [] };
+    }
+    const allowPaths = stripWriteGlobs('allow', config.filesystem.allowWrite);
+    const denyPaths = stripWriteGlobs('deny', config.filesystem.denyWrite);
+    const allowOnly = [
+        ...defaultWritePathsUnder({
+            denyRead: config.filesystem.denyRead,
+            allowRead: config.filesystem.allowRead,
+            credentials: config.credentials,
+        }),
+        ...allowPaths,
+    ];
+    return {
+        allowOnly,
+        denyWithinAllow: denyPaths,
+        ...literalWriteLists(config.filesystem.allowWrite, config.filesystem.denyWrite),
+    };
+}
+/**
+ * Build the Windows file-access set (deny stamps + sandbox-user
+ * grants) from `runtimeConfig`. Globs are expanded to concrete
+ * paths (point-in-time — a path appearing after this returns is NOT
+ * covered). Directory targets are accepted (the `(OI)(CI)` ACEs
+ * cover the subtree).
+ *
+ * The sandbox user has no inherent rights on real-user-owned files,
+ * so `allowWrite` (the working-tree roots) becomes a per-session
+ * `MODIFY_NO_FDC` ALLOW ACE for `<sb-SID>`, `allowRead` a
+ * `READ|EXECUTE` ALLOW ACE, and `denyRead`/`denyWrite` become an
+ * explicit DENY ACE for `<sb-SID>` on the target plus a
+ * `(OI)(CI) FILE_DELETE_CHILD` DENY on its parent.
+ */
+function computeWindowsFsAccessSet(c) {
+    const fs = c.filesystem;
+    // filesystem.disabled bypasses ALL filesystem rule generation —
+    // same as the macOS/Linux wrapWithSandbox path (readConfig /
+    // writeConfig left undefined). On Windows this means no ACL
+    // stamp/grant; credential FILE denies are dropped along with the
+    // rest (credential ENV: mode:'deny' is structural under the
+    // fresh srt-sandbox env; mode:'mask' sentinels are passed via
+    // the --env overlay).
+    if (fs?.disabled) {
+        return { grantRead: [], grantWrite: [], denyRead: [], denyWrite: [] };
+    }
+    const expand = expandWindowsFsPaths;
+    // `mode: 'deny'` — non-existent literals reach srt-win, which
+    // creates a placeholder chain and stamps it (deny lands on the
+    // exact target path). `mode: 'grant'` drops them (a grant on
+    // nothing is meaningless).
+    const denyRead = expand([
+        ...new Set([
+            ...(fs?.denyRead ?? []),
+            ...getCredentialDenyReadPaths(c.credentials),
+        ]),
+    ], { mode: 'deny' });
+    const denyWrite = expand(fs?.denyWrite ?? [], { mode: 'deny' });
+    return {
+        // `allowRead` also serves as `allowWithinDeny`: a file under a
+        // denied dir gets an explicit ALLOW ACE for the sandbox user,
+        // and explicit DENY on the parent doesn't override it because
+        // the recompose chokepoint orders deny-before-allow per-path.
+        grantRead: expand(fs?.allowRead ?? [], { mode: 'grant' }),
+        grantWrite: expand(fs?.allowWrite ?? [], { mode: 'grant' }),
+        denyRead,
+        denyWrite,
+    };
+}
+/**
+ * Snapshot the raw config fields that feed
+ * {@link computeWindowsFsAccessSet}. Used by updateConfig() to
+ * short-circuit the resolved-set diff (which re-runs glob
+ * expansion) when nothing relevant changed.
+ */
+function rawWindowsFsInputs(c) {
+    // Keyed exactly on what {@link computeWindowsFsAccessSet} reads.
+    // `network.allowedDomains` does NOT feed file-deny (only mask
+    // injectHosts), so a network-only updateConfig hits the cache.
+    return {
+        disabled: c.filesystem.disabled ?? false,
+        denyRead: [...c.filesystem.denyRead],
+        denyWrite: [...c.filesystem.denyWrite],
+        allowRead: [...(c.filesystem.allowRead ?? [])],
+        allowWrite: [...c.filesystem.allowWrite],
+        credFiles: getCredentialDenyReadPaths(c.credentials),
+    };
+}
+function sameRawWindowsFsInputs(a, b) {
+    return (a.disabled === b.disabled &&
+        samePathEntries(a.denyRead, b.denyRead) &&
+        samePathEntries(a.denyWrite, b.denyWrite) &&
+        samePathEntries(a.allowRead, b.allowRead) &&
+        samePathEntries(a.allowWrite, b.allowWrite) &&
+        samePathEntries(a.credFiles, b.credFiles));
+}
+/**
+ * True when `newConfig`'s file-deny inputs match what was
+ * stamped at initialize(). Compares raw inputs only (cheap,
+ * order-insensitive); never re-expands globs — updateConfig is
+ * warn-only on Windows and the resolved set wouldn't be used.
+ */
+function sameWindowsStampSet(newConfig) {
+    return (windowsFsRawInputs !== undefined &&
+        sameRawWindowsFsInputs(windowsFsRawInputs, rawWindowsFsInputs(newConfig)));
+}
+function getNetworkRestrictionConfig() {
+    if (!config) {
+        return {};
+    }
+    // Preserve an explicitly-empty allowlist: consumers need to distinguish
+    // "no network restriction configured" (absent) from "allowlist configured
+    // with zero entries" (block-all / ask-only). Stripping the empty array
+    // made a host app's restriction-status UI report an airgapped config as
+    // unrestricted. deniedHosts keeps the strip — an empty denylist and an
+    // absent one are semantically identical.
+    const allowedHosts = config.network.allowedDomains;
+    const deniedHosts = config.network.deniedDomains;
+    return {
+        allowedHosts,
+        ...(deniedHosts.length > 0 && { deniedHosts }),
+    };
+}
+function getAllowUnixSockets() {
+    return config?.network?.allowUnixSockets;
+}
+function getAllowAllUnixSockets() {
+    return config?.network?.allowAllUnixSockets;
+}
+function getAllowLocalBinding() {
+    return config?.network?.allowLocalBinding;
+}
+function getAllowMachLookup() {
+    return config?.network?.allowMachLookup;
+}
+function getIgnoreViolations() {
+    return config?.ignoreViolations;
+}
+function getEnableWeakerNestedSandbox() {
+    return config?.enableWeakerNestedSandbox;
+}
+function getEnableWeakerNetworkIsolation() {
+    return config?.enableWeakerNetworkIsolation;
+}
+function getAllowAppleEvents() {
+    return config?.allowAppleEvents;
+}
+function getRipgrepConfig() {
+    return config?.ripgrep ?? { command: 'rg' };
+}
+function getMandatoryDenySearchDepth() {
+    return config?.mandatoryDenySearchDepth ?? 3;
+}
+function getAllowGitConfig() {
+    return config?.filesystem?.allowGitConfig ?? false;
+}
+/**
+ * Union of session-level and per-call `git.safeDirectories`. Marks
+ * paths as `safe.directory` (dubious-ownership bypass) WITHOUT
+ * touching the write grant — the repo top-level for a subdirectory
+ * launch must NOT go in `filesystem.allowWrite`.
+ */
+function getGitSafeDirectories(customConfig) {
+    return [
+        ...(config?.git?.safeDirectories ?? []),
+        ...(customConfig?.git?.safeDirectories ?? []),
+    ];
+}
+function getSeccompConfig() {
+    return config?.seccomp;
+}
+function getProxyAuthToken() {
+    return proxyAuthToken;
+}
+function getProxyPort() {
+    return managerContext?.httpProxyPort;
+}
+function getSocksProxyPort() {
+    return managerContext?.socksProxyPort;
+}
+function getLinuxHttpSocketPath() {
+    return managerContext?.linuxBridge?.httpSocketPath;
+}
+function getLinuxSocksSocketPath() {
+    return managerContext?.linuxBridge?.socksSocketPath;
+}
+/**
+ * Wait for network initialization to complete if already in progress
+ * Returns true if initialized successfully, false otherwise
+ */
+async function waitForNetworkInitialization() {
+    if (!config) {
+        return false;
+    }
+    if (initializationPromise) {
+        try {
+            await initializationPromise;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return managerContext !== undefined;
+}
+/** A wrap that has started over this many times walks without giving the
+ *  thread back. */
+const RESTARTS_IN_TURNS = 2;
+/** In place of what a walk finds: the configuration was replaced under it. */
+const REPLACED = Symbol('replaced');
+async function wrapWithSandbox(command, binShell, customConfig, abortSignal, options) {
+    return wrapWithSandboxAgain(0, command, binShell, customConfig, abortSignal, options);
+}
+/** {@link wrapWithSandbox}, having started over `restarts` times. */
+async function wrapWithSandboxAgain(restarts, command, binShell, customConfig, abortSignal, options) {
+    const platform = getPlatform();
+    const commandId = options?.commandId;
+    registerCommandText(command, options);
+    const startedWith = config;
+    const startedAt = configInstalls;
+    const startedIn = workingDirectory();
+    const movedOn = () => config !== startedWith ||
+        configInstalls !== startedAt ||
+        workingDirectory() !== startedIn;
+    const startOver = () => wrapWithSandboxAgain(restarts + 1, command, binShell, customConfig, abortSignal, options);
+    /** `steps`, left as soon as the host is seen to have moved on: what they
+     *  would go on to find is for a wrap that starts over anyway. */
+    function* whileCurrent(steps) {
+        for (;;) {
+            if (movedOn())
+                return REPLACED;
+            const step = steps.next();
+            if (step.done)
+                return step.value;
+            yield;
+        }
+    }
+    const walked = (steps) => {
+        if (restarts < RESTARTS_IN_TURNS) {
+            return finishInTurns(whileCurrent(steps), abortSignal);
+        }
+        abortSignal?.throwIfAborted();
+        return finish(steps);
+    };
+    // filesystem.disabled bypasses ALL filesystem rule generation. Both
+    // platform wrappers treat readConfig/writeConfig === undefined as "no
+    // filesystem restrictions" (seatbelt emits `(allow file-write*)`; bwrap
+    // skips the `--ro-bind / /` root and all path binds).
+    //
+    // Precedence: when a caller passes a per-call filesystem override at all,
+    // its `disabled` (defaulting to false) wins outright. A global
+    // disabled=true must not silently discard a per-call tightening that
+    // omits the new key.
+    const fsDisabled = customConfig?.filesystem !== undefined
+        ? (customConfig.filesystem.disabled ?? false)
+        : (config?.filesystem.disabled ?? false);
+    // Credential env handling is independent of filesystem policy: unsetEnvVars /
+    // setEnvVars must be applied even when fsDisabled (the credential file
+    // deny-reads are dropped, but env scrubbing still happens).
+    const credentialRestrictions = getCredentialRestrictions(customConfig?.credentials ?? config?.credentials, customConfig?.network?.allowedDomains ?? config?.network?.allowedDomains);
+    // Get configs - use custom if provided, otherwise fall back to main config
+    // If neither exists, defaults to empty arrays (most restrictive)
+    // Always include default system write paths (like /dev/null, /tmp/claude)
+    let writeConfig;
+    let readConfig;
+    if (!fsDisabled) {
+        const userAllowWrite = stripWriteGlobs('allow', customConfig?.filesystem?.allowWrite ??
+            config?.filesystem.allowWrite ??
+            []);
+        writeConfig = {
+            allowOnly: [
+                ...defaultWritePathsUnder({
+                    denyRead: customConfig?.filesystem?.denyRead ??
+                        config?.filesystem.denyRead ??
+                        [],
+                    allowRead: customConfig?.filesystem?.allowRead ?? config?.filesystem.allowRead,
+                    credentials: customConfig?.credentials ?? config?.credentials,
+                }),
+                ...userAllowWrite,
+            ],
+            denyWithinAllow: stripWriteGlobs('deny', customConfig?.filesystem?.denyWrite ??
+                config?.filesystem.denyWrite ??
+                []),
+            ...literalWriteLists(customConfig?.filesystem?.allowWrite ?? config?.filesystem.allowWrite, customConfig?.filesystem?.denyWrite ?? config?.filesystem.denyWrite),
+        };
+        // Credential deny paths are unioned with the caller's denyRead — never
+        // replacing it — so explicit filesystem restrictions always survive.
+        // allowRead is resolved first: on Linux a denyRead glob's expansion is
+        // collapsed against the paths that re-expose contents under a denied
+        // directory (allowRead + allowWrite), so both must be final here.
+        const expandedAllowRead = await walked(resolveReadPathEntries('allow', customConfig?.filesystem?.allowRead ??
+            config?.filesystem.allowRead ??
+            [], expandAllowReadGlob));
+        if (expandedAllowRead === REPLACED)
+            return startOver();
+        // The TLS-termination CA cert and the trust bundle the env vars point at
+        // (NODE_EXTRA_CA_CERTS etc.) must be readable by the child, even if their
+        // paths fall under a user-configured denyRead.
+        if (mitmCA) {
+            expandedAllowRead.push(mitmCA.certPath, mitmCA.trustBundlePath);
+        }
+        // Likewise the JVM proxy agent jar JAVA_TOOL_OPTIONS points at.
+        if (javaAgentJarPath) {
+            expandedAllowRead.push(javaAgentJarPath);
+        }
+        const reExposedPaths = reExposedBy(expandedAllowRead, customConfig?.filesystem?.allowRead ?? config?.filesystem.allowRead, writeConfig);
+        const unlistableDenyDirs = new Set();
+        const listings = new Map();
+        const expandedDenyRead = await walked(resolveReadPathEntries('deny', unionDenyReadPaths(spelledOf(customConfig?.filesystem?.denyRead ?? config?.filesystem.denyRead), credentialRestrictions), (pattern, anchor) => expandReadDenyGlobLinuxSteps(pattern, reExposedPaths, unlistableDenyDirs, { anchor, listings }), credentialRestrictions.degradeToDenyPaths));
+        if (expandedDenyRead === REPLACED)
+            return startOver();
+        readConfig = {
+            denyOnly: expandedDenyRead,
+            allowWithinDeny: expandedAllowRead,
+            unlistableDenyDirs: [...unlistableDenyDirs],
+            ...literalReadLists(customConfig?.filesystem?.denyRead ?? config?.filesystem.denyRead, customConfig?.filesystem?.allowRead ?? config?.filesystem.allowRead),
+        };
+    }
+    // Check if network config is specified - this determines if we need network restrictions
+    // Network restriction is needed when:
+    // 1. customConfig has network.allowedDomains defined (even if empty array)
+    // 2. OR config has network.allowedDomains defined (even if empty array)
+    // An empty allowedDomains array still requests network restrictions.
+    // Custom lists do not replace the live proxy's session allow/deny lists.
+    // A custom empty list does not revoke session allowances.
+    const hasNetworkConfig = customConfig?.network?.allowedDomains !== undefined ||
+        config?.network?.allowedDomains !== undefined;
+    // Network RESTRICTION is needed whenever network config is specified
+    // This includes empty allowedDomains arrays.
+    const needsNetworkRestriction = hasNetworkConfig;
+    // Network PROXY is needed whenever network config is specified
+    // Even with empty allowedDomains, we route through proxy so that:
+    // 1. updateConfig() can enable network access for already-running processes
+    // 2. The proxy enforces session policy and can ask for approval.
+    const needsNetworkProxy = hasNetworkConfig;
+    // Wait for network initialization only if proxy is actually needed
+    if (needsNetworkProxy) {
+        await waitForNetworkInitialization();
+    }
+    // INVARIANT: one wrap, one configuration. updateConfig() can run in any of
+    // the turns above, and what was read before it must not be put together
+    // with what is read after it: the write list of one configuration with the
+    // allowGitConfig of another is a policy nobody chose. So the wrap starts
+    // over. Nothing from here to the platform's wrapper awaits.
+    //
+    // And one working directory, which a relative entry is resolved against
+    // wherever it is read: a `.` bound back from where the host has gone to,
+    // over denies walked from where it was, uncovers what they matched.
+    //
+    // INVARIANT: what a wrap hands out was read from the disk after its
+    // configuration was installed. A host that writes a file and then installs
+    // a rule that denies it finds it denied by every wrap that goes by that
+    // rule. So a wrap that starts over keeps nothing of what it has listed or
+    // walked, the same rules included. A configuration installed after this
+    // check is the next wrap's.
+    //
+    // An embedder can replace the configuration many times during one walk.
+    // After RESTARTS_IN_TURNS the wrap walks without a turn of the event loop,
+    // so no timer or I/O callback replaces it meanwhile. That holds the thread
+    // for one walk, as every wrap did before the walk took turns. It is not a
+    // proof that the wrap ends: a promise continuation, or anything at all
+    // while the network is still being initialized, can replace it between the
+    // walk and this check, and the wrap then starts over once more.
+    if (movedOn())
+        return startOver();
+    // Check custom config to allow pseudo-terminal (can be applied dynamically)
+    const allowPty = customConfig?.allowPty ?? config?.allowPty;
+    const allowUnixSockets = customConfig?.network?.allowUnixSockets ?? getAllowUnixSockets();
+    const allowAllUnixSockets = customConfig?.network?.allowAllUnixSockets ?? getAllowAllUnixSockets();
+    const allowLocalBinding = customConfig?.network?.allowLocalBinding ?? getAllowLocalBinding();
+    const allowMachLookup = customConfig?.network?.allowMachLookup ?? getAllowMachLookup();
+    const allowGitConfig = customConfig?.filesystem?.allowGitConfig ?? getAllowGitConfig();
+    const enableWeakerNestedSandbox = customConfig?.enableWeakerNestedSandbox ?? getEnableWeakerNestedSandbox();
+    const enableWeakerNetworkIsolation = customConfig?.enableWeakerNetworkIsolation ?? getEnableWeakerNetworkIsolation();
+    const allowAppleEvents = customConfig?.allowAppleEvents ?? getAllowAppleEvents();
+    const mandatoryDenySearchDepth = customConfig?.mandatoryDenySearchDepth ?? getMandatoryDenySearchDepth();
+    const gitSafeDirectories = getGitSafeDirectories(customConfig);
+    switch (platform) {
+        case 'macos':
+            // macOS sandbox profile supports glob patterns directly, no ripgrep needed
+            return wrapCommandWithSandboxMacOS({
+                command,
+                commandId,
+                needsNetworkRestriction,
+                // Only pass proxy ports if proxy is running (when there are domains to filter)
+                httpProxyPort: needsNetworkProxy ? getProxyPort() : undefined,
+                socksProxyPort: needsNetworkProxy ? getSocksProxyPort() : undefined,
+                proxyAuthToken: needsNetworkProxy ? proxyAuthToken : undefined,
+                caCertPath: mitmCA?.trustBundlePath,
+                javaAgentJarPath: needsNetworkProxy ? javaAgentJarPath : undefined,
+                readConfig,
+                writeConfig,
+                unsetEnvVars: credentialRestrictions.unsetEnvVars,
+                setEnvVars: credentialRestrictions.setEnvVars,
+                maskedFileBinds: credentialRestrictions.maskedFileBinds,
+                degradeToDenyPaths: credentialRestrictions.degradeToDenyPaths,
+                allowUnixSockets,
+                allowAllUnixSockets,
+                allowLocalBinding,
+                allowMachLookup,
+                ignoreViolations: getIgnoreViolations(),
+                allowPty,
+                allowGitConfig,
+                gitSafeDirectories,
+                enableWeakerNetworkIsolation,
+                allowAppleEvents,
+                binShell,
+            });
+        case 'linux':
+            return wrapCommandWithSandboxLinux({
+                command,
+                commandId,
+                needsNetworkRestriction,
+                // Only pass socket paths if proxy is running (when there are domains to filter)
+                httpSocketPath: needsNetworkProxy
+                    ? getLinuxHttpSocketPath()
+                    : undefined,
+                socksSocketPath: needsNetworkProxy
+                    ? getLinuxSocksSocketPath()
+                    : undefined,
+                httpProxyPort: needsNetworkProxy
+                    ? managerContext?.httpProxyPort
+                    : undefined,
+                socksProxyPort: needsNetworkProxy
+                    ? managerContext?.socksProxyPort
+                    : undefined,
+                proxyAuthToken: needsNetworkProxy ? proxyAuthToken : undefined,
+                caCertPath: mitmCA?.trustBundlePath,
+                javaAgentJarPath: needsNetworkProxy ? javaAgentJarPath : undefined,
+                readConfig,
+                writeConfig,
+                unsetEnvVars: credentialRestrictions.unsetEnvVars,
+                setEnvVars: credentialRestrictions.setEnvVars,
+                maskedFileBinds: credentialRestrictions.maskedFileBinds,
+                maskedFileStoreDir: credentialRestrictions.maskedFileStoreDir,
+                enableWeakerNestedSandbox,
+                allowAllUnixSockets,
+                binShell,
+                ripgrepConfig: getRipgrepConfig(),
+                mandatoryDenySearchDepth,
+                allowGitConfig,
+                gitSafeDirectories,
+                seccompConfig: getSeccompConfig(),
+                bwrapPath: config?.bwrapPath,
+                socatPath: config?.socatPath,
+                observeSocketPath: linuxMonitor?.observeSocketPath,
+                abortSignal,
+            }).catch((err) => {
+                // It awaits once more, for its scan: see the invariant above.
+                if (err instanceof WorkingDirectoryChanged)
+                    return startOver();
+                throw err;
+            });
+        case 'windows':
+            // Windows wraps to an argv array, not a shell string. Forcing
+            // callers through wrapWithSandboxArgv() means they spawn with
+            // {shell:false}, which is the security boundary that keeps the
+            // user's command bytes off the HOST shell.
+            throw new Error('wrapWithSandbox() returns a shell string and is not supported ' +
+                'on Windows. Use SandboxManager.wrapWithSandboxArgv() and ' +
+                'spawn the result with {shell: false}.');
+        default:
+            // Unsupported platform - this should not happen since isSandboxingEnabled() checks platform support
+            throw new Error(`Sandbox configuration is not supported on platform: ${platform}`);
+    }
+}
+/**
+ * Wrap `command` for the sandbox and return a spawn descriptor:
+ * `{ argv, env }`, suitable for
+ * `spawn(argv[0], argv.slice(1), {shell: false, env})`.
+ *
+ * On Windows this is the ONLY supported wrap method (see
+ * {@link wrapWithSandbox}); `env` is the broker process's spawn env
+ * — the sandboxed child gets a fresh `srt-sandbox` profile env with
+ * only the `--env` overlay baked into `argv` (see
+ * {@link wrapCommandWithSandboxWindows}). On
+ * macOS/Linux `argv` is `[binShell, '-c', <wrapWithSandbox result>]`
+ * (proxy env is baked into that command) and `env` is the unchanged
+ * `process.env`, so callers can spawn uniformly across platforms.
+ *
+ * @param cwd the working directory the caller will spawn the result
+ *   with. On Windows the child's cwd is whatever the caller passes
+ *   as the spawn `{cwd:}` option (there is no `--cwd` flag), and
+ *   the `safe.directory` git-config injection derives from this — so
+ *   pass the same value here as to `spawn({cwd})`. Defaults to
+ *   `process.cwd()`. Currently unused on macOS/Linux.
+ */
+async function wrapWithSandboxArgv(command, binShell, customConfig, abortSignal, cwd, options) {
+    const platform = getPlatform();
+    if (platform === 'windows') {
+        const hasNetworkConfig = customConfig?.network?.allowedDomains !== undefined ||
+            config?.network?.allowedDomains !== undefined;
+        if (hasNetworkConfig) {
+            await waitForNetworkInitialization();
+        }
+        const credentialRestrictions = getCredentialRestrictions(customConfig?.credentials ?? config?.credentials, customConfig?.network?.allowedDomains ?? config?.network?.allowedDomains);
+        // Per-exec FILE denies (customConfig only — the session-level
+        // config's denies were already stamped at initialize()).
+        // Paths go through `expandWindowsFsPaths` — the SAME
+        // chokepoint the session-level set uses (point-in-time glob
+        // expand, normalize, missing→drop) — so a per-exec entry
+        // resolves identically to its session-level equivalent.
+        // macOS/Linux per-exec already reuses session-level expansion;
+        // Windows now matches.
+        //
+        // The dedup against `windowsFsStampedSet` is an OPTIMIZATION,
+        // not a correctness gate: re-stamping a session-held path
+        // under the exec's distinct holder is refcount-safe but wastes
+        // a SetSecurityInfo round-trip.
+        //
+        // filesystem.disabled bypasses ALL filesystem rule generation
+        // — including credential-derived file denies — same ordering
+        // as session-level `computeWindowsFsAccessSet` (credential
+        // ENV: mode:'deny' is structural under the fresh srt-sandbox
+        // env; mode:'mask' sentinels are passed via the --env
+        // overlay).
+        // Per-exec allowRead/allowWrite throw — `srt-win exec` only
+        // exposes `--deny-*`; per-exec grants are not implemented.
+        const fsCfg = customConfig?.filesystem;
+        let perExecDenyRead = [];
+        let perExecDenyWrite = [];
+        if (!fsCfg?.disabled) {
+            if (fsCfg?.allowRead?.length || fsCfg?.allowWrite?.length) {
+                throw new Error(`Per-exec filesystem.allowRead/allowWrite is not supported ` +
+                    `on Windows — \`srt-win exec\` only exposes per-exec ` +
+                    `denies. Set them at the session level (initialize()).`);
+            }
+            const rawRead = [
+                ...(fsCfg?.denyRead ?? []),
+                ...getCredentialDenyReadPaths(customConfig?.credentials),
+            ];
+            const rawWrite = fsCfg?.denyWrite ?? [];
+            // Skip on the dominant path (no per-exec fs or
+            // credential-file deny).
+            if (rawRead.length > 0 || rawWrite.length > 0) {
+                const sessRead = new Set(windowsFsStampedSet?.denyRead ?? []);
+                const sessWrite = new Set(windowsFsStampedSet?.denyWrite ?? []);
+                const expand = expandWindowsFsPaths;
+                perExecDenyRead = expand(rawRead, { mode: 'deny' }).filter(p => !sessRead.has(p));
+                perExecDenyWrite = expand(rawWrite, { mode: 'deny' }).filter(p => !sessRead.has(p) && !sessWrite.has(p));
+            }
+        }
+        // Per-exec deny rides on argv (`acl stamp` reads stdin, but
+        // exec's stdin belongs to the child). The CreateProcessW
+        // length check lives in `wrapCommandWithSandboxWindows`
+        // where the full argv (incl. shell + user command) is known.
+        //
+        // The `denyReadPaths` half of the SESSION-level credentials
+        // is already unioned into the stamp set at initialize() time
+        // via `computeWindowsFsAccessSet`.
+        registerCommandText(command, options);
+        return wrapCommandWithSandboxWindows({
+            command,
+            commandId: options?.commandId,
+            httpProxyPort: hasNetworkConfig ? getProxyPort() : undefined,
+            socksProxyPort: hasNetworkConfig ? getSocksProxyPort() : undefined,
+            proxyAuthToken: hasNetworkConfig ? proxyAuthToken : undefined,
+            // mode:'deny' env vars are structurally absent (fresh
+            // srt-sandbox profile env). mode:'mask' sentinels are
+            // passed via the --env overlay so the sandboxed child sees
+            // the sentinel value, same as macOS/Linux.
+            setEnvVars: credentialRestrictions.setEnvVars,
+            denyRead: perExecDenyRead,
+            denyWrite: perExecDenyWrite,
+            // safe.directory: cwd + the resolved session-level write
+            // grants + explicit git.safeDirectories — the working-tree
+            // roots the sandbox user has MODIFY on plus any repo top-level
+            // the caller marks as safe without granting write.
+            cwd,
+            allowWrite: windowsFsStampedSet?.grantWrite,
+            gitSafeDirectories: getGitSafeDirectories(customConfig),
+            caCertPath: mitmCA?.trustBundlePath,
+            binShell: parseWindowsBinShell(binShell),
+            srtWin: customConfig?.windows?.srtWin
+                ? resolveSrtWin(customConfig.windows.srtWin)
+                : (srtWinSpawn ?? resolveSrtWin(config?.windows?.srtWin)),
+        });
+    }
+    // macOS/Linux: delegate to the existing string wrapper, then put
+    // the result behind `<shell> -c` so the caller's argv-spawn works.
+    if (typeof binShell === 'object') {
+        throw new Error('binShell object form is Windows-only; pass a shell path string ' +
+            'on macOS/Linux');
+    }
+    const wrapped = await wrapWithSandbox(command, binShell, customConfig, abortSignal, options);
+    const shell = binShell ?? '/bin/bash';
+    return { argv: [shell, '-c', wrapped], env: process.env };
+}
+/**
+ * Get the current sandbox configuration
+ * @returns The current configuration, or undefined if not initialized
+ */
+function getConfig() {
+    return config;
+}
+/**
+ * Update the sandbox configuration in place.
+ *
+ * **Network/allowlist changes are a live swap**: the running
+ * mux proxy reads `config.network.allowedDomains` /
+ * `deniedDomains` per-request (via `filterNetworkRequest`), so
+ * reassigning `config` here takes effect on the next connection
+ * with no proxy rebind and no port change — on every platform,
+ * including Windows. This is what lets a host enable/deny domains
+ * for already-running sandboxed children.
+ *
+ * Filesystem changes (denyRead/denyWrite) are NOT applied live:
+ * macOS bakes them into the seatbelt profile at wrap time, and
+ * Linux/Windows bake them into the bwrap argv / DENY-ACE set at
+ * wrap time. Call reset() + initialize() to apply a new
+ * filesystem config.
+ *
+ * @param newConfig - The new configuration to use
+ */
+function updateConfig(newConfig) {
+    if (getPlatform() === 'windows' &&
+        config &&
+        !sameWindowsStampSet(newConfig)) {
+        logForDebugging(`[Sandbox Windows] updateConfig: the resolved file-access set ` +
+            `(filesystem.* ∪ credentials.files) changed but the ACL ` +
+            `stamp/grant is session-wide — call reset() then initialize() ` +
+            `to apply. The previously-applied set stays in effect.`, { level: 'warn' });
+    }
+    // Built before anything is swapped, so a malformed range leaves the
+    // previous config fully in effect.
+    const nextGuard = createResolvedAddressGuard(newConfig.network);
+    // Deep clone the config to avoid mutations. structuredClone cannot clone
+    // functions, so pull filterRequest out, clone the rest, and put it back —
+    // a function reference is immutable in the sense that matters here.
+    const { filterRequest, ...rest } = newConfig.network;
+    config = structuredClone({ ...newConfig, network: rest });
+    config.network.filterRequest = filterRequest;
+    configInstalls++;
+    resolvedAddressGuard = nextGuard;
+    // Re-resolve parent proxy so hot-reload picks up changes. Note: the proxy
+    // servers capture `parentProxy` by value at creation, so changes here take
+    // effect only on re-initialize. This keeps the state consistent for the
+    // next initialize() call.
+    parentProxy = resolveParentProxy(newConfig.network.parentProxy);
+    logForDebugging('Sandbox configuration updated');
+}
+/**
+ * Lightweight cleanup to call after each sandboxed command completes.
+ *
+ * On Linux, bwrap creates empty files on the host filesystem as mount points
+ * when protecting non-existent deny paths (e.g. ~/.bashrc, ~/.gitconfig).
+ * These persist after bwrap exits. This function removes them.
+ *
+ * Safe to call on any platform — it's a no-op on macOS.
+ * Also called automatically by reset() and on process exit as safety nets.
+ */
+function cleanupAfterCommand() {
+    cleanupBwrapMountPoints();
+}
+/**
+ * How long to wait for a bridge process to exit after SIGTERM before
+ * escalating to SIGKILL.
+ *
+ * socat exits within ~10ms of SIGTERM; this is purely a safety margin.
+ * Keep it well below bun's default 5s test/hook timeout: when a bridge's
+ * `'exit'` event is missed entirely (a Linux-only Bun pidfd notification
+ * bug, oven-sh/bun#30301), this timer is the only thing that lets `reset()`
+ * make progress, and a 5000ms value here loses the race against the hook
+ * timer by a couple of milliseconds — that race was the dominant CI flake.
+ */
+const BRIDGE_EXIT_TIMEOUT_MS = 1500;
+/**
+ * SIGTERM a bridge process and resolve once it has exited.
+ *
+ * Returns immediately if the process has already exited (`.exitCode` /
+ * `.signalCode` set) — registering `.once('exit')` after the event has
+ * already been emitted produces a listener that never fires.
+ *
+ * Falls back to SIGKILL after {@link BRIDGE_EXIT_TIMEOUT_MS}.
+ */
+function killBridgeProcess(proc, label) {
+    // Already exited → 'exit' already emitted → a fresh once('exit') would
+    // never fire. Don't wait on it.
+    if (!proc.pid || proc.exitCode !== null || proc.signalCode !== null) {
+        return Promise.resolve();
+    }
+    try {
+        process.kill(proc.pid, 'SIGTERM');
+        logForDebugging(`Sent SIGTERM to ${label} bridge process`);
+    }
+    catch (err) {
+        if (err.code !== 'ESRCH') {
+            logForDebugging(`Error killing ${label} bridge: ${err}`, {
+                level: 'error',
+            });
+        }
+        // ESRCH = process already gone; nothing to wait for either way.
+        return Promise.resolve();
+    }
+    return new Promise(resolve => {
+        let settled = false;
+        const done = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve();
+        };
+        proc.once('exit', () => {
+            logForDebugging(`${label} bridge process exited`);
+            done();
+        });
+        const timer = setTimeout(() => {
+            // Re-check liveness — the 'exit' may have raced us.
+            if (proc.exitCode === null && proc.signalCode === null) {
+                logForDebugging(`${label} bridge did not exit, forcing SIGKILL`, {
+                    level: 'warn',
+                });
+                try {
+                    if (proc.pid)
+                        process.kill(proc.pid, 'SIGKILL');
+                }
+                catch {
+                    // Process may have already exited
+                }
+            }
+            done();
+        }, BRIDGE_EXIT_TIMEOUT_MS);
+        // The bridge process is being torn down; this timer must not be the
+        // only thing keeping the event loop alive.
+        timer.unref?.();
+    });
+}
+/**
+ * Forcibly close an http.Server, including any in-flight requests.
+ *
+ * Plain `server.close()` waits for every active request to finish.
+ * The proxy may be mid-upstream-request when reset() runs (e.g. a test's
+ * curl was killed by --max-time while the proxy was still dialing the
+ * real example.com / api.github.com), and `dialDirect()` allows up to
+ * 30s before giving up. Combined with a socat fork that hasn't yet seen
+ * its unix-socket EOF, that leaves a fully-open inbound connection and
+ * `server.close()` never calls back. `closeAllConnections()` (Node 18.2+,
+ * also implemented in Bun) tears down those sockets so `close()` resolves
+ * immediately.
+ */
+function forceCloseHttpServer(server) {
+    return new Promise(resolve => {
+        // Must run *before* close(): in Bun, close() also detaches the
+        // underlying handle, so a closeAllConnections() called afterwards
+        // becomes a no-op and the close callback waits for the in-flight
+        // request to drain — defeating the purpose. With closeAllConnections()
+        // first, the connections are gone by the time close() runs and its
+        // callback fires immediately (Bun reports "Server is not running.",
+        // Node reports no error). Verified against both orderings.
+        if (typeof server.closeAllConnections === 'function') {
+            server.closeAllConnections();
+        }
+        server.close(error => {
+            if (error && error.message !== 'Server is not running.') {
+                logForDebugging(`Error closing HTTP proxy server: ${error.message}`, {
+                    level: 'error',
+                });
+            }
+            resolve();
+        });
+    });
+}
+async function reset() {
+    // Windows: release this session's sandbox-user ACEs. Best-effort
+    // — log anomalies rather than throw, so teardown always
+    // completes. Leftover ACEs are recoverable later via
+    // `srt-win acl recover` (which sweeps by trustee SID).
+    if (windowsFsStampedSet && windowsFsSbUserSid) {
+        const sb = windowsFsSbUserSid;
+        // Captured at initialize() — the SAME binary the grants/stamps
+        // were applied with, immune to `config` mutation between.
+        const srtWin = srtWinSpawn;
+        // 'restored'/'alreadyOriginal' are the pre- same-user-removal
+        // srt-win's success vocabulary; 'revoked'/'stillHeld' are the
+        // post-. Either is non-anomalous.
+        const ok = new Set(['revoked', 'stillHeld', 'restored', 'alreadyOriginal']);
+        const log = (kind, e) => {
+            if (!ok.has(e.status)) {
+                logForDebugging(`[Sandbox Windows] ${kind}: '${e.path}' ${e.status} — ` +
+                    `ACE may be left in place; resolve and run ` +
+                    `\`srt-win acl recover\` to clear`, { level: 'warn' });
+            }
+        };
+        for (const e of revokeWindowsAcl({ sandboxUserSid: sb, srtWin }) ?? []) {
+            log('grant revoke', e);
+        }
+        for (const e of restoreWindowsAcl({ sandboxUserSid: sb, srtWin }) ?? []) {
+            log('deny restore', e);
+        }
+    }
+    windowsFsStampedSet = undefined;
+    windowsFsSbUserSid = undefined;
+    windowsFsRawInputs = undefined;
+    srtWinSpawn = undefined;
+    // windowsWfpVerified is NOT cleared — per-process, not per-session.
+    // Clean up any leftover bwrap mount points. Force past the
+    // active-sandbox counter — reset() means the session is over.
+    cleanupBwrapMountPoints({ force: true });
+    // Stop log monitor
+    if (logMonitorShutdown) {
+        logMonitorShutdown();
+        logMonitorShutdown = undefined;
+    }
+    if (linuxMonitor) {
+        linuxMonitor.stop();
+        linuxMonitor = undefined;
+    }
+    if (managerContext?.linuxBridge) {
+        const { httpSocketPath, socksSocketPath, httpBridgeProcess, socksBridgeProcess, } = managerContext.linuxBridge;
+        // Kill both bridges and wait for them to exit
+        await Promise.all([
+            killBridgeProcess(httpBridgeProcess, 'HTTP'),
+            killBridgeProcess(socksBridgeProcess, 'SOCKS'),
+        ]);
+        // Clean up sockets
+        if (httpSocketPath) {
+            try {
+                fs.rmSync(httpSocketPath, { force: true });
+                logForDebugging('Cleaned up HTTP socket');
+            }
+            catch (err) {
+                logForDebugging(`HTTP socket cleanup error: ${err}`, {
+                    level: 'error',
+                });
+            }
+        }
+        if (socksSocketPath) {
+            try {
+                fs.rmSync(socksSocketPath, { force: true });
+                logForDebugging('Cleaned up SOCKS socket');
+            }
+            catch (err) {
+                logForDebugging(`SOCKS socket cleanup error: ${err}`, {
+                    level: 'error',
+                });
+            }
+        }
+    }
+    // Close servers in parallel (only if they exist, i.e., were started by us)
+    const closePromises = [];
+    if (mitmCA) {
+        closePromises.push(disposeMitmCA(mitmCA));
+    }
+    if (muxProxyServer) {
+        closePromises.push(muxProxyServer.close().catch((error) => {
+            logForDebugging(`Error closing mux proxy server: ${error.message}`, {
+                level: 'error',
+            });
+        }));
+    }
+    if (httpProxyServer) {
+        closePromises.push(forceCloseHttpServer(httpProxyServer));
+    }
+    if (socksProxyServer) {
+        const socksClose = socksProxyServer.close().catch((error) => {
+            logForDebugging(`Error closing SOCKS proxy server: ${error.message}`, {
+                level: 'error',
+            });
+        });
+        closePromises.push(socksClose);
+    }
+    // Wait for all servers to close
+    await Promise.all(closePromises);
+    // Clear references
+    muxProxyServer = undefined;
+    httpProxyServer = undefined;
+    proxyAuthToken = undefined;
+    socksProxyServer = undefined;
+    managerContext = undefined;
+    initializationPromise = undefined;
+    parentProxy = undefined;
+    resolvedAddressGuard = createResolvedAddressGuard();
+    mitmCA = undefined;
+    javaAgentJarPath = undefined;
+    sentinelRegistry.clear();
+    awsPairRegistry.clear();
+    commandTextsByKey.clear();
+    maskedFileStore.dispose();
+}
+function getSandboxViolationStore() {
+    return sandboxViolationStore;
+}
+function annotateStderrWithSandboxFailures(command, stderr) {
+    if (!config) {
+        return stderr;
+    }
+    const violations = sandboxViolationStore.getViolationsForCommand(command);
+    if (violations.length === 0) {
+        return stderr;
+    }
+    let annotated = stderr;
+    annotated += EOL + '<sandbox_violations>' + EOL;
+    for (const violation of violations) {
+        annotated += violation.line + EOL;
+    }
+    annotated += '</sandbox_violations>';
+    return annotated;
+}
+/**
+ * Returns glob patterns from Edit/Read permission rules that are not
+ * fully supported on Linux. Returns empty array on macOS or when
+ * sandboxing is disabled.
+ *
+ * Patterns ending with /** are excluded since they work as subpaths.
+ * So are entries marked literal. An entry that is also the name of a path
+ * that exists is still returned: what is returned must not depend on what
+ * is on the disk, which a sandboxed command can change.
+ */
+function getLinuxGlobPatternWarnings() {
+    // Only warn on Linux/WSL (bubblewrap doesn't support globs)
+    // macOS supports glob patterns via regex conversion
+    if (getPlatform() !== 'linux' || !config || config.filesystem.disabled) {
+        return [];
+    }
+    const globPatterns = [];
+    // Write paths take no globs at all on Linux: bubblewrap binds concrete
+    // paths, and nothing expands them.
+    const allPaths = [
+        ...config.filesystem.allowWrite,
+        ...config.filesystem.denyWrite,
+    ];
+    for (const path of allPaths) {
+        if (typeof path !== 'string')
+            continue;
+        // Strip trailing /** since that's just a subpath (directory and everything under it)
+        const pathWithoutTrailingStar = removeTrailingGlobSuffix(path);
+        // Only warn if there are still glob characters after removing trailing /**
+        if (containsGlobChars(pathWithoutTrailingStar)) {
+            globPatterns.push(path);
+        }
+    }
+    // Read paths are expanded, so a glob there is supported — unless the
+    // pattern has no literal directory for the walk to start from (a wildcard
+    // in its first path component, `/**/*.pem`), which expands to nothing and
+    // leaves the entry unenforced.
+    for (const path of [
+        ...config.filesystem.denyRead,
+        ...(config.filesystem.allowRead ?? []),
+    ]) {
+        if (typeof path !== 'string')
+            continue;
+        const baseDir = globPatternBaseDir(normalizePathForSandbox(path));
+        if (containsGlobChars(removeTrailingGlobSuffix(path)) &&
+            (baseDir === '' || baseDir === '/')) {
+            globPatterns.push(path);
+        }
+    }
+    return globPatterns;
+}
+// ============================================================================
+// Export as Namespace with Interface
+// ============================================================================
+/**
+ * Global sandbox manager that handles both network and filesystem restrictions
+ * for this session. This runs outside of the sandbox, on the host machine.
+ */
+export const SandboxManager = {
+    initialize,
+    isSupportedPlatform,
+    isSandboxingEnabled,
+    checkDependencies,
+    checkDependenciesAsync,
+    getFsReadConfig,
+    getFsWriteConfig,
+    getNetworkRestrictionConfig,
+    getAllowUnixSockets,
+    getAllowLocalBinding,
+    getAllowMachLookup,
+    getIgnoreViolations,
+    getEnableWeakerNestedSandbox,
+    getProxyPort,
+    getProxyAuthToken,
+    getSocksProxyPort,
+    getLinuxHttpSocketPath,
+    getLinuxSocksSocketPath,
+    waitForNetworkInitialization,
+    wrapWithSandbox,
+    wrapWithSandboxArgv,
+    cleanupAfterCommand,
+    reset,
+    getMitmCA: () => mitmCA,
+    getSentinelRegistry: () => sentinelRegistry,
+    getAwsPairRegistry: () => awsPairRegistry,
+    getMaskedFileStore: () => maskedFileStore,
+    getSandboxViolationStore,
+    annotateStderrWithSandboxFailures,
+    getLinuxGlobPatternWarnings,
+    getConfig,
+    updateConfig,
+};
+//# sourceMappingURL=sandbox-manager.js.map