playwriter 0.2.0 → 0.3.0

package/src/executor.ts

@@ -66,6 +66,7 @@ const usefulGlobals = {
   AbortController,
   AbortSignal,
   structuredClone,
+  process,
 } as const
 
 /**
@@ -226,6 +227,7 @@ export interface CdpConfig {
   port?: number
   token?: string
   extensionId?: string | null
+  autoEnable?: boolean
   /** Direct CDP WebSocket URL — bypasses relay + extension, connects straight to Chrome */
   directCdpUrl?: string
 }
@@ -287,7 +289,12 @@ export class PlaywrightExecutor {
   private context: BrowserContext | null = null
 
   private userState: Record<string, any> = {}
-  private browserLogs: Map<string, string[]> = new Map()
+  private browserLogs: Map<Page, string[]> = new Map()
+  // Tracks the index up to which getLatestLogs({ sinceLastCall: true }) has
+  // returned logs. 0 means "return everything" (first call gets full buffer).
+  // When addBrowserLog shifts old entries (cap at MAX_LOGS_PER_PAGE), cursors
+  // are decremented so they stay in sync with the array.
+  private pageLogCursor: Map<Page, number> = new Map()
   private lastSnapshots: WeakMap<Page, Map<string, string>> = new WeakMap()
   private lastRefToLocator: WeakMap<Page, Map<string, string>> = new WeakMap()
   private warningEvents: WarningEvent[] = []
@@ -531,41 +538,68 @@ export class PlaywrightExecutor {
   }
 
   private setupPageConsoleListener(page: Page) {
-    // Use targetId() if available, fallback to internal _guid for CDP connections
-    const targetId = page.targetId() || ((page as any)._guid as string | undefined)
-    if (!targetId) {
-      return
-    }
-
-    if (!this.browserLogs.has(targetId)) {
-      this.browserLogs.set(targetId, [])
+    if (!this.browserLogs.has(page)) {
+      this.browserLogs.set(page, [])
     }
 
-    page.on('framenavigated', (frame) => {
-      if (frame === page.mainFrame()) {
-        this.browserLogs.set(targetId, [])
-      }
-    })
+    // Logs are NOT cleared on navigation so that getLatestLogs({ sinceLastCall: true })
+    // can return errors from the previous page load. The MAX_LOGS_PER_PAGE cap (5000)
+    // prevents unbounded growth; old entries are shifted out in addBrowserLog.
 
     page.on('close', () => {
-      this.browserLogs.delete(targetId)
+      this.browserLogs.delete(page)
+      this.pageLogCursor.delete(page)
     })
 
     page.on('console', (msg) => {
       try {
         const logEntry = `[${msg.type()}] ${msg.text()}`
-        if (!this.browserLogs.has(targetId)) {
-          this.browserLogs.set(targetId, [])
-        }
-        const pageLogs = this.browserLogs.get(targetId)!
-        pageLogs.push(logEntry)
-        if (pageLogs.length > MAX_LOGS_PER_PAGE) {
-          pageLogs.shift()
-        }
+        this.addBrowserLog({ page, logEntry })
       } catch (e) {
         this.logger.error('[Executor] Failed to get console message text:', e)
       }
     })
+
+    page.on('pageerror', (error) => {
+      this.addBrowserLog({ page, logEntry: `[pageerror] ${error.message}` })
+    })
+  }
+
+  private addBrowserLog(options: { page: Page; logEntry: string }) {
+    if (!this.browserLogs.has(options.page)) {
+      this.browserLogs.set(options.page, [])
+    }
+    const pageLogs = this.browserLogs.get(options.page)!
+    pageLogs.push(options.logEntry)
+    if (pageLogs.length > MAX_LOGS_PER_PAGE) {
+      pageLogs.shift()
+      // Decrement cursor so it stays in sync with the shifted array.
+      // Clamp to 0 so the cursor never goes negative.
+      const cursor = this.pageLogCursor.get(options.page)
+      if (cursor !== undefined && cursor > 0) {
+        this.pageLogCursor.set(options.page, cursor - 1)
+      }
+    }
+  }
+
+  private pagesRelatedToPage(page: Page): Page[] {
+    const frameUrls = new Set(
+      page
+        .frames()
+        .map((frame) => {
+          return frame.url()
+        })
+        .filter((url) => {
+          return url && url !== 'about:blank'
+        }),
+    )
+
+    return page
+      .context()
+      .pages()
+      .filter((candidate) => {
+        return candidate === page || frameUrls.has(candidate.url())
+      })
   }
 
   private async checkExtensionStatus(): Promise<{
@@ -573,17 +607,24 @@ export class PlaywrightExecutor {
     activeTargets: number
     playwriterVersion: string | null
   }> {
-    const { host = '127.0.0.1', port = 19988, extensionId } = this.cdpConfig
+    const { host = '127.0.0.1', port = 19988, extensionId, token } = this.cdpConfig
     const { httpBaseUrl } = parseRelayHost(host, port)
     const notConnected = { connected: false, activeTargets: 0, playwriterVersion: null }
+    const headers: Record<string, string> = {}
+    const effectiveToken = token || process.env.PLAYWRITER_TOKEN
+    if (effectiveToken) {
+      headers['Authorization'] = `Bearer ${effectiveToken}`
+    }
     try {
       if (extensionId) {
         const response = await fetch(`${httpBaseUrl}/extensions/status`, {
           signal: AbortSignal.timeout(2000),
+          headers,
         })
         if (!response.ok) {
           const fallback = await fetch(`${httpBaseUrl}/extension/status`, {
             signal: AbortSignal.timeout(2000),
+            headers,
           })
           if (!fallback.ok) {
             return notConnected
@@ -617,6 +658,7 @@ export class PlaywrightExecutor {
 
       const response = await fetch(`${httpBaseUrl}/extension/status`, {
         signal: AbortSignal.timeout(2000),
+        headers,
       })
       if (!response.ok) {
         return notConnected
@@ -968,21 +1010,50 @@ export class PlaywrightExecutor {
         })
       }
 
-      const getLatestLogs = async (options?: { page?: Page; count?: number; search?: string | RegExp }) => {
-        const { page: filterPage, count, search } = options || {}
+      const getLatestLogs = async (options?: {
+        page?: Page
+        count?: number
+        search?: string | RegExp
+        // When true, only return logs added since the last getLatestLogs call
+        // with sinceLastCall: true. First call returns all buffered logs.
+        // Cursors are tracked per page so navigations and new logs are
+        // never missed. Useful for checking page errors after each action.
+        sinceLastCall?: boolean
+      }) => {
+        const { page: filterPage, count, search, sinceLastCall = false } = options || {}
         let allLogs: string[] = []
 
-        if (filterPage) {
-          // Use targetId() if available, fallback to internal _guid for CDP connections
-          const targetId = filterPage.targetId() || ((filterPage as any)._guid as string | undefined)
-          if (!targetId) {
-            throw new Error('Could not get page targetId')
+        // Collect logs, optionally slicing from cursor when sinceLastCall is set
+        const collectLogs = (targetPage: Page): string[] => {
+          const logs = this.browserLogs.get(targetPage) || []
+          if (!sinceLastCall) {
+            return logs
           }
-          const pageLogs = this.browserLogs.get(targetId) || []
-          allLogs = [...pageLogs]
+          const cursor = this.pageLogCursor.get(targetPage) || 0
+          return logs.slice(cursor)
+        }
+
+        if (filterPage) {
+          const relatedPages = this.pagesRelatedToPage(filterPage)
+          allLogs = relatedPages.flatMap((relatedPage) => {
+            return collectLogs(relatedPage)
+          })
         } else {
-          for (const pageLogs of this.browserLogs.values()) {
-            allLogs.push(...pageLogs)
+          for (const [p] of this.browserLogs) {
+            allLogs.push(...collectLogs(p))
+          }
+        }
+
+        // Advance cursors after collecting so next sinceLastCall call starts fresh
+        if (sinceLastCall) {
+          const pagesToAdvance = filterPage
+            ? this.pagesRelatedToPage(filterPage)
+            : [...this.browserLogs.keys()]
+          for (const p of pagesToAdvance) {
+            const logs = this.browserLogs.get(p)
+            if (logs) {
+              this.pageLogCursor.set(p, logs.length)
+            }
           }
         }
 
@@ -1021,6 +1092,7 @@ export class PlaywrightExecutor {
 
       const clearAllLogs = () => {
         this.browserLogs.clear()
+        this.pageLogCursor.clear()
       }
 
       const getCDPSession = async (options: { page: Page }) => {
@@ -1221,6 +1293,18 @@ export class PlaywrightExecutor {
         // Ghost Browser API - only works in Ghost Browser, mirrors chrome.ghostPublicAPI etc
         chrome: chromeGhostBrowser,
         ...usefulGlobals,
+        // Expose process with safety overrides:
+        // - cwd() returns the session's cwd instead of the relay server's cwd
+        // - exit() is blocked to prevent killing the relay server
+        // - chdir() is blocked to prevent affecting other sessions
+        process: new Proxy(process, {
+          get(target, prop, receiver) {
+            if (prop === 'cwd') return () => self.sessionCwd || target.cwd()
+            if (prop === 'exit') return () => { throw new Error('process.exit() is not allowed in the sandbox') }
+            if (prop === 'chdir') return () => { throw new Error('process.chdir() is not allowed in the sandbox, use a new session with a different cwd instead') }
+            return Reflect.get(target, prop, receiver)
+          },
+        }),
       }
 
       const vmContext = vm.createContext(vmContextObj)

package/src/relay-client.ts

@@ -39,6 +39,31 @@ export async function getRelayServerVersion(port: number = RELAY_PORT): Promise<
   }
 }
 
+/**
+ * Poll /version until a relay responds or timeout expires.
+ * Used during startup races where a relay may have bound the port
+ * but isn't serving HTTP yet (issue #75).
+ */
+export async function waitForRelayVersion({
+  port = RELAY_PORT,
+  timeoutMs = 2000,
+  intervalMs = 200,
+}: {
+  port?: number
+  timeoutMs?: number
+  intervalMs?: number
+} = {}): Promise<string | null> {
+  const end = Date.now() + timeoutMs
+  while (Date.now() < end) {
+    const version = await getRelayServerVersion(port)
+    if (version) {
+      return version
+    }
+    await sleep(intervalMs)
+  }
+  return null
+}
+
 export async function getExtensionStatus(
   port: number = RELAY_PORT,
 ): Promise<{ connected: boolean; activeTargets: number; playwriterVersion: string | null } | null> {
@@ -196,11 +221,26 @@ export interface EnsureRelayServerOptions {
   env?: Record<string, string>
 }
 
+// Module-level dedup: if ensureRelayServer is called concurrently within the
+// same process (e.g. two MCP tool handlers at once), only one spawn runs.
+let pendingEnsure: Promise<true | undefined> | null = null
+
 /**
  * Ensures the relay server is running. Starts it if not running.
  * Optionally restarts on version mismatch.
+ * Concurrent calls within the same process are deduplicated.
  */
 export async function ensureRelayServer(options: EnsureRelayServerOptions = {}): Promise<true | undefined> {
+  if (pendingEnsure) {
+    return pendingEnsure
+  }
+  pendingEnsure = ensureRelayServerImpl(options).finally(() => {
+    pendingEnsure = null
+  })
+  return pendingEnsure
+}
+
+async function ensureRelayServerImpl(options: EnsureRelayServerOptions = {}): Promise<true | undefined> {
   const { logger, restartOnVersionMismatch = true, env: additionalEnv } = options
   const serverVersion = await getRelayServerVersion(RELAY_PORT)
 
@@ -227,11 +267,28 @@ export async function ensureRelayServer(options: EnsureRelayServerOptions = {}):
   } else {
     const listeningPids = await getListeningPidsForPort({ port: RELAY_PORT }).catch(() => [])
     if (listeningPids.length > 0) {
-      logger?.log(
-        pc.yellow(
-          `Port ${RELAY_PORT} is already in use (pid(s): ${listeningPids.join(', ')}). Attempting to stop the existing process...`,
-        ),
-      )
+      // Something is on the port but /version didn't respond. It might be a
+      // relay that's still starting (race with another CLI/MCP instance).
+      // Poll /version briefly before deciding to kill it (issue #75).
+      const foundVersion = await waitForRelayVersion({ port: RELAY_PORT })
+      if (foundVersion) {
+        // A relay came up while we waited; use it
+        if (foundVersion === VERSION || compareVersions(foundVersion, VERSION) > 0) {
+          return
+        }
+        if (!restartOnVersionMismatch) {
+          return
+        }
+        logger?.log(
+          pc.yellow(`CDP relay server version mismatch (server: ${foundVersion}, client: ${VERSION}), restarting...`),
+        )
+      } else {
+        logger?.log(
+          pc.yellow(
+            `Port ${RELAY_PORT} is already in use (pid(s): ${listeningPids.join(', ')}). Attempting to stop the existing process...`,
+          ),
+        )
+      }
       await killRelayServer({ port: RELAY_PORT })
     }
 

package/src/relay-core.test.ts

@@ -730,6 +730,7 @@ describe('Relay Core Tests', () => {
             console.error('Test error 67890');
             console.warn('Test warning 11111');
             console.log('Test log 2 with', { data: 'object' });
+            setTimeout(() => { throw new Error('Test pageerror 22222'); }, 0);
           });
           // Wait for logs to be captured
           await new Promise(resolve => setTimeout(resolve, 100));
@@ -752,6 +753,7 @@ describe('Relay Core Tests', () => {
     expect(output).toContain('[log] Test log 12345')
     expect(output).toContain('[error] Test error 67890')
     expect(output).toContain('[warning] Test warning 11111')
+    expect(output).toContain('[pageerror] Test pageerror 22222')
 
     // Test filtering by search string
     const errorLogsResult = await client.callTool({
@@ -769,7 +771,7 @@ describe('Relay Core Tests', () => {
     // With context lines (5 above/below), nearby logs are also included
     expect(errorOutput).toContain('[log] Test log 12345')
 
-    // Test that logs are cleared on page reload
+    // Test that logs persist across page reload
     await client.callTool({
       name: 'execute',
       arguments: {
@@ -812,7 +814,9 @@ describe('Relay Core Tests', () => {
       },
     })
 
-    // Check logs after reload - old logs should be gone
+    // Check logs after reload - old logs persist (no longer cleared on navigation)
+    // so both pre- and post-reload logs are present. Use sinceLastCall to get
+    // only new logs if needed.
     const afterReloadResult = await client.callTool({
       name: 'execute',
       arguments: {
@@ -826,7 +830,7 @@ describe('Relay Core Tests', () => {
 
     const afterReloadOutput = (afterReloadResult as any).content[0].text
     expect(afterReloadOutput).toContain('[log] After reload 88888')
-    expect(afterReloadOutput).not.toContain('[log] Before reload 99999')
+    expect(afterReloadOutput).toContain('[log] Before reload 99999')
 
     // Clean up
     await client.callTool({
@@ -943,7 +947,7 @@ describe('Relay Core Tests', () => {
     expect(allOutput).toContain('[log] PageA log 11111')
     expect(allOutput).toContain('[log] PageB log 33333')
 
-    // Test that reloading page A clears only page A logs
+    // Test that reloading page A preserves logs (no longer cleared on navigation)
     await client.callTool({
       name: 'execute',
       arguments: {
@@ -957,7 +961,7 @@ describe('Relay Core Tests', () => {
       },
     })
 
-    // Check page A logs - should only have new log
+    // Check page A logs - logs persist across navigation, so both old and new are present
     const pageAAfterReloadResult = await client.callTool({
       name: 'execute',
       arguments: {
@@ -971,7 +975,7 @@ describe('Relay Core Tests', () => {
 
     const pageAAfterReloadOutput = (pageAAfterReloadResult as any).content[0].text
     expect(pageAAfterReloadOutput).toContain('[log] PageA after reload 55555')
-    expect(pageAAfterReloadOutput).not.toContain('[log] PageA log 11111')
+    expect(pageAAfterReloadOutput).toContain('[log] PageA log 11111')
 
     // Check page B logs - should still have original logs
     const pageBAfterAReloadResult = await client.callTool({

package/src/relay-session.test.ts

@@ -1277,7 +1277,15 @@ describe('Auto-enable Tests', () => {
     })
     expect(tabCountBefore).toBe(0)
 
-    const browser = await chromium.connectOverCDP(getCdpUrl({ port: TEST_PORT }))
+    const previousAutoEnable = process.env.PLAYWRITER_AUTO_ENABLE
+    delete process.env.PLAYWRITER_AUTO_ENABLE
+    const browser = await chromium.connectOverCDP(getCdpUrl({ port: TEST_PORT, autoEnable: true })).finally(() => {
+      if (previousAutoEnable === undefined) {
+        delete process.env.PLAYWRITER_AUTO_ENABLE
+        return
+      }
+      process.env.PLAYWRITER_AUTO_ENABLE = previousAutoEnable
+    })
 
     const pages = browser.contexts()[0].pages()
     expect(pages.length).toBeGreaterThan(0)

package/src/relay-state.test.ts

@@ -2,7 +2,7 @@
  * Unit tests for relay state transitions.
  * Data-in / data-out transitions for the unified extension map.
  */
-import { describe, test, expect } from 'vitest'
+import { describe, test, expect, beforeAll, afterAll } from 'vitest'
 import type { WSContext } from 'hono/ws'
 import type { Protocol } from './cdp-types.js'
 import * as relayState from './relay-state.js'
@@ -568,3 +568,69 @@ describe('store.setState with transitions', () => {
     expect(state.playwrightClients.size).toBe(1)
   })
 })
+
+// ---------------------------------------------------------------------------
+// DNS rebinding protection — Host header validation
+// Node.js fetch/undici treats Host as a forbidden header, so we use the raw
+// http module to send requests with arbitrary Host values.
+// ---------------------------------------------------------------------------
+
+import http from 'node:http'
+
+function httpGet({ port, path, host }: { port: number; path: string; host: string }): Promise<{ status: number; body: string }> {
+  return new Promise((resolve, reject) => {
+    const req = http.request({ hostname: '127.0.0.1', port, path, method: 'GET', headers: { Host: host } }, (res) => {
+      let body = ''
+      res.on('data', (chunk: Buffer) => {
+        body += chunk.toString()
+      })
+      res.on('end', () => {
+        resolve({ status: res.statusCode!, body })
+      })
+    })
+    req.on('error', reject)
+    req.end()
+  })
+}
+
+describe('Host header validation (DNS rebinding protection)', () => {
+  let server: { close(): void } | null = null
+  const TEST_PORT = 19996
+
+  beforeAll(async () => {
+    const { startPlayWriterCDPRelayServer } = await import('./cdp-relay.js')
+    server = await startPlayWriterCDPRelayServer({ port: TEST_PORT })
+  })
+
+  afterAll(async () => {
+    server?.close()
+    server = null
+  })
+
+  test('rejects requests with non-localhost Host header', async () => {
+    // DNS rebinding: evil.com resolves to 127.0.0.1
+    const res = await httpGet({ port: TEST_PORT, path: '/', host: 'evil.com' })
+    expect(res.status).toBe(403)
+    expect(res.body).toContain('Invalid Host header')
+
+    // With port suffix
+    const res2 = await httpGet({ port: TEST_PORT, path: '/version', host: 'evil.com:19996' })
+    expect(res2.status).toBe(403)
+  })
+
+  test('allows requests with localhost Host headers', async () => {
+    const localhostVariants = [
+      `localhost:${TEST_PORT}`,
+      `127.0.0.1:${TEST_PORT}`,
+      `[::1]:${TEST_PORT}`,
+      'localhost',
+      '127.0.0.1',
+      'LOCALHOST',
+    ]
+
+    for (const hostValue of localhostVariants) {
+      const res = await httpGet({ port: TEST_PORT, path: '/', host: hostValue })
+      expect(res.status, `Expected 200 for Host: ${hostValue}`).toBe(200)
+    }
+  })
+})

package/src/skill.md

@@ -203,10 +203,19 @@ You can collaborate with the user - they can help with captchas, difficult eleme
 - `page` - a default page (may be shared with other agents). Prefer creating your own page and storing it in `state` (see "working with pages")
 - `context` - browser context, access all pages via `context.pages()`
 - `require` - load Node.js modules (e.g., `const fs = require('node:fs')`). ESM `import` is not available in the sandbox
-- Node.js globals: `setTimeout`, `setInterval`, `fetch`, `URL`, `Buffer`, `crypto`, etc.
+- Node.js globals: `setTimeout`, `setInterval`, `fetch`, `URL`, `Buffer`, `crypto`, `process`, etc.
+
+**Not available in the sandbox:** `__dirname`, `__filename`, `import`.
 
 **Important:** `state` is **session-isolated** but pages are **shared** across all sessions. See "working with pages" for how to avoid interference.
 
+**Sandboxed `fs` write restrictions:** `require('node:fs')` is scoped. Writes (writeFileSync, mkdirSync, etc.) only succeed in:
+- The **directory where `playwriter` CLI was invoked** (the session's cwd)
+- `/tmp`
+- The OS temp directory (`os.tmpdir()`, e.g. `/var/folders/.../T/` on macOS)
+
+Writing to any other path (e.g. `~/Downloads`, `~/Desktop`) throws `EPERM: operation not permitted, access outside allowed directories`. To save files elsewhere, write to a temp path first, then move the file using a shell command outside the sandbox.
+
 ## rules
 
 - **Initialize state.page first**: see "working with pages" — at the start of a task, assign `state.page` (reuse `about:blank` or create one) and use `state.page` for all automation steps.
@@ -215,6 +224,7 @@ You can collaborate with the user - they can help with captchas, difficult eleme
 - **No bringToFront**: never call unless user asks - it's disruptive and unnecessary, you can interact with background pages
 - **Check state after actions**: always verify page state after clicking/submitting (see next section)
 - **Clean up listeners**: call `state.page.removeAllListeners()` at end of message to prevent leaks
+- **Always print page logs after every action**: call `getLatestLogs({ page: state.page, sinceLastCall: true })` after every goto, click, or submit to catch console errors and warnings. Do not manually collect `page.on('console')` events; manual listeners miss logs emitted before the listener is attached. The first `sinceLastCall` call returns all buffered logs including startup and hydration errors.
 - **CDP sessions**: use `getCDPSession({ page: state.page })` not `state.page.context().newCDPSession()` - NEVER use `newCDPSession()` method, it doesn't work through playwriter relay
 - **Wait for load**: use `state.page.waitForLoadState('domcontentloaded')` not `state.page.waitForEvent('load')` - waitForEvent times out if already loaded
 - **Minimize timeouts**: prefer proper waits (`waitForSelector`, `waitForPageLoad`) over `state.page.waitForTimeout()`. Short timeouts (1-2s) are acceptable for non-deterministic events like animations, tab opens, or async UI updates where no specific selector is available
@@ -227,18 +237,21 @@ You can collaborate with the user - they can help with captchas, difficult eleme
 Every browser interaction must follow **observe → act → observe**. Never chain multiple actions blindly.
 
 1. **Open page** — get or create your page, navigate to URL
-2. **Observe** — print `state.page.url()` + `snapshot()`. Always print URL — pages can redirect unexpectedly.
+2. **Observe** — print `state.page.url()` + `snapshot()` + `getLatestLogs({ sinceLastCall: true })`. Always print URL — pages can redirect unexpectedly.
 3. **Check** — if page isn't ready (loading, wrong URL, content missing), wait and observe again
 4. **Act** — perform one action (click, type, submit)
-5. **Observe again** — print URL + snapshot to verify the action's effect
+5. **Observe again** — print URL + snapshot + page logs to verify the action's effect
 6. **Repeat** from step 3 until task is complete
 
+**Always print page logs after every action** using `getLatestLogs({ sinceLastCall: true })`. This returns only new console messages and errors since the last call, so you catch hydration errors, failed network requests, and runtime exceptions without duplicates. The first call returns all buffered logs from the page, including logs emitted before your script started.
+
 ```js
 // Each step should be a separate execute call:
 // Step 1: navigate + observe
 state.page = context.pages().find((p) => p.url() === 'about:blank') ?? (await context.newPage())
 await state.page.goto('https://example.com', { waitUntil: 'domcontentloaded' })
 console.log('URL:', state.page.url())
+console.log('Page logs:', await getLatestLogs({ page: state.page, sinceLastCall: true }))
 await snapshot({ page: state.page }).then(console.log)
 ```
 
@@ -246,25 +259,26 @@ await snapshot({ page: state.page }).then(console.log)
 // Step 2: act + observe
 await state.page.locator('button:has-text("Submit")').click()
 console.log('URL:', state.page.url())
+console.log('Page logs:', await getLatestLogs({ page: state.page, sinceLastCall: true }))
 await snapshot({ page: state.page }).then(console.log)
 ```
 
 If nothing changed after an action, try `waitForPageLoad({ page: state.page, timeout: 3000 })` or you may have clicked the wrong element.
 
-**Deeper observation** — when snapshots aren't enough to understand what happened, combine multiple channels:
+**Deeper observation** — when snapshots aren't enough to understand what happened, combine snapshot with filtered logs:
 
 ```js
-// Check console for errors after an action
+// Search for specific errors in all logs (not just since last call)
 const errors = await getLatestLogs({ page: state.page, search: /error|fail/i, count: 20 })
 
-// Combine snapshot + logs for full picture
+// Combine snapshot + filtered logs for full picture
 const snap = await snapshot({ page: state.page, search: /dialog|error|message/ })
 const logs = await getLatestLogs({ page: state.page, search: /error/i, count: 10 })
 console.log('UI:', snap)
 console.log('Logs:', logs)
 ```
 
-Use `getLatestLogs()` for console errors, `state.page.url()` for navigation, screenshots only for visual layout issues.
+Use `getLatestLogs({ sinceLastCall: true })` after every action, `getLatestLogs({ search })` for targeted debugging, `state.page.url()` for navigation, screenshots only for visual layout issues.
 
 ## common mistakes to avoid
 
@@ -680,17 +694,22 @@ For carousels or lazy-loaded galleries, you may need to click navigation arrows
 
 ## utility functions
 
-**getLatestLogs** - retrieve captured browser console logs (up to 5000 per page, cleared on navigation):
+**getLatestLogs** - retrieve captured browser console logs and page errors (up to 5000 per page):
+
+Always use this helper when inspecting browser logs. Do not attach new `page.on('console')` listeners for debugging because they only see future events and can miss logs emitted during page startup or hydration.
+
+Use `sinceLastCall: true` after every action to get only new logs since the previous call. The first call returns all buffered logs including pre-existing ones. Logs persist across navigations so you never miss errors from page transitions.
 
 ```js
-await getLatestLogs({ page?, count?, search? })
-// Examples:
+await getLatestLogs({ page?, count?, search?, sinceLastCall? })
+// After every action: get only new logs
+const newLogs = await getLatestLogs({ page: state.page, sinceLastCall: true })
+// Search all logs (ignores cursor):
 const errors = await getLatestLogs({ search: /error/i, count: 50 })
-const pageLogs = await getLatestLogs({ page: state.page })
+const pageLogs = await getLatestLogs({ page: state.page, count: 100 })
+const hydrationErrors = await getLatestLogs({ page: state.page, search: /hydration|pageerror|React/i })
 ```
 
-For custom log collection across runs, store in state: `state.logs = []; state.page.on('console', m => state.logs.push(m.text()))`
-
 **getCleanHTML** - get cleaned HTML from a locator or page, with search and diffing:
 
 ```js

package/src/start-relay-server.ts

@@ -1,5 +1,6 @@
 import { startPlayWriterCDPRelayServer } from './cdp-relay.js'
 import { createFileLogger } from './create-logger.js'
+import { waitForRelayVersion } from './relay-client.js'
 import { LOG_CDP_FILE_PATH } from './utils.js'
 
 process.title = 'playwriter-ws-server'
@@ -25,7 +26,27 @@ export async function startServer({
   host = '127.0.0.1',
   token,
 }: { port?: number; host?: string; token?: string } = {}) {
-  const server = await startPlayWriterCDPRelayServer({ port, host, token, logger })
+  let server
+  try {
+    server = await startPlayWriterCDPRelayServer({ port, host, token, logger })
+  } catch (err: unknown) {
+    // When two relay processes race to start (issue #75), the loser gets
+    // EADDRINUSE. Check if the winner is a valid relay and exit cleanly
+    // instead of crashing with a scary error in the logs.
+    const errWithCode = err as NodeJS.ErrnoException
+    if (errWithCode?.code === 'EADDRINUSE') {
+      // The winner may have bound the port but not be ready to answer /version
+      // yet, so poll for up to 2 seconds before giving up.
+      const version = await waitForRelayVersion({ port })
+      if (version) {
+        await logger.log(`Another relay (v${version}) already bound to port ${port}, exiting gracefully`)
+        process.exit(0)
+      }
+      await logger.error(`Port ${port} is in use by a non-relay process`)
+      process.exit(1)
+    }
+    throw err
+  }
 
   console.log('CDP Relay Server running. Press Ctrl+C to stop.')
   console.log('Logs are being written to:', logger.logFilePath)