@openparachute/agent 0.1.0

package/docs/design/2026-05-01-channel-wiring-approvals-deep-dive.md

@@ -0,0 +1,272 @@
+# Channel-wiring + approvals deep dive
+
+**Status:** Research · 2026-05-01 · follow-up to paraclaw#67
+
+Aaron wired a second Telegram bot via `/claw/channels/new` (the fast-path landed in PR #69). The form validated the bot, captured his Telegram userId, and offered the wire button. Then he DM'd the new bot — and a "wire this channel?" approval card landed in his **first** Telegram bot's DM, asking him to approve a registration he'd just initiated three seconds earlier through the form.
+
+This is empirically wrong on at least three axes: the approval shouldn't have fired (the form already had operator intent), the card shouldn't have been delivered through a *different* bot, and the resulting wiring used cautious approval-flow defaults instead of the trusted-operator wire-flow defaults. Aaron asked for a deep dive before any code changes.
+
+This document reconstructs what actually happened from the live install's DB and logs, maps the architecture that produced the behavior, critiques what's wrong, and proposes three design directions. Aaron decides what to do.
+
+---
+
+## 1. Empirical trace
+
+Live install at `~/.parachute/claw/paraclaw.db` (note: filename is `paraclaw.db`, not the `v2.db` the prompt referenced; same role). Times are UTC except where noted (log file uses local PT — UTC = local + 6h).
+
+### 1.1 The two bots
+
+`messaging_groups` rows for telegram, ordered by creation:
+
+| MG id | platform_id | name | is_group | unknown_sender_policy | created_at |
+|---|---|---|---|---|---|
+| `mg-…e4z1rv` | `telegram:8792496425:1190596288` | Techne DM | 0 | **strict** | 2026-04-28 05:05 |
+| `mg-…ihfgeq` | `telegram:8792496425:-1003927577645` | (group) | 1 | request_approval | 2026-04-29 02:25 |
+| `mg-…90uhi5` | `telegram:8757751201:-1002245300962` | (group) | 1 | request_approval | 2026-05-01 19:13:43.981 |
+| `mg-…ogxhkj` | `telegram:8757751201:1190596288` | (DM) | 0 | request_approval | 2026-05-01 19:13:43.982 |
+
+Bot1 = `8792496425` (UnforcedAGI / the original setup-wizard wire). Bot2 = `8757751201` (the new one). Aaron's Telegram user id = `1190596288`.
+
+### 1.2 The wirings
+
+`messaging_group_agents` (all wired to the only existing agent group, Techne):
+
+| MGA id | MG | engage | sender_scope | ignored_msg_policy | created_at |
+|---|---|---|---|---|---|
+| `mga-…gc6co9` | bot1-DM-Aaron | pattern `.` | **all** | **drop** | 2026-04-28 |
+| `mga-…5i9dz9` | bot2-DM-Aaron | pattern `.` | **known** | **accumulate** | 2026-05-01 19:14:17 |
+| `mga-…9977ij` | bot2-Group | pattern `.` | known | accumulate | 2026-05-01 19:15:07 |
+
+Bot1's MGA (created by `init-first-agent.ts`) uses the trusted defaults: `sender_scope='all'`, `ignored_message_policy='drop'`, `unknown_sender_policy='strict'`. Bot2's MGA uses the cautious defaults: `sender_scope='known'`, `ignored_message_policy='accumulate'`, `unknown_sender_policy='request_approval'`. **Different rows, different behavior, both wired by the operator on the same day for the same operator.**
+
+### 1.3 user_dms cache
+
+| user_id | channel_type | messaging_group_id | resolved_at |
+|---|---|---|---|
+| `telegram:1190596288` | telegram | `mg-…e4z1rv` (bot1 DM) | 2026-04-29 |
+
+`user_dms` is keyed `(user_id, channel_type)` — exactly one row per user-channel. When the channel-approval flow asks "where can I reach Aaron?", this cache says "his bot1 DM" and stops.
+
+### 1.4 The timeline (from `~/.parachute/claw/logs/claw.log`)
+
+```
+13:13:43.697  Channel bot registered          adapter=telegram botId=8757751201
+13:13:43.697  Channel adapter registered dynamically
+13:13:43.980  Inbound DM received             channelId=telegram:8757751201:1190596288  (×3)
+13:13:43.981  Auto-created messaging group    mg-…90uhi5  (telegram:8757751201:-1002245300962)
+13:13:43.982  Auto-created messaging group    mg-…ogxhkj  (telegram:8757751201:1190596288)
+13:13:43.983  ERROR Channel-request gate threw — UNIQUE constraint failed:
+              pending_channel_approvals.messaging_group_id  (×2)
+13:13:44.529  Channel registration card delivered  mg-…90uhi5  approver=telegram:1190596288
+13:13:44.555  Channel registration card delivered  mg-…ogxhkj  approver=telegram:1190596288
+13:14:17.329  Channel registration approved — wiring created  mga-…5i9dz9
+13:14:17.342  Session created
+13:14:17.353  Spawning container               techne
+13:14:25.204  Message delivered                platformId=telegram:8757751201:1190596288
+13:15:07.386  Channel registration approved — wiring created  mga-…9977ij  (group)
+```
+
+### 1.5 What this says
+
+**The wire form's `Wire` button never effectively ran.** Validation completed at 13:13:43.697; the dynamic register-bot path (PR #67 B2) brought the Bot2 polling loop live in the same call. **283 ms later** Telegram's `getUpdates` returned three queued DMs Aaron had sent before the form even existed. The router auto-created the bot2-DM messaging group with `unknown_sender_policy='request_approval'` (router.ts:179, hardcoded for any auto-create), saw zero wirings, and called `channelRequestGate` — which delivered the approval card. Aaron approved via the card; the channel-approval handler created the MGA with its own (cautious) defaults. By the time the operator could reach the form's "Wire" button, the MGA already existed; the wire button was a no-op idempotent on the existing MGA pair.
+
+The wire path's defaults (`sender_scope='all'`, `unknown_sender_policy='strict'`) were never applied. The approval-handler's defaults (`sender_scope='known'`, `unknown_sender_policy='request_approval'` inherited from auto-create) won by milliseconds.
+
+### 1.6 The race-condition bug
+
+Three rapid inbound DMs at 13:13:43.980 each fired `requestChannelApproval`. The dedup check (`hasInFlightChannelApproval` in `channel-approval.ts:63`) reads-then-inserts non-atomically. All three saw "no pending row" and raced the `INSERT INTO pending_channel_approvals` (PK on messaging_group_id). The first won; the other two threw `UNIQUE constraint failed` (logged at ERROR). User-visible impact: zero — the first INSERT got an approval card delivered. But the error log is misleading and the dedup is wrong by design.
+
+### 1.7 Why the card came through Bot1
+
+`pickApprovalDelivery(approvers, originChannelType)` (`src/modules/approvals/primitive.ts:104`) walks the approver list, calls `ensureUserDm(userId)` per approver, returns the first one that resolves. `ensureUserDm` looks up `user_dms` first; only on a miss does it call the platform's `openDM`. Aaron's `user_dms` row was Bot1's DM — that's what got returned. The function has no notion of "approval is *about* Bot2; prefer Bot2's DM if reachable."
+
+### 1.8 Hypothesis verdict
+
+The team-lead's three hypotheses:
+- (a) **Half-correct.** Wire path's MGA was never created; the approval handler's MGA *was* created with `sender_scope='known'`. Aaron, as approver, was auto-added to `agent_group_members` so the replay wouldn't bounce. So the wire flow eventually produced a working channel — but via the wrong code path.
+- (b) **Confirmed.** The bot2-DM `mg-…ogxhkj` was created by `routeInbound`'s auto-create, *not* by `wireDmToAgent`. There's a single MG per (channel_type, platform_id), so we don't have *duplicate* siblings — we have a `wireDmToAgent` that never inserted because `routeInbound` got there first.
+- (c) **Wrong.** Platform_id encoding `telegram:8757751201:1190596288` is correct (bot2 + Aaron). PR A's encoding is solid.
+
+Root cause: **the bot adapter goes live the moment the user clicks "Validate."** The wire button's only remaining job in the post-PR #67 flow is creating the MGA — but inbound traffic on a backlogged channel races it.
+
+---
+
+## 2. Architecture map
+
+### 2.1 platform_id encoding
+
+`<channel>:<botId>:<native>` (PR A landed pre-PR #67 B1). Per channel:
+- Telegram: `botId` is the bot's Telegram user id (positive int from `getMe`); `native` is the `chat_id`. For DMs `chat_id == userId`; for groups `chat_id` is a negative int.
+- Discord: `botId` is the application id; `native` is `@me:<botUserId>` for DMs or a guild-channel id for guilds.
+
+The bot dimension is what makes two Telegram bots' identical DM `chat_id`s resolve to distinct `messaging_groups` rows.
+
+### 2.2 Wire flow (UI → DB)
+
+User clicks "Validate & register bot" on `/claw/channels/new`:
+1. `POST /api/channels/{adapter}/register-bot` (B2) → validates token, persists `secrets` row `CHANNEL_BOT_TOKEN:<channel>:<botId>`, calls `registerBotAdapter`. **Adapter goes live now.**
+2. UI shows resolved identity, asks for agent group + (Telegram) operator userId.
+3. User clicks "Wire" → `POST /api/groups/:folder/wire-channel` → `wireDmToAgent(...)` → INSERT messaging_groups + messaging_group_agents, defaults `sender_scope='all'`, `ignored_message_policy='drop'`, `unknown_sender_policy='strict'`.
+
+Step 1 → 3 is **not atomic**. Anything that hits the polling loop between steps lands on an unwired channel.
+
+### 2.3 Inbound flow (router.ts)
+
+Adapter polling loop receives a message → `routeInbound(event)`:
+1. Look up MG by (channel_type, platform_id). If missing AND message is mention/DM, auto-create with `unknown_sender_policy='request_approval'` (router.ts:179, hardcoded).
+2. If `agentCount === 0`: record dropped_message, fire `channelRequestGate` (the registration approval), return.
+3. Else: `senderResolver` upserts `users` row, fan out to wirings. Each wiring evaluates `engage_mode`, `accessGate`, `senderScopeGate` independently. Engaged → write to session inbound DB + wake container. Not engaged but `accumulate` → write inbound with `trigger=0`. Else drop.
+
+### 2.4 Approval picking (`src/modules/approvals/primitive.ts`)
+
+- `pickApprover(agentGroupId)` returns ordered user ids: scoped admins → global admins → owners. For Aaron's install, owner-only.
+- `pickApprovalDelivery(approvers, originChannelType)` walks the list, prefers same-channel approvers, calls `ensureUserDm` to resolve a reachable DM. Returns the first hit. **No bot-level preference** — picks any cached or openable DM.
+
+### 2.5 Identity tables
+
+- `users(id, kind, display_name, created_at)` — id = `<channel>:<handle>` (e.g. `telegram:1190596288`). Upserted on first sender resolution.
+- `user_roles(user_id, role, agent_group_id, granted_by, granted_at)` — owner / admin (global if `agent_group_id IS NULL`, scoped otherwise).
+- `agent_group_members(user_id, agent_group_id, added_by, added_at)` — unprivileged-access gate; channel-approval handler auto-adds the triggering sender so the replay doesn't bounce on `sender_scope='known'`.
+- `user_dms(user_id, channel_type, messaging_group_id, resolved_at)` — DM cache. **One row per user per channel.** First-cached wins.
+
+### 2.6 unknown_sender_policy × sender_scope
+
+These are independent. `unknown_sender_policy` is on `messaging_groups`; `sender_scope` is on `messaging_group_agents`. Most install paths default both to the same posture (strict/all OR request_approval/known) but they drift in the auto-create + approval-handler combo: MG inherits `request_approval` (from router auto-create), MGA inherits `known` (from approval handler). Net effect: senders Aaron hasn't approved get bounced to a sender-approval cascade (`pending_sender_approvals`).
+
+### 2.7 Approval table zoo
+
+Three tables, three lifecycles:
+- `pending_channel_approvals` — channel-registration cards (PR #67 area). PK on `messaging_group_id`. Deleted on approve/reject.
+- `pending_sender_approvals` — sender-scope cards (when `sender_scope='known'` rejects an unknown sender). Different lifecycle, different module.
+- `approvals` — the modular approval primitive (paraclaw#11/#286). Used by self-mod, MCP, etc. Distinct from the channel/sender tables.
+
+The team-lead's prompt asks me to confirm `pending_channel_approvals` and `approvals` are distinct: **yes**, separate tables, separate code paths. Channel registration was deliberately not folded into the unified primitive (see `channel-approval.ts:1-38` header comment).
+
+---
+
+## 3. Critique
+
+### 3.1 The validate-spawns-the-bot UX is the load-bearing problem
+
+PR #67 B2's polish folded validate + register into one button click — for good reason (avoided doubled API quota on Telegram's getUpdates). But it converted "validate the token works" from a read-only action into a side-effecting one. The bot is *live and serving traffic* before the operator picks an agent group. A backlogged channel will race the wire.
+
+### 3.2 The approval cascade for self-wire is wrong
+
+The form *just* captured the operator's userId. The system has all the context it needs to know "Aaron is wiring his own bot to his own DM." Yet the inbound message gets treated as a stranger DM'ing an unwired channel — an approval card is built and delivered to that same operator, by a different bot, asking them to approve what they're already in the middle of doing.
+
+It's not just an annoyance; it's misleading. The card delivery via Bot1 implies "Bot1 owns this approval" or "this is a system-level event in Bot1's chat" — neither is true.
+
+### 3.3 The card-via-different-bot is mostly accidental
+
+`pickApprovalDelivery` tries to find any reachable DM. For a single-bot install this happens to be the right bot. For multi-bot, it's whichever bot's DM got cached first. In Aaron's case, this caused the surprising "Bot1 telling me about Bot2" UX. It's not principled; it's just what the cache returned.
+
+A principled answer: approval cards about Bot X should prefer delivery via Bot X if the approver is reachable there. For first-touch operators (no `user_dms` yet for that bot), fall back. For cross-bot scenarios where the approver isn't reachable on the new bot, the current behavior is fine.
+
+### 3.4 The race in `pending_channel_approvals` is real
+
+Three concurrent inbounds → three concurrent `requestChannelApproval` calls → unique-key collision. The current code logs ERROR and moves on, so user-visible impact is nil, but:
+- The error log misleads anyone debugging.
+- If the **first** insert fails for any reason (not a duplicate — say, a constraint or transient I/O), the others *would* have succeeded, but never reach INSERT because the dedup check was non-atomic.
+
+Atomic fix: `INSERT … ON CONFLICT DO NOTHING` and check `changes() > 0` to decide whether to deliver. Already cheap; just hasn't been done.
+
+### 3.5 The two MGA-default sets create a hidden invariant
+
+`wireDmToAgent` defaults: trusted (all/drop/strict). `channel-approval.ts` handler defaults: cautious (known/accumulate/request_approval). They're meant to model two different intents:
+- Operator proactively wired this bot to themselves → trust.
+- An admin approved a stranger's mention/DM after-the-fact → cautious.
+
+But which one applies depends on a milliseconds-level race that the operator can't observe. **The intent isn't legible from the data afterward** — `mga-…5i9dz9` looks identical in shape to a real "I approved a stranger" wire. The system can't recover the operator's actual intent, and neither can the operator looking back at the wirings list.
+
+### 3.6 Multi-bot model gaps surfaced by PR #67
+
+PR #67 B2 introduced the secrets-backed multi-bot scan (`spawnSecretsBackedBots`) that brings every `CHANNEL_BOT_TOKEN:<channel>:<botId>` secret live on boot. Combined with `register-bot` going live immediately on validate, **the system has no notion of a "registered but inert" bot.** Once registered, a bot serves traffic forever. There's no "I want to test this token but not yet route messages" state.
+
+---
+
+## 4. Design proposals
+
+### A. Defer adapter spawn until after wire (atomic register+wire)
+
+**Sketch.** Split `/api/channels/{adapter}/register-bot` into two phases. Phase 1 = validate + persist secret + return identity, **don't bring the adapter live**. Phase 2 = "wire" endpoint creates MGA *and* spawns the adapter atomically. `spawnSecretsBackedBots()` at boot only spawns secrets that have at least one wiring; orphaned secrets stay inert.
+
+**Data model.** No schema changes. New invariant: an adapter is live only when a wiring exists. Implemented in `spawnSecretsBackedBots` (skip orphans) + in the wire endpoint (start adapter on success).
+
+**UX.** The form's "Validate" returns identity but the bot stays cold. "Wire" is the action that brings it live. Backlogged DMs land on a wired channel — engaged immediately, no approval cascade. Operators wanting to "just verify the token works" still get the validation result without committing to a live bot.
+
+**Solves.** The race entirely. The surprise-approval-cascade for self-wire entirely. Makes orphan-secret cleanup (a future tablet on PR #67) trivial.
+
+**Doesn't solve.** Approval card delivery via wrong bot for *post-wire* registrations (different operator, after wire is committed). That's still routed via `pickApprovalDelivery` and still picks the cached DM.
+
+**Migration.** Modest. Update `register-bot` to skip `registerBotAdapter`. Update `wireDmToAgent` (or a new wrapper) to call `registerBotAdapter` after MGA insert. Update `spawnSecretsBackedBots` to JOIN through messaging_groups+messaging_group_agents. Delete the existing race-doc-update from PR #67's body; it ceases to be a thing.
+
+**Risk.** A user who validates and never wires leaves an orphan secret. We need a sweep or a UI prompt. (Discord/Telegram tokens don't expire automatically, so the orphan persists — but it's inert.) Lower-risk than current "always live" semantics.
+
+### B. Operator-self-wire trust hint
+
+**Sketch.** When `/channels/new` form is submitted, persist a short-lived "trusted setup hint" naming `(channel_type, bot_id, operator_user_id, expires_at)`. The router checks for a matching hint when handling the first inbound on an unwired bot's DM. If matched, skip `channelRequestGate` and immediately wire with `wireDmToAgent`'s trusted defaults (all/drop/strict). Hint expires on use or after 10 minutes.
+
+**Data model.** New table `pending_channel_setup_hints (channel_type, bot_id, operator_user_id, expires_at)` or in-memory map (cheaper, lost on restart — fine because hints are 10-minute things).
+
+**UX.** Same form flow as today. The first DM Aaron sends to Bot2 just works; no card. Subsequent DMs from anyone else go through the normal approval path.
+
+**Solves.** The "I just wired this, the next message from me should just work" UX. Preserves the polling-eager validate UX.
+
+**Doesn't solve.** The race is still there for *other* senders (someone else DMs the bot in the validate-to-wire window — they get the approval cascade, which is correct behavior anyway). Card-via-wrong-bot for post-wire approvals is unaddressed.
+
+**Migration.** Small. Add the table or in-memory map, hook into the form submit, hook into router.ts:218 (channel-request gate dispatch) to consult the hint first. Default hint TTL = 10 min, configurable.
+
+**Risk.** Hint table needs cleanup (TTL sweep). In-memory variant is lost on restart, which is correct behavior — operators who don't wire within 10 min are starting over anyway.
+
+### C. Approval delivery follows the bot in question
+
+**Sketch.** Extend `pickApprovalDelivery` to take an optional `preferredBotId`. For channel-registration approvals, pass the bot id of the channel being registered. The function tries to resolve a `user_dms` row for the (approver, channel_type, bot_id) combination; on miss, falls back to current behavior.
+
+**Data model.** Existing `user_dms` is keyed `(user_id, channel_type)` — only one DM per user-channel. Need to extend to `(user_id, channel_type, bot_id)` to differentiate. Migration: ALTER TABLE adds `bot_id TEXT` column, backfill from `messaging_groups.platform_id` (parse second segment). Make `(user_id, channel_type, bot_id)` the new PK; the old `(user_id, channel_type)` constraint goes away.
+
+**UX.** Approval cards land in the right bot. Less confusing for the operator. For first-touch (no cached DM via the new bot), still falls back so functionality doesn't break.
+
+**Solves.** The cross-bot card delivery confusion. Doesn't solve the surprise-approval-cascade for self-wire.
+
+**Migration.** Schema change is non-trivial but mechanical. Code change is one extra arg + a fallback.
+
+**Risk.** Existing `user_dms` rows need a sane bot_id backfill. For Aaron's row (bot1's MG), bot_id is recoverable. For older rows from before PR A's bot dimension, bot_id is `null` and matches the legacy "single-bot per channel" assumption — needs care.
+
+### Recommendation
+
+**A + B together.** A removes the race; B handles the case where the operator wants to test by DM'ing in the validate-but-not-yet-wired window (with A alone, they'd have to wire first). Together: validate is read-only, the form's wire button is the single commit point, and there's a short trust window for the operator to test from their own client.
+
+C is a smaller cleanup that's worth doing independently — it makes the surface principled even if A+B aren't shipped together.
+
+---
+
+## 5. Open questions for Aaron
+
+These are decisions the research can't make alone:
+
+1. **Trust the form's captured userId for self-wire bypass?** Proposal B trusts that the operator filling out `/channels/new` and entering their own Telegram userId is the same person as the one DM'ing the bot. If yes, the hint-based bypass is fine. If no, we need a stronger binding (e.g., the form generates a one-time token the operator includes in their first DM).
+
+2. **Should an inert (registered but unwired) secret persist across restarts?** Proposal A has `spawnSecretsBackedBots()` skip orphans. That means a validated-but-not-wired bot doesn't survive a restart. Alternative: keep the secret, log a warning at boot listing orphans, let the operator decide via a UI sweep. Open: which trade-off do you prefer?
+
+3. **Should approval cards always come from the bot in question?** Proposal C says yes-when-possible. Edge: an admin approving a registration for a bot they've never DM'd — the approval has to come from somewhere. Current fallback (any cached DM) is the simplest answer; alternative is "the bot DMs the admin first" which is more invasive.
+
+4. **What's the right MGA default for "operator approved a stranger's DM via card"?** Today: `sender_scope='known'`, `ignored_message_policy='accumulate'`. The reasoning (only let already-known users engage; stash others' messages until they're approved) is defensive. But it surprised Aaron when he was the "stranger." For *self*-approval (operator approving their own DM), should the defaults flip to `all`/`drop`?
+
+5. **How visible should the post-wire wiring shape be?** Right now the channels list shows the wiring exists but not its `sender_scope`/`ignored_message_policy`/`unknown_sender_policy`. If those shape the engagement profile materially, shouldn't they be surfaced in the channel-edit UI? (This is orthogonal to the proposals above but adjacent.)
+
+6. **Does PR #72 ship as-is, or wait for one of these proposals?** PR #72 is correct for the multi-bot infrastructure. The UX bugs above exist with or without it. The argument for shipping #72 first: the infrastructure is sound, and the design fixes are about the *flow*, not the *capability*. The argument against: shipping the multi-bot path before fixing the surprise-cascade UX means more operators hit the surprise.
+
+---
+
+## Appendix: file references
+
+- Router auto-create policy: `src/router.ts:179`
+- Channel-request gate dispatch: `src/router.ts:218`
+- Wire-flow defaults (trusted): `src/web/wire-channel.ts:158-172`
+- Approval-flow defaults (cautious): `src/modules/permissions/index.ts:344-355`
+- Approval delivery picker: `src/modules/approvals/primitive.ts:104-120`
+- Channel-registration handler: `src/modules/permissions/channel-approval.ts`
+- pending_channel_approvals schema: `src/db/migrations/012-channel-registration.ts`
+- B2 register-bot endpoint: `src/web/server.ts` (POST `/api/channels/{adapter}/register-bot`)
+- B2 secrets-backed scan: `src/channels/channel-registry.ts` (`spawnSecretsBackedBots`)
+- Live install evidence: `~/.parachute/claw/paraclaw.db`, `~/.parachute/claw/logs/claw.log`

package/docs/design/2026-05-02-channel-policy-and-approval-routing.md

@@ -0,0 +1,250 @@
+# Channel policy + approval routing
+
+**Status:** Design proposal · 2026-05-02 · paraclaw#67 follow-up
+
+Three threads surfaced once the multi-bot wiring landed and Aaron started using two Telegram bots side by side:
+
+1. **Approval delivery doesn't follow the bot in question.** TechneRobot group-chat approval cards arrived through UnforcedAGI's DM — wrong bot, wrong mental model.
+2. **Per-channel policy is buried.** `unknown_sender_policy` (per-MG) and `engage_mode` / `sender_scope` / `ignored_message_policy` (per-MGA) are real, working knobs, but only the per-MGA three are surfaced in the UI. The per-MG one isn't editable anywhere outside the trust-hint code path. There's no "always allow this group" toggle, no "respond only to mentions" toggle on a wired chat.
+3. **NanoClaw heritage.** Some of these knobs predate paraclaw; some are paraclaw-era. Reusing NanoClaw shapes where they exist (instead of re-deriving) saves churn and keeps the user-facing language stable.
+
+This doc proposes how to fix all three together. No impl until Aaron reads it.
+
+## 1. Current state — what exists today
+
+### 1a. The four MGA knobs (paraclaw migration 010, replaced legacy `trigger_rules` JSON)
+
+`messaging_group_agents` carries four orthogonal columns governing per-wiring behavior. Migration 010 (`src/db/migrations/010-engage-modes.ts`) split them out of the legacy `trigger_rules` (opaque JSON) + `response_scope` (conflated axis) shape. Behavior at runtime, traced through `src/router.ts`:
+
+| Column | Values | What the router actually does | Code |
+|---|---|---|---|
+| `engage_mode` | `pattern` \| `mention` \| `mention-sticky` | `pattern`+regex test on text (`'.'` sentinel = always); `mention` requires `event.message.isMention`; `mention-sticky` accepts mention OR an existing per-thread session for this `(agent, mg, thread)` | `evaluateEngage` at `src/router.ts:402-433` |
+| `engage_pattern` | regex string, nullable | Used only when `engage_mode='pattern'`. Bad regex fails open. | `src/router.ts:411-418` |
+| `sender_scope` | `all` \| `known` | `all` = no-op; `known` = `canAccessAgentGroup(userId, agent_group_id)` must allow. Enforced via the `senderScopeGate` hook the permissions module registers. | `src/modules/permissions/index.ts:175-183` |
+| `ignored_message_policy` | `drop` \| `accumulate` | Branch on the *non-engaging* path: `drop` = silently skip; `accumulate` = still write the inbound row to the agent's session DB with `trigger=0`, so context is available next time it does engage | `src/router.ts:355-358` |
+
+Note the API surface (`src/web/routes/channels.ts:8-22`) uses different enum names that translate at the route boundary — `engageMode='all'` collapses to DB `engage_mode='pattern'` + `engage_pattern='.'`; `senderScope='allowlist'` ↔ `sender_scope='known'`; `ignoredMessagePolicy='silent'` ↔ `ignored_message_policy='accumulate'`. The UI sees the API names. The DB keeps the original ones. The translator is lossy on the `mention` ↔ `mention-sticky` distinction (renders both as `mention`); the `apiToDbPatch` at `src/web/routes/channels.ts:97-127` carefully preserves sticky on round-trip.
+
+### 1b. The MG-level knob
+
+`messaging_groups.unknown_sender_policy` is a single column with three values, set at MG creation (default `'strict'`):
+
+| Value | Router behavior | Source |
+|---|---|---|
+| `strict` | Drop messages from senders the access gate refuses; record in `dropped_messages` (paraclaw default). | `src/modules/permissions/index.ts:106-115` |
+| `request_approval` | Drop, record, AND fire a sender-approval card to admins. Used by the unwired-channel auto-set flow at `src/router.ts:183`. | `src/modules/permissions/index.ts:117-140` |
+| `public` | Skip the access gate entirely — anyone in the chat can engage the agent (subject to per-MGA `sender_scope`). | `src/modules/permissions/index.ts:147-151` |
+
+This is the per-MG "always allow" knob Aaron's asking for — it already exists end-to-end. What's missing is a UI surface to flip it.
+
+### 1c. UI surfaces today
+
+- `web/ui/src/routes/ChannelsList.tsx` — per-MGA inline editor. Edits `engageMode`, `engagePattern`, `senderScope`, `ignoredMessagePolicy`, `priority`. **Does not edit `unknown_sender_policy`.**
+- `web/ui/src/routes/WireChannelPage.tsx` — wire-creation only. Sets `unknown_sender_policy='strict'` on new MGs (see `src/web/wire-channel.ts:136`). No per-MG detail page.
+- `web/ui/src/routes/GroupDetail.tsx` — agent-group detail. Vault attachments + activity. No channel-policy surface.
+- Approval card itself — Approve / Ignore (or Approve / Reject) buttons only. No "Approve & always allow this group" shortcut.
+
+### 1d. Approval routing today
+
+`pickApprovalDelivery` in `src/modules/approvals/primitive.ts:104-120`:
+
+```ts
+if (originChannelType) {
+  for (const userId of approvers) {
+    if (channelTypeOf(userId) !== originChannelType) continue;
+    const mg = await ensureUserDm(userId);
+    if (mg) return { userId, messagingGroup: mg };
+  }
+}
+for (const userId of approvers) {
+  const mg = await ensureUserDm(userId);
+  if (mg) return { userId, messagingGroup: mg };
+}
+```
+
+`ensureUserDm` (`src/modules/permissions/user-dm.ts:52-112`) is keyed `(user_id, channel_type)` against `user_dms` — so for an operator with two Telegram bots, this **always returns whichever bot's DM was resolved first**. Aaron's live `user_dms` has exactly one row, pinned to `mg-1777352749546-e4z1rv` (the UnforcedAGI Aaron-DM). Every TechneRobot approval card delivers via UnforcedAGI. That's the bug.
+
+### 1e. Aaron's live state (ground truth, queried 2026-05-02)
+
+Four telegram MGs, three wired:
+
+| MG | Bot | Chat | `unknown_sender_policy` | MGA `engage_mode` / `engage_pattern` | `sender_scope` | `ignored_message_policy` |
+|---|---|---|---|---|---|---|
+| `mg-…e4z1rv` | UnforcedAGI (8792…425) | Aaron DM (1190…288) | `strict` | `pattern` / `.` | `all` | `drop` |
+| `mg-…ihfgeq` | UnforcedAGI | group (-1003…645) | `request_approval` | *(unwired)* | — | — |
+| `mg-…ogxhkj` | TechneRobot (8757…201) | Aaron DM (1190…288) | `request_approval` | `pattern` / `.` | `known` | `accumulate` |
+| `mg-…90uhi5` | TechneRobot | group (-1002…962) | `request_approval` | `pattern` / `.` | `known` | `accumulate` |
+
+`user_dms` has one row: Aaron → telegram → UnforcedAGI Aaron-DM. So every approval today, regardless of origin bot, goes through UnforcedAGI.
+
+## 2. NanoClaw heritage
+
+Migration 010 explicitly back-compats from NanoClaw's pre-rebirth `trigger_rules` JSON + `response_scope` enum. The five-knob model in section 1a is paraclaw's split of NanoClaw's two — same axis count, cleaner names, no JSON parsing in the hot path. The default values match NanoClaw's: `requiresTrigger=true` ↔ `engage_mode='mention'`; `response_scope='allowlisted'` ↔ `sender_scope='known'`. New users see paraclaw shapes; legacy installs migrated forward.
+
+`unknown_sender_policy` is paraclaw-era — there's no equivalent in NanoClaw migration history. NanoClaw treated unknown senders the same way it treated everyone else (`response_scope` did all the gating). Paraclaw added the MG-level dimension specifically to support `request_approval` (the unwired-channel cascade) without overloading per-MGA `sender_scope`. So the *concept* is paraclaw's; the *axis split* mimics NanoClaw's design instinct (orthogonal columns over JSON blobs).
+
+`user_dms` is also paraclaw-era. NanoClaw single-bot setups never needed bot disambiguation in DM caching — there was only one bot per channel. The `(user_id, channel_type)` PK is a NanoClaw-shaped assumption that paraclaw inherited and never updated when multi-bot landed.
+
+**Implication for Proposal C:** there is no NanoClaw shape to defer to. We're inventing the multi-bot DM cache from scratch. That's fine — the bot dimension is genuinely new.
+
+**Implication for the policy UI:** NanoClaw shipped a CLI-driven config model; there was no per-channel settings page on the host UI. Paraclaw added the web UI and inherited NanoClaw's enum vocabulary, then split it. So we're not deviating from a NanoClaw UI pattern — we're filling a gap that was never built.
+
+## 3. Problem statement (the three asks)
+
+1. **Approval routing follows the bot, not the operator-channel pair.** When an approval originates from an inbound on bot X, the card should reach the approver via bot X if at all possible, falling back gracefully when the approver hasn't DM'd that bot yet.
+2. **Per-MG / per-MGA policy is editable from a single intuitive surface.** Operator should be able to flip "always allow this group" (per-MG) and "respond only to mentions" (per-MGA) without remembering enum names or visiting two pages.
+3. **The approval card itself carries quick-actions** so deciding "yes, and trust this chat going forward" is one click, not a click-then-navigate.
+
+## 4. Proposals
+
+### 4a. Proposal C — bot-aware approval delivery
+
+**Shape: extend `user_dms` PK to `(user_id, channel_type, bot_id)`.** Drop the row when `bot_id` is empty / null only for channel types that don't have a bot dimension (none today, but the schema must allow it for future channels like email). Migration:
+
+```sql
+ALTER TABLE user_dms RENAME TO user_dms_legacy;
+CREATE TABLE user_dms (
+  user_id            TEXT NOT NULL REFERENCES users(id),
+  channel_type       TEXT NOT NULL,
+  bot_id             TEXT NOT NULL DEFAULT '',
+  messaging_group_id TEXT NOT NULL REFERENCES messaging_groups(id),
+  resolved_at        TEXT NOT NULL,
+  PRIMARY KEY (user_id, channel_type, bot_id)
+);
+INSERT INTO user_dms (user_id, channel_type, bot_id, messaging_group_id, resolved_at)
+SELECT
+  u.user_id,
+  u.channel_type,
+  COALESCE(
+    -- Decode bot_id from the cached MG's v2 platform_id (slot 1 after channel:).
+    SUBSTR(mg.platform_id, LENGTH(mg.channel_type) + 2,
+           INSTR(SUBSTR(mg.platform_id, LENGTH(mg.channel_type) + 2), ':') - 1),
+    ''
+  ) AS bot_id,
+  u.messaging_group_id,
+  u.resolved_at
+FROM user_dms_legacy u
+JOIN messaging_groups mg ON mg.id = u.messaging_group_id;
+DROP TABLE user_dms_legacy;
+```
+
+Aaron's existing row would migrate to `bot_id='8792496425'` (UnforcedAGI). TechneRobot DMs become uncached on day one — `ensureUserDm(userId, botId='8757751201')` returns null on first lookup, falls through to the resolver, and re-caches.
+
+**Resolver change:** `ensureUserDm` takes an optional `botId` parameter. When provided, the cache key includes it, and on miss the resolver picks the live adapter for `(channelType, botId)` (we already have `getChannelAdapterByBotId` from PR A). When omitted, behavior is the legacy "any bot" — preserved for callers that don't care which bot delivers.
+
+**Routing change:** `pickApprovalDelivery` takes an optional `originBotId`. The signature becomes:
+
+```ts
+export async function pickApprovalDelivery(
+  approvers: string[],
+  originChannelType: string,
+  originBotId: string | null,
+): Promise<{ userId: string; messagingGroup: MessagingGroup } | null>;
+```
+
+Resolution order (preserving the channel-tie-break that's already there):
+
+1. Same channel type AND `ensureUserDm(userId, originBotId)` resolves — return that bot's DM.
+2. Same channel type AND `ensureUserDm(userId, /* any */)` resolves — return whatever bot (fallback).
+3. Different channel type AND `ensureUserDm(userId, /* any */)` resolves — cross-channel fallback (existing behavior).
+4. None — `null` (existing behavior).
+
+Step 2 is the load-bearing fallback Aaron asked about: "what if the approver hasn't DM'd this bot yet?" — they get the card on whatever bot they have DM'd, with no extra surface. The card body should still name the origin bot ("New DM to **TechneRobot** in chat XYZ") so the approver isn't confused about which bot wired up. That's a card-rendering tweak in the modules that build cards (`channel-approval.ts:115-122`, `sender-approval.ts`).
+
+**Default for "no DM with anyone":** unchanged. `pickApprovalDelivery` returns null, the requesting module logs and aborts. Static admin-notification channels are out of scope for this doc — would be a separate dimension on the install (`alerts:` channel concept).
+
+**Why this shape over alternatives:**
+
+- *Separate `(user_id, channel_type, bot_id) → mg_id` table:* same row count, less migration churn (no rename), but adds a new table the rest of the code has to learn about. The PK extension is honest about what changed.
+- *Compute on the fly from `messaging_groups`:* you'd resolve "what's user X's DM with bot Y" by scanning MGs. Plausible — slot1 of `platform_id` IS the bot_id under v2 — but it loses the resolver semantics (you can't cache a *failure* to find the DM; every lookup re-attempts `openDM`). The cache is load-bearing for Discord rate limits.
+
+### 4b. Per-MG detail page (the granular policy UI)
+
+**Route shape: `/claw/channels/<mga-id>` for the per-wiring surface, `/claw/channels/<mg-id>` for the per-MG surface.** Disambiguate by id prefix (`mg-` vs `mga-`) — both are routable from the existing channels list with a single click.
+
+Why two routes and not one tabbed page: the MG-level knob (`unknown_sender_policy`) is independent of any one wiring; a user can have multiple MGAs on the same MG and the policy applies to all of them. Mounting both on one MGA-keyed URL would mislead.
+
+**`/claw/channels/<mg-id>` (per-MG):**
+
+```
+[ telegram ]   ←  channel-type pill
+TechneRobot   ←  bot.name
+group: Techne Friends · -1002245300962
+
+Who can engage?
+  ◉ Strict — only members of this agent group can talk to it
+  ◯ Always allow — anyone in this chat can engage
+  ◯ Approval-gated — first message from a new sender requires admin OK
+
+[ Wirings to this group ]
+   • Techne (priority 0) — engage on @mention; senders: known; ignored: accumulate    [ Edit ]
+
+[ Save ]    [ Cancel ]
+```
+
+Three radio choices map directly to `strict | public | request_approval`. Copy is operator-facing — no enum names. The wirings list links each MGA to its detail page.
+
+**`/claw/channels/<mga-id>` (per-MGA, replaces today's inline ChannelsList editor):**
+
+```
+[ telegram ]
+TechneRobot → Techne agent group
+
+When does it engage?
+  ◯ Always — every message in this chat
+  ◉ Mentions — when @TechneRobot is tagged
+  ◯ Pattern — text matches a regex:  [____________]
+
+Who can talk to it?
+  ◯ Anyone in the chat
+  ◉ Members only — owner / admin / explicit member
+
+What about messages it ignores?
+  ◯ Drop — not seen, not stored
+  ◉ Accumulate — stored for context, no reply
+
+Priority [0]   ← higher wins when multiple wirings could match
+
+[ Save ]    [ Remove wiring ]
+```
+
+Same fields as today's inline editor, just promoted to a route so the "Edit" button can carry richer copy and there's room to display read-only metadata (created at, agent group folder, MG link).
+
+The existing `ChannelsList` collapses to a list of MGAs that link to per-MGA detail. The per-MGA detail page links up to the per-MG page via a "Group settings →" pill at the top.
+
+### 4c. Quick-action on the approval card
+
+Replace the two-button card with three buttons on cards that originate from `request_approval` policy:
+
+- **Approve** — current behavior (admit sender + replay).
+- **Approve & always allow** — admit sender, AND flip the MG's `unknown_sender_policy` to `public`. Tracked in payload, executed by the response handler.
+- **Reject** — current behavior.
+
+Three buttons fit comfortably in Telegram and Discord chat-card layouts (they accept arbitrary button rows). The rendering happens in `chat-sdk-bridge` via `ask_question`; we extend the option list and the response handler in `src/modules/permissions/index.ts:handleSenderApprovalResponse` to interpret the new value.
+
+**Out of scope for this doc:** mention-only quick-action on the card (it's per-MGA, requires picking which MGA to update — adds card complexity). Operators who want that can navigate to per-MGA settings; it's a one-tap path from the card's chat link.
+
+## 5. Migration notes
+
+- **Proposal C:** see SQL above. One migration file (`026-user-dms-bot-id.ts`). Backfill is decode-from-platform_id — works because v2 platform_ids are guaranteed by paraclaw#67 PR A. Rollback is "drop the column"; no data loss because the legacy keying is reconstructible (any bot caches just collapse).
+- **Per-MG / per-MGA UI:** no schema change. Routes added, list view trimmed, two new components.
+- **Quick-actions on card:** no schema change. New option `approve_and_allow` in the sender-approval card payload; handler dispatches on it.
+
+## 6. Open questions for Aaron
+
+1. **Card copy when origin bot ≠ delivery bot.** When step-2 fallback fires (TechneRobot approval delivered via UnforcedAGI because no TechneRobot↔operator DM exists yet), the card needs to clearly say "this is about **TechneRobot** in *Techne Friends*." Should the bot-name come from the agent group name, the bot's display_name, or the platform-level bot username? My instinct: bot username (most identifiable to a Telegram operator who knows `@TechneRobot`).
+
+2. **`Approve & always allow` scope.** Does that flip apply to the *current MG only* (per-chat trust), or also auto-add the sender as a member? The pure interpretation is MG-only; the convenient interpretation is both. I lean MG-only — admitting the sender is what regular Approve already does, and bundling them feels like overreach.
+
+3. **Mention-only on the card.** Section 4c skipped this. Do you want a fourth button on cards, or are operators OK navigating to per-MGA settings to flip mention mode? Three buttons is comfortable; four starts to crowd.
+
+4. **Two routes vs tabbed.** I went with `/channels/<mg-id>` and `/channels/<mga-id>`. If you'd rather have `/channels/<mga-id>` as the only route and surface MG settings as a collapsed accordion, that simplifies routing at the cost of nesting unrelated knobs.
+
+## Phasing for impl (after this doc is signed off)
+
+1. **PR 1: Proposal C migration + resolver + routing change.** Backwards-compatible API (botId optional). One DB migration, two function signatures. Tests: bot-aware ensureUserDm, fallback chain in pickApprovalDelivery.
+2. **PR 2: per-MGA detail page.** Route + component. No schema change. Replaces inline editor in ChannelsList.
+3. **PR 3: per-MG detail page + UnknownSenderPolicy editor.** Route + component + new PATCH on `/api/channels/mg/:id`.
+4. **PR 4: Quick-action card.** Schema-free. Card option list grows, handler grows, tests for each branch.
+
+Each PR is independently shippable; PR 1 unblocks the routing fix Aaron asked about first; PRs 2-4 are pure UX polish over the working data model.