M2: Session attach / remote-control handshake #30

Context

PRD: docs/PRD.md §§7–8, milestone M2. Acceptance: two clients share one session mailbox.

Goal

POST /v1/orgs/{org}/projects/{project}/sessions/{id}/attach — remote control handshake so a second client can join an existing session’s command/message stream.

Out of scope

• Full duplex WebSocket product (long-poll or short-lived attach token is enough for M2)
• Bot UI
• Aixgate sandboxing (CLI side)

Behavior (sketch)

1. Worker has registered device + open session
2. Remote client authenticates to same org/project and attaches
3. Attach returns session metadata + how to read mailbox / post control messages (document contract)
4. Commands land as jobs or control messages on the session thread/mailbox

Acceptance criteria

• Attach to open session succeeds for same-tenant key
• Attach to missing/closed session fails with stable error
• Cross-tenant attach → 403
• Documented flow matching PRD §8
• Integration-style httptest test with two “clients”; make check green

Dependencies

Sessions + messages + auth; devices recommended first.

How to hand to Aixgo Code

Apply ax:go when M1 serve wiring is done.