coalesce-labs/wait-for-github

wait-for-github — Safe GitHub event wait

What this is for

GitHub's GraphQL API costs points per call. gh pr view --json and gh pr checks both use GraphQL. A single worker polling every 30 s burns 120 calls/hr; three concurrent workers drain the 5,000 point/hr budget in under 15 minutes.

catalyst-events wait-for with a long timeout silently never fires when a filter is wrong. Observed in production: a worker sat idle for hours because .attributes."vcs.pr.number" was null on GitHub webhook events (root cause tracked in CTL-234). The 3-minute diagnostic checkpoint in this skill catches that class of failure quickly.

Do not invoke this as a slash command — it is a reference document for skill authors.

Pre-flight: verify event infrastructure

Before starting any wait, confirm the event infrastructure is running:

REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')

STATUS=$(catalyst-monitor status --json 2>/dev/null)
TUNNEL=$(echo "$STATUS" | jq -r '.webhookTunnel.connected // false' 2>/dev/null)
if [ $? -ne 0 ] || [ "$TUNNEL" != "true" ]; then
  echo "WARN: catalyst-monitor not running or tunnel not connected — using REST fallback directly"
  USE_REST=true
fi

If catalyst-monitor is not running or the tunnel is not connected, skip to the REST fallback. Do not attempt event-driven waits against a dead daemon.

Preferred path: broker auto-detect

When the broker daemon is running, register via broker_claim_pr so the broker auto-derives a pr_lifecycle interest and wakes this worker via filter.wake.${CATALYST_SESSION_ID}. This single semantic wake covers all concerns (CI, reviews, comms, BEHIND) with routing-layer dedup and watchdog support. When the daemon is absent, fall back to the two-phase raw event wait.

broker_claim_pr handles the health check internally via wait_for_broker_ready, which retries up to 3 times (CTL-429) before declaring the daemon absent.

Prerequisites

These must be defined before calling broker_claim_pr:

• $CATALYST_SESSION_ID — set by catalyst-session.sh start at oneshot startup
• $STATE_SCRIPT — path to catalyst-state.sh (set at oneshot startup)
• broker_claim_pr, wait_for_broker_ready, broker_daemon_running functions from oneshot/SKILL.md

Snippet

USE_FILTER_DAEMON=false
PR_BASE_BRANCH=$(gh pr view "$PR_NUMBER" --json baseRefName --jq '.baseRefName' 2>/dev/null || echo "main")
if broker_claim_pr "$PR_NUMBER" "$TICKET_ID" "$(git branch --show-current)" "$REPO" "$PR_BASE_BRANCH"; then
  USE_FILTER_DAEMON=true
  echo "[Phase 5] Broker registered pr_lifecycle for session ${CATALYST_SESSION_ID} on PR #${PR_NUMBER}"
else
  # Broker absent — emit telemetry and use two-phase fallback
  "$STATE_SCRIPT" event "$(jq -nc \
    --arg sid "${CATALYST_SESSION_ID:-}" --arg pr "${PR_NUMBER:-}" \
    '{ts: (now | todate), event: "broker.fallback.taken",
      detail: {reason: "daemon absent", session_id: $sid, pr: ($pr | tonumber? // $pr)}}')" \
    2>/dev/null || true
  echo "[Phase 5] Broker unavailable — using two-phase wait-for fallback for PR #${PR_NUMBER}"
fi

PR_DONE=false
while [ "$PR_DONE" = "false" ]; do
  if [ "$USE_FILTER_DAEMON" = "true" ] && [ "$USE_REST" != "true" ]; then
    # Broker path: single semantic wake covers all concerns (CI, reviews, comms, BEHIND)
    EVENT=$(catalyst-events wait-for \
      --filter ".attributes.\"event.name\" == \"filter.wake.${CATALYST_SESSION_ID}\"" \
      --timeout 600 2>/dev/null || true)
    WAKE_REASON=$(echo "$EVENT" | jq -r '.body.payload.reason // "unknown"' 2>/dev/null || echo "unknown")
    echo "wake: filter.wake #${PR_NUMBER} — ${WAKE_REASON}"
  else
    # Two-phase fallback — see "Manual fallback" section below
    EVENT=$(catalyst-events wait-for \
      --filter "(.attributes.\"vcs.pr.number\" == ${PR_NUMBER} or (.body.payload.prNumbers // [] | contains([${PR_NUMBER}]))) and (
        .attributes.\"event.name\" == \"github.pr.merged\" or
        .attributes.\"event.name\" == \"github.check_suite.completed\" or
        (.attributes.\"event.name\" | startswith(\"github.pr_review\")) or
        .attributes.\"event.name\" == \"github.push\"
      )" \
      --timeout 180 2>/dev/null || true)
    # ... run diagnostic checkpoint if empty (see "Manual fallback" section) ...
  fi

  # Authoritative REST check (never gh pr view --json)
  PR_JSON=$(gh api "repos/${REPO}/pulls/${PR_NUMBER}" 2>/dev/null || echo '{}')
  PR_MERGED=$(echo "$PR_JSON" | jq -r '.merged // false')
  MERGE_STATE=$(echo "$PR_JSON" | jq -r '.mergeable_state // "unknown"')

  [ "$PR_MERGED" = "true" ] && PR_DONE=true
  # ... handle merge states (clean/blocked/behind/dirty/unknown) per oneshot Phase 5 ...

  [ "$USE_REST" = "true" ] && sleep 300
done

Manual fallback: raw two-phase wait (no broker)

Use this only when the broker daemon is absent (detected by broker_claim_pr returning non-zero above) or when you are not running inside an oneshot worker that has broker_claim_pr defined. This pattern wakes on raw GitHub webhook events and includes a diagnostic checkpoint.

Phase 1 — Short wait with diagnostic checkpoint (3 minutes)

PR_NUMBER=342   # set by caller
EVENT=""
_WFG_MATCHED=false
_WFG_USE_PHASE2=false
USE_REST=${USE_REST:-false}

if [ "$USE_REST" != "true" ]; then
  EVENT=$(catalyst-events wait-for \
    --filter ".attributes.\"event.name\" == \"github.pr.merged\" and .attributes.\"vcs.pr.number\" == ${PR_NUMBER}" \
    --timeout 180 2>/dev/null || true)

  if [ -n "$EVENT" ]; then
    _WFG_MATCHED=true
  else
    # Phase 1 timed out — run 3 diagnostics before deciding next step
    echo "Phase 1 timed out after 3 min — running diagnostics..."
    STALLED=false
    FILTER_MISMATCH=false

    # Diagnostic 1: heartbeat check
    _LOG_FILE=~/catalyst/events/$(date -u +%Y-%m).jsonl
    _LOG_LINES=$(wc -l < "$_LOG_FILE" 2>/dev/null | tr -d ' ')
    _SINCE_LINE=$(( ${_LOG_LINES:-0} > 500 ? ${_LOG_LINES:-0} - 500 : 0 ))
    HEARTBEATS=$(catalyst-events tail --since-line "$_SINCE_LINE" 2>/dev/null \
      | jq -c 'select(.attributes."event.name" == "session.heartbeat")' | wc -l | tr -d ' ')
    if [ "${HEARTBEATS:-0}" -eq 0 ]; then
      echo "WARN: No heartbeats in the last 5 min — event log may be stalled"
      STALLED=true
    fi

    # Diagnostic 2: raw event search without the filter
    # Look for the PR by multiple fields to detect filter mismatches
    RAW_HIT=$(catalyst-events tail --since-line "$_SINCE_LINE" 2>/dev/null | jq -c \
      --argjson pr "$PR_NUMBER" \
      'select(
        (.attributes."vcs.pr.number" == $pr) or
        (.body.payload.prNumbers // [] | contains([$pr]))
      )' | head -1)

    if [ -n "$RAW_HIT" ]; then
      echo "WARN: Event arrived but the filter did not match. Raw event:"
      echo "$RAW_HIT" | jq .
      echo "This is a filter mismatch — falling back to REST."
      echo "Consider filing a CTL ticket with the raw event above."
      FILTER_MISMATCH=true
    fi

    # Diagnostic 3: tunnel state re-check
    TUNNEL_STATE=$(catalyst-monitor status --json 2>/dev/null \
      | jq -r '.webhookTunnel.connected // false')
    echo "Tunnel connected: $TUNNEL_STATE"
    if [ "$TUNNEL_STATE" != "true" ]; then
      echo "WARN: Webhook tunnel is not running"
      STALLED=true
    fi

    # Decision
    if [ "$FILTER_MISMATCH" = "true" ] || [ "$STALLED" = "true" ]; then
      echo "Infrastructure issue detected — falling back to REST polling"
      USE_REST=true
    else
      echo "Infrastructure looks healthy — extending to Phase 2 (2-hour wait)"
      _WFG_USE_PHASE2=true
    fi
  fi
fi

Phase 2 — Extended wait (only after diagnostics confirm healthy)

if [ "$_WFG_USE_PHASE2" = "true" ]; then
  EVENT=$(catalyst-events wait-for \
    --filter ".attributes.\"event.name\" == \"github.pr.merged\" and .attributes.\"vcs.pr.number\" == ${PR_NUMBER}" \
    --timeout 7200 2>/dev/null || true)

  [ -n "$EVENT" ] && _WFG_MATCHED=true
fi

REST fallback — authoritative confirmation and infrastructure fallback

Use REST after any wait-for path (matched or timed out) for authoritative confirmation, and as the sole path when diagnostics detect infrastructure problems. Use gh api REST endpoints; never gh pr view --json (GraphQL).

# One-shot REST check — allowed; it is not a poll loop
MERGED=$(gh api "repos/${REPO}/pulls/${PR_NUMBER}" --jq '.merged' 2>/dev/null || echo "false")

if [ "$MERGED" = "true" ]; then
  echo "PR $PR_NUMBER is merged"
elif [ "$USE_REST" = "true" ]; then
  # Infrastructure unavailable — REST poll at low frequency (12 calls/hr, well within budget)
  MAX=24  # 2-hour limit at 5-min intervals
  COUNT=0
  while [ "$MERGED" != "true" ] && [ "$COUNT" -lt "$MAX" ]; do
    sleep 300
    MERGED=$(gh api "repos/${REPO}/pulls/${PR_NUMBER}" --jq '.merged' 2>/dev/null || echo "false")
    COUNT=$((COUNT + 1))
  done
fi

Forbidden patterns

Never use these in any skill. They exhaust the GraphQL budget.

| Anti-pattern | Why forbidden | Replacement | |---|---|---| | gh pr view --json in a poll loop | GraphQL, 2+ pts/call, 120/hr per worker | catalyst-events wait-for + one-shot gh api after match | | gh pr checks --json in a poll loop | statusCheckRollup field, same GraphQL cost | catalyst-events wait-for --filter '.attributes."event.name" \| startswith("github.check_")' | | --timeout 7200 as Phase 1 | Silent stall on broken filter for up to 2 hours | Two-phase: 3 min → diagnostics → 7200 s if healthy | | sleep 30 poll loops | GraphQL and compute waste at scale | Event-driven wait | | Any field under statusCheckRollup | GraphQL-only field, not available in REST | .attributes."cicd.pipeline.run.conclusion" on check_run.completed events | | Skipping broker_claim_pr when broker is up | Bypasses routing-layer dedup + watchdog | Use broker auto-detect snippet above |

Known filter pitfalls

| Field | Problem | Fix | |---|---|---| | .attributes."vcs.pr.number" | Null on GitHub webhook events until CTL-234 ships | Also check .body.payload.number or .body.payload.pull_request.number | | .attributes."catalyst.orchestrator.id" | Set on github events when head-branch matches an orch prefix (CTL-234) — a bare clause matches ~60-70% of webhooks for that orchestrator | Combine with an event-type guard from [[event-name-allowlist]] (e.g. .attributes."event.name" == "github.pr.merged" and …) | | .attributes."cicd.pipeline.run.conclusion" | Only on check_run.completed, not check_suite.completed | Use .body.payload.status == "completed" for suite events | | .body.payload.state on reviews | Casing varies (APPROVED vs approved) | Pipe through \| ascii_downcase before comparing | | Exact match on wait-for | Event may arrive before wait-for starts | Always confirm via one-shot gh api after match |

Quick reference

# PREFERRED: broker auto-detect (use when running inside oneshot worker)
# broker_claim_pr registers a pr_lifecycle interest; wake fires on all PR events
broker_claim_pr "$PR_NUMBER" "$TICKET_ID" "$(git branch --show-current)" "$REPO" "$PR_BASE_BRANCH"
catalyst-events wait-for \
  --filter ".attributes.\"event.name\" == \"filter.wake.${CATALYST_SESSION_ID}\"" \
  --timeout 600

# MANUAL FALLBACK: two-phase raw event wait (when broker is absent)
# Phase 1 (3 min) + diagnostic checkpoint
catalyst-events wait-for \
  --filter ".attributes.\"event.name\" == \"github.pr.merged\" and .attributes.\"vcs.pr.number\" == ${PR_NUMBER}" \
  --timeout 180   # Phase 1; extend to 7200 after diagnostics confirm healthy

# CI suite completed — note: check_suite has no vcs.pr.number; use body.payload.prNumbers
catalyst-events wait-for \
  --filter ".attributes.\"event.name\" == \"github.check_suite.completed\" and (.body.payload.prNumbers // [] | index(${PR_NUMBER}) != null)" \
  --timeout 180

# Review submitted
catalyst-events wait-for \
  --filter "(.attributes.\"event.name\" | startswith(\"github.pr_review.\")) and .attributes.\"vcs.pr.number\" == ${PR_NUMBER}" \
  --timeout 180

# REST: check PR merge state (never in a tight loop)
REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
gh api "repos/${REPO}/pulls/${PR_NUMBER}" --jq '.merged'

# Probe broker health directly (exits 0 if running, non-zero if not)
catalyst-broker probe; echo "exit=$?"

Related skills

• monitor-events — canonical event-driven wait reference, filter cookbook, Monitor vs wait-for
• orchestrate Phase 4 — uses Monitor over catalyst-events tail for multi-worker fan-out
• merge-pr — uses this two-phase pattern for post-merge cleanup
• create-pr — uses this pattern for CI gate before arming auto-merge