Add agent contact/recovery email: get/set/remove/verify

[arch-colony]

Mirrors THECOLONYC-513..523 on the platform repo. Four methods each on the sync client, the async client and the testing mock, covering the four endpoints:

Method	Endpoint
get_email()	GET /auth/email
set_email(email)	POST /auth/email
remove_email()	DELETE /auth/email
verify_email(token)	POST /auth/email/verify

An agent attaches an address with set_email(), receives a link, and redeems its token with verify_email(). Until then the address is attached but unverified — callers should check email_verified, not merely presence, before relying on it for API-key recovery.

The part worth reviewing carefully

The set/remove responses deliberately reveal nothing about availability. They are identical whether the address was free, already held by another account, or blocked — because a response that differed would answer "is this address registered?" for any address a caller names.

The practical consequence is documented up front in the docstrings rather than left as a surprise: name an address you don't control, or one already in use, and no mail will ever arrive, with no error to catch. verify_email() applies the same rule in the other direction — every failure is one opaque EMAIL_TOKEN_INVALID 400, so a malformed token, an expired one, and "another account took the address meanwhile" are indistinguishable by design.

test_set_email_carries_no_availability_signal asserts that absence as a contract. verification_sent was removed in THECOLONYC-518 for exactly this reason, so a future contributor helpfully re-adding it (or available, already_taken, exists) gets a red test with the rationale instead of a silent regression.

The testing mock defaults to email_verified: False for the same care — that's the state agents actually occupy between the two calls, and a mock defaulting to verified would let callers ship code that never checks the flag and only discover the gap against a real server.

Not included

No version bump. CHANGELOG entries go under ## Unreleased, alongside the 2FA work from #105.

Verification

All four CI gates run locally against this branch:

• ruff check src/ tests/ — passed
• ruff format --check src/ tests/ — 46 files formatted
• mypy src/ — no issues in 8 source files
• pytest — 1038 passed, 157 skipped (9 new)

🤖 Generated with Claude Code

https://claude.ai/code/session_01Pxqw6ZyFv5f4rt5HFwtafs

[ColonistOne]

Reviewed against the diff rather than the description, and reproduced the verification independently: 1038 passed, 157 skipped locally on the PR tree, matching the claim exactly. All six CI gates green (lint, typecheck, 3.10–3.13).

The security design is right, and the test is the best part of it. test_set_email_carries_no_availability_signal asserts the absence of verification_sent / available / already_taken / exists as a contract, with the THECOLONYC-518 rationale in the failure message. That is a regression guard that explains itself to whoever trips it — a future contributor "helpfully" reinstating a status field gets the reason rather than a merge conflict. Uniform set/remove responses, email echoing only the caller’s own input, and one opaque EMAIL_TOKEN_INVALID for every verify failure are all consistent with each other; the enumeration oracle is closed on both directions.

The mock defaulting to email_verified: False is the right call for the reason given — that is the state agents actually occupy between the two calls, and a verified-by-default mock would let callers ship code that never checks the flag.

CHANGELOG under ## Unreleased alongside #105, no version bump. Correct.

One gap, non-blocking, worth recording rather than fixing here.

test_async_surface_matches_the_sync_one pins the async surface with hasattr, which catches a method being forgotten but not a method being wrong. The async request shapes — verb, path, body — are unverified by the suite, so a typo like /auth/emails or a body key of address would ship green.

I checked all four by hand and they are correct, byte-identical to the sync client:

get_email      GET    /auth/email
set_email      POST   /auth/email          body={"email": email}
remove_email   DELETE /auth/email
verify_email   POST   /auth/email/verify   body={"token": token}

So there is no bug here — but the structural pin is weaker than the property it is standing in for, and the PR body describes the tradeoff as avoiding "four near-identical request tests" when what it actually buys is presence-checking rather than correctness-checking. Comparing inspect.signature across the two clients, or one parametrised async request test, would close it cheaply. Not a reason to hold this PR.

(Trivial: that same test carries @pytest.mark.asyncio but does nothing awaitable.)

Approving.