@panorama-ai/gateway 2.24.133 → 2.24.137

package/dist/index.js

@@ -28,6 +28,7 @@ const DEFAULT_GATEWAY_CONCURRENCY = 10;
 const MAX_SUBAGENT_OUTPUT_BYTES = 5_000_000;
 const MAX_SUBAGENT_EVENT_PAYLOAD_BYTES = 200_000;
 const MAX_GATEWAY_LOG_BYTES = 200_000;
+const MAX_GATEWAY_EVENT_MESSAGE_CHARS = 2000;
 const SUBAGENT_EVENT_BATCH_SIZE = 200;
 const SUBAGENT_CANCEL_KILL_TIMEOUT_MS = 5_000;
 const PROCESS_KILL_GRACE_MS = 2_000;
@@ -83,6 +84,11 @@ const GATEWAY_CONCURRENCY = (() => {
 const activeSubagentRuns = new Map();
 const pendingCancelByRunId = new Map();
 const pendingCancelBySubagentId = new Map();
+const pendingGatewayEvents = [];
+let CURRENT_CAPABILITIES = null;
+let CURRENT_DEVICE_NAME = null;
+let CURRENT_CONFIG = null;
+let CURRENT_PROVIDER_HEALTH = null;
 let ACTIVE_OPTIONS = null;
 function parseArgs(argv) {
     const positional = [];
@@ -121,7 +127,7 @@ function parseArgs(argv) {
     return { command, positional, options };
 }
 function printHelp() {
-    console.log(`\nPanorama Gateway\n\nUsage:\n  panorama-gateway pair <PAIRING_CODE> [--device-name \"My Mac\"] [--supabase-url URL] [--anon-key KEY]\n  panorama-gateway start [--device-name \"My Mac\"] [--foreground|--daemon]\n  panorama-gateway stop\n  panorama-gateway status\n  panorama-gateway logs [--lines 200] [--no-follow]\n\nNotes:\n  Start runs in the background by default for the built CLI. Use --foreground to keep it attached.\n\nOutput options:\n  --verbose, -v                     Show technical details (paths, IDs, PIDs)\n\nEnvironment options:\n  --env <local|dev|test|stage|prod>  Load .env.<env> from repo root (defaults to .env)\n  --env-file <path>                 Load a specific env file\n  PANORAMA_ENV                      Same as --env\n  PANORAMA_ENV_FILE                 Same as --env-file\n\nCLI overrides:\n  --config-dir <path>               Override config directory (default: ~/.panorama/gateway)\n  --config-path <path>              Override gateway config file\n  --log-path <path>                 Override gateway log file\n  --pid-path <path>                 Override gateway pid file\n  --claude-cli <path>               Override Claude CLI command\n  --codex-cli <path>                Override Codex CLI command\n  --gemini-cli <path>               Override Gemini CLI command\n  --claude-home <path>              Override Claude home directory\n\nEnvironment overrides:\n  PANORAMA_SUPABASE_URL or SUPABASE_URL\n  PANORAMA_SUPABASE_ANON_KEY or SUPABASE_ANON_KEY or SUPABASE_PUBLISHABLE_KEY\n  PANORAMA_GATEWAY_CONFIG_DIR\n  PANORAMA_GATEWAY_CONFIG_PATH\n  PANORAMA_GATEWAY_LOG_PATH\n  PANORAMA_GATEWAY_PID_PATH\n  PANORAMA_CLAUDE_CLI or CLAUDE_CLI\n  PANORAMA_CODEX_CLI or CODEX_CLI\n  PANORAMA_GEMINI_CLI or GEMINI_CLI\n  PANORAMA_CLAUDE_HOME\n`);
+    console.log(`\nPanorama Gateway\n\nUsage:\n  panorama-gateway pair <PAIRING_CODE> [--device-name \"My Mac\"] [--supabase-url URL] [--anon-key KEY]\n  panorama-gateway start [--device-name \"My Mac\"] [--foreground|--daemon]\n  panorama-gateway stop\n  panorama-gateway status\n  panorama-gateway logs [--lines 200] [--no-follow]\n  panorama-gateway doctor\n\nNotes:\n  Start runs in the background by default for the built CLI. Use --foreground to keep it attached.\n\nOutput options:\n  --verbose, -v                     Show technical details (paths, IDs, PIDs)\n\nEnvironment options:\n  --env <local|dev|test|stage|prod>  Load .env.<env> from repo root (defaults to .env)\n  --env-file <path>                 Load a specific env file\n  PANORAMA_ENV                      Same as --env\n  PANORAMA_ENV_FILE                 Same as --env-file\n\nCLI overrides:\n  --config-dir <path>               Override config directory (default: ~/.panorama/gateway)\n  --config-path <path>              Override gateway config file\n  --log-path <path>                 Override gateway log file\n  --pid-path <path>                 Override gateway pid file\n  --claude-cli <path>               Override Claude CLI command\n  --codex-cli <path>                Override Codex CLI command\n  --gemini-cli <path>               Override Gemini CLI command\n  --claude-home <path>              Override Claude home directory\n\nEnvironment overrides:\n  PANORAMA_SUPABASE_URL or SUPABASE_URL\n  PANORAMA_SUPABASE_ANON_KEY or SUPABASE_ANON_KEY or SUPABASE_PUBLISHABLE_KEY\n  PANORAMA_GATEWAY_CONFIG_DIR\n  PANORAMA_GATEWAY_CONFIG_PATH\n  PANORAMA_GATEWAY_LOG_PATH\n  PANORAMA_GATEWAY_PID_PATH\n  PANORAMA_CLAUDE_CLI or CLAUDE_CLI\n  PANORAMA_CODEX_CLI or CODEX_CLI\n  PANORAMA_GEMINI_CLI or GEMINI_CLI\n  PANORAMA_CLAUDE_HOME\n`);
 }
 function getStringOption(options, key) {
     const value = options[key];
@@ -177,6 +183,83 @@ function resolveGatewayPaths(options) {
     }
     return paths;
 }
+function resolveGatewayFallbackConfigDir() {
+    if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', 'Panorama Gateway');
+    }
+    if (process.platform === 'win32') {
+        const base = process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
+        return path.join(base, 'Panorama Gateway');
+    }
+    const dataHome = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share');
+    return path.join(dataHome, 'panorama-gateway');
+}
+async function ensureWritableDirectory(dir) {
+    try {
+        await fs.mkdir(dir, { recursive: true });
+        const probe = path.join(dir, `.panorama-write-${randomUUID()}`);
+        await fs.writeFile(probe, 'ok', 'utf-8');
+        await fs.unlink(probe);
+        return { ok: true };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function prepareGatewayConfigDir(options, allowFallback) {
+    const resolvedOptions = getActiveOptions(options);
+    const overrideDir = getStringOption(resolvedOptions, 'config-dir') || process.env.PANORAMA_GATEWAY_CONFIG_DIR;
+    const overridePath = getStringOption(resolvedOptions, 'config-path') || process.env.PANORAMA_GATEWAY_CONFIG_PATH;
+    const explicitOverride = Boolean(overrideDir || overridePath);
+    const { configDir, configPath, logPath, pidPath } = resolveGatewayPaths(resolvedOptions);
+    const writable = await ensureWritableDirectory(configDir);
+    if (writable.ok) {
+        process.env.PANORAMA_GATEWAY_CONFIG_DIR = configDir;
+        process.env.PANORAMA_GATEWAY_CONFIG_PATH = configPath;
+        process.env.PANORAMA_GATEWAY_LOG_PATH = logPath;
+        process.env.PANORAMA_GATEWAY_PID_PATH = pidPath;
+        return { configDir, configPath };
+    }
+    if (explicitOverride || !allowFallback) {
+        throw new GatewayCliError('Gateway config directory is not writable.', writable.error ??
+            `Unable to write to ${configDir}. Set --config-dir or PANORAMA_GATEWAY_CONFIG_DIR to a writable location.`);
+    }
+    const fallbackDir = resolveGatewayFallbackConfigDir();
+    const fallbackWritable = await ensureWritableDirectory(fallbackDir);
+    if (!fallbackWritable.ok) {
+        throw new GatewayCliError('Gateway config directory is not writable.', fallbackWritable.error ??
+            `Unable to write to ${configDir} or fallback ${fallbackDir}.`);
+    }
+    const fallbackOptions = { ...resolvedOptions, 'config-dir': fallbackDir };
+    const fallbackPaths = resolveGatewayPaths(fallbackOptions);
+    if (configPath !== fallbackPaths.configPath && fsSync.existsSync(configPath)) {
+        try {
+            await fs.mkdir(path.dirname(fallbackPaths.configPath), { recursive: true });
+            await fs.copyFile(configPath, fallbackPaths.configPath);
+        }
+        catch (error) {
+            logError('Failed to migrate gateway config to fallback directory', {
+                from: configPath,
+                to: fallbackPaths.configPath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    resolvedOptions['config-dir'] = fallbackDir;
+    process.env.PANORAMA_GATEWAY_CONFIG_DIR = fallbackDir;
+    process.env.PANORAMA_GATEWAY_CONFIG_PATH = fallbackPaths.configPath;
+    process.env.PANORAMA_GATEWAY_LOG_PATH = fallbackPaths.logPath;
+    process.env.PANORAMA_GATEWAY_PID_PATH = fallbackPaths.pidPath;
+    cliWarn('Gateway config directory not writable; using fallback location.', resolvedOptions, [
+        { label: 'Fallback', value: formatPathForDisplay(fallbackDir), verboseOnly: true },
+        { label: 'Previous', value: formatPathForDisplay(configDir), verboseOnly: true },
+    ]);
+    return {
+        configDir: fallbackPaths.configDir,
+        configPath: fallbackPaths.configPath,
+        migratedFrom: configDir,
+    };
+}
 function resolveSubagentWorkdirRoot(options) {
     const { configDir } = resolveGatewayPaths(options);
     return resolveSubagentWorkdirRootBase(configDir);
@@ -209,6 +292,71 @@ function formatPathForDisplay(value) {
     }
     return value;
 }
+function truncateText(value, maxLength) {
+    if (value.length <= maxLength)
+        return value;
+    return `${value.slice(0, maxLength)}...`;
+}
+async function emitGatewayEvent(supabase, config, payload) {
+    if (!config.gatewayId || !config.teamId)
+        return;
+    const message = truncateText(payload.message, MAX_GATEWAY_EVENT_MESSAGE_CHARS);
+    const details = payload.details ?? {};
+    const { error } = await supabase
+        .from('gateway_events')
+        .insert({
+        gateway_id: config.gatewayId,
+        team_id: config.teamId,
+        provider: payload.provider ?? null,
+        level: payload.level,
+        code: payload.code ?? null,
+        message,
+        details,
+    });
+    if (error) {
+        logError('Failed to record gateway event', {
+            error: error.message,
+            code: payload.code ?? null,
+            provider: payload.provider ?? null,
+        });
+    }
+}
+function queueGatewayEvent(payload) {
+    pendingGatewayEvents.push(payload);
+}
+async function flushGatewayEvents(supabase, config) {
+    if (pendingGatewayEvents.length === 0)
+        return;
+    const queued = pendingGatewayEvents.splice(0, pendingGatewayEvents.length);
+    for (const payload of queued) {
+        await emitGatewayEvent(supabase, config, payload);
+    }
+}
+async function emitProviderHealthEvents(supabase, config, providerHealth, context) {
+    const entries = Object.entries(providerHealth);
+    for (const [providerId, health] of entries) {
+        if (health.status === 'healthy')
+            continue;
+        const error = typeof health.error === 'string' ? health.error : undefined;
+        const errorSummary = error ? truncateText(error, 500) : undefined;
+        const message = errorSummary
+            ? `${providerId} validation failed: ${errorSummary}`
+            : `${providerId} validation status: ${health.status}`;
+        await emitGatewayEvent(supabase, config, {
+            level: health.status === 'unhealthy' ? 'error' : 'warn',
+            code: 'provider_validation',
+            provider: providerId,
+            message,
+            details: {
+                context,
+                status: health.status,
+                check_type: health.check_type,
+                error: errorSummary ?? null,
+                duration_ms: health.duration_ms ?? null,
+            },
+        });
+    }
+}
 function writeCliDetails(details, options, writer) {
     if (!details || details.length === 0)
         return;
@@ -475,6 +623,28 @@ function logError(message, data) {
         console.error(`[gateway] ${message}`);
     }
 }
+async function createGatewayEventClient(config) {
+    if (!config.supabaseUrl || !config.supabaseAnonKey)
+        return null;
+    const supabase = createClient(config.supabaseUrl, config.supabaseAnonKey, {
+        auth: {
+            persistSession: false,
+            autoRefreshToken: false,
+            detectSessionInUrl: false,
+        },
+    });
+    const { data: sessionData, error: sessionError } = await supabase.auth.setSession({
+        access_token: config.accessToken,
+        refresh_token: config.refreshToken,
+    });
+    if (sessionError || !sessionData?.session) {
+        logError('Failed to authenticate gateway event session', {
+            error: sessionError?.message || 'No session returned',
+        });
+        return null;
+    }
+    return supabase;
+}
 function readPidFile(options) {
     const { pidPath } = resolveGatewayPaths(options);
     try {
@@ -517,7 +687,7 @@ async function safeJson(response) {
         return null;
     }
 }
-async function pairGateway(code, options) {
+async function pairGateway(code, options, configResolution) {
     const supabaseUrl = resolveSupabaseUrl(options);
     const supabaseAnonKey = resolveSupabaseAnonKey(options);
     if (!supabaseUrl || !supabaseAnonKey) {
@@ -557,12 +727,14 @@ async function pairGateway(code, options) {
     await saveConfig(config, options);
     let providerHealthSummary = null;
     let anyProviderReady = false;
+    let providerHealth = null;
     try {
         await ensureClaudeGatewayHome();
-        const { providerHealth, anyProviderReady: ready } = await buildCapabilities({
+        const { providerHealth: resolvedHealth, anyProviderReady: ready } = await buildCapabilities({
             validationMode: 'full',
         });
-        config.providerHealth = providerHealth;
+        config.providerHealth = resolvedHealth;
+        providerHealth = resolvedHealth;
         await saveConfig(config, options);
         providerHealthSummary = Object.entries(providerHealth)
             .map(([id, health]) => `${id}:${health.status}`)
@@ -587,6 +759,24 @@ async function pairGateway(code, options) {
     if (providerHealthSummary && !anyProviderReady) {
         cliWarn('No gateway providers passed validation. Install/authenticate a provider before starting the gateway.', options, [{ label: 'Provider health', value: providerHealthSummary, verboseOnly: true }]);
     }
+    const eventClient = await createGatewayEventClient(config);
+    if (eventClient) {
+        await flushGatewayEvents(eventClient, config);
+        if (configResolution?.migratedFrom) {
+            await emitGatewayEvent(eventClient, config, {
+                level: 'warn',
+                code: 'config_dir_fallback',
+                message: 'Gateway config directory was not writable; using fallback location.',
+                details: {
+                    previous: configResolution.migratedFrom,
+                    current: configResolution.configDir,
+                },
+            });
+        }
+        if (providerHealth) {
+            await emitProviderHealthEvents(eventClient, config, providerHealth, 'pairing');
+        }
+    }
 }
 async function execClaudeVersion() {
     const start = Date.now();
@@ -665,54 +855,110 @@ function resolveRunPlanEnv(env, workDir) {
         return [key, value];
     }));
 }
-async function runProviderValidation(provider, model) {
-    const workRoot = resolveValidationWorkdirRoot();
-    const workDir = await createWorkDir(workRoot, [
-        { value: provider.id, label: 'provider id' },
-        { value: randomUUID(), label: 'validation run id' },
-    ]);
+function isCodexConfigError(message) {
+    if (!message)
+        return false;
+    const normalized = message.toLowerCase();
+    return (normalized.includes('config.toml') ||
+        normalized.includes('mcp_servers') ||
+        normalized.includes('invalid transport'));
+}
+async function resetCodexConfig() {
+    const home = resolveGatewayProviderHome('codex');
+    const candidates = [
+        path.join(home, '.codex', 'config.toml'),
+        path.join(home, 'xdg', 'config', 'codex', 'config.toml'),
+    ];
+    const resetPaths = [];
     try {
-        const runPlan = provider.buildModelRunPlan({
-            model,
-            prompt: PROVIDER_VALIDATION_PROMPT,
-            jsonSchema: PROVIDER_VALIDATION_SCHEMA,
-            timeoutMs: PROVIDER_VALIDATION_TIMEOUT_MS,
-        });
-        assertSafeOutputPath(workDir, runPlan.outputPath);
-        await writeRunPlanFiles(workDir, runPlan.files);
-        const runResult = await runSubagentCommand(runPlan.command, runPlan.args, {
-            timeoutMs: runPlan.timeoutMs ?? PROVIDER_VALIDATION_TIMEOUT_MS,
-            cwd: workDir,
-            env: resolveRunPlanEnv(runPlan.env, workDir),
-        });
-        if (!runResult.ok) {
-            return {
-                ok: false,
-                durationMs: runResult.durationMs,
-                error: runResult.error || runResult.stderr || 'Provider validation failed',
-            };
+        for (const configPath of candidates) {
+            if (!fsSync.existsSync(configPath))
+                continue;
+            const backupPath = `${configPath}.backup.${Date.now()}`;
+            await fs.rename(configPath, backupPath);
+            resetPaths.push(configPath);
         }
+        return { reset: resetPaths.length > 0, paths: resetPaths };
+    }
+    catch (error) {
+        return {
+            reset: resetPaths.length > 0,
+            paths: resetPaths,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function runProviderValidation(provider, model) {
+    const attempt = async () => {
+        const workRoot = resolveValidationWorkdirRoot();
+        const workDir = await createWorkDir(workRoot, [
+            { value: provider.id, label: 'provider id' },
+            { value: randomUUID(), label: 'validation run id' },
+        ]);
         try {
-            provider.normalizeModelRunResult({
-                stdout: runResult.stdout,
-                outputFormat: runPlan.outputFormat,
-                outputMode: runPlan.outputMode,
-                outputPath: runPlan.outputPath,
-                workDir,
+            const runPlan = provider.buildModelRunPlan({
+                model,
+                prompt: PROVIDER_VALIDATION_PROMPT,
+                jsonSchema: PROVIDER_VALIDATION_SCHEMA,
+                timeoutMs: PROVIDER_VALIDATION_TIMEOUT_MS,
             });
+            assertSafeOutputPath(workDir, runPlan.outputPath);
+            await writeRunPlanFiles(workDir, runPlan.files);
+            const runResult = await runSubagentCommand(runPlan.command, runPlan.args, {
+                timeoutMs: runPlan.timeoutMs ?? PROVIDER_VALIDATION_TIMEOUT_MS,
+                cwd: workDir,
+                env: resolveRunPlanEnv(runPlan.env, workDir),
+            });
+            if (!runResult.ok) {
+                return {
+                    ok: false,
+                    durationMs: runResult.durationMs,
+                    error: runResult.error || runResult.stderr || 'Provider validation failed',
+                };
+            }
+            try {
+                provider.normalizeModelRunResult({
+                    stdout: runResult.stdout,
+                    outputFormat: runPlan.outputFormat,
+                    outputMode: runPlan.outputMode,
+                    outputPath: runPlan.outputPath,
+                    workDir,
+                });
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    durationMs: runResult.durationMs,
+                    error: error instanceof Error ? error.message : 'Failed to parse validation output',
+                };
+            }
+            return { ok: true, durationMs: runResult.durationMs };
         }
-        catch (error) {
-            return {
-                ok: false,
-                durationMs: runResult.durationMs,
-                error: error instanceof Error ? error.message : 'Failed to parse validation output',
-            };
+        finally {
+            await cleanupWorkDir(workDir, workRoot);
+        }
+    };
+    const result = await attempt();
+    if (result.ok)
+        return result;
+    if (provider.id === 'codex' && isCodexConfigError(result.error)) {
+        const reset = await resetCodexConfig();
+        if (reset.reset) {
+            logInfo('Reset Codex config after validation error', { paths: reset.paths });
+            queueGatewayEvent({
+                level: 'warn',
+                code: 'provider_config_reset',
+                provider: provider.id,
+                message: 'Codex config reset after validation error.',
+                details: {
+                    paths: reset.paths,
+                    error: reset.error ?? null,
+                },
+            });
+            return await attempt();
         }
-        return { ok: true, durationMs: runResult.durationMs };
-    }
-    finally {
-        await cleanupWorkDir(workDir, workRoot);
     }
+    return result;
 }
 function coerceHealthStatus(value) {
     if (value === 'healthy' || value === 'unhealthy' || value === 'unknown' || value === 'unavailable') {
@@ -751,8 +997,10 @@ async function resolveProviderHealth(params) {
             duration_ms: validation.durationMs,
         };
     }
+    const fallbackStatus = coerceHealthStatus(lastFullStatus);
+    const previousStatus = previous?.status ? coerceHealthStatus(previous.status) : undefined;
     return {
-        status: coerceHealthStatus(lastFullStatus),
+        status: previousStatus ?? fallbackStatus,
         check_type: 'light',
         checked_at: now,
         last_full_checked_at: lastFullCheckedAt,
@@ -853,6 +1101,129 @@ function appendClaudeIsolationArgs(args, support) {
         args.push('--disable-slash-commands');
     }
 }
+function formatProviderLabel(providerId) {
+    switch (providerId) {
+        case 'claude_code':
+            return 'Claude';
+        case 'gemini':
+            return 'Gemini';
+        case 'codex':
+            return 'Codex';
+        default:
+            return providerId;
+    }
+}
+function normalizeProviderErrorSummary(message) {
+    if (!message)
+        return undefined;
+    const normalized = message.replace(/\s+/g, ' ').trim();
+    if (!normalized)
+        return undefined;
+    return truncateText(normalized, 500);
+}
+function buildProviderFailureMessage(providerId, detail) {
+    const label = formatProviderLabel(providerId);
+    const detailSuffix = detail ? ` Details: ${detail}` : '';
+    return `Gateway provider ${label} is unhealthy. Try another provider or run "panorama-gateway doctor".${detailSuffix}`;
+}
+function isProviderReady(entry) {
+    if (!entry)
+        return false;
+    if (entry.health?.status === 'healthy')
+        return true;
+    if (!entry.available)
+        return false;
+    if (!entry.health)
+        return true;
+    return entry.health.status !== 'unavailable' && entry.health.status !== 'unhealthy';
+}
+function computeGatewayStatusFromCapabilities(providers) {
+    const anyReady = Object.values(providers).some((entry) => isProviderReady(entry));
+    return anyReady ? 'ready' : 'error';
+}
+function resolveRuntimeProviderHealth(providerId) {
+    if (CURRENT_PROVIDER_HEALTH && CURRENT_PROVIDER_HEALTH[providerId]) {
+        return CURRENT_PROVIDER_HEALTH[providerId];
+    }
+    const fromConfig = CURRENT_CONFIG?.providerHealth?.[providerId];
+    if (fromConfig)
+        return fromConfig;
+    return PROVIDER_CAPABILITIES?.[providerId]?.health;
+}
+async function updateRuntimeProviderHealth(params) {
+    const providerCapabilities = PROVIDER_CAPABILITIES;
+    if (!providerCapabilities || !providerCapabilities[params.providerId])
+        return;
+    const previous = resolveRuntimeProviderHealth(params.providerId);
+    const nextStatus = params.status;
+    const errorSummary = normalizeProviderErrorSummary(params.error);
+    const nowIso = new Date().toISOString();
+    const nextHealth = {
+        status: nextStatus,
+        check_type: 'light',
+        checked_at: nowIso,
+        last_full_checked_at: previous?.last_full_checked_at,
+        last_full_status: previous?.last_full_status,
+        error: nextStatus === 'healthy' ? undefined : errorSummary ?? previous?.error,
+    };
+    providerCapabilities[params.providerId] = {
+        ...providerCapabilities[params.providerId],
+        health: nextHealth,
+    };
+    if (CURRENT_CAPABILITIES) {
+        const rawProviders = CURRENT_CAPABILITIES.providers;
+        if (rawProviders && typeof rawProviders === 'object') {
+            const providers = rawProviders;
+            if (providers[params.providerId]) {
+                providers[params.providerId] = {
+                    ...providers[params.providerId],
+                    health: nextHealth,
+                };
+            }
+            CURRENT_CAPABILITIES = {
+                ...CURRENT_CAPABILITIES,
+                providers,
+            };
+        }
+    }
+    if (CURRENT_CONFIG) {
+        if (!CURRENT_CONFIG.providerHealth) {
+            CURRENT_CONFIG.providerHealth = {};
+        }
+        CURRENT_CONFIG.providerHealth[params.providerId] = nextHealth;
+        void saveConfig(CURRENT_CONFIG).catch((error) => {
+            logError('Failed to persist gateway provider health', {
+                error: error instanceof Error ? error.message : String(error),
+                provider: params.providerId,
+            });
+        });
+    }
+    CURRENT_PROVIDER_HEALTH = {
+        ...(CURRENT_PROVIDER_HEALTH ?? {}),
+        [params.providerId]: nextHealth,
+    };
+    const nextStatusOverall = computeGatewayStatusFromCapabilities(providerCapabilities);
+    if (CURRENT_CAPABILITIES && CURRENT_DEVICE_NAME) {
+        await sendHeartbeat(params.supabase, nextStatusOverall, CURRENT_CAPABILITIES, CURRENT_DEVICE_NAME);
+    }
+    const statusChanged = previous?.status !== nextStatus;
+    if (statusChanged && nextStatus !== 'healthy' && CURRENT_CONFIG) {
+        const label = formatProviderLabel(params.providerId);
+        await emitGatewayEvent(params.supabase, CURRENT_CONFIG, {
+            level: nextStatus === 'unhealthy' ? 'error' : 'warn',
+            code: 'provider_unhealthy',
+            provider: params.providerId,
+            message: `${label} provider marked ${nextStatus}.`,
+            details: {
+                context: params.context,
+                status: nextStatus,
+                error: errorSummary ?? null,
+                job_id: params.jobId ?? null,
+                run_id: params.runId ?? null,
+            },
+        });
+    }
+}
 async function ensureClaudeGatewayHome() {
     const claudeHome = resolveClaudeGatewayHome();
     await fs.mkdir(claudeHome, { recursive: true });
@@ -2065,9 +2436,38 @@ async function handleSubagentRunJob(supabase, job) {
         const exitCodeMessage = activeResult.exitCode === null
             ? 'Subagent process did not exit cleanly'
             : `Subagent exited with code ${activeResult.exitCode}`;
-        const errorMessage = !activeResult.ok
+        let errorMessage = !activeResult.ok
             ? (activeResult.error ?? stderrMessage ?? exitCodeMessage)
             : parseError ?? null;
+        const providerId = adapter.id;
+        if (!wasCancelled) {
+            if (shouldFail) {
+                const parsed = activeResult.stderr
+                    ? extractGatewayErrorSummary(activeResult.stderr)?.message
+                    : null;
+                const providerSummary = normalizeProviderErrorSummary(parsed ?? errorMessage ?? null);
+                await updateRuntimeProviderHealth({
+                    supabase,
+                    providerId,
+                    status: 'unhealthy',
+                    error: providerSummary ?? errorMessage,
+                    context: 'subagent_run',
+                    jobId: job.id,
+                    runId: resolvedRunId,
+                });
+                errorMessage = buildProviderFailureMessage(providerId, providerSummary ?? errorMessage);
+            }
+            else {
+                await updateRuntimeProviderHealth({
+                    supabase,
+                    providerId,
+                    status: 'healthy',
+                    context: 'subagent_run',
+                    jobId: job.id,
+                    runId: resolvedRunId,
+                });
+            }
+        }
         const failureOutput = buildErrorOutput(wasCancelled ? cancelReason : errorMessage ?? 'Subagent run failed');
         const metadataUpdate = {
             schema_version: SUBAGENT_SCHEMA_VERSION,
@@ -2197,6 +2597,16 @@ async function handleModelRunJob(_supabase, job) {
     const providerId = (providerFromPayload === 'claude_code' || providerFromPayload === 'codex' || providerFromPayload === 'gemini')
         ? providerFromPayload
         : inferGatewayProviderFromModel(model);
+    const updateProviderHealth = async (status, errorMessage) => {
+        await updateRuntimeProviderHealth({
+            supabase: _supabase,
+            providerId,
+            status,
+            error: errorMessage ?? null,
+            context: 'model_run',
+            jobId: job.id,
+        });
+    };
     const provider = getGatewayCliProvider(providerId);
     let normalizedPrompt = prompt;
     let normalizedSchema = jsonSchema;
@@ -2260,17 +2670,20 @@ async function handleModelRunJob(_supabase, job) {
         }
         await updateJobDebug(_supabase, job.id, debugInfo);
         if (!runResult.ok) {
+            const summary = normalizeProviderErrorSummary(errorSummary?.message ?? runResult.error ?? 'Gateway model run failed');
+            await updateProviderHealth('unhealthy', summary ?? 'Gateway model run failed');
+            const failureMessage = buildProviderFailureMessage(providerId, summary);
             return {
                 ok: false,
                 result: {
-                    message: 'Gateway CLI failed for model run',
+                    message: failureMessage,
                     exit_code: runResult.exitCode,
                     stderr: stderrInfo.value,
                     stdout: stdoutInfo.value,
                     command: commandLine,
                     error_summary: errorSummary ?? null,
                 },
-                error: runResult.error ?? 'Gateway model run failed',
+                error: failureMessage,
             };
         }
         let normalized;
@@ -2285,12 +2698,21 @@ async function handleModelRunJob(_supabase, job) {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : 'Failed to normalize gateway output';
+            const summary = normalizeProviderErrorSummary(message);
+            await updateProviderHealth('unhealthy', summary ?? message);
+            const failureMessage = buildProviderFailureMessage(providerId, summary ?? message);
             return {
                 ok: false,
-                result: { message, stdout: stdoutInfo.value, stderr: stderrInfo.value, command: commandLine },
-                error: message,
+                result: {
+                    message: failureMessage,
+                    stdout: stdoutInfo.value,
+                    stderr: stderrInfo.value,
+                    command: commandLine,
+                },
+                error: failureMessage,
             };
         }
+        await updateProviderHealth('healthy');
         return {
             ok: true,
             result: {
@@ -2455,7 +2877,7 @@ async function processJob(supabase, config, job) {
         job_type: claimed.job_type,
     }, `Unsupported job type: ${claimed.job_type}`);
 }
-async function startGateway(options) {
+async function startGateway(options, configResolution) {
     const paths = resolveGatewayPaths(options);
     const foregroundRequested = options.foreground === true;
     const explicitDaemon = options.daemon === true || options.background === true;
@@ -2533,6 +2955,8 @@ async function startGateway(options) {
         deviceName,
     };
     await saveConfig(config, options);
+    CURRENT_CONFIG = config;
+    CURRENT_DEVICE_NAME = deviceName;
     const supabase = createClient(supabaseUrl, supabaseAnonKey, {
         auth: {
             persistSession: false,
@@ -2583,6 +3007,8 @@ async function startGateway(options) {
     }
     let currentCapabilities = initialCapabilities;
     let currentProviderHealth = providerHealth;
+    CURRENT_CAPABILITIES = initialCapabilities;
+    CURRENT_PROVIDER_HEALTH = providerHealth;
     const providerStatus = (currentCapabilities.providers ?? {});
     const initialStatus = anyProviderReady ? 'ready' : 'error';
     logInfo('Gateway capabilities loaded', {
@@ -2596,6 +3022,22 @@ async function startGateway(options) {
         ])),
         concurrency: GATEWAY_CONCURRENCY,
     });
+    if (configResolution?.migratedFrom) {
+        await emitGatewayEvent(supabase, config, {
+            level: 'warn',
+            code: 'config_dir_fallback',
+            message: 'Gateway config directory was not writable; using fallback location.',
+            details: {
+                previous: configResolution.migratedFrom,
+                current: configResolution.configDir,
+            },
+        });
+    }
+    await flushGatewayEvents(supabase, config);
+    const ranFullValidation = Object.values(providerHealth).some((health) => health.check_type === 'full');
+    if (ranFullValidation) {
+        await emitProviderHealthEvents(supabase, config, providerHealth, 'startup');
+    }
     await sendHeartbeat(supabase, initialStatus, currentCapabilities, deviceName);
     let heartbeatStatus = initialStatus;
     await writePidFile(process.pid, options);
@@ -2607,11 +3049,13 @@ async function startGateway(options) {
         try {
             const { capabilities: nextCapabilities, providerHealth: nextProviderHealth, anyProviderReady: nextReady, } = await buildCapabilities({
                 validationMode: 'light',
-                previousHealth: currentProviderHealth,
+                previousHealth: CURRENT_PROVIDER_HEALTH ?? currentProviderHealth,
             });
             currentCapabilities = nextCapabilities;
             currentProviderHealth = nextProviderHealth;
             config.providerHealth = nextProviderHealth;
+            CURRENT_CAPABILITIES = nextCapabilities;
+            CURRENT_PROVIDER_HEALTH = nextProviderHealth;
             heartbeatStatus = nextReady ? 'ready' : 'error';
             await sendHeartbeat(supabase, heartbeatStatus, currentCapabilities, deviceName);
         }
@@ -2827,6 +3271,64 @@ async function statusGateway(options) {
         { label: 'PID Path', value: formatPathForDisplay(pidPath), verboseOnly: true },
     ]);
 }
+async function doctorGateway(options, configResolution) {
+    const { configPath, configDir } = resolveGatewayPaths(options);
+    const configExists = fsSync.existsSync(configPath);
+    let config = null;
+    if (configExists) {
+        try {
+            config = await loadConfig(options);
+        }
+        catch (error) {
+            cliWarn('Unable to read gateway config.', options, [
+                { label: 'Config path', value: formatPathForDisplay(configPath), verboseOnly: true },
+                { label: 'Error', value: error instanceof Error ? error.message : String(error), verboseOnly: true },
+            ]);
+        }
+    }
+    cliInfo('Gateway doctor report', options, [
+        { label: 'Config dir', value: formatPathForDisplay(configDir) },
+        { label: 'Paired', value: configExists ? 'Yes' : 'No' },
+        { label: 'Gateway ID', value: config?.gatewayId ?? undefined, verboseOnly: true },
+        { label: 'Team ID', value: config?.teamId ?? undefined, verboseOnly: true },
+    ]);
+    await ensureClaudeGatewayHome();
+    const { providerHealth, anyProviderReady } = await buildCapabilities({
+        validationMode: 'full',
+        previousHealth: config?.providerHealth,
+    });
+    if (config) {
+        config.providerHealth = providerHealth;
+        await saveConfig(config, options);
+    }
+    const providerEntries = Object.entries(providerHealth);
+    console.log('Provider status:');
+    for (const [providerId, health] of providerEntries) {
+        const error = health.error ? ` (${truncateText(health.error, 200)})` : '';
+        console.log(`  - ${providerId}: ${health.status}${error}`);
+    }
+    if (!anyProviderReady) {
+        cliWarn('No providers passed validation. Install/authenticate a provider before starting the gateway.', options);
+    }
+    if (config) {
+        const eventClient = await createGatewayEventClient(config);
+        if (eventClient) {
+            await flushGatewayEvents(eventClient, config);
+            if (configResolution?.migratedFrom) {
+                await emitGatewayEvent(eventClient, config, {
+                    level: 'warn',
+                    code: 'config_dir_fallback',
+                    message: 'Gateway config directory was not writable; using fallback location.',
+                    details: {
+                        previous: configResolution.migratedFrom,
+                        current: configResolution.configDir,
+                    },
+                });
+            }
+            await emitProviderHealthEvents(eventClient, config, providerHealth, 'doctor');
+        }
+    }
+}
 async function showLogs(options) {
     const linesRaw = getStringOption(options, 'lines');
     const lines = linesRaw ? Number.parseInt(linesRaw, 10) : 200;
@@ -2897,16 +3399,20 @@ async function run() {
     }
     if (parsed.command === 'pair') {
         loadEnvironment(parsed.options);
+        const configResolution = await prepareGatewayConfigDir(parsed.options, true);
+        applyOptionEnvOverrides(parsed.options);
         const code = getStringOption(parsed.options, 'code') || parsed.positional[0];
         if (!code) {
             throw new Error('Pairing code is required');
         }
-        await pairGateway(code, parsed.options);
+        await pairGateway(code, parsed.options, configResolution);
         return;
     }
     if (parsed.command === 'start') {
         loadEnvironment(parsed.options);
-        await startGateway(parsed.options);
+        const configResolution = await prepareGatewayConfigDir(parsed.options, true);
+        applyOptionEnvOverrides(parsed.options);
+        await startGateway(parsed.options, configResolution);
         return;
     }
     if (parsed.command === 'stop') {
@@ -2921,6 +3427,13 @@ async function run() {
         await showLogs(parsed.options);
         return;
     }
+    if (parsed.command === 'doctor') {
+        loadEnvironment(parsed.options);
+        const configResolution = await prepareGatewayConfigDir(parsed.options, true);
+        applyOptionEnvOverrides(parsed.options);
+        await doctorGateway(parsed.options, configResolution);
+        return;
+    }
     printHelp();
     process.exitCode = 1;
 }