@m13v/s4l 1.6.197-rc.7

package/scripts/linkedin_browser.py

@@ -0,0 +1,730 @@
+#!/usr/bin/env python3
+"""LinkedIn browser automation: read-only sidebar pre-check.
+
+Usage:
+    python3 linkedin_browser.py unread-dms
+
+Read-only DOM scrape: NO Voyager API, NO scroll-and-expand loops, NO
+permalink fan-out, NO clicks/typing, NO programmatic login. Each
+invocation does ONE navigation + ONE page.evaluate() then closes the context.
+
+Per CLAUDE.md "LinkedIn: flagged patterns" carve-out (2026-04-29): a
+read-only DOM read is permitted because its fingerprint is indistinguishable
+from the existing mcp__linkedin-agent__ sessions (same profile, same cookies,
+same headed Chrome binary). The 2026-04-17 restriction was caused by Voyager
+calls + permalink scroll loops, neither of which appear here.
+
+Connects to the running linkedin-agent's persistent profile at
+~/.claude/browser-profiles/linkedin. Launches HEADED Chromium (per the
+CLAUDE.md note that LinkedIn fingerprints headless aggressively). Holds
+the linkedin-browser lock for the entire run; expects the caller (shell)
+to have already done lock acquisition + ensure_browser_healthy so the MCP
+Chrome is gone and the profile is free.
+
+Sister script for SERP discovery: scripts/discover_linkedin_candidates.py
+(replaces the Claude-driven SERP nav inside skill/run-linkedin.sh Phase A).
+That script imports PROFILE_DIR / VIEWPORT / SYSTEM_CHROME / LOCK_*
+constants + _acquire_browser_lock + _is_login_or_checkpoint from this
+module so both tools cooperate on the same Chrome profile and lock file.
+
+Output (stdout, JSON):
+    {
+        "ok": true,
+        "url": "https://www.linkedin.com/messaging/",
+        "total_threads": 13,
+        "unread_count": 0,
+        "threads": [...],
+    }
+
+Failure shapes:
+    {"ok": false, "error": "session_invalid", "url": "..."}
+    {"ok": false, "error": "profile_locked", "detail": "..."}
+    {"ok": false, "error": "navigation_failed", "detail": "..."}
+
+Exits 0 on success, 1 on failure.
+"""
+
+import atexit
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+from typing import Optional
+
+
+def _bh_activity_log(action: str, cdp_url: str) -> None:
+    """Append to the universal browser-activity.log (Python-CDP path coverage).
+
+    The harness MCP server.py logs its own bh_run calls, but these CDP scripts
+    attach via connect_over_cdp and bypass it, so they log here directly.
+    """
+    try:
+        import time as _t
+        import os as _o
+        from pathlib import Path as _P
+        _p = _P(_o.environ.get(
+            "BH_ACTIVITY_LOG",
+            str(_P.home() / ".claude" / "browser-profiles" / "browser-activity.log"),
+        ))
+        _port = (cdp_url or "").rsplit(":", 1)[-1].split("/")[0] or "-"
+        _p.parent.mkdir(parents=True, exist_ok=True)
+        with _p.open("a") as _f:
+            _f.write(
+                f"[{_t.strftime('%Y-%m-%d %H:%M:%S')}] pycdp "
+                f"script={_o.path.basename(__file__)} action={action} "
+                f"pid={_o.getpid()} ppid={_o.getppid()} cdp={cdp_url or '-'} "
+                f"port={_port}\n"
+            )
+    except Exception:
+        pass
+
+
+def _is_holder_alive(holder: str) -> bool:
+    """Mirror ~/.claude/hooks/linkedin-agent-lock.sh is_holder_alive().
+
+    A live Claude session puts its UUID on the cmdline as
+    `claude --session-id <UUID>`. pgrep matches it; absence means the
+    holder is dead and the lock is stale, even if its JSONL transcript
+    is still tail-flushing. This is the canonical liveness signal.
+    """
+    if not holder:
+        return False
+    try:
+        return (
+            subprocess.run(
+                ["pgrep", "-f", f"claude.*--session-id {holder}"],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=2,
+            ).returncode
+            == 0
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        # On error, assume alive to err on the side of NOT stealing the lock.
+        return True
+
+# Profile dir is overridable so the harness migration (2026-05-26) can point
+# the cold-launch fallback at ~/.claude/browser-profiles/browser-harness-linkedin
+# while leaving legacy linkedin-agent callers unchanged. The Twitter harness
+# uses the same pattern (TWITTER_CDP_URL + harness profile dir).
+PROFILE_DIR = os.path.expanduser(
+    os.environ.get(
+        "LINKEDIN_PROFILE_DIR",
+        "~/.claude/browser-profiles/linkedin",
+    )
+)
+LOCK_FILE = os.path.expanduser("~/.claude/linkedin-agent-lock.json")
+LOCK_EXPIRY = 300  # Must match ~/.claude/hooks/linkedin-agent-lock.sh
+LOCK_WAIT_MAX = 30  # seconds; pre-check should not block long
+LOCK_POLL_INTERVAL = 2
+VIEWPORT = {"width": 911, "height": 1016}
+# linkedin-agent uses the system Google Chrome binary, not Playwright's
+# bundled "Chrome for Testing". Profile was created/migrated by system
+# Chrome and "Chrome for Testing" fails to open it (SIGTRAP / kill EPERM
+# observed 2026-04-29). Match the agent's binary so the profile stays
+# compatible.
+SYSTEM_CHROME = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+
+_LOCK_SESSION_ID = f"python:{os.getpid()}"
+_LOCK_INHERITED = False
+_UUID_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+)
+
+
+def _release_browser_lock():
+    if _LOCK_INHERITED:
+        return
+    try:
+        if os.path.exists(LOCK_FILE):
+            with open(LOCK_FILE) as f:
+                lock = json.load(f)
+            if lock.get("session_id") == _LOCK_SESSION_ID:
+                os.remove(LOCK_FILE)
+    except (json.JSONDecodeError, OSError):
+        pass
+
+
+atexit.register(_release_browser_lock)
+
+
+def _is_python_holder_alive(holder: str) -> bool:
+    """Liveness probe for a `python:PID` lock holder (defect a fix, 2026-06-16).
+
+    Mirrors twitter_browser._is_python_holder_alive (see docs/twitter_browser_lock.md).
+    Holders written by the python scripts are `python:<pid>`; the linkedin-agent
+    PreToolUse hook writes UUID holders (handled separately by _is_holder_alive).
+    A python holder whose process died without running its atexit release used to
+    starve every peer until LOCK_EXPIRY (300s); os.kill(pid, 0) lets us reclaim it
+    at once. Returns True for anything we cannot prove dead, so the worst case
+    degrades to the LOCK_EXPIRY failsafe rather than stealing a live peer's lock.
+    """
+    if not holder.startswith("python:"):
+        return True  # not a python holder; this probe makes no claim
+    try:
+        pid = int(holder.split(":", 1)[1])
+    except (ValueError, IndexError):
+        return True  # unparseable holder -> don't steal on this basis
+    try:
+        os.kill(pid, 0)
+        return True            # process exists -> alive
+    except ProcessLookupError:
+        return False           # no such process -> dead, reclaimable
+    except PermissionError:
+        return True            # exists but another owner -> alive
+    except OSError:
+        return True            # ambiguous -> err toward NOT stealing
+
+
+def _try_take_lock() -> bool:
+    """Atomically claim LOCK_FILE for this process (defect c fix, 2026-06-16).
+    O_CREAT|O_EXCL makes "is it free? then take it" a single syscall, so two
+    python acquirers can't both win the old os.path.exists + open(w) race. A
+    False return means a peer beat us; the caller re-loops. Coexists with the
+    linkedin-agent hook (which registers UUID holders via its own write path):
+    python only takes when it has decided the lock is free or reclaimable.
+    """
+    try:
+        fd = os.open(LOCK_FILE, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+    except FileExistsError:
+        return False
+    except OSError:
+        return False
+    try:
+        os.write(fd, json.dumps(
+            {"session_id": _LOCK_SESSION_ID, "timestamp": int(time.time())}
+        ).encode())
+    finally:
+        os.close(fd)
+    return True
+
+
+def _acquire_browser_lock():
+    """Acquire the LinkedIn browser session mutex (~/.claude/linkedin-agent-lock.json).
+
+    Mirrors twitter_browser._acquire_browser_lock (full writeup:
+    docs/twitter_browser_lock.md). Co-managed with the linkedin-agent PreToolUse
+    hook, which registers live Claude sessions as UUID holders; we INHERIT those
+    rather than fight them. Reclaim priority (a holder PROVEN dead is taken at
+    once, so a crashed peer cannot starve the fleet for LOCK_WAIT_MAX/LOCK_EXPIRY):
+      1. holder == us           -> re-entrant; already ours.
+      2. UUID holder, pid gone  -> stale Claude session, reclaim.
+      3. python:PID, pid gone   -> dead peer (defect a fix), reclaim.
+      4. age >= LOCK_EXPIRY     -> failsafe for holders we cannot probe.
+      5. live UUID holder       -> inherit (parent Claude session / hook).
+      6. live python:PID holder -> real peer; wait, then give up (profile_locked).
+
+    Acquisition is atomic (_try_take_lock / O_EXCL). The lockfile JSON shape
+    {"session_id","timestamp"} is preserved so the hook keeps interoperating.
+    """
+    global _LOCK_SESSION_ID, _LOCK_INHERITED
+    deadline = time.time() + LOCK_WAIT_MAX
+    try:
+        os.makedirs(os.path.dirname(LOCK_FILE), exist_ok=True)
+    except OSError:
+        pass
+    while True:
+        if not os.path.exists(LOCK_FILE):
+            if _try_take_lock():
+                break
+            if time.time() >= deadline:
+                print(json.dumps({
+                    "ok": False, "error": "profile_locked",
+                    "detail": f"create-contended waited={LOCK_WAIT_MAX}s",
+                }))
+                sys.exit(1)
+            time.sleep(LOCK_POLL_INTERVAL)
+            continue
+        try:
+            with open(LOCK_FILE) as f:
+                lock = json.load(f)
+        except (json.JSONDecodeError, OSError):
+            # Corrupt / half-written / vanished between exists() and open().
+            if _try_take_lock():
+                break
+            if time.time() >= deadline:
+                print(json.dumps({
+                    "ok": False, "error": "profile_locked",
+                    "detail": f"unreadable waited={LOCK_WAIT_MAX}s",
+                }))
+                sys.exit(1)
+            time.sleep(LOCK_POLL_INTERVAL)
+            continue
+        age = time.time() - lock.get("timestamp", 0)
+        holder = lock.get("session_id", "")
+
+        # 1. Re-entrant: the lock is already ours (or a stale lock left by a
+        # previous process whose PID we reused). Refresh timestamp + proceed.
+        if holder == _LOCK_SESSION_ID and not _LOCK_INHERITED:
+            try:
+                with open(LOCK_FILE, "w") as f:
+                    json.dump(
+                        {"session_id": _LOCK_SESSION_ID,
+                         "timestamp": int(time.time())}, f)
+            except OSError:
+                pass
+            break
+
+        # 2-4. Reclaim a holder we can prove dead/expired (remove + atomic take).
+        reclaim_reason = ""
+        if _UUID_RE.match(holder or "") and not _is_holder_alive(holder):
+            reclaim_reason = "dead_uuid"
+        elif holder.startswith("python:") and not _is_python_holder_alive(holder):
+            reclaim_reason = "dead_python"
+        elif age >= LOCK_EXPIRY:
+            reclaim_reason = "expired"
+        if reclaim_reason:
+            try:
+                os.remove(LOCK_FILE)
+            except OSError:
+                pass
+            if _try_take_lock():
+                print(f"[browser_lock] reclaimed holder={holder or '<none>'} "
+                      f"reason={reclaim_reason} age={int(age)}s -> pid={os.getpid()} "
+                      f"platform=linkedin", file=sys.stderr)
+                break
+            time.sleep(LOCK_POLL_INTERVAL)
+            continue
+
+        # 5. Live UUID holder = parent Claude session / hook -> inherit.
+        if _UUID_RE.match(holder or ""):
+            _LOCK_SESSION_ID = holder
+            _LOCK_INHERITED = True
+            break
+
+        # 6. Live python:PID peer -> real contention. Wait, then give up. Reaching
+        # the deadline now means the holder is genuinely alive (dead ones were
+        # reclaimed above), NOT the defect-a starvation. peer_alive=1 is the tell.
+        if time.time() >= deadline:
+            print(json.dumps({
+                "ok": False,
+                "error": "profile_locked",
+                "detail": (
+                    f"holder={holder} age={int(age)}s "
+                    f"waited={LOCK_WAIT_MAX}s peer_alive=1"
+                ),
+            }))
+            sys.exit(1)
+        time.sleep(LOCK_POLL_INTERVAL)
+        continue
+
+
+def _is_login_or_checkpoint(url: str) -> bool:
+    if not url:
+        return True
+    return any(
+        marker in url
+        for marker in (
+            "/login",
+            "/checkpoint",
+            "/uas/login",
+            "linkedin.com/authwall",
+        )
+    )
+
+
+def _read_devtools_active_port() -> Optional[int]:
+    """Return the CDP port the linkedin-agent MCP Chrome is listening on.
+
+    The persistent profile dir holds a `DevToolsActivePort` file written
+    by Chrome on startup whenever `--remote-debugging-port=0` is passed
+    (the linkedin-agent MCP launches Chrome that way). First line is the
+    port, second line is the browser uuid path. Missing file -> None
+    (MCP is cold; caller raises RuntimeError — cold-launch removed
+    2026-05-27, never attach to the wrong profile).
+    """
+    port_file = os.path.join(PROFILE_DIR, "DevToolsActivePort")
+    try:
+        with open(port_file) as f:
+            first = f.readline().strip()
+        port = int(first)
+        if port <= 0 or port >= 65536:
+            return None
+        return port
+    except (FileNotFoundError, ValueError, OSError):
+        return None
+
+
+def _pid_listening_on(port: int) -> Optional[int]:
+    """Return the PID listening on a TCP port, via lsof. Best-effort.
+
+    Used purely for diagnostic logging in `_connect_to_running_or_launch`
+    so failure logs can answer "did we attach to an existing Chrome or
+    cold-launch one ourselves?" without guesswork. Never raises.
+    """
+    try:
+        out = subprocess.run(
+            ["lsof", "-ti", f":{port}", "-sTCP:LISTEN"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            timeout=3,
+        ).stdout.decode("utf-8", "replace").strip()
+        if out:
+            return int(out.splitlines()[0])
+    except (subprocess.TimeoutExpired, FileNotFoundError, ValueError, OSError):
+        pass
+    return None
+
+
+def _connect_to_running_or_launch(p, *, prefer_cdp: bool = True):
+    """Get a BrowserContext for LinkedIn via CDP attach to a running harness.
+
+    Cold-launch fallback REMOVED 2026-05-27. Per explicit user instruction:
+    the pipeline must NEVER spawn its own Chrome on the `linkedin` profile.
+    That fallback would attach to a *different* profile from the one the
+    harness Chrome owns (`browser-harness-linkedin`), and the two have
+    drifted in practice: the harness profile holds the active `li_at`
+    session cookie, the `linkedin` profile does not. Cold-launching it
+    sent every scrape straight to /authwall and silently masked the real
+    failure (the harness was unreachable).
+
+    Strategy now (harness-only, 2026-05-31):
+      1. If `LINKEDIN_CDP_URL` env var is set (skill/lib/linkedin-backend.sh
+         sets it to http://127.0.0.1:9556), attach to the linkedin-harness
+         Chrome via connect_over_cdp. Returns owns_context=False; caller
+         closes only the page they opened, never the context.
+      2. If that attach fails, RAISE. The legacy DevToolsActivePort fallback
+         to the linkedin-agent profile (~/.claude/browser-profiles/linkedin)
+         was REMOVED 2026-05-31: it silently attached to a SECOND Chrome
+         whenever the harness was momentarily unreachable, which is the
+         "two LinkedIn browsers in parallel" bug. The harness Chrome on :9556
+         is now the ONLY allowed LinkedIn browser. Never attach to a sibling
+         profile, never cold-launch.
+
+    `prefer_cdp` kept as a kwarg for caller-API stability but no longer
+    has a meaningful False branch (cold-launch and legacy attach are gone).
+
+    Returns:
+        (context, owns_context)  # owns_context is always False on success
+
+    Raises:
+        RuntimeError if no warm harness/MCP Chrome is reachable.
+    """
+    from playwright.sync_api import sync_playwright  # noqa: F401
+
+    last_err: Optional[Exception] = None
+
+    # Lane 1: explicit harness CDP URL (preferred — set by linkedin-backend.sh
+    # when the browser-harness Chrome is up on port 9556).
+    harness_cdp_url = os.environ.get("LINKEDIN_CDP_URL", "").strip()
+    if prefer_cdp and harness_cdp_url:
+        try:
+            browser = p.chromium.connect_over_cdp(
+                harness_cdp_url,
+                timeout=5000,
+            )
+            contexts = browser.contexts
+            if contexts:
+                print(
+                    f"[linkedin_browser] mode=harness_cdp_attach "
+                    f"url={harness_cdp_url} profile=browser-harness-linkedin",
+                    file=sys.stderr,
+                    flush=True,
+                )
+                _bh_activity_log("attach_harness", harness_cdp_url)
+                return contexts[0], False
+            last_err = RuntimeError("harness CDP attach: zero contexts")
+        except Exception as e:
+            last_err = e
+            print(
+                f"[linkedin_browser] harness_cdp_attach failed: {e}",
+                file=sys.stderr,
+                flush=True,
+            )
+
+    # Lane 2 (legacy DevToolsActivePort attach to the linkedin-agent profile
+    # ~/.claude/browser-profiles/linkedin) was REMOVED 2026-05-31. It let the
+    # pipeline silently attach to a SECOND Chrome (the retired linkedin-agent
+    # MCP browser) whenever the harness attach above failed — the root cause
+    # of the "two LinkedIn browsers in parallel" bug. The harness Chrome on
+    # :9556 is now the ONLY allowed LinkedIn browser.
+
+    # No warm harness Chrome reachable. Fail loudly — never attach to the
+    # legacy linkedin-agent profile, never cold-launch.
+    raise RuntimeError(
+        "linkedin_browser: harness Chrome (port 9556) not reachable via "
+        "LINKEDIN_CDP_URL. Legacy DevToolsActivePort + cold-launch fallbacks "
+        "were removed (they attached to the wrong profile and spawned a "
+        "second browser). Restart the linkedin-harness Chrome and retry. "
+        f"Last error: {last_err}"
+    )
+
+
+def unread_dms() -> dict:
+    """Scan LinkedIn /messaging/ sidebar in headed mode, read-only.
+
+    Cold-launch removed 2026-05-27 — this now requires the linkedin-harness
+    Chrome to be reachable via CDP; otherwise it returns
+    error='no_warm_browser' so the caller can surface the real cause
+    instead of silently attaching to a logged-out sibling profile.
+    """
+    from playwright.sync_api import sync_playwright
+
+    _acquire_browser_lock()
+
+    with sync_playwright() as p:
+        try:
+            context, _owns_context = _connect_to_running_or_launch(p)
+        except RuntimeError as e:
+            return {
+                "ok": False,
+                "error": "no_warm_browser",
+                "detail": str(e),
+            }
+
+        page = None
+        _reused_page = False
+        try:
+            # Reuse an existing harness tab instead of spawning a throwaway one
+            # (mirrors reddit_browser). new_page() also steals OS focus every
+            # call. Prefer a tab already on linkedin.com (not login/checkpoint),
+            # else the first open page; only new_page() when the context has no
+            # usable tab. A reused tab is left open in the finally below so the
+            # next consumer can reuse it too.
+            for pg in context.pages:
+                u = pg.url or ""
+                if "linkedin.com" in u and "login" not in u and "checkpoint" not in u:
+                    page, _reused_page = pg, True
+                    break
+            if page is None and context.pages:
+                page, _reused_page = context.pages[0], True
+            if page is None:
+                page = context.new_page()
+            try:
+                page.goto(
+                    "https://www.linkedin.com/messaging/",
+                    wait_until="domcontentloaded",
+                    timeout=30000,
+                )
+            except Exception as e:
+                return {
+                    "ok": False,
+                    "error": "navigation_failed",
+                    "detail": str(e),
+                }
+
+            # Settle: wait for the conversation list to render. LinkedIn's
+            # messaging UI lazy-loads after DOMContentLoaded.
+            try:
+                page.wait_for_selector(
+                    "ul.msg-conversations-container__conversations-list, "
+                    "ul[class*='conversations-list'], "
+                    "main [role='list']",
+                    timeout=10000,
+                )
+            except Exception:
+                pass  # we'll still try to read whatever's there
+            page.wait_for_timeout(1500)
+
+            cur_url = page.url
+            if _is_login_or_checkpoint(cur_url):
+                return {
+                    "ok": False,
+                    "error": "session_invalid",
+                    "url": cur_url,
+                }
+
+            # Read sidebar. Strategy:
+            #   - For each conversation list item, derive partner name
+            #     (bolded participant), preview text, time, and unread state.
+            #   - Unread signal: visual blue dot (.notification-badge--show)
+            #     OR data-test-unread, NOT generic [aria-label*=unread].
+            #     LinkedIn renders hover "Mark as unread" buttons that
+            #     contain the substring 'unread' on every thread.
+            #   - thread_url: try the <a href> if rendered; otherwise null.
+            threads = page.evaluate(
+                """
+                () => {
+                  const out = [];
+                  // Find conversation list items. LinkedIn renders these as
+                  // <li> inside the conversations list; fall back to any
+                  // [role=listitem] anchored under the messaging main.
+                  const candidates = document.querySelectorAll(
+                    "ul.msg-conversations-container__conversations-list > li, "
+                    + "ul[class*='conversations-list'] > li, "
+                    + "main [role='listitem']"
+                  );
+                  for (const item of candidates) {
+                    // Skip ad slots / non-conversation rows.
+                    const link = item.querySelector(
+                      "a.msg-conversation-listitem__link, a[href*='/messaging/thread/']"
+                    );
+                    const innerText = (item.innerText || "").trim();
+                    if (!innerText) continue;
+
+                    // Unread badge: blue dot. Avoid the broad
+                    // [aria-label*=unread] selector which matches the
+                    // hover "Mark as unread" affordance.
+                    const blueDot = item.querySelector(
+                      ".notification-badge--show, "
+                      + "[data-test-unread='true'], "
+                      + ".msg-conversation-card__unread-count, "
+                      + ".notification-badge.notification-badge--show"
+                    );
+                    const unread = !!blueDot;
+
+                    // Partner name: prefer h3 / participant-names node.
+                    const nameEl = item.querySelector(
+                      "h3, .msg-conversation-listitem__participant-names, "
+                      + ".msg-conversation-card__participant-names"
+                    );
+                    const partner = nameEl
+                      ? (nameEl.textContent || "").trim()
+                      : "";
+
+                    // Time element: usually a small time/timestamp span.
+                    const timeEl = item.querySelector(
+                      "time, .msg-conversation-listitem__time-stamp, "
+                      + ".msg-conversation-card__time-stamp"
+                    );
+                    const time = timeEl
+                      ? (timeEl.textContent || "").trim()
+                      : "";
+
+                    // Preview (snippet of last message). Take first text
+                    // node after the participant name that isn't the time.
+                    const previewEl = item.querySelector(
+                      ".msg-conversation-card__message-snippet, "
+                      + ".msg-conversation-listitem__message-snippet, "
+                      + "p.msg-conversation-card__message-snippet"
+                    );
+                    let preview = previewEl
+                      ? (previewEl.textContent || "").trim()
+                      : "";
+                    if (!preview) {
+                      // Fallback: trim partner+time off the innerText.
+                      preview = innerText
+                        .replace(partner, "")
+                        .replace(time, "")
+                        .trim();
+                    }
+
+                    let threadUrl = null;
+                    if (link) {
+                      const href = link.getAttribute("href") || "";
+                      if (href && /\\/messaging\\/thread\\//.test(href)) {
+                        threadUrl = href.startsWith("http")
+                          ? href
+                          : ("https://www.linkedin.com" + href);
+                      }
+                    }
+
+                    out.push({
+                      partner,
+                      preview: preview,
+                      time,
+                      thread_url: threadUrl,
+                      unread,
+                    });
+                  }
+                  return JSON.stringify(out);
+                }
+                """
+            )
+            try:
+                threads_list = json.loads(threads or "[]")
+            except json.JSONDecodeError:
+                threads_list = []
+
+            unread_count = sum(1 for t in threads_list if t.get("unread"))
+
+            return {
+                "ok": True,
+                "url": cur_url,
+                "total_threads": len(threads_list),
+                "unread_count": unread_count,
+                "threads": threads_list,
+            }
+
+        finally:
+            # CDP-attach branch: NEVER close the context — that would
+            # terminate the harness Chrome we just attached to. Only close a
+            # page WE created; if we reused an existing tab, leave it open so
+            # the next consumer can reuse it (tab-reuse convention).
+            if page is not None and not _reused_page:
+                try:
+                    page.close()
+                except Exception:
+                    pass
+
+
+def unread_dms_with_retry(max_attempts: int = 2) -> dict:
+    """Wrap unread_dms with one retry on TargetClosedError-style transient
+    failures. The headed Chrome launch races against atexit lock release on
+    the previous run; a single retry after a short delay clears most cases.
+    """
+    last_result: dict = {"ok": False, "error": "no_attempts"}
+    for attempt in range(1, max_attempts + 1):
+        try:
+            result = unread_dms()
+        except Exception as e:
+            result = {
+                "ok": False,
+                "error": "exception",
+                "detail": f"{type(e).__name__}: {e}",
+                "attempt": attempt,
+            }
+        last_result = result
+        # Only retry on transient browser-target failures, not on
+        # session_invalid / profile_locked which won't self-heal.
+        err = (result.get("error") or "").lower()
+        detail = (result.get("detail") or "").lower()
+        transient = (
+            "targetclosed" in detail
+            or "target page" in detail
+            or "browser has been closed" in detail
+            or err == "navigation_failed"
+        )
+        if result.get("ok") or not transient or attempt >= max_attempts:
+            if attempt > 1:
+                result["retry_attempt"] = attempt
+            return result
+        print(
+            f"[linkedin_browser] transient failure attempt {attempt}: "
+            f"{result.get('detail') or result.get('error')}; retrying...",
+            file=sys.stderr,
+        )
+        time.sleep(2)
+    return last_result
+
+
+def main():
+    # Guard: only authorized pipelines may invoke this helper. Other Claude
+    # subprocess planners (post_reddit, post_twitter, etc.) auto-load
+    # CLAUDE.md as system context, see this helper documented there, and
+    # have wandered off-task to "smoke test" it — racing the linkedin
+    # profile's SingletonLock and triggering server-side session
+    # invalidation. The legitimate caller sets the matching env var
+    # immediately before invoking; nothing else does.
+    if os.environ.get("SOCIAL_AUTOPOSTER_LINKEDIN_PRECHECK") != "1":
+        print(
+            json.dumps({
+                "ok": False,
+                "error": "unauthorized_caller",
+                "detail": (
+                    "linkedin_browser.py is invoked only by the "
+                    "engage-dm-replies pre-check. Set "
+                    "SOCIAL_AUTOPOSTER_LINKEDIN_PRECHECK=1 from the caller "
+                    "if this invocation is legitimate. (For SERP discovery, "
+                    "use scripts/discover_linkedin_candidates.py instead.)"
+                ),
+            }),
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    if len(sys.argv) < 2:
+        print(__doc__)
+        sys.exit(2)
+    cmd = sys.argv[1]
+    if cmd == "unread-dms":
+        result = unread_dms_with_retry()
+        print(json.dumps(result, indent=2))
+        sys.exit(0 if result.get("ok") else 1)
+    print(f"Unknown command: {cmd}", file=sys.stderr)
+    sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()