feat(v2): user-level privilege model + cold DM infra + init-first-agent skill

Replaces the agent-group-centric "main group" concept with user-level
privileges and adds the cold-DM infrastructure needed for proactive
outbound messaging (pairing, approvals, welcome flows).

Privilege model
- New tables: users, user_roles (owner global-only; admin global or
  scoped to an agent_group), agent_group_members (explicit non-
  privileged access; admin/owner imply membership), user_dms (cold-DM
  resolution cache).
- Removed agent_groups.is_admin, messaging_groups.admin_user_id. Replaced
  with messaging_groups.unknown_sender_policy (strict | request_approval
  | public) for per-chat unknown-sender gating.
- src/access.ts: canAccessAgentGroup, pickApprover, pickApprovalDelivery.
- src/router.ts: access gate on every inbound, honoring
  unknown_sender_policy for unknown senders.
- src/channels/telegram.ts: pairing interceptor upserts the paired user
  and promotes them to owner if hasAnyOwner() is false (first-pair-wins).

Cold DM infrastructure
- ChannelAdapter.openDM?(handle) — optional method. Chat-SDK-bridge wires
  it to chat.openDM() for resolution-required channels (Discord, Slack,
  Teams, Webex, gChat); direct-addressable channels (Telegram, WhatsApp,
  iMessage, Matrix, Resend) fall through to the handle directly.
- src/user-dm.ts: ensureUserDm(userId) — resolves + caches via user_dms.

Approval routing
- onecli-approvals + delivery use pickApprover + pickApprovalDelivery:
  scoped admins → global admins → owners (dedup), first reachable via
  ensureUserDm, same-channel-kind tie-break. Approvals land in the
  approver's DM, not the origin chat.

Delivery fixes
- delivery.ts ACL rejection now throws instead of returning undefined —
  the outer loop previously marked rejected messages as delivered.
- Implicit-origin allow: session.messaging_group_id === target skips the
  destination check.
- createMessagingGroupAgent auto-creates the companion agent_destinations
  row (normalized local_name from the messaging group's name, collision-
  broken within the agent's namespace).

Container
- container-runner.ts: /workspace/global always read-only; drops
  NANOCLAW_IS_ADMIN; adds NANOCLAW_ADMIN_USER_IDS (owners + global admins
  + scoped admins for this agent group). Agent-runner poll-loop gates
  slash commands against that set.

New skill: /init-first-agent
- Walks the operator through standing up the first agent for a channel:
  channel pick → identity lookup (reads each channel SKILL.md's
  ## Channel Info > how-to-find-id) → DM platform_id resolution (direct-
  addressable, cold-DM via "user DMs bot first + sqlite lookup", or
  Telegram pair-code fallback) → run scripts/init-first-agent.ts →
  verify via tail of nanoclaw.log.
- scripts/init-first-agent.ts: parameterized helper that upserts the
  user + grants owner (if none), creates dm-with-<display-name> agent
  group + initGroupFilesystem, reuses/creates the DM messaging_group,
  wires it (auto-creates destination), resolves the session, and writes
  a kind:'chat' / sender:'system' welcome message into inbound.db. Host
  sweep wakes the container and the agent DMs the operator via the
  normal delivery path.

/manage-channels rewrite
- Drops --is-main / --jid / main-vs-non-main isolation references.
- First-channel flow delegates to /init-first-agent.
- Explains createMessagingGroupAgent auto-creates destinations.
- Adds a privileged-users show section.

setup/
- register.ts: drop --is-main, --jid, --local-name, --trigger
  requiresTrigger defaults; call initGroupFilesystem; normalize to
  v2 schema (no is_admin, no admin_user_id, sets unknown_sender_policy
  'strict'); let createMessagingGroupAgent handle the destination row.
- pair-telegram.ts: emit PAIRED_USER_ID (namespaced "telegram:<id>")
  instead of ADMIN_USER_ID; update header comment.
- register.test.ts deleted — was v1-only, tested a registered_groups
  table that no longer exists.

Docs
- v2-architecture-diagram.{md,html}: ER diagram updated to drop
  is_admin/admin_user_id, add unknown_sender_policy, and include
  users/user_roles/agent_group_members/user_dms.
- v2-architecture-draft.md: approval-routing paragraph rewritten for
  pickApprover/pickApprovalDelivery/ensureUserDm; SQL schema block
  updated; admin-verification paragraph references
  NANOCLAW_ADMIN_USER_IDS.
- v2-setup-wiring.md: entity-model sketch rewritten.
- v2-checklist.md: marked privilege refactor / container filtering /
  approval routing / unknown-sender gating done; removed obsolete
  admin_user_id and main-vs-non-main items.

Scripts
- scripts/init-first-agent.ts (new) replaces scripts/welcome-owner-dm.ts
  (removed; welcome-owner was a Discord-specific one-off).
- test-v2-host.ts, test-v2-channel-e2e.ts, seed-discord.ts: drop
  is_admin + admin_user_id, use unknown_sender_policy.

Tests
- src/access.test.ts (new): 14 tests for canAccessAgentGroup, role
  helpers, pickApprover, ensureUserDm, pickApprovalDelivery.
- src/db/db-v2.test.ts: adds 3 tests for the auto-created
  agent_destinations row (normalized name, no duplicates, collision
  break within an agent group).
- host-core.test.ts, channel-registry.test.ts: updated fixtures to
  use unknown_sender_policy: 'public' where the test exercises routing
  rather than the access gate.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

src/channels/adapter.ts

@@ -94,6 +94,23 @@ export interface ChannelAdapter {
   setTyping?(platformId: string, threadId: string | null): Promise<void>;
   syncConversations?(): Promise<ConversationInfo[]>;
   updateConversations?(conversations: ConversationConfig[]): void;
+
+  /**
+   * Open (or fetch) a DM with this user, returning the platform_id of the
+   * resulting DM channel. Called by the host on demand to initiate cold
+   * DMs — approvals, pairing handshakes, host-initiated notifications — to
+   * users who may never have messaged the bot themselves.
+   *
+   * Omit this method on channels where the user handle IS already the DM
+   * chat id (Telegram, WhatsApp, iMessage, email, Matrix). Callers will
+   * fall through to using the handle directly.
+   *
+   * For channels that distinguish user id from DM channel id (Discord,
+   * Slack, Teams, Webex, gChat): implement by delegating to Chat SDK's
+   * chat.openDM, which hits the platform's idempotent open-DM endpoint.
+   * Returning the same platform_id on repeated calls is expected.
+   */
+  openDM?(userHandle: string): Promise<string>;
 }
 
 /** Factory function that creates a channel adapter (returns null if credentials missing). */

src/channels/channel-registry.test.ts

@@ -133,7 +133,6 @@ describe('channel + router integration', () => {
       id: 'ag-1',
       name: 'Test Agent',
       folder: 'test-agent',
-      is_admin: 0,
       agent_provider: null,
       container_config: null,
       created_at: now(),
@@ -144,7 +143,7 @@ describe('channel + router integration', () => {
       platform_id: 'chan-100',
       name: 'Test Channel',
       is_group: 1,
-      admin_user_id: null,
+      unknown_sender_policy: 'public',
       created_at: now(),
     });
     createMessagingGroupAgent({

src/channels/chat-sdk-bridge.ts

@@ -426,6 +426,22 @@ export function createChatSdkBridge(config: ChatSdkBridgeConfig): ChannelAdapter
       await adapter.startTyping(tid);
     },
 
+    /**
+     * Open (or fetch) a DM with a user via Chat SDK's chat.openDM. The
+     * returned Thread's id is encoded platform-specifically (e.g. Discord
+     * encodes @me:channelId:threadId), so we unwrap with
+     * channelIdFromThreadId to get the plain DM channel id — that's what
+     * the rest of NanoClaw uses as `platform_id`.
+     *
+     * Throws if Chat SDK's underlying adapter doesn't implement openDM.
+     * Channels without DM support (Telegram, WhatsApp native) don't go
+     * through chat-sdk-bridge at all, so this path isn't invoked for them.
+     */
+    async openDM(userHandle: string): Promise<string> {
+      const thread = await chat.openDM(userHandle);
+      return adapter.channelIdFromThreadId(thread.id);
+    },
+
     async teardown() {
       gatewayAbort?.abort();
       await chat.shutdown();

src/channels/telegram-pairing.ts

@@ -7,8 +7,9 @@
  * register. The message must be exactly the 4 digits (optionally prefixed by
  * `@botname ` for groups with privacy ON) — arbitrary messages that happen to
  * contain a 4-digit number do NOT match. The inbound interceptor in
- * telegram.ts matches the code and records the chat (with admin_user_id)
- * before it ever reaches the router.
+ * telegram.ts matches the code, records the chat, upserts the paired user,
+ * and (if no owner exists yet) promotes them to owner — all before the
+ * message ever reaches the router.
  *
  * Storage is a JSON file at data/telegram-pairings.json — single-process,
  * read-modify-write under an in-process mutex.

src/channels/telegram.ts

@@ -8,6 +8,8 @@ import { createTelegramAdapter } from '@chat-adapter/telegram';
 import { readEnvFile } from '../env.js';
 import { log } from '../log.js';
 import { createMessagingGroup, getMessagingGroupByPlatform, updateMessagingGroup } from '../db/messaging-groups.js';
+import { grantRole, hasAnyOwner } from '../db/user-roles.js';
+import { upsertUser } from '../db/users.js';
 import { createChatSdkBridge, type ReplyContext } from './chat-sdk-bridge.js';
 import { sanitizeTelegramLegacyMarkdown } from './telegram-markdown-sanitize.js';
 import { registerChannelAdapter } from './channel-registry.js';
@@ -79,8 +81,9 @@ function readInboundFields(message: InboundMessage): InboundFields {
 
 /**
  * Build an onInbound interceptor that consumes pairing codes before they
- * reach the router. On match: upserts messaging_groups with admin_user_id
- * and short-circuits. On miss: forwards to the host.
+ * reach the router. On match: records the chat + its paired user, promotes
+ * the user to owner if the instance has no owner yet, and short-circuits.
+ * On miss: forwards to the host.
  */
 function createPairingInterceptor(
   botUsernamePromise: Promise<string | null>,
@@ -109,13 +112,13 @@ function createPairingInterceptor(
         hostOnInbound(platformId, threadId, message);
         return;
       }
-      // Pairing matched — upsert the messaging_group with admin binding and
-      // short-circuit. Skip the router entirely so this code-bearing message
-      // never reaches an agent.
+      // Pairing matched — record the chat and short-circuit so the
+      // code-bearing message never reaches an agent. Privilege is now a
+      // property of the paired user, not the chat: upsert the user, and if
+      // this instance has no owner yet, promote them to owner.
       const existing = getMessagingGroupByPlatform('telegram', platformId);
       if (existing) {
         updateMessagingGroup(existing.id, {
-          admin_user_id: consumed.consumed!.adminUserId,
           is_group: consumed.consumed!.isGroup ? 1 : 0,
         });
       } else {
@@ -125,13 +128,35 @@ function createPairingInterceptor(
           platform_id: platformId,
           name: consumed.consumed!.name,
           is_group: consumed.consumed!.isGroup ? 1 : 0,
-          admin_user_id: consumed.consumed!.adminUserId,
+          unknown_sender_policy: 'strict',
           created_at: new Date().toISOString(),
         });
       }
+
+      const pairedUserId = `telegram:${consumed.consumed!.adminUserId}`;
+      upsertUser({
+        id: pairedUserId,
+        kind: 'telegram',
+        display_name: null,
+        created_at: new Date().toISOString(),
+      });
+
+      let promotedToOwner = false;
+      if (!hasAnyOwner()) {
+        grantRole({
+          user_id: pairedUserId,
+          role: 'owner',
+          agent_group_id: null,
+          granted_by: null,
+          granted_at: new Date().toISOString(),
+        });
+        promotedToOwner = true;
+      }
+
       log.info('Telegram pairing accepted — chat registered', {
         platformId,
-        adminUserId: consumed.consumed!.adminUserId,
+        pairedUser: pairedUserId,
+        promotedToOwner,
         intent: consumed.intent,
       });
     })().catch((err) => {