feat: add session.identityLinks for cross-platform DM session linking (#1033)

Co-authored-by: Shadow <shadow@clawd.bot>

docs/concepts/session.md

@@ -11,6 +11,7 @@ Use `session.dmScope` to control how **direct messages** are grouped:
 - `main` (default): all DMs share the main session for continuity.
 - `per-peer`: isolate by sender id across channels.
 - `per-channel-peer`: isolate by channel + sender (recommended for multi-user inboxes).
+Use `session.identityLinks` to map provider-prefixed peer ids to a canonical identity so the same person shares a DM session across channels when using `per-peer` or `per-channel-peer`.
 
 ## Gateway is the source of truth
 All session state is **owned by the gateway** (the “master” Clawdbot). UI clients (macOS app, WebChat, etc.) must query the gateway for session lists and token counts instead of reading local files.
@@ -42,6 +43,7 @@ the workspace is writable. See [Memory](/concepts/memory) and
     - Multiple phone numbers and channels can map to the same agent main key; they act as transports into one conversation.
   - `per-peer`: `agent:<agentId>:dm:<peerId>`.
   - `per-channel-peer`: `agent:<agentId>:<channel>:dm:<peerId>`.
+  - If `session.identityLinks` matches a provider-prefixed peer id (for example `telegram:123`), the canonical key replaces `<peerId>` so the same person shares a session across channels.
 - Group chats isolate state: `agent:<agentId>:<channel>:group:<id>` (rooms/channels use `agent:<agentId>:<channel>:channel:<id>`).
   - Telegram forum topics append `:topic:<threadId>` to the group id for isolation.
   - Legacy `group:<id>` keys are still recognized for migration.
@@ -86,6 +88,9 @@ Send these as standalone messages so they register.
   session: {
     scope: "per-sender",      // keep group keys separate
     dmScope: "main",          // DM continuity (set per-channel-peer for shared inboxes)
+    identityLinks: {
+      alice: ["telegram:123456789", "discord:987654321012345678"]
+    },
     idleMinutes: 120,
     resetTriggers: ["/new", "/reset"],
     store: "~/.clawdbot/agents/{agentId}/sessions/sessions.json",