feat: add Hermes local Discord communication bridge

[dnth]

Intent

Fix firstmate PR #116 (the Hermes Communication Officer local Discord bridge, FM-3)
per the scout review at data/review-fm116-hermes-bridge/report.md, and ship it as a
properly validated PR, superseding the original #116 which bypassed validation.

The PR #116 work is the base of this branch, unmodified, with the fixes on top. The
review found the core-infra edits (bootstrap, watcher, supervision) CLEAN and
correctly gated; those are kept, and a home that never opts in must remain
unaffected.

BLOCKERS to fix:

1. Unrecoverable reply wedge. An ambiguous mid-chunk send failure (URLError,
   TimeoutError, OSError, HTTP 408, unparseable 200) leaves progress.inflight set
   forever; fm_ext_outbox_begin returns 3 before the dead-owner/TTL-steal logic, so
   restart, wait, and release never recover. A wedged reply must eventually be
   retried, failed, or surfaced.
2. Poller O(n) and unbounded state growth. fm-ext-outbox.sh pending rescans every
   reply ever sent (25 delivered -> 2.5s, 300 -> 26s against a 2s poll), and
   state/ext-context/*.json plus *.offered.json are never removed. pending must be
   bounded/incremental, and retention must mirror X mode's 7-day cap
   (FMX_FOLLOWUP_MAX_AGE_SECS).

AUTH POSTURE (captain decision, least-privilege and fail-closed):

• No standing guild-wide default authority. Standing captain-level authority
  requires an explicit finest-grained guild:channel:author allowlist rule; a
  guild-only or channel-only rule must not grant it.
• The two allowlist implementations must AGREE: bin/fm-ext-lib.sh fm_ext_allowlisted
  and contrib/hermes-gateway-firstmate-comms/intake.py allowlisted disagreed across
  rule shapes. Unify them to one source of truth or a shared contract and prove
  agreement by test across all rule shapes.
• Keep the allowlist fail-closed: empty, comments-only, symlinked, and missing
  allowlist all deny.

MAJORS to fix:

• Config-file opt-in and environment opt-in disagree, and the gateway plugin forces
  the environment variable on. Make opt-in consistent.
• The poll claims offers before the wake is durable, so a watcher failure can
  silently drop requests. Make the wake durable before claiming.

Acceptance criteria:

• AC1: The reply wedge is recoverable, with a colocated test proving an ambiguous
  mid-chunk send failure is eventually retried, failed, or surfaced, not stuck.
• AC2: fm-ext-outbox.sh pending is bounded/incremental (no O(n) rescan of all
  replies; a measurement shows it stays roughly flat as delivered-reply count
  grows), and ext-context state has a bounded retention policy like X mode's 7-day
  cap.
• AC3: The shell and Python allowlist implementations agree across all rule shapes,
  with a test comparing them over G, G:C, G:C:A, G:C:, G:, G:C:A:extra and case
  variants, asserting identical decisions.
• AC4: Auth is least-privilege and fail-closed: standing captain-level authority
  requires an explicit guild:channel:author rule (no guild-wide default), and
  empty, comments-only, symlinked, and missing allowlist deny; tests cover each.
• AC5: Secret-gate tests cover mismatched, mode-0644, symlinked, empty, and missing
  secret, not just the happy path.
• AC6: Config-file versus environment opt-in are consistent, and the poll makes the
  wake durable before claiming (no silent request drop on watcher failure), each
  with a test.
• AC7: The reviewed-clean core-infra gating is preserved (a home that never opts in
  is bit-for-bit unaffected), and all changes ship through no-mistakes as one PR
  held for captain merge.

Constraints:

• This edits firstmate's shared tracked material: follow the firstmate coding
  guidelines, and keep bin scripts shellcheck-clean via bin/fm-lint.sh.
• The contrib gateway plugin and docs are in scope for the auth, retention, and
  opt-in fixes.
• Delivery is no-mistakes with yolo off: the PR is held for captain merge and must
  not be merged by the pipeline or by me.
• Firstmate has since confirmed this is high-risk core-infra and directed the FULL
  No-Mistakes validation to a green PR.

Deliberately out of scope, to be raised as separate follow-ups rather than fixed
here: extracting the shared private-artifact primitive that bin/fm-x-lib.sh and
bin/fm-ext-lib.sh duplicate, per-author intake rate limiting, reclassifying Discord
401/403 as transient, and gateway plugin logging.

Firstmate-Validation-Generation: 16ec786216d21dbdc1d62cd77d48c31f

What Changed

• Added the local Hermes Communication Officer Discord bridge, including intake, durable wake polling, outbox delivery, reply splitting/recovery, and the dedicated gateway plugin.
• Unified fail-closed bridge activation, secret validation, and allowlist handling, with explicit authority rules and bounded ext-context/outbox retention.
• Updated bootstrap, watcher, supervision, configuration, architecture docs, and added comprehensive fm-ext bridge coverage.

Risk Assessment

⚠️ Medium: The reviewed bridge, recovery, retention, authorization, and opt-in paths appear to satisfy the stated source-level requirements, but the change is substantial core-infrastructure code with concurrency and lifecycle complexity.

Testing

Ran the focused end-to-end Hermes bridge suite twice; all bridge, recovery, retention, auth, opt-in, durable-wake, and non-opt-in no-op checks passed. Full transcript captured as evidence; worktree remained clean.

Evidence: Hermes bridge targeted test transcript

ok - 1 allowlisted intake writes inbox; non-/fm does not
ok - 2 correlation persists across a new shell
ok - 3 immediate ack without waiting for Firstmate work
ok - 4 delayed follow-up after link when inbox is gone
ok - 5 multiple follow-ups; duplicate generation is a no-op
ok - 6 idempotent intake and emit
ok - 7 Hermes restart: unsent outbox delivers once, receipt sticks
ok - 8 Firstmate restart: inbox+offer persist; one wake per offer
ok - 9 mid-send refuse and CAS receipt
ok - 10 unauthorized and missing allowlist write no inbox
ok - 12 hermes refused as secondmate
ok - 13 transient 5xx/429 clears posting marker and allows retry
ok - 14 mid-delivery still refuses automatic plugin repost
ok - 15 wake failure does not leave a permanently silent offered marker
ok - 16 ambiguous timeout/URLError recovers after the window
ok - 17 permanent 4xx is terminal failed, not endless retry
ok - 18 text under the Discord budget is one post
ok - 19 over-limit text posts ordered chunks without FMX_PAIRING_TOKEN
ok - 20 later-chunk transient failure resumes without reposting earlier chunks
ok - 20 state override preserves resume progress
ok - 21 concurrent resume claims: only one poster sends the next chunk
ok - 22 pre-send failures release inflight; abort drops inflight first
ok - 23 stale inflight steal requires dead pid and TTL; live concurrent and TTL=0 steal-vs-steal still one winner
ok - bootstrap arms the ext-watch identity shim
ok - poll is a hard no-op when the bridge is off
ok - gateway /fm handler performs no terminal dispatch
ok - 24 a wedged ambiguous mid-chunk send is recovered and delivered
ok - 25 an unrecoverable wedge is failed and surfaced, never silent
ok - 26 pre-send crash without progress recovers and delivers once
pending steady-state: 5 delivered=109ms, 60 delivered=139ms
ok - 26 pending stays flat as delivered replies accumulate
ok - 27 bridge records expire on the documented retention window
shape guild -> allow
shape guild-channel -> allow
shape guild-channel-author -> allow
shape wrong-author -> deny
shape trailing-author-colon -> deny
shape trailing-channel-colon -> deny
shape four-components -> deny
shape one-character-off -> deny
shape mixed-case-upper -> deny
shape mixed-case-lower -> deny
shape padded -> allow
shape commented -> deny
ok - 28 shell and plugin reach one identical allowlist decision on every rule shape
ok - 29 standing authority needs an author-scoped rule; broad and broken allowlists deny
ok - 30 the secret gate is closed on mismatched, wrong-mode, symlinked, empty and missing secrets
ok - 31 config/ext-bridge is the only way to activate; the environment can only disable
ok - 32 the poll releases its claim when the wake cannot be made durable
ok - 33 a home that never opts in gains no bridge state
all fm-ext-bridge tests passed

- Outcome: 🔧 3 issues found → auto-fixed ✅ across 2 runs (12m0s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 2 issues found → auto-fixed (6) ✅

• ⚠️ tests/fm-ext-bridge.test.sh:1306 - This regression test only greps Python source for dispatch_tool(, which is source-content-only evidence and cannot prove runtime behavior. Replace it with an executable plugin invocation that asserts no terminal dispatch occurs.
• 🚨 tests/fm-ext-bridge.test.sh:1583 - The required AC3 says the shell/Python comparison must cover case variants, but this test explicitly substitutes a numeric one-character mismatch because Discord IDs are numeric and never exercises case variants. Please confirm whether that acceptance requirement is intentionally waived or add a behavioral probe that covers it.

🔧 Fix: Replace source grep and add case-variant behavioral probes
2 errors still open:

• 🚨 bin/fm-ext-lib.sh:840 - fm_ext_outbox_stuck_recover releases the inflight claim before updating progress (lines 840-845). Another poster can claim and send the same chunk between those operations, then this process overwrites the newer progress with inflight=null, allowing duplicate Discord posts or lost progress. Update progress while the claim is still held, then release it, or otherwise serialize the recovery transition.
• 🚨 bin/fm-ext-outbox.sh:143 - AC2 requires pending to avoid an O(n) rescan of all replies as delivered count grows, but pending still iterates "$OUTBOX"/*.json on every call (lines 143-166). Every delivered generation leaves receipt/progress/failed marker files in that same directory, so the loop remains linear in historical replies; it only avoids jq work for marker names. Meeting the stated criterion requires an explicit bounded pending index or moving terminal markers outside the scanned namespace, which extends the state layout and needs authorization.

🔧 Fix: Serialize recovery progress update before inflight release
2 errors still open:

• 🚨 bin/fm-ext-lib.sh:778 - A crash can leave a valid posting/inflight claim before the poster writes its first progress artifact (the claim is created in fm_ext_outbox_begin, then write_progress runs later). On restart, fm_ext_outbox_stuck_age requires that progress file and returns failure when it is absent, so fm_ext_outbox_stuck_recover never clears or fails the claim and fm_ext_outbox_begin keeps returning mid-delivery forever. Recovery must handle a stale inflight claim with no progress (for example by safely reopening/releasing it) so this pre-send crash window is recoverable.
• 🚨 bin/fm-ext-lib.sh:1227 - The implementation explicitly skips pruning context and .offered.json records whenever the inbox file still exists (if [ -e "$inbox/$slug.json" ]; then continue). An unhandled/abandoned request can therefore retain state/ext-context indefinitely, contradicting the required AC2: “state/ext-context/*.json plus *.offered.json ... [must have] a bounded retention policy like X mode's 7-day cap.” Please confirm this exemption is intentional or authorize an expiry/recovery policy for abandoned inbox entries.

🔧 Fix: Recover pre-send wedges without progress artifacts
1 warning still open:

• ⚠️ bin/fm-ext-lib.sh:1255 - The retention exemption treats any existing state/ext-inbox/<slug>.json path as live work using only -e. A malformed or symlinked inbox file is not processable by the poller, yet it prevents pruning the corresponding ext-context and .offered.json records indefinitely, violating AC2's seven-day bound. Require fm_ext_private_artifact_file_valid "$inbox" "$slug.json" 600 before applying the live-inbox exemption.

🔧 Fix: Validate inbox artifacts before retaining bridge context
2 issues (1 error, 1 warning) still open:

• 🚨 contrib/hermes-gateway-firstmate-comms/outbox_poster.py:288 - progress_path hardcodes home/state/ext-outbox, while every shell outbox command honors FM_STATE_OVERRIDE. With a state override, begin claims/resumes the progress file in the overridden directory, but load_progress reads the default directory, treats the delivery as new, resets posted_count to zero, and can repost already-delivered chunks. Derive this path from the same state override used by the CLI before writing or reading progress.
• ⚠️ tests/fm-ext-bridge.test.sh:378 - These newly added assertions inspect fm-spawn.sh source text for particular strings instead of executing the public spawn interface; matching text can be dead, commented, or behaviorally unused. Replace them with behavioral probes (or remove them) so the test proves Hermes launch/TUI and crew-only secondmate behavior through observable results.

🔧 Fix: Honor state overrides and remove source-only spawn assertions
1 error still open:

• 🚨 bin/fm-ext-lib.sh:823 - fm_ext_outbox_stuck_recover recovers any in-flight progress solely by age and never checks whether the inflight marker's recorded owner PID is still alive. If the original poster is legitimately blocked longer than FM_EXT_MIDDELIVERY_RECOVERY_SECS, a second poster clears the chunk, releases the claim, and re-sends it concurrently, allowing duplicate Discord messages. This contradicts the function's stated invariant that a genuinely live send is never recovered; require a live-owner check (or equivalent stale-owner predicate) before clearing an in-flight chunk.

🔧 Fix: Recover only inactive in-flight deliveries using heartbeats
✅ Re-checked - no issues remain.

🔧 **Test** - 3 issues found → auto-fixed ✅

• 🚨 tests/fm-ext-bridge.test.sh:260 - tests/fm-ext-bridge.test.sh test_7_unsent_outbox_receipt_once uses $state without declaring or assigning it at line 260, so the targeted suite aborts before completing. Define the intended destination (or remove the stale copy) before running the suite.
• 🚨 tests/fm-ext-bridge.test.sh:554 - test_16_ambiguous_urlerror_keeps_mid_delivery still asserts that an ambiguous wedge must refuse every later retry (lines 554-600). This contradicts the authoritative AC1 behavior and the passing test_24 recovery proof; update or replace the stale expectation so the suite validates eventual retry/failure/surfacing.
• 🚨 tests/fm-ext-bridge.test.sh:1498 - test_26_presend_crash_without_progress_recovers and test_26_pending_stays_flat_as_delivered_grows both use $TMP_ROOT/c26 (lines 1498 and 1575). Running them together leaves state from the first test and makes the pending test report zero pending items; give the tests distinct home directories or cleanly isolate fixtures.
• bash tests/fm-ext-bridge.test.sh (fails at line 260 due to unbound state; when bypassed, reaches the stale test_16 expectation)
• Focused bridge functions test_24, test_25, test_26_presend_crash_without_progress_recovers, test_26_pending_stays_flat_as_delivered_grows, and test_27 through test_33 via an isolated harness
• Existing tests 1 through 15, 17 through 23, and state-override test executed before the suite failures

🔧 Fix: Fixed bridge test harness defects; targeted suite passes
✅ Re-checked - no issues remain.

• bash tests/fm-ext-bridge.test.sh

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.