fix(telegram): admin @username resolution, store convergence, group-invite policy enforcement, privacy-mode warning

[juniperbevensee]

Fixes four Telegram connector gaps in HSM.

1. Connect-path admins: @usernames resolved, multiple admins supported

The connect route previously wrote config.adminUser verbatim into TELEGRAM_ALLOWED_USERS — a typed @handle was stored raw and never matched the numeric sender IDs the gateway compares against, silently locking the admin out.

• Connect dialog admin field now accepts multiple comma-separated entries (numeric IDs and/or @usernames).
• Server-side (surfaces/connect): entries are split, @handles resolved to numeric IDs via resolveTelegramAdmins (strict — an unresolvable handle returns 400, surfaced inline in the dialog; nothing raw is ever stored). The bot token from the request payload is used, since TELEGRAM_BOT_TOKEN may not be in the agent .env yet at connect time.
• Display names persisted to resolved-identities.json (merged, same shape as the settings path).
• Settings PUT: telegram allowlists are expanded with resolved numeric IDs (expandTelegramAllowlist, mirroring the Signal phone→UUID expansion).

2. Admin-store convergence

TELEGRAM_ALLOWED_USERS (env bootstrap) and the SurfaceAdminService overlay (harnesses.json → surfaceAdmins, served live to the policy plugin) could diverge. Both the connect route and settings PUT now call SurfaceAdminService.syncFromAllowlist, which replaces the explicit overlay (when one exists) with the valid numeric identities from the freshly-written allowlist. Invalid entries (unresolved @handles, wildcards) are dropped by validation — never stored. With no explicit overlay, the bootstrap default already reads the env live, so no sync is needed and setAdmins's bootstrap-actor semantics are preserved.

3. Telegram group-invite policy is no longer inert

• GROUP_INVITE_VARS gains telegram: 'TELEGRAM_GROUP_INVITE_POLICY' — the existing Group Invite Policy toggle now actually writes it (approved-only / allow-all, same values as signal/slack).
• New enforcement endpoint for the swarm_map_policy agent plugin (contract below).
• Middleware: the new POST path is exempted from the operator-cookie gate via AGENT_CALLABLE_POST_PATHS (agents cannot obtain the cookie — same rationale as the existing agent-read allowlist). Trust model documented in middleware.ts: the caller self-reports addedByUserId, so blast radius is bounded — the handler can only append one structurally-validated groupId to that surface's group allowlist, still gated by policy + admin check, and audit-logged.

4. Privacy-mode warning in the connect flow

The dialog's getMe verification now reads can_read_all_group_messages; when false a non-blocking warning explains Group Privacy is ON, the bot won't see regular group messages, how to disable it (BotFather → /setprivacy → Disable), and that the bot must be removed/re-added to existing groups after changing it.

Plus format hints on both the connect-dialog admin field and the settings Admins TagInput (numeric IDs or @usernames; @usernames auto-resolved).

New plugin contract (consumed by a hermes-agent-mt follow-up)

POST /api/harnesses/:id/surfaces/:platform/groups/:groupId
Content-Type: application/json

{ "addedByUserId": "<platform-native user id of whoever added the bot>" }

Responses (200 unless the request is malformed):

Case	Body
Approved, allowlist updated	{ "approved": true, "restarted": <bool> } (restarted:false = env written but container recreate failed, e.g. no compose file yet)
Approved, no-op (* wildcard or already listed)	{ "approved": true, "already_allowed": true }
Rejected	{ "approved": false, "reason": "<why>" } — plugin should leave the group
Malformed (unsupported platform, invalid groupId, missing addedByUserId, no agent .env)	400 { "error": "<what>" }

Policy semantics: allow-all → approve for anyone; approved-only or unset (secure default) → approve only when addedByUserId is an admin (SurfaceAdminService.isAdmin, fail-closed). No auth cookie required on this one path (see AGENT_CALLABLE_POST_PATHS).

Test results

• vitest run: 85 files, 829 tests passed (43 new: resolver strict/best-effort matrices, connect-route resolution + multi-admin normalization + 400-on-unresolvable, store convergence, approveGroupInvite policy × admin matrix, POST route responses, middleware gate exemptions, privacy-mode flag).
• eslint .: identical to baseline (72 pre-existing errors, none introduced).
• next build: passes.

Noted but deliberately not fixed

• addedByUserId on the new POST is self-reported by the agent — the server cannot verify who performed the platform-side invite. Documented in middleware.ts; consistent with the trust already extended to the plugin's is_admin/is_group_allowed reads.
• The same connect-path verbatim-adminUser behavior still exists for mattermost/discord/slack (out of scope).
• Settings PUT keeps raw @handles in the env alongside the appended numeric IDs (display parity with the settings GET merge; harmless — they just never match).

🤖 Generated with Claude Code