browser-debug-mcp-bridge 1.11.0 → 1.11.1

package/apps/mcp-server/dist/mcp/server.js

@@ -649,6 +649,7 @@ const TOOL_SCHEMAS = {
             captureMode: { type: 'string', enum: ['extension-fetch', 'cdp-response'] },
             triggerReload: { type: 'boolean' },
             matchMode: { type: 'string', enum: ['exact', 'prefix'] },
+            ruleType: { type: 'string' },
             requestMethod: { type: 'string' },
             requestHeaders: { type: 'object' },
             timeoutMs: { type: 'number' },
@@ -1113,6 +1114,8 @@ const DEFAULT_NETWORK_POLL_TIMEOUT_MS = 15_000;
 const MAX_NETWORK_POLL_TIMEOUT_MS = 120_000;
 const DEFAULT_NETWORK_POLL_INTERVAL_MS = 250;
 const LIVE_SESSION_DISCONNECTED_CODE = 'LIVE_SESSION_DISCONNECTED';
+const OVERRIDE_LIVE_COMMAND_TIMEOUT_CODE = 'OVERRIDE_LIVE_COMMAND_TIMEOUT';
+const OVERRIDE_LIVE_COMMAND_FAILED_CODE = 'OVERRIDE_LIVE_COMMAND_FAILED';
 const STALE_LIVE_CONNECTION_GRACE_WINDOW_MS = 30 * 60 * 1000;
 const NOISE_SESSION_HOST_PATTERNS = [
     /(^|\.)adtrafficquality\.google$/i,
@@ -1422,6 +1425,29 @@ function isRecordWithRscFlightMetadata(value) {
         && value.source !== undefined
         && value.patchKind !== undefined;
 }
+function normalizeRuleStringHeaders(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const headers = {};
+    for (const [name, rawValue] of Object.entries(value)) {
+        if (typeof rawValue !== 'string') {
+            continue;
+        }
+        const normalizedName = name.trim().toLowerCase();
+        const normalizedValue = rawValue.trim();
+        if (normalizedName.length > 0 && normalizedValue.length > 0) {
+            headers[normalizedName] = normalizedValue;
+        }
+    }
+    return Object.keys(headers).length > 0 ? headers : undefined;
+}
+function getRscFlightRuleRequestHeaders(rule) {
+    return isRecord(rule.rscFlight) ? normalizeRuleStringHeaders(rule.rscFlight.requestHeaders) : undefined;
+}
+function getOverrideRuleRequestHeaders(rule) {
+    return normalizeRuleStringHeaders(rule.requestHeaders) ?? getRscFlightRuleRequestHeaders(rule);
+}
 function buildRscFlightRuleIssues(rule) {
     const ruleId = String(rule.ruleId ?? 'unknown');
     const issues = [];
@@ -1465,17 +1491,20 @@ function buildRscFlightRuleIssues(rule) {
             }
         }
     }
-    if (rule.requestMethod !== 'GET') {
+    const requestMethod = normalizeOverrideRequestMethod(rule.requestMethod);
+    const requestHeaders = getRscFlightRuleRequestHeaders(rule);
+    const isCapturedPostRscFlight = requestMethod === 'POST' && requestHeaders?.rsc === '1';
+    if (requestMethod !== 'GET' && !isCapturedPostRscFlight) {
         issues.push({
             code: 'RSC_FLIGHT_METHOD_UNSUPPORTED',
             severity: 'error',
-            message: `Rule ${ruleId} RSC flight overrides only support GET requests.`,
+            message: `Rule ${ruleId} RSC flight overrides only support GET requests or captured POST RSC response-stage patches.`,
         });
     }
     const targetAssetUrl = typeof rule.targetAssetUrl === 'string' ? rule.targetAssetUrl : '';
     try {
         const parsed = new URL(targetAssetUrl);
-        if (!parsed.searchParams.has('_rsc')) {
+        if (requestMethod === 'GET' && !parsed.searchParams.has('_rsc')) {
             issues.push({
                 code: 'RSC_FLIGHT_TARGET_INVALID',
                 severity: 'error',
@@ -1595,7 +1624,7 @@ function buildOverrideProfileIssues(profile) {
         issues.push(...classifyOverrideResponseRequestCapability({
             ruleId: rule.ruleId,
             requestMethod: rule.requestMethod,
-            requestHeaders: rule.requestHeaders,
+            requestHeaders: getOverrideRuleRequestHeaders(rule),
             ruleType: rule.ruleType,
         }).issues.map((issue) => ({ ...issue })));
         if (rule.ruleType === 'rsc-flight') {
@@ -1676,8 +1705,14 @@ function hasEnabledExperimentalRscFlightRule(profile) {
     });
 }
 function canBypassPreflightForExperimentalRsc(profile, blockingCodes) {
+    const allowedExperimentalBlockers = new Set([
+        'UNSUPPORTED_RSC_FLIGHT_RULE',
+        'NO_OBSERVED_ASSETS',
+        'TARGET_ASSET_NOT_OBSERVED',
+    ]);
     return blockingCodes.length > 0
-        && blockingCodes.every((code) => code === 'UNSUPPORTED_RSC_FLIGHT_RULE')
+        && blockingCodes.includes('UNSUPPORTED_RSC_FLIGHT_RULE')
+        && blockingCodes.every((code) => allowedExperimentalBlockers.has(code))
         && hasEnabledExperimentalRscFlightRule(profile);
 }
 const OVERRIDE_VARIANT_HEADER_ALLOWLIST = new Set([
@@ -1797,6 +1832,36 @@ function pushOverridePreflightIssue(issues, issue) {
     }
     issues.push(issue);
 }
+function getPreflightIssues(preflight) {
+    return Array.isArray(preflight?.issues)
+        ? preflight.issues.filter((issue) => isRecord(issue))
+        : [];
+}
+function getBlockingPreflightCodes(preflight) {
+    return getPreflightIssues(preflight)
+        .filter((issue) => issue.severity === 'error')
+        .map((issue) => String(issue.code ?? 'UNKNOWN'));
+}
+function hasPreflightIssue(preflight, codes) {
+    const expected = new Set(codes);
+    return getPreflightIssues(preflight).some((issue) => expected.has(String(issue.code ?? '')));
+}
+function shouldRefreshObservedAssetsForEnable(preflight) {
+    const assetReadinessCodes = new Set([
+        'NO_OBSERVED_ASSETS',
+        'TARGET_ASSET_NOT_OBSERVED',
+        'SESSION_SCOPE_DRIFT',
+    ]);
+    const blockingCodes = getBlockingPreflightCodes(preflight);
+    if (blockingCodes.length === 0 || !blockingCodes.every((code) => assetReadinessCodes.has(code))) {
+        return false;
+    }
+    return hasPreflightIssue(preflight, [
+        'NO_OBSERVED_ASSETS',
+        'TARGET_ASSET_NOT_OBSERVED',
+        'SESSION_SCOPE_DRIFT',
+    ]);
+}
 function buildOverridePreflight(options) {
     const session = options.db
         .prepare(`
@@ -1835,7 +1900,20 @@ function buildOverridePreflight(options) {
             .filter((context) => context !== null)
             .map((context) => [String(context.variantKey ?? JSON.stringify(context)), context])).values()];
     const sessionState = options.getSessionConnectionState?.(options.sessionId);
+    const hasLiveConnectionLookup = typeof options.getSessionConnectionState === 'function';
     const diagnosis = session ? diagnoseOverridePoc(options.db, options.sessionId, latestRun?.runId) : null;
+    const observedAssetTabs = [...new Set(observedAssets
+            .map((asset) => asset.tabId)
+            .filter((tabId) => typeof tabId === 'number' && Number.isFinite(tabId)))].sort((a, b) => a - b);
+    const observedAssetPageUrls = [...new Set(observedAssets
+            .map((asset) => asset.pageUrl)
+            .filter((pageUrl) => typeof pageUrl === 'string' && pageUrl.trim().length > 0))].slice(0, 5);
+    const sessionTabId = typeof session?.tab_id === 'number' ? session.tab_id : undefined;
+    const observedAssetsWithKnownTabs = observedAssets.filter((asset) => typeof asset.tabId === 'number');
+    const topLevelScopeLikely = sessionTabId === undefined
+        || observedAssets.length === 0
+        || observedAssetsWithKnownTabs.length === 0
+        || observedAssetsWithKnownTabs.some((asset) => asset.tabId === sessionTabId);
     for (const issue of buildOverrideProfileIssues(profile)) {
         pushOverridePreflightIssue(issues, { ...issue, source: 'profile' });
     }
@@ -1865,55 +1943,117 @@ function buildOverridePreflight(options) {
                 message: `Session ${options.sessionId} has ended and cannot enable overrides.`,
             });
         }
-        if (sessionState && sessionState.connected !== true) {
+        if (hasLiveConnectionLookup && (!sessionState || sessionState.connected !== true)) {
             pushOverridePreflightIssue(issues, {
                 code: LIVE_SESSION_DISCONNECTED_CODE,
                 severity: 'error',
                 source: 'connection',
-                message: `Session ${options.sessionId} is not currently connected to the live extension bridge.`,
+                message: sessionState
+                    ? `Session ${options.sessionId} is not currently connected to the live extension bridge. Last disconnect reason: ${sessionState.disconnectReason ?? 'unknown'}.`
+                    : `Session ${options.sessionId} has no current live extension connection state.`,
+                disconnectedAt: sessionState?.disconnectedAt,
+                disconnectReason: sessionState?.disconnectReason,
             });
         }
     }
     const enabledRules = Array.isArray(profile.rules)
         ? profile.rules.filter((rule) => isRecord(rule) && rule.enabled === true)
         : [];
+    const enabledRuleAssetReadiness = enabledRules
+        .map((rule) => {
+        const targetAssetUrl = normalizeOptionalString(rule.targetAssetUrl);
+        if (!targetAssetUrl) {
+            return null;
+        }
+        const requestMethod = normalizeOverrideRequestMethod(rule.requestMethod);
+        const matchMode = String(rule.matchMode ?? 'exact');
+        const matchingAssets = observedAssets.filter((asset) => {
+            const methodMatches = normalizeOverrideRequestMethod(asset.requestMethod) === requestMethod;
+            if (!methodMatches) {
+                return false;
+            }
+            return matchMode === 'prefix'
+                ? asset.url.startsWith(targetAssetUrl)
+                : asset.url === targetAssetUrl;
+        });
+        return {
+            ruleId: String(rule.ruleId ?? 'unknown'),
+            targetAssetUrl,
+            requestMethod,
+            matchMode,
+            captureProven: rule.ruleType === 'rsc-flight' && isRecordWithRscFlightMetadata(rule.rscFlight),
+            matchingAssets,
+        };
+    })
+        .filter((readiness) => readiness !== null);
+    const matchedTargetAssetCount = enabledRuleAssetReadiness.filter((readiness) => readiness.matchingAssets.length > 0).length;
+    const capturedTargetAssetCount = enabledRuleAssetReadiness
+        .filter((readiness) => readiness.matchingAssets.length === 0 && readiness.captureProven)
+        .length;
+    const unobservedTargetAssetCount = enabledRuleAssetReadiness.length - matchedTargetAssetCount;
+    const unsatisfiedTargetAssetCount = enabledRuleAssetReadiness.length - matchedTargetAssetCount - capturedTargetAssetCount;
+    const targetAssetObserved = observedAssets.length > 0 && matchedTargetAssetCount > 0;
+    const targetAssetReadinessSatisfied = observedAssets.length > 0
+        && (enabledRuleAssetReadiness.length === 0 || matchedTargetAssetCount > 0 || capturedTargetAssetCount > 0);
     const anyServiceWorkerControlled = observedAssets.some((asset) => asset.serviceWorkerControlled);
     const cspMetaTags = [...new Set(observedAssets.flatMap((asset) => asset.cspMetaTags))];
     if (observedAssets.length === 0) {
         pushOverridePreflightIssue(issues, {
             code: 'NO_OBSERVED_ASSETS',
-            severity: 'warning',
+            severity: 'error',
             source: 'observed-assets',
-            message: 'No observed production assets are stored for this session yet.',
+            message: 'No observed production assets are stored for this session yet; the target route is not capture-ready for override enablement.',
         });
     }
-    for (const rule of enabledRules) {
-        const ruleId = String(rule.ruleId ?? 'unknown');
-        const targetAssetUrl = normalizeOptionalString(rule.targetAssetUrl);
-        if (!targetAssetUrl) {
-            continue;
-        }
-        const requestMethod = normalizeOverrideRequestMethod(rule.requestMethod);
-        const matchingAssets = observedAssets.filter((asset) => {
-            return asset.url === targetAssetUrl
-                && normalizeOverrideRequestMethod(asset.requestMethod) === requestMethod;
+    else if (!topLevelScopeLikely) {
+        pushOverridePreflightIssue(issues, {
+            code: 'SESSION_SCOPE_DRIFT',
+            severity: 'error',
+            source: 'observed-assets',
+            message: `Observed override assets were recorded only for tab(s) ${observedAssetTabs.join(', ')}, but the session top-level tab is ${sessionTabId}.`,
+            observedAssetTabs,
+            sessionTabId,
+            observedPageUrls: observedAssetPageUrls,
+        });
+    }
+    if (observedAssets.length > 0 && enabledRuleAssetReadiness.length > 0 && matchedTargetAssetCount === 0 && capturedTargetAssetCount === 0) {
+        const sampleTargets = enabledRuleAssetReadiness.slice(0, 5).map((readiness) => ({
+            ruleId: readiness.ruleId,
+            requestMethod: readiness.requestMethod,
+            matchMode: readiness.matchMode,
+            targetAssetUrl: readiness.targetAssetUrl,
+        }));
+        pushOverridePreflightIssue(issues, {
+            code: 'TARGET_ASSET_NOT_OBSERVED',
+            severity: 'error',
+            source: 'observed-assets',
+            message: enabledRuleAssetReadiness.length === 1
+                ? `Rule ${enabledRuleAssetReadiness[0].ruleId} target asset was not observed for ${enabledRuleAssetReadiness[0].requestMethod} ${enabledRuleAssetReadiness[0].targetAssetUrl}.`
+                : `None of the ${enabledRuleAssetReadiness.length} enabled override targets were observed for this session.`,
+            checkedTargetAssetCount: enabledRuleAssetReadiness.length,
+            sampleTargets,
         });
-        if (observedAssets.length > 0 && matchingAssets.length === 0) {
+    }
+    for (const readiness of enabledRuleAssetReadiness) {
+        if (readiness.matchingAssets.length === 0) {
+            if (readiness.captureProven) {
+                continue;
+            }
             pushOverridePreflightIssue(issues, {
-                code: 'TARGET_ASSET_NOT_OBSERVED',
+                code: 'TARGET_ASSET_NOT_OBSERVED_FOR_RULE',
                 severity: 'warning',
                 source: 'observed-assets',
-                message: `Rule ${ruleId} target asset was not observed for ${requestMethod} ${targetAssetUrl}.`,
+                message: `Rule ${readiness.ruleId} target asset was not observed for ${readiness.requestMethod} ${readiness.targetAssetUrl}.`,
             });
             continue;
         }
-        for (const asset of matchingAssets) {
+        for (const asset of readiness.matchingAssets) {
             if (typeof asset.integrity === 'string' && asset.integrity.length > 0) {
                 pushOverridePreflightIssue(issues, {
                     code: 'TARGET_ASSET_SRI_PRESENT',
                     severity: 'error',
                     source: 'observed-assets',
-                    message: `Rule ${ruleId} target asset ${asset.url} includes integrity="${asset.integrity}" and cannot be overridden safely.`,
+                    message: `Rule ${readiness.ruleId} target asset ${asset.url} includes integrity="${asset.integrity}" and cannot be overridden safely.`,
                 });
             }
         }
@@ -1936,23 +2076,29 @@ function buildOverridePreflight(options) {
     }
     const ready = !issues.some((issue) => issue.severity === 'error');
     const nextActions = !ready
-        ? issues.some((issue) => issue.code === 'SERVER_ACTION_UNSUPPORTED')
-            ? [{
-                    code: 'REPLAN_SERVER_ACTION_OVERRIDE',
-                    message: 'Server actions stay unsupported in production override mode; move the override to a GET document/data/API response.',
-                }]
-            : issues.some((issue) => issue.code === 'MUTATION_REPLAY_UNSUPPORTED')
-                ? [{
-                        code: 'REPLAN_MUTATION_OVERRIDE',
-                        message: 'Mutation responses are not replay-safe; use a GET document/data/API response path instead.',
-                    }]
-                : issues.some((issue) => issue.code === 'UNSAFE_REQUEST_METHOD')
-                    ? [{ code: 'REPLAN_GET_ONLY_OVERRIDE', message: 'Remove or regenerate non-GET rules before enabling overrides.' }]
-                    : issues.some((issue) => issue.code === 'TARGET_ASSET_SRI_PRESENT')
-                        ? [{ code: 'CHOOSE_ANOTHER_OVERRIDE_PATH', message: 'Choose a document/data response path or remove SRI on the production asset before enabling overrides.' }]
-                        : issues.some((issue) => issue.code === 'SESSION_NOT_FOUND' || issue.code === 'SESSION_PAUSED' || issue.code === 'SESSION_ENDED' || issue.code === LIVE_SESSION_DISCONNECTED_CODE)
-                            ? [{ code: 'RECONNECT_SESSION', message: 'Reconnect or resume the target session before enabling overrides.' }]
-                            : buildOverrideProfileNextActions(profile, issues)
+        ? issues.some((issue) => issue.code === 'SESSION_NOT_FOUND' || issue.code === 'SESSION_PAUSED' || issue.code === 'SESSION_ENDED' || issue.code === LIVE_SESSION_DISCONNECTED_CODE)
+            ? [{ code: 'RECONNECT_SESSION', message: 'Reconnect or resume the target session before enabling overrides.' }]
+            : issues.some((issue) => issue.code === 'SESSION_SCOPE_DRIFT')
+                ? [{ code: 'FOCUS_BOUND_TAB', message: 'Focus or reselect the bound top-level tab, then observe override assets again.' }]
+                : issues.some((issue) => issue.code === 'SERVER_ACTION_UNSUPPORTED')
+                    ? [{
+                            code: 'REPLAN_SERVER_ACTION_OVERRIDE',
+                            message: 'Server actions stay unsupported in production override mode; move the override to a GET document/data/API response.',
+                        }]
+                    : issues.some((issue) => issue.code === 'MUTATION_REPLAY_UNSUPPORTED')
+                        ? [{
+                                code: 'REPLAN_MUTATION_OVERRIDE',
+                                message: 'Mutation responses are not replay-safe; use a GET document/data/API response path instead.',
+                            }]
+                        : issues.some((issue) => issue.code === 'UNSAFE_REQUEST_METHOD')
+                            ? [{ code: 'REPLAN_GET_ONLY_OVERRIDE', message: 'Remove or regenerate non-GET rules before enabling overrides.' }]
+                            : issues.some((issue) => issue.code === 'TARGET_ASSET_SRI_PRESENT')
+                                ? [{ code: 'CHOOSE_ANOTHER_OVERRIDE_PATH', message: 'Choose a document/data response path or remove SRI on the production asset before enabling overrides.' }]
+                                : issues.some((issue) => issue.code === 'NO_OBSERVED_ASSETS')
+                                    ? [{ code: 'OBSERVE_OVERRIDE_ASSETS', message: 'Observe the bound target route before enabling overrides.' }]
+                                    : issues.some((issue) => issue.code === 'TARGET_ASSET_NOT_OBSERVED')
+                                        ? [{ code: 'OBSERVE_TARGET_ROUTE', message: 'Load the route that requests the configured target and observe assets again.' }]
+                                        : buildOverrideProfileNextActions(profile, issues)
         : observedAssets.length === 0
             ? [{ code: 'OBSERVE_OVERRIDE_ASSETS', message: 'Run observe_override_assets on the target route before enabling overrides in production workflows.' }]
             : [{ code: 'ENABLE_OVERRIDES', message: 'Preflight checks passed; the selected profile can be enabled on the live session.' }];
@@ -1976,8 +2122,22 @@ function buildOverridePreflight(options) {
         checks: {
             sessionFound: session !== undefined,
             connected: sessionState?.connected === true,
+            captureReady: session !== undefined
+                && getSessionStatus(session) === 'active'
+                && (!hasLiveConnectionLookup || sessionState?.connected === true)
+                && observedAssets.length > 0
+                && topLevelScopeLikely
+                && !issues.some((issue) => issue.severity === 'error'),
+            topLevelScopeLikely,
+            observedAssetTabs,
+            observedAssetPageUrls,
             observedAssetCount: observedAssets.length,
-            targetAssetObserved: issues.every((issue) => issue.code !== 'TARGET_ASSET_NOT_OBSERVED'),
+            targetAssetObserved,
+            targetAssetReadinessSatisfied,
+            matchedTargetAssetCount,
+            capturedTargetAssetCount,
+            unobservedTargetAssetCount,
+            unsatisfiedTargetAssetCount,
             serviceWorkerControlled: anyServiceWorkerControlled,
             cspMetaTagCount: cspMetaTags.length,
             recentPlanCount: recentPlans.length,
@@ -1985,6 +2145,14 @@ function buildOverridePreflight(options) {
         },
         observedAssets: {
             count: observedAssets.length,
+            tabIds: observedAssetTabs,
+            pageUrls: observedAssetPageUrls,
+            targetAssetObserved,
+            targetAssetReadinessSatisfied,
+            matchedTargetAssetCount,
+            capturedTargetAssetCount,
+            unobservedTargetAssetCount,
+            unsatisfiedTargetAssetCount,
             serviceWorkerControlled: anyServiceWorkerControlled,
             cspMetaTags,
         },
@@ -3156,6 +3324,66 @@ function normalizeCaptureError(sessionId, error) {
     }
     return fallback;
 }
+function isCaptureTimeoutMessage(message) {
+    const normalized = message.toLowerCase();
+    return normalized.includes('timed out') || normalized.includes('timeout');
+}
+function isRecoverableOverrideLiveCommandError(error) {
+    if (isLiveSessionDisconnectedError(error)) {
+        return true;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return isCaptureTimeoutMessage(message);
+}
+function extractTimeoutMsFromMessage(message, fallback) {
+    const match = message.match(/(?:after|waiting)\s+(\d+)ms/i);
+    if (!match) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(match[1] ?? '', 10);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+function buildOverrideLiveCommandFailure(options) {
+    const originalMessage = options.error instanceof Error ? options.error.message : String(options.error);
+    const timeout = extractTimeoutMsFromMessage(originalMessage, options.timeoutMs);
+    const timedOut = isCaptureTimeoutMessage(originalMessage);
+    const disconnected = isLiveSessionDisconnectedError(options.error);
+    const sessionState = options.getSessionConnectionState?.(options.sessionId);
+    const code = disconnected
+        ? LIVE_SESSION_DISCONNECTED_CODE
+        : timedOut
+            ? OVERRIDE_LIVE_COMMAND_TIMEOUT_CODE
+            : OVERRIDE_LIVE_COMMAND_FAILED_CODE;
+    const message = timedOut
+        ? `${options.command} for session ${options.sessionId} timed out after ${timeout}ms before the live extension returned an override command result.`
+        : disconnected
+            ? `${options.command} for session ${options.sessionId} could not reach a connected live extension target.`
+            : `${options.command} for session ${options.sessionId} failed before returning an override command result.`;
+    return {
+        ok: false,
+        available: false,
+        code,
+        command: options.command,
+        timeoutMs: timeout,
+        timedOut,
+        disconnected,
+        message,
+        originalMessage,
+        sessionConnected: sessionState?.connected,
+        disconnectedAt: sessionState?.disconnectedAt,
+        disconnectReason: sessionState?.disconnectReason,
+    };
+}
+function createOverrideLiveCommandError(options) {
+    const failure = buildOverrideLiveCommandFailure(options);
+    const code = String(failure.code ?? OVERRIDE_LIVE_COMMAND_FAILED_CODE);
+    const message = `${code}: ${options.command} for session ${options.sessionId} ${failure.timedOut === true
+        ? `timed out after ${String(failure.timeoutMs)}ms`
+        : `failed`}. ${String(failure.message ?? '')} Original error: ${String(failure.originalMessage ?? 'unknown')}`;
+    const error = new Error(message);
+    Object.assign(error, { code, details: failure });
+    return error;
+}
 function isLiveSessionDisconnectedError(error) {
     return error instanceof LiveSessionDisconnectedError;
 }
@@ -3167,12 +3395,99 @@ async function executeLiveCapture(captureClient, sessionId, command, payload, ti
         throw normalizeCaptureError(sessionId, error);
     }
 }
+async function executeOverrideLiveCaptureWithDiagnostics(options) {
+    try {
+        const capture = await executeLiveCapture(options.captureClient, options.sessionId, options.command, options.payload, options.timeoutMs);
+        return { capture, payload: ensureCaptureSuccess(capture, options.sessionId) };
+    }
+    catch (error) {
+        throw createOverrideLiveCommandError({
+            sessionId: options.sessionId,
+            command: options.command,
+            timeoutMs: options.timeoutMs,
+            error,
+            getSessionConnectionState: options.getSessionConnectionState,
+        });
+    }
+}
 function ensureCaptureSuccess(result, sessionId) {
     if (!result.ok) {
         throw normalizeCaptureError(sessionId, new Error(result.error ?? 'Capture command failed'));
     }
     return result.payload ?? {};
 }
+async function refreshObservedAssetsForOverrideEnable(options) {
+    const { payload } = await executeOverrideLiveCaptureWithDiagnostics({
+        captureClient: options.captureClient,
+        sessionId: options.sessionId,
+        command: 'CAPTURE_OVERRIDE_OBSERVE_ASSETS',
+        payload: { tabId: options.tabId, includePerformance: true },
+        timeoutMs: 5_000,
+        getSessionConnectionState: options.getSessionConnectionState,
+    });
+    persistObservedOverrideAssets(options.db, {
+        ...payload,
+        sessionId: options.sessionId,
+        tabId: payload.tabId ?? options.tabId,
+    });
+    return {
+        tabId: typeof payload.tabId === 'number' ? payload.tabId : options.tabId,
+        pageUrl: typeof payload.pageUrl === 'string' ? payload.pageUrl : undefined,
+        assetCount: Array.isArray(payload.assets) ? payload.assets.length : 0,
+    };
+}
+function buildPersistedOverrideStatus(options) {
+    let profile = null;
+    let profileError;
+    try {
+        profile = resolveOverrideProfileRecord(options.profileId);
+    }
+    catch (error) {
+        profileError = error instanceof Error ? error.message : String(error);
+    }
+    const latestRun = listOverridePocRuns(options.db, options.sessionId, 1, 0).runs[0] ?? null;
+    const recentRequests = listOverridePocRequests(options.db, options.sessionId, 5, 0, latestRun?.runId).requests;
+    const recentPlans = listOverridePlanAudits(options.db, { sessionId: options.sessionId, limit: 5, offset: 0 }).plans;
+    let preflight;
+    if (profileError) {
+        preflight = {
+            ready: false,
+            profileId: null,
+            profile: null,
+            issues: [{
+                    code: 'OVERRIDE_CONFIG_UNAVAILABLE',
+                    severity: 'error',
+                    source: 'profile',
+                    message: profileError,
+                }],
+            checks: {
+                sessionFound: auditSessionExists(options.db, options.sessionId),
+                connected: options.getSessionConnectionState?.(options.sessionId)?.connected === true,
+            },
+            nextActions: [{
+                    code: 'FIX_OVERRIDE_CONFIG_PATH',
+                    message: 'Create a readable override-poc config or point OVERRIDE_POC_CONFIG_PATH at the intended config, then retry override status.',
+                }],
+        };
+    }
+    else {
+        preflight = buildOverridePreflight({
+            db: options.db,
+            sessionId: options.sessionId,
+            profileId: options.profileId,
+            getSessionConnectionState: options.getSessionConnectionState,
+        });
+    }
+    return {
+        profile,
+        profileError,
+        latestRun,
+        recentRequests,
+        recentPlans,
+        preflight,
+        diagnosis: diagnoseOverridePoc(options.db, options.sessionId, latestRun?.runId),
+    };
+}
 function auditSessionExists(db, sessionId) {
     const row = db.prepare('SELECT 1 FROM sessions WHERE session_id = ? LIMIT 1').get(sessionId);
     return row !== undefined;
@@ -5405,8 +5720,14 @@ export function createV2ToolHandlers(captureClient, getDb, getSessionConnectionS
                 throw new Error('sessionId is required');
             }
             const tabId = resolveOptionalTabId(input.tabId);
-            const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_OVERRIDE_OBSERVE_ASSETS', { tabId, includePerformance: input.includePerformance !== false }, 5_000);
-            const payload = ensureCaptureSuccess(capture, sessionId);
+            const { capture, payload } = await executeOverrideLiveCaptureWithDiagnostics({
+                captureClient,
+                sessionId,
+                command: 'CAPTURE_OVERRIDE_OBSERVE_ASSETS',
+                payload: { tabId, includePerformance: input.includePerformance !== false },
+                timeoutMs: 5_000,
+                getSessionConnectionState,
+            });
             const assetCount = Array.isArray(payload.assets) ? payload.assets.length : 0;
             const persisted = getDb
                 ? persistObservedOverrideAssets(getDb(), { ...payload, sessionId, tabId: payload.tabId ?? tabId })
@@ -5436,23 +5757,31 @@ export function createV2ToolHandlers(captureClient, getDb, getSessionConnectionS
             assertOverrideResponseRequestCaptureSafe({
                 requestMethod: input.requestMethod,
                 requestHeaders: input.requestHeaders,
+                ruleType: input.ruleType,
                 subject: 'Response body capture request',
             });
             const tabId = resolveOptionalTabId(input.tabId);
             const timeoutMs = resolveTimeoutMs(input.timeoutMs, 10_000, 60_000);
-            const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_OVERRIDE_RESPONSE_BODY', {
-                targetUrl,
-                tabId,
-                captureMode: normalizeOptionalString(input.captureMode),
-                triggerReload: typeof input.triggerReload === 'boolean' ? input.triggerReload : undefined,
-                matchMode: normalizeOptionalString(input.matchMode),
-                requestMethod: input.requestMethod,
-                requestHeaders: isRecord(input.requestHeaders) ? input.requestHeaders : undefined,
-                timeoutMs,
-                maxBodyBytes: input.maxBodyBytes,
-                includeBody: input.includeBody === true,
-            }, timeoutMs + 2_000);
-            const payload = ensureCaptureSuccess(capture, sessionId);
+            const { capture, payload } = await executeOverrideLiveCaptureWithDiagnostics({
+                captureClient,
+                sessionId,
+                command: 'CAPTURE_OVERRIDE_RESPONSE_BODY',
+                payload: {
+                    targetUrl,
+                    tabId,
+                    captureMode: normalizeOptionalString(input.captureMode),
+                    triggerReload: typeof input.triggerReload === 'boolean' ? input.triggerReload : undefined,
+                    matchMode: normalizeOptionalString(input.matchMode),
+                    ruleType: normalizeOptionalString(input.ruleType),
+                    requestMethod: input.requestMethod,
+                    requestHeaders: isRecord(input.requestHeaders) ? input.requestHeaders : undefined,
+                    timeoutMs,
+                    maxBodyBytes: input.maxBodyBytes,
+                    includeBody: input.includeBody === true,
+                },
+                timeoutMs: timeoutMs + 2_000,
+                getSessionConnectionState,
+            });
             return {
                 ...createBaseResponse(sessionId),
                 limitsApplied: {
@@ -5480,19 +5809,26 @@ export function createV2ToolHandlers(captureClient, getDb, getSessionConnectionS
                 }
                 const tabId = resolveOptionalTabId(input.tabId);
                 const timeoutMs = resolveTimeoutMs(input.timeoutMs, 10_000, 60_000);
-                const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_OVERRIDE_RESPONSE_BODY', {
-                    targetUrl,
-                    tabId,
-                    captureMode: normalizeOptionalString(input.captureMode),
-                    triggerReload: typeof input.triggerReload === 'boolean' ? input.triggerReload : undefined,
-                    matchMode: normalizeOptionalString(input.matchMode),
-                    requestMethod: input.requestMethod,
-                    requestHeaders: isRecord(input.requestHeaders) ? input.requestHeaders : undefined,
-                    timeoutMs,
-                    maxBodyBytes: input.maxBodyBytes,
-                    includeBody: true,
-                }, timeoutMs + 2_000);
-                const payload = ensureCaptureSuccess(capture, sessionId);
+                const { payload } = await executeOverrideLiveCaptureWithDiagnostics({
+                    captureClient,
+                    sessionId,
+                    command: 'CAPTURE_OVERRIDE_RESPONSE_BODY',
+                    payload: {
+                        targetUrl,
+                        tabId,
+                        captureMode: normalizeOptionalString(input.captureMode),
+                        triggerReload: typeof input.triggerReload === 'boolean' ? input.triggerReload : undefined,
+                        matchMode: normalizeOptionalString(input.matchMode),
+                        ruleType: normalizeOptionalString(input.ruleType),
+                        requestMethod: input.requestMethod,
+                        requestHeaders: isRecord(input.requestHeaders) ? input.requestHeaders : undefined,
+                        timeoutMs,
+                        maxBodyBytes: input.maxBodyBytes,
+                        includeBody: true,
+                    },
+                    timeoutMs: timeoutMs + 2_000,
+                    getSessionConnectionState,
+                });
                 if (payload.truncated === true) {
                     throw new Error('Captured response body was truncated; increase maxBodyBytes before planning a patch.');
                 }
@@ -5585,8 +5921,10 @@ export function createV2ToolHandlers(captureClient, getDb, getSessionConnectionS
             let observedFromPersisted;
             if (!Array.isArray(observedAssets) && sessionId) {
                 const tabId = resolveOptionalTabId(input.tabId);
+                const command = 'CAPTURE_OVERRIDE_OBSERVE_ASSETS';
+                const timeoutMs = 5_000;
                 try {
-                    const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_OVERRIDE_OBSERVE_ASSETS', { tabId, includePerformance: true }, 5_000);
+                    const capture = await executeLiveCapture(captureClient, sessionId, command, { tabId, includePerformance: true }, timeoutMs);
                     observedFromLiveTab = ensureCaptureSuccess(capture, sessionId);
                     observedAssets = observedFromLiveTab.assets;
                     if (getDb) {
@@ -5594,11 +5932,22 @@ export function createV2ToolHandlers(captureClient, getDb, getSessionConnectionS
                     }
                 }
                 catch (error) {
-                    if (!getDb || !isLiveSessionDisconnectedError(error)) {
+                    if (getDb && isRecoverableOverrideLiveCommandError(error)) {
+                        observedAssets = listObservedOverrideAssets(getDb(), { sessionId });
+                        observedFromPersisted = { sessionId, assetCount: Array.isArray(observedAssets) ? observedAssets.length : 0 };
+                    }
+                    else if (isRecoverableOverrideLiveCommandError(error)) {
+                        throw createOverrideLiveCommandError({
+                            sessionId,
+                            command,
+                            timeoutMs,
+                            error,
+                            getSessionConnectionState,
+                        });
+                    }
+                    else {
                         throw error;
                     }
-                    observedAssets = listObservedOverrideAssets(getDb(), { sessionId });
-                    observedFromPersisted = { sessionId, assetCount: Array.isArray(observedAssets) ? observedAssets.length : 0 };
                 }
             }
             const mapping = await mapNextOverrideAssetsWithDrift({
@@ -5642,8 +5991,10 @@ export function createV2ToolHandlers(captureClient, getDb, getSessionConnectionS
             let observedFromPersisted;
             if (!Array.isArray(observedAssets) && sessionId) {
                 const tabId = resolveOptionalTabId(input.tabId);
+                const command = 'CAPTURE_OVERRIDE_OBSERVE_ASSETS';
+                const timeoutMs = 5_000;
                 try {
-                    const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_OVERRIDE_OBSERVE_ASSETS', { tabId, includePerformance: true }, 5_000);
+                    const capture = await executeLiveCapture(captureClient, sessionId, command, { tabId, includePerformance: true }, timeoutMs);
                     observedFromLiveTab = ensureCaptureSuccess(capture, sessionId);
                     observedAssets = observedFromLiveTab.assets;
                     if (getDb) {
@@ -5651,11 +6002,22 @@ export function createV2ToolHandlers(captureClient, getDb, getSessionConnectionS
                     }
                 }
                 catch (error) {
-                    if (!getDb || !isLiveSessionDisconnectedError(error)) {
+                    if (getDb && isRecoverableOverrideLiveCommandError(error)) {
+                        observedAssets = listObservedOverrideAssets(getDb(), { sessionId });
+                        observedFromPersisted = { sessionId, assetCount: Array.isArray(observedAssets) ? observedAssets.length : 0 };
+                    }
+                    else if (isRecoverableOverrideLiveCommandError(error)) {
+                        throw createOverrideLiveCommandError({
+                            sessionId,
+                            command,
+                            timeoutMs,
+                            error,
+                            getSessionConnectionState,
+                        });
+                    }
+                    else {
                         throw error;
                     }
-                    observedAssets = listObservedOverrideAssets(getDb(), { sessionId });
-                    observedFromPersisted = { sessionId, assetCount: Array.isArray(observedAssets) ? observedAssets.length : 0 };
                 }
             }
             const plan = await planNextSourceOverride({
@@ -5716,14 +6078,58 @@ export function createV2ToolHandlers(captureClient, getDb, getSessionConnectionS
             if (!sessionId) {
                 throw new Error('sessionId is required');
             }
-            const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_OVERRIDE_POC_GET_STATUS', {}, 3_000);
-            const payload = ensureCaptureSuccess(capture, sessionId);
+            const command = 'CAPTURE_OVERRIDE_POC_GET_STATUS';
+            const timeoutMs = 3_000;
+            let capture;
+            let payload;
+            try {
+                capture = await executeLiveCapture(captureClient, sessionId, command, {}, timeoutMs);
+                payload = ensureCaptureSuccess(capture, sessionId);
+            }
+            catch (error) {
+                if (!getDb || !isRecoverableOverrideLiveCommandError(error)) {
+                    throw error;
+                }
+                const persisted = buildPersistedOverrideStatus({
+                    db: getDb(),
+                    sessionId,
+                    profileId: input.profileId,
+                    getSessionConnectionState,
+                });
+                const liveStatus = buildOverrideLiveCommandFailure({
+                    sessionId,
+                    command,
+                    timeoutMs,
+                    error,
+                    getSessionConnectionState,
+                });
+                return {
+                    ...createBaseResponse(sessionId),
+                    limitsApplied: {
+                        maxResults: 1,
+                        truncated: false,
+                    },
+                    statusSource: 'persisted-audit',
+                    liveStatus,
+                    ...persisted,
+                    nextActions: [
+                        { code: 'RECONNECT_OR_RETRY_OVERRIDE_STATUS', message: 'Reconnect or rebind the top-level session, then retry get_override_status for live debugger state.' },
+                        { code: 'DIAGNOSE_OVERRIDES', message: 'Run diagnose_overrides to inspect persisted run and readiness signals while live status is unavailable.' },
+                    ],
+                };
+            }
             return {
                 ...createBaseResponse(sessionId),
                 limitsApplied: {
                     maxResults: 1,
                     truncated: capture.truncated ?? false,
                 },
+                statusSource: 'live',
+                liveStatus: {
+                    available: true,
+                    command,
+                    timeoutMs,
+                },
                 preflight: getDb
                     ? buildOverridePreflight({
                         db: getDb(),
@@ -5763,7 +6169,8 @@ export function createV2ToolHandlers(captureClient, getDb, getSessionConnectionS
             if (!sessionId) {
                 throw new Error('sessionId is required');
             }
-            const preflight = getDb
+            const tabId = resolveOptionalTabId(input.tabId);
+            let preflight = getDb
                 ? buildOverridePreflight({
                     db: getDb(),
                     sessionId,
@@ -5771,20 +6178,58 @@ export function createV2ToolHandlers(captureClient, getDb, getSessionConnectionS
                     getSessionConnectionState,
                 })
                 : null;
+            let observedBeforeEnable;
+            let observedAssetRefreshError;
+            const initialBlockingCodes = getBlockingPreflightCodes(preflight);
+            const initialProfile = isRecord(preflight?.profile) ? preflight.profile : {};
+            const initialExperimentalBypass = canBypassPreflightForExperimentalRsc(initialProfile, initialBlockingCodes);
+            if (preflight && getDb && !initialExperimentalBypass && shouldRefreshObservedAssetsForEnable(preflight)) {
+                try {
+                    observedBeforeEnable = await refreshObservedAssetsForOverrideEnable({
+                        captureClient,
+                        db: getDb(),
+                        sessionId,
+                        tabId,
+                        getSessionConnectionState,
+                    });
+                    preflight = buildOverridePreflight({
+                        db: getDb(),
+                        sessionId,
+                        profileId: input.profileId,
+                        getSessionConnectionState,
+                    });
+                }
+                catch (error) {
+                    observedAssetRefreshError = error instanceof Error ? error.message : String(error);
+                }
+            }
             if (preflight && preflight.ready !== true) {
-                const blockingCodes = Array.isArray(preflight.issues)
-                    ? preflight.issues
-                        .filter((issue) => isRecord(issue) && issue.severity === 'error')
-                        .map((issue) => String(issue.code ?? 'UNKNOWN'))
-                    : [];
+                const blockingCodes = getBlockingPreflightCodes(preflight);
                 const profile = isRecord(preflight.profile) ? preflight.profile : {};
                 if (!canBypassPreflightForExperimentalRsc(profile, blockingCodes)) {
-                    throw new Error(`Override preflight failed: ${blockingCodes.join(', ') || 'UNKNOWN'}`);
+                    const refreshSuffix = observedAssetRefreshError
+                        ? `; observed asset refresh failed: ${observedAssetRefreshError}`
+                        : '';
+                    throw new Error(`Override preflight failed: ${blockingCodes.join(', ') || 'UNKNOWN'}${refreshSuffix}`);
                 }
             }
-            const tabId = resolveOptionalTabId(input.tabId);
-            const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_OVERRIDE_POC_ENABLE', { tabId }, 8_000);
-            const payload = ensureCaptureSuccess(capture, sessionId);
+            const command = 'CAPTURE_OVERRIDE_POC_ENABLE';
+            const timeoutMs = 8_000;
+            let capture;
+            let payload;
+            try {
+                capture = await executeLiveCapture(captureClient, sessionId, command, { tabId }, timeoutMs);
+                payload = ensureCaptureSuccess(capture, sessionId);
+            }
+            catch (error) {
+                throw createOverrideLiveCommandError({
+                    sessionId,
+                    command,
+                    timeoutMs,
+                    error,
+                    getSessionConnectionState,
+                });
+            }
             return {
                 ...createBaseResponse(sessionId),
                 limitsApplied: {
@@ -5792,6 +6237,7 @@ export function createV2ToolHandlers(captureClient, getDb, getSessionConnectionS
                     truncated: capture.truncated ?? false,
                 },
                 preflight,
+                observedBeforeEnable,
                 ...payload,
                 nextActions: [{ code: 'RELOAD_OR_INTERACT', message: 'Reload or interact with the tab so configured asset requests occur under the active override.' }],
             };
@@ -5801,14 +6247,64 @@ export function createV2ToolHandlers(captureClient, getDb, getSessionConnectionS
             if (!sessionId) {
                 throw new Error('sessionId is required');
             }
-            const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_OVERRIDE_POC_DISABLE', {}, 5_000);
-            const payload = ensureCaptureSuccess(capture, sessionId);
+            const command = 'CAPTURE_OVERRIDE_POC_DISABLE';
+            const timeoutMs = 5_000;
+            let capture;
+            let payload;
+            try {
+                capture = await executeLiveCapture(captureClient, sessionId, command, {}, timeoutMs);
+                payload = ensureCaptureSuccess(capture, sessionId);
+            }
+            catch (error) {
+                if (!getDb || !isRecoverableOverrideLiveCommandError(error)) {
+                    throw createOverrideLiveCommandError({
+                        sessionId,
+                        command,
+                        timeoutMs,
+                        error,
+                        getSessionConnectionState,
+                    });
+                }
+                const persisted = buildPersistedOverrideStatus({
+                    db: getDb(),
+                    sessionId,
+                    profileId: input.profileId,
+                    getSessionConnectionState,
+                });
+                const disableAttempt = buildOverrideLiveCommandFailure({
+                    sessionId,
+                    command,
+                    timeoutMs,
+                    error,
+                    getSessionConnectionState,
+                });
+                return {
+                    ...createBaseResponse(sessionId),
+                    limitsApplied: {
+                        maxResults: 1,
+                        truncated: false,
+                    },
+                    statusSource: 'persisted-audit',
+                    disableAttempt,
+                    ...persisted,
+                    nextActions: [
+                        { code: 'RECONNECT_OR_RETRY_DISABLE', message: 'Reconnect or rebind the top-level session, then retry disable_overrides to confirm debugger detachment.' },
+                        { code: 'GET_OVERRIDE_STATUS', message: 'Run get_override_status after reconnecting to verify whether the override is still active.' },
+                    ],
+                };
+            }
             return {
                 ...createBaseResponse(sessionId),
                 limitsApplied: {
                     maxResults: 1,
                     truncated: capture.truncated ?? false,
                 },
+                statusSource: 'live',
+                disableAttempt: {
+                    ok: true,
+                    command,
+                    timeoutMs,
+                },
                 ...payload,
                 nextActions: [{ code: 'VERIFY_DISABLED', message: 'Run get_override_status if you need to confirm the debugger override is inactive.' }],
             };