fix(matrix): supervise sync consumer lifecycle

[jerryhjones]

What does this PR do?

Matrix currently owns _sync_task as fire-and-forget state. Initial sync failure can still be followed by a connected claim, and a later sync-consumer exit can leave the adapter and gateway reporting healthy while inbound Matrix processing is dead.

This PR gives the consumer an explicit startup handoff, clears connected state on every teardown/failure path, retains fatal-notification carrier tasks, and makes readiness reflect current unhealthy platform state. It deliberately does not reimplement Matrix authentication classification; #80532 remains the classifier dependency.

Related Issue

Related to #80336.

This PR addresses only the sync-task lifecycle/readiness portion of #80336; #80532 owns structured auth-error classification, so the issue should remain open until both parts are resolved.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• plugins/platforms/matrix/adapter.py: fail initial sync cleanly; serialize same-instance connect/disconnect; use a generation-owned two-phase startup handoff; supervise unexpected consumer exit; retain and generation-gate fatal notifications; and transfer task/client/crypto teardown to a cancellation-safe cleanup owner.
• gateway/readiness.py: degrade only for current unhealthy configured platform records while preserving intentional disabled and legacy record behavior.
• tests/gateway/test_matrix.py, tests/gateway/test_matrix_sync_lifecycle.py, tests/gateway/test_readiness.py: cover startup failure, reconnect failure, unexpected task exit, cancellation, notification ownership, stale callbacks, cleanup, and readiness identity/state semantics.

How to Test

1. Focused/canonical Matrix + readiness suite:

   HERMES_PYTHON=/Users/jj/.hermes/venvs/hermes-matrix-dev/bin/python \
     scripts/run_tests.sh tests/gateway/test_matrix*.py tests/gateway/test_readiness.py -q

   Exact head on current upstream/main@791e2ae3: 226 passed, 1 failed, 1 skipped. The lone failure is the pre-existing test_collect_runtime_readiness_reports_healthy_local_runtime disk-capacity assertion; unchanged current main reproduces it because this host reports disk.used_percent=90.0. Excluding that baseline case, the three changed suites pass 154/154. On the preceding base, the same diff recorded 227 passed, 0 failed, 1 skipped; the 19-test lifecycle file also passed 10 consecutive runs (190/190).
2. Temporary current upstream/main@79b8703d + fix(matrix): classify sync auth failures by status and errcode, not substring (salvage #66878) #80532 classifier stack, same command: 252 passed, 0 failed, 1 skipped.
3. Regression sabotage against unchanged current upstream/main@79b8703d while retaining the new tests: initial-sync false-connected, unexpected consumer exit, connect cancellation, connect/disconnect serialization, in-flight stale notification, cancellation-safe cleanup (crypto and session cases), immediate and cancelled constructor cleanup, cancellation during crypto database start, and stale readiness provenance all failed as intended (11 failed).
4. Repository checks: ruff check . passed; Windows-footgun scan passed across 1,019 files; py_compile and git diff --check passed. Advisory ty diff reported no new production-code diagnostic (new entries are test-mock/module-resolution diagnostics plus a tool panic). A full canonical run on the preceding base upstream/main@790e1eb6 recorded 124 failures across 39 unrelated files and no Matrix/readiness failure, so the full-suite checklist remains honestly unchecked and draft CI is the next broad gate.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits
• I searched for existing PRs and kept fix(matrix): classify sync auth failures by status and errcode, not substring (salvage #66878) #80532's classifier out of this change
• My PR contains only changes related to Matrix sync lifecycle/readiness
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes
• I've tested on macOS 26.6.2 with Python 3.11 through scripts/run_tests.sh

Documentation & Housekeeping

• Relevant documentation — N/A; this corrects runtime health semantics without adding user configuration
• cli-config.yaml.example — N/A
• CONTRIBUTING.md / AGENTS.md — N/A
• Cross-platform impact considered; no platform-specific APIs added
• Tool descriptions/schemas — N/A

Risks and exclusions

• Auth-error classification remains owned by fix(matrix): classify sync auth failures by status and errcode, not substring (salvage #66878) #80532. The temporary combined tree is tested separately, but this PR does not duplicate that contributor's classifier.
• This detects consumer termination; it is not a stalled-long-poll watchdog.
• No production gateway, account, token, or service was changed while developing this patch.

Screenshots / Logs

N/A — lifecycle behavior is covered by automated regression tests.

[jerryhjones]

Agent exact-head audit: no blockers found

Reviewed draft PR #96022 at exact head 00ec01b062f1f57d49354ca50639f5592a681c21 against base 791e2ae3257e211d14ca77e654dfe10ee1976a1c.

This is a durable agent audit record, not a formal GitHub or maintainer approval.

Lens

• initial sync failure and connected-state honesty;
• generation-owned consumer startup/publication and stale callback suppression;
• connect/disconnect serialization, fatal-notification admission, and cancellation-safe resource ownership;
• readiness state and exact runtime-writer provenance;
• dependency/overlap with [Bug]:[Matrix] Transient TLS/timeout sync failures stop sync as "permanent auth error" #80336 and fix(matrix): classify sync auth failures by status and errcode, not substring (salvage #66878) #80532;
• pushed SHA, live PR ref, base/head synchronization, scope, and honest check state.

Checks rerun

• changed suites: 154 passed, 1 deselected;
• canonical Matrix/readiness set: 226 passed, 1 failed, 1 skipped;
  • the only failure is test_collect_runtime_readiness_reports_healthy_local_runtime;
  • unchanged exact base reproduces it because this host reports 90.1% disk used, crossing the existing >= 90.0% degraded threshold;
• ruff check .: passed;
• py_compile on all changed Python files: passed;
• git diff --check: passed;
• local HEAD, fork branch, and fetched live PR ref: exact SHA match;
• non-mutating fix(matrix): classify sync auth failures by status and errcode, not substring (salvage #66878) #80532 merge-tree probe: no conflict; prior combined suite: 252 passed, 0 failed, 1 skipped.

Follow-up completed during audit

The body phrase that GitHub parsed as an auto-closing keyword was rewritten. Live closingIssuesReferences is now empty, so partial issue #80336 will remain open.

Residual risk

• GitHub currently reports no CI checks, not a pass.
• No formal maintainer review exists.
• fix(matrix): classify sync auth failures by status and errcode, not substring (salvage #66878) #80532 remains the authentication-classifier dependency.
• Consumer termination is supervised; a still-running stalled long poll is intentionally not watched.
• The broad repository suite is not green on this host; the PR checklist remains honestly unchecked.

Verdict: ready for Jerry's observation in draft state; not ready to merge.