Skip to content

Business operating system for Claude Code — 57 skills, 21 agents, smart daemon. Unified inbox (WhatsApp/Email/Slack/Telegram), autonomous PR merge, full-AWS monitoring, revenue (Stripe+RevenueCat), e-commerce (Shopify), marketing (Klaviyo/Meta/GA4), voice (Bland/ElevenLabs), APM (Datadog/NewRelic/OTEL), YOLO mode.

feat(ops-inbox): Mac WhatsApp.app fallback suite — Tier-4 archive + auto ground-truth + Cloudflare-tunnel transport (#560)

Aurora Capital656b7be3d13a
diff --git a/claude-ops/bin/wa-inbox-fresh.sh b/claude-ops/bin/wa-inbox-fresh.sh
index de444cc3..800130e5 100755
--- a/claude-ops/bin/wa-inbox-fresh.sh
+++ b/claude-ops/bin/wa-inbox-fresh.sh
@@ -22,6 +22,22 @@ WAIT_TICKS="${WA_FRESH_WAIT_TICKS:-8}" # ×4s ≈ 32s max wait
log() { printf '%s\n' "$*"; }
+# Mac ground-truth cross-check — AUTOMATIC when the store looks stale.
+# Reads the Mac WhatsApp.app ChatStorage over Tailscale SSH (Cloudflare-tunnel
+# fallback via wa-mac-transport.sh). Read-only, bounded, never fatal.
+mac_ground_truth() {
+ local script mac_out
+ script="$(dirname "$0")/wa-mac-latest.sh"
+ [ -x "$script" ] || script="$HOME/bin/wa-mac-latest.sh"
+ [ -x "$script" ] || { log "wa-fresh: mac cross-check skipped (wa-mac-latest.sh not installed)"; return 0; }
+ log "wa-fresh: MAC GROUND TRUTH (latest 10 from WhatsApp.app store):"
+ if mac_out=$(WA_MAC_QUIET=1 timeout 50 "$script" --recent 10 2>/dev/null); then
+ printf '%s\n' "$mac_out" | sed 's/^/wa-fresh: /'
+ else
+ log "wa-fresh: mac cross-check unavailable (Mac unreachable over tailscale + cloudflare)"
+ fi
+}
+
# 1. bridge up? Liveness = a real TCP/HTTP connection to :8080.
# curl exit 7 = connection refused (not listening); exit 0 even on 404.
# Do NOT use `ss | grep :8080` — ss renders port 8080 as the service name
@@ -71,6 +87,7 @@ if ! alive; then
else
log "wa-fresh: ERROR bridge still down — store is STALE, do not trust it"
fi
+ mac_ground_truth
exit 2
fi
@@ -82,11 +99,13 @@ fi
if [ ! -r "$DB" ]; then
log "wa-fresh: ERROR messages store missing or unreadable at $DB — do not trust it"
+ mac_ground_truth
exit 2
fi
before=$(sqlite3 "$DB" "SELECT COALESCE(datetime(MAX(timestamp)),'1970-01-01') FROM messages;") || {
log "wa-fresh: ERROR cannot read messages store at $DB — do not trust it"
+ mac_ground_truth
exit 2
}
@@ -97,6 +116,7 @@ case "$code" in
2*) ;;
*)
log "wa-fresh: ERROR backfill failed (HTTP ${code}) — store may be stale, do not trust it"
+ mac_ground_truth
exit 2
;;
esac
@@ -161,13 +181,14 @@ fi
# 5. freshness report
after=$(sqlite3 "$DB" "SELECT COALESCE(datetime(MAX(timestamp)),'?') FROM messages;") || {
log "wa-fresh: ERROR cannot read messages store at $DB — do not trust it"
+ mac_ground_truth
exit 2
}
age_min=$(sqlite3 "$DB" "SELECT CAST((julianday('now')-julianday(MAX(timestamp)))*1440 AS INT) FROM messages;") || age_min=""
log "wa-fresh: newest message = ${after} (${age_min:-?} min old) | new rows this cycle = ${new}"
if [ "${age_min:-9999}" -gt 120 ]; then
log "wa-fresh: WARNING newest message is >2h old — store may be lagging; treat 'last-sender' classification with caution"
- log "wa-fresh: store may be lagging — cross-check Mac ground truth: bin/wa-mac-latest.sh --recent"
+ mac_ground_truth
fi
log "wa-fresh: NOTE phone-sent messages may be absent — confirm 'did I reply?' with the human, not this store"
exit 0
diff --git a/claude-ops/bin/wa-mac-archive.sh b/claude-ops/bin/wa-mac-archive.sh
new file mode 100755
index 00000000..6943bdda
--- /dev/null
+++ b/claude-ops/bin/wa-mac-archive.sh
@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# wa-mac-archive.sh — Tier-4 WhatsApp archive fallback via the Mac WhatsApp.app.
+#
+# When the whatsmeow bridge cannot archive (app-state 429 rate-overlimit, LTHash
+# wedge that resync can't heal), this script archives chats through the REAL
+# WhatsApp.app on the owner's Mac via AppleScript UI automation over SSH.
+# Because the Mac app is a first-class WhatsApp client, its archive mutations
+# sync server-side to the phone AND propagate back to the bridge — no bridge
+# app-state writes needed, so the 429 path is bypassed entirely.
+#
+# SCOPE GUARD: this script can ONLY archive. It never sends, deletes, or mutates
+# anything else. Outbound sends remain on the bridge under the Rule-6 gate.
+#
+# Usage:
+# wa-mac-archive.sh --contact "<name or number>" archive one chat
+# wa-mac-archive.sh --jid <[email protected]> archive one chat by JID
+# wa-mac-archive.sh --batch <file> one JID-or-name per line
+# add --dry-run to resolve + report without touching the UI
+#
+# Transport: wa-mac-transport.sh (Tailscale first, Cloudflare tunnel fallback).
+# Env: WA_MAC_SSH / WA_MAC_CF_HOST (see wa-mac-transport.sh), WA_MAC_PACE (s, default 4)
+set -euo pipefail
+# shellcheck source=wa-mac-transport.sh
+. "$(dirname "${BASH_SOURCE[0]}")/wa-mac-transport.sh" 2>/dev/null || . "$HOME/bin/wa-mac-transport.sh"
+
+DB='$HOME/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite'
+PACE="${WA_MAC_PACE:-4}"
+DRY=0; TARGETS=()
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --contact|--jid) TARGETS+=("${2:?}"); shift ;;
+ --batch) while IFS= read -r l; do [ -n "$l" ] && TARGETS+=("$l"); done < "${2:?}"; shift ;;
+ --dry-run) DRY=1 ;;
+ *) echo "unknown arg: $1" >&2; exit 64 ;;
+ esac; shift
+done
+[ ${#TARGETS[@]} -gt 0 ] || { echo "no targets — use --contact/--jid/--batch" >&2; exit 64; }
+
+wa_mac_resolve || { echo "wa-mac-archive: Mac unreachable (tailscale + cloudflare)" >&2; exit 7; }
+echo "wa-mac-archive: transport=$WA_MAC_TRANSPORT, targets=${#TARGETS[@]}, pace=${PACE}s"
+
+# AppleScript runner: opens the chat via in-app search, then clicks the menu-bar
+# item whose name contains "Archive" (locale-robust: NL "Archiveer" also matches
+# via the fallback list). Runs inside the Aqua session via launchctl asuser.
+run_archive_ui() { # $1 = partner display name
+ local name="$1"
+ # The UI automation runs REMOTELY on the Mac — require the remote host to be
+ # Darwin before driving it (also satisfies the macOS-only-tool lint guard).
+ if [ "${WA_MAC_REMOTE_OS:=$(wa_mac_ssh uname 2>/dev/null)}" = "Darwin" ]; then
+ wa_mac_ssh 'cat > /tmp/wa_archive.scpt && UID_N=$(id -u) && sudo -n launchctl asuser "$UID_N" sudo -u "$(whoami)" osascript /tmp/wa_archive.scpt' <<EOF
+on run
+ set chatName to "$(printf '%s' "$name" | sed 's/"/\\"/g')"
+ tell application "WhatsApp" to activate
+ delay 1.2
+ tell application "System Events"
+ tell process "WhatsApp"
+ keystroke "f" using {command down}
+ delay 0.6
+ keystroke chatName
+ delay 1.4
+ key code 125 -- down: first search result
+ delay 0.4
+ key code 36 -- return: open chat
+ delay 1.0
+ -- find an Archive menu item anywhere in the menu bar (EN/NL/DE/etc.)
+ set archived to false
+ repeat with mb in menu bar items of menu bar 1
+ try
+ repeat with mi in menu items of menu 1 of mb
+ set t to (name of mi as text)
+ if t contains "Archive" or t contains "Archiveer" or t contains "Archivier" then
+ click mi
+ set archived to true
+ exit repeat
+ end if
+ end repeat
+ end try
+ if archived then exit repeat
+ end repeat
+ -- clear search state
+ key code 53 -- esc
+ if not archived then error "no Archive menu item found for " & chatName
+ end tell
+ end tell
+end run
+EOF
+ else
+ echo "remote host is not Darwin — refusing UI automation" >&2
+ return 1
+ fi
+}
+
+ok=0; fail=0; skip=0
+for t in "${TARGETS[@]}"; do
+ q=$(printf '%s' "$t" | sed "s/'/''/g")
+ row=$(wa_mac_ssh "sqlite3 -separator $'\x1f' \"$DB\" \"SELECT ZPARTNERNAME, COALESCE(ZARCHIVED,0) FROM ZWACHATSESSION WHERE ZCONTACTJID='$q' OR ZPARTNERNAME LIKE '%$q%' ORDER BY ZLASTMESSAGEDATE DESC LIMIT 1;\"" 2>/dev/null || true)
+ name="${row%%$'\x1f'*}"; arch="${row##*$'\x1f'}"
+ if [ -z "$name" ]; then echo " MISS $t (no Mac chat found)"; fail=$((fail+1)); continue; fi
+ if [ "$arch" = "1" ]; then echo " SKIP $name (already archived on Mac)"; skip=$((skip+1)); continue; fi
+ if [ "$DRY" = 1 ]; then echo " DRY $name"; ok=$((ok+1)); continue; fi
+ ui_err=""
+ if ui_err=$(run_archive_ui "$name" 2>&1 >/dev/null); then
+ sleep 1
+ v=$(wa_mac_ssh "sqlite3 \"$DB\" \"SELECT COALESCE(ZARCHIVED,0) FROM ZWACHATSESSION WHERE ZPARTNERNAME='$(printf '%s' "$name" | sed "s/'/''/g")' ORDER BY ZLASTMESSAGEDATE DESC LIMIT 1;\"" 2>/dev/null || echo "?")
+ if [ "$v" = "1" ]; then echo " OK $name (verified ZARCHIVED=1)"; else echo " OK? $name (UI action done, ZARCHIVED=$v — verify visually)"; fi
+ ok=$((ok+1))
+ else
+ if [ -n "$ui_err" ]; then
+ echo " FAIL $name ($ui_err)"
+ else
+ echo " FAIL $name (remote AppleScript error — check Accessibility permission for sshd on the Mac)"
+ fi
+ fail=$((fail+1))
+ fi
+ sleep "$PACE"
+done
+echo "wa-mac-archive: done — ok=$ok skip=$skip fail=$fail"
+[ "$fail" -eq 0 ]
diff --git a/claude-ops/bin/wa-mac-latest.sh b/claude-ops/bin/wa-mac-latest.sh
index 8ceeddae..1b23e7de 100755
--- a/claude-ops/bin/wa-mac-latest.sh
+++ b/claude-ops/bin/wa-mac-latest.sh
@@ -9,9 +9,11 @@
# wa-mac-latest.sh --contact <q> [N] latest N for a contact by name or number (default 12)
# wa-mac-latest.sh --since "YYYY-MM-DD HH:MM" all messages since a local timestamp
# add --json for machine-readable output
-# Env: WA_MAC_SSH ssh target (REQUIRED, e.g. user@mac-host)
+# Env: WA_MAC_SSH (direct/Tailscale target) and/or WA_MAC_CF_HOST (cloudflared
+# SSH hostname fallback) — resolved via wa-mac-transport.sh, Tailscale first.
set -euo pipefail
-MAC="${WA_MAC_SSH:?set WA_MAC_SSH=user@mac-host (Tailscale ssh target)}"
+# shellcheck source=wa-mac-transport.sh
+. "$(dirname "${BASH_SOURCE[0]}")/wa-mac-transport.sh" 2>/dev/null || . "$HOME/bin/wa-mac-transport.sh"
DB='$HOME/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite'
AE=978307200
JSON=0; MODE="recent"; ARG=""; N=""
@@ -31,7 +33,9 @@ case "$MODE" in
contact) q=$(printf '%s' "$ARG"|sed "s/'/''/g"); SQL="SELECT $dt,m.ZISFROMME,s.ZPARTNERNAME,substr(m.ZTEXT,1,200) FROM ZWAMESSAGE m JOIN ZWACHATSESSION s ON m.ZCHATSESSION=s.Z_PK WHERE (s.ZPARTNERNAME LIKE '%$q%' OR s.ZCONTACTJID LIKE '%$q%') AND m.ZTEXT IS NOT NULL ORDER BY m.ZMESSAGEDATE DESC LIMIT $LIMIT;" ;;
since) ts=$(printf '%s' "$ARG"|sed "s/'/''/g"); SQL="SELECT $dt,m.ZISFROMME,s.ZPARTNERNAME,substr(m.ZTEXT,1,160) FROM ZWAMESSAGE m JOIN ZWACHATSESSION s ON m.ZCHATSESSION=s.Z_PK WHERE m.ZTEXT IS NOT NULL AND $dt >= '$ts' ORDER BY m.ZMESSAGEDATE DESC;" ;;
esac
-raw=$(timeout 35 ssh -o StrictHostKeyChecking=no -o ConnectTimeout=10 "$MAC" "sqlite3 -separator $'\x1f' \"$DB\" \"$SQL\"" 2>&1) || { echo "ERROR: could not reach Mac WhatsApp DB ($MAC). $raw" >&2; exit 2; }
+wa_mac_resolve || { echo "ERROR: Mac unreachable over tailscale AND cloudflare — cannot read WhatsApp ground truth" >&2; exit 2; }
+raw=$(timeout 35 ssh "${WA_MAC_SSH_ARGS[@]}" "sqlite3 -separator $'\x1f' \"$DB\" \"$SQL\"" 2>&1) || { echo "ERROR: could not read Mac WhatsApp DB (transport=$WA_MAC_TRANSPORT). $raw" >&2; exit 2; }
+[ "${WA_MAC_QUIET:-0}" = 1 ] || echo "wa-mac: transport=$WA_MAC_TRANSPORT" >&2
if [ "$JSON" = 1 ]; then
printf '%s\n' "$raw" | python3 -c 'import sys,json;US="\x1f";o=[]
for l in sys.stdin:
diff --git a/claude-ops/bin/wa-mac-transport.sh b/claude-ops/bin/wa-mac-transport.sh
new file mode 100755
index 00000000..13264af3
--- /dev/null
+++ b/claude-ops/bin/wa-mac-transport.sh
@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# wa-mac-transport.sh — shared transport resolver for reaching the owner's Mac
+# (the machine running WhatsApp.app, used as ground-truth fallback by
+# wa-mac-latest.sh and wa-mac-archive.sh).
+#
+# Resolves a working SSH transport in priority order:
+# 1. Tailscale / direct SSH (WA_MAC_SSH, e.g. [email protected])
+# 2. Cloudflare tunnel SSH (WA_MAC_CF_HOST, e.g. ssh-mac.example.com,
+# via `cloudflared access ssh` ProxyCommand — works when Tailscale is down)
+#
+# Source this file, then call:
+# wa_mac_resolve # sets WA_MAC_TRANSPORT (tailscale|cloudflare|none)
+# # and fills WA_MAC_SSH_ARGS array; rc 1 if none work
+# wa_mac_ssh <cmd...> # run a command on the Mac over the resolved transport
+#
+# Env (no committed defaults — set these in your shell profile, never here):
+# WA_MAC_SSH direct ssh target, user@host (transport 1)
+# WA_MAC_CF_HOST cloudflared SSH hostname (transport 2, optional)
+# WA_MAC_CF_USER ssh user for the CF path (default: user part of WA_MAC_SSH)
+# WA_MAC_SSH_OPTS extra ssh options (optional)
+
+WA_MAC_TS_TARGET="${WA_MAC_SSH:-}"
+WA_MAC_CF_HOST="${WA_MAC_CF_HOST:-}"
+WA_MAC_CF_USER="${WA_MAC_CF_USER:-${WA_MAC_TS_TARGET%%@*}}"
+WA_MAC_TRANSPORT="none"
+WA_MAC_SSH_ARGS=()
+
+_wa_mac_common_opts=(-o BatchMode=yes -o ConnectTimeout=6 -o StrictHostKeyChecking=accept-new)
+_wa_mac_ssh_opts=()
+if [ -n "${WA_MAC_SSH_OPTS:-}" ]; then
+ # shellcheck disable=SC2206
+ _wa_mac_ssh_opts=(${WA_MAC_SSH_OPTS})
+fi
+
+wa_mac_resolve() {
+ # 1. Tailscale / direct SSH
+ if [ -n "$WA_MAC_TS_TARGET" ] && \
+ ssh "${_wa_mac_common_opts[@]}" "${_wa_mac_ssh_opts[@]}" "$WA_MAC_TS_TARGET" true 2>/dev/null; then
+ WA_MAC_TRANSPORT="tailscale"
+ WA_MAC_SSH_ARGS=("${_wa_mac_common_opts[@]}" "${_wa_mac_ssh_opts[@]}" "$WA_MAC_TS_TARGET")
+ return 0
+ fi
+ # 2. Cloudflare tunnel SSH (cloudflared access ssh)
+ if [ -n "$WA_MAC_CF_HOST" ] && [ -n "$WA_MAC_CF_USER" ] && command -v cloudflared >/dev/null 2>&1; then
+ local proxy="cloudflared access ssh --hostname $WA_MAC_CF_HOST"
+ if ssh "${_wa_mac_common_opts[@]}" -o ProxyCommand="$proxy" \
+ "${_wa_mac_ssh_opts[@]}" "${WA_MAC_CF_USER}@${WA_MAC_CF_HOST}" true 2>/dev/null; then
+ WA_MAC_TRANSPORT="cloudflare"
+ WA_MAC_SSH_ARGS=("${_wa_mac_common_opts[@]}" -o ProxyCommand="$proxy" "${_wa_mac_ssh_opts[@]}" "${WA_MAC_CF_USER}@${WA_MAC_CF_HOST}")
+ return 0
+ fi
+ fi
+ WA_MAC_TRANSPORT="none"
+ WA_MAC_SSH_ARGS=()
+ return 1
+}
+
+wa_mac_ssh() {
+ if [ "$WA_MAC_TRANSPORT" = "none" ] || [ ${#WA_MAC_SSH_ARGS[@]} -eq 0 ]; then
+ wa_mac_resolve || { echo "wa-mac: Mac unreachable (tailscale + cloudflare both down/unconfigured)" >&2; return 7; }
+ fi
+ ssh "${WA_MAC_SSH_ARGS[@]}" "$@"
+}
diff --git a/claude-ops/scripts/install-whatsapp-bridge-linux.sh b/claude-ops/scripts/install-whatsapp-bridge-linux.sh
index bdf8bc61..2449ab13 100755
--- a/claude-ops/scripts/install-whatsapp-bridge-linux.sh
+++ b/claude-ops/scripts/install-whatsapp-bridge-linux.sh
@@ -123,6 +123,13 @@ mkdir -p "$HOME/bin"
cp "$SCRIPT_DIR/../bin/wa-inbox-fresh.sh" "$HOME/bin/wa-inbox-fresh.sh"
chmod +x "$HOME/bin/wa-inbox-fresh.sh"
+# ─── Ship Mac ground-truth fallback suite (reader + Tier-4 archiver + transport) ─
+echo "▶ Installing wa-mac-{transport,latest,archive}.sh → ~/bin (Mac WhatsApp.app fallback)"
+for f in wa-mac-transport.sh wa-mac-latest.sh wa-mac-archive.sh; do
+ cp "$SCRIPT_DIR/../bin/$f" "$HOME/bin/$f"
+ chmod +x "$HOME/bin/$f"
+done
+
# ─── Ship wa-bridge-keepalive.sh (hang-detection so phone-sends always sync) ──
echo "▶ Installing wa-bridge-keepalive.sh → ~/bin (uptime watchdog)"
cp "$SCRIPT_DIR/../bin/wa-bridge-keepalive.sh" "$HOME/bin/wa-bridge-keepalive.sh"
diff --git a/claude-ops/scripts/setup-wa-mac-cf-tunnel.sh b/claude-ops/scripts/setup-wa-mac-cf-tunnel.sh
new file mode 100755
index 00000000..e55fc984
--- /dev/null
+++ b/claude-ops/scripts/setup-wa-mac-cf-tunnel.sh
@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# setup-wa-mac-cf-tunnel.sh — wire the Cloudflare-tunnel SSH fallback to the
+# owner's Mac (transport 2 of wa-mac-transport.sh).
+#
+# What it does:
+# LOCAL (this box): installs cloudflared if missing (dnf/apt/brew).
+# MAC (over the currently-working SSH path, usually Tailscale):
+# - installs cloudflared via brew if missing
+# - installs the tunnel as a LaunchDaemon using a remotely-managed tunnel
+# token (CF_TUNNEL_TOKEN) so it survives reboots
+# Prints the env exports to add to your shell profile.
+#
+# Prereqs (one-time, in the Cloudflare Zero Trust dashboard):
+# 1. Create a tunnel (remotely-managed), copy its token → CF_TUNNEL_TOKEN
+# 2. Add a public hostname route: <WA_MAC_CF_HOST> → ssh://localhost:22
+# 3. (Recommended) Add an Access application + service token or allow-policy
+# for that hostname so the SSH port isn't open to the world.
+#
+# Usage:
+# WA_MAC_SSH=user@mac-tailscale-ip \
+# WA_MAC_CF_HOST=ssh-mac.example.com \
+# CF_TUNNEL_TOKEN=<token> \
+# bash setup-wa-mac-cf-tunnel.sh
+set -euo pipefail
+
+: "${WA_MAC_SSH:?set WA_MAC_SSH=user@mac-host (a currently-working SSH path to the Mac)}"
+: "${WA_MAC_CF_HOST:?set WA_MAC_CF_HOST=ssh hostname routed in the CF tunnel}"
+: "${CF_TUNNEL_TOKEN:?set CF_TUNNEL_TOKEN=<remotely-managed tunnel token>}"
+
+echo "▶ 1/3 local cloudflared"
+if ! command -v cloudflared >/dev/null 2>&1; then
+ if command -v dnf >/dev/null 2>&1; then
+ sudo dnf install -y https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-$(uname -m | sed 's/aarch64/arm64/;s/x86_64/amd64/').rpm
+ elif command -v apt-get >/dev/null 2>&1; then
+ curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb -o /tmp/cloudflared.deb && sudo dpkg -i /tmp/cloudflared.deb
+ elif command -v brew >/dev/null 2>&1; then
+ brew install cloudflared
+ else
+ echo "install cloudflared manually: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/" >&2; exit 1
+ fi
+fi
+cloudflared --version
+
+echo "▶ 2/3 Mac-side cloudflared LaunchDaemon (over $WA_MAC_SSH)"
+ssh -o BatchMode=yes -o ConnectTimeout=8 "$WA_MAC_SSH" "
+ set -e
+ if ! command -v cloudflared >/dev/null 2>&1; then
+ if command -v brew >/dev/null 2>&1; then brew install cloudflared
+ else echo 'brew missing on Mac — install cloudflared manually' >&2; exit 1; fi
+ fi
+ # idempotent: reinstall service with the (possibly rotated) token
+ sudo -n cloudflared service uninstall >/dev/null 2>&1 || true
+ sudo -n cloudflared service install '$CF_TUNNEL_TOKEN'
+ sleep 3
+ sudo -n launchctl list | grep -i cloudflare || true
+ echo 'mac: cloudflared service installed'
+"
+
+echo "▶ 3/3 verify CF path end-to-end"
+USER_PART="${WA_MAC_SSH%%@*}"
+if ssh -o BatchMode=yes -o ConnectTimeout=10 \
+ -o ProxyCommand="cloudflared access ssh --hostname $WA_MAC_CF_HOST" \
+ "${USER_PART}@${WA_MAC_CF_HOST}" true; then
+ echo "✓ Cloudflare-tunnel SSH to Mac works"
+else
+ echo "✗ CF path not working yet — check the tunnel's public-hostname route (ssh://localhost:22) and Access policy" >&2
+ exit 1
+fi
+
+cat <<EOF
+
+Add to your shell profile (and the daemon env if used by timers):
+ export WA_MAC_SSH=$WA_MAC_SSH
+ export WA_MAC_CF_HOST=$WA_MAC_CF_HOST
+EOF
diff --git a/claude-ops/skills/ops-inbox/SKILL.md b/claude-ops/skills/ops-inbox/SKILL.md
index 5b9fd7cf..f1a80784 100644
--- a/claude-ops/skills/ops-inbox/SKILL.md
+++ b/claude-ops/skills/ops-inbox/SKILL.md
@@ -87,9 +87,11 @@ Before executing, load available context:
The whatsmeow bridge can **silently miss inbound messages** when its history/app-state sync lags — most often on `@lid` chats (e.g. 2026-06-11 it missed a reply from a contact that the Mac WhatsApp.app had). The Mac app keeps an **unencrypted** local Core Data store at `~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite`, readable over Tailscale SSH, so it is a reliable ground-truth backstop.
-- **When to use:** if `wa-inbox-fresh.sh` reports the store is **STALE** (exit 2, or "newest message" far older than expected), OR a contact's *known* reply is missing from the bridge (common on `@lid` chats), cross-check the Mac app's ground-truth store before classifying that thread as "no reply".
-- **Command:** `bin/wa-mac-latest.sh --contact <name|number> [N]` (also `--recent [N]`, `--since "YYYY-MM-DD HH:MM"`, add `--json` for machine-readable output). It reads `~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite` over Tailscale SSH (target via `WA_MAC_SSH`, e.g. `user@mac-host`). Schema: `ZWAMESSAGE` (`ZTEXT`, `ZISFROMME`, `ZMESSAGEDATE` = seconds since 2001-01-01) joined to `ZWACHATSESSION` (`ZPARTNERNAME`, `ZCONTACTJID`).
-- **READ-ONLY ground truth.** This reader never writes and never sends. Sends still go through the whatsmeow bridge (`mcp__whatsapp__send_message`) under the Rule-6 outbound-approval gate — the Mac store is only consulted to confirm what actually arrived.
+- **When it runs AUTOMATICALLY:** `wa-inbox-fresh.sh` now invokes the Mac cross-check itself whenever the bridge store looks stale — on exit 2 (store unreadable) or when the newest message is >2h old, it prints a `MAC GROUND TRUTH` block (latest 10 messages from the Mac app store) inline in the freshness report. No orchestration needed.
+- **When to use manually:** a contact's *known* reply is missing from the bridge (common on `@lid` chats) — cross-check before classifying that thread as "no reply".
+- **Command:** `bin/wa-mac-latest.sh --contact <name|number> [N]` (also `--recent [N]`, `--since "YYYY-MM-DD HH:MM"`, add `--json` for machine-readable output). It reads `~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite` over SSH. Schema: `ZWAMESSAGE` (`ZTEXT`, `ZISFROMME`, `ZMESSAGEDATE` = seconds since 2001-01-01) joined to `ZWACHATSESSION` (`ZPARTNERNAME`, `ZCONTACTJID`).
+- **Transport chain (`bin/wa-mac-transport.sh`, shared by all wa-mac-* scripts):** ① Tailscale/direct SSH (`WA_MAC_SSH=user@host`) → ② Cloudflare-tunnel SSH (`WA_MAC_CF_HOST=ssh-mac.example.com`, via `cloudflared access ssh` ProxyCommand) when Tailscale is down. One-time wiring: `scripts/setup-wa-mac-cf-tunnel.sh` (installs cloudflared locally + the Mac LaunchDaemon from a remotely-managed tunnel token, then verifies end-to-end). Both env vars live in the shell profile, never in the repo.
+- **READ-ONLY ground truth for reads.** The reader never writes and never sends. Sends still go through the whatsmeow bridge (`mcp__whatsapp__send_message`) under the Rule-6 outbound-approval gate — the Mac store is only consulted to confirm what actually arrived. The ONLY write-capable Mac surface is `wa-mac-archive.sh` (archive-only, see Tier 4 of the archive ladder).
- **Why no Linux-native alternative:** there is no official WhatsApp Linux desktop app; the third-party Flatpak clients (`whatsapp-for-linux`, ZapZap) are Electron WhatsApp-Web wrappers that need a GUI, consume a linked-device slot, and store data in encrypted IndexedDB (not a queryable SQLite) — so the Mac `ChatStorage.sqlite` is the preferred backstop.
**The FULL-THREAD AWARENESS GATE (in "Processing each channel") depends on this step having run first.** That gate's "read both directions incl. `[voice]`" only works once `wa-inbox-fresh.sh` (freshness + backfill) and the voice-note transcription pass (step 0c) have completed and the store has settled — otherwise outbound rows and `[voice]` bodies are still missing and the gate reads an incomplete thread.
@@ -528,6 +530,12 @@ All channel credentials come from env vars or CLI auth — no hardcoded secrets.
- Expect one 429 rate-overlimit pause (~15–20 min) mid skip-loop; it resumes automatically. Success log: `"regular_low sync complete (skipped N bad patches)"` → `"archive mutations enabled"`.
- Upstream: tulir/whatsmeow#1171 (SkipBrokenAppStatePatches). When merged, Fix T + Fix V can be retired.
+ **Tier 4 — server-side rate-limit (429 `rate-overlimit`) or tiers 1–3 exhausted**: WhatsApp's servers are throttling app-state fetches for the account, so NO bridge-side mutation can land (this is server-side; resync retries just re-429). Bypass the bridge entirely and archive via the REAL Mac WhatsApp.app:
+ ```bash
+ bin/wa-mac-archive.sh --batch <file-with-one-jid-or-name-per-line> # or --contact "<name>" / --jid <[email protected]>
+ ```
+ The Mac app is a first-class client — its archive mutations sync server-side to the phone and propagate back to the bridge once its app-state heals. The script is **archive-only** (scope-guarded; it can never send or delete), resolves chats from the Mac `ChatStorage.sqlite`, drives the app via AppleScript UI automation in the Aqua session, verifies `ZARCHIVED=1` per chat, and paces (default 4s). Transport = `wa-mac-transport.sh` (Tailscale → Cloudflare tunnel). Map `@lid` JIDs to phone JIDs or names first (the scan JSON carries both). Requires the Mac online on either transport + Accessibility permission for the SSH-launched osascript; on failure it reports per-chat `FAIL` — fall back to waiting out the 429 (15–60 min) and retry Tier 1.
+
Surface the appropriate tier to the user when archive blocks; don't abandon inbox-zero.
## Core principle: FULL INBOX SCAN