@m13v/s4l 1.6.197-rc.7

package/scripts/capture_thread_media.py

@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+"""Deterministically capture + persist + format thread media for the prep step.
+
+Companion to the main Twitter posting cycle (run-twitter-cycle.sh Phase 2b-prep,
+2026-06-03 thread-media feature). The prep prompt forbids the model from calling
+twitter_browser.py, so the SHELL pre-fetches the media of every candidate the
+model is about to draft against, in ONE cheap browser pass, then:
+
+  1. persists each candidate's media into twitter_candidates.thread_media (so the
+     record survives independent of the model), and
+  2. emits a "MEDIA CONTEXT" prompt block to stdout so the reply-writer can "see"
+     the image / video / GIF / link-card it is replying to instead of replying
+     text-blind.
+
+Input: a TSV file, one `candidate_id<TAB>tweet_url` per line (built by the
+CANDIDATE_BLOCK loop in run-twitter-cycle.sh).
+
+Media shape per item: {url, alt, type}, type in image|video|gif|card. An empty
+list [] is valid and meaningful ("captured, none found", distinct from NULL =
+"never captured").
+
+Usage:
+    python3 scripts/capture_thread_media.py --urls-file /tmp/urls.tsv \\
+        [--scroll 1] [--no-persist]
+
+Output:
+    stdout  -> the MEDIA CONTEXT prompt block (empty string if no media at all)
+    stderr  -> per-candidate diagnostics + a final JSON summary line
+"""
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from http_api import api_get, api_patch  # noqa: E402
+
+# Imported lazily inside main() so --help works without a browser / playwright.
+
+
+def _load_pairs(urls_file):
+    """Return [(candidate_id:str, url:str)] from a `cid<TAB>url` TSV file."""
+    pairs = []
+    with open(urls_file) as f:
+        for line in f:
+            line = line.rstrip("\n")
+            if not line.strip():
+                continue
+            if "\t" in line:
+                cid, url = line.split("\t", 1)
+            else:
+                # Tolerate a bare-URL line (no cid); skip it, we can't key it.
+                continue
+            cid = cid.strip()
+            url = url.strip()
+            if cid and url:
+                pairs.append((cid, url))
+    return pairs
+
+
+def _persist(candidate_id, media, repost=None):
+    """Persist media (+ repost provenance) onto twitter_candidates via set_media.
+
+    repost is {"is_repost": bool, "reposted_by": str} or None.
+
+    POSITIVE-ONLY for repost: we send is_repost/reposted_by ONLY when we detected
+    a repost (is_repost True). The candidate URL is the ORIGINAL tweet permalink,
+    where X does NOT render the "<X> reposted" timeline banner, so fresh detection
+    here is almost always False; sending that False would clobber the authoritative
+    flag set at discovery time (the server COALESCEs only on null, not on false).
+    Omitting the keys leaves COALESCE(null, is_repost) = the stored value intact.
+    """
+    payload = {"id": int(candidate_id), "action": "set_media", "thread_media": media}
+    if repost is not None and bool(repost.get("is_repost", False)):
+        payload["is_repost"] = True
+        payload["reposted_by"] = repost.get("reposted_by", "") or ""
+    resp = api_patch(
+        "/api/v1/twitter-candidates/by-id", payload,
+        ok_on_conflict=True, ok_on_404=True,
+    )
+    if (resp or {}).get("_not_found"):
+        return False, "CANDIDATE_NOT_FOUND"
+    if not (resp or {}).get("ok"):
+        return False, (resp or {}).get("error") or "SET_MEDIA_FAILED"
+    return True, None
+
+
+def _fetch_stored_repost(candidate_id):
+    """Read the repost flag stored at discovery time for one candidate.
+
+    Repost provenance is detected and stored by the DISCOVERY scan (the timeline
+    is the only place X renders the "<X> reposted" banner). The prep step runs on
+    the original-tweet permalink, which never shows that banner, so we read the
+    authoritative stored value here to surface it to the model in the prompt block.
+
+    Returns {"is_repost": bool, "reposted_by": str}; defaults to a non-repost on
+    any error / missing candidate (fail-open: never block the cycle).
+    """
+    try:
+        resp = api_get(
+            "/api/v1/twitter-candidates/by-id",
+            {"id": int(candidate_id)}, ok_on_404=True,
+        )
+    except Exception:
+        return {"is_repost": False, "reposted_by": ""}
+    cand = (resp or {}).get("candidate") or {}
+    return {
+        "is_repost": bool(cand.get("is_repost", False)),
+        "reposted_by": cand.get("reposted_by", "") or "",
+    }
+
+
+def _format_item(item):
+    """One '  - <type>: "<alt>" (<url>)' line for the prompt block."""
+    t = (item.get("type") or "media").strip()
+    alt = (item.get("alt") or "").strip()
+    url = (item.get("url") or "").strip()
+    alt_part = f'"{alt}"' if alt else "[no description]"
+    return f"  - {t}: {alt_part} ({url})"
+
+
+def _build_block(captured):
+    """captured: list of (candidate_id, media_list, repost). Returns prompt block.
+
+    A section is emitted for any candidate that has media OR is a repost, so the
+    model is told about repost provenance even when the tweet carries no media.
+    """
+    sections = []
+    for cid, media, repost in captured:
+        is_repost = bool((repost or {}).get("is_repost"))
+        if not media and not is_repost:
+            continue
+        body = []
+        if is_repost:
+            rb = ((repost or {}).get("reposted_by") or "").strip()
+            who = f"@{rb}" if rb else "another account"
+            body.append(
+                f"  - REPOST: this is a repost surfaced by {who}. The tweet text "
+                "and any media below were written by the ORIGINAL author, not the "
+                "reposter. Reply to the original author's content; do not address "
+                "the reposter."
+            )
+        if media:
+            body.extend(_format_item(it) for it in media)
+        sections.append(f"Candidate {cid}:\n" + "\n".join(body))
+    if not sections:
+        return ""
+    header = (
+        "## MEDIA IN THESE THREADS\n"
+        "Some candidate threads contain images, videos, GIFs, link-cards, or are "
+        "reposts. This is part of the content you are replying to: react to what "
+        "the tweet VISUALLY shows, not just its text, and treat reposted content "
+        "as the original author's. A candidate NOT listed here had no media and is "
+        "not a repost (or capture was skipped); reply to its text as usual. "
+        "Descriptions marked [no description] mean the media had no alt-text, so "
+        "infer from the thread text and the media type."
+    )
+    return header + "\n\n" + "\n".join(sections) + "\n"
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--urls-file", required=True,
+                   help="TSV: one candidate_id<TAB>tweet_url per line.")
+    p.add_argument("--scroll", type=int, default=1,
+                   help="scroll_count passed to the batch scraper (default 1).")
+    p.add_argument("--no-persist", action="store_true",
+                   help="Skip writing thread_media to the DB (format only).")
+    args = p.parse_args()
+
+    pairs = _load_pairs(args.urls_file)
+    if not pairs:
+        # Nothing to do; emit empty block, exit clean so the shell continues.
+        print("", end="")
+        print(json.dumps({"captured": 0, "persisted": 0, "with_media": 0, "reposts": 0}), file=sys.stderr)
+        return
+
+    # Lazy import so an empty/short-circuit run never pays the playwright cost.
+    from twitter_browser import scrape_many_thread_media
+
+    urls = [url for _cid, url in pairs]
+    try:
+        batch = scrape_many_thread_media(urls, scroll_count=args.scroll)
+    except Exception as e:
+        # Browser failure must NOT break the cycle: emit empty block, log, exit 0.
+        print("", end="")
+        print(json.dumps({"error": "SCRAPE_FAILED", "detail": str(e)}), file=sys.stderr)
+        return
+
+    # Map url -> {media, repost} (results echo the input url verbatim as thread_url).
+    by_url = {}
+    for r in (batch or {}).get("results", []):
+        by_url[r.get("thread_url")] = {
+            "media": r.get("media") or [],
+            "repost": {
+                "is_repost": bool(r.get("is_repost", False)),
+                "reposted_by": r.get("reposted_by", "") or "",
+            },
+        }
+
+    captured = []          # (cid, media, repost) for ALL pairs (media may be [])
+    persisted = 0
+    with_media = 0
+    reposts = 0
+    access_checked = 0
+    access_not_visible = 0
+    access_check_limit = int(os.environ.get("S4L_TWITTER_EMPTY_MEDIA_ACCESS_CHECKS", "3"))
+    access_wait_ms = int(os.environ.get("S4L_TWITTER_EMPTY_MEDIA_ACCESS_WAIT_MS", "4000"))
+    empty_capture_unreliable = None
+    for cid, url in pairs:
+        rec = by_url.get(url) or {}
+        media = rec.get("media", [])
+        access = None
+        if not media:
+            # Empty media is only meaningful when the tweet itself rendered.
+            # If x.com served an empty app shell / block / protected page, do
+            # NOT persist [] because [] means "captured successfully, no media";
+            # leaving NULL lets a later cycle retry instead of poisoning the row.
+            if empty_capture_unreliable:
+                access = empty_capture_unreliable
+            elif access_checked < access_check_limit:
+                try:
+                    from twitter_access_check import diagnose_tweet_access
+                    access = diagnose_tweet_access(
+                        url, wait_ms=access_wait_ms, include_public=False,
+                    )
+                    access_checked += 1
+                except Exception as e:
+                    access = {"status": "access_check_failed", "reason": str(e)}
+                    access_checked += 1
+            else:
+                access = {"status": "unchecked", "reason": "empty_media_access_check_cap"}
+            status = access.get("status")
+            if status not in ("visible", "visible_no_anchor", "unchecked"):
+                access_not_visible += 1
+                if status in ("app_not_hydrated", "app_error", "logged_out", "access_check_failed", "unknown"):
+                    empty_capture_unreliable = access
+                print(
+                    f"[capture_thread_media] cid={cid} url={url} "
+                    f"access_status={status} reason={access.get('reason')} "
+                    "leaving thread_media NULL",
+                    file=sys.stderr,
+                )
+                captured.append((cid, media, {"is_repost": False, "reposted_by": ""}))
+                continue
+        fresh = rec.get("repost", {"is_repost": False, "reposted_by": ""})
+        # Authoritative repost flag comes from discovery (stored). Fresh permalink
+        # detection is a rare bonus; prefer stored, fall back to fresh.
+        stored = _fetch_stored_repost(cid)
+        if stored.get("is_repost"):
+            repost = stored
+        elif fresh.get("is_repost"):
+            repost = fresh
+        else:
+            repost = {"is_repost": False, "reposted_by": ""}
+        captured.append((cid, media, repost))
+        if media:
+            with_media += 1
+        if repost.get("is_repost"):
+            reposts += 1
+        if not args.no_persist:
+            # _persist is positive-only for repost: pass the FRESH detection (so a
+            # newly-seen banner is recorded) but never the stored value back (no
+            # round-trip clobber). Media is always persisted.
+            ok, err = _persist(cid, media, fresh)
+            if ok:
+                persisted += 1
+            else:
+                print(f"[capture_thread_media] persist failed cid={cid}: {err}",
+                      file=sys.stderr)
+
+    block = _build_block(captured)
+    # stdout = the prompt block ONLY (shell captures it verbatim).
+    sys.stdout.write(block)
+    print(json.dumps({
+        "captured": len(captured),
+        "persisted": persisted,
+        "with_media": with_media,
+        "reposts": reposts,
+        "access_checked": access_checked,
+        "access_not_visible": access_not_visible,
+        "urls_visited": (batch or {}).get("urls_visited", 0),
+    }), file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/check_browser_lock_health.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# Health check for the browser session-lock fix (2026-06-16).
+# Full context: docs/twitter_browser_lock.md. Logic test: scripts/test_browser_lock.py.
+#
+# Prints [ok ] / [BAD] / [i  ] lines so you can tell at a glance whether the fix is
+# present in code AND behaving in production. Exits non-zero if any [BAD] is found.
+#
+#   bash scripts/check_browser_lock_health.sh [HOURS]   # default lookback 24h
+#
+# What it checks (see docs §4/§5 for the why):
+#   1. fix still present in twitter_browser.py + linkedin_browser.py (catch a revert)
+#   2. defect-b `rm -f` has NOT crept back into skill/*.sh
+#   3. reclaim markers firing  = fix actively catching dead holders (positive signal)
+#   4. starvation giveups WITHOUT the peer-alive tell = defect (a) recurring (BAD)
+#   5. shell-lock trap_rm owner=OTHER = a pipeline deleted a LIVE peer's lock (BAD)
+set -u
+cd "$(dirname "$0")/.."
+LOGS="skill/logs"
+HOURS="${1:-24}"
+bad=0
+
+# Dated per-run logs that are BOTH within the lookback window AND newer than the lock
+# code file. The `-newer` clause is the key: it counts only runs that started after the
+# fix (or, if the fix is ever reverted, after that revert) -- so day-one pre-fix
+# starvation noise is excluded automatically, and a real regression still surfaces.
+# (NOT launchd-*.log: those are append-only, so their mtime says nothing about when a
+# line inside was written.)
+recent=$(find "$LOGS" -maxdepth 1 -name '*2026-*.log' -mmin "-$((HOURS*60))" \
+           -newer scripts/twitter_browser.py 2>/dev/null | grep -v 'launchd-' || true)
+[ -z "$recent" ] && recent="/dev/null"   # guard: never let grep read stdin
+
+echo "== browser-lock health (last ${HOURS}h of dated per-run logs) =="
+
+# 1. fix present in code
+if grep -q _is_python_holder_alive scripts/twitter_browser.py 2>/dev/null \
+   && grep -q _is_python_holder_alive scripts/linkedin_browser.py 2>/dev/null; then
+  echo "[ok ] fix present (twitter_browser.py + linkedin_browser.py)"
+else
+  echo "[BAD] fix MISSING from code -> reverted (re-apply from docs/twitter_browser_lock.md)"; bad=1
+fi
+
+# 2. defect-b rm -f gone from shells (anchored so the explanatory comment is not a hit).
+#    Scope to *.sh only -- never recurse skill/ (it holds a huge claude-sessions/ tree).
+if grep -hEq '^[[:space:]]*rm -f .*twitter-browser-lock\.json' skill/*.sh skill/lib/*.sh 2>/dev/null; then
+  echo "[BAD] defect-b: an actual 'rm -f ...twitter-browser-lock.json' is back in skill/*.sh"; bad=1
+else
+  echo "[ok ] no rm -f of the session lock in skill/*.sh"
+fi
+
+# 3. positive: reclaim markers (each = a dead holder caught that USED to starve the fleet)
+rec=$(grep -hoE '\[browser_lock\] reclaimed .*reason=[a-z_]+' $recent 2>/dev/null | wc -l | tr -d ' ')
+recd=$(grep -hoE '\[browser_lock\] reclaimed .*reason=dead_python' $recent 2>/dev/null | wc -l | tr -d ' ')
+echo "[i  ] reclaim markers fired: ${rec:-0} (of which dead_python: ${recd:-0}) -- 0 is fine if nothing crashed"
+
+# 4. starvation: twitter giveup without 'peer alive' / linkedin profile_locked without 'peer_alive'
+bad_tw=$(grep -hE 'locked by session .* giving up' $recent 2>/dev/null | grep -vc 'peer alive' || true)
+bad_li=$(grep -hE 'profile_locked' $recent 2>/dev/null | grep -vc 'peer_alive' || true)
+bad_tw=${bad_tw:-0}; bad_li=${bad_li:-0}
+if [ "$bad_tw" -gt 0 ] || [ "$bad_li" -gt 0 ]; then
+  echo "[BAD] old-format starvation giveups: twitter=$bad_tw linkedin=$bad_li (defect a recurring?)"; bad=1
+else
+  echo "[ok ] no old-format starvation giveups (twitter + linkedin)"
+fi
+
+# 5. shell-lock: dangerous trap_rm owner=OTHER (deleting a live peer's shell lock).
+#    NOTE: 'event=stale_reclaim ... owner=OTHER' is LEGITIMATE (reclaiming a dead holder),
+#    only 'event=trap_rm ... owner=OTHER' is the bad one.
+if [ -f "$LOGS/lock-events.log" ]; then
+  to=$(grep -cE 'event=trap_rm .*owner=OTHER' "$LOGS/lock-events.log" 2>/dev/null); to=${to:-0}
+  if [ "$to" -gt 0 ]; then
+    echo "[BAD] shell trap_rm owner=OTHER x$to (a pipeline deleted a LIVE peer's shell lock)"; bad=1
+  else
+    echo "[ok ] shell-lock: no trap_rm owner=OTHER (live-lock deletes)"
+  fi
+fi
+
+echo "=================================================="
+if [ "$bad" -ne 0 ]; then
+  echo "RESULT: ATTENTION NEEDED (see [BAD] above)"; exit 1
+fi
+echo "RESULT: HEALTHY"

package/scripts/check_external_pool_depth.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+"""Email-alert when any external_short_links pool runs low.
+
+For every project with `external_short_links: true` in config.json, checks the
+(project, platform) pool depth against two thresholds:
+
+  WARN     -- available / total <= 0.20  (i.e., 80% of the pool has been claimed)
+  CRITICAL -- available == 0             (pool exhausted, next post returns
+                                          {ok: false, error: 'pool_exhausted'})
+
+Emails go to i@m13v.com via the Gmail DWD lane. State lives in the
+`external_pool_alerts` table so we don't spam: same (project, platform,
+severity) is suppressed for 24h after a send.
+
+Designed to run on launchd every 30 min. The 20% threshold gives 7-30 days of
+runway warning before a CRITICAL fires (at typical 5-15 posts/day burn). The
+CRITICAL alert is the "on error" case the user asked for; it fires at most
+once per 24h per (project, platform).
+
+Usage:
+  python3 scripts/check_external_pool_depth.py            # check + alert
+  python3 scripts/check_external_pool_depth.py --dry-run  # report only, no email/state writes
+  python3 scripts/check_external_pool_depth.py --force    # ignore 24h cooldown
+"""
+from __future__ import annotations
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from email.message import EmailMessage
+import base64
+
+REPO_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, os.path.join(REPO_DIR, 'scripts'))
+sys.path.insert(0, os.path.expanduser('~/gmail-api'))
+
+from http_api import api_get, api_post  # noqa: E402
+
+WARN_REMAINING_RATIO = 0.20
+COOLDOWN_HOURS = 24
+NOTIFICATION_EMAIL = os.environ.get('NOTIFICATION_EMAIL', 'i@m13v.com')
+PLATFORMS = ['reddit', 'twitter', 'linkedin', 'github_issues', 'moltbook']
+CONFIG_PATH = os.path.join(REPO_DIR, 'config.json')
+
+
+def _scrub_dashes(s: str) -> str:
+    return s.replace('—', ',').replace('–', ',') if s else s
+
+
+def _load_external_projects() -> list[dict]:
+    with open(CONFIG_PATH) as f:
+        cfg = json.load(f)
+    return [p for p in cfg.get('projects', []) if p.get('external_short_links')]
+
+
+def _pool_depth(project: str, platform: str) -> tuple[int, int]:
+    resp = api_get(
+        "/api/v1/post-links/pool-depth",
+        query={"project_name": project, "platform": platform},
+    )
+    d = resp.get("data") or {}
+    return int(d.get("available") or 0), int(d.get("total") or 0)
+
+
+def _recent_alert_exists(project: str, platform: str, severity: str) -> bool:
+    resp = api_get(
+        "/api/v1/external-pool-alerts",
+        query={
+            "project_name": project,
+            "platform": platform,
+            "severity": severity,
+            "within_hours": COOLDOWN_HOURS,
+        },
+    )
+    return bool((resp.get("data") or {}).get("recent"))
+
+
+def _record_alert(project: str, platform: str, severity: str,
+                  available: int, total: int, ratio: float) -> None:
+    api_post(
+        "/api/v1/external-pool-alerts",
+        {
+            "project_name": project,
+            "platform": platform,
+            "severity": severity,
+            "available": available,
+            "total": total,
+            "ratio": ratio,
+        },
+    )
+
+
+def _gmail_send(subject: str, body: str) -> None:
+    from gmail_dwd_client import gmail_for
+    msg = EmailMessage()
+    msg['Subject'] = _scrub_dashes(subject)
+    msg['From'] = 'social-autoposter <i@m13v.com>'
+    msg['To'] = NOTIFICATION_EMAIL
+    msg.set_content(_scrub_dashes(body))
+    raw = base64.urlsafe_b64encode(msg.as_bytes()).decode('ascii')
+    client = gmail_for('i@m13v.com')
+    client.service.users().messages().send(userId='me', body={'raw': raw}).execute()
+
+
+def _format_subject(project: str, platform: str, severity: str,
+                    available: int, total: int) -> str:
+    pct = f"{(available / total * 100):.0f}%" if total else "0%"
+    return f"[POOL {severity}] {project}/{platform}: {available}/{total} left ({pct})"
+
+
+def _format_body(project: str, platform: str, severity: str,
+                 available: int, total: int, ratio: float,
+                 destinations: list[dict]) -> str:
+    lines = [
+        f"Severity:     {severity}",
+        f"Project:      {project}",
+        f"Platform:     {platform}",
+        f"Available:    {available}",
+        f"Total minted: {total}",
+        f"Remaining:    {ratio*100:.1f}%",
+        "",
+    ]
+    if severity == 'CRITICAL':
+        lines += [
+            "The pool is exhausted. The next post for this (project, platform) will",
+            "return {ok: false, error: 'pool_exhausted'} and skip. Refill IMMEDIATELY:",
+            "",
+        ]
+    else:
+        lines += [
+            f"Pool has dropped under {int(WARN_REMAINING_RATIO*100)}% remaining. Schedule a refill",
+            "in the next few days to avoid hitting pool_exhausted on the next cycle.",
+            "",
+        ]
+    lines += [
+        "Refill commands (in ~/social-autoposter):",
+        "  python3 scripts/mint_kent_pool.py        # Kent clients (Runner/Agora/Podlog)",
+        "  # for other external clients: extend mint_kent_pool.py SITE_CONFIG first",
+        "",
+        "Pool status snapshot:",
+        "  python3 scripts/mint_kent_pool.py --status",
+        "",
+    ]
+    if destinations:
+        lines += ["Per-destination breakdown for this slice:"]
+        for d in destinations[:20]:
+            lines.append(
+                f"  {d['minted_session'][-65:]:<65} "
+                f"avail={d['available']:>5} claimed={d['claimed']:>5}"
+            )
+        if len(destinations) > 20:
+            lines.append(f"  ... and {len(destinations) - 20} more destinations")
+        lines.append("")
+    lines += [
+        f"Cooldown:     {COOLDOWN_HOURS}h per (project, platform, severity)",
+        f"Re-fire:      python3 scripts/check_external_pool_depth.py --force",
+    ]
+    return "\n".join(lines)
+
+
+def _destinations_for_slice(project: str, platform: str) -> list[dict]:
+    resp = api_get(
+        "/api/v1/post-links/pool-depth",
+        query={
+            "project_name": project,
+            "platform": platform,
+            "with_destinations": "1",
+        },
+    )
+    return (resp.get("data") or {}).get("destinations") or []
+
+
+def check(dry_run: bool = False, force: bool = False,
+          warn_ratio: float = WARN_REMAINING_RATIO,
+          limit: int | None = None) -> dict:
+    projects = _load_external_projects()
+    fired: list[dict] = []
+    skipped_cooldown: list[dict] = []
+    healthy: list[dict] = []
+    for p in projects:
+        project_name = p['name']
+        for platform in PLATFORMS:
+            available, total = _pool_depth(project_name, platform)
+            if total == 0:
+                continue
+            ratio = available / total if total > 0 else 0.0
+            if available == 0:
+                severity = 'CRITICAL'
+            elif ratio <= warn_ratio:
+                severity = 'WARN'
+            else:
+                healthy.append({
+                    'project': project_name, 'platform': platform,
+                    'available': available, 'total': total, 'ratio': ratio,
+                })
+                continue
+            key = (project_name, platform, severity)
+            if not force and _recent_alert_exists(*key):
+                skipped_cooldown.append({
+                    'project': project_name, 'platform': platform,
+                    'severity': severity, 'available': available, 'total': total,
+                })
+                continue
+            fired_row = {
+                'project': project_name, 'platform': platform,
+                'severity': severity, 'available': available, 'total': total,
+                'ratio': ratio,
+            }
+            fired.append(fired_row)
+            if dry_run:
+                continue
+            if limit is not None and len(fired) > limit:
+                continue
+            destinations = _destinations_for_slice(project_name, platform)
+            subject = _format_subject(project_name, platform, severity, available, total)
+            body = _format_body(project_name, platform, severity, available, total,
+                                ratio, destinations)
+            try:
+                _gmail_send(subject, body)
+                _record_alert(project_name, platform, severity,
+                              available, total, ratio)
+            except Exception as e:
+                fired_row['send_error'] = str(e)
+                print(f"[pool-check] email send failed for {project_name}/{platform}: {e}",
+                      file=sys.stderr)
+    return {
+        'checked_at': datetime.now(timezone.utc).isoformat(),
+        'fired': fired,
+        'skipped_cooldown': skipped_cooldown,
+        'healthy_count': len(healthy),
+        'dry_run': dry_run,
+    }
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument('--dry-run', action='store_true',
+                    help='compute and report, do not email or write state')
+    ap.add_argument('--force', action='store_true',
+                    help='ignore 24h cooldown, re-fire matching alerts')
+    ap.add_argument('--warn-ratio', type=float, default=WARN_REMAINING_RATIO,
+                    help=f'WARN threshold for available/total (default {WARN_REMAINING_RATIO})')
+    ap.add_argument('--limit', type=int, default=None,
+                    help='cap the number of alert emails per run (smoke testing)')
+    args = ap.parse_args()
+    result = check(dry_run=args.dry_run, force=args.force,
+                   warn_ratio=args.warn_ratio, limit=args.limit)
+    print(json.dumps(result, indent=2, default=str))
+
+
+if __name__ == '__main__':
+    main()

package/scripts/check_unread_web_chats.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+"""Check for web-chat threads with unread visitor messages (HTTP-only).
+
+Reads GET /api/v1/web-chat/unread, which (1) recovers stuck threads and
+(2) returns each unread, claimable thread with its first 200 messages embedded
+in one round trip. Replaces the inline psycopg2 reads.
+
+Prints a JSON array of:
+  { thread_id, project, visitor_email, visitor_name, unread, last_message,
+    page_url, messages: [{ id, text, sender, sender_name, created_at, read }] }
+"""
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from http_api import api_get
+
+
+def main():
+    resp = api_get("/api/v1/web-chat/unread")
+    threads = (resp.get("data") or {}).get("threads") or []
+    print(json.dumps(threads))
+
+
+if __name__ == "__main__":
+    main()