@flrande/bak-extension 0.6.14 → 0.6.16

package/src/background.ts

@@ -25,18 +25,18 @@ import {
   clearNetworkEntries,
   dropNetworkCapture,
   ensureNetworkDebugger,
-  exportHar,
-  getNetworkEntry,
-  latestNetworkTimestamp,
-  listNetworkEntries,
-  recentNetworkSampleIds,
-  searchNetworkEntries,
-  waitForNetworkEntry
+  exportHar,
+  getNetworkEntry,
+  getReplayableNetworkRequest,
+  latestNetworkTimestamp,
+  listNetworkEntries,
+  recentNetworkSampleIds,
+  searchNetworkEntries,
+  waitForNetworkEntry
 } from './network-debugger.js';
 import { isSupportedAutomationUrl } from './url-policy.js';
 import { computeReconnectDelayMs } from './reconnect.js';
 import { resolveSessionBindingStateMap, STORAGE_KEY_SESSION_BINDINGS } from './session-binding-storage.js';
-import { containsRedactionMarker } from './privacy.js';
 import {
   type SessionBindingBrowser,
   type SessionBindingColor,
@@ -70,12 +70,14 @@ interface ExtensionConfig {
   debugRichText: boolean;
 }
 
-interface RuntimeErrorDetails {
-  message: string;
-  context: 'config' | 'socket' | 'request' | 'parse';
-  at: number;
-}
-
+interface RuntimeErrorDetails {
+  message: string;
+  context: 'config' | 'socket' | 'request' | 'parse';
+  at: number;
+}
+
+type PopupSessionBindingStatus = 'attached' | 'window-only' | 'detached';
+
 interface PopupSessionBindingSummary {
   id: string;
   label: string;
@@ -85,7 +87,7 @@ interface PopupSessionBindingSummary {
   activeTabUrl: string | null;
   windowId: number | null;
   groupId: number | null;
-  detached: boolean;
+  status: PopupSessionBindingStatus;
   lastBindingUpdateAt: number | null;
   lastBindingUpdateReason: string | null;
 }
@@ -107,14 +109,15 @@ interface PopupState {
   extensionVersion: string;
   lastBindingUpdateAt: number | null;
   lastBindingUpdateReason: string | null;
-  sessionBindings: {
-    count: number;
-    attachedCount: number;
-    detachedCount: number;
-    tabCount: number;
-    items: PopupSessionBindingSummary[];
-  };
-}
+  sessionBindings: {
+    count: number;
+    attachedCount: number;
+    windowOnlyCount: number;
+    detachedCount: number;
+    tabCount: number;
+    items: PopupSessionBindingSummary[];
+  };
+}
 
 const DEFAULT_PORT = 17373;
 const STORAGE_KEY_TOKEN = 'pairToken';
@@ -344,44 +347,99 @@ async function loadSessionBindingState(bindingId: string): Promise<SessionBindin
   return stateMap[bindingId] ?? null;
 }
 
-async function listSessionBindingStates(): Promise<SessionBindingRecord[]> {
-  return Object.values(await loadSessionBindingStateMap());
-}
-
-async function summarizeSessionBindings(states: SessionBindingRecord[]): Promise<PopupState['sessionBindings']> {
-  const items = await Promise.all(
-    states.map(async (state) => {
-      const detached = state.windowId === null || state.tabIds.length === 0;
-      const activeTab =
-        typeof state.activeTabId === 'number' ? await sessionBindingBrowser.getTab(state.activeTabId) : null;
-      const bindingUpdate = bindingUpdateMetadata.get(state.id);
-      return {
-        id: state.id,
-        label: state.label,
-        tabCount: state.tabIds.length,
-        activeTabId: state.activeTabId,
-        activeTabTitle: activeTab?.title ?? null,
-        activeTabUrl: activeTab?.url ?? null,
-        windowId: state.windowId,
-        groupId: state.groupId,
-        detached,
-        lastBindingUpdateAt: bindingUpdate?.at ?? null,
-        lastBindingUpdateReason: bindingUpdate?.reason ?? null
-      } satisfies PopupSessionBindingSummary;
-    })
-  );
+async function listSessionBindingStates(): Promise<SessionBindingRecord[]> {
+  return Object.values(await loadSessionBindingStateMap());
+}
+
+function collectPopupSessionBindingTabIds(state: SessionBindingRecord): number[] {
+  return [
+    ...new Set(state.tabIds.concat([state.activeTabId, state.primaryTabId].filter((value): value is number => typeof value === 'number')))
+  ];
+}
+
+async function inspectPopupSessionBinding(
+  state: SessionBindingRecord
+): Promise<{ summary: PopupSessionBindingSummary; prune: boolean }> {
+  const trackedTabs = (
+    await Promise.all(
+      collectPopupSessionBindingTabIds(state).map(async (tabId) => {
+        return await sessionBindingBrowser.getTab(tabId);
+      })
+    )
+  ).filter((tab): tab is SessionBindingTab => tab !== null);
+  const liveWindow = typeof state.windowId === 'number' ? await sessionBindingBrowser.getWindow(state.windowId) : null;
+  const activeTab = trackedTabs.find((tab) => tab.id === state.activeTabId) ?? trackedTabs.find((tab) => tab.active) ?? trackedTabs[0] ?? null;
+  const status: PopupSessionBindingStatus = trackedTabs.length > 0 ? 'attached' : liveWindow ? 'window-only' : 'detached';
+  const bindingUpdate = bindingUpdateMetadata.get(state.id);
+  return {
+    summary: {
+      id: state.id,
+      label: state.label,
+      tabCount: trackedTabs.length,
+      activeTabId: activeTab?.id ?? null,
+      activeTabTitle: activeTab?.title ?? null,
+      activeTabUrl: activeTab?.url ?? null,
+      windowId: activeTab?.windowId ?? trackedTabs[0]?.windowId ?? liveWindow?.id ?? state.windowId,
+      groupId:
+        trackedTabs.length > 0
+          ? activeTab?.groupId ?? trackedTabs.find((tab) => tab.groupId !== null)?.groupId ?? state.groupId
+          : null,
+      status,
+      lastBindingUpdateAt: bindingUpdate?.at ?? null,
+      lastBindingUpdateReason: bindingUpdate?.reason ?? null
+    },
+    prune: status === 'detached'
+  };
+}
+
+async function summarizeSessionBindings(): Promise<PopupState['sessionBindings']> {
+  const statusRank: Record<PopupSessionBindingStatus, number> = {
+    attached: 0,
+    'window-only': 1,
+    detached: 2
+  };
+  const items = await mutateSessionBindingStateMap(async (stateMap) => {
+    const inspected = await Promise.all(
+      Object.entries(stateMap).map(async ([bindingId, state]) => {
+        return {
+          bindingId,
+          inspected: await inspectPopupSessionBinding(state)
+        };
+      })
+    );
+    for (const entry of inspected) {
+      if (entry.inspected.prune) {
+        delete stateMap[entry.bindingId];
+      }
+    }
+    return inspected
+      .filter((entry) => !entry.inspected.prune)
+      .map((entry) => entry.inspected.summary)
+      .sort((left, right) => {
+        const byStatus = statusRank[left.status] - statusRank[right.status];
+        if (byStatus !== 0) {
+          return byStatus;
+        }
+        const byUpdate = (right.lastBindingUpdateAt ?? 0) - (left.lastBindingUpdateAt ?? 0);
+        if (byUpdate !== 0) {
+          return byUpdate;
+        }
+        return left.label.localeCompare(right.label);
+      });
+  });
   return {
     count: items.length,
-    attachedCount: items.filter((item) => !item.detached).length,
-    detachedCount: items.filter((item) => item.detached).length,
-    tabCount: items.reduce((sum, item) => sum + item.tabCount, 0),
-    items
-  };
-}
-
+    attachedCount: items.filter((item) => item.status === 'attached').length,
+    windowOnlyCount: items.filter((item) => item.status === 'window-only').length,
+    detachedCount: items.filter((item) => item.status === 'detached').length,
+    tabCount: items.reduce((sum, item) => sum + item.tabCount, 0),
+    items
+  };
+}
+
 async function buildPopupState(): Promise<PopupState> {
   const config = await getConfig();
-  const sessionBindings = await summarizeSessionBindings(await listSessionBindingStates());
+  const sessionBindings = await summarizeSessionBindings();
   const reconnectRemainingMs = nextReconnectAt === null ? null : Math.max(0, nextReconnectAt - Date.now());
   let connectionState: PopupState['connectionState'];
   if (!config.token) {
@@ -780,10 +838,18 @@ async function withTab(target: { tabId?: number; bindingId?: string } = {}, opti
   return validate(tab);
 }
 
-async function captureAlignedTabScreenshot(tab: chrome.tabs.Tab): Promise<string> {
-  if (typeof tab.id !== 'number' || typeof tab.windowId !== 'number') {
-    throw toError('E_NOT_FOUND', 'Tab screenshot requires tab id and window id');
-  }
+async function captureAlignedTabScreenshot(tab: chrome.tabs.Tab): Promise<{
+  captureStatus: 'complete' | 'degraded' | 'skipped';
+  imageData?: string;
+  captureError?: {
+    code?: string;
+    message: string;
+    details?: Record<string, unknown>;
+  };
+}> {
+  if (typeof tab.id !== 'number' || typeof tab.windowId !== 'number') {
+    throw toError('E_NOT_FOUND', 'Tab screenshot requires tab id and window id');
+  }
 
   const activeTabs = await chrome.tabs.query({ windowId: tab.windowId, active: true });
   const activeTab = activeTabs[0];
@@ -793,13 +859,24 @@ async function captureAlignedTabScreenshot(tab: chrome.tabs.Tab): Promise<string
     await chrome.tabs.update(tab.id, { active: true });
     await new Promise((resolve) => setTimeout(resolve, 80));
   }
-
-  try {
-    return await chrome.tabs.captureVisibleTab(tab.windowId, { format: 'png' });
-  } finally {
-    if (shouldSwitch && typeof activeTab?.id === 'number') {
-      try {
-        await chrome.tabs.update(activeTab.id, { active: true });
+
+  try {
+    return {
+      captureStatus: 'complete',
+      imageData: await chrome.tabs.captureVisibleTab(tab.windowId, { format: 'png' })
+    };
+  } catch (error) {
+    return {
+      captureStatus: 'degraded',
+      captureError: {
+        code: 'E_CAPTURE_FAILED',
+        message: error instanceof Error ? error.message : String(error)
+      }
+    };
+  } finally {
+    if (shouldSwitch && typeof activeTab?.id === 'number') {
+      try {
+        await chrome.tabs.update(activeTab.id, { active: true });
       } catch {
         // Ignore restore errors if the original tab no longer exists.
       }
@@ -954,10 +1031,10 @@ async function executePageWorld<T>(
     target,
     world: 'MAIN',
     args: [
-      {
-        action,
-        scope,
-        framePath,
+      {
+        action,
+        scope,
+        framePath,
         expr: typeof params.expr === 'string' ? params.expr : '',
         path: typeof params.path === 'string' ? params.path : '',
         resolver: typeof params.resolver === 'string' ? params.resolver : undefined,
@@ -965,13 +1042,15 @@ async function executePageWorld<T>(
         method: typeof params.method === 'string' ? params.method : 'GET',
         headers: typeof params.headers === 'object' && params.headers !== null ? params.headers : undefined,
         body: typeof params.body === 'string' ? params.body : undefined,
-        contentType: typeof params.contentType === 'string' ? params.contentType : undefined,
-        mode: params.mode === 'json' ? 'json' : 'raw',
-        maxBytes: typeof params.maxBytes === 'number' ? params.maxBytes : undefined,
-        timeoutMs: typeof params.timeoutMs === 'number' ? params.timeoutMs : undefined
-      }
-    ],
-    func: async (payload) => {
+        contentType: typeof params.contentType === 'string' ? params.contentType : undefined,
+        mode: params.mode === 'json' ? 'json' : 'raw',
+        maxBytes: typeof params.maxBytes === 'number' ? params.maxBytes : undefined,
+        timeoutMs: typeof params.timeoutMs === 'number' ? params.timeoutMs : undefined,
+        fullResponse: params.fullResponse === true,
+        auth: params.auth === 'manual' || params.auth === 'off' ? params.auth : 'auto'
+      }
+    ],
+    func: async (payload) => {
       const serializeValue = (value: unknown, maxBytes?: number) => {
         let cloned: unknown;
         try {
@@ -1071,10 +1150,10 @@ async function executePageWorld<T>(
         return current;
       };
 
-      const resolveExtractValue = (
-        targetWindow: Window & { eval: (expr: string) => unknown },
-        path: string,
-        resolver: unknown
+      const resolveExtractValue = (
+        targetWindow: Window & { eval: (expr: string) => unknown },
+        path: string,
+        resolver: unknown
       ): { resolver: 'globalThis' | 'lexical'; value: unknown } => {
         const strategy = resolver === 'globalThis' || resolver === 'lexical' ? resolver : 'auto';
         const lexicalExpression = buildPathExpression(path);
@@ -1101,11 +1180,82 @@ async function executePageWorld<T>(
             throw error;
           }
         }
-        return { resolver: 'lexical', value: readLexical() };
-      };
-
-      try {
-        const targetWindow = payload.scope === 'main' ? window : payload.scope === 'current' ? resolveFrameWindow(payload.framePath ?? []) : window;
+        return { resolver: 'lexical', value: readLexical() };
+      };
+
+      const findHeaderName = (headers: Record<string, string>, name: string): string | undefined =>
+        Object.keys(headers).find((key) => key.toLowerCase() === name.toLowerCase());
+
+      const findCookieValue = (cookieString: string, name: string): string | undefined => {
+        const targetName = `${name}=`;
+        for (const segment of cookieString.split(';')) {
+          const trimmed = segment.trim();
+          if (trimmed.toLowerCase().startsWith(targetName.toLowerCase())) {
+            return trimmed.slice(targetName.length);
+          }
+        }
+        return undefined;
+      };
+
+      const buildJsonSummary = (
+        value: unknown
+      ): { schema?: { columns: Array<{ key: string; label: string }> }; mappedRows?: Array<Record<string, unknown>> } => {
+        const rowsCandidate = (() => {
+          if (Array.isArray(value)) {
+            return value;
+          }
+          if (typeof value !== 'object' || value === null) {
+            return null;
+          }
+          const record = value as Record<string, unknown>;
+          for (const key of ['data', 'rows', 'results', 'items']) {
+            if (Array.isArray(record[key])) {
+              return record[key] as unknown[];
+            }
+          }
+          return null;
+        })();
+        if (Array.isArray(rowsCandidate) && rowsCandidate.length > 0) {
+          const objectRows = rowsCandidate
+            .filter((row): row is Record<string, unknown> => typeof row === 'object' && row !== null && !Array.isArray(row))
+            .slice(0, 25);
+          if (objectRows.length > 0) {
+            const columns = [...new Set(objectRows.flatMap((row) => Object.keys(row)))].slice(0, 20);
+            return {
+              schema: {
+                columns: columns.map((label, index) => ({
+                  key: `col_${index + 1}`,
+                  label
+                }))
+              },
+              mappedRows: objectRows.map((row) => {
+                const mapped: Record<string, unknown> = {};
+                for (const column of columns) {
+                  mapped[column] = row[column];
+                }
+                return mapped;
+              })
+            };
+          }
+        }
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+          const columns = Object.keys(value as Record<string, unknown>).slice(0, 20);
+          if (columns.length > 0) {
+            return {
+              schema: {
+                columns: columns.map((label, index) => ({
+                  key: `col_${index + 1}`,
+                  label
+                }))
+              }
+            };
+          }
+        }
+        return {};
+      };
+
+      try {
+        const targetWindow = payload.scope === 'main' ? window : payload.scope === 'current' ? resolveFrameWindow(payload.framePath ?? []) : window;
         if (payload.action === 'eval') {
           const evaluator = (targetWindow as Window & { eval: (expr: string) => unknown }).eval;
           const serialized = serializeValue(evaluator(payload.expr), payload.maxBytes);
@@ -1121,14 +1271,53 @@ async function executePageWorld<T>(
             bytes: serialized.bytes,
             resolver: extracted.resolver
           };
-        }
-        if (payload.action === 'fetch') {
-          const headers = { ...(payload.headers ?? {}) } as Record<string, string>;
-          if (payload.contentType && !headers['Content-Type']) {
-            headers['Content-Type'] = payload.contentType;
-          }
-          const controller = typeof AbortController === 'function' ? new AbortController() : null;
-          const timeoutId =
+        }
+        if (payload.action === 'fetch') {
+          const headers = { ...(payload.headers ?? {}) } as Record<string, string>;
+          if (payload.contentType && !findHeaderName(headers, 'Content-Type')) {
+            headers['Content-Type'] = payload.contentType;
+          }
+          const fullResponse = payload.fullResponse === true;
+          const authApplied: string[] = [];
+          const authSources = new Set<string>();
+          const requestUrl = new URL(payload.url, targetWindow.location.href);
+          const sameOrigin = requestUrl.origin === targetWindow.location.origin;
+          const authMode = payload.auth === 'manual' || payload.auth === 'off' ? payload.auth : 'auto';
+          const maybeApplyHeader = (name: string, value: string | undefined, source: string): void => {
+            if (!value || findHeaderName(headers, name)) {
+              return;
+            }
+            headers[name] = value;
+            authApplied.push(name);
+            authSources.add(source);
+          };
+          if (sameOrigin && authMode === 'auto') {
+            const xsrfCookie = findCookieValue(targetWindow.document.cookie ?? '', 'XSRF-TOKEN');
+            if (xsrfCookie) {
+              maybeApplyHeader('X-XSRF-TOKEN', decodeURIComponent(xsrfCookie), 'cookie:XSRF-TOKEN');
+            }
+            const metaTokens = [
+              {
+                selector: 'meta[name="xsrf-token"], meta[name="x-xsrf-token"]',
+                header: 'X-XSRF-TOKEN',
+                source: 'meta:xsrf-token'
+              },
+              {
+                selector: 'meta[name="csrf-token"], meta[name="csrf_token"], meta[name="_csrf"]',
+                header: 'X-CSRF-TOKEN',
+                source: 'meta:csrf-token'
+              }
+            ];
+            for (const token of metaTokens) {
+              const meta = targetWindow.document.querySelector<HTMLMetaElement>(token.selector);
+              const content = meta?.content?.trim();
+              if (content) {
+                maybeApplyHeader(token.header, content, token.source);
+              }
+            }
+          }
+          const controller = typeof AbortController === 'function' ? new AbortController() : null;
+          const timeoutId =
             controller && typeof payload.timeoutMs === 'number' && payload.timeoutMs > 0
               ? window.setTimeout(() => controller.abort(), payload.timeoutMs)
               : null;
@@ -1153,43 +1342,56 @@ async function executePageWorld<T>(
           return {
             url: targetWindow.location.href,
             framePath: payload.scope === 'current' ? payload.framePath ?? [] : [],
-            value: (() => {
-              const encoder = typeof TextEncoder === 'function' ? new TextEncoder() : null;
-              const decoder = typeof TextDecoder === 'function' ? new TextDecoder() : null;
-              const previewLimit = typeof payload.maxBytes === 'number' && payload.maxBytes > 0 ? payload.maxBytes : 8192;
-              const encodedBody = encoder ? encoder.encode(bodyText) : null;
-              const bodyBytes = encodedBody ? encodedBody.byteLength : bodyText.length;
-              const truncated = bodyBytes > previewLimit;
-              if (payload.mode === 'json' && truncated) {
-                throw {
-                  code: 'E_BODY_TOO_LARGE',
-                  message: 'JSON response exceeds max-bytes',
-                  details: {
-                    bytes: bodyBytes,
-                    maxBytes: previewLimit
-                  }
-                };
-              }
-              const previewText =
-                encodedBody && decoder
-                  ? decoder.decode(encodedBody.subarray(0, Math.min(encodedBody.byteLength, previewLimit)))
-                  : truncated
-                    ? bodyText.slice(0, previewLimit)
-                    : bodyText;
-              return {
-                url: response.url,
-                status: response.status,
-                ok: response.ok,
-                headers: headerMap,
-                contentType: response.headers.get('content-type') ?? undefined,
-                bodyText: payload.mode === 'json' ? undefined : previewText,
-                json: payload.mode === 'json' && bodyText ? JSON.parse(bodyText) : undefined,
-                bytes: bodyBytes,
-                truncated
-              };
-            })()
-          };
-        }
+            value: (() => {
+              const encoder = typeof TextEncoder === 'function' ? new TextEncoder() : null;
+              const decoder = typeof TextDecoder === 'function' ? new TextDecoder() : null;
+              const previewLimit = !fullResponse && typeof payload.maxBytes === 'number' && payload.maxBytes > 0 ? payload.maxBytes : 8192;
+              const encodedBody = encoder ? encoder.encode(bodyText) : null;
+              const bodyBytes = encodedBody ? encodedBody.byteLength : bodyText.length;
+              const truncated = !fullResponse && bodyBytes > previewLimit;
+              const previewText =
+                fullResponse
+                  ? bodyText
+                  : encodedBody && decoder
+                  ? decoder.decode(encodedBody.subarray(0, Math.min(encodedBody.byteLength, previewLimit)))
+                  : truncated
+                    ? bodyText.slice(0, previewLimit)
+                    : bodyText;
+              const result: Record<string, unknown> = {
+                url: response.url,
+                status: response.status,
+                ok: response.ok,
+                headers: headerMap,
+                contentType: response.headers.get('content-type') ?? undefined,
+                bytes: bodyBytes,
+                truncated,
+                authApplied: authApplied.length > 0 ? authApplied : undefined,
+                authSources: authSources.size > 0 ? [...authSources] : undefined
+              };
+              if (payload.mode === 'json') {
+                const parsedJson = bodyText ? JSON.parse(bodyText) : undefined;
+                const summary = buildJsonSummary(parsedJson);
+                if (fullResponse || !truncated) {
+                  result.json = parsedJson;
+                } else {
+                  result.degradedReason = 'response body exceeded max-bytes and was summarized';
+                }
+                if (summary.schema) {
+                  result.schema = summary.schema;
+                }
+                if (summary.mappedRows) {
+                  result.mappedRows = summary.mappedRows;
+                }
+              } else {
+                result.bodyText = previewText;
+                if (truncated) {
+                  result.degradedReason = 'response body exceeded max-bytes and was truncated';
+                }
+              }
+              return result;
+            })()
+          };
+        }
         throw { code: 'E_NOT_FOUND', message: `Unsupported page world action: ${payload.action}` };
       } catch (error) {
         return {
@@ -1269,23 +1471,20 @@ function filterNetworkEntrySections(entry: NetworkEntry, include: unknown): Netw
   return clone;
 }
 
-function replayHeadersFromEntry(entry: NetworkEntry): Record<string, string> | undefined {
-  if (!entry.requestHeaders) {
-    return undefined;
-  }
-  const headers: Record<string, string> = {};
-  for (const [name, value] of Object.entries(entry.requestHeaders)) {
-    const normalizedName = name.toLowerCase();
-    if (REPLAY_FORBIDDEN_HEADER_NAMES.has(normalizedName) || normalizedName.startsWith('sec-')) {
-      continue;
-    }
-    if (containsRedactionMarker(value)) {
-      continue;
-    }
-    headers[name] = value;
-  }
-  return Object.keys(headers).length > 0 ? headers : undefined;
-}
+function replayHeadersFromRequestHeaders(requestHeaders: Record<string, string> | undefined): Record<string, string> | undefined {
+  if (!requestHeaders) {
+    return undefined;
+  }
+  const headers: Record<string, string> = {};
+  for (const [name, value] of Object.entries(requestHeaders)) {
+    const normalizedName = name.toLowerCase();
+    if (REPLAY_FORBIDDEN_HEADER_NAMES.has(normalizedName) || normalizedName.startsWith('sec-')) {
+      continue;
+    }
+    headers[name] = value;
+  }
+  return Object.keys(headers).length > 0 ? headers : undefined;
+}
 
 function collectTimestampMatchesFromText(text: string, source: TimestampEvidenceCandidate['source'], patterns?: string[]): TimestampEvidenceCandidate[] {
   const regexes = (
@@ -1403,7 +1602,7 @@ function latestTimestampFromCandidates(
   return latest;
 }
 
-function computeFreshnessAssessment(input: {
+function computeFreshnessAssessment(input: {
   latestInlineDataTimestamp: number | null;
   latestPageDataTimestamp: number | null;
   latestNetworkDataTimestamp: number | null;
@@ -1440,10 +1639,79 @@ function computeFreshnessAssessment(input: {
     .filter((value): value is number => typeof value === 'number');
   if (staleSignals.length > 0 && staleSignals.every((value) => now - value > input.staleWindowMs)) {
     return 'stale';
-  }
-  return 'unknown';
-}
-
+  }
+  return 'unknown';
+}
+
+function freshnessCategoryPriority(category: PageFreshnessResult['evidence']['classifiedTimestamps'][number]['category']): number {
+  switch (category) {
+    case 'data':
+      return 0;
+    case 'unknown':
+      return 1;
+    case 'event':
+      return 2;
+    case 'contract':
+      return 3;
+    default:
+      return 4;
+  }
+}
+
+function freshnessSourcePriority(source: PageFreshnessResult['evidence']['classifiedTimestamps'][number]['source']): number {
+  switch (source) {
+    case 'network':
+      return 0;
+    case 'page-data':
+      return 1;
+    case 'visible':
+      return 2;
+    case 'inline':
+      return 3;
+    default:
+      return 4;
+  }
+}
+
+function rankFreshnessEvidence(
+  candidates: PageFreshnessResult['evidence']['classifiedTimestamps'],
+  now = Date.now()
+): PageFreshnessResult['evidence']['classifiedTimestamps'] {
+  return candidates
+    .slice()
+    .sort((left, right) => {
+      const byCategory = freshnessCategoryPriority(left.category) - freshnessCategoryPriority(right.category);
+      if (byCategory !== 0) {
+        return byCategory;
+      }
+      const bySource = freshnessSourcePriority(left.source) - freshnessSourcePriority(right.source);
+      if (bySource !== 0) {
+        return bySource;
+      }
+      const leftTimestamp = parseTimestampCandidate(left.value, now) ?? Number.NEGATIVE_INFINITY;
+      const rightTimestamp = parseTimestampCandidate(right.value, now) ?? Number.NEGATIVE_INFINITY;
+      if (leftTimestamp !== rightTimestamp) {
+        return rightTimestamp - leftTimestamp;
+      }
+      return left.value.localeCompare(right.value);
+    });
+}
+
+function deriveFreshnessConfidence(
+  primary: PageFreshnessResult['evidence']['classifiedTimestamps'][number] | null
+): PageFreshnessResult['confidence'] {
+  if (!primary) {
+    return 'low';
+  }
+  if (primary.category === 'data' && (primary.source === 'network' || primary.source === 'page-data')) {
+    return 'high';
+  }
+  if (primary.category === 'data') {
+    return 'medium';
+  }
+  return 'low';
+}
+
 async function collectPageInspection(tabId: number, params: Record<string, unknown> = {}): Promise<PageInspectionState> {
   return (await forwardContentRpc(tabId, 'bak.internal.inspectState', params)) as PageInspectionState;
 }
@@ -1589,24 +1857,32 @@ async function buildFreshnessForTab(tabId: number, params: Record<string, unknow
     now
   );
   const latestInlineDataTimestamp = latestTimestampFromCandidates(inlineCandidates, now);
-  const latestPageDataTimestamp = latestTimestampFromCandidates(pageDataCandidates, now);
-  const latestNetworkDataTimestamp = latestTimestampFromCandidates(networkCandidates, now);
-  const domVisibleTimestamp = latestTimestampFromCandidates(visibleCandidates, now);
-  const latestNetworkTs = latestNetworkTimestamp(tabId);
-  const lastMutationAt = typeof inspection.lastMutationAt === 'number' ? inspection.lastMutationAt : null;
-  const allCandidates = [...visibleCandidates, ...inlineCandidates, ...pageDataCandidates, ...networkCandidates];
-  return {
-    pageLoadedAt: typeof inspection.pageLoadedAt === 'number' ? inspection.pageLoadedAt : null,
-    lastMutationAt,
-    latestNetworkTimestamp: latestNetworkTs,
-    latestInlineDataTimestamp,
-    latestPageDataTimestamp,
-    latestNetworkDataTimestamp,
-    domVisibleTimestamp,
-    assessment: computeFreshnessAssessment({
-      latestInlineDataTimestamp,
-      latestPageDataTimestamp,
-      latestNetworkDataTimestamp,
+  const latestPageDataTimestamp = latestTimestampFromCandidates(pageDataCandidates, now);
+  const latestNetworkDataTimestamp = latestTimestampFromCandidates(networkCandidates, now);
+  const domVisibleTimestamp = latestTimestampFromCandidates(visibleCandidates, now);
+  const latestNetworkTs = latestNetworkTimestamp(tabId);
+  const lastMutationAt = typeof inspection.lastMutationAt === 'number' ? inspection.lastMutationAt : null;
+  const allCandidates = rankFreshnessEvidence([...visibleCandidates, ...inlineCandidates, ...pageDataCandidates, ...networkCandidates], now);
+  const primaryEvidence =
+    allCandidates.find((candidate) => parseTimestampCandidate(candidate.value, now) !== null) ?? null;
+  const primaryTimestamp = primaryEvidence ? parseTimestampCandidate(primaryEvidence.value, now) : null;
+  return {
+    pageLoadedAt: typeof inspection.pageLoadedAt === 'number' ? inspection.pageLoadedAt : null,
+    lastMutationAt,
+    latestNetworkTimestamp: latestNetworkTs,
+    latestInlineDataTimestamp,
+    latestPageDataTimestamp,
+    latestNetworkDataTimestamp,
+    domVisibleTimestamp,
+    primaryTimestamp,
+    primaryCategory: primaryEvidence?.category ?? null,
+    primarySource: primaryEvidence?.source ?? null,
+    confidence: deriveFreshnessConfidence(primaryEvidence),
+    suppressedEvidenceCount: Math.max(0, allCandidates.length - (primaryEvidence ? 1 : 0)),
+    assessment: computeFreshnessAssessment({
+      latestInlineDataTimestamp,
+      latestPageDataTimestamp,
+      latestNetworkDataTimestamp,
       latestNetworkTimestamp: latestNetworkTs,
       domVisibleTimestamp,
       lastMutationAt,
@@ -1615,10 +1891,10 @@ async function buildFreshnessForTab(tabId: number, params: Record<string, unknow
     }),
     evidence: {
       visibleTimestamps: visibleCandidates.map((candidate) => candidate.value),
-      inlineTimestamps: inlineCandidates.map((candidate) => candidate.value),
-      pageDataTimestamps: pageDataCandidates.map((candidate) => candidate.value),
-      networkDataTimestamps: networkCandidates.map((candidate) => candidate.value),
-      classifiedTimestamps: allCandidates,
+      inlineTimestamps: inlineCandidates.map((candidate) => candidate.value),
+      pageDataTimestamps: pageDataCandidates.map((candidate) => candidate.value),
+      networkDataTimestamps: networkCandidates.map((candidate) => candidate.value),
+      classifiedTimestamps: allCandidates,
       networkSampleIds: recentNetworkSampleIds(tabId)
     }
   };
@@ -2051,32 +2327,37 @@ async function handleRequest(request: CliRequest): Promise<unknown> {
         return await executePageWorld(tab.id!, 'extract', params);
       });
     }
-    case 'page.fetch': {
-      return await preserveHumanFocus(typeof target.tabId !== 'number', async () => {
-        const tab = await withTab(target);
-        return await executePageWorld<PageFetchResponse>(tab.id!, 'fetch', params);
-      });
-    }
-    case 'page.snapshot': {
-      return await preserveHumanFocus(typeof target.tabId !== 'number', async () => {
-        const tab = await withTab(target);
-        if (typeof tab.id !== 'number' || typeof tab.windowId !== 'number') {
-          throw toError('E_NOT_FOUND', 'Tab missing id');
-        }
-        const includeBase64 = params.includeBase64 !== false;
-        const config = await getConfig();
-        const elements = await sendToContent<{ elements: unknown[] }>(tab.id, {
-          type: 'bak.collectElements',
-          debugRichText: config.debugRichText
-        });
-        const imageData = await captureAlignedTabScreenshot(tab);
-        return {
-          imageBase64: includeBase64 ? imageData.replace(/^data:image\/png;base64,/, '') : '',
-          elements: elements.elements,
-          tabId: tab.id,
-          url: tab.url ?? ''
-        };
-      });
+    case 'page.fetch': {
+      return await preserveHumanFocus(typeof target.tabId !== 'number', async () => {
+        const tab = await withTab(target);
+        return await executePageWorld<PageFetchResponse>(tab.id!, 'fetch', params);
+      });
+    }
+    case 'page.snapshot': {
+      return await preserveHumanFocus(typeof target.tabId !== 'number', async () => {
+        const tab = await withTab(target);
+        if (typeof tab.id !== 'number' || typeof tab.windowId !== 'number') {
+          throw toError('E_NOT_FOUND', 'Tab missing id');
+        }
+        const includeBase64 = params.includeBase64 !== false;
+        const config = await getConfig();
+        const elements = await sendToContent<{ elements: unknown[] }>(tab.id, {
+          type: 'bak.collectElements',
+          debugRichText: config.debugRichText
+        });
+        const screenshot = params.capture === false ? { captureStatus: 'skipped' as const } : await captureAlignedTabScreenshot(tab);
+        return {
+          captureStatus: screenshot.captureStatus,
+          captureError: screenshot.captureError,
+          imageBase64:
+            includeBase64 && typeof screenshot.imageData === 'string'
+              ? screenshot.imageData.replace(/^data:image\/png;base64,/, '')
+              : undefined,
+          elements: elements.elements,
+          tabId: tab.id,
+          url: tab.url ?? ''
+        };
+      });
     }
     case 'element.click': {
       return await preserveHumanFocus(typeof target.tabId !== 'number', async () => {
@@ -2191,19 +2472,13 @@ async function handleRequest(request: CliRequest): Promise<unknown> {
         }
       });
     }
-    case 'network.search': {
-      return await preserveHumanFocus(typeof target.tabId !== 'number', async () => {
-        const tab = await withTab(target);
-        await ensureTabNetworkCapture(tab.id!);
-        return {
-          entries: searchNetworkEntries(
-            tab.id!,
-            String(params.pattern ?? ''),
-            typeof params.limit === 'number' ? params.limit : 50
-          )
-        };
-      });
-    }
+    case 'network.search': {
+      return await preserveHumanFocus(typeof target.tabId !== 'number', async () => {
+        const tab = await withTab(target);
+        await ensureTabNetworkCapture(tab.id!);
+        return searchNetworkEntries(tab.id!, String(params.pattern ?? ''), typeof params.limit === 'number' ? params.limit : 50);
+      });
+    }
     case 'network.waitFor': {
       return await preserveHumanFocus(typeof target.tabId !== 'number', async () => {
         const tab = await withTab(target);
@@ -2231,48 +2506,52 @@ async function handleRequest(request: CliRequest): Promise<unknown> {
         return { ok: true };
       });
     }
-    case 'network.replay': {
-      return await preserveHumanFocus(typeof target.tabId !== 'number', async () => {
-        const tab = await withTab(target);
-        await ensureTabNetworkCapture(tab.id!);
-        const entry = getNetworkEntry(tab.id!, String(params.id ?? ''));
-        if (!entry) {
-          throw toError('E_NOT_FOUND', `network entry not found: ${String(params.id ?? '')}`);
-        }
-        if (entry.requestBodyTruncated === true) {
-          throw toError('E_BODY_TOO_LARGE', 'captured request body was truncated and cannot be replayed safely', {
-            requestId: entry.id,
-            requestBytes: entry.requestBytes
-          });
-        }
-        if (containsRedactionMarker(entry.requestBodyPreview)) {
-          throw toError('E_EXECUTION', 'captured request body was redacted and cannot be replayed safely', {
-            requestId: entry.id
-          });
-        }
-        const replayed = await executePageWorld<PageFetchResponse>(tab.id!, 'fetch', {
-          url: entry.url,
-          method: entry.method,
-          headers: replayHeadersFromEntry(entry),
-          body: entry.requestBodyPreview,
-          contentType: (() => {
-            const requestHeaders = entry.requestHeaders ?? {};
-            const contentTypeHeader = Object.keys(requestHeaders).find((name) => name.toLowerCase() === 'content-type');
-            return contentTypeHeader ? requestHeaders[contentTypeHeader] : undefined;
-          })(),
-          mode: params.mode,
-          timeoutMs: params.timeoutMs,
-          maxBytes: params.maxBytes,
-          scope: 'current'
-        });
-        const frameResult = replayed.result ?? replayed.results?.find((candidate) => candidate.value || candidate.error);
-        if (frameResult?.error) {
-          throw toError(frameResult.error.code ?? 'E_EXECUTION', frameResult.error.message, frameResult.error.details);
-        }
-        const first = frameResult?.value;
-        if (!first) {
-          throw toError('E_EXECUTION', 'network replay returned no response payload');
-        }
+    case 'network.replay': {
+      return await preserveHumanFocus(typeof target.tabId !== 'number', async () => {
+        const tab = await withTab(target);
+        await ensureTabNetworkCapture(tab.id!);
+        const replayable = getReplayableNetworkRequest(tab.id!, String(params.id ?? ''));
+        if (!replayable) {
+          throw toError('E_NOT_FOUND', `network entry not found: ${String(params.id ?? '')}`);
+        }
+        if (replayable.degradedReason) {
+          return {
+            url: replayable.entry.url,
+            status: 0,
+            ok: false,
+            headers: {},
+            bytes: replayable.entry.requestBytes,
+            truncated: true,
+            degradedReason: replayable.degradedReason
+          } satisfies PageFetchResponse;
+        }
+        const replayed = await executePageWorld<PageFetchResponse>(tab.id!, 'fetch', {
+          url: replayable.entry.url,
+          method: replayable.entry.method,
+          headers: replayHeadersFromRequestHeaders(replayable.headers),
+          body: replayable.body,
+          contentType: replayable.contentType,
+          mode: params.mode,
+          timeoutMs: params.timeoutMs,
+          maxBytes: params.maxBytes,
+          fullResponse: params.fullResponse === true,
+          auth: params.auth,
+          scope: 'current'
+        });
+        const frameResult = replayed.result ?? replayed.results?.find((candidate) => candidate.value || candidate.error);
+        if (frameResult?.error) {
+          throw toError(frameResult.error.code ?? 'E_EXECUTION', frameResult.error.message, frameResult.error.details);
+        }
+        const first = frameResult?.value;
+        if (!first) {
+          return {
+            url: replayable.entry.url,
+            status: 0,
+            ok: false,
+            headers: {},
+            degradedReason: 'network replay returned no response payload'
+          } satisfies PageFetchResponse;
+        }
         return params.withSchema === 'auto' && params.mode === 'json'
           ? await enrichReplayWithSchema(tab.id!, String(params.id ?? ''), first)
           : first;