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>

setup/register.ts

@@ -11,11 +11,6 @@ import { DATA_DIR } from '../src/config.js';
 import { initDb } from '../src/db/connection.js';
 import { runMigrations } from '../src/db/migrations/index.js';
 import { createAgentGroup, getAgentGroupByFolder } from '../src/db/agent-groups.js';
-import {
-  createDestination,
-  getDestinationByName,
-  normalizeName,
-} from '../src/db/agent-destinations.js';
 import {
   createMessagingGroup,
   createMessagingGroupAgent,
@@ -23,6 +18,7 @@ import {
   getMessagingGroupAgentByPair,
 } from '../src/db/messaging-groups.js';
 import { isValidGroupFolder } from '../src/group-folder.js';
+import { initGroupFilesystem } from '../src/group-init.js';
 import { log } from '../src/log.js';
 import { resolveSession, writeSessionMessage } from '../src/session-manager.js';
 import { emitStatus } from './status.js';
@@ -40,14 +36,10 @@ interface RegisterArgs {
   channel: string;
   /** Whether messages require the trigger pattern to activate */
   requiresTrigger: boolean;
-  /** Whether this is the admin/main agent group */
-  isMain: boolean;
   /** Display name for the assistant */
   assistantName: string;
   /** Session mode: 'shared' (one session per channel) or 'per-thread' */
   sessionMode: string;
-  /** Optional local name the agent uses for this channel (defaults to normalized messaging group name) */
-  localName: string | null;
 }
 
 function parseArgs(args: string[]): RegisterArgs {
@@ -58,16 +50,12 @@ function parseArgs(args: string[]): RegisterArgs {
     folder: '',
     channel: 'discord',
     requiresTrigger: true,
-    isMain: false,
     assistantName: 'Andy',
     sessionMode: 'shared',
-    localName: null,
   };
 
   for (let i = 0; i < args.length; i++) {
     switch (args[i]) {
-      // Accept both --jid (v1 compat) and --platform-id (v2)
-      case '--jid':
       case '--platform-id':
         result.platformId = args[++i] || '';
         break;
@@ -86,18 +74,12 @@ function parseArgs(args: string[]): RegisterArgs {
       case '--no-trigger-required':
         result.requiresTrigger = false;
         break;
-      case '--is-main':
-        result.isMain = true;
-        break;
       case '--assistant-name':
         result.assistantName = args[++i] || 'Andy';
         break;
       case '--session-mode':
         result.sessionMode = args[++i] || 'shared';
         break;
-      case '--local-name':
-        result.localName = args[++i] || null;
-        break;
     }
   }
 
@@ -153,7 +135,6 @@ export async function run(args: string[]): Promise<void> {
       id: agId,
       name: parsed.assistantName,
       folder: parsed.folder,
-      is_admin: parsed.isMain ? 1 : 0,
       agent_provider: null,
       container_config: null,
       created_at: new Date().toISOString(),
@@ -161,6 +142,7 @@ export async function run(args: string[]): Promise<void> {
     agentGroup = getAgentGroupByFolder(parsed.folder)!;
     log.info('Created agent group', { id: agId, folder: parsed.folder });
   }
+  initGroupFilesystem(agentGroup);
 
   // 2. Create or find messaging group
   let messagingGroup = getMessagingGroupByPlatform(parsed.channel, parsed.platformId);
@@ -172,14 +154,15 @@ export async function run(args: string[]): Promise<void> {
       platform_id: parsed.platformId,
       name: parsed.name,
       is_group: 1,
-      admin_user_id: null,
+      unknown_sender_policy: 'strict',
       created_at: new Date().toISOString(),
     });
     messagingGroup = getMessagingGroupByPlatform(parsed.channel, parsed.platformId)!;
     log.info('Created messaging group', { id: mgId, channel: parsed.channel, platformId: parsed.platformId });
   }
 
-  // 3. Wire agent to messaging group + create destination row for the agent's map
+  // 3. Wire agent to messaging group — createMessagingGroupAgent auto-creates
+  // the companion agent_destinations row so delivery's ACL admits this target.
   let newlyWired = false;
   const existing = getMessagingGroupAgentByPair(messagingGroup.id, agentGroup.id);
   if (!existing) {
@@ -198,31 +181,13 @@ export async function run(args: string[]): Promise<void> {
       trigger_rules: triggerRules,
       response_scope: 'all',
       session_mode: parsed.sessionMode,
-      priority: parsed.isMain ? 10 : 0,
-      created_at: new Date().toISOString(),
-    });
-
-    // Create destination row so the agent can address this channel by name.
-    // Auto-suffix on collision within this agent's namespace.
-    const baseLocalName = normalizeName(parsed.localName || parsed.name);
-    let localName = baseLocalName;
-    let suffix = 2;
-    while (getDestinationByName(agentGroup.id, localName)) {
-      localName = `${baseLocalName}-${suffix}`;
-      suffix++;
-    }
-    createDestination({
-      agent_group_id: agentGroup.id,
-      local_name: localName,
-      target_type: 'channel',
-      target_id: messagingGroup.id,
+      priority: 0,
       created_at: new Date().toISOString(),
     });
     log.info('Wired agent to messaging group', {
       mgaId,
       agentGroup: agentGroup.id,
       messagingGroup: messagingGroup.id,
-      localName,
     });
   }
 
@@ -242,22 +207,7 @@ export async function run(args: string[]): Promise<void> {
     log.info('Onboarding message written', { sessionId: session.id, channel: parsed.channel });
   }
 
-  // 5. Create group folders
-  fs.mkdirSync(path.join(projectRoot, 'groups', parsed.folder, 'logs'), { recursive: true });
-
-  // Create CLAUDE.md from template if it doesn't exist
-  const groupClaudeMdPath = path.join(projectRoot, 'groups', parsed.folder, 'CLAUDE.md');
-  if (!fs.existsSync(groupClaudeMdPath)) {
-    const templatePath = parsed.isMain
-      ? path.join(projectRoot, 'groups', 'main', 'CLAUDE.md')
-      : path.join(projectRoot, 'groups', 'global', 'CLAUDE.md');
-    if (fs.existsSync(templatePath)) {
-      fs.copyFileSync(templatePath, groupClaudeMdPath);
-      log.info('Created CLAUDE.md from template', { file: groupClaudeMdPath, template: templatePath });
-    }
-  }
-
-  // 6. Update assistant name in CLAUDE.md files if different from default
+  // 5. Update assistant name in CLAUDE.md files if different from default
   let nameUpdated = false;
   if (parsed.assistantName !== 'Andy') {
     log.info('Updating assistant name', { from: 'Andy', to: parsed.assistantName });