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.

2 files changed, 84 insertions, 16 deletions

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"* ]]
 }
diff --git a/scripts/tests/signal-receive.bats b/scripts/tests/signal-receive.bats
new file mode 100644
index 0000000..8fe4d67
--- /dev/null
+++ b/scripts/tests/signal-receive.bats
@@ -0,0 +1,66 @@
+#!/usr/bin/env bats
+# signal-receive.sh — drains the Signal pager account's inbound queue to keep it
+# warm (the roam-sync-shaped fix for receive-staleness) and to surface Craig's
+# replies. Run on velox by the signal-receive systemd timer. These tests stub
+# signal-cli on PATH to verify command construction without a network or the
+# real account.
+
+setup() {
+    REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../.." && pwd)"
+    RECV="$REPO_ROOT/scripts/signal-receive.sh"
+    STUBS="$(mktemp -d)"
+    LOG="$STUBS/calls.log"
+    # HAS_ACCOUNT (default 1) controls the listAccounts answer so the local-account
+    # guard can be exercised: "1" lists both test accounts as present, "0" lists
+    # none (so the guard no-ops).
+    cat > "$STUBS/signal-cli" <<EOF
+#!/bin/bash
+if [ "\$1" = "listAccounts" ]; then
+  if [ "\${HAS_ACCOUNT:-1}" = "1" ]; then
+    echo "Number: +15045173983"
+    echo "Number: +19995550000"
+  fi
+  exit 0
+fi
+echo "signal-cli \$*" >> "$LOG"
+exit 0
+EOF
+    chmod +x "$STUBS/signal-cli"
+}
+
+teardown() {
+    rm -rf "$STUBS"
+}
+
+@test "defaults to the pager account, a 10s timeout, and read receipts" {
+    PATH="$STUBS:$PATH" run bash "$RECV"
+    [ "$status" -eq 0 ]
+    grep -q -- "-a +15045173983 receive --timeout 10 --send-read-receipts" "$LOG"
+}
+
+@test "honors an explicit account and timeout" {
+    PATH="$STUBS:$PATH" run bash "$RECV" +19995550000 25
+    [ "$status" -eq 0 ]
+    grep -q -- "-a +19995550000 receive --timeout 25" "$LOG"
+}
+
+@test "no-ops (exit 0) when the account is not registered on this machine" {
+    # Guards the runbook claim that the timer no-ops on a common-package machine
+    # that stows the units but holds no pager account.
+    HAS_ACCOUNT=0 PATH="$STUBS:$PATH" run bash "$RECV"
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"not registered"* ]]
+    # The receive must not have run.
+    ! grep -q "receive" "$LOG"
+}
+
+@test "no-ops (exit 0) when signal-cli is not on PATH" {
+    # Empty stub dir with no signal-cli; echo/exit/command are bash builtins, so
+    # the script still runs and hits its signal-cli-absent branch, which no-ops.
+    rm -f "$STUBS/signal-cli"
+    # Invoke bash by absolute path so `run` finds it regardless of the empty
+    # PATH the script itself sees.
+    PATH="$STUBS" run "$(command -v bash)" "$RECV"
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"signal-cli"* ]]
+}