From 302b062680c8fbd9743d4e083154ac5fc314955a Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Mon, 20 Jul 2026 16:03:08 -0500
Subject: feat(pager): document the Signal pager and add the receive timer

The pager worked but was undocumented and drifting stale: signal-cli warned the account had gone 47 days without a receive, and no runbook existed to hand a future session or a non-Claude runtime.

I added the runbook under docs/design/ and a roam-sync-shaped receive timer that drains the queue every 15 minutes, keeping the account warm and surfacing reply messages. I also generalized agent-page: it now sends directly from any machine holding the pager account and relays to velox only when it doesn't. ratio is linked as a device of the account, so a page lands even when velox is down.

The receive script no-ops cleanly where the account isn't registered, since the units stow onto every machine via the shared common package.
---
 scripts/tests/agent-page.bats | 34 ++++++++++++++++++----------------
 1 file changed, 18 insertions(+), 16 deletions(-)

(limited to 'scripts/tests/agent-page.bats')

diff --git a/scripts/tests/agent-page.bats b/scripts/tests/agent-page.bats
index 071e4b9..7317ac7 100644
--- a/scripts/tests/agent-page.bats
+++ b/scripts/tests/agent-page.bats
@@ -1,9 +1,11 @@
 #!/usr/bin/env bats
 # agent-page — the runtime-neutral phone pager. Pages Craig over Signal from
-# any machine on the tailnet: runs signal-cli directly on velox (where the
-# pager identity lives), ssh-relays to velox from everywhere else. These tests
-# stub ssh/uname/signal-cli on PATH to verify command construction without a
-# network or a phone.
+# any machine on the tailnet: sends directly wherever the pager account is
+# registered locally (velox, or any linked device), and ssh-relays to velox
+# from a machine that doesn't hold the account. These tests stub
+# ssh/signal-cli on PATH to verify command construction without a network or
+# a phone. The signal-cli stub answers `listAccounts` to control which branch
+# the dispatch takes.
 
 setup() {
     REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../.." && pwd)"
@@ -15,8 +17,14 @@ setup() {
 echo "ssh \$*" >> "$LOG"
 exit 0
 EOF
+    # HAS_ACCOUNT controls the listAccounts answer: "1" → the pager account is
+    # local (send direct), unset/"0" → not local (relay).
     cat > "$STUBS/signal-cli" <<EOF
 #!/bin/bash
+if [ "\$1" = "listAccounts" ]; then
+  [ "\${HAS_ACCOUNT:-0}" = "1" ] && echo "Number: +15045173983"
+  exit 0
+fi
 echo "signal-cli \$*" >> "$LOG"
 exit 0
 EOF
@@ -33,8 +41,8 @@ teardown() {
     [[ "$output" == *"usage"* ]]
 }
 
-@test "relays through ssh to velox with the pager account and Craig's UUID" {
-    PATH="$STUBS:$PATH" run bash "$PAGE" build finished
+@test "relays through ssh to velox when the account is not local" {
+    HAS_ACCOUNT=0 PATH="$STUBS:$PATH" run bash "$PAGE" build finished
     [ "$status" -eq 0 ]
     grep -q "^ssh .*velox" "$LOG"
     grep -q "15045173983" "$LOG"
@@ -43,16 +51,10 @@ teardown() {
     grep -qF 'build\ finished' "$LOG"
 }
 
-@test "on velox itself, calls signal-cli directly (no ssh)" {
-    cat > "$STUBS/uname" <<'EOF'
-#!/bin/bash
-[ "$1" = "-n" ] && { echo velox; exit 0; }
-exec /usr/bin/uname "$@"
-EOF
-    chmod +x "$STUBS/uname"
-    PATH="$STUBS:$PATH" run bash "$PAGE" hello
+@test "sends directly (no ssh) when the pager account is registered locally" {
+    HAS_ACCOUNT=1 PATH="$STUBS:$PATH" run bash "$PAGE" hello
     [ "$status" -eq 0 ]
-    grep -q "^signal-cli " "$LOG"
+    grep -q "^signal-cli -a +15045173983 send " "$LOG"
     ! grep -q "^ssh " "$LOG"
 }
 
@@ -62,7 +64,7 @@ EOF
 exit 255
 EOF
     chmod +x "$STUBS/ssh"
-    PATH="$STUBS:$PATH" run bash "$PAGE" urgent thing
+    HAS_ACCOUNT=0 PATH="$STUBS:$PATH" run bash "$PAGE" urgent thing
     [ "$status" -ne 0 ]
     [[ "$output" == *"notify"* ]]
 }
-- 
cgit v1.2.3