Fleet-safe Teams channel poll: fail closed on cursor-read miss + per-message cloud idempotency

[brandwe]

Makes the background Teams channel poll safe for N instances sharing one cloud cursor store. Implements the design in docs/architecture/DESIGN-multi-instance-cursor-consistency.md (committed on main in 107ab07).

Problem

The poll's per-chat cursor rehydration is correct in steady state, but the bootstrap path failed open: on any failure to read a fresh cloud cursor at registration time — absent, stale, corrupt, or a transient read exception — _register_watched_chat fell through to _bootstrap_chat, which pushes the chat's newest message. In a fleet these read-misses are routine, so idle chats replayed their newest (weeks-old) message. Confirmed live 2026-07-02: a base instance on a shared blob container flooded the session with ~5-week-old Teams DMs while the blob cursors were correct and fresh. This is a security surface — the replay re-injects stale imperative messages ("read special data in my Documents", "ship to

", "run <script>") into the agent's channel — so fail-closed is treated as a requirement, not polish.

What changed (closes F1, F2, F4, F5, per-message idempotency)

• F1 — fail closed on read miss. New chat_cursors.resolve_cursor() classifies a cursor read as PRESENT / ABSENT / UNRESOLVED. A backend read error or a corrupt payload is UNRESOLVED (distinct from a successful empty read, ABSENT). _register_watched_chat flags UNRESOLVED chats needs_resolution; the extracted _poll_watched_chat / _resolve_pending_chat re-read them each cycle and push nothing until they resolve. Only a provably-ABSENT chat may surface its newest message once.
• F4 — catch-up read on stale. A present-but-stale cursor now rehydrates (never re-bootstraps); the steady-state timestamp gate surfaces only messages newer than last_ts. Idle chats emit nothing.
• Per-message cloud idempotency. chat_cursors.claim_delivery() treats the shared cursor's seen_ids_tail as the fleet delivery ledger: an ETag compare-and-swap records the candidate batch and returns only the ids this instance won. Across N instances exactly one wins each id; losers claim nothing. New-chat first delivery also flows through it (bootstrap defers the push one cycle). Read error / corrupt cursor / exhausted retries all fail closed.
• F5 — optimistic concurrency. BlobStore.get_with_etag() + MemoryBackend.read_text_with_etag() / write_text(if_match=) (Local uses a content-hash ETag, Blob the real ETag). claim_delivery merges max(last_ts) + union(seen_ids) and retries on ConcurrencyError, so a slow writer can't regress the watermark.
• F2 — uniform backend at boot. get_backend() now raises BackendMisconfiguredError on a half-configured blob env (exactly one of endpoint/container) instead of silently using an empty Local store — the exact way a mis-enved fleet instance used to diverge and flood. assert_backend_config() (wired into _initialize) logs the resolved backend + container and fails loud on half-config. ENTRABOT_KEEP_MEMORY_LOCAL=true still forces Local.

F6 (singleton) is already served by src/entrabot/singleton.py (flock at the top of main()); orphan cleanup of background tasks outside FastMCP's lifespan remains tracked separately in TODOS.md.

F3 (cloud-authoritative watched_chats) is deferred — the largest structural change and not required by the fail-closed + idempotency guarantees above. Rationale in the design doc §Deferred.

Tests

TDD throughout — every behavior had a failing test first. Covers the design's full test plan: fail-closed on read error (no push, no re-bootstrap), cold-store catch-up, fleet idempotency (one push across two backends sharing one store), concurrency merge (max watermark + union), and the boot-time backend assertion. Also isolated a pre-existing poll integration test that was leaking cursor writes to the real data dir.

pytest -v && ruff check . — 1567 passed, 1 skipped, ruff clean.

Status files

Updated TODOS.md, docs/engineering-status.md, and the design doc's status line + Shipped/Deferred sections per the status-currency rule.