(CODUX-225) Complete the iMessage bridge connector

[numnx]

🧩 Task: Complete the iMessage bridge connector

Automated task PR opened by Code UX for T07.

📋 Summary

Sprint: Sprint 225 · Chat connector completeness and verification · Task: T07

Complete and verify all six chat connectors through provider-specific profiles, correct authentication and session behavior, encrypted durable state, atomic routing and retries, REST/MCP/dashboard management, official-documentation evidence, deterministic contract coverage, and credential-gated checks limited to provider-controlled endpoints, with Discord prioritized.

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.6-sol

⏱️ Timing

Started	2026-07-13 22:51:13 UTC
Finished	2026-07-13 23:08:03 UTC
Duration	16m 50s

📊 Token Usage

Metric	Value
Input tokens	162,153
Cached input tokens	4,345,600
Output tokens	38,613
Total tokens	4,546,366
Invocations	1
Tool calls	37
Active time	15m 46s

Included usage estimate (subscription/local login): $4.14

✅ QA Review

⏳ QA review runs after this PR is opened. Check the task card in the dashboard for the outcome once it lands.

📝 Full Task Prompt

## Objective
Complete iMessage as a transparent managed/native bridge contract with strict process, authentication, health-check, and lifecycle behavior rather than claiming unsupported direct Apple API access.

## Scope
- `src/domain/chat-connectors/providers/imessage.ts`
- Create `src/services/chat-providers/imessage-native-bridge.ts`
- Create `tests/backend/domain/chat-connectors/imessage.test.ts` and `tests/backend/services/imessage-native-bridge.test.ts`
- `docs/settings/chat-connectors/imessage.md`
- `docs-web/architecture/chat-connectors/imessage.md`
- Official references: [Apple Messages framework](https://developer.apple.com/documentation/messages), [iMessage apps](https://developer.apple.com/imessage/), and [Message UI](https://developer.apple.com/documentation/messageui)

## Implementation Requirements
1. Keep `managed_bridge` and `native_bridge` as the only supported modes, label them as third-party/local bridge contracts, and explicitly mark provider-native endpoint verification as unavailable.
2. Define a versioned JSON stdin/stdout protocol for send and health-check operations, including stable message, chat, sender, reply, correlation, result, and error fields.
3. Execute the configured binary and arguments without a shell, enforce bounded stdout/stderr and timeout limits, pass secrets only through the dedicated environment boundary, and terminate the full child process lifecycle on timeout, cancellation, or shutdown.
4. Validate managed/native inbound bearer credentials and replay nonces through shared security primitives, normalize bridge message GUIDs and chat GUIDs, and preserve thread/reply identity without assuming undocumented Apple payload shapes.
5. Implement deterministic health verification for managed bridges and native commands, including unsupported platform, missing executable, permission, protocol-version, timeout, malformed response, and nonzero-exit diagnostics.
6. Document that Apple publishes app-extension and business experiences but no general-purpose public server bot API or public personal-iMessage sandbox, so no Apple network endpoint may be used by the live test suite.
7. Cover quoting, spaces, Windows/macOS path handling, missing executables, timeouts, cancellation, oversized output, malformed JSON, credential redaction, protocol negotiation, and successful bridge sends with Node-powered fixtures.

## Constraints
- Do not claim the native bridge is endorsed, hosted, or tested by Apple.
- Do not use shell interpretation, AppleScript in tests, the local Messages database, or a real user's Messages account.
- Preserve existing native command records and retain explicit operator control over executable configuration.
- Do not modify other provider modules or shared generated docs-web artifacts.

## Verification
- Run `pnpm run test:backend -- tests/backend/domain/chat-connectors/imessage.test.ts tests/backend/services/imessage-native-bridge.test.ts`.
- Run `pnpm run lint`.
- Confirm all tests are deterministic on Linux, macOS, and Windows and no test attempts an Apple network or local Messages operation.

🌿 Branch Info

Base: feature/CODUX-225-chat-connector-completeness-and-verification
Head: task/feature-codux-22-t07-codex-24812d70-mrjtgp06

---

🤖 Generated by Code UX