@provos/ironcurtain 0.9.1 → 0.11.0

package/dist/trusted-process/mcp-proxy-server.js

@@ -1,65 +1,53 @@
 /**
- * MCP Proxy Server -- The trusted process running as a standalone MCP server.
+ * MCP Proxy Server -- Standalone MCP subprocess for Code Mode.
  *
- * Code Mode spawns this as a child process via stdio transport. It acts
- * as the security boundary between the sandbox and real MCP servers:
+ * Runs as a child process spawned by MCPClientManager. Acts as a pure
+ * MCP pass-through relay: connects to real MCP backend servers and
+ * forwards tool calls without any policy evaluation. The coordinator
+ * in the parent process owns the full security pipeline.
  *
- * 1. Connects to real MCP servers as a client
- * 2. Exposes their tools with passthrough schemas
- * 3. Evaluates every tool call against the policy engine
- * 4. Forwards allowed calls to real servers, denies or escalates others
- * 5. Logs every request and decision to the append-only audit log
+ * Responsibilities:
+ *   - MCP transport setup (stdio/UDS/TCP)
+ *   - Backend MCP server connection (StdioClientTransport)
+ *   - OAuth credential injection and TokenFileRefresher
+ *   - Sandbox-runtime wrapping (srt)
+ *   - ListTools handler (raw pass-through)
+ *   - CallTool handler (pure forward to backend)
+ *   - Virtual proxy tools (MITM_CONTROL_ADDR)
+ *   - Tool description hints injection
+ *   - Roots bridging: on `notifications/roots/list_changed` from the
+ *     coordinator, fetch fresh roots via `server.listRoots()`, update
+ *     the shared `relayRoots` array, and notify each backend client so
+ *     they re-query their `roots/list` handlers with the new set.
  *
  * Configuration via environment variables:
- *   AUDIT_LOG_PATH     -- path to the audit log file
  *   MCP_SERVERS_CONFIG -- JSON string of MCP server configs to proxy
  *   GENERATED_DIR      -- path to the generated artifacts directory
  *   PROTECTED_PATHS    -- JSON array of protected paths
- *   ALLOWED_DIRECTORY  -- (optional) sandbox directory for structural containment check
- *   ESCALATION_DIR     -- (optional) directory for file-based escalation IPC
+ *   ALLOWED_DIRECTORY  -- (optional) sandbox directory
  *   SESSION_LOG_PATH   -- (optional) path for capturing child process stderr
  *   SANDBOX_POLICY     -- (optional) "enforce" | "warn" (default: "warn")
- *   AUDIT_REDACTION    -- (optional) "true" to redact PII/credentials in audit log entries
- *   SERVER_FILTER      -- (optional) when set, only connect to this single server name
- *   AUTO_APPROVE_ENABLED   -- (optional) "true" to enable auto-approval of escalations
- *   AUTO_APPROVE_MODEL_ID  -- (optional) qualified model ID for auto-approve LLM
- *   AUTO_APPROVE_API_KEY   -- (optional) API key for the auto-approve model's provider
- *   AUTO_APPROVE_LLM_LOG_PATH -- (optional) path to JSONL file for auto-approve LLM logging
+ *   SERVER_FILTER      -- (optional) only connect to this single server name
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { UdsServerTransport } from './uds-server-transport.js';
 import { TcpServerTransport } from './tcp-server-transport.js';
-import { CallToolRequestSchema, CompatibilityCallToolResultSchema, ListToolsRequestSchema, ListRootsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, CompatibilityCallToolResultSchema, ListToolsRequestSchema, ListRootsRequestSchema, RootsListChangedNotificationSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
-import { appendFileSync, existsSync, mkdtempSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
-import { atomicWriteJsonSync } from '../escalation/escalation-watcher.js';
+import { appendFileSync, mkdtempSync, writeFileSync, writeSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { tmpdir, homedir } from 'node:os';
-import { v4 as uuidv4 } from 'uuid';
-import { loadGeneratedPolicy, extractServerDomainAllowlists, getPackageGeneratedDir } from '../config/index.js';
-import { PolicyEngine, extractAnnotatedPaths } from './policy-engine.js';
-import { getPathRoles, expandTilde } from '../types/argument-roles.js';
-import { AuditLog } from './audit-log.js';
-import { prepareToolArgs, rewriteResultContent } from './path-utils.js';
-import { CONTAINER_WORKSPACE_DIR } from '../docker/agent-adapter.js';
-import { extractPolicyRoots, toMcpRoots, directoryForPath } from './policy-roots.js';
-import { checkSandboxAvailability, resolveSandboxConfig, writeServerSettings, wrapServerCommand, cleanupSettingsFiles, annotateSandboxViolation, discoverNodePaths, rewriteServerSettings, } from './sandbox-integration.js';
-import { ROOTS_REFRESH_TIMEOUT_MS } from './mcp-client-manager.js';
-import { CallCircuitBreaker } from './call-circuit-breaker.js';
-import { autoApprove, extractArgsForAutoApprove, readUserContext } from './auto-approver.js';
-import { createLanguageModelFromEnv } from '../config/model-provider.js';
-import { wrapLanguageModel } from 'ai';
-import { createLlmLoggingMiddleware } from '../pipeline/llm-logger.js';
+import { loadGeneratedPolicy, getPackageGeneratedDir } from '../config/index.js';
+import { expandTilde } from '../types/argument-roles.js';
+import { extractPolicyRoots, toMcpRoots } from './policy-roots.js';
+import { checkSandboxAvailability, resolveSandboxConfig, writeServerSettings, wrapServerCommand, cleanupSettingsFiles, discoverNodePaths, rewriteServerSettings, } from './sandbox-integration.js';
 import { extractMcpErrorMessage } from './mcp-error-utils.js';
-import { updateServerContext, formatServerContext } from './server-context.js';
 import { permissiveJsonSchemaValidator } from './permissive-output-validator.js';
 import { VERSION } from '../version.js';
-import { buildTrustedServerSet } from '../memory/memory-annotations.js';
 import { loadToolDescriptionHints, applyToolDescriptionHints } from './tool-description-hints.js';
-import { createApprovalWhitelist, extractWhitelistCandidates, } from './approval-whitelist.js';
 import { getProviderForServer } from '../auth/oauth-registry.js';
 import { loadClientCredentials } from '../auth/oauth-provider.js';
 import { OAuthTokenProvider } from '../auth/oauth-token-provider.js';
@@ -67,68 +55,10 @@ import { loadOAuthToken } from '../auth/oauth-token-store.js';
 import { writeGWorkspaceCredentialFile } from './gworkspace-credentials.js';
 import { TokenFileRefresher } from './token-file-refresher.js';
 import { proxyAnnotations, proxyPolicyRules, proxyToolDefinitions, handleVirtualProxyTool, createControlApiClient, } from '../docker/proxy-tools.js';
-/**
- * Pending whitelist candidates keyed by escalation ID.
- * Populated when a request file is written with candidates;
- * consumed when the response comes back with a selection.
- * Module-level state — the proxy is a singleton process.
- */
-const pendingWhitelistCandidates = new Map();
-/**
- * Adds a root to a client's root list and waits for the server to
- * fetch the updated list. No-op if the root URI is already present.
- * Times out after ROOTS_REFRESH_TIMEOUT_MS if the server never requests
- * the updated list (e.g. servers that don't implement Roots protocol).
- *
- * Returns `'added'` when the server acknowledged the update (called
- * `roots/list`), `'timeout'` when the server didn't respond in time,
- * or `false` when the root was already present.
- */
-async function addRootToClient(state, root) {
-    if (state.roots.some((r) => r.uri === root.uri))
-        return false;
-    state.roots.push(root);
-    let timer;
-    let outcome = 'timeout';
-    const refreshed = new Promise((resolve) => {
-        state.rootsRefreshed = () => {
-            clearTimeout(timer);
-            outcome = 'added';
-            resolve();
-        };
-    });
-    const timeout = new Promise((resolve) => {
-        timer = setTimeout(() => {
-            state.rootsRefreshed = undefined;
-            resolve();
-        }, ROOTS_REFRESH_TIMEOUT_MS);
-        timer.unref();
-    });
-    await state.client.sendRootsListChanged();
-    await Promise.race([refreshed, timeout]);
-    return outcome;
-}
-/**
- * Delay before retrying a tool call that returned "access denied" immediately
- * after roots expansion. The filesystem server needs time to async-validate
- * (fs.realpath, fs.stat) the new roots after receiving the rootsListChanged
- * notification. Exported for test access.
- */
-export const ROOTS_RACE_RETRY_DELAY_MS = 200;
-/**
- * Checks whether an MCP tool call result looks like a roots-race "access denied"
- * error -- the filesystem server rejected the call because it hasn't finished
- * processing the updated roots yet.
- */
-function isRootsRaceError(result) {
-    if (!('isError' in result) || !result.isError)
-        return false;
-    const text = extractTextFromContent(result.content);
-    if (!text)
-        return false;
-    const lower = text.toLowerCase();
-    return lower.includes('access denied') || lower.includes('outside allowed directories');
-}
+import { buildToolMap, assertUniqueToolNames } from './tool-call-pipeline.js';
+// ---------------------------------------------------------------------------
+// Subprocess helpers
+// ---------------------------------------------------------------------------
 /** Appends a timestamped line to the session log file. */
 function logToSessionFile(sessionLogPath, message) {
     const timestamp = new Date().toISOString();
@@ -157,15 +87,6 @@ function getMissingEnvVars(args) {
     }
     return missing;
 }
-/** Extracts concatenated text from MCP content blocks. */
-export function extractTextFromContent(content) {
-    if (!Array.isArray(content))
-        return undefined;
-    const texts = content
-        .filter((c) => c.type === 'text' && typeof c.text === 'string')
-        .map((c) => c.text);
-    return texts.length > 0 ? texts.join('\n') : undefined;
-}
 /**
  * Replaces known credential values in a string with `***REDACTED***`.
  * Prevents credential leakage in session log files.
@@ -179,163 +100,40 @@ function redactCredentials(text, credentials) {
     }
     return result;
 }
-const ESCALATION_POLL_INTERVAL_MS = 500;
-const DEFAULT_ESCALATION_TIMEOUT_SECONDS = 300;
-/** Auto-approve trusted input older than this is rejected as stale. */
-const TRUSTED_INPUT_STALENESS_MS = 120_000;
 /**
- * Returns true when a user context is safe to act on for auto-approval.
- *
- * For PTY sessions (isPtySession=true):
- *   - source must be 'mux-trusted-input' (set by the trusted mux layer)
- *   - timestamp must be present, valid, not in the future, and within
- *     TRUSTED_INPUT_STALENESS_MS of `now`
- *
- * For non-PTY sessions:
- *   - source is not checked (no mux layer in the path)
- *   - a missing or invalid timestamp does not prevent trust; a valid stale
- *     timestamp still prevents trust (belt-and-suspenders for future callers)
- *
- * @param context - The user context parsed from user-context.json
- * @param isPtySession - Whether this is a PTY interactive session
- * @param now - Current time in ms; defaults to Date.now() (injectable for tests)
+ * True when this proxy subprocess is in a viable serving state -- either
+ * virtual-only mode (no backends configured) or at least one configured
+ * backend connected. Returning false means the parent should treat this
+ * subprocess as failed; otherwise it would register zero tools for the
+ * server and trigger a misleading "stale annotations" warning in the
+ * coordinator's drift check.
  */
-export function isUserContextTrusted(context, isPtySession, now = Date.now()) {
-    const sourceValid = !isPtySession || context.source === 'mux-trusted-input';
-    if (!sourceValid)
-        return false;
-    let stale = isPtySession; // non-PTY sessions don't require timestamps
-    if (context.timestamp !== undefined) {
-        const tsMs = new Date(context.timestamp).getTime();
-        if (!Number.isNaN(tsMs)) {
-            const ageMs = now - tsMs;
-            stale = ageMs > TRUSTED_INPUT_STALENESS_MS || ageMs < 0;
-        }
-    }
-    return !stale;
-}
-/** Reads escalation timeout from env var, falling back to default. */
-function getEscalationTimeoutMs() {
-    const envValue = process.env.ESCALATION_TIMEOUT_SECONDS;
-    if (envValue) {
-        const parsed = Number(envValue);
-        if (Number.isFinite(parsed) && parsed > 0) {
-            return parsed * 1000;
-        }
-    }
-    return DEFAULT_ESCALATION_TIMEOUT_SECONDS * 1000;
-}
-/** Silently removes a file. Ignores errors (e.g. file already gone). */
-function tryUnlink(path) {
-    try {
-        unlinkSync(path);
-    }
-    catch {
-        /* ignore */
-    }
-}
-/**
- * Removes both escalation IPC files. Request is deleted first so the
- * session side sees "request gone + response exists" as normal
- * approval-in-progress rather than an expiry.
- */
-function cleanupEscalationFiles(requestPath, responsePath) {
-    tryUnlink(requestPath);
-    tryUnlink(responsePath);
+export function proxyCanServe(serversConfig, connectedBackendCount) {
+    return Object.keys(serversConfig).length === 0 || connectedBackendCount > 0;
 }
 /**
- * Reads and parses the escalation response file if it exists.
- * Returns the response data, or undefined if the file is not present.
- */
-function readEscalationResponse(responsePath) {
-    if (!existsSync(responsePath))
-        return undefined;
-    const raw = JSON.parse(readFileSync(responsePath, 'utf-8'));
-    // Validate whitelistSelection: must be an integer if present, discard otherwise
-    let whitelistSelection;
-    if (typeof raw.whitelistSelection === 'number' && Number.isInteger(raw.whitelistSelection)) {
-        whitelistSelection = raw.whitelistSelection;
-    }
-    return {
-        decision: raw.decision,
-        ...(whitelistSelection !== undefined ? { whitelistSelection } : {}),
-    };
-}
-/**
- * Waits for a human decision via file-based IPC.
- *
- * Writes a request file to the escalation directory, then polls
- * for a response file. The session process (on the other side)
- * detects the request, surfaces it to the user, and writes the response.
+ * Writes a diagnostic line to stderr and (if configured) the proxy session log.
  *
- * Returns 'approved' or 'denied'. On timeout, returns 'denied'.
+ * Uses `fs.writeSync` so the bytes reach the OS before the function returns
+ * even when stderr is a pipe (parent-spawned subprocess). `process.stderr.write`
+ * is asynchronous in that case, which would let a follow-up `process.exit(1)`
+ * truncate the diagnostic before delivery.
  */
-async function waitForEscalationDecision(escalationDir, request) {
-    const requestPath = resolve(escalationDir, `request-${request.escalationId}.json`);
-    const responsePath = resolve(escalationDir, `response-${request.escalationId}.json`);
-    atomicWriteJsonSync(requestPath, request);
-    const deadline = Date.now() + getEscalationTimeoutMs();
-    while (Date.now() < deadline) {
-        const response = readEscalationResponse(responsePath);
-        if (response) {
-            cleanupEscalationFiles(requestPath, responsePath);
-            return response;
-        }
-        await new Promise((r) => setTimeout(r, ESCALATION_POLL_INTERVAL_MS));
-    }
-    // Final check -- response may have arrived between last poll and deadline
-    const lateResponse = readEscalationResponse(responsePath);
-    cleanupEscalationFiles(requestPath, responsePath);
-    return lateResponse ?? { decision: 'denied' };
+function emitProxyDiagnostic(level, message, sessionLogPath) {
+    writeSync(2, `${level}: ${message}\n`);
+    if (sessionLogPath)
+        logToSessionFile(sessionLogPath, `[proxy] ${message}`);
 }
-/**
- * Creates the auto-approve LLM model from environment variables.
- * Returns null when auto-approve is not enabled or env vars are missing.
- * Wraps with LLM logging middleware when a log path is provided.
- */
-async function createAutoApproveModel(sessionLogPath) {
-    if (process.env.AUTO_APPROVE_ENABLED !== 'true')
-        return null;
-    const modelId = process.env.AUTO_APPROVE_MODEL_ID;
-    if (!modelId)
-        return null;
-    const apiKey = process.env.AUTO_APPROVE_API_KEY ?? '';
-    try {
-        const baseModel = await createLanguageModelFromEnv(modelId, apiKey);
-        const llmLogPath = process.env.AUTO_APPROVE_LLM_LOG_PATH;
-        if (sessionLogPath) {
-            logToSessionFile(sessionLogPath, `Auto-approve model created: ${modelId}`);
-        }
-        if (!llmLogPath)
-            return baseModel;
-        return wrapLanguageModel({
-            model: baseModel,
-            middleware: createLlmLoggingMiddleware(llmLogPath, { stepName: 'auto-approve' }),
-        });
-    }
-    catch (err) {
-        // Model creation failure should not prevent the proxy from starting.
-        // Auto-approve simply won't be available for this session.
-        const message = err instanceof Error ? err.message : String(err);
-        if (sessionLogPath) {
-            logToSessionFile(sessionLogPath, `Auto-approve model creation failed for ${modelId}: ${message}`);
-        }
-        return null;
-    }
-}
-// ── Extracted functions ────────────────────────────────────────────────
 /**
  * Reads and validates proxy environment variables.
  * Returns a typed config object or calls process.exit(1) on missing required vars.
  */
 export function parseProxyEnvConfig() {
-    const auditLogPath = process.env.AUDIT_LOG_PATH ?? './audit.jsonl';
     const serversConfigJson = process.env.MCP_SERVERS_CONFIG;
     const generatedDir = process.env.GENERATED_DIR;
     const protectedPathsJson = process.env.PROTECTED_PATHS ?? '[]';
     const sessionLogPath = process.env.SESSION_LOG_PATH;
     const allowedDirectory = process.env.ALLOWED_DIRECTORY;
-    const escalationDir = process.env.ESCALATION_DIR;
     if (!serversConfigJson) {
         process.stderr.write('MCP_SERVERS_CONFIG environment variable is required\n');
         process.exit(1);
@@ -351,7 +149,6 @@ export function parseProxyEnvConfig() {
         : {};
     delete process.env.SERVER_CREDENTIALS;
     const sandboxPolicy = (process.env.SANDBOX_POLICY ?? 'warn');
-    const auditRedaction = process.env.AUDIT_REDACTION === 'true';
     const allServersConfig = JSON.parse(serversConfigJson);
     const protectedPaths = JSON.parse(protectedPathsJson);
     // When SERVER_FILTER is set, only connect to that single backend server.
@@ -373,17 +170,15 @@ export function parseProxyEnvConfig() {
     // Otherwise they default to the same directory as compiled policy.
     const toolAnnotationsDir = process.env.TOOL_ANNOTATIONS_DIR ?? generatedDir;
     return {
-        auditLogPath,
         serversConfig,
         generatedDir,
         toolAnnotationsDir,
         protectedPaths,
         sessionLogPath,
         allowedDirectory,
-        escalationDir,
         serverCredentials,
         sandboxPolicy,
-        auditRedaction,
+        serverFilter,
     };
 }
 /**
@@ -433,365 +228,6 @@ export function resolveServerSandboxConfigs(serversConfig, allowedDirectory, san
     }
     return { resolvedSandboxConfigs, settingsDir, serverCwdPaths };
 }
-/**
- * Validates that all argument keys exist in the tool's inputSchema.
- * Returns null if valid, or an error message listing unknown and valid keys.
- * Skips validation when the schema has no properties or allows additional properties.
- */
-export function validateToolArguments(args, inputSchema) {
-    const properties = inputSchema.properties;
-    if (!properties || typeof properties !== 'object')
-        return null;
-    if (inputSchema.additionalProperties)
-        return null;
-    const validKeys = new Set(Object.keys(properties));
-    const unknownKeys = Object.keys(args).filter((k) => !validKeys.has(k));
-    if (unknownKeys.length === 0)
-        return null;
-    const unknownList = unknownKeys.map((k) => `"${k}"`).join(', ');
-    const validList = [...validKeys]
-        .sort()
-        .map((k) => `"${k}"`)
-        .join(', ');
-    return `Unknown argument(s): ${unknownList}. Valid parameters are: ${validList}`;
-}
-/** Builds a lookup map from tool name to ProxiedTool for routing. */
-export function buildToolMap(allTools) {
-    const toolMap = new Map();
-    for (const tool of allTools) {
-        toolMap.set(tool.name, tool);
-    }
-    return toolMap;
-}
-/**
- * Creates an audit entry and logs it. Extracted so the audit shape
- * construction is testable independently.
- */
-export function buildAuditEntry(request, argsForTransport, policyDecision, result, durationMs, options) {
-    return {
-        timestamp: request.timestamp,
-        requestId: request.requestId,
-        serverName: request.serverName,
-        toolName: request.toolName,
-        arguments: argsForTransport,
-        policyDecision,
-        escalationResult: options.escalationResult,
-        result,
-        durationMs,
-        sandboxed: options.sandboxed || undefined,
-        autoApproved: options.autoApproved || undefined,
-        whitelistApproved: options.whitelistApproved || undefined,
-        whitelistPatternId: options.whitelistPatternId,
-    };
-}
-/**
- * Handles a single tool call request: policy evaluation, escalation,
- * circuit breaker check, and forwarding to the real MCP server.
- *
- * This is the core security logic extracted from the CallTool handler
- * for independent unit testing.
- */
-export async function handleCallTool(toolName, rawArgs, deps) {
-    const toolInfo = deps.toolMap.get(toolName);
-    if (!toolInfo) {
-        return {
-            content: [{ type: 'text', text: `Unknown tool: ${toolName}` }],
-            isError: true,
-        };
-    }
-    // Annotation-driven normalization: split into transport vs policy args.
-    // Trusted servers skip annotation lookup and prepareToolArgs — use raw args directly.
-    const annotation = deps.policyEngine.getAnnotation(toolInfo.serverName, toolInfo.name, rawArgs);
-    const isTrusted = !annotation && deps.policyEngine.isTrustedServer(toolInfo.serverName);
-    if (!annotation && !isTrusted) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Missing annotation for tool: ${toolInfo.serverName}__${toolInfo.name}. Re-run 'ironcurtain annotate-tools' to update.`,
-                },
-            ],
-            isError: true,
-        };
-    }
-    // Validate argument names against the tool's schema.
-    // Skip for trusted servers (check directly, not via isTrusted which also requires missing annotation).
-    if (!deps.policyEngine.isTrustedServer(toolInfo.serverName)) {
-        const validationError = validateToolArguments(rawArgs, toolInfo.inputSchema);
-        if (validationError) {
-            deps.auditLog.log({
-                timestamp: new Date().toISOString(),
-                requestId: uuidv4(),
-                serverName: toolInfo.serverName,
-                toolName: toolInfo.name,
-                arguments: rawArgs,
-                policyDecision: { status: 'deny', rule: 'invalid-arguments', reason: validationError },
-                result: { status: 'denied', error: validationError },
-                durationMs: 0,
-            });
-            return {
-                content: [{ type: 'text', text: validationError }],
-                isError: true,
-            };
-        }
-    }
-    let argsForTransport;
-    let argsForPolicy;
-    if (isTrusted) {
-        // Trusted server with no annotation: use raw args for both transport and policy
-        argsForTransport = rawArgs;
-        argsForPolicy = rawArgs;
-    }
-    else {
-        // annotation is guaranteed non-null here: we returned early if both are falsy
-        const resolvedAnnotation = annotation;
-        // Enrich git tool args with the locally tracked working directory when
-        // the agent omits the `path` argument. The git MCP server tracks its own
-        // CWD (set via git_set_working_dir) and uses it implicitly, but the
-        // policy engine needs the explicit path to resolve sandbox containment
-        // and the default remote URL for domain-based policy rules.
-        // The serverContextMap mirrors the git server's working directory from
-        // successful git_set_working_dir / git_clone calls, avoiding an RPC.
-        let effectiveRawArgs = rawArgs;
-        const hasEffectivePath = 'path' in rawArgs && typeof rawArgs.path === 'string' && rawArgs.path.trim() !== '';
-        if (toolInfo.serverName === 'git' && 'path' in resolvedAnnotation.args && !hasEffectivePath) {
-            const gitWorkDir = deps.serverContextMap.get('git')?.workingDirectory;
-            if (!gitWorkDir) {
-                const errorMsg = 'Git server has no working directory set. Call git_set_working_dir first.';
-                deps.auditLog.log(buildAuditEntry({
-                    requestId: uuidv4(),
-                    serverName: toolInfo.serverName,
-                    toolName: toolInfo.name,
-                    arguments: rawArgs,
-                    timestamp: new Date().toISOString(),
-                }, rawArgs, { status: 'deny', rule: 'git-path-enrichment-failed', reason: errorMsg }, { status: 'denied', error: errorMsg }, 0, {}));
-                return {
-                    content: [{ type: 'text', text: `Error: ${errorMsg}` }],
-                    isError: true,
-                };
-            }
-            effectiveRawArgs = { ...rawArgs, path: gitWorkDir };
-        }
-        ({ argsForTransport, argsForPolicy } = prepareToolArgs(effectiveRawArgs, resolvedAnnotation, deps.allowedDirectory, CONTAINER_WORKSPACE_DIR));
-    }
-    const request = {
-        requestId: uuidv4(),
-        serverName: toolInfo.serverName,
-        toolName: toolInfo.name,
-        arguments: argsForPolicy,
-        timestamp: new Date().toISOString(),
-    };
-    const evaluation = deps.policyEngine.evaluate(request);
-    const policyDecision = {
-        status: evaluation.decision,
-        rule: evaluation.rule,
-        reason: evaluation.reason,
-    };
-    let escalationResult;
-    let autoApproved = false;
-    let whitelistApproved = false;
-    let whitelistPatternId;
-    let rootsExpanded = false;
-    const serverSandboxConfig = deps.resolvedSandboxConfigs.get(toolInfo.serverName);
-    const serverIsSandboxed = serverSandboxConfig?.sandboxed === true;
-    function logAudit(result, durationMs, overrideEscalation) {
-        const entry = buildAuditEntry(request, argsForTransport, policyDecision, result, durationMs, {
-            escalationResult: overrideEscalation ?? escalationResult,
-            sandboxed: serverIsSandboxed,
-            autoApproved,
-            whitelistApproved: whitelistApproved || undefined,
-            whitelistPatternId,
-        });
-        deps.auditLog.log(entry);
-    }
-    if (evaluation.decision === 'escalate') {
-        // Annotation is guaranteed non-null here: trusted servers always allow (never escalate),
-        // and missing-annotation returns early above. Narrow the type for TypeScript.
-        const resolvedAnnotation = annotation;
-        const whitelistMatch = deps.whitelist.match(toolInfo.serverName, toolInfo.name, argsForPolicy, resolvedAnnotation);
-        if (whitelistMatch.matched) {
-            whitelistApproved = true;
-            whitelistPatternId = whitelistMatch.patternId;
-            escalationResult = 'approved';
-            policyDecision.status = 'allow';
-            policyDecision.reason = `Whitelist-approved: ${whitelistMatch.pattern.description}`;
-        }
-        if (!whitelistApproved) {
-            if (!deps.escalationDir) {
-                logAudit({ status: 'denied', error: evaluation.reason }, 0, 'denied');
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `ESCALATION REQUIRED: ${evaluation.reason}. Action denied (no escalation handler).`,
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-            const escalationId = uuidv4();
-            // Try auto-approve before falling through to human escalation
-            if (deps.autoApproveModel) {
-                const userContext = readUserContext(deps.escalationDir);
-                if (userContext) {
-                    const isPtySession = process.env.IRONCURTAIN_PTY_SESSION === '1';
-                    if (isUserContextTrusted(userContext, isPtySession)) {
-                        const autoResult = await autoApprove({
-                            userMessage: userContext.userMessage,
-                            toolName: `${toolInfo.serverName}/${toolInfo.name}`,
-                            escalationReason: evaluation.reason,
-                            arguments: extractArgsForAutoApprove(argsForPolicy, annotation),
-                        }, deps.autoApproveModel);
-                        if (autoResult.decision === 'approve') {
-                            autoApproved = true;
-                            escalationResult = 'approved';
-                            policyDecision.status = 'allow';
-                            policyDecision.reason = `Auto-approved: ${autoResult.reasoning}`;
-                        }
-                    }
-                }
-            }
-            if (!autoApproved) {
-                // Extract whitelist candidates just before human escalation (avoids
-                // wasted work when auto-approve succeeds).
-                const { patterns: candidatePatterns, ipcs: candidateIpcs } = extractWhitelistCandidates(toolInfo.serverName, toolInfo.name, argsForPolicy, resolvedAnnotation, evaluation.escalatedRoles, escalationId, evaluation.reason);
-                if (candidatePatterns.length > 0) {
-                    // Store full patterns in proxy memory, keyed by escalation ID
-                    pendingWhitelistCandidates.set(escalationId, candidatePatterns);
-                }
-                try {
-                    const response = await waitForEscalationDecision(deps.escalationDir, {
-                        escalationId,
-                        serverName: request.serverName,
-                        toolName: request.toolName,
-                        arguments: argsForTransport,
-                        reason: evaluation.reason,
-                        context: formatServerContext(deps.serverContextMap, toolInfo.serverName),
-                        whitelistCandidates: candidateIpcs.length > 0 ? candidateIpcs : undefined,
-                    });
-                    if (response.decision === 'denied') {
-                        logAudit({ status: 'denied', error: evaluation.reason }, 0, 'denied');
-                        return {
-                            content: [{ type: 'text', text: `ESCALATION DENIED: ${evaluation.reason}` }],
-                            isError: true,
-                        };
-                    }
-                    escalationResult = 'approved';
-                    policyDecision.status = 'allow';
-                    policyDecision.reason = 'Approved by human during escalation';
-                    // Handle whitelist selection from the response
-                    if (response.whitelistSelection !== undefined) {
-                        const storedPatterns = pendingWhitelistCandidates.get(escalationId);
-                        if (storedPatterns &&
-                            response.whitelistSelection >= 0 &&
-                            response.whitelistSelection < storedPatterns.length) {
-                            const selectedPattern = storedPatterns[response.whitelistSelection];
-                            deps.whitelist.add(selectedPattern);
-                        }
-                    }
-                }
-                finally {
-                    // Issue 12: ensure cleanup even if waitForEscalationDecision throws
-                    pendingWhitelistCandidates.delete(escalationId);
-                }
-            }
-        }
-        // Expand roots for approved path arguments only (skip URLs, opaques)
-        const state = deps.clientStates.get(toolInfo.serverName);
-        if (state && annotation) {
-            const pathValues = extractAnnotatedPaths(argsForTransport, annotation, getPathRoles());
-            for (const p of pathValues) {
-                const result = await addRootToClient(state, {
-                    uri: `file://${directoryForPath(p)}`,
-                    name: 'escalation-approved',
-                });
-                if (result === 'added')
-                    rootsExpanded = true;
-            }
-        }
-    }
-    if (evaluation.decision === 'deny') {
-        logAudit({ status: 'denied', error: evaluation.reason }, 0);
-        return {
-            content: [{ type: 'text', text: `DENIED: ${evaluation.reason}` }],
-            isError: true,
-        };
-    }
-    // Circuit breaker: deny if the same tool+args is called too many times
-    const cbVerdict = deps.circuitBreaker.check(toolInfo.name, argsForTransport);
-    if (!cbVerdict.allowed) {
-        logAudit({ status: 'denied', error: cbVerdict.reason }, 0);
-        return {
-            content: [{ type: 'text', text: cbVerdict.reason }],
-            isError: true,
-        };
-    }
-    // Virtual proxy tools: handle locally, no backend forwarding
-    if (toolInfo.serverName === 'proxy' && deps.controlApiClient) {
-        const startTime = Date.now();
-        try {
-            const result = await handleVirtualProxyTool(toolInfo.name, argsForTransport, deps.controlApiClient);
-            logAudit({ status: 'success' }, Date.now() - startTime);
-            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-        }
-        catch (err) {
-            const errorMessage = err instanceof Error ? err.message : String(err);
-            logAudit({ status: 'error', error: errorMessage }, Date.now() - startTime);
-            return { content: [{ type: 'text', text: `Error: ${errorMessage}` }], isError: true };
-        }
-    }
-    // Policy allows -- forward to the real MCP server with transport args
-    const startTime = Date.now();
-    try {
-        const clientState = deps.clientStates.get(toolInfo.serverName);
-        if (!clientState) {
-            const err = `Internal error: no client connection for server "${toolInfo.serverName}"`;
-            logAudit({ status: 'denied', error: err }, 0);
-            return { content: [{ type: 'text', text: err }], isError: true };
-        }
-        const client = clientState.client;
-        // CompatibilityCallToolResultSchema accepts the legacy `toolResult` response format
-        // (protocol version 2024-10-07). Output schema validation is intentionally
-        // bypassed by the permissiveJsonSchemaValidator injected at Client construction time.
-        const callToolArgs = { name: toolInfo.name, arguments: argsForTransport };
-        const callToolOpts = { timeout: getEscalationTimeoutMs() };
-        let result = await client.callTool(callToolArgs, CompatibilityCallToolResultSchema, callToolOpts);
-        // Race condition mitigation: after roots expansion the filesystem server
-        // has been notified but may not have finished async-validating the new
-        // roots (fs.realpath, fs.stat). Retry once after a short delay.
-        if (rootsExpanded && isRootsRaceError(result)) {
-            const initialError = extractTextFromContent(result.content) ?? 'access denied (roots race)';
-            logAudit({ status: 'error', error: `Roots race detected, retrying: ${initialError}` }, Date.now() - startTime);
-            await new Promise((r) => setTimeout(r, ROOTS_RACE_RETRY_DELAY_MS));
-            result = await client.callTool(callToolArgs, CompatibilityCallToolResultSchema, callToolOpts);
-        }
-        // Reverse-rewrite host sandbox paths to container workspace paths in results
-        const rewrittenContent = deps.allowedDirectory
-            ? rewriteResultContent(result.content, deps.allowedDirectory, CONTAINER_WORKSPACE_DIR)
-            : result.content;
-        if (result.isError) {
-            const errorText = extractTextFromContent(rewrittenContent) ?? 'Unknown tool error';
-            const errorMessage = annotateSandboxViolation(errorText, serverIsSandboxed);
-            logAudit({ status: 'error', error: errorMessage }, Date.now() - startTime);
-            return { content: rewrittenContent, isError: true };
-        }
-        updateServerContext(deps.serverContextMap, toolInfo.serverName, toolInfo.name, argsForTransport);
-        logAudit({ status: 'success' }, Date.now() - startTime);
-        return { content: rewrittenContent };
-    }
-    catch (err) {
-        const rawError = extractMcpErrorMessage(err);
-        const errorMessage = annotateSandboxViolation(rawError, serverIsSandboxed);
-        logAudit({ status: 'error', error: errorMessage }, Date.now() - startTime);
-        const errorContent = [{ type: 'text', text: `Error: ${errorMessage}` }];
-        return {
-            content: deps.allowedDirectory
-                ? rewriteResultContent(errorContent, deps.allowedDirectory, CONTAINER_WORKSPACE_DIR)
-                : errorContent,
-            isError: true,
-        };
-    }
-}
 /**
  * Selects and validates the proxy transport based on environment variables.
  * Returns 'tcp', 'uds', or 'stdio' along with the transport options.
@@ -814,27 +250,30 @@ export function selectTransportConfig() {
 // ── main() -- thin orchestrator ────────────────────────────────────────
 async function main() {
     const envConfig = parseProxyEnvConfig();
-    const { auditLogPath, serversConfig, generatedDir, toolAnnotationsDir, protectedPaths, sessionLogPath, allowedDirectory, escalationDir, serverCredentials, sandboxPolicy, auditRedaction, } = envConfig;
-    const { compiledPolicy, toolAnnotations, dynamicLists } = loadGeneratedPolicy({
+    const { serversConfig, generatedDir, toolAnnotationsDir, sessionLogPath, allowedDirectory, serverCredentials, sandboxPolicy, serverFilter, } = envConfig;
+    // Load compiled policy + annotations to derive MCP roots advertised
+    // to backend MCP servers at connection time (the backend still uses
+    // Roots to authorize filesystem access).
+    const { compiledPolicy, toolAnnotations } = loadGeneratedPolicy({
         policyDir: generatedDir,
         toolAnnotationsDir,
         fallbackDir: getPackageGeneratedDir(),
     });
-    // Merge proxy tool annotations and policy rules into the loaded artifacts
-    // so the PolicyEngine can evaluate proxy tool calls.
+    // Merge proxy tool annotations and policy rules so roots derivation
+    // includes any paths referenced by proxy policy rules.
     toolAnnotations.servers.proxy = {
         inputHash: 'hardcoded',
         tools: proxyAnnotations,
     };
     compiledPolicy.rules = [...proxyPolicyRules, ...compiledPolicy.rules];
-    const serverDomainAllowlists = extractServerDomainAllowlists(serversConfig);
-    const trustedServers = buildTrustedServerSet(serversConfig);
-    const policyEngine = new PolicyEngine(compiledPolicy, toolAnnotations, protectedPaths, allowedDirectory, serverDomainAllowlists, dynamicLists, trustedServers);
-    const auditLog = new AuditLog(auditLogPath, { redact: auditRedaction });
-    const circuitBreaker = new CallCircuitBreaker();
-    const autoApproveModel = await createAutoApproveModel(sessionLogPath);
     const policyRoots = extractPolicyRoots(compiledPolicy, allowedDirectory ?? '/tmp');
     const mcpRoots = toMcpRoots(policyRoots);
+    // Shared mutable roots array bridged to the coordinator. The proxy
+    // server's `notifications/roots/list_changed` handler (registered
+    // below) refreshes this in place via `server.listRoots()`, and each
+    // backend client's `roots/list` handler returns it. All backends
+    // observe the same authoritative set.
+    const relayRoots = [...mcpRoots];
     // ── Sandbox availability & config resolution ──────────────────────
     const { sandboxAvailable } = validateSandboxAvailability(sandboxPolicy, sessionLogPath, process.platform);
     const { resolvedSandboxConfigs, settingsDir, serverCwdPaths } = resolveServerSandboxConfigs(serversConfig, allowedDirectory, sandboxAvailable, sandboxPolicy);
@@ -849,10 +288,7 @@ async function main() {
         // that aren't set — the server will fail to start without them.
         const missingEnvVars = getMissingEnvVars(config.args);
         if (missingEnvVars.length > 0) {
-            const warning = `Skipping MCP server "${serverName}": missing environment variable(s) ${missingEnvVars.join(', ')}`;
-            process.stderr.write(`WARNING: ${warning}\n`);
-            if (sessionLogPath)
-                logToSessionFile(sessionLogPath, `[proxy] ${warning}`);
+            emitProxyDiagnostic('WARNING', `Skipping MCP server "${serverName}": missing environment variable(s) ${missingEnvVars.join(', ')}`, sessionLogPath);
             continue;
         }
         // ── OAuth token injection for servers backed by OAuth providers ──
@@ -861,18 +297,12 @@ async function main() {
         if (oauthProvider) {
             const clientCreds = loadClientCredentials(oauthProvider);
             if (!clientCreds) {
-                const warning = `Skipping MCP server "${serverName}": no OAuth credentials. Run 'ironcurtain auth import ${oauthProvider.id} <file>'`;
-                process.stderr.write(`WARNING: ${warning}\n`);
-                if (sessionLogPath)
-                    logToSessionFile(sessionLogPath, `[proxy] ${warning}`);
+                emitProxyDiagnostic('WARNING', `Skipping MCP server "${serverName}": no OAuth credentials. Run 'ironcurtain auth import ${oauthProvider.id} <file>'`, sessionLogPath);
                 continue;
             }
             const tokenProvider = new OAuthTokenProvider(oauthProvider, clientCreds);
             if (!tokenProvider.isAuthorized()) {
-                const warning = `Skipping MCP server "${serverName}": not authorized. Run 'ironcurtain auth ${oauthProvider.id}'`;
-                process.stderr.write(`WARNING: ${warning}\n`);
-                if (sessionLogPath)
-                    logToSessionFile(sessionLogPath, `[proxy] ${warning}`);
+                emitProxyDiagnostic('WARNING', `Skipping MCP server "${serverName}": not authorized. Run 'ironcurtain auth ${oauthProvider.id}'`, sessionLogPath);
                 continue;
             }
             try {
@@ -928,10 +358,7 @@ async function main() {
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
-                const warning = `Skipping MCP server "${serverName}": OAuth token error: ${message}. Run 'ironcurtain auth ${oauthProvider.id}'`;
-                process.stderr.write(`WARNING: ${warning}\n`);
-                if (sessionLogPath)
-                    logToSessionFile(sessionLogPath, `[proxy] ${warning}`);
+                emitProxyDiagnostic('WARNING', `Skipping MCP server "${serverName}": OAuth token error: ${message}. Run 'ironcurtain auth ${oauthProvider.id}'`, sessionLogPath);
                 continue;
             }
         }
@@ -983,7 +410,11 @@ async function main() {
             capabilities: { roots: { listChanged: true } },
             jsonSchemaValidator: permissiveJsonSchemaValidator,
         });
-        const state = { client, roots: [...mcpRoots] };
+        // All backend clients share the single `relayRoots` array so a
+        // coordinator-driven roots update (see the proxy server's
+        // `roots/list_changed` handler below) is visible to every backend
+        // on its next `roots/list` request.
+        const state = { client, roots: relayRoots };
         client.setRequestHandler(ListRootsRequestSchema, () => {
             if (state.rootsRefreshed) {
                 state.rootsRefreshed();
@@ -1010,9 +441,21 @@ async function main() {
             });
         }
     }
+    // Exit non-zero so the parent's `MCPClientManager.connect()` fails the
+    // handshake -- the existing try/catch in `connectBackendSubprocesses`
+    // skips the server without reaching `registerTools`.
+    if (!proxyCanServe(serversConfig, clientStates.size)) {
+        const serverNames = Object.keys(serversConfig).join(', ');
+        emitProxyDiagnostic('ERROR', `proxy subprocess for SERVER_FILTER="${serverFilter ?? '<unset>'}" has no connected backend (configured: ${serverNames}); exiting`, sessionLogPath);
+        for (const refresher of tokenRefreshers.values()) {
+            refresher.stop();
+        }
+        cleanupSettingsFiles(settingsDir);
+        process.exit(1);
+    }
     // In virtual-only mode (SERVER_FILTER=proxy), register proxy tool definitions
     // and create the control API client for communicating with the MITM proxy.
-    const isVirtualOnlyMode = process.env.SERVER_FILTER === 'proxy' && Object.keys(serversConfig).length === 0;
+    const isVirtualOnlyMode = serverFilter === 'proxy' && Object.keys(serversConfig).length === 0;
     let controlApiClient = null;
     if (isVirtualOnlyMode) {
         for (const toolDef of proxyToolDefinitions) {
@@ -1030,6 +473,11 @@ async function main() {
         }
         controlApiClient = createControlApiClient(mitmControlAddr);
     }
+    // Defense-in-depth: the relay's CallTool handler routes by bare
+    // tool name, so two backends exposing the same tool name would
+    // silently collide and route to the wrong server. Fail fast if we
+    // ever end up with such a collision in the loaded tool set.
+    assertUniqueToolNames(allTools);
     const toolMap = buildToolMap(allTools);
     const toolDescriptionHints = loadToolDescriptionHints();
     const hintedTools = applyToolDescriptionHints(allTools, toolDescriptionHints);
@@ -1044,23 +492,85 @@ async function main() {
     // eslint-disable-next-line @typescript-eslint/no-deprecated -- intentional use of low-level Server for raw JSON schema passthrough
     const server = new Server({ name: 'ironcurtain-proxy', version: VERSION }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, () => listToolsResponse);
-    const serverContextMap = new Map();
-    const callToolDeps = {
-        toolMap,
-        policyEngine,
-        auditLog,
-        circuitBreaker,
-        clientStates,
-        resolvedSandboxConfigs,
-        allowedDirectory,
-        escalationDir,
-        autoApproveModel,
-        serverContextMap,
-        whitelist: createApprovalWhitelist(),
-        controlApiClient,
-    };
+    // ── Roots bridging (coordinator → relay → backends) ───────────────
+    // The coordinator in the parent process is the authoritative source
+    // of MCP roots. On escalation approval it expands its roots and
+    // sends `notifications/roots/list_changed` to this relay. We fetch
+    // the fresh list from the coordinator via `server.listRoots()`,
+    // replace `relayRoots` in place, and propagate the notification to
+    // every backend client so they re-query via their `roots/list`
+    // handlers (registered above).
+    server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
+        try {
+            const { roots: updatedRoots } = await server.listRoots();
+            // Replace contents in-place so all backend clientStates -- which
+            // share the same array reference as `relayRoots` -- see the new
+            // set on their next `roots/list` call. MCP `Root.name` is
+            // optional in the spec; fall back to the URI so our internal
+            // `name: string` contract holds.
+            relayRoots.length = 0;
+            for (const r of updatedRoots) {
+                relayRoots.push({ uri: r.uri, name: r.name ?? r.uri });
+            }
+        }
+        catch (err) {
+            if (sessionLogPath) {
+                const msg = err instanceof Error ? err.message : String(err);
+                logToSessionFile(sessionLogPath, `[proxy] Failed to fetch roots from coordinator: ${msg}`);
+            }
+            return;
+        }
+        await Promise.all([...clientStates.values()].map(async (state) => {
+            try {
+                await state.client.sendRootsListChanged();
+            }
+            catch (err) {
+                if (sessionLogPath) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    logToSessionFile(sessionLogPath, `[proxy] sendRootsListChanged to backend failed: ${msg}`);
+                }
+            }
+        }));
+    });
+    // Pass-through CallTool handler: forward to the backend client,
+    // return the raw result. No policy evaluation -- the coordinator
+    // in the parent process handles that.
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
-        return handleCallTool(req.params.name, req.params.arguments ?? {}, callToolDeps);
+        const toolInfo = toolMap.get(req.params.name);
+        if (!toolInfo) {
+            return {
+                content: [{ type: 'text', text: `Unknown tool: ${req.params.name}` }],
+                isError: true,
+            };
+        }
+        // Virtual proxy tools stay local -- they speak to the MITM control
+        // socket via the ControlApiClient and never reach a backend MCP server.
+        const rawArgs = req.params.arguments ?? {};
+        if (toolInfo.serverName === 'proxy' && controlApiClient) {
+            try {
+                const result = await handleVirtualProxyTool(toolInfo.name, rawArgs, controlApiClient);
+                return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+            }
+            catch (err) {
+                const errorMessage = err instanceof Error ? err.message : String(err);
+                return { content: [{ type: 'text', text: `Error: ${errorMessage}` }], isError: true };
+            }
+        }
+        const clientState = clientStates.get(toolInfo.serverName);
+        if (!clientState) {
+            return {
+                content: [{ type: 'text', text: `Internal error: no client connection for server "${toolInfo.serverName}"` }],
+                isError: true,
+            };
+        }
+        try {
+            const result = await clientState.client.callTool({ name: toolInfo.name, arguments: rawArgs }, CompatibilityCallToolResultSchema);
+            return result.isError ? { content: result.content, isError: true } : { content: result.content };
+        }
+        catch (err) {
+            const errorMessage = extractMcpErrorMessage(err);
+            return { content: [{ type: 'text', text: `Error: ${errorMessage}` }], isError: true };
+        }
     });
     // ── Transport selection ───────────────────────────────────────────
     const transportConfig = selectTransportConfig();
@@ -1105,7 +615,6 @@ async function main() {
         catch {
             /* ignore */
         }
-        await auditLog.close();
         process.exit(0);
     }
     process.on('SIGINT', () => {