@m13v/s4l 1.6.197-rc.7

package/scripts/log_run.py

@@ -0,0 +1,364 @@
+#!/usr/bin/env python3
+"""Append a summary line to the persistent run monitor log.
+
+Usage:
+    python3 scripts/log_run.py --script post_reddit --posted 5 --skipped 2 --failed 0 --cost 3.45 --elapsed 600
+"""
+
+import argparse
+import os
+import sys
+from datetime import datetime, timedelta, timezone
+
+LOG_PATH = os.path.expanduser("~/social-autoposter/skill/logs/run_monitor.log")
+
+
+# Map a script-name prefix to the blocklist platform value. The blocklist
+# table uses canonical 'x' for Twitter; everything else matches the prefix.
+_PLATFORM_MAP = [
+    ("reddit", "reddit"),
+    ("twitter", "x"),
+    ("linkedin", "linkedin"),
+    ("github", "github_issues"),
+    ("instagram", "instagram"),
+]
+
+
+def _platform_from_script(script_name):
+    name = (script_name or "").lower()
+    for prefix, plat in _PLATFORM_MAP:
+        if prefix in name:
+            return plat
+    return None
+
+
+def _detect_escape_hatch(script_name, elapsed_seconds):
+    """Query /api/v1/blocklist for LLM/manual escape-hatch firings during
+    this run window, filtered by the script's platform.
+
+    Returns (count, details_list) where details_list contains 'handle:class'
+    strings. Velocity-auto rows are EXCLUDED — they fire programmatically
+    via the route.ts SQL path on every reply and would flood the pill on
+    discovery cycles. We only surface model-judgment / operator-judgment
+    classifications (bot, engagement_loop, manual_block).
+
+    Fail-safe: any API error returns (0, []) so the run line still writes.
+    """
+    if not elapsed_seconds:
+        return 0, []
+    platform = _platform_from_script(script_name)
+    if not platform:
+        return 0, []
+    try:
+        sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+        from http_api import api_get  # noqa: E402
+        cutoff = datetime.now(timezone.utc) - timedelta(seconds=float(elapsed_seconds) + 30)
+        resp = api_get("/api/v1/blocklist", query={"platform": platform, "limit": 100})
+        rows = ((resp or {}).get("data") or {}).get("blocklist") or []
+        hits = []
+        for r in rows:
+            created_at = r.get("created_at")
+            if not created_at:
+                continue
+            try:
+                ts = datetime.fromisoformat(str(created_at).replace("Z", "+00:00"))
+            except Exception:
+                continue
+            # Rows are ordered DESC by created_at, so once we cross the
+            # cutoff every remaining row is older — short-circuit.
+            if ts < cutoff:
+                break
+            classification = r.get("classification") or ""
+            if classification not in ("bot", "engagement_loop", "manual_block"):
+                continue
+            handle = (r.get("handle") or "?").replace(",", "").replace(":", "")
+            hits.append(f"{handle}:{classification}")
+        return len(hits), hits
+    except Exception:
+        return 0, []
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Log a run summary line")
+    parser.add_argument("--script", required=True, help="Script name (e.g. post_reddit, engage_reddit)")
+    parser.add_argument("--posted", type=int, default=0, help="Number of successful posts")
+    parser.add_argument("--skipped", type=int, default=0, help="Number of skipped items")
+    parser.add_argument("--failed", type=int, default=0, help="Number of failures")
+    parser.add_argument("--cost", type=float, default=0.0, help="Total cost in USD")
+    parser.add_argument("--elapsed", type=float, default=0.0, help="Elapsed time in seconds")
+    parser.add_argument("--model", default="", help="Dominant Claude model id used in the run (optional)")
+    parser.add_argument("--replies-refreshed", type=int, default=0,
+                        help="Number of per-reply stat rows refreshed in this run "
+                             "(stats_*, engage_github). Surfaces as a separate pill "
+                             "in the dashboard Jobs table.")
+    parser.add_argument("--checked", type=int, default=0,
+                        help="Stats jobs only: rows the run actually hit the "
+                             "platform API for (Reddit JSON, fxtwitter, LinkedIn "
+                             "feed scrape, etc.). Excludes skipped-as-fresh and "
+                             "skipped-as-stable. Renders as 'checked' pill.")
+    parser.add_argument("--updated", type=int, default=0,
+                        help="Stats jobs only: legacy/back-compat field. Pre-2026-05-18 "
+                             "this was 'rows where any tracked metric moved' but it "
+                             "silently summed in Step 1 view-scrape counts too. Use "
+                             "`--changed` for the new clean semantics; keep `--updated` "
+                             "wired only for old log lines.")
+    parser.add_argument("--removed", type=int, default=0,
+                        help="Stats jobs only: posts newly flagged deleted/removed in this run. "
+                             "Renders as 'removed'.")
+    # 2026-05-18 stats-pill relabel pass. The legacy `updated` field conflated
+    # two distinct things (Step 1 view scrape count + Step 2 detail-leg
+    # changed count) which made "updated" balloon meaninglessly. The new
+    # split lets the dashboard show four clean pills:
+    #   scanned         -> total rows considered this run (= polled + skipped)
+    #   checked         -> rows we actually hit the platform API for
+    #   changed         -> subset of checked where any tracked metric moved
+    #   views-refreshed -> rows where the cheap view-scrape leg wrote a value
+    # All four are optional, additive to the existing stats_segment, and
+    # default to 0 so existing callers don't have to change.
+    parser.add_argument("--scanned", type=int, default=0,
+                        help="Stats jobs only: TOTAL rows considered this run "
+                             "(polled + skipped + bypassed-as-fresh). "
+                             "Renders as a 'scanned' pill on stats rows.")
+    parser.add_argument("--changed", type=int, default=0,
+                        help="Stats jobs only: subset of `checked` where any "
+                             "tracked metric actually moved. Renders as a "
+                             "'changed' pill. Distinct from `--updated` which "
+                             "stays for back-compat with the old field name.")
+    parser.add_argument("--views-refreshed", dest="views_refreshed", type=int, default=0,
+                        help="Stats jobs only: rows where the cheap view-scrape "
+                             "leg (Step 1 profile scrape on Reddit; built-in on "
+                             "Twitter) wrote a fresh view count. Distinct from "
+                             "`--changed`, which is the per-row JSON-API leg.")
+    parser.add_argument("--unavailable", type=int, default=0,
+                        help="Stats jobs (LinkedIn): posts where the platform "
+                             "explicitly returned a 'post unavailable' string. "
+                             "Subset of removed; rendered as a separate pill.")
+    parser.add_argument("--not-found", dest="not_found", type=int, default=0,
+                        help="Stats jobs (LinkedIn): posts still active but our "
+                             "comment couldn't be located. Renders as 'not_found'.")
+    parser.add_argument("--salvaged", type=int, default=0,
+                        help="Twitter cycle: number of pending candidates from "
+                             "prior cycles re-assigned to this batch in Phase 0. "
+                             "Surfaces as a 'salvaged' pill in the dashboard "
+                             "Result column so an operator can tell that work "
+                             "from a previously-failed cycle is being retried "
+                             "rather than lost. Optional; 0 = omit segment.")
+    # ---- Discovery-stage counters (Twitter cycle, mirrors LinkedIn) -----
+    # Twitter wires the same shape LinkedIn already exposes
+    # (queries / candidates_found / dropped_below_floor) so the dashboard can
+    # render a single 'discover' tooltip across platforms. Each is an
+    # independent integer flag; pass 0 / omit to skip the segment. Stay
+    # backward-compatible: emitted as `key=N` after `salvaged` and before
+    # the cost/elapsed pair so older log lines (no discovery info) still
+    # parse via the existing positional regex in bin/server.js.
+    parser.add_argument("--queries", type=int, default=0,
+                        help="Discovery: number of search queries the cycle "
+                             "actually ran (raw count, including duds). "
+                             "Twitter Phase 1 / LinkedIn Phase A.")
+    parser.add_argument("--duds", type=int, default=0,
+                        help="Discovery: subset of --queries that returned "
+                             "zero candidates. Used by the dashboard to show "
+                             "query-quality drift over time.")
+    parser.add_argument("--tweets-pulled", dest="tweets_pulled", type=int, default=0,
+                        help="Discovery: raw tweets/posts the scraper pulled "
+                             "before the floor filter. Twitter only — "
+                             "LinkedIn doesn't have a directly comparable "
+                             "raw-volume number.")
+    parser.add_argument("--candidates", type=int, default=0,
+                        help="Discovery: candidates that survived the "
+                             "post-floor filter (Twitter T0 snapshot rows / "
+                             "LinkedIn candidates_found). Includes salvaged "
+                             "rows from prior cycles.")
+    parser.add_argument("--above-floor", dest="above_floor", type=int, default=0,
+                        help="Discovery: candidates that cleared the "
+                             "review-cap floor — for Twitter this is "
+                             "Δ≥10 momentum (the same signal that flips "
+                             "POST_LIMIT 1→3); for LinkedIn this is the "
+                             "post-virality-floor count. Smaller than "
+                             "--candidates.")
+    parser.add_argument("--failure-reasons", dest="failure_reasons", default="",
+                        help="Optional comma-separated `reason:count` pairs "
+                             "describing why a run reported failed>0 "
+                             "(e.g. 'monthly_limit:5,timeout:1'). Surfaced in "
+                             "the dashboard Result column so operators can "
+                             "tell a hard cap from a transient error without "
+                             "opening the log file. Reason keys are free-form "
+                             "snake_case; the dashboard sorts by count desc "
+                             "and shows the top one with the rest in tooltip.")
+    parser.add_argument("--skip-reasons", dest="skip_reasons", default="",
+                        help="Optional comma-separated `reason:count` pairs "
+                             "describing why a run reported skipped>0 "
+                             "(e.g. 'duplicate_thread_pre_post:3,empty_reply_text:1'). "
+                             "Distinct from --failure-reasons: skips are "
+                             "intentional (dedup race guards, empty drafts, "
+                             "rate-limited threads) and the dashboard renders "
+                             "them as a yellow 'skipped: <reason>' pill rather "
+                             "than the red 'failed: <reason>' pill. Same "
+                             "sanitization rules as --failure-reasons.")
+    # Inbox/feed scan counters (engage-reddit, engage-twitter, etc.). Lets a
+    # pipeline that scans an inbox before engaging surface scan-stage
+    # granularity (seen / new / excluded / unmatched) in the dashboard Result
+    # column, so an empty cycle reads as "scanned 100 / 0 new" instead of just
+    # "0 0 0 0". Comma-separated `key=N` pairs; whitespace and the pipe char are
+    # stripped. Empty = omit the segment entirely (preserves backward compat).
+    parser.add_argument("--scan", dest="scan", default="",
+                        help="Optional comma-separated `key=N` pairs from an "
+                             "inbox/feed scan stage (e.g. "
+                             "'seen=100,new=0,excluded=1,unmatched=0'). "
+                             "Surfaces as scan-stage pills in the dashboard "
+                             "Result column for engage runs.")
+    # Invent-topics hourly job counters. Carries the project picked, how many
+    # topics were invented, how many queries were drafted in total, how many
+    # queries surfaced ANY supply, and the per-topic query counts. Free-form
+    # key=value comma-separated string — keys with integer values are parsed
+    # as ints in the dashboard, `project` is parsed as a string, `qpt` is
+    # parsed as a `+`-separated int list. Example:
+    #   --invent='project=fazm,topics=3,queries=15,queries_w_supply=1,qpt=5+5+5'
+    # Tails after scan= so the bin/server.js positional regex extends
+    # backward-compatibly (the new group is optional).
+    parser.add_argument("--invent", dest="invent", default="",
+                        help="Invent-topics job stats. Comma-separated "
+                             "key=value pairs (e.g. 'project=fazm,topics=3,"
+                             "queries=15,queries_w_supply=1,qpt=5+5+5'). "
+                             "Surfaces as the result-column pills on the "
+                             "Invent Topics rows in the Status > Job History "
+                             "tab.")
+    args = parser.parse_args()
+
+    timestamp = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
+    model_suffix = f" model={args.model}" if args.model else ""
+    # Inserted between failed=N and cost= so the existing positional regex in
+    # bin/server.js still parses old lines (the segment is optional in the regex).
+    replies_segment = (
+        f" replies_refreshed={args.replies_refreshed}"
+        if args.replies_refreshed else ""
+    )
+    # Stats-job per-run counters. The base segment (checked/updated/removed)
+    # stays as a single optional capture group for the bin/server.js regex.
+    # The LinkedIn-specific extras (unavailable/not_found) tail the base
+    # segment as their own optional groups so older lines still parse.
+    # 2026-05-18 relabel: scanned/changed/views_refreshed tail the segment as
+    # their own optional groups. Old log lines without them still parse.
+    # Trigger the segment if ANY stats-job field is set so the new fields
+    # surface even when the legacy three are zero.
+    _any_stats = (args.checked or args.updated or args.removed
+                  or args.unavailable or args.not_found
+                  or args.scanned or args.changed or args.views_refreshed)
+    stats_segment = (
+        f" checked={args.checked} updated={args.updated} removed={args.removed}"
+        if _any_stats else ""
+    )
+    if args.unavailable:
+        stats_segment += f" unavailable={args.unavailable}"
+    if args.not_found:
+        stats_segment += f" not_found={args.not_found}"
+    if args.scanned:
+        stats_segment += f" scanned={args.scanned}"
+    if args.changed:
+        stats_segment += f" changed={args.changed}"
+    if args.views_refreshed:
+        stats_segment += f" views_refreshed={args.views_refreshed}"
+    # `salvaged=N` segment tails the stats segment as its own optional capture
+    # so old log lines (no salvage info) still parse cleanly. Twitter-cycle
+    # specific today, but any pipeline that retries pending work cross-cycle
+    # can emit it.
+    salvaged_segment = f" salvaged={args.salvaged}" if args.salvaged else ""
+    # `discover` segment carries Phase-1/discovery counters the dashboard
+    # surfaces as a tooltip on the Result column (queries / duds /
+    # tweets_pulled / candidates / above_floor). Each sub-key is only
+    # emitted when non-zero so old log lines without discovery info still
+    # parse via the existing positional regex. The whole segment is opt-in:
+    # if every counter is zero, no `discover=` token appears at all.
+    discover_parts = []
+    if args.queries:
+        discover_parts.append(f"queries={args.queries}")
+    if args.duds:
+        discover_parts.append(f"duds={args.duds}")
+    if args.tweets_pulled:
+        discover_parts.append(f"tweets_pulled={args.tweets_pulled}")
+    if args.candidates:
+        discover_parts.append(f"candidates={args.candidates}")
+    if args.above_floor:
+        discover_parts.append(f"above_floor={args.above_floor}")
+    discover_segment = (
+        " discover=" + ",".join(discover_parts) if discover_parts else ""
+    )
+    # `failure_reasons` segment is appended after elapsed (and after the
+    # optional model suffix) so the existing positional regex in bin/server.js
+    # still parses old lines. Sanitize: strip whitespace and forbid the pipe
+    # char so the value can't break out of the log line column. Empty string
+    # = omit the segment entirely (preserves backward compat).
+    fr_raw = (args.failure_reasons or "").strip()
+    fr_clean = fr_raw.replace("|", "").replace(" ", "")
+    failure_segment = f" failure_reasons={fr_clean}" if fr_clean else ""
+    # `skip_reasons=` segment is the skip-side companion to failure_reasons.
+    # Tails after failure_reasons so the existing positional regex stays
+    # back-compat: old log lines that ended at failure_reasons (or earlier)
+    # still parse, the new group is optional. Same sanitization rules.
+    sr_raw = (args.skip_reasons or "").strip()
+    sr_clean = sr_raw.replace("|", "").replace(" ", "")
+    skip_segment = f" skip_reasons={sr_clean}" if sr_clean else ""
+    # `scan=` segment carries inbox/feed scan-stage counters. Same sanitization
+    # rules as failure_reasons (strip whitespace + pipe). Appended after
+    # discover= so the existing positional regex in bin/server.js can extend
+    # without breaking back-compat on old lines.
+    scan_raw = (args.scan or "").strip()
+    scan_clean = scan_raw.replace("|", "").replace(" ", "")
+    scan_segment = f" scan={scan_clean}" if scan_clean else ""
+    # `invent=` segment carries the invent-topics hourly job's per-run counts.
+    # Same sanitization rules as scan=/failure_reasons (strip whitespace + pipe).
+    # Tails after scan= so the bin/server.js positional regex extends
+    # backward-compatibly — old lines with no invent= still parse.
+    invent_raw = (args.invent or "").strip()
+    invent_clean = invent_raw.replace("|", "").replace(" ", "")
+    invent_segment = f" invent={invent_clean}" if invent_clean else ""
+    # `escape_hatch=` segment surfaces author_blocklist writes that happened
+    # during this run window (LLM-judgment via reply_db.py CLI, or manual
+    # operator adds). Auto-detected via the API so callers don't have to
+    # plumb it; fail-safe to empty on any error. Velocity-auto rows are
+    # excluded inside _detect_escape_hatch — they fire on every reply and
+    # would flood the pill. Tails after skip_reasons so old log lines (no
+    # escape-hatch info) still parse via the bin/server.js positional regex.
+    eh_count, eh_details = _detect_escape_hatch(args.script, args.elapsed)
+    if eh_count:
+        eh_details_clean = ",".join(eh_details).replace("|", "").replace(" ", "")
+        escape_hatch_segment = (
+            f" escape_hatch={eh_count} escape_hatch_details={eh_details_clean}"
+        )
+    else:
+        escape_hatch_segment = ""
+    line = (
+        f"{timestamp} | {args.script} | "
+        f"posted={args.posted} skipped={args.skipped} failed={args.failed}"
+        f"{replies_segment}{stats_segment}{salvaged_segment}{discover_segment}{scan_segment}{invent_segment} "
+        f"cost=${args.cost:.2f} elapsed={args.elapsed:.0f}s{model_suffix}{failure_segment}{skip_segment}{escape_hatch_segment}"
+    )
+
+    os.makedirs(os.path.dirname(LOG_PATH), exist_ok=True)
+    with open(LOG_PATH, "a") as f:
+        f.write(line + "\n")
+
+    print(line)
+
+    # Silent-failure warning fires when a posting job claims `failed>0` but
+    # never posted anything. Stats/audit jobs legitimately run with posted=0
+    # while doing real work (scanning rows, checking the API); suppress the
+    # warning when any of `--checked / --scanned / --replies-refreshed` is
+    # non-zero so audit and stats rows don't trip a false positive.
+    _real_work = (args.checked or args.scanned or args.replies_refreshed
+                  or args.changed or args.updated or args.views_refreshed)
+    # SCAN_ONLY runs (the Desktop-session autopilot's scan step) never post by
+    # design — an empty scan is "nothing fresh on-theme right now", not a silent
+    # failure. run-twitter-cycle.sh exports SCAN_ONLY=1 and log_run.py inherits
+    # it, so suppress the alarm for that path. The legacy full-cycle / plist
+    # autopilot runs WITHOUT SCAN_ONLY, so its behavior is byte-for-byte unchanged.
+    _scan_only = os.environ.get("SCAN_ONLY") == "1"
+    if args.posted == 0 and args.failed > 0 and not _real_work and not _scan_only:
+        warning = f"WARNING: {args.script} posted=0 failed={args.failed} -- possible silent failure"
+        with open(LOG_PATH, "a") as f:
+            f.write(f"{timestamp} | {warning}\n")
+        print(warning)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/log_thread_media.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Persist captured thread media on a twitter_candidates row.
+
+Deterministic, model-free companion to the main posting cycle (2026-06-03
+thread-media feature). The cycle pre-fetches the media of every candidate it is
+about to draft against (twitter_browser.py thread-media-batch), then calls this
+script once per candidate to persist the media into
+twitter_candidates.thread_media so the reply-writer prompt can "see" the
+image / video / GIF / link-card it is replying to, and the record survives
+independent of the model.
+
+Media shape: a JSON array of {url, alt, type} objects, type in
+image|video|gif|card. An empty array [] is valid and meaningful ("captured,
+none found", distinct from NULL = "never captured").
+
+Usage:
+    # Pass media JSON inline:
+    python3 scripts/log_thread_media.py --candidate-id 12345 \\
+        --media '[{"url":"https://pbs.twimg.com/...","alt":"Image","type":"image"}]'
+
+    # Or read the media JSON array from a file (handy for batch wiring):
+    python3 scripts/log_thread_media.py --candidate-id 12345 --media-file /tmp/m.json
+
+Output (JSON):
+    {"logged": true, "candidate_id": 12345, "media_count": 1}
+    {"error": "CANDIDATE_NOT_FOUND", ...}
+    {"error": "BAD_MEDIA_JSON", ...}
+"""
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from http_api import api_patch
+
+
+def _load_media(args):
+    """Return a parsed media list (or raise ValueError) from --media/--media-file."""
+    raw = None
+    if args.media_file:
+        with open(args.media_file) as f:
+            raw = f.read()
+    elif args.media is not None:
+        raw = args.media
+    else:
+        raise ValueError("one of --media or --media-file is required")
+    raw = (raw or "").strip()
+    if raw == "":
+        # Treat an empty arg as "captured, none found" -> [].
+        return []
+    parsed = json.loads(raw)
+    if not isinstance(parsed, list):
+        raise ValueError("media must be a JSON array")
+    return parsed
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--candidate-id", type=int, required=True)
+    p.add_argument(
+        "--media", default=None,
+        help='JSON array of {url,alt,type}. Empty/"" means captured-none ([]).',
+    )
+    p.add_argument(
+        "--media-file", default=None,
+        help="Path to a file containing the media JSON array (alternative to --media).",
+    )
+    args = p.parse_args()
+
+    try:
+        media = _load_media(args)
+    except Exception as e:
+        print(json.dumps({"error": "BAD_MEDIA_JSON", "detail": str(e)}))
+        sys.exit(1)
+
+    payload = {
+        "id": args.candidate_id,
+        "action": "set_media",
+        "thread_media": media,
+    }
+
+    resp = api_patch(
+        "/api/v1/twitter-candidates/by-id", payload,
+        ok_on_conflict=True, ok_on_404=True,
+    )
+
+    if (resp or {}).get("_not_found"):
+        print(json.dumps({"error": "CANDIDATE_NOT_FOUND", "candidate_id": args.candidate_id}))
+        sys.exit(1)
+    if not (resp or {}).get("ok"):
+        print(json.dumps({
+            "error": "SET_MEDIA_FAILED",
+            "candidate_id": args.candidate_id,
+            "detail": (resp or {}).get("error"),
+        }))
+        sys.exit(1)
+
+    print(json.dumps({
+        "logged": True,
+        "candidate_id": args.candidate_id,
+        "media_count": len(media),
+    }))
+
+
+if __name__ == "__main__":
+    main()

package/scripts/log_twitter_search_attempts.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""
+log_twitter_search_attempts.py
+
+Insert one row per (query, project, tweets_found) into twitter_search_attempts.
+Reads a JSON array on stdin shaped like:
+
+    [
+      {"query": "...", "project": "fazm", "tweets_found": 0},
+      {"query": "...", "project": "mediar", "tweets_found": 3},
+      ...
+    ]
+
+Used by run-twitter-cycle.sh after Phase 1 scan parses queries_used out of the
+LLM envelope. Logging zero-result queries here is the whole point — the
+twitter_candidates table only has rows for tweets that were actually scraped,
+so duds were previously invisible. Pair with top_dud_twitter_queries.py.
+
+    python3 scripts/log_twitter_search_attempts.py --batch-id <id> < queries.json
+    python3 scripts/log_twitter_search_attempts.py --batch-id <id> \
+        --attempts-out /tmp/attempts.json < queries.json
+
+When --attempts-out is provided, writes a JSON list of
+    [{"query": ..., "project": ..., "attempt_id": <int>}, ...]
+to that path so the downstream scorer can stamp twitter_candidates.search_
+attempt_id and the dashboard gets exact 1:1 query<->post attribution. Without
+this, the dashboard falls back to a (batch_id, project_name) fanout that
+credits every query in the batch — including dud ones — with every posted
+candidate (the bug user spotted 2026-05-21).
+
+Migrated 2026-05-18: writes now POST to /api/v1/twitter-search-attempts via
+scripts/http_api.py instead of opening a psycopg2 connection.
+"""
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from http_api import api_post  # noqa: E402
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--batch-id", default=None)
+    p.add_argument(
+        "--attempts-out",
+        default=None,
+        help="Optional path; if set, write JSON list of "
+             "[{query, project, attempt_id}, ...] for the scorer to consume.",
+    )
+    # kind: which pipeline drafted these attempts. 'cycle' (default) preserves
+    # back-compat for every existing caller (run-twitter-cycle.sh + friends).
+    # invent_topics.py passes --kind invent so qualified_query_bank can union
+    # the proven invented set into the Phase 1 bank.
+    p.add_argument("--kind", default="cycle", choices=("cycle", "invent"),
+                   help="Pipeline lane writing these attempts.")
+    args = p.parse_args()
+
+    raw = sys.stdin.read().strip()
+    if not raw:
+        print("log_twitter_search_attempts: empty stdin, nothing to log", file=sys.stderr)
+        if args.attempts_out:
+            # Write empty list so the caller can still pass --attempts to the
+            # scorer without a missing-file race.
+            with open(args.attempts_out, "w") as f:
+                json.dump([], f)
+        return 0
+
+    try:
+        rows = json.loads(raw)
+    except json.JSONDecodeError as e:
+        print(f"log_twitter_search_attempts: bad JSON on stdin: {e}", file=sys.stderr)
+        return 1
+
+    if not isinstance(rows, list) or not rows:
+        print("log_twitter_search_attempts: not a list or empty list, nothing to log", file=sys.stderr)
+        if args.attempts_out:
+            with open(args.attempts_out, "w") as f:
+                json.dump([], f)
+        return 0
+
+    inserted = 0
+    attempts_map = []
+    for r in rows:
+        if not isinstance(r, dict):
+            continue
+        query = (r.get("query") or "").strip()
+        project = (r.get("project") or "").strip() or None
+        tweets_found = r.get("tweets_found")
+        try:
+            tweets_found = int(tweets_found if tweets_found is not None else 0)
+        except (TypeError, ValueError):
+            tweets_found = 0
+        # search_topic is the higher-level theme driving this query (set by
+        # pick_search_topic.py at the start of the cycle). Optional, because
+        # run-twitter-cycle.sh hasn't been threaded through the queries_used
+        # envelope yet; score_twitter_candidates.py also backfills it from
+        # twitter_candidates.search_topic on its end of the pipeline.
+        search_topic = (r.get("search_topic") or "").strip() or None
+        if not query:
+            continue
+        try:
+            payload = {
+                "query": query,
+                "project_name": project,
+                "tweets_found": tweets_found,
+                "batch_id": args.batch_id,
+                "kind": args.kind,
+            }
+            if search_topic:
+                payload["search_topic"] = search_topic
+            resp = api_post(
+                "/api/v1/twitter-search-attempts",
+                payload,
+            )
+            inserted += 1
+            attempt_id = ((resp.get("data") or {}).get("attempt") or {}).get("id")
+            if attempt_id is not None:
+                attempts_map.append({
+                    "query": query,
+                    "project": project,
+                    "attempt_id": int(attempt_id),
+                })
+        except SystemExit as e:
+            # http_api raises SystemExit on terminal failure. Log and keep
+            # going so a single bad row doesn't drop the rest of the batch.
+            print(f"log_twitter_search_attempts: API error for {query!r}: {e}", file=sys.stderr)
+            continue
+
+    if args.attempts_out:
+        with open(args.attempts_out, "w") as f:
+            json.dump(attempts_map, f)
+        print(
+            f"log_twitter_search_attempts: wrote {len(attempts_map)} attempt-id "
+            f"entries to {args.attempts_out}",
+            file=sys.stderr,
+        )
+
+    duds = sum(1 for r in rows if isinstance(r, dict) and not int(r.get("tweets_found") or 0))
+    print(
+        f"log_twitter_search_attempts: inserted {inserted} rows ({duds} duds) "
+        f"for batch={args.batch_id}",
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())