social-autoposter 1.6.6 → 1.6.7

package/bin/cli.js

@@ -170,19 +170,72 @@ function writeAppMakerEnvFile() {
   console.log(`  AppMaker VM detected -> wrote ${envPath} (TWITTER_CDP_URL=http://127.0.0.1:9222)`);
 }
 
+// AppMaker VMs also need the twitter-harness MCP server (browser-harness/server.py)
+// to drive port 9222, not its default 9555. That's a SECOND path the env file alone
+// doesn't cover, because the MCP server is spawned by Claude as a subprocess with
+// an env block taken from the MCP config file (--strict-mcp-config replaces the
+// inherited env, so a parent BH_PORT export wouldn't reach it). So we patch the
+// MCP config in-place to bake BH_PORT=9222 into its env block.
+// Idempotent: parses the JSON, sets env.BH_PORT, rewrites. Safe to re-run.
+function applyAppMakerMcpConfigOverrides() {
+  const cfgPath = path.join(HOME, '.claude', 'browser-agent-configs', 'twitter-harness-mcp.json');
+  if (!fs.existsSync(cfgPath)) {
+    console.log(`  AppMaker MCP override: ${cfgPath} not found, skipping (will be picked up next run)`);
+    return;
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+  } catch (e) {
+    console.warn(`  AppMaker MCP override: failed to parse ${cfgPath}: ${e.message}`);
+    return;
+  }
+  const srv = cfg?.mcpServers?.['twitter-harness'];
+  if (!srv) {
+    console.warn(`  AppMaker MCP override: ${cfgPath} has no mcpServers.twitter-harness entry`);
+    return;
+  }
+  if (!srv.env || typeof srv.env !== 'object') srv.env = {};
+  if (srv.env.BH_PORT === '9222') {
+    console.log(`  AppMaker MCP override: BH_PORT=9222 already set in ${cfgPath}`);
+    return;
+  }
+  srv.env.BH_PORT = '9222';
+  fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
+  console.log(`  AppMaker MCP override: set BH_PORT=9222 in ${cfgPath}`);
+}
+
 // Provision the browser-harness toolchain that backs the twitter-harness MCP:
 //   1. install uv (Astral) if missing
 //   2. git-clone browser-use/browser-harness
 //   3. uv tool install -e . (provides the `browser-harness` CLI)
 //   4. ensure `mcp` Python package is importable for server.py
 //   5. copy our shipped server.py into ~/.claude/mcp-servers/browser-harness/
-// All steps are idempotent. Skipped entirely on AppMaker VMs (the proxied
-// Chromium on 9222 replaces the harness).
+// All steps are idempotent.
+//
+// AppMaker VMs: the toolchain is STILL needed (the MCP server.py is what
+// Claude invokes during Phase 1's tweet scan, and it requires uv + mcp +
+// browser-harness CLI to run). The AppMaker-specific deltas are:
+//   (a) writeAppMakerEnvFile() points TWITTER_CDP_URL at 9222 for posting
+//   (b) applyAppMakerMcpConfigOverrides() injects BH_PORT=9222 so server.py
+//       drives the AppMaker Chromium instead of trying to launch its own
+//       Chrome on 9555. server.py's ensure_chrome() short-circuits when CDP
+//       is already alive on PORT, so no double-Chrome ever spawns.
+// Previously we early-returned here on AppMaker, which left the VM without
+// uv installed and broke Phase 1's Claude scan (the MCP server's `command:
+// /root/.local/bin/uv` resolved to ENOENT, Claude got no tools, returned an
+// empty envelope).
 function installBrowserHarness() {
-  if (isAppMakerVm()) {
-    console.log('  AppMaker VM detected -> skipping browser-harness install (Chromium on 9222 is canonical)');
+  const onAppMaker = isAppMakerVm();
+  if (onAppMaker) {
+    console.log('  AppMaker VM detected -> installing harness toolchain (deps); MCP will be pointed at port 9222');
     writeAppMakerEnvFile();
-    return;
+    // scripts/run_claude.sh uses `uuidgen` for session IDs on AUP-retry. The
+    // base image ships libuuid1 (shared lib) but not the CLI tool — the
+    // package is `uuid-runtime`. Without it, run_claude.sh's session_id
+    // generation falls back to empty string and claude --session-id breaks.
+    console.log('    installing uuid-runtime (uuidgen) for run_claude.sh...');
+    spawnSync('bash', ['-lc', 'command -v uuidgen >/dev/null 2>&1 || DEBIAN_FRONTEND=noninteractive apt-get install -y -qq uuid-runtime'], { stdio: 'inherit' });
   }
   console.log('  setting up browser-harness (twitter-harness MCP backend)...');
 
@@ -440,6 +493,9 @@ function init() {
   installBrowserHarness();
   // Install browser agent MCP configs + profile dirs (skips existing files)
   installBrowserAgentConfigs();
+  // On AppMaker VMs, patch the twitter-harness MCP config so its server.py
+  // drives port 9222 (AppMaker Chromium) instead of the default 9555.
+  if (isAppMakerVm()) applyAppMakerMcpConfigOverrides();
   // Register those MCP servers with Claude so they show up in `claude mcp list`.
   registerBrowserAgentMcpServers();
 
@@ -524,6 +580,9 @@ function update() {
   installBrowserHarness();
   // Top up browser agent configs (won't overwrite user customizations)
   installBrowserAgentConfigs();
+  // On AppMaker VMs, patch the twitter-harness MCP config so its server.py
+  // drives port 9222 (AppMaker Chromium) instead of the default 9555.
+  if (isAppMakerVm()) applyAppMakerMcpConfigOverrides();
   // Register any newly added MCP servers with Claude (idempotent).
   registerBrowserAgentMcpServers();
 

package/bin/server.js

@@ -994,6 +994,74 @@ async function enrichEngageRuns(runs) {
   }
 }
 
+// dm_outreach_* runs: skill/dm-outreach-*.sh always calls log_run.py with
+// hardcoded --posted 0 --skipped 0 --failed 0 because per-DM outcomes go to
+// the `dms` table via dm_db_update.py, not the log summary. Without an
+// enricher the dashboard literally renders "posted 0 / skipped 0" even on
+// runs that sent multiple DMs (and the operator wrongly concludes the cron
+// is broken). Mirror enrichEngageRuns: derive attempted / sent / skipped /
+// errored from `dms` rows whose claude_session_id belongs to this run's
+// window. Cost is preserved as-is (get_run_cost.py already aggregates the
+// whole job, identical pattern to engage / post-comments runs).
+async function enrichDMOutreachRuns(runs) {
+  const dmRuns = runs.filter(r => r.job_type === 'dm-outreach' && r.platform_key);
+  if (!dmRuns.length) return;
+  let oldestMs = Infinity;
+  for (const r of dmRuns) {
+    const ms = new Date(r.started_at).getTime();
+    if (ms < oldestMs) oldestMs = ms;
+  }
+  // Slack window: the shell wrapper sets CLAUDE_SESSION_ID up front but
+  // claude_sessions row gets stamped when the headless run starts (a few
+  // seconds in); skip rows can fire >5 min before sent rows in the same
+  // session. 5 min slack matches what enrichRunsCostBreakdown uses.
+  const slackMs = 5 * 60 * 1000;
+  const since = new Date(oldestMs - slackMs).toISOString();
+  // Join dms -> claude_sessions so each dms row carries the session's
+  // started_at (used to assign it to the right run row when multiple
+  // dm-outreach runs land in the same query window).
+  const rows = await pq(
+    "SELECT d.platform, d.status, cs.started_at, cs.script " +
+    "FROM dms d JOIN claude_sessions cs ON cs.session_id = d.claude_session_id " +
+    "WHERE cs.started_at >= $1::timestamp AND cs.script LIKE 'dm-outreach-%'",
+    [since]
+  );
+  if (!rows) return;
+  const pendingByPlatform = {};
+  const pendingRows = await pq(
+    "SELECT platform, COUNT(*)::int AS n FROM dms WHERE status='pending' GROUP BY platform"
+  );
+  if (pendingRows) {
+    for (const r of pendingRows) pendingByPlatform[(r.platform || '').toLowerCase()] = r.n;
+  }
+  for (const run of dmRuns) {
+    const startMs = new Date(run.started_at).getTime();
+    const endMs = new Date(run.finished_at).getTime() + slackMs;
+    // dm_outreach_twitter run -> DB platform 'x'. Reddit/LinkedIn keep slug.
+    const dbPlatform = run.platform_key === 'twitter' ? 'x' : run.platform_key;
+    let sent = 0, skipped = 0, errored = 0, attempted = 0;
+    for (const p of rows) {
+      if ((p.platform || '').toLowerCase() !== dbPlatform) continue;
+      const sessTs = p.started_at instanceof Date ? p.started_at.getTime() : Date.parse(p.started_at);
+      if (sessTs < startMs - slackMs || sessTs > endMs) continue;
+      attempted++;
+      if (p.status === 'sent') sent++;
+      else if (p.status === 'skipped') skipped++;
+      else if (p.status === 'error') errored++;
+    }
+    const prior = run.result || {};
+    run.result = {
+      type: 'dm-outreach',
+      attempted,
+      sent,
+      skipped,
+      errored,
+      pending_now: pendingByPlatform[dbPlatform] || 0,
+      cost_usd: prior.cost_usd || 0,
+    };
+  }
+}
+
 // scan_*_replies / scan_*_followups / scan_*_mentions runs: the shell wrappers
 // log `posted=FOUND` where FOUND is grepped from stdout, which is fragile and
 // zero-by-default. Replace it with a direct count of rows inserted into the
@@ -4237,6 +4305,7 @@ async function handleApi(req, res) {
       }
       await enrichLinkEditRuns(runs);
       await enrichEngageRuns(runs);
+      await enrichDMOutreachRuns(runs);
       await enrichCheckRepliesRuns(runs);
       await enrichPostCommentsLinkedInRuns(runs);
       await enrichPostCommentsTwitterRuns(runs);
@@ -6783,6 +6852,9 @@ async function handleApi(req, res) {
       linkedin: p => !isDisabled(p, 'linkedin') && hasSearchTopics(p),
       reddit:   p => !isDisabled(p, 'reddit'),
       moltbook: p => !isDisabled(p, 'moltbook'),
+      // Instagram doesn't use search_topics; posts come from prerendered mixer
+      // drafts. Projects can still opt out via platforms_disabled.
+      instagram: p => !isDisabled(p, 'instagram'),
     };
     const totalWeightByPlatform = {};
     for (const plat of platforms) {
@@ -9487,6 +9559,30 @@ function renderResult(run) {
       '</span>'
     );
   }
+  if (r.type === 'dm-outreach') {
+    // Per-run DB-derived counts (see enrichDMOutreachRuns in server.js).
+    // dm-outreach-*.sh hardcodes posted/skipped/failed=0 in log_run.py
+    // because per-DM outcomes go to the dms table via dm_db_update.py.
+    // Pills here come from joining dms -> claude_sessions on the run window.
+    // attempted is the total candidates the run actually resolved (sent +
+    // skipped + errored); the operator wants to see "we tried 7, sent 2"
+    // not "0". (No backticks in this comment block: renderResult lives
+    // inside an outer HTML template literal, see note at the engage branch.)
+    const attempted = r.attempted || 0;
+    const sent = r.sent || 0;
+    const skipped = r.skipped || 0;
+    const errored = r.errored || 0;
+    const pending = r.pending_now || 0;
+    const cost = r.cost_usd || 0;
+    return (
+      pill('attempted', attempted, attempted > 0 ? 'var(--text)' : 'var(--muted)') +
+      pill('sent', sent, sent > 0 ? '#22c55e' : 'var(--muted)') +
+      pill('skipped', skipped, skipped > 0 ? '#eab308' : 'var(--muted)') +
+      pill('errored', errored, errored > 0 ? '#ef4444' : 'var(--muted)') +
+      pill('queue', pending, pending > 0 ? 'var(--text)' : 'var(--muted)') +
+      '<span style="font-size:12px;color:var(--muted);">$' + cost.toFixed(2) + '</span>'
+    );
+  }
   if (r.type === 'engage') {
     // Per-run DB-derived counts (see enrichEngageRuns in server.js).
     // Empty-queue runs show "queue empty" so the operator can tell a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "social-autoposter",
-  "version": "1.6.6",
+  "version": "1.6.7",
   "description": "Automated social posting pipeline for Reddit, X/Twitter, LinkedIn, and Moltbook. Install as a Claude Code agent skill.",
   "bin": {
     "social-autoposter": "bin/cli.js"
@@ -13,6 +13,7 @@
   "files": [
     "bin/",
     "scripts/*.py",
+    "scripts/*.sh",
     "scripts/engagement_styles_extra.json",
     "schema-postgres.sql",
     "config.example.json",

package/scripts/_dm_icp_batch.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Usage: _dm_icp_batch.sh DM_ID DEFAULT_LABEL DEFAULT_NOTES [override:project=label:notes ...]
+# Sets default label/notes on all 19 projects, then applies overrides
+set -e
+DM_ID=$1
+DEFAULT_LABEL=$2
+DEFAULT_NOTES=$3
+shift 3
+
+declare -A LABELS NOTES
+PROJECTS=(fazm Terminator "macOS MCP" Vipassana S4L "AI Browser Profile" "WhatsApp MCP" "macOS Session Replay" Cyrano Assrt PieLine Clone mk0r fde10x claude-meter c0nsl tenxats paperback-expert studyly)
+for p in "${PROJECTS[@]}"; do
+  LABELS["$p"]="$DEFAULT_LABEL"
+  NOTES["$p"]="$DEFAULT_NOTES"
+done
+
+for arg in "$@"; do
+  proj="${arg%%=*}"
+  rest="${arg#*=}"
+  lbl="${rest%%:*}"
+  note="${rest#*:}"
+  LABELS["$proj"]="$lbl"
+  NOTES["$proj"]="$note"
+done
+
+cd /Users/matthewdi/social-autoposter
+for p in "${PROJECTS[@]}"; do
+  python3 scripts/dm_conversation.py set-icp-precheck \
+    --dm-id "$DM_ID" --project "$p" \
+    --label "${LABELS[$p]}" --notes "${NOTES[$p]}" >/dev/null
+done
+echo "ICP prechecks set for DM $DM_ID (default=$DEFAULT_LABEL, ${#@} overrides)"

package/scripts/_dm_record_sent.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Usage: ./_dm_record_sent.sh DM_ID "content"
+set -e
+DM=$1
+CONTENT=$2
+source ~/social-autoposter/.env
+psql "$DATABASE_URL" -c "UPDATE dms SET status='sent', our_dm_content=\$\$$CONTENT\$\$, sent_at=NOW(), claude_session_id='967dfa68-2d39-42de-99e9-acdb2d3552ac'::uuid WHERE id=$DM;" 2>&1 | tail -1
+python3 /Users/matthewdi/social-autoposter/scripts/dm_conversation.py log-outbound --dm-id "$DM" --content "$CONTENT" --verified 2>&1 | tail -1

package/scripts/author_history_block.py

@@ -49,6 +49,73 @@ PLATFORM_ALIAS = {
 }
 
 
+# Per-process cache for active campaign suffixes; populated lazily on first
+# format_block() call. None = not loaded yet; [] = loaded but empty.
+_ACTIVE_CAMPAIGN_SUFFIXES_CACHE = None
+
+
+def _load_active_campaign_suffixes():
+    """Best-effort: return a list of currently-active campaign suffix literals.
+
+    Mirrors the helper of the same name in scripts/top_performers.py. We
+    duplicate (rather than import) to keep this module's failure mode
+    independent of top_performers' larger dependency surface.
+
+    Used to strip the suffix from `our_content` before injecting prior
+    interactions into the draft prompt, so the LLM never learns to echo
+    the suffix in its drafts (which would then double-fire when the
+    tool-layer injection at twitter_browser.reply_to_tweet / reddit_browser
+    appends a second copy). See feedback_suffix_injection_gating.md for the
+    history; this closes the 4th leak path that the 2026-05-19 sweep missed.
+
+    On any failure returns []: missing strip is preferable to crashing the
+    prompt assembly path.
+    """
+    global _ACTIVE_CAMPAIGN_SUFFIXES_CACHE
+    if _ACTIVE_CAMPAIGN_SUFFIXES_CACHE is not None:
+        return _ACTIVE_CAMPAIGN_SUFFIXES_CACHE
+    suffixes = []
+    try:
+        from http_api import api_get  # noqa: E402
+        resp = api_get(
+            "/api/v1/campaigns",
+            query={"status": "active", "has_suffix": "true", "limit": 500},
+        )
+        rows = ((resp or {}).get("data") or {}).get("campaigns") or []
+        for r in rows:
+            s = (r.get("suffix") or "").strip()
+            if s and s not in suffixes:
+                suffixes.append(s)
+    except Exception as e:
+        print(
+            f"[author_history_block] _load_active_campaign_suffixes failed: {e!r}",
+            file=sys.stderr,
+        )
+    _ACTIVE_CAMPAIGN_SUFFIXES_CACHE = suffixes
+    return suffixes
+
+
+def _strip_active_campaign_suffixes(text, suffixes):
+    """Trailing-only, idempotent strip of any active-campaign suffix.
+
+    Identical contract to top_performers._strip_active_campaign_suffixes.
+    Idempotent loop also collapses an already-doubled historical suffix
+    (e.g. "... written with s4lai written with s4lai") to clean text.
+    Trailing-only so we never touch the body of the comment.
+    """
+    if not text or not suffixes:
+        return text
+    cleaned = text.rstrip()
+    changed = True
+    while changed:
+        changed = False
+        for sfx in suffixes:
+            if sfx and cleaned.endswith(sfx):
+                cleaned = cleaned[: -len(sfx)].rstrip()
+                changed = True
+    return cleaned
+
+
 def _normalize(handle):
     """Lowercase + strip @, u/, / prefixes. Empty/'unknown' → empty string."""
     if not handle:
@@ -188,6 +255,12 @@ def format_block(rows, author, platform, days):
         f"window={days}d, latest first):"
     )
     lines = [header]
+    # Load active campaign suffixes ONCE per format_block call so we strip
+    # them off `our_content` BEFORE truncation. Short Twitter replies
+    # (≤140 chars total) would otherwise show the suffix verbatim in the
+    # exemplar, training the LLM to echo it; the tool layer then appends
+    # a second copy. See feedback_suffix_injection_gating.md.
+    suffix_strip_list = _load_active_campaign_suffixes()
     for row in rows:
         (
             _id,
@@ -202,7 +275,10 @@ def format_block(rows, author, platform, days):
         ) = row
         date = posted_at.date().isoformat() if posted_at else "?"
         proj = project or "?"
-        ours = _truncate(our_content, 140)
+        our_content_clean = _strip_active_campaign_suffixes(
+            our_content, suffix_strip_list
+        )
+        ours = _truncate(our_content_clean, 140)
         eng_bits = []
         if upvotes:
             eng_bits.append(f"likes={upvotes}")

package/scripts/bench_dashboard.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# bench_dashboard.sh
+#
+# Benchmark Social Autoposter dashboard endpoint latencies using curl + awk.
+# Prints a table with p50/p95/min/max per endpoint.
+#
+# Env vars:
+#   BASE_URL     default http://localhost:3141
+#   RUNS         default 10 (requests per endpoint)
+#   CONCURRENCY  default 1 (serial). If >1, uses background curls + wait.
+#
+# Always exits 0.
+
+set -u
+
+BASE_URL="${BASE_URL:-http://localhost:3141}"
+RUNS="${RUNS:-10}"
+CONCURRENCY="${CONCURRENCY:-1}"
+
+ENDPOINTS=(
+  "/"
+  "/api/pending"
+  "/api/activity/stats?hours=24"
+  "/api/style/stats?hours=24"
+  "/api/status"
+  "/api/jobs"
+)
+
+TIMESTAMP="$(date '+%Y-%m-%d %H:%M:%S')"
+
+printf 'bench_dashboard.sh  time=%s  base=%s  runs=%s  concurrency=%s\n' \
+  "$TIMESTAMP" "$BASE_URL" "$RUNS" "$CONCURRENCY"
+printf '\n'
+
+# Header row
+printf '%-40s %-3s %-7s %-7s %-7s %-7s %s\n' \
+  "endpoint" "n" "p50" "p95" "min" "max" "codes"
+
+TMPDIR="$(mktemp -d -t bench_dashboard.XXXXXX)"
+trap 'rm -rf "$TMPDIR"' EXIT
+
+# Run one curl, append "http_code time_total" to the given outfile.
+# Args: URL OUTFILE
+run_one() {
+  local url="$1"
+  local out="$2"
+  # -s silent, -o /dev/null discard body, -w format.
+  # On connection failure curl prints "000 0.000".
+  local line
+  line="$(curl -s -o /dev/null -w '%{http_code} %{time_total}\n' \
+    --max-time 60 "$url" 2>/dev/null || true)"
+  if [ -z "$line" ]; then
+    line="000 0.000"
+  fi
+  printf '%s\n' "$line" >> "$out"
+}
+
+for ep in "${ENDPOINTS[@]}"; do
+  url="${BASE_URL}${ep}"
+  outfile="${TMPDIR}/out.$$.$(echo "$ep" | tr -c 'A-Za-z0-9' '_')"
+  : > "$outfile"
+
+  if [ "$CONCURRENCY" -le 1 ]; then
+    i=0
+    while [ "$i" -lt "$RUNS" ]; do
+      run_one "$url" "$outfile"
+      i=$((i + 1))
+    done
+  else
+    # Launch in waves of CONCURRENCY until RUNS total are done.
+    launched=0
+    while [ "$launched" -lt "$RUNS" ]; do
+      wave=0
+      pids=""
+      while [ "$wave" -lt "$CONCURRENCY" ] && [ "$launched" -lt "$RUNS" ]; do
+        run_one "$url" "$outfile" &
+        pids="$pids $!"
+        wave=$((wave + 1))
+        launched=$((launched + 1))
+      done
+      # wait for this wave
+      for p in $pids; do
+        wait "$p" 2>/dev/null || true
+      done
+    done
+  fi
+
+  # Compute stats with awk.
+  # Input: lines of "CODE TIME". Output one line:
+  #   count p50 p95 min max codes
+  awk -v ep="$ep" '
+    {
+      code = $1
+      t = $2 + 0
+      times[NR] = t
+      codes[code]++
+      n++
+      if (n == 1 || t < mn) mn = t
+      if (n == 1 || t > mx) mx = t
+    }
+    END {
+      if (n == 0) {
+        printf "%-40s %-3d %-7s %-7s %-7s %-7s %s\n", ep, 0, "-", "-", "-", "-", "none"
+        exit
+      }
+      # sort times ascending (insertion sort, fine for small n)
+      for (i = 2; i <= n; i++) {
+        v = times[i]; j = i - 1
+        while (j >= 1 && times[j] > v) { times[j+1] = times[j]; j-- }
+        times[j+1] = v
+      }
+      # p50 and p95 using nearest-rank, 1-indexed
+      p50_idx = int((50/100) * n + 0.9999); if (p50_idx < 1) p50_idx = 1; if (p50_idx > n) p50_idx = n
+      p95_idx = int((95/100) * n + 0.9999); if (p95_idx < 1) p95_idx = 1; if (p95_idx > n) p95_idx = n
+      p50 = times[p50_idx]
+      p95 = times[p95_idx]
+
+      # Build codes string sorted by code key
+      ncodes = 0
+      for (c in codes) { ncodes++; ck[ncodes] = c }
+      for (i = 2; i <= ncodes; i++) {
+        v = ck[i]; j = i - 1
+        while (j >= 1 && ck[j] > v) { ck[j+1] = ck[j]; j-- }
+        ck[j+1] = v
+      }
+      codes_str = ""
+      for (i = 1; i <= ncodes; i++) {
+        sep = (i == 1) ? "" : " "
+        codes_str = codes_str sep ck[i] "x" codes[ck[i]]
+      }
+
+      printf "%-40s %-3d %-7.3f %-7.3f %-7.3f %-7.3f %s\n", \
+        ep, n, p50, p95, mn, mx, codes_str
+    }
+  ' "$outfile"
+done
+
+exit 0

package/scripts/clean_stale_singleton.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# clean_stale_singleton.sh — Remove stale Chrome singleton symlinks from a
+# browser profile if (and only if) the PID they reference is dead.
+#
+# Background: when Chrome exits ungracefully (SIGKILL, system sleep, force
+# quit, jetsam), it leaves Singleton{Lock,Cookie,Socket} + RunningChromeVersion
+# symlinks behind. On the next launch Chrome sees them, fails to talk to the
+# (now-dead) PID listed in SingletonLock, and pops "Something went wrong when
+# opening your profile. Some features may be unavailable" once per service
+# (cookies, prefs, history, sync, ...) — typically 7 dialogs. Until the user
+# clicks all of them, no pages load and the pipeline hangs.
+#
+# Safe to call before any Chrome launch on the same profile. Idempotent.
+# Refuses to clean if the SingletonLock PID is still alive (so we never
+# yank locks out from under a running Chrome — including a real user
+# session attached to the same profile).
+#
+# Usage: clean_stale_singleton.sh <profile_dir>
+#   e.g. clean_stale_singleton.sh ~/.claude/browser-profiles/twitter
+
+set -uo pipefail
+
+profile_dir="${1:-}"
+if [ -z "$profile_dir" ] || [ ! -d "$profile_dir" ]; then
+    echo "[clean_stale_singleton] usage: $0 <profile_dir>" >&2
+    exit 0  # never block the pipeline on a misuse; just no-op
+fi
+
+lock_link="$profile_dir/SingletonLock"
+
+# No lock = nothing to clean.
+if [ ! -L "$lock_link" ] && [ ! -e "$lock_link" ]; then
+    exit 0
+fi
+
+# SingletonLock target format: <hostname>-<pid>
+target=$(readlink "$lock_link" 2>/dev/null || echo "")
+pid="${target##*-}"
+
+if [ -n "$pid" ] && [[ "$pid" =~ ^[0-9]+$ ]]; then
+    if kill -0 "$pid" 2>/dev/null; then
+        # Live Chrome owns this profile. Do NOT touch.
+        echo "[clean_stale_singleton] ${profile_dir##*/}: SingletonLock PID $pid alive; leaving locks intact." >&2
+        exit 0
+    fi
+fi
+
+# Stale: PID dead, malformed, or unreadable. Nuke the singletons so Chrome
+# can launch cleanly. Also drop RunningChromeVersion which Chrome cross-checks.
+rm -f "$profile_dir/SingletonLock" \
+      "$profile_dir/SingletonCookie" \
+      "$profile_dir/SingletonSocket" \
+      "$profile_dir/RunningChromeVersion"
+
+echo "[clean_stale_singleton] ${profile_dir##*/}: cleared stale singleton locks (was PID ${pid:-unknown})." >&2
+exit 0