browserclaw 0.11.6 → 0.12.1

package/dist/index.d.cts

@@ -628,6 +628,72 @@ interface ChallengeWaitResult {
     /** The challenge still present (null if resolved) */
     challenge: ChallengeInfo | null;
 }
+/**
+ * A single rule for checking whether the browser session is authenticated.
+ * Multiple rules can be combined — all must pass for `authenticated: true`.
+ */
+interface AuthCheckRule {
+    /** URL must contain this substring (checked against page URL) */
+    url?: string;
+    /** A cookie with this name must exist (non-empty value) */
+    cookie?: string;
+    /** A CSS selector that must match at least one element on the page (includes hidden elements) */
+    selector?: string;
+    /** Text that must be present on the page */
+    text?: string;
+    /** Text that must NOT be present on the page (e.g. "Sign in", "Log in") */
+    textGone?: string;
+    /** JavaScript function (as string) that must return a truthy value in the browser context */
+    fn?: string;
+}
+/** The kind of auth check rule that was evaluated. */
+type AuthCheckRuleKind = 'url' | 'cookie' | 'selector' | 'text' | 'textGone' | 'fn';
+/** Result of a single auth check rule evaluation. */
+interface AuthCheckDetail {
+    /** Which rule type was checked */
+    rule: AuthCheckRuleKind;
+    /** Whether this individual check passed */
+    passed: boolean;
+    /** Human-readable detail (e.g. the actual URL, cookie value presence, etc.) */
+    detail?: string;
+}
+/** Result of an `isAuthenticated()` call. */
+interface AuthCheckResult {
+    /** `true` only if ALL rules passed */
+    authenticated: boolean;
+    /** Per-rule results for debugging */
+    checks: AuthCheckDetail[];
+}
+/** Standard exit reasons for structured telemetry. */
+type ExitReason = 'success' | 'auth_failed' | 'nav_failed' | 'timeout' | 'crash' | 'disconnected' | 'manual' | 'error';
+/** Structured telemetry envelope for a browser session lifecycle. */
+interface RunTelemetry {
+    /** Milliseconds to launch Chrome (undefined if connected to existing instance) */
+    launchMs?: number;
+    /** Milliseconds to establish CDP connection */
+    connectMs?: number;
+    /** Milliseconds for initial navigation (if a URL was provided at launch) */
+    navMs?: number;
+    /** Whether auth verification passed (undefined if not checked) */
+    authOk?: boolean;
+    /** Structured exit reason when the session ends */
+    exitReason?: ExitReason | (string & {});
+    /** Whether cleanup (process kill, connection close) succeeded */
+    cleanupOk?: boolean;
+    /** Key timestamps in ISO 8601 format */
+    timestamps: {
+        /** When the launch/connect sequence started */
+        startedAt: string;
+        /** When Chrome process became reachable */
+        launchedAt?: string;
+        /** When Playwright CDP connection was established */
+        connectedAt?: string;
+        /** When initial navigation completed */
+        navigatedAt?: string;
+        /** When stop() was called */
+        stoppedAt?: string;
+    };
+}
 /** Result of DNS pinning resolution — hostname locked to resolved addresses. */
 interface PinnedHostname {
     hostname: string;
@@ -1443,6 +1509,36 @@ declare class CrawlPage {
         timeoutMs?: number;
         pollMs?: number;
     }): Promise<ChallengeWaitResult>;
+    /**
+     * Check whether the current page session appears authenticated.
+     *
+     * Evaluates one or more rules against the page state. All rules must pass
+     * for `authenticated` to be `true`. Returns per-rule details for debugging.
+     *
+     * @param rules - Array of auth check rules (url, cookie, selector, text, textGone, fn)
+     * @returns Authentication status and per-rule check details
+     *
+     * @example
+     * ```ts
+     * // Check by URL and absence of login text
+     * const result = await page.isAuthenticated([
+     *   { url: '/dashboard' },
+     *   { textGone: 'Sign in' },
+     * ]);
+     * if (!result.authenticated) {
+     *   console.log('Auth failed:', result.checks.filter(c => !c.passed));
+     * }
+     *
+     * // Check by cookie presence
+     * const result = await page.isAuthenticated([{ cookie: 'session_id' }]);
+     *
+     * // Check with custom JS function
+     * const result = await page.isAuthenticated([
+     *   { fn: '() => !!document.querySelector("[data-user-id]")' },
+     * ]);
+     * ```
+     */
+    isAuthenticated(rules: AuthCheckRule[]): Promise<AuthCheckResult>;
     /**
      * Get the underlying Playwright `Page` object for this tab.
      *
@@ -1516,6 +1612,7 @@ declare class BrowserClaw {
     private readonly ssrfPolicy;
     private readonly recordVideo;
     private chrome;
+    private readonly _telemetry;
     private constructor();
     /**
      * Launch a new Chrome instance and connect to it.
@@ -1631,8 +1728,42 @@ declare class BrowserClaw {
      * If the browser was launched by `BrowserClaw.launch()`, the Chrome process
      * will be terminated. If connected via `BrowserClaw.connect()`, only the
      * Playwright connection is closed.
+     *
+     * @param exitReason - Optional structured reason for stopping (e.g. `'success'`, `'auth_failed'`, `'timeout'`)
+     */
+    stop(exitReason?: ExitReason | (string & {})): Promise<void>;
+    /**
+     * Get structured telemetry for this browser session.
+     *
+     * Returns timing data, timestamps, and exit information collected
+     * throughout the session lifecycle. Useful for diagnosing startup
+     * latency, auth failures, and cleanup issues in cron/unattended runs.
+     *
+     * @returns Telemetry envelope with launch/connect/nav timings and exit info
+     *
+     * @example
+     * ```ts
+     * const browser = await BrowserClaw.launch({ url: 'https://example.com' });
+     * const page = await browser.currentPage();
+     *
+     * // ... do work ...
+     *
+     * const auth = await page.isAuthenticated([{ cookie: 'session' }]);
+     * browser.recordAuthResult(auth.authenticated);
+     *
+     * await browser.stop(auth.authenticated ? 'success' : 'auth_failed');
+     * console.log(browser.telemetry());
+     * // { launchMs: 1823, connectMs: 45, navMs: 620, authOk: true,
+     * //   exitReason: 'success', cleanupOk: true, timestamps: { ... } }
+     * ```
+     */
+    telemetry(): Readonly<RunTelemetry>;
+    /**
+     * Record the result of an authentication check in the telemetry envelope.
+     *
+     * @param ok - Whether authentication was successful
      */
-    stop(): Promise<void>;
+    recordAuthResult(ok: boolean): void;
 }
 
 /**
@@ -1890,4 +2021,4 @@ declare function waitForChallengeViaPlaywright(opts: {
     pollMs?: number;
 }): Promise<ChallengeWaitResult>;
 
-export { type AriaNode, type AriaSnapshotResult, type BatchAction, type BatchActionResult, BlockedBrowserTargetError, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, BrowserTabNotFoundError, type ChallengeInfo, type ChallengeKind, type ChallengeWaitResult, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogEvent, type DialogHandler, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type RequestResult, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, STEALTH_SCRIPT, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, detectChallengeViaPlaywright, ensureContextState, executeSingleAction, forceDisconnectPlaywrightConnection, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, pressAndHoldViaCdp, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingPathsWithinRoot, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, setDialogHandler, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };
+export { type AriaNode, type AriaSnapshotResult, type AuthCheckDetail, type AuthCheckResult, type AuthCheckRule, type AuthCheckRuleKind, type BatchAction, type BatchActionResult, BlockedBrowserTargetError, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, BrowserTabNotFoundError, type ChallengeInfo, type ChallengeKind, type ChallengeWaitResult, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogEvent, type DialogHandler, type DialogOptions, type DownloadResult, type ExitReason, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type RequestResult, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type RunTelemetry, STEALTH_SCRIPT, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, detectChallengeViaPlaywright, ensureContextState, executeSingleAction, forceDisconnectPlaywrightConnection, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, pressAndHoldViaCdp, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingPathsWithinRoot, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, setDialogHandler, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };

package/dist/index.d.ts

@@ -628,6 +628,72 @@ interface ChallengeWaitResult {
     /** The challenge still present (null if resolved) */
     challenge: ChallengeInfo | null;
 }
+/**
+ * A single rule for checking whether the browser session is authenticated.
+ * Multiple rules can be combined — all must pass for `authenticated: true`.
+ */
+interface AuthCheckRule {
+    /** URL must contain this substring (checked against page URL) */
+    url?: string;
+    /** A cookie with this name must exist (non-empty value) */
+    cookie?: string;
+    /** A CSS selector that must match at least one element on the page (includes hidden elements) */
+    selector?: string;
+    /** Text that must be present on the page */
+    text?: string;
+    /** Text that must NOT be present on the page (e.g. "Sign in", "Log in") */
+    textGone?: string;
+    /** JavaScript function (as string) that must return a truthy value in the browser context */
+    fn?: string;
+}
+/** The kind of auth check rule that was evaluated. */
+type AuthCheckRuleKind = 'url' | 'cookie' | 'selector' | 'text' | 'textGone' | 'fn';
+/** Result of a single auth check rule evaluation. */
+interface AuthCheckDetail {
+    /** Which rule type was checked */
+    rule: AuthCheckRuleKind;
+    /** Whether this individual check passed */
+    passed: boolean;
+    /** Human-readable detail (e.g. the actual URL, cookie value presence, etc.) */
+    detail?: string;
+}
+/** Result of an `isAuthenticated()` call. */
+interface AuthCheckResult {
+    /** `true` only if ALL rules passed */
+    authenticated: boolean;
+    /** Per-rule results for debugging */
+    checks: AuthCheckDetail[];
+}
+/** Standard exit reasons for structured telemetry. */
+type ExitReason = 'success' | 'auth_failed' | 'nav_failed' | 'timeout' | 'crash' | 'disconnected' | 'manual' | 'error';
+/** Structured telemetry envelope for a browser session lifecycle. */
+interface RunTelemetry {
+    /** Milliseconds to launch Chrome (undefined if connected to existing instance) */
+    launchMs?: number;
+    /** Milliseconds to establish CDP connection */
+    connectMs?: number;
+    /** Milliseconds for initial navigation (if a URL was provided at launch) */
+    navMs?: number;
+    /** Whether auth verification passed (undefined if not checked) */
+    authOk?: boolean;
+    /** Structured exit reason when the session ends */
+    exitReason?: ExitReason | (string & {});
+    /** Whether cleanup (process kill, connection close) succeeded */
+    cleanupOk?: boolean;
+    /** Key timestamps in ISO 8601 format */
+    timestamps: {
+        /** When the launch/connect sequence started */
+        startedAt: string;
+        /** When Chrome process became reachable */
+        launchedAt?: string;
+        /** When Playwright CDP connection was established */
+        connectedAt?: string;
+        /** When initial navigation completed */
+        navigatedAt?: string;
+        /** When stop() was called */
+        stoppedAt?: string;
+    };
+}
 /** Result of DNS pinning resolution — hostname locked to resolved addresses. */
 interface PinnedHostname {
     hostname: string;
@@ -1443,6 +1509,36 @@ declare class CrawlPage {
         timeoutMs?: number;
         pollMs?: number;
     }): Promise<ChallengeWaitResult>;
+    /**
+     * Check whether the current page session appears authenticated.
+     *
+     * Evaluates one or more rules against the page state. All rules must pass
+     * for `authenticated` to be `true`. Returns per-rule details for debugging.
+     *
+     * @param rules - Array of auth check rules (url, cookie, selector, text, textGone, fn)
+     * @returns Authentication status and per-rule check details
+     *
+     * @example
+     * ```ts
+     * // Check by URL and absence of login text
+     * const result = await page.isAuthenticated([
+     *   { url: '/dashboard' },
+     *   { textGone: 'Sign in' },
+     * ]);
+     * if (!result.authenticated) {
+     *   console.log('Auth failed:', result.checks.filter(c => !c.passed));
+     * }
+     *
+     * // Check by cookie presence
+     * const result = await page.isAuthenticated([{ cookie: 'session_id' }]);
+     *
+     * // Check with custom JS function
+     * const result = await page.isAuthenticated([
+     *   { fn: '() => !!document.querySelector("[data-user-id]")' },
+     * ]);
+     * ```
+     */
+    isAuthenticated(rules: AuthCheckRule[]): Promise<AuthCheckResult>;
     /**
      * Get the underlying Playwright `Page` object for this tab.
      *
@@ -1516,6 +1612,7 @@ declare class BrowserClaw {
     private readonly ssrfPolicy;
     private readonly recordVideo;
     private chrome;
+    private readonly _telemetry;
     private constructor();
     /**
      * Launch a new Chrome instance and connect to it.
@@ -1631,8 +1728,42 @@ declare class BrowserClaw {
      * If the browser was launched by `BrowserClaw.launch()`, the Chrome process
      * will be terminated. If connected via `BrowserClaw.connect()`, only the
      * Playwright connection is closed.
+     *
+     * @param exitReason - Optional structured reason for stopping (e.g. `'success'`, `'auth_failed'`, `'timeout'`)
+     */
+    stop(exitReason?: ExitReason | (string & {})): Promise<void>;
+    /**
+     * Get structured telemetry for this browser session.
+     *
+     * Returns timing data, timestamps, and exit information collected
+     * throughout the session lifecycle. Useful for diagnosing startup
+     * latency, auth failures, and cleanup issues in cron/unattended runs.
+     *
+     * @returns Telemetry envelope with launch/connect/nav timings and exit info
+     *
+     * @example
+     * ```ts
+     * const browser = await BrowserClaw.launch({ url: 'https://example.com' });
+     * const page = await browser.currentPage();
+     *
+     * // ... do work ...
+     *
+     * const auth = await page.isAuthenticated([{ cookie: 'session' }]);
+     * browser.recordAuthResult(auth.authenticated);
+     *
+     * await browser.stop(auth.authenticated ? 'success' : 'auth_failed');
+     * console.log(browser.telemetry());
+     * // { launchMs: 1823, connectMs: 45, navMs: 620, authOk: true,
+     * //   exitReason: 'success', cleanupOk: true, timestamps: { ... } }
+     * ```
+     */
+    telemetry(): Readonly<RunTelemetry>;
+    /**
+     * Record the result of an authentication check in the telemetry envelope.
+     *
+     * @param ok - Whether authentication was successful
      */
-    stop(): Promise<void>;
+    recordAuthResult(ok: boolean): void;
 }
 
 /**
@@ -1890,4 +2021,4 @@ declare function waitForChallengeViaPlaywright(opts: {
     pollMs?: number;
 }): Promise<ChallengeWaitResult>;
 
-export { type AriaNode, type AriaSnapshotResult, type BatchAction, type BatchActionResult, BlockedBrowserTargetError, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, BrowserTabNotFoundError, type ChallengeInfo, type ChallengeKind, type ChallengeWaitResult, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogEvent, type DialogHandler, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type RequestResult, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, STEALTH_SCRIPT, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, detectChallengeViaPlaywright, ensureContextState, executeSingleAction, forceDisconnectPlaywrightConnection, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, pressAndHoldViaCdp, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingPathsWithinRoot, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, setDialogHandler, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };
+export { type AriaNode, type AriaSnapshotResult, type AuthCheckDetail, type AuthCheckResult, type AuthCheckRule, type AuthCheckRuleKind, type BatchAction, type BatchActionResult, BlockedBrowserTargetError, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, BrowserTabNotFoundError, type ChallengeInfo, type ChallengeKind, type ChallengeWaitResult, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogEvent, type DialogHandler, type DialogOptions, type DownloadResult, type ExitReason, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type RequestResult, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type RunTelemetry, STEALTH_SCRIPT, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, detectChallengeViaPlaywright, ensureContextState, executeSingleAction, forceDisconnectPlaywrightConnection, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, pressAndHoldViaCdp, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingPathsWithinRoot, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, setDialogHandler, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };

package/dist/index.js

@@ -1562,6 +1562,7 @@ ${stderrOutput.slice(0, 2e3)}` : "";
     userDataDir,
     cdpPort,
     startedAt,
+    launchMs: Date.now() - startedAt,
     proc
   };
 }
@@ -6316,6 +6317,137 @@ var CrawlPage = class {
       pollMs: opts?.pollMs
     });
   }
+  // ── Auth Health ──────────────────────────────────────────────
+  /**
+   * Check whether the current page session appears authenticated.
+   *
+   * Evaluates one or more rules against the page state. All rules must pass
+   * for `authenticated` to be `true`. Returns per-rule details for debugging.
+   *
+   * @param rules - Array of auth check rules (url, cookie, selector, text, textGone, fn)
+   * @returns Authentication status and per-rule check details
+   *
+   * @example
+   * ```ts
+   * // Check by URL and absence of login text
+   * const result = await page.isAuthenticated([
+   *   { url: '/dashboard' },
+   *   { textGone: 'Sign in' },
+   * ]);
+   * if (!result.authenticated) {
+   *   console.log('Auth failed:', result.checks.filter(c => !c.passed));
+   * }
+   *
+   * // Check by cookie presence
+   * const result = await page.isAuthenticated([{ cookie: 'session_id' }]);
+   *
+   * // Check with custom JS function
+   * const result = await page.isAuthenticated([
+   *   { fn: '() => !!document.querySelector("[data-user-id]")' },
+   * ]);
+   * ```
+   */
+  async isAuthenticated(rules) {
+    if (!rules.length) return { authenticated: true, checks: [] };
+    const page = await getRestoredPageForTarget({ cdpUrl: this.cdpUrl, targetId: this.targetId });
+    const checks = [];
+    for (const rule of rules) {
+      if (rule.url !== void 0) {
+        const currentUrl = page.url();
+        const passed = currentUrl.includes(rule.url);
+        checks.push({ rule: "url", passed, detail: passed ? currentUrl : `expected "${rule.url}" in "${currentUrl}"` });
+      }
+      if (rule.cookie !== void 0) {
+        const cookies = await page.context().cookies();
+        const found = cookies.some((c) => c.name === rule.cookie && c.value !== "");
+        checks.push({
+          rule: "cookie",
+          passed: found,
+          detail: found ? `cookie "${rule.cookie}" present` : `cookie "${rule.cookie}" missing or empty`
+        });
+      }
+      if (rule.selector !== void 0) {
+        try {
+          const count = await page.locator(rule.selector).count();
+          const passed = count > 0;
+          checks.push({
+            rule: "selector",
+            passed,
+            detail: passed ? `"${rule.selector}" found (${String(count)})` : `"${rule.selector}" not found`
+          });
+        } catch (err) {
+          console.warn(
+            `[browserclaw] isAuthenticated selector check failed: ${err instanceof Error ? err.message : String(err)}`
+          );
+          checks.push({ rule: "selector", passed: false, detail: `"${rule.selector}" error during evaluation` });
+        }
+      }
+      if (rule.text !== void 0 || rule.textGone !== void 0) {
+        let bodyText = null;
+        try {
+          const raw = await evaluateViaPlaywright({
+            cdpUrl: this.cdpUrl,
+            targetId: this.targetId,
+            fn: '() => { const b = document.body; return b ? b.innerText : ""; }'
+          });
+          bodyText = typeof raw === "string" ? raw : null;
+        } catch (err) {
+          console.warn(
+            `[browserclaw] isAuthenticated body text fetch failed: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+        if (rule.text !== void 0) {
+          if (bodyText === null) {
+            checks.push({ rule: "text", passed: false, detail: `"${rule.text}" error during evaluation` });
+          } else {
+            const passed = bodyText.includes(rule.text);
+            checks.push({
+              rule: "text",
+              passed,
+              detail: passed ? `"${rule.text}" found` : `"${rule.text}" not found in page text`
+            });
+          }
+        }
+        if (rule.textGone !== void 0) {
+          if (bodyText === null) {
+            checks.push({ rule: "textGone", passed: false, detail: `"${rule.textGone}" error during evaluation` });
+          } else {
+            const passed = !bodyText.includes(rule.textGone);
+            checks.push({
+              rule: "textGone",
+              passed,
+              detail: passed ? `"${rule.textGone}" absent (good)` : `"${rule.textGone}" still present`
+            });
+          }
+        }
+      }
+      if (rule.fn !== void 0) {
+        try {
+          const result = await evaluateViaPlaywright({
+            cdpUrl: this.cdpUrl,
+            targetId: this.targetId,
+            fn: rule.fn
+          });
+          const passed = result !== null && result !== void 0 && result !== false && result !== 0 && result !== "";
+          checks.push({
+            rule: "fn",
+            passed,
+            detail: passed ? "function returned truthy" : `function returned ${JSON.stringify(result)}`
+          });
+        } catch (err) {
+          checks.push({
+            rule: "fn",
+            passed: false,
+            detail: `function threw: ${err instanceof Error ? err.message : String(err)}`
+          });
+        }
+      }
+    }
+    return {
+      authenticated: checks.length > 0 && checks.every((c) => c.passed),
+      checks
+    };
+  }
   // ── Playwright Escape Hatches ─────────────────────────────────
   /**
    * Get the underlying Playwright `Page` object for this tab.
@@ -6374,9 +6506,11 @@ var BrowserClaw = class _BrowserClaw {
   ssrfPolicy;
   recordVideo;
   chrome;
-  constructor(cdpUrl, chrome, ssrfPolicy, recordVideo) {
+  _telemetry;
+  constructor(cdpUrl, chrome, telemetry, ssrfPolicy, recordVideo) {
     this.cdpUrl = cdpUrl;
     this.chrome = chrome;
+    this._telemetry = telemetry;
     this.ssrfPolicy = ssrfPolicy;
     this.recordVideo = recordVideo;
   }
@@ -6405,13 +6539,21 @@ var BrowserClaw = class _BrowserClaw {
    * ```
    */
   static async launch(opts = {}) {
+    const startedAt = (/* @__PURE__ */ new Date()).toISOString();
     const chrome = await launchChrome(opts);
     const cdpUrl = `http://127.0.0.1:${String(chrome.cdpPort)}`;
     const ssrfPolicy = opts.allowInternal === true ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts.ssrfPolicy;
-    const browser = new _BrowserClaw(cdpUrl, chrome, ssrfPolicy, opts.recordVideo);
+    const telemetry = {
+      launchMs: chrome.launchMs,
+      timestamps: { startedAt, launchedAt: (/* @__PURE__ */ new Date()).toISOString() }
+    };
+    const browser = new _BrowserClaw(cdpUrl, chrome, telemetry, ssrfPolicy, opts.recordVideo);
     if (opts.url !== void 0 && opts.url !== "") {
       const page = await browser.currentPage();
+      const navT0 = Date.now();
       await page.goto(opts.url);
+      telemetry.navMs = Date.now() - navT0;
+      telemetry.timestamps.navigatedAt = (/* @__PURE__ */ new Date()).toISOString();
     }
     return browser;
   }
@@ -6430,6 +6572,8 @@ var BrowserClaw = class _BrowserClaw {
    * ```
    */
   static async connect(cdpUrl, opts) {
+    const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const connectT0 = Date.now();
     let resolvedUrl = cdpUrl;
     if (resolvedUrl === void 0 || resolvedUrl === "") {
       const discovered = await discoverChromeCdpUrl();
@@ -6445,7 +6589,11 @@ var BrowserClaw = class _BrowserClaw {
     }
     await connectBrowser(resolvedUrl, opts?.authToken);
     const ssrfPolicy = opts?.allowInternal === true ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts?.ssrfPolicy;
-    return new _BrowserClaw(resolvedUrl, null, ssrfPolicy, opts?.recordVideo);
+    const telemetry = {
+      connectMs: Date.now() - connectT0,
+      timestamps: { startedAt, connectedAt: (/* @__PURE__ */ new Date()).toISOString() }
+    };
+    return new _BrowserClaw(resolvedUrl, null, telemetry, ssrfPolicy, opts?.recordVideo);
   }
   /**
    * Open a URL in a new tab and return the page handle.
@@ -6474,7 +6622,12 @@ var BrowserClaw = class _BrowserClaw {
    * @returns CrawlPage for the first/active page
    */
   async currentPage() {
+    const connectT0 = Date.now();
     const { browser } = await connectBrowser(this.cdpUrl);
+    if (this._telemetry.connectMs === void 0) {
+      this._telemetry.connectMs = Date.now() - connectT0;
+      this._telemetry.timestamps.connectedAt = (/* @__PURE__ */ new Date()).toISOString();
+    }
     const pages = getAllPages(browser);
     if (!pages.length) throw new Error("No pages available. Use browser.open(url) to create a tab.");
     const tid = await pageTargetId(pages[0]).catch(() => null);
@@ -6551,15 +6704,61 @@ var BrowserClaw = class _BrowserClaw {
    * If the browser was launched by `BrowserClaw.launch()`, the Chrome process
    * will be terminated. If connected via `BrowserClaw.connect()`, only the
    * Playwright connection is closed.
+   *
+   * @param exitReason - Optional structured reason for stopping (e.g. `'success'`, `'auth_failed'`, `'timeout'`)
    */
-  async stop() {
-    clearRecordingContext(this.cdpUrl);
-    await disconnectBrowser();
-    if (this.chrome) {
-      await stopChrome(this.chrome);
-      this.chrome = null;
+  async stop(exitReason) {
+    this._telemetry.timestamps.stoppedAt = (/* @__PURE__ */ new Date()).toISOString();
+    if (exitReason !== void 0) this._telemetry.exitReason = exitReason;
+    try {
+      clearRecordingContext(this.cdpUrl);
+      await disconnectBrowser();
+      if (this.chrome) {
+        await stopChrome(this.chrome);
+        this.chrome = null;
+      }
+      this._telemetry.cleanupOk = true;
+    } catch (err) {
+      this._telemetry.cleanupOk = false;
+      throw err;
     }
   }
+  /**
+   * Get structured telemetry for this browser session.
+   *
+   * Returns timing data, timestamps, and exit information collected
+   * throughout the session lifecycle. Useful for diagnosing startup
+   * latency, auth failures, and cleanup issues in cron/unattended runs.
+   *
+   * @returns Telemetry envelope with launch/connect/nav timings and exit info
+   *
+   * @example
+   * ```ts
+   * const browser = await BrowserClaw.launch({ url: 'https://example.com' });
+   * const page = await browser.currentPage();
+   *
+   * // ... do work ...
+   *
+   * const auth = await page.isAuthenticated([{ cookie: 'session' }]);
+   * browser.recordAuthResult(auth.authenticated);
+   *
+   * await browser.stop(auth.authenticated ? 'success' : 'auth_failed');
+   * console.log(browser.telemetry());
+   * // { launchMs: 1823, connectMs: 45, navMs: 620, authOk: true,
+   * //   exitReason: 'success', cleanupOk: true, timestamps: { ... } }
+   * ```
+   */
+  telemetry() {
+    return this._telemetry;
+  }
+  /**
+   * Record the result of an authentication check in the telemetry envelope.
+   *
+   * @param ok - Whether authentication was successful
+   */
+  recordAuthResult(ok) {
+    this._telemetry.authOk = ok;
+  }
 };
 
 export { BlockedBrowserTargetError, BrowserClaw, BrowserTabNotFoundError, CrawlPage, InvalidBrowserNavigationUrlError, STEALTH_SCRIPT, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, detectChallengeViaPlaywright, ensureContextState, executeSingleAction, forceDisconnectPlaywrightConnection, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, pressAndHoldViaCdp, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingPathsWithinRoot, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, setDialogHandler, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };