Add group metadata sync for easier group activation

- Sync group names from WhatsApp via groupFetchAllParticipating()
- Store group names in chats table (jid -> name mapping)
- Daily sync with 24h cache, on-demand refresh via IPC
- Write available_groups.json snapshot for agent (main group only)
- Agent can request refresh_groups via IPC if group not found
- Update documentation in main CLAUDE.md and debug skill

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/container-runner.ts

@@ -400,3 +400,34 @@ export function writeTasksSnapshot(
   const tasksFile = path.join(groupIpcDir, 'current_tasks.json');
   fs.writeFileSync(tasksFile, JSON.stringify(filteredTasks, null, 2));
 }
+
+export interface AvailableGroup {
+  jid: string;
+  name: string;
+  lastActivity: string;
+  isRegistered: boolean;
+}
+
+/**
+ * Write available groups snapshot for the container to read.
+ * Only main group can see all available groups (for activation).
+ * Non-main groups only see their own registration status.
+ */
+export function writeGroupsSnapshot(
+  groupFolder: string,
+  isMain: boolean,
+  groups: AvailableGroup[],
+  registeredJids: Set<string>
+): void {
+  const groupIpcDir = path.join(DATA_DIR, 'ipc', groupFolder);
+  fs.mkdirSync(groupIpcDir, { recursive: true });
+
+  // Main sees all groups; others see nothing (they can't activate groups)
+  const visibleGroups = isMain ? groups : [];
+
+  const groupsFile = path.join(groupIpcDir, 'available_groups.json');
+  fs.writeFileSync(groupsFile, JSON.stringify({
+    groups: visibleGroups,
+    lastSync: new Date().toISOString()
+  }, null, 2));
+}

src/db.ts

@@ -75,9 +75,68 @@ export function initDatabase(): void {
  * Store chat metadata only (no message content).
  * Used for all chats to enable group discovery without storing sensitive content.
  */
-export function storeChatMetadata(chatJid: string, timestamp: string): void {
-  db.prepare(`INSERT OR REPLACE INTO chats (jid, name, last_message_time) VALUES (?, ?, ?)`)
-    .run(chatJid, chatJid, timestamp);
+export function storeChatMetadata(chatJid: string, timestamp: string, name?: string): void {
+  if (name) {
+    // Update with name, preserving existing timestamp if newer
+    db.prepare(`
+      INSERT INTO chats (jid, name, last_message_time) VALUES (?, ?, ?)
+      ON CONFLICT(jid) DO UPDATE SET
+        name = excluded.name,
+        last_message_time = MAX(last_message_time, excluded.last_message_time)
+    `).run(chatJid, name, timestamp);
+  } else {
+    // Update timestamp only, preserve existing name if any
+    db.prepare(`
+      INSERT INTO chats (jid, name, last_message_time) VALUES (?, ?, ?)
+      ON CONFLICT(jid) DO UPDATE SET
+        last_message_time = MAX(last_message_time, excluded.last_message_time)
+    `).run(chatJid, chatJid, timestamp);
+  }
+}
+
+/**
+ * Update chat name without changing timestamp.
+ * Used during group metadata sync.
+ */
+export function updateChatName(chatJid: string, name: string): void {
+  db.prepare(`
+    INSERT INTO chats (jid, name, last_message_time) VALUES (?, ?, ?)
+    ON CONFLICT(jid) DO UPDATE SET name = excluded.name
+  `).run(chatJid, name, new Date(0).toISOString());
+}
+
+export interface ChatInfo {
+  jid: string;
+  name: string;
+  last_message_time: string;
+}
+
+/**
+ * Get all known chats, ordered by most recent activity.
+ */
+export function getAllChats(): ChatInfo[] {
+  return db.prepare(`
+    SELECT jid, name, last_message_time
+    FROM chats
+    ORDER BY last_message_time DESC
+  `).all() as ChatInfo[];
+}
+
+/**
+ * Get timestamp of last group metadata sync.
+ */
+export function getLastGroupSync(): string | null {
+  // Store sync time in a special chat entry
+  const row = db.prepare(`SELECT last_message_time FROM chats WHERE jid = '__group_sync__'`).get() as { last_message_time: string } | undefined;
+  return row?.last_message_time || null;
+}
+
+/**
+ * Record that group metadata was synced.
+ */
+export function setLastGroupSync(): void {
+  const now = new Date().toISOString();
+  db.prepare(`INSERT OR REPLACE INTO chats (jid, name, last_message_time) VALUES ('__group_sync__', '__group_sync__', ?)`).run(now);
 }
 
 /**

src/index.ts

@@ -19,11 +19,13 @@ import {
   IPC_POLL_INTERVAL
 } from './config.js';
 import { RegisteredGroup, Session, NewMessage } from './types.js';
-import { initDatabase, storeMessage, storeChatMetadata, getNewMessages, getMessagesSince, getAllTasks, getTaskById } from './db.js';
+import { initDatabase, storeMessage, storeChatMetadata, getNewMessages, getMessagesSince, getAllTasks, getTaskById, updateChatName, getAllChats, getLastGroupSync, setLastGroupSync } from './db.js';
 import { startSchedulerLoop } from './task-scheduler.js';
-import { runContainerAgent, writeTasksSnapshot } from './container-runner.js';
+import { runContainerAgent, writeTasksSnapshot, writeGroupsSnapshot, AvailableGroup } from './container-runner.js';
 import { loadJson, saveJson } from './utils.js';
 
+const GROUP_SYNC_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
 const logger = pino({
   level: process.env.LOG_LEVEL || 'info',
   transport: { target: 'pino-pretty', options: { colorize: true } }
@@ -58,6 +60,62 @@ function saveState(): void {
   saveJson(path.join(DATA_DIR, 'sessions.json'), sessions);
 }
 
+/**
+ * Sync group metadata from WhatsApp.
+ * Fetches all participating groups and stores their names in the database.
+ * Called on startup, daily, and on-demand via IPC.
+ */
+async function syncGroupMetadata(force = false): Promise<void> {
+  // Check if we need to sync (skip if synced recently, unless forced)
+  if (!force) {
+    const lastSync = getLastGroupSync();
+    if (lastSync) {
+      const lastSyncTime = new Date(lastSync).getTime();
+      const now = Date.now();
+      if (now - lastSyncTime < GROUP_SYNC_INTERVAL_MS) {
+        logger.debug({ lastSync }, 'Skipping group sync - synced recently');
+        return;
+      }
+    }
+  }
+
+  try {
+    logger.info('Syncing group metadata from WhatsApp...');
+    const groups = await sock.groupFetchAllParticipating();
+
+    let count = 0;
+    for (const [jid, metadata] of Object.entries(groups)) {
+      if (metadata.subject) {
+        updateChatName(jid, metadata.subject);
+        count++;
+      }
+    }
+
+    setLastGroupSync();
+    logger.info({ count }, 'Group metadata synced');
+  } catch (err) {
+    logger.error({ err }, 'Failed to sync group metadata');
+  }
+}
+
+/**
+ * Get available groups list for the agent.
+ * Returns groups ordered by most recent activity.
+ */
+function getAvailableGroups(): AvailableGroup[] {
+  const chats = getAllChats();
+  const registeredJids = new Set(Object.keys(registeredGroups));
+
+  return chats
+    .filter(c => c.jid !== '__group_sync__' && c.jid.endsWith('@g.us'))
+    .map(c => ({
+      jid: c.jid,
+      name: c.name,
+      lastActivity: c.last_message_time,
+      isRegistered: registeredJids.has(c.jid)
+    }));
+}
+
 async function processMessage(msg: NewMessage): Promise<void> {
   const group = registeredGroups[msg.chat_jid];
   if (!group) return;
@@ -110,6 +168,10 @@ async function runAgent(group: RegisteredGroup, prompt: string, chatJid: string)
     next_run: t.next_run
   })));
 
+  // Update available groups snapshot (main group only can see all groups)
+  const availableGroups = getAvailableGroups();
+  writeGroupsSnapshot(group.folder, isMain, availableGroups, new Set(Object.keys(registeredGroups)));
+
   try {
     const output = await runContainerAgent(group, {
       prompt,
@@ -351,6 +413,20 @@ async function processTaskIpc(
       }
       break;
 
+    case 'refresh_groups':
+      // Only main group can request a refresh
+      if (isMain) {
+        logger.info({ sourceGroup }, 'Group metadata refresh requested via IPC');
+        await syncGroupMetadata(true);
+        // Write updated snapshot immediately
+        const availableGroups = getAvailableGroups();
+        const { writeGroupsSnapshot: writeGroups } = await import('./container-runner.js');
+        writeGroups(sourceGroup, true, availableGroups, new Set(Object.keys(registeredGroups)));
+      } else {
+        logger.warn({ sourceGroup }, 'Unauthorized refresh_groups attempt blocked');
+      }
+      break;
+
     default:
       logger.warn({ type: data.type }, 'Unknown IPC task type');
   }
@@ -393,6 +469,12 @@ async function connectWhatsApp(): Promise<void> {
       }
     } else if (connection === 'open') {
       logger.info('Connected to WhatsApp');
+      // Sync group metadata on startup (respects 24h cache)
+      syncGroupMetadata().catch(err => logger.error({ err }, 'Initial group sync failed'));
+      // Set up daily sync timer
+      setInterval(() => {
+        syncGroupMetadata().catch(err => logger.error({ err }, 'Periodic group sync failed'));
+      }, GROUP_SYNC_INTERVAL_MS);
       startSchedulerLoop({
         sendMessage,
         registeredGroups: () => registeredGroups,