@openparachute/agent 0.1.0

package/src/db/messaging-groups.ts

@@ -0,0 +1,252 @@
+import type { MessagingGroup, MessagingGroupAgent } from '../types.js';
+// Transitional tier violation: core imports from optional agent-to-agent module.
+// `createMessagingGroupAgent` auto-creates a destination row on wiring — the
+// two concerns are currently bundled. When agent-to-agent isn't installed,
+// the table doesn't exist and this import chain remains dormant because
+// `createMessagingGroupAgent` is only called from setup/admin paths that
+// also only run when wiring channels to agents (which implicitly requires
+// agent-to-agent for the destination ACL to mean anything). A cleaner split
+// (or making the destination side effect module-owned) is tracked in the
+// refactor plan.
+import {
+  createDestination,
+  getDestinationByName,
+  getDestinationByTarget,
+  normalizeName,
+} from '../modules/agent-to-agent/db/agent-destinations.js';
+import { getDb, hasTable } from './connection.js';
+
+// ── Messaging Groups ──
+
+export function createMessagingGroup(group: MessagingGroup): void {
+  getDb()
+    .prepare(
+      `INSERT INTO messaging_groups (id, channel_type, platform_id, name, is_group, unknown_sender_policy, created_at)
+       VALUES (@id, @channel_type, @platform_id, @name, @is_group, @unknown_sender_policy, @created_at)`,
+    )
+    .run(group);
+}
+
+export function getMessagingGroup(id: string): MessagingGroup | undefined {
+  return getDb().prepare('SELECT * FROM messaging_groups WHERE id = ?').get(id) as MessagingGroup | undefined;
+}
+
+export function getMessagingGroupByPlatform(channelType: string, platformId: string): MessagingGroup | undefined {
+  return getDb()
+    .prepare('SELECT * FROM messaging_groups WHERE channel_type = ? AND platform_id = ?')
+    .get(channelType, platformId) as MessagingGroup | undefined;
+}
+
+/**
+ * Combined lookup for the router's fast-drop path. Returns the messaging
+ * group (if it exists) and a count of wired agents in one query — lets
+ * `routeInbound` short-circuit messages for unwired / unknown channels
+ * with a single DB read instead of four (mg lookup, sender upsert, agents
+ * lookup, dropped_messages insert).
+ *
+ * Returns `null` when no messaging_groups row exists for this channel.
+ * Returns `{ mg, agentCount: 0 }` when the row exists but has no wired
+ * agents. Uses the `UNIQUE(channel_type, platform_id)` index plus the
+ * `UNIQUE(messaging_group_id, agent_group_id)` index for the JOIN — both
+ * covered by existing SQLite auto-indexes from the UNIQUE constraints.
+ */
+export function getMessagingGroupWithAgentCount(
+  channelType: string,
+  platformId: string,
+): { mg: MessagingGroup; agentCount: number } | null {
+  const row = getDb()
+    .prepare(
+      `SELECT mg.*, COUNT(mga.id) AS agent_count
+         FROM messaging_groups mg
+    LEFT JOIN messaging_group_agents mga ON mga.messaging_group_id = mg.id
+        WHERE mg.channel_type = ? AND mg.platform_id = ?
+     GROUP BY mg.id`,
+    )
+    .get(channelType, platformId) as (MessagingGroup & { agent_count: number }) | undefined;
+  if (!row) return null;
+  const { agent_count, ...mg } = row;
+  return { mg: mg as MessagingGroup, agentCount: agent_count };
+}
+
+export function getAllMessagingGroups(): MessagingGroup[] {
+  return getDb().prepare('SELECT * FROM messaging_groups ORDER BY name').all() as MessagingGroup[];
+}
+
+export function getMessagingGroupsByChannel(channelType: string): MessagingGroup[] {
+  return getDb().prepare('SELECT * FROM messaging_groups WHERE channel_type = ?').all(channelType) as MessagingGroup[];
+}
+
+export function updateMessagingGroup(
+  id: string,
+  updates: Partial<Pick<MessagingGroup, 'name' | 'is_group' | 'unknown_sender_policy'>>,
+): void {
+  const fields: string[] = [];
+  const values: Record<string, unknown> = { id };
+
+  for (const [key, value] of Object.entries(updates)) {
+    if (value !== undefined) {
+      fields.push(`${key} = @${key}`);
+      values[key] = value;
+    }
+  }
+  if (fields.length === 0) return;
+
+  getDb()
+    .prepare(`UPDATE messaging_groups SET ${fields.join(', ')} WHERE id = @id`)
+    .run(values);
+}
+
+export function deleteMessagingGroup(id: string): void {
+  getDb().prepare('DELETE FROM messaging_groups WHERE id = ?').run(id);
+}
+
+/**
+ * Mark a messaging group as denied by the owner (channel-registration flow).
+ * Future mentions on this channel silently drop until an admin explicitly
+ * wires it via `createMessagingGroupAgent`, which implicitly clears the
+ * denied state by making `agentCount > 0` — the router's denied-channel
+ * check sits on the `agentCount === 0` branch.
+ *
+ * Passing null unsets the flag (used by tests or a future "unblock channel"
+ * admin command).
+ */
+export function setMessagingGroupDeniedAt(id: string, deniedAt: string | null): void {
+  getDb().prepare('UPDATE messaging_groups SET denied_at = ? WHERE id = ?').run(deniedAt, id);
+}
+
+// ── Messaging Group Agents ──
+
+/**
+ * Wire a messaging group to an agent group. Also auto-creates the matching
+ * `agent_destinations` row so the agent can deliver to this chat as a
+ * target, not just reply to the origin. Without this, routing to chats that
+ * aren't the session's origin (agent-shared sessions, cross-channel sends)
+ * would require an operator to hand-insert destination rows every time.
+ *
+ * The destination row is skipped if one already exists for the same target,
+ * so re-wiring is a no-op. The local_name uses the messaging group's `name`
+ * field when set, falling back to `${channel_type}-${mg_id prefix}`, with
+ * a numeric suffix to break collisions within the agent's namespace. This
+ * mirrors the backfill logic in migration 004.
+ */
+export function createMessagingGroupAgent(mga: MessagingGroupAgent): void {
+  getDb()
+    .prepare(
+      `INSERT INTO messaging_group_agents (
+         id, messaging_group_id, agent_group_id,
+         engage_mode, engage_pattern, sender_scope, ignored_message_policy,
+         session_mode, priority, created_at
+       )
+       VALUES (
+         @id, @messaging_group_id, @agent_group_id,
+         @engage_mode, @engage_pattern, @sender_scope, @ignored_message_policy,
+         @session_mode, @priority, @created_at
+       )`,
+    )
+    .run(mga);
+
+  // Auto-create an agent_destinations row so delivery's ACL doesn't block
+  // outbound messages that target this chat. Guarded: when the agent-to-agent
+  // module isn't installed the table doesn't exist — skip silently. Without
+  // the module, the ACL check in delivery is also skipped (same guard), so
+  // channel sends still work.
+  //
+  // ⚠️  DESTINATION PROJECTION NOTE: this function only writes the central
+  // `agent_destinations` row. It does NOT project into any running
+  // agent's session inbound.db (see top-of-file invariant in
+  // src/modules/agent-to-agent/db/agent-destinations.ts). In practice this
+  // is fine because the only real callers are one-shot setup scripts
+  // (setup/register.ts, scripts/init-first-agent.ts, /manage-channels
+  // skill) that run in a separate process from the host. Any already-
+  // running container for `mga.agent_group_id` will keep serving the
+  // stale projection until its next wake (idle timeout or next inbound
+  // message) at which point spawnContainer's writeDestinations call
+  // refreshes from central. If you call this from code that runs INSIDE
+  // the host process and need the refresh to happen immediately,
+  // explicitly call the module's `writeDestinations(mga.agent_group_id,
+  // <sessionId>)` afterwards.
+  if (!hasTable(getDb(), 'agent_destinations')) return;
+
+  const existing = getDestinationByTarget(mga.agent_group_id, 'channel', mga.messaging_group_id);
+  if (existing) return;
+
+  const mg = getMessagingGroup(mga.messaging_group_id);
+  if (!mg) return;
+
+  const base = normalizeName(mg.name || `${mg.channel_type}-${mga.messaging_group_id.slice(0, 8)}`);
+  let localName = base;
+  let suffix = 2;
+  while (getDestinationByName(mga.agent_group_id, localName)) {
+    localName = `${base}-${suffix}`;
+    suffix++;
+  }
+
+  createDestination({
+    agent_group_id: mga.agent_group_id,
+    local_name: localName,
+    target_type: 'channel',
+    target_id: mga.messaging_group_id,
+    created_at: mga.created_at,
+  });
+}
+
+export function getMessagingGroupAgents(messagingGroupId: string): MessagingGroupAgent[] {
+  return getDb()
+    .prepare('SELECT * FROM messaging_group_agents WHERE messaging_group_id = ? ORDER BY priority DESC')
+    .all(messagingGroupId) as MessagingGroupAgent[];
+}
+
+export function getMessagingGroupAgentByPair(
+  messagingGroupId: string,
+  agentGroupId: string,
+): MessagingGroupAgent | undefined {
+  return getDb()
+    .prepare('SELECT * FROM messaging_group_agents WHERE messaging_group_id = ? AND agent_group_id = ?')
+    .get(messagingGroupId, agentGroupId) as MessagingGroupAgent | undefined;
+}
+
+export function getMessagingGroupAgent(id: string): MessagingGroupAgent | undefined {
+  return getDb().prepare('SELECT * FROM messaging_group_agents WHERE id = ?').get(id) as
+    | MessagingGroupAgent
+    | undefined;
+}
+
+export function updateMessagingGroupAgent(
+  id: string,
+  updates: Partial<
+    Pick<
+      MessagingGroupAgent,
+      'engage_mode' | 'engage_pattern' | 'sender_scope' | 'ignored_message_policy' | 'session_mode' | 'priority'
+    >
+  >,
+): void {
+  const fields: string[] = [];
+  const values: Record<string, unknown> = { id };
+
+  for (const [key, value] of Object.entries(updates)) {
+    if (value !== undefined) {
+      fields.push(`${key} = @${key}`);
+      values[key] = value;
+    }
+  }
+  if (fields.length === 0) return;
+
+  getDb()
+    .prepare(`UPDATE messaging_group_agents SET ${fields.join(', ')} WHERE id = @id`)
+    .run(values);
+}
+
+export function deleteMessagingGroupAgent(id: string): void {
+  getDb().prepare('DELETE FROM messaging_group_agents WHERE id = ?').run(id);
+}
+
+/** Get all messaging groups wired to an agent group (reverse lookup). */
+export function getMessagingGroupsByAgentGroup(agentGroupId: string): MessagingGroup[] {
+  return getDb()
+    .prepare(
+      `SELECT mg.* FROM messaging_groups mg
+       JOIN messaging_group_agents mga ON mga.messaging_group_id = mg.id
+       WHERE mga.agent_group_id = ?`,
+    )
+    .all(agentGroupId) as MessagingGroup[];
+}

package/src/db/migrations/001-initial.ts

@@ -0,0 +1,112 @@
+import type { Database } from '../connection.js';
+
+import type { Migration } from './index.js';
+
+export const migration001: Migration = {
+  version: 1,
+  name: 'initial-v2-schema',
+  up(db: Database) {
+    db.exec(`
+      CREATE TABLE agent_groups (
+        id               TEXT PRIMARY KEY,
+        name             TEXT NOT NULL,
+        folder           TEXT NOT NULL UNIQUE,
+        agent_provider   TEXT,
+        created_at       TEXT NOT NULL
+      );
+
+      CREATE TABLE messaging_groups (
+        id                    TEXT PRIMARY KEY,
+        channel_type          TEXT NOT NULL,
+        platform_id           TEXT NOT NULL,
+        name                  TEXT,
+        is_group              INTEGER DEFAULT 0,
+        unknown_sender_policy TEXT NOT NULL DEFAULT 'strict',
+        created_at            TEXT NOT NULL,
+        UNIQUE(channel_type, platform_id)
+      );
+
+      CREATE TABLE messaging_group_agents (
+        id                 TEXT PRIMARY KEY,
+        messaging_group_id TEXT NOT NULL REFERENCES messaging_groups(id),
+        agent_group_id     TEXT NOT NULL REFERENCES agent_groups(id),
+        trigger_rules      TEXT,
+        response_scope     TEXT DEFAULT 'all',
+        session_mode       TEXT DEFAULT 'shared',
+        priority           INTEGER DEFAULT 0,
+        created_at         TEXT NOT NULL,
+        UNIQUE(messaging_group_id, agent_group_id)
+      );
+
+      CREATE TABLE users (
+        id           TEXT PRIMARY KEY,
+        kind         TEXT NOT NULL,
+        display_name TEXT,
+        created_at   TEXT NOT NULL
+      );
+
+      -- role ∈ {owner, admin}
+      -- owner: agent_group_id must be NULL (always global)
+      -- admin: agent_group_id NULL = global, else scoped
+      CREATE TABLE user_roles (
+        user_id        TEXT NOT NULL REFERENCES users(id),
+        role           TEXT NOT NULL,
+        agent_group_id TEXT REFERENCES agent_groups(id),
+        granted_by     TEXT REFERENCES users(id),
+        granted_at     TEXT NOT NULL,
+        PRIMARY KEY (user_id, role, agent_group_id)
+      );
+      CREATE INDEX idx_user_roles_scope ON user_roles(agent_group_id, role);
+
+      -- "known" membership in an agent group. Admin @ A implies membership
+      -- without needing a row (invariant enforced in code).
+      CREATE TABLE agent_group_members (
+        user_id        TEXT NOT NULL REFERENCES users(id),
+        agent_group_id TEXT NOT NULL REFERENCES agent_groups(id),
+        added_by       TEXT REFERENCES users(id),
+        added_at       TEXT NOT NULL,
+        PRIMARY KEY (user_id, agent_group_id)
+      );
+
+      -- DM channel cache: for each (user, channel) pair, which messaging_group
+      -- row is their direct-message channel. Populated on demand by
+      -- ensureUserDm() — either from adapter.openDM() for channels that
+      -- distinguish user id from DM chat id (Discord, Slack, Teams) or by
+      -- pointing directly at the user's handle for channels where they're
+      -- the same (Telegram, WhatsApp, iMessage, email, Matrix).
+      CREATE TABLE user_dms (
+        user_id            TEXT NOT NULL REFERENCES users(id),
+        channel_type       TEXT NOT NULL,
+        messaging_group_id TEXT NOT NULL REFERENCES messaging_groups(id),
+        resolved_at        TEXT NOT NULL,
+        PRIMARY KEY (user_id, channel_type)
+      );
+
+      CREATE TABLE sessions (
+        id                 TEXT PRIMARY KEY,
+        agent_group_id     TEXT NOT NULL REFERENCES agent_groups(id),
+        messaging_group_id TEXT REFERENCES messaging_groups(id),
+        thread_id          TEXT,
+        agent_provider     TEXT,
+        status             TEXT DEFAULT 'active',
+        container_status   TEXT DEFAULT 'stopped',
+        last_active        TEXT,
+        created_at         TEXT NOT NULL
+      );
+      CREATE INDEX idx_sessions_agent_group ON sessions(agent_group_id);
+      CREATE INDEX idx_sessions_lookup ON sessions(messaging_group_id, thread_id);
+
+      CREATE TABLE pending_questions (
+        question_id    TEXT PRIMARY KEY,
+        session_id     TEXT NOT NULL REFERENCES sessions(id),
+        message_out_id TEXT NOT NULL,
+        platform_id    TEXT,
+        channel_type   TEXT,
+        thread_id      TEXT,
+        title          TEXT NOT NULL,
+        options_json   TEXT NOT NULL,
+        created_at     TEXT NOT NULL
+      );
+    `);
+  },
+};

package/src/db/migrations/002-chat-sdk-state.ts

@@ -0,0 +1,36 @@
+import type { Database } from '../connection.js';
+
+import type { Migration } from './index.js';
+
+export const migration002: Migration = {
+  version: 2,
+  name: 'chat-sdk-state',
+  up(db: Database) {
+    db.exec(`
+      CREATE TABLE chat_sdk_kv (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        expires_at INTEGER
+      );
+
+      CREATE TABLE chat_sdk_subscriptions (
+        thread_id TEXT PRIMARY KEY,
+        subscribed_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE chat_sdk_locks (
+        thread_id TEXT PRIMARY KEY,
+        token TEXT NOT NULL,
+        expires_at INTEGER NOT NULL
+      );
+
+      CREATE TABLE chat_sdk_lists (
+        key TEXT NOT NULL,
+        idx INTEGER NOT NULL,
+        value TEXT NOT NULL,
+        expires_at INTEGER,
+        PRIMARY KEY (key, idx)
+      );
+    `);
+  },
+};

package/src/db/migrations/008-dropped-messages.ts

@@ -0,0 +1,27 @@
+import type { Database } from '../connection.js';
+import type { Migration } from './index.js';
+
+export const migration008: Migration = {
+  version: 8,
+  name: 'dropped-messages',
+  up: (db: Database) => {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS unregistered_senders (
+        channel_type    TEXT NOT NULL,
+        platform_id     TEXT NOT NULL,
+        user_id         TEXT,
+        sender_name     TEXT,
+        reason          TEXT NOT NULL,
+        messaging_group_id TEXT,
+        agent_group_id  TEXT,
+        message_count   INTEGER NOT NULL DEFAULT 1,
+        first_seen      TEXT NOT NULL,
+        last_seen       TEXT NOT NULL,
+        PRIMARY KEY (channel_type, platform_id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_unregistered_senders_last_seen
+        ON unregistered_senders(last_seen);
+    `);
+  },
+};

package/src/db/migrations/009-drop-pending-credentials.ts

@@ -0,0 +1,13 @@
+import type { Database } from '../connection.js';
+import type { Migration } from './index.js';
+
+export const migration009: Migration = {
+  version: 9,
+  name: 'drop-pending-credentials',
+  up: (db: Database) => {
+    db.exec(`
+      DROP INDEX IF EXISTS idx_pending_credentials_status;
+      DROP TABLE IF EXISTS pending_credentials;
+    `);
+  },
+};

package/src/db/migrations/010-engage-modes.ts

@@ -0,0 +1,103 @@
+/**
+ * Replace `trigger_rules` (opaque JSON) + `response_scope` (conflated axis)
+ * with four explicit orthogonal columns on messaging_group_agents:
+ *
+ *   engage_mode            'pattern' | 'mention' | 'mention-sticky'
+ *   engage_pattern         regex string (required when engage_mode='pattern';
+ *                          '.' means "match everything" — the "always" flavor)
+ *   sender_scope           'all' | 'known'
+ *   ignored_message_policy 'drop' | 'accumulate'
+ *
+ * Backfill rules (applied per-row, reading the old JSON):
+ *   - If trigger_rules.pattern is a non-empty string → engage_mode='pattern',
+ *     engage_pattern = that value
+ *   - Else if trigger_rules.requiresTrigger === false OR response_scope='all'
+ *     → engage_mode='pattern', engage_pattern='.'
+ *   - Else (requires trigger but no pattern specified) → engage_mode='mention'
+ *   - sender_scope: 'known' when response_scope was 'allowlisted', 'all' otherwise
+ *   - ignored_message_policy: 'drop' (conservative default; no old-schema analog)
+ */
+import type { Database } from '../connection.js';
+import type { Migration } from './index.js';
+
+import { log } from '../../log.js';
+
+interface LegacyRow {
+  id: string;
+  trigger_rules: string | null;
+  response_scope: string | null;
+}
+
+function backfill(row: LegacyRow): {
+  engage_mode: 'pattern' | 'mention' | 'mention-sticky';
+  engage_pattern: string | null;
+  sender_scope: 'all' | 'known';
+  ignored_message_policy: 'drop' | 'accumulate';
+} {
+  let parsed: Record<string, unknown> = {};
+  if (row.trigger_rules) {
+    try {
+      parsed = JSON.parse(row.trigger_rules) as Record<string, unknown>;
+    } catch {
+      // Invalid JSON falls through to conservative defaults.
+    }
+  }
+
+  const pattern = typeof parsed.pattern === 'string' && parsed.pattern.length > 0 ? (parsed.pattern as string) : null;
+  const requiresTrigger = parsed.requiresTrigger;
+
+  let engage_mode: 'pattern' | 'mention' | 'mention-sticky' = 'mention';
+  let engage_pattern: string | null = null;
+  if (pattern) {
+    engage_mode = 'pattern';
+    engage_pattern = pattern;
+  } else if (requiresTrigger === false || row.response_scope === 'all') {
+    engage_mode = 'pattern';
+    engage_pattern = '.';
+  }
+
+  const sender_scope: 'all' | 'known' = row.response_scope === 'allowlisted' ? 'known' : 'all';
+
+  return { engage_mode, engage_pattern, sender_scope, ignored_message_policy: 'drop' };
+}
+
+export const migration010: Migration = {
+  version: 10,
+  name: 'engage-modes',
+  up: (db: Database) => {
+    // Add the four new columns alongside the existing two. SQLite ALTER ADD
+    // is cheap and non-rewriting.
+    db.exec(`
+      ALTER TABLE messaging_group_agents ADD COLUMN engage_mode            TEXT;
+      ALTER TABLE messaging_group_agents ADD COLUMN engage_pattern         TEXT;
+      ALTER TABLE messaging_group_agents ADD COLUMN sender_scope           TEXT;
+      ALTER TABLE messaging_group_agents ADD COLUMN ignored_message_policy TEXT;
+    `);
+
+    // Backfill existing rows in JS (parsing JSON per-row is painful in pure SQL).
+    const rows = db
+      .prepare('SELECT id, trigger_rules, response_scope FROM messaging_group_agents')
+      .all() as LegacyRow[];
+    const update = db.prepare(
+      `UPDATE messaging_group_agents
+         SET engage_mode            = ?,
+             engage_pattern         = ?,
+             sender_scope           = ?,
+             ignored_message_policy = ?
+       WHERE id = ?`,
+    );
+    for (const row of rows) {
+      const v = backfill(row);
+      update.run(v.engage_mode, v.engage_pattern, v.sender_scope, v.ignored_message_policy, row.id);
+    }
+
+    // Drop the legacy columns. DROP COLUMN requires SQLite 3.35+ (2021); our
+    // better-sqlite3 ships a current build.
+    db.exec(`
+      ALTER TABLE messaging_group_agents DROP COLUMN trigger_rules;
+      ALTER TABLE messaging_group_agents DROP COLUMN response_scope;
+    `);
+
+    log.info('engage-modes migration: backfilled rows', { count: rows.length });
+  },
+};

package/src/db/migrations/011-pending-sender-approvals.ts

@@ -0,0 +1,40 @@
+/**
+ * Unknown-sender approval flow. When `unknown_sender_policy = 'request_approval'`
+ * a non-member message triggers a card to the most appropriate admin. An
+ * in-flight entry in this table dedups concurrent attempts from the same
+ * sender; the row is cleared on approve / deny.
+ *
+ * Previously this migration also rebuilt `messaging_groups` to flip the
+ * column DEFAULT from `'strict'` to `'request_approval'`. Removed: the
+ * rebuild failed SQLite's foreign-key integrity check at DROP time on live
+ * DBs with existing FK references (sessions, user_dms, etc.), and `PRAGMA
+ * foreign_keys` / `defer_foreign_keys` can't be toggled inside the
+ * implicit migration transaction. The default-flip was cosmetic anyway —
+ * every `createMessagingGroup` callsite passes `unknown_sender_policy`
+ * explicitly, and the router's auto-create path was updated to hardcode
+ * `'request_approval'` directly (see src/router.ts:123).
+ */
+import type { Database } from '../connection.js';
+import type { Migration } from './index.js';
+
+export const migration011: Migration = {
+  version: 11,
+  name: 'pending-sender-approvals',
+  up: (db: Database) => {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS pending_sender_approvals (
+        id                   TEXT PRIMARY KEY,
+        messaging_group_id   TEXT NOT NULL REFERENCES messaging_groups(id),
+        agent_group_id       TEXT NOT NULL REFERENCES agent_groups(id),
+        sender_identity      TEXT NOT NULL,      -- namespaced user id (channel_type:handle)
+        sender_name          TEXT,
+        original_message     TEXT NOT NULL,      -- JSON serialized InboundEvent
+        approver_user_id     TEXT NOT NULL,
+        created_at           TEXT NOT NULL,
+        UNIQUE(messaging_group_id, sender_identity)
+      );
+      CREATE INDEX IF NOT EXISTS idx_pending_sender_approvals_mg
+        ON pending_sender_approvals(messaging_group_id);
+    `);
+  },
+};

package/src/db/migrations/012-channel-registration.ts

@@ -0,0 +1,48 @@
+/**
+ * Unknown-channel registration flow.
+ *
+ * When a channel that isn't wired to any agent group receives a mention or
+ * DM, the router escalates to the owner for approval before wiring. Approve
+ * creates a `messaging_group_agents` row (with conservative defaults) and
+ * replays the triggering event. Deny marks the channel denied forever
+ * (stored as a timestamp on `messaging_groups.denied_at`) so future
+ * messages on that channel drop silently without re-prompting.
+ *
+ * Two changes:
+ *   1. `messaging_groups.denied_at TEXT NULL` — set on deny, checked in the
+ *      router before re-escalating. ALTER TABLE ADD COLUMN is FK-safe
+ *      unlike the table rebuild that bit us in migration 011.
+ *   2. `pending_channel_approvals` table. PRIMARY KEY on
+ *      `messaging_group_id` gives free in-flight dedup — a second mention
+ *      while the card is pending is silently dropped by INSERT OR IGNORE,
+ *      preventing card spam.
+ */
+import type { Database } from '../connection.js';
+import type { Migration } from './index.js';
+
+export const migration012: Migration = {
+  version: 12,
+  name: 'channel-registration',
+  up: (db: Database) => {
+    // 1. Add denied_at to messaging_groups. Idempotent guard in case the
+    //    column was added by some other path before this migration ran.
+    const cols = db.prepare("PRAGMA table_info('messaging_groups')").all() as Array<{ name: string }>;
+    if (!cols.some((c) => c.name === 'denied_at')) {
+      db.exec(`ALTER TABLE messaging_groups ADD COLUMN denied_at TEXT`);
+    }
+
+    // 2. pending_channel_approvals.
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS pending_channel_approvals (
+        messaging_group_id   TEXT PRIMARY KEY REFERENCES messaging_groups(id),
+        agent_group_id       TEXT NOT NULL REFERENCES agent_groups(id),
+                             -- The agent the approved wiring will target.
+                             -- Picked at request time (currently: earliest
+                             -- agent_group by created_at).
+        original_message     TEXT NOT NULL,      -- JSON serialized InboundEvent
+        approver_user_id     TEXT NOT NULL,
+        created_at           TEXT NOT NULL
+      );
+    `);
+  },
+};

package/src/db/migrations/013-approval-render-metadata.ts

@@ -0,0 +1,27 @@
+/**
+ * Persist ask_question render metadata (title + options_json) on
+ * `pending_channel_approvals` and `pending_sender_approvals`, mirroring the
+ * columns migration 003 / module-approvals-title-options added to
+ * `pending_approvals`.
+ *
+ * Before this, `getAskQuestionRender` hardcoded the title + option labels
+ * for these two tables in the DB-access layer — duplicating wording that
+ * also lived in the approval modules and causing a visible drift between
+ * the initial card title ("📣 Bot mentioned in new chat" / "💬 New direct
+ * message", chosen per event) and the post-click render ("📣 Channel
+ * registration", constant). Storing the render metadata alongside the row
+ * lets both sides read from the same source.
+ */
+import type { Database } from '../connection.js';
+import type { Migration } from './index.js';
+
+export const migration013: Migration = {
+  version: 13,
+  name: 'approval-render-metadata',
+  up(db: Database) {
+    db.exec(`ALTER TABLE pending_channel_approvals ADD COLUMN title TEXT NOT NULL DEFAULT ''`);
+    db.exec(`ALTER TABLE pending_channel_approvals ADD COLUMN options_json TEXT NOT NULL DEFAULT '[]'`);
+    db.exec(`ALTER TABLE pending_sender_approvals ADD COLUMN title TEXT NOT NULL DEFAULT ''`);
+    db.exec(`ALTER TABLE pending_sender_approvals ADD COLUMN options_json TEXT NOT NULL DEFAULT '[]'`);
+  },
+};