feat: reliable echo via final-id resolution + supervise beepertexts

[hamr0]

Two asks from multis (beeperbox's first consumer). Ask B(1) — the stale-Xvfb-lock restart fix — already shipped in #12; this PR is Ask A + Ask B(2).

Ask A — reliable echo via id resolution (mcp/server.js)

Problem: a send returns a pendingMessageID, but Beeper swaps it for the real bridge id on ack. The echo-guard recorded the pending id and matched read-backs by exact id → always missed → every match degraded to the fragile 15-minute text fallback.

Fix (grounded in Beeper's docs): send_message / note_to_self now resolve the pending id to the final bridge id — GET .../messages/{pendingMessageID} retried until the id swaps (bounded, best-effort, never throws) — and record both ids in the ledger. A read-back then matches by exact id whether or not the swap happened. The content fallback survives only as a last-ditch net and only for sends whose final id couldn't be resolved; once a send is resolved, its text fallback is retired.

Acceptance criteria (all covered by unit tests):

• ✅ exact-id tagging via the resolved bridge id
• ✅ two identical-text sends both caught (each by its own id)
• ✅ a human re-typing identical text after a resolved send is not mis-tagged (stays external)
• → lets multis drop its _isLooping backstop

Additive return fields on both send tools: pending_message_id, resolved. message_id is the final bridge id when resolved: true, else the pending id. No field removed. Tunable via BEEPERBOX_RESOLVE_RETRIES (default 4) / BEEPERBOX_RESOLVE_DELAY_MS (default 250); set retries 0 to disable.

Ask B(2) — supervise beepertexts (entrypoint.sh)

Problem: beepertexts ran unattended. When its API process crashed while the Electron launcher lingered, the container looked "up" and the MCP layer kept answering, but every tool call returned -32603 fetch failed because :23373 was gone — half-dead, never self-heals.

Fix: the entrypoint now supervises — relaunch if the process dies, recycle if the API stays down after having been up (watches both the PID and :23373/v1/spec). An API_WAS_UP gate protects first-run login: until the user enables the API it's down by design, so the loop never recycles before the API has come up once. Clean docker stop shutdown preserved. Reversible/tunable: BEEPERBOX_SUPERVISE (default 1, 0 = old behavior), BEEPERBOX_SUPERVISE_INTERVAL (10s), BEEPERBOX_SUPERVISE_API_GRACE (6 ≈ 60s).

Verification — AGENT_RULES (POC + test-must-fail)

• Unit suite: 26 pass (was 21). New: read-back tagged by resolved id; the human-retype acceptance test; two-identical-sends; unresolved-entry safety net; addResolvedId persist/reload round-trip. The existing 21 pass unchanged → legacy sent_id back-compat holds.
• POC spikes (not committed) proved the load-bearing claims and that the tests can fail: the prior matcher mis-tags the human re-type; an ungated supervisor would recycle pre-login.

Honest limitations (unverified in CI — no live Beeper account)

• The pendingMessageID → final id resolution depends on Beeper's live ack behavior. multis proved it against a real account (id 908); it is not exercised in CI. Validate against your own account before relying on it for a high-stakes auto-responder.
• The supervisor's kill/relaunch integration needs a live container — only its decision logic is POC-covered here.
• Resolution adds up to ~750ms (default) to a send while it waits for the ack; tune down or disable if latency-sensitive.

Docs

CHANGELOG (Ask A + supervision under [Unreleased]), beeperbox.context.md (send returns + rewritten echo-guard caveat), docs/GUIDE.md (send-return row + self-heal troubleshooting note), docs/PRD.md (supervised-backend operational property).

🤖 Generated with Claude Code