@trygocode/notify 0.1.6 → 0.3.1

package/snippets/ralph-homer.sh

@@ -1,21 +1,341 @@
 # gocode-notify — Ralph/Homer loop opt-in snippet  (PRD §5.6, trigger C)
 #
 # OPT-IN. This snippet is NOT auto-injected by `gocode-notify setup`; the
-# installer never edits your loop scripts without consent. Paste these two
-# lines into the completion/halt path of any loop you control (this repo's
-# `ralph`/`homer` skills, Geoffrey Huntley's `while :; do … done` one-liner,
-# or your own driver) to get a phone push when the loop finishes or halts.
+# installer never edits your loop scripts without consent. Paste the relevant
+# stanzas into the completion/halt/stall paths of any loop you control (this
+# repo's `ralph`/`homer` skills, Geoffrey Huntley's `while :; do … done`
+# one-liner, or your own driver) to get phone pushes for the right events.
 #
 # Prereq: you've already paired this machine once with
 #   npx @trygocode/notify@latest login --code <CODE>
 # (get <CODE> from the GoCode app → "Connect a coding agent").
 #
-# Both lines are fire-and-forget: the `|| true` guarantees a failed/slow push
+# All calls are fire-and-forget: the `|| true` guarantees a failed/slow push
 # can never block or fail your loop (the CLI also self-times-out in 5s).
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# KIND CONTRACT (PRD §4 "Notify Human-Gating")
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# The *kind* is the contract. The GoCode server classifies every kind into
+# exactly one push-worthiness bucket. Callers only need to emit the RIGHT kind;
+# the server handles foreground-suppression, stall-dedup, and FCM delivery.
+#
+#  Kind                 Push-worthy?  When to emit
+#  ─────────────────    ────────────  ────────────────────────────────────────
+#  loop_completed       ✅  YES       Loop finished all work cleanly.
+#  ralph_completed      ✅  YES       Ralph-specific alias for loop_completed.
+#  loop_halted          ✅  YES       Loop paused — a HUMAN is needed.
+#  ralph_halted         ✅  YES       Ralph-specific alias for loop_halted.
+#                                     Covers: user_blocking question, max
+#                                     consecutive failures.
+#  ralph_synth_question ✅  YES       Setup question raised BEFORE the loop
+#                                     starts — genuinely needs a human.
+#  ralph_waiting        ✅  EDGE ONLY Offline / quota stall. Emit ONLY on the
+#                                     stall EDGE (first failure). Server drops
+#                                     repeats until a resumed/completed/halted
+#                                     re-arms the edge. See pattern below.
+#  ralph_resumed        🔕  NO push   Stall recovered; loop running again.
+#                                     Silent control event: its only effect is
+#                                     to reset the server-side stall state
+#                                     machine back to ARMED so the NEXT genuine
+#                                     stall edge will push again.
+#  ralph_question       🔕  NO push   In-loop question the Oracle answers
+#                                     autonomously. Server logs it for the
+#                                     dashboard but NEVER sends to FCM. Do NOT
+#                                     emit this on oracle-answerable paths.
+#  ralph_advanced       🔕  NO push   Queue advanced to next PRD (info only).
+#  finished             ✅  YES       Generic agent-finished (non-loop hooks).
+#  awaiting_input       ✅  YES       Generic agent needs the human (non-loop).
+#  error                ✅  YES       Generic agent hit an error.
+#
+# Rule: only emit push-worthy kinds on the paths where a HUMAN is genuinely
+# needed. Oracle-answerable questions and routine loop events must be silent.
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# PATTERN 1 — Loop completion (all work done cleanly)
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Use loop_completed (or ralph_completed for Ralph-specific loops).
+gocode-notify send --kind loop_completed --source ralph \
+  --project "$(basename "$PWD")" || true
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PATTERN 2 — Loop halt (a HUMAN is needed — user_blocking / max-failures)
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# Emit ralph_halted ONLY when the loop is genuinely paused awaiting human action:
+#   - A user_blocking question was raised (the Oracle cannot answer it).
+#   - The loop hit max consecutive failures and stopped.
+#
+# Do NOT emit ralph_halted for oracle-answerable (blocking) questions — the
+# Oracle handles those autonomously; emitting halted would be a false alarm.
+
+gocode-notify send --kind ralph_halted --source ralph \
+  --project "$(basename "$PWD")" \
+  --title "Ralph halted — needs you" || true
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PATTERN 3 — Offline / quota stall (edge-triggered, NOT every retry)
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# A loop that polls every ~60s on a network/quota outage must push ONCE when
+# it first stalls, stay SILENT while still stalled, and push AGAIN only after
+# it recovers and then stalls again. Never spam on every retry.
+#
+# Caller-side responsibility: only fire ralph_waiting on the EDGE (first stall),
+# not on every subsequent retry. The server also deduplicates repeats as a
+# defense-in-depth backstop.
+#
+# Shell pattern (adapt to your loop's retry logic):
+
+_stall_notified=0   # reset to 0 at loop start or after recovery
+
+# Inside your retry / offline-backoff loop:
+if [[ "$_stall_notified" -eq 0 ]]; then
+  # First time we're stalled — notify on the edge.
+  gocode-notify send --kind ralph_waiting --source ralph \
+    --project "$(basename "$PWD")" \
+    --title "Ralph waiting — offline or quota" || true
+  _stall_notified=1
+fi
+sleep 60
+
+# When the endpoint recovers — emit ralph_resumed to reset the server edge state.
+# This re-arms the next genuine stall edge so it will push again.
+# Then reset the caller-side flag.
+_stall_notified=0
+gocode-notify send --kind ralph_resumed --source ralph \
+  --project "$(basename "$PWD")" || true
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PATTERN 4 — Oracle-answerable question (SILENT — do NOT push)
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# When the loop raises a question that the Oracle will answer autonomously
+# (a normal "blocking" question, not "user_blocking"), emit NOTHING. The
+# Oracle will handle it and the loop will continue with no human in the picture.
+#
+# Previously: some loops emitted `ralph_question` here. DO NOT do this —
+# ralph_question is classified as a non-push info kind server-side (it is
+# logged for the dashboard but never sent to FCM), and the caller should stop
+# emitting it entirely on oracle-answerable paths to minimize noise.
+#
+# Summary:
+#   user_blocking halt  → push (ralph_halted)
+#   oracle-answerable   → push NOTHING (or at most ralph_question, which is
+#                         server-side demoted to a silent info event)
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PATTERN 5 — Crash-safe terminal notify via trap (PRD §8.6)
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# Problem: a loop killed by an unexpected signal (SIGTERM, SIGKILL, SIGINT),
+# an unhandled error, or a shell `exit` on a non-zero status will terminate
+# WITHOUT ever reaching the explicit halt/completed path — so the user's phone
+# is never notified, leaving them unaware the loop stopped.
+#
+# Solution: register a bash `trap` at the TOP of your loop script that fires a
+# best-effort `loop_halted` push on ANY unexpected exit.  The `|| true` guard
+# ensures the trap itself can never cause a secondary failure.
+#
+# HOW IT WORKS
+# ─────────────
+# 1. Set _LOOP_EXITED=0 at the top of your script (before the main loop).
+# 2. At every NORMAL exit path (completed / halted / stall) flip the flag to 1
+#    BEFORE sending the final push, so the trap knows a push already went out.
+# 3. The trap only fires a push when _LOOP_EXITED == 0 (i.e. the script reached
+#    the EXIT signal without a controlled terminal notification).
+#
+# SIGNALS COVERED
+# ────────────────
+# Bash's EXIT pseudo-signal fires on:
+#   • Normal exit (fall-through past the last line)     ← covered by flag
+#   • `exit N` from any point in the script             ← covered by flag
+#   • SIGTERM (graceful kill, e.g. `kill <pid>`)        ← ✅ caught
+#   • SIGINT  (Ctrl-C / terminal close)                 ← ✅ caught
+#   • Unhandled ERR (set -e + unset command)            ← ✅ caught
+#
+# NOTE: SIGKILL (kill -9) cannot be trapped by any process — that's a kernel
+# hard-kill.  Nothing can be done for SIGKILL; document this for your users.
+#
+# ─── PASTE THIS BLOCK AT THE TOP OF YOUR LOOP SCRIPT ────────────────────────
+
+# 1. Flag: 0 = no terminal push has gone out yet; 1 = push already sent.
+_LOOP_EXITED=0
+
+# 2. Crash-safe trap — fires on EXIT (normal fall-through, `exit N`, SIGTERM,
+#    SIGINT, unhandled ERR).  Sends loop_halted if no controlled push went out.
+_loop_crash_trap() {
+  if [[ "${_LOOP_EXITED:-0}" -eq 0 ]]; then
+    # Unexpected exit — best-effort push, never block.
+    gocode-notify send --kind loop_halted --source ralph \
+      --project "$(basename "$PWD")" \
+      --title "Loop exited unexpectedly — check logs" || true
+  fi
+}
+trap '_loop_crash_trap' EXIT
 
-# --- At loop completion (the loop finished all work cleanly) -----------------
-gocode-notify send --kind loop_completed --source ralph --project "$(basename "$PWD")" || true
+# ─── END OF TOP-OF-SCRIPT BLOCK ──────────────────────────────────────────────
 
-# --- At loop halt (paused_max_failures / awaiting_human / question raised) ---
-gocode-notify send --kind loop_halted --source ralph --project "$(basename "$PWD")" \
+# ─── AT EACH NORMAL TERMINAL EXIT PATH, set the flag THEN send the push ──────
+
+# Example — loop completed cleanly:
+_LOOP_EXITED=1
+gocode-notify send --kind loop_completed --source ralph \
+  --project "$(basename "$PWD")" || true
+
+# Example — loop halted (user_blocking / max-failures):
+_LOOP_EXITED=1
+gocode-notify send --kind ralph_halted --source ralph \
+  --project "$(basename "$PWD")" \
   --title "Ralph halted — needs you" || true
+
+# Example — explicit clean exit (no push needed, but mark so trap is silent):
+_LOOP_EXITED=1
+
+# ─────────────────────────────────────────────────────────────────────────────
+# MINIMAL COPY-PASTE (drop-in for any loop script)
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# Add these 6 lines to the top of your script and the trap handles the rest:
+#
+#   _LOOP_EXITED=0
+#   _loop_crash_trap() {
+#     [[ "${_LOOP_EXITED:-0}" -eq 0 ]] && \
+#       gocode-notify send --kind loop_halted --source ralph \
+#         --project "$(basename "$PWD")" \
+#         --title "Loop exited unexpectedly — check logs" || true
+#   }
+#   trap '_loop_crash_trap' EXIT
+#
+# Then at every terminal exit path, set _LOOP_EXITED=1 before the final push.
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PATTERN 6 — `terminal_halt` helper (PRD §8.7 R12)
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# PROBLEM this solves:
+#   When a loop has many exit paths (task-complete, user_blocking halt,
+#   max-consecutive-failures, stall, explicit stop) each one must:
+#     1. Set _LOOP_EXITED=1       (so the crash trap stays silent)
+#     2. Send the right push kind
+#     3. Break out of the main loop
+#   Duplicating those 3 steps at every exit point is error-prone — it is easy
+#   to add a new `break` or `exit` path and forget the push.
+#
+# SOLUTION — one-call `terminal_halt <kind> <detail>`:
+#   Centralise the 3 steps in a single helper.  Every exit path calls the
+#   helper; the push is guaranteed by construction.
+#
+# TERMINAL KINDS — the three categories an exit can belong to:
+#
+#   ┌──────────────────────┬────────────────────────────────────────────────┐
+#   │ Kind                 │ When to use                                    │
+#   ├──────────────────────┼────────────────────────────────────────────────┤
+#   │ loop_halted          │ Loop stopped; a HUMAN is needed.               │
+#   │   (ralph_halted)     │ • user_blocking question raised                │
+#   │                      │ • max consecutive failures reached             │
+#   │                      │ • explicit operator stop (.homer/STOP file)    │
+#   ├──────────────────────┼────────────────────────────────────────────────┤
+#   │ loop_completed       │ Loop finished all work cleanly — all tasks     │
+#   │   (ralph_completed)  │ checked off or tracker fully satisfied.        │
+#   ├──────────────────────┼────────────────────────────────────────────────┤
+#   │ ralph_waiting        │ Loop cannot proceed right now (offline /       │
+#   │                      │ quota stall) — emit on the EDGE only (first    │
+#   │                      │ stall). Use PATTERN 3's _stall_notified guard  │
+#   │                      │ before calling terminal_halt with this kind.   │
+#   └──────────────────────┴────────────────────────────────────────────────┘
+#
+# SIGNATURE:
+#   terminal_halt <kind> <detail>
+#
+#   <kind>    — one of the terminal kinds above (loop_halted, loop_completed,
+#               ralph_halted, ralph_completed, ralph_waiting, …)
+#   <detail>  — short human-readable description that becomes --title / body text
+#               on the push notification.  Keep it under 80 chars.
+#
+# HOW TO USE — paste the function definition at the top of your loop script
+# (right after the _LOOP_EXITED + trap block), then call `terminal_halt` at
+# every exit point instead of inline _LOOP_EXITED=1 + gocode-notify + break.
+#
+# ─── PASTE THIS FUNCTION DEFINITION AT THE TOP OF YOUR LOOP SCRIPT ───────────
+
+terminal_halt() {
+  # terminal_halt <kind> <detail>
+  # Marks the loop as exiting (silences crash trap), sends the push, then
+  # breaks out of the enclosing loop.  Safe to call from inside `while`/`for`.
+  local _th_kind="${1:-loop_halted}"
+  local _th_detail="${2:-Loop exited}"
+  _LOOP_EXITED=1
+  gocode-notify send --kind "$_th_kind" --source ralph \
+    --project "$(basename "$PWD")" \
+    --title "$_th_detail" || true
+  # `break` exits the innermost loop.  If you call terminal_halt from a nested
+  # function inside the main loop, use `return` + then call `break` in the
+  # caller, or replace this with `exit 0` for a top-level script.
+  break
+}
+
+# ─── END OF FUNCTION DEFINITION ──────────────────────────────────────────────
+
+# ─── USAGE EXAMPLES — replace the inline _LOOP_EXITED=1 + send + break ───────
+
+# Example — loop completed cleanly:
+#   terminal_halt loop_completed "All tasks finished"
+
+# Example — loop halted (user_blocking question):
+#   terminal_halt ralph_halted "User action required — see .homer/questions/"
+
+# Example — loop halted (max consecutive failures):
+#   terminal_halt ralph_halted "Max consecutive failures reached — check logs"
+
+# Example — stall edge (wrap in the _stall_notified guard from PATTERN 3):
+#   if [[ "$_stall_notified" -eq 0 ]]; then
+#     terminal_halt ralph_waiting "Offline / quota stall — retrying when ready"
+#     # NOTE: terminal_halt breaks the loop here.  For a stall you may prefer
+#     # to stay in the loop and retry — in that case emit ralph_waiting inline
+#     # (PATTERN 3) and do NOT call terminal_halt (which would exit the loop).
+#   fi
+
+# ─── COMPLETE BOILERPLATE (combine PATTERN 5 + PATTERN 6) ────────────────────
+#
+# Minimal drop-in for a new loop script — covers crash-safe trap + terminal_halt:
+#
+#   _LOOP_EXITED=0
+#
+#   _loop_crash_trap() {
+#     [[ "${_LOOP_EXITED:-0}" -eq 0 ]] && \
+#       gocode-notify send --kind loop_halted --source ralph \
+#         --project "$(basename "$PWD")" \
+#         --title "Loop exited unexpectedly — check logs" || true
+#   }
+#   trap '_loop_crash_trap' EXIT
+#
+#   terminal_halt() {
+#     local _th_kind="${1:-loop_halted}"
+#     local _th_detail="${2:-Loop exited}"
+#     _LOOP_EXITED=1
+#     gocode-notify send --kind "$_th_kind" --source ralph \
+#       --project "$(basename "$PWD")" \
+#       --title "$_th_detail" || true
+#     break
+#   }
+#
+#   # Main loop
+#   while true; do
+#     # ... your loop body ...
+#
+#     if all_tasks_done; then
+#       terminal_halt loop_completed "All tasks finished"
+#     fi
+#     if user_blocking_halt; then
+#       terminal_halt ralph_halted "User action required"
+#     fi
+#     if max_failures_exceeded; then
+#       terminal_halt ralph_halted "Max consecutive failures reached"
+#     fi
+#   done
+#
+# Any path that exits without calling terminal_halt is caught by the trap.
+# Any path that calls terminal_halt gets exactly one push, then breaks cleanly.