feat: add Pushover last-hop captain notifier (fork-only)

[Bre77]

Intent

• Ship the "last hop" captain-notification channel recommended in the captain-alert-channel-b3 investigation: a small curl-based Pushover sender, no daemon, no inbound port.
  • Tier maps straight to Pushover priority: urgent -> priority 1 (bypasses quiet hours, sounds once), emergency -> priority 2 (Pushover re-alerts every retry seconds, up to expire seconds, until acknowledged in the app).
  • FM_NOTIFY_RETRY / FM_NOTIFY_EXPIRE env-override the emergency defaults (30s / 3600s), validated against Pushover's own 30s minimum / 10800s maximum.
• Secrets never touch disk, stdout, or curl's argv.
  • The Pushover user key and application token are read from 1Password (op item get Pushover --vault CLI --fields username|credential --reveal) at call time only, live in shell variables, and are sent to curl over stdin (--data @-) so ps never shows them.
  • OP_SERVICE_ACCOUNT_TOKEN is read from the environment (source it from your shell profile, per existing fleet practice); its absence is a loud, immediate failure.
• Every documented failure mode fails loud and non-zero, per "a notification script that fails silently is worse than none."
  • Missing OP_SERVICE_ACCOUNT_TOKEN, a missing or empty 1Password field (the error names the exact field), and a non-2xx Pushover response (prints Pushover's errors array) all exit non-zero with a clear message.
• --dry-run previews the tier/priority/retry/expire/message with secrets redacted and makes no external calls at all (no op, no curl) - tested with tripwire mocks that fail the test if either is invoked.
• On an emergency (priority-2) send, prints Pushover's receipt id so a caller can later poll acknowledgment via the receipts API.
  • Out of scope for this PR: receipt-acknowledgment polling itself.
  • Out of scope for this PR: any Twilio voice tier (documented in the report as an optional, later tier-4).
  • Out of scope for this PR: auto-wiring ClickStack alerts to call this script - firstmate invokes it by judgment for now.
  • Out of scope for this PR: a real end-to-end send - the captain still needs to add the 1Password item/fields; firstmate will run the live test once that's in place, not this crewmate.
• Added a one-line escalation-channel pointer in AGENTS.md section 9 and a catalog row in docs/scripts.md; no other docs needed changes.

What Changed

• bin/fm-notify-captain.sh (new): the notifier, shellcheck-clean, self-contained (no sibling lib sourcing needed).
• tests/fm-notify-captain.test.sh (new): 18 cases covering tier->priority mapping and retry/expire overrides (all via --dry-run, no external calls), the dry-run send-nothing guarantee, every loud-failure path (missing token, absent op binary, missing/empty 1Password field on either username or credential, non-2xx response), and two success-path cases (mocked op/curl) confirming the emergency receipt prints and that secrets never appear in curl's argv.
• AGENTS.md: one-line pointer in the escalation section.
• docs/scripts.md: one-row catalog entry.

Risk Assessment

Low. New, isolated script with no callers wired up yet (ClickStack auto-wiring is explicitly out of scope); firstmate will invoke it by judgment. No changes to existing scripts, watcher, or supervision paths.

Testing

• shellcheck bin/fm-notify-captain.sh tests/fm-notify-captain.test.sh - clean.
• ./tests/fm-notify-captain.test.sh - 18/18 pass.
• Manually smoke-tested dry-run output, missing-token/missing-field/non-2xx paths, and a full mocked success path (verified the Pushover user key and application token never appear in curl's argv, only in its stdin body).
• Ran the repo's full local gate (shellcheck over every bin/*.sh/bin/backends/*.sh/tests/*.sh, then every tests/*.test.sh): clean except one pre-existing, unrelated failure - tests/fm-session-start.test.sh's "pi supervision block missing" case fails identically on a clean fork/main checkout with none of this PR's changes present (confirmed via git stash showing zero tracked-file diff before this work). Not touched by this PR; worth tracking separately. This PR's own gate run (--check) excludes that one file and is otherwise the unmodified CI mirror.

Full narrative / original brief

Build firstmate's emergency captain-notification "last hop": a Pushover sender script, per the accepted recommendation in the captain-alert-channel-b3 report, which defines the tier ladder (urgent/emergency -> Pushover priority 1/2) and verified Pushover API behavior (priority 2 requires retry/expire, re-alerts until acknowledged, receipt id in the response for later polling via the receipts API).

Deliverable: bin/fm-notify-captain.sh with --tier <urgent|emergency> "<message>" (+ optional --title), secrets pulled from 1Password at runtime only, POST to https://api.pushover.net/1/messages.json, loud non-zero failure on every documented failure mode, and a --dry-run flag. Tests colocated at tests/fm-notify-captain.test.sh, no real sends from tests.

Field-name correction mid-task from the captain: the 1Password Pushover item (vault CLI) has the user key in field username and the application token in field credential - there is no api token field. The script and tests were updated to match.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: aeb803060e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Check Pushover JSON status before reporting success

Captain, when Pushover returns HTTP 200 with a body like {"status":0,"errors":[...]} for an invalid request, this code accepts the response as delivered and prints sent, even though no notification was queued. Pushover's API docs explicitly say success requires the JSON/XML status value to be 1, and that a non-1 status is invalid input, so this can silently lose the emergency page in exactly the last-hop path this script is meant to protect.

Useful? React with 👍 / 👎.