Document A2A reply return-path routing

api/group-management.mdx

@@ -1,10 +1,10 @@
 ---
 title: Group management
 description: API reference for agent groups, messaging groups, wirings, and the v2 entity model
 tag: "UPDATED"
 ---
 
 In v2, NanoClaw uses a new entity model that separates agent groups (workspaces) from messaging groups (platform chats). These are connected through wirings — many-to-many relationships stored in `messaging_group_agents`.
 
 ## Entity model
 
@@ -45,9 +45,9 @@
 - Auto-created on first mention or DM
 - `denied_at` silently drops future mentions
 
 ### Wirings (messaging_group_agents)
 
 Wirings connect messaging groups to agent groups:
 
 ```typescript
 interface MessagingGroupAgent {
@@ -129,8 +129,8 @@
 |-------|---------|
 | `agent_groups` | Agent workspaces |
 | `messaging_groups` | Platform chats/channels |
 | `messaging_group_agents` | Wirings with engage/scope/session config |
 | `users` | Namespaced platform identifiers |
 | `user_roles` | Owner and admin roles |
 | `agent_group_members` | Unprivileged membership |
 | `user_dms` | Cached DM channel mapping |
@@ -146,7 +146,7 @@
 
 | Table | Purpose |
 |-------|---------|
-| `messages_in` | Inbound messages, tasks, system notifications |
+| `messages_in` | Inbound messages, tasks, system notifications. A2A inbound rows carry `source_session_id` for reply return-path routing |
 | `delivered` | Delivery tracking |
 | `destinations` | Live destination map |
 | `session_routing` | Default reply routing |
@@ -155,20 +155,20 @@
 
 | Table | Purpose |
 |-------|---------|
-| `messages_out` | Outbound messages |
+| `messages_out` | Outbound messages, including `in_reply_to` stamped by the agent's MCP tools for A2A reply correlation |
 | `processing_ack` | Processing acknowledgments |
 | `session_state` | Persistent key/value store |
 | `container_state` | Tool-in-flight tracking |
 
 ## Channel approval flow
 
 When a message arrives on an unwired channel:
 
 1. Router detects no wirings exist for this messaging group
 2. Channel-request gate sends approval card to the owner
 3. **Approve** — creates wiring with defaults:
    - Groups: `mention-sticky` engage mode
    - DMs: `pattern='.'` (always respond)
    - Triggering sender is auto-admitted as a member
    - Original event is replayed
 4. **Deny** — sets `denied_at` on the messaging group

api/message-routing.mdx

@@ -23,15 +23,15 @@
 
 ### 2. Messaging group lookup
 
 Combined query for messaging group and wired agent count. Messaging groups are auto-created only on mentions or DMs — plain chatter is silent.
 
 ### 3. Unwired channel handling
 
 If no agents are wired and it's a mention, the channel-request gate escalates to the owner for approval.
 
 ### 4. Sender resolution
 
 The permissions module extracts a namespaced user ID and upserts the users row:
 
 ```typescript
 // User ID format: channelType:handle
@@ -40,7 +40,7 @@
 
 ### 5. Fan-out
 
 Each wired agent is evaluated independently. Message IDs are namespaced by agent group ID to prevent collisions.
 
 ### 6. Engage evaluation
 
@@ -58,14 +58,14 @@
 
 ## Module hooks
 
 The router accepts optional pluggable hooks:
 
 | Hook | Purpose |
 |------|---------|
 | `setSenderResolver` | Runs before agent resolution — extracts user ID |
 | `setAccessGate` | Runs after agent resolution — enforces `unknown_sender_policy` |
 | `setSenderScopeGate` | Per-wiring sender scope enforcement |
 | `setChannelRequestGate` | Escalation for unwired channels |
 
 All hooks are optional. Without the permissions module, the system is allow-all.
 
@@ -86,11 +86,21 @@
 2. Filter already-delivered via `inbound.db`'s `delivered` table
 3. Route by `kind`:
    - `system` — dispatch to registered delivery action handlers
-   - `channel_type='agent'` — agent-to-agent module
+   - `channel_type='agent'` — agent-to-agent module (see [return-path routing](#agent-to-agent-return-path-routing))
    - Normal — permission check, then channel adapter delivery
 4. Mark delivered in `inbound.db`
 5. Clean up `outbox/` files (best-effort)
 
+## Agent-to-agent return-path routing
+
+When an agent emits a reply to another agent group, the target may have multiple active sessions. The router resolves the destination session in three layers, highest fidelity first:
+
+1. **Direct return-path** — if the outbound carries `in_reply_to`, the router opens the source session's `inbound.db`, reads the triggering row's `source_session_id`, and routes to that session.
+2. **Peer-affinity fallback** — when `in_reply_to` is absent or doesn't resolve, the router uses the most recent A2A inbound from the same peer agent group whose `source_session_id` is non-null.
+3. **Legacy fallback** — newest active session for the target agent group (pre-migration compatibility).
+
+The `source_session_id` column on `messages_in` is stamped when an outbound A2A message is converted to the target's inbound row. The container's MCP `send_message` and `send_file` tools thread the current batch's `in_reply_to` onto every outbound row so the host can correlate replies back to the originating session.
+
 ### Delivery actions
 
 Modules register handlers via `registerDeliveryAction(action, handler)`:

changelog/docs-updates.mdx

@@ -5,20 +5,29 @@
 rss: true
 ---
 
+<Update label="A2A reply return-path routing" description="2026-05-08" tags={["Updated"]}>
+  Documented the agent-to-agent reply routing fix from [qwibitai/nanoclaw#2267](https://github.com/qwibitai/nanoclaw/pull/2267). When a target agent group has multiple active sessions, A2A replies now route back to the session that asked the question via the new `source_session_id` column on `messages_in` and `in_reply_to` threading on `messages_out`.
+
+  ## Updated
+  - **`api/message-routing.mdx`**: new "Agent-to-agent return-path routing" section covering the three-layer resolution (direct return-path, peer-affinity fallback, legacy newest-active-session fallback)
+  - **`concepts/architecture.mdx`**: `messages_in` schema note for `source_session_id`; module summary updated to describe origin-aware A2A routing
+  - **`api/group-management.mdx`**: session-database table notes for the new `source_session_id` and `in_reply_to` fields
+</Update>
+
 <Update label="v2.0.0 launch readiness: front-door rewrites" description="2026-04-22" tags={["Updated"]}>
   Phase A of the v2 documentation sprint — bringing the pages every new user lands on into alignment with the v2 rewrite. All claims verified directly against upstream source (`src/db/schema.ts`, `src/types.ts`, `src/config.ts`, `container/Dockerfile`, `src/delivery.ts`) rather than upstream `docs/` (which includes a stale `architecture.md` draft and a `db-session.md` that omits the `container_state` table).
 
   ## Rewritten
   - **`introduction.mdx`**: v2 positioning — two-DB session IO, entity model, Node + Bun runtime split, OneCLI-only credentials. Token count updated to ~127k (~64% of context window). Source file table aligned with `src/` as of v2.0.1.
   - **`quickstart.mdx`**: one-command `bash nanoclaw.sh` flow replaces the v1 fork-and-clone + Claude Code + `/setup` dance. Documents the three-level setup log contract (terminal, `logs/setup.log`, per-step raw logs) and the Anthropic OAuth exception.
   - **`installation.mdx`**: simplified to system requirements + platform prerequisites + `bash nanoclaw.sh`. Service management retained (launchd / systemd / WSL wrapper). File-structure tree updated for `data/v2-sessions/`, `store/v2.db`, and the per-session `inbound.db` + `outbound.db` layout.
   - **`integrations/overview.mdx`**: reframed around channels (13+) and providers (4), both living on dedicated branches (`channels`, `providers`). Expanded channel list to cover Teams, iMessage, Matrix, Google Chat, Webex, Linear, GitHub, WeChat, Resend, and the local `/claw` CLI.
   - **`features/customization.mdx`**: full v2 rewrite — verified trigger pattern code against `src/config.ts`, replaced nonexistent `POLL_INTERVAL` / `SCHEDULER_POLL_INTERVAL` with actual `ACTIVE_POLL_MS` / `SWEEP_POLL_MS` from `src/delivery.ts`, documented per-wiring engage config (`engage_mode`, `sender_scope`, `ignored_message_policy`, `session_mode`), kept OneCLI / legacy credential proxy as version tabs.
 
   ## v2 update banners
   Added `<Warning>` banners to pages pending a v2 rewrite (channel adapters moved to a single `channels` branch in v2, not per-channel `skill/*` branches):
   - `integrations/whatsapp.mdx`, `telegram.mdx`, `discord.mdx`, `slack.mdx`, `gmail.mdx`, `x-twitter.mdx`, `skills-system.mdx`
   - `integrations/ollama.mdx` (Ollama now lives on the `providers` branch — `/add-ollama-provider` or `/add-ollama-tool`)
 
   ## Token count sync
   - `integrations/skills-system.mdx`: 43.8k → 127k
@@ -26,15 +35,15 @@
 </Update>
 
 <Update label="v2.0.0: architectural rewrite docs" description="2026-04-22" tags={["Updated"]}>
   Merged PR #187 — comprehensive rewrite of concepts, advanced, api, and features pages for the v2.0.0 ground-up architectural rewrite ([qwibitai/nanoclaw#1919](https://github.com/qwibitai/nanoclaw/pull/1919)). Closed PRs #184, #185, #186 as superseded.
 
   ## Updated
   - **Two-database session model**: `inbound.db` (host writes) + `outbound.db` (container writes) replace stdin/stdout piping and filesystem IPC — documented across `concepts/architecture`, `advanced/ipc-system`, `advanced/container-runtime`
   - **Entity model**: agent groups, messaging groups, wirings (many-to-many), users, and roles replace the v1 group/channel model — new `concepts/groups` and `api/group-management`
   - **Bun-based agent runner**: runs TypeScript directly (no compilation), shared source via read-only bind mount, `tini` as PID 1 — `concepts/containers`, `advanced/container-runtime`
   - **Permissions system**: engage modes (pattern/mention/mention-sticky), sender scope (all/known), unknown sender policies (strict/request_approval/public), approval flows — `concepts/security`, `advanced/security-model`
   - **Delivery system**: two-poll architecture (active 1s, sweep 60s) with delivery action registry — `features/messaging`
   - **Task model**: tasks as `messages_in` rows with cron recurrence and series tracking — `concepts/tasks`, `features/scheduled-tasks`, `api/task-scheduling`
   - **OneCLI Agent Vault** is the sole credential path; legacy credential proxy removed — `advanced/security-model`, `api/configuration`
   - **Changelog**: v2.0.0 release entry
 
@@ -59,14 +68,14 @@
   - **Architecture**: Documented auto-compact threshold at 165k tokens
 </Update>
 
 <Update label="v1.2.46–v1.2.47 sync: store mount, reply context, requiresTrigger" description="2026-04-04" tags={["Updated"]}>
   Triaged 3 automated Mintlify PRs (#175–#177). Merged #177 (most comprehensive), closed #175 and #176 (superseded). Cherry-picked unique content from closed PRs.
 
   ## Updated
   - **Store mount (rw)**: Documented `store/` read-write mount for main agent across containers, container-runtime, security, security-model, groups, customization pages
   - **`requiresTrigger` parameter**: Added to `register_group` MCP tool description in containers and messaging pages
   - **Reply context**: Updated architecture database section with `reply_to_message_id`, `reply_to_message_content`, `reply_to_sender_name` columns
   - **`isMain` preservation**: Updated register_group handler snippet in messaging page
   - **`CONTAINER_MAX_OUTPUT_SIZE`**: Added truncation behavior note to configuration reference
   - **Token count**: Updated from 43.3k to 43.4k in introduction and skills-system pages
   - **Changelog**: Added v1.2.46 and v1.2.47 product release entries
@@ -87,11 +96,11 @@
 </Update>
 
 <Update label="PR triage: v1.2.43–v1.2.46 sync" description="2026-04-02" tags={["Updated"]}>
   Reviewed and triaged 8 automated Mintlify PRs (#161–#168). Merged 4, closed 4 (superseded or stale token counts). Validated all changes against upstream source code at v1.2.46. Deleted 11 stale branches (4 PR + 7 orphan).
 
   ## Updated
   - **OneCLI version labels**: Corrected Agent Vault version from v1.2.22+ to v1.2.35+ across 8 pages, added tabbed 401 troubleshooting
   - **Ollama integration**: Added 4 admin tools (`ollama_pull_model`, `ollama_delete_model`, `ollama_show_model`, `ollama_list_running`) gated by `OLLAMA_ADMIN_TOOLS=true`, noted Ollama removal from core
   - **Stale session recovery**: Added auto-recovery docs to troubleshooting and container-runtime lifecycle, plus manual sqlite3 fallback
   - **Container runtime**: Documented `hostGatewayArgs()`, `--add-host` flag, `curl`/`git` in container image
   - **SDK options**: Added `settingSources` and `sender` parameter docs
@@ -104,23 +113,23 @@
   Merged automated health check PR #158 (4 of 5 fixes verified against upstream). Corrected the remaining inaccurate claim in a follow-up (#159).
 
   ## Fixed
   - **`api/message-routing`**: Removed phantom `channel?: ChannelType` param from `formatOutbound` signature
   - **`features/scheduled-tasks`**: Updated TIMEZONE snippet to current `resolveConfigTimezone()` with IANA validation and UTC fallback
   - **`advanced/container-runtime`**: Fixed `stopContainer` code from async `exec()` callback to actual sync try/catch pattern
   - **`api/configuration`**: Added `trace` as valid `LOG_LEVEL` value (used by container runner for verbose output)
   - **`features/messaging`**: Corrected stale `src/session-commands.ts` reference to `src/index.ts`, and fixed misleading description of what `index.ts` does
 
   ## Updated
   - **`advanced/remote-control`**: Fixed inaccurate security section — the remote control URL requires Anthropic sign-in, not just URL secrecy. Based on feedback from Gavriel Cohen.
 </Update>
 
 <Update label="Automated PR triage: v1.2.35–v1.2.42 sync" description="2026-03-28" tags={["Updated", "Fixed"]}>
   Reviewed and triaged 27 automated Mintlify PRs (#92–#151). Merged 6, consolidated 7 into a single verified PR (#153), closed 15 (superseded, fabricated, or conflicting). Validated all changes against upstream source code at v1.2.42. Deleted 41 stale `mintlify/*` branches.
 
   ## Updated
   - **OneCLI rebrand**: Renamed "OneCLI Gateway" to "OneCLI Agent Vault" across 15 pages, updated URL to `github.com/onecli/onecli`. Code snippets preserved as-is (upstream source still uses "gateway" in code).
   - **Message limits**: Corrected 200-message cap to `MAX_MESSAGES_PER_PROMPT` (default 10) across messaging, architecture, and configuration pages
   - **Dependencies**: Removed phantom deps (`pino`, `pino-pretty`, `yaml`, `zod`), updated `better-sqlite3` to `11.10.0` and `cron-parser` to `5.5.0`
   - **Token count**: Updated from ~41.3k to ~42.4k
   - **Mount property**: Fixed `containerConfig.mounts` → `additionalMounts` with `hostPath`
   - **SQL column**: Fixed `trigger` → `trigger_pattern` in troubleshooting query
@@ -130,9 +139,9 @@
   - **Telegram forum topics** (`integrations/telegram`) — `message_thread_id` tracking and automatic topic routing
   - **Task scripts cost guidance** (`concepts/tasks`, `features/scheduled-tasks`, `api/task-scheduling`) — API credit awareness, testing guidance, when-not-to-use advice
   - **Auth 401 troubleshooting** (`advanced/troubleshooting`) — short-lived vs long-lived OAuth tokens, `claude setup-token` fix
   - **K8s image GC** (`advanced/troubleshooting`) — Rancher Desktop kubelet garbage collection known issue
   - **Text-style formatting** (`features/messaging`) — corrected WhatsApp link rendering and Telegram Markdown v1 preservation
   - **Security fixes** (`advanced/container-runtime`, `advanced/security-model`, `concepts/security`) — `stopContainer` name validation, mount path colon rejection, `isMain` preservation, allowlist caching behavior
   - **Configuration**: Added `MAX_MESSAGES_PER_PROMPT` and `LOG_LEVEL` environment variables
   - **Skills**: Added `/init-onecli` (operational) and `/add-emacs` (upstream)
 
@@ -143,7 +152,7 @@
 </Update>
 
 <Update label="Automated PR triage: v1.2.24–v1.2.34 sync" description="2026-03-26" tags={["New", "Updated", "Fixed"]}>
   Reviewed and triaged 43 automated Mintlify PRs (#86–#128). Merged 8, closed 30 (superseded or inaccurate), kept 5 pending v1.2.35 release. Validated all changes against upstream source code at v1.2.34.
 
   ## New sections
   - **Task scripts** (`concepts/tasks`, `features/scheduled-tasks`, `api/task-scheduling`) — pre-execution bash scripts with `wakeAgent` JSON contract, `ScriptResult` type, execution flow
@@ -151,7 +160,7 @@
   - **CLAUDE.md template system** (`concepts/groups`, `api/group-management`) — automatic template copy during registration with `isMain`-based selection
   - **Channel-formatting skill** (`features/messaging`, `api/message-routing`, `integrations/slack`, `integrations/skills-system`) — per-channel text transformation table
   - **WhatsApp pairing code auth** (`integrations/whatsapp`) — tabbed QR code vs pairing code with phone number formatting rules
   - **loginctl linger** (`installation`, `quickstart`, `advanced/troubleshooting`) — systemd user service persistence after SSH logout
   - **Mount-allowlist preservation** (`quickstart`, `advanced/troubleshooting`) — `/setup` skips overwrite of existing config
 
   ## Updated
@@ -192,8 +201,8 @@
   - **Container runtime**: Container arguments code and key flags documented for both methods
   - **Architecture**: Startup sequence and container image updated
   - **Installation**: OneCLI added as prerequisite #5, `@onecli-sh/sdk` dependency
   - **Containers, Ollama, Skills examples**: Passing references updated to version-neutral language
   - **Customization**: Mount allowlist format updated (`allowedPaths` → `allowedRoots` with per-root read/write control)
   - **Product changelog**: Added v1.2.22 release entry and v1.2.0 scheduled task fix
 </Update>
 
@@ -215,7 +224,7 @@
 </Update>
 
 <Update label="PR consolidation and issue cleanup" description="2026-03-23" tags={["New", "Updated", "Fixed"]}>
   Reviewed, triaged, and consolidated 10 automated Mintlify PRs (#60–#69). Verified all changes against NanoClaw source code, excluded 6 incorrect changes, and resolved the final 2 open issues.
 
   ## New pages
   - **Claw CLI** (`features/cli`) — documents the `/claw` Python CLI for running agents from the command line (#64)
@@ -223,7 +232,7 @@
   ## New sections
   - **Apple Container vs Docker** (`advanced/container-runtime`) — when to use each runtime, key differences table, switching instructions (closes #50)
   - **Container internals** (`concepts/containers`) — allowed tools table, conversation archival, global memory injection, additional directory auto-discovery
   - **Slack message formatting** (`integrations/slack`) — mrkdwn syntax differences and `/slack-formatting` skill
   - **200-message history cap** (`features/messaging`) — documents the default query limit on message retrieval (closes #49)
   - **Opt-in diagnostics** (`concepts/security`, `quickstart`) — PostHog telemetry, consent flow, permanent opt-out (#68)
 
@@ -235,12 +244,12 @@
   - **Configuration** — fixed DATA_DIR description (runtime data, not legacy)
   - **Skills system** — added missing skills (`/get-qodo-rules`, `/qodo-pr-resolver`, `/x-integration`, `/add-compact`, `/add-parallel`, `/slack-formatting`)
   - **Contributing** — removed `/clear` from RFS (exists as `/add-compact`), updated to 4 skill types
   - **SEO descriptions** — improved frontmatter across 10 pages for better search discoverability
 
   ## Fixed
   - 13-page factual error sweep against source code (#67) — credential proxy terminology, IPC operations, container mount behavior, removed phantom MCP tool
   - Consolidated overlapping fixes from 6 PRs into 2 clean PRs (#70, #71), closing 7 automated PRs as superseded
   - Excluded incorrect automated changes: Channel Factory rename, fabricated commit reference, speculative formatting table, unverified frontmatter claims
 
   ## Housekeeping
   - Product changelog: added v1.2.20 (ESLint) and v1.2.21 (diagnostics) entries, fixed version ordering
@@ -252,21 +261,21 @@
   Ran a full docs-gap analysis against the upstream codebase and resolved 13 of 15 content-gap issues. Two low-priority items remain open (#49, #50).
 
   ## New pages
   - **Ollama integration** (`integrations/ollama`) — MCP server architecture, local model setup, third-party endpoints
   - **Voice transcription** (`features/voice-transcription`) — Whisper API (cloud) and whisper.cpp (local) with comparison table
   - **Image vision** (`features/image-vision`) — Multimodal image understanding for WhatsApp
   - **PDF reader** (`features/pdf-reader`) — Text extraction via poppler-utils
   - **X (Twitter) integration** (`integrations/x-twitter`) — Host+agent architecture, OAuth setup
   - **Parallel AI** (`integrations/parallel-ai`) — Web research MCP servers (quick search + deep research)
 
   ## Updated pages
   - **Skills system** — Documented channel fork architecture (5 fork repos), updated merge workflows, separated upstream vs fork skills
   - **Installation** — Added Windows (WSL) support across all sections: prerequisites, Docker Desktop WSL 2 backend, troubleshooting
   - **Security** — Documented sender allowlist: trigger/drop modes, per-chat overrides, file format
   - **Messaging** — Added `/compact` session command and authorization rules
   - **Telegram** — Expanded agent swarm section with installation and per-bot config
   - **WhatsApp** — Added skills summary table and emoji reactions section
   - **API reference** — Fixed `formatMessages` signature (added `timezone` param and `<context>` header)
   - **Configuration** — Added `OLLAMA_HOST`, expanded `ANTHROPIC_BASE_URL` and `SENDER_ALLOWLIST_PATH` docs
 
   ## Housekeeping
@@ -292,7 +301,7 @@
 
 <Update label="Source sync and remote control" description="2026-03-19" tags={["Updated"]}>
   - Fixed remote-control commands documentation
   - Deduplicated IPC docs
   - Added `update_task` to auth tables in API reference
 </Update>
 
@@ -308,12 +317,12 @@
 
 <Update label="v1.2.17 source sync" description="2026-03-18" tags={["New", "Updated"]}>
   - Documented `/capabilities` and `/status` container-agent skills as new pages
   - Synced docs with source code v1.2.17 — corrected mount allowlist format, interval drift handling, credential proxy behavior, and IPC config
   - Documented IPC task snapshot refresh and `update_task` operation
 </Update>
 
 <Update label="Credential proxy and task lifecycle" description="2026-03-16" tags={["Fixed"]}>
   Fixed stale documentation for credential proxy, database path, mount allowlist, and task lifecycle to match current source code.
 </Update>
 
 <Update label="Automation workflows" description="2026-03-16" tags={["New"]}>
@@ -324,7 +333,7 @@
 <Update label="Portal branding and UX" description="2026-03-16" tags={["Updated"]}>
   - Applied NanoClaw branding with custom theme colors, fonts, and SEO metadata
   - Switched theme from Aspen to Mint for better sidebar typography
   - Cleaned up introduction page, footer, and removed callout CSS override
 </Update>
 
 <Update label="Portal launch" description="2026-03-15" tags={["New"]}>

concepts/architecture.mdx

@@ -5,7 +5,7 @@
 keywords: ["architecture", "system design", "single process"]
 ---
 
 NanoClaw is a lightweight AI assistant that runs agents in isolated containers. The v2 architecture is a ground-up rewrite built on a two-database session model, a pluggable module system, and a new entity model that separates users, agent groups, messaging groups, and wirings.
 
 ## High-level overview
 
@@ -41,7 +41,7 @@
 
 ### Channel adapters
 
 NanoClaw uses a self-registering adapter pattern for messaging channels. Installed adapters such as Telegram, Discord, WhatsApp, Signal, Slack, Teams, iMessage, and the local CLI register at startup. Channels with missing credentials are skipped with a warning.
 
 All adapters implement a common interface with `onInbound`, `onInboundEvent`, `onMetadata`, and `onAction` callbacks, allowing the rest of the system to be channel-agnostic.
 
@@ -49,16 +49,16 @@
 
 The router (`src/router.ts`) is the central message routing pipeline:
 
 1. **Thread policy** — non-threaded adapters (Telegram, WhatsApp, iMessage) collapse `threadId` to null
 2. **Messaging group lookup** — finds or auto-creates messaging groups on mentions/DMs
 3. **Unwired channel handling** — if no agents are wired, the channel-request gate escalates to the owner for approval
 4. **Sender resolution** — the permissions module extracts namespaced user IDs and upserts users
 5. **Fan-out** — each wired agent is evaluated independently against engage mode, sender scope, and access gates
 6. **Engage evaluation** — per-agent decision based on `pattern`, `mention`, or `mention-sticky` mode
 7. **Delivery** — engaging agents get a session wake and container spawn; non-engaging agents with `accumulate` policy store the message for future context
 
 <Info>
 Message IDs are namespaced by agent group ID to prevent collisions during fan-out to multiple agents.
 </Info>
 
 ### Session manager
@@ -77,7 +77,7 @@
 
 The container runner (`src/container-runner.ts`) spawns and manages isolated agent execution:
 
 - **Wake deduplication** — concurrent wake calls for the same session are deduplicated via an in-flight promise map
 - **Per-agent-group images** — custom Docker images with additional apt/npm packages can be built per agent group
 - **Shared source** — `/app/src` is a read-only bind mount from the host; source changes never require an image rebuild
 - **No stdin/stdout** — all IO is via the two-DB split; no stdin piping or output markers
@@ -92,7 +92,7 @@
 - **Retry** — 3 attempts per message, then permanently failed
 
 <Note>
 Deduplication via an in-flight set prevents double-delivery when both polls hit the same session simultaneously.
 </Note>
 
 ### Host sweep
@@ -100,7 +100,7 @@
 The host sweep (`src/host-sweep.ts`) runs every 60 seconds:
 
 - Syncs `processing_ack` from `outbound.db` to update inbound message status
 - Detects stale containers via heartbeat mtime and processing_ack age
 - Wakes containers for due messages (scheduled tasks with `process_after <= now`)
 - Advances recurring task series (creates next-occurrence rows)
 
@@ -108,26 +108,26 @@
 
 **Central database** (`data/v2.db`) stores the entity model:
 
 - **agent_groups** — workspaces with folder, name, and optional provider
 - **messaging_groups** — platform chats with `unknown_sender_policy` (`strict`, `request_approval`, or `public`)
 - **messaging_group_agents** — many-to-many wirings with engage mode, pattern, sender scope, ignored message policy, session mode, and priority
 - **users** — namespaced platform identifiers (e.g., `phone:+1555...`, `tg:123`, `discord:456`)
 - **user_roles** — owner (always global) or admin (global or scoped to agent group)
 - **sessions** — status tracking for both session and container
 
 **Session inbound.db** (host writes, container reads):
 
-- **messages_in** — inbound messages with status, `process_after`, recurrence, `series_id`, and trigger flag
+- **messages_in** — inbound messages with status, `process_after`, recurrence, `series_id`, trigger flag, and (for A2A inbound) `source_session_id` for return-path routing
 - **delivered** — tracks delivery outcomes
 - **destinations** — live destination map (channels and other agents)
 - **session_routing** — default reply routing
 
 **Session outbound.db** (container writes, host reads):
 
 - **messages_out** — outbound messages with `deliver_after` and recurrence
 - **processing_ack** — tracks which inbound messages the container has processed
 - **session_state** — persistent key/value store (e.g., SDK session ID for resume)
 - **container_state** — tool-in-flight state for stuck-detection
 
 ### Module system
 
@@ -135,7 +135,7 @@
 
 - **Permissions** — sender resolution, access gating, channel approval, sender approval
 - **Scheduling** — task creation, pause/resume/cancel/update via delivery actions
-- **Agent-to-agent** — cross-agent message routing
+- **Agent-to-agent** — cross-agent message routing with origin-aware return paths so replies land in the session that asked the question, not just the target's newest active session
 - **Approvals** — interactive question cards
 - **Self-mod** — agent self-modification requests
 - **Typing** — typing indicator management
@@ -231,7 +231,7 @@
 - **Tools**: `agent-browser`, `vercel` CLI, `curl`, `git`
 - **SDK**: `@anthropic-ai/claude-code` (Claude Agent SDK)
 - **PID 1**: `tini` for proper signal forwarding
 - **User**: Runs as `node` user (uid 1000, non-root)
 - **Working directory**: `/workspace/group`
 
 <Info>
@@ -240,12 +240,12 @@
 
 ## Startup sequence
 
 1. **Central DB initialization** — opens `data/v2.db`, runs migrations, performs one-time filesystem cutover
 2. **Container runtime check** — ensures Docker is running, cleans up orphan containers
 3. **Channel adapter initialization** — registers all channel adapters with `onInbound`, `onInboundEvent`, `onMetadata`, and `onAction` callbacks
 4. **Delivery adapter bridge** — bridges the delivery system to channel adapters for `deliver()` and `setTyping()` calls
 5. **Delivery polls** — starts active poll (1s for running containers) and sweep poll (60s for all active sessions)
 6. **Host sweep** — 60s sweep for processing_ack sync, stale detection, due-message wake, and recurrence advancement
 
 ## Graceful shutdown