Implement one credential-gated read-only MailPlus/IMAP sync loop

[jmcte]

Objective

Deliver the first real product vertical slice: one configured MailPlus account can perform a safe, read-only metadata sync into the local SQLite index through the existing contracts.

Prerequisites

Do not merge until the transactional/checkpoint work and relevant CI/privacy blockers from #98 are complete. Interface design and synthetic integration tests may begin earlier.

Relevant code

• src/mailplus_intelligence/live_adapter.py
• src/mailplus_intelligence/sync.py
• src/mailplus_intelligence/scheduler.py
• src/mailplus_intelligence/cli.py
• src/mailplus_intelligence/doctor.py
• docs/integration/live-mailplus-adapter.md
• docs/raw-fetch-interface.md
• docs/mailplus-locator-export-contract.md

Scope

• Select and document the supported first transport, expected to be read-only IMAP unless MailPlus API evidence supports a safer/better contract.
• Implement TLS verification, connection/authentication, mailbox selection, pagination, and metadata/header retrieval.
• Never fetch body or attachment payloads during metadata sync.
• Use mailbox-scoped cursor semantics such as account + mailbox + UIDVALIDITY + UID/MODSEQ where available.
• Detect cursor invalidation, mailbox reset, moved/missing locators, and authentication failures with typed errors.
• Add mpi sync run with explicit source/account selection, dry-run, bounded batch/page controls, and inspectable summary.
• Replace scheduler flags with atomic leases: unique token, heartbeat/renewal, configurable expiry, token-checked release.
• Extend doctor to perform optional reachability/auth/capability checks without printing secrets.
• Provide a safe Synology/cron/launchd scheduling recipe.

Non-goals

• No mailbox mutation, delete, move, flag change, or send.
• No raw body or attachment download.
• No multi-account support.
• No live CI credentials or mandatory live tests.
• No automatic retry of credential-gated failures as generic network failures.

Acceptance criteria

• Fixture/fake server integration covers pagination, resume, UIDVALIDITY change, authentication failure, timeout, and malformed metadata.
• Metadata sync cannot request body/attachment payloads.
• Cursor and source identity are stable and inspectable.
• mpi sync run --dry-run performs no database/checkpoint mutation.
• Apply mode is replay-safe and uses the atomic checkpoint contract.
• Overlapping runs cannot both acquire the same lease.
• Doctor reports configured/reachable/authenticated/sync-capable separately.
• Logs exclude credentials, full headers, recipient dumps, bodies, and prompt payloads.
• Live-only test instructions require explicit operator approval and are excluded from normal CI.

Validation

Required automated coverage:

• fake IMAP/MailPlus server contract tests
• atomic lease concurrency test
• full first-sync and resume test
• cursor invalidation/recovery test
• credentials/redaction log test
• fixture-mode fast and extended suites

Exact dependencies

Implementation is blocked on #100, #104, and #105. Coordinate ingest/thread/locator interfaces with #107. Fake-server interface tests may begin before all blockers close.

Parent

Part of #98.