cli-claw-kit 0.0.1

package/dist/db.js

@@ -0,0 +1,3683 @@
+import crypto from 'crypto';
+import Database from './sqlite-compat.js';
+import fs from 'fs';
+import path from 'path';
+import { resolveAppPath } from './app-root.js';
+import { STORE_DIR, GROUPS_DIR } from './config.js';
+import { logger } from './logger.js';
+import { AGENT_MEMORY_TEMPLATE_FILENAME, getAgentMemoryPath, } from './project-memory.js';
+import { getDefaultPermissions, normalizePermissions } from './permissions.js';
+import { parseRuntimeIdentity, serializeRuntimeIdentity, } from './runtime-identity.js';
+let db;
+// Prepared statement cache — lazy-initialized on first use after initDatabase()
+let _stmts = null;
+const _newMsgStmtCache = new Map();
+function stmts() {
+    if (!_stmts) {
+        _stmts = {
+            storeMessageSelect: db.prepare(`SELECT id FROM messages
+         WHERE chat_jid = ? AND turn_id = ? AND source_kind = 'sdk_final'
+         ORDER BY timestamp DESC LIMIT 1`),
+            storeMessageInsert: db.prepare(`INSERT OR REPLACE INTO messages (
+          id, chat_jid, source_jid, sender, sender_name, content, timestamp, is_from_me,
+          attachments, token_usage, runtime_identity, turn_id, session_id, sdk_message_uuid, source_kind, finalization_reason
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+            insertUsageInsert: db.prepare(`INSERT INTO usage_records (id, user_id, group_folder, agent_id, message_id, model,
+          input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens,
+          cost_usd, duration_ms, num_turns, source, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+            insertUsageUpsert: db.prepare(`INSERT INTO usage_daily_summary (user_id, model, date,
+          total_input_tokens, total_output_tokens,
+          total_cache_read_tokens, total_cache_creation_tokens,
+          total_cost_usd, request_count, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, 1, datetime('now'))
+        ON CONFLICT(user_id, model, date) DO UPDATE SET
+          total_input_tokens = total_input_tokens + excluded.total_input_tokens,
+          total_output_tokens = total_output_tokens + excluded.total_output_tokens,
+          total_cache_read_tokens = total_cache_read_tokens + excluded.total_cache_read_tokens,
+          total_cache_creation_tokens = total_cache_creation_tokens + excluded.total_cache_creation_tokens,
+          total_cost_usd = total_cost_usd + excluded.total_cost_usd,
+          request_count = request_count + 1,
+          updated_at = datetime('now')`),
+            getSessionWithUser: db.prepare(`SELECT s.*, u.username, u.role, u.status, u.display_name, u.permissions, u.must_change_password
+         FROM user_sessions s
+         JOIN users u ON s.user_id = u.id
+         WHERE s.id = ?`),
+            deleteSession: db.prepare('DELETE FROM user_sessions WHERE id = ?'),
+            updateSessionLastActive: db.prepare('UPDATE user_sessions SET last_active_at = ? WHERE id = ?'),
+            updateTokenUsageById: db.prepare(`UPDATE messages SET token_usage = ?, cost_usd = ? WHERE id = ? AND chat_jid = ?`),
+            updateTokenUsageLatest: db.prepare(`UPDATE messages SET token_usage = ?, cost_usd = ?
+         WHERE rowid = (
+           SELECT rowid FROM messages
+           WHERE chat_jid = ? AND is_from_me = 1 AND token_usage IS NULL
+             AND COALESCE(source_kind, 'legacy') != 'sdk_send_message'
+           ORDER BY timestamp DESC LIMIT 1
+         )`),
+            getMessagesSince: db.prepare(`SELECT id, chat_jid, source_jid, runtime_identity, sender, sender_name, content, timestamp, attachments
+         FROM messages
+         WHERE chat_jid = ? AND (timestamp > ? OR (timestamp = ? AND id > ?)) AND is_from_me = 0
+         ORDER BY timestamp ASC, id ASC`),
+            getExpiredSessionIds: db.prepare('SELECT id FROM user_sessions WHERE expires_at < ?'),
+        };
+    }
+    return _stmts;
+}
+function getNewMessagesStmt(jidCount) {
+    let s = _newMsgStmtCache.get(jidCount);
+    if (!s) {
+        const placeholders = Array(jidCount).fill('?').join(',');
+        s = db.prepare(`SELECT id, chat_jid, source_jid, runtime_identity, sender, sender_name, content, timestamp, attachments
+       FROM messages
+       WHERE (timestamp > ? OR (timestamp = ? AND id > ?))
+         AND chat_jid IN (${placeholders})
+         AND is_from_me = 0
+         AND COALESCE(source_kind, '') != 'user_command'
+       ORDER BY timestamp ASC, id ASC`);
+        _newMsgStmtCache.set(jidCount, s);
+    }
+    return s;
+}
+function mapDbMessageRow(row) {
+    return {
+        ...row,
+        runtime_identity: parseRuntimeIdentity(row.runtime_identity),
+        is_from_me: row.is_from_me === 1,
+    };
+}
+function hasColumn(tableName, columnName) {
+    const columns = db.prepare(`PRAGMA table_info(${tableName})`).all();
+    return columns.some((column) => column.name === columnName);
+}
+function ensureColumn(tableName, columnName, sqlTypeWithDefault) {
+    if (hasColumn(tableName, columnName))
+        return;
+    db.exec(`ALTER TABLE ${tableName} ADD COLUMN ${columnName} ${sqlTypeWithDefault}`);
+}
+function assertSchema(tableName, requiredColumns, forbiddenColumns = []) {
+    const columns = db.prepare(`PRAGMA table_info(${tableName})`).all();
+    const names = new Set(columns.map((c) => c.name));
+    const missing = requiredColumns.filter((c) => !names.has(c));
+    const forbidden = forbiddenColumns.filter((c) => names.has(c));
+    if (missing.length > 0 || forbidden.length > 0) {
+        throw new Error(`Incompatible DB schema in table "${tableName}". Missing: [${missing.join(', ')}], forbidden: [${forbidden.join(', ')}]. ` +
+            'Please remove ~/.cli-claw/db/messages.db and restart.');
+    }
+}
+/** Internal helper — reads router_state before initDatabase exports are available. */
+function getRouterStateInternal(key) {
+    try {
+        const row = db
+            .prepare('SELECT value FROM router_state WHERE key = ?')
+            .get(key);
+        return row?.value;
+    }
+    catch {
+        return undefined; // Table may not exist yet on first run
+    }
+}
+export function initDatabase() {
+    const dbPath = path.join(STORE_DIR, 'messages.db');
+    fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+    db = new Database(dbPath);
+    // Enable WAL mode for better concurrency and performance
+    db.exec('PRAGMA journal_mode = WAL');
+    db.exec('PRAGMA busy_timeout = 5000');
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS chats (
+      jid TEXT PRIMARY KEY,
+      name TEXT,
+      last_message_time TEXT
+    );
+    CREATE TABLE IF NOT EXISTS messages (
+      id TEXT,
+      chat_jid TEXT,
+      source_jid TEXT,
+      sender TEXT,
+      sender_name TEXT,
+      content TEXT,
+      timestamp TEXT,
+      is_from_me INTEGER,
+      attachments TEXT,
+      token_usage TEXT,
+      runtime_identity TEXT,
+      turn_id TEXT,
+      session_id TEXT,
+      sdk_message_uuid TEXT,
+      source_kind TEXT,
+      finalization_reason TEXT,
+      PRIMARY KEY (id, chat_jid),
+      FOREIGN KEY (chat_jid) REFERENCES chats(jid)
+    );
+    CREATE INDEX IF NOT EXISTS idx_timestamp ON messages(timestamp);
+    CREATE INDEX IF NOT EXISTS idx_messages_jid_ts ON messages(chat_jid, timestamp);
+
+    CREATE TABLE IF NOT EXISTS scheduled_tasks (
+      id TEXT PRIMARY KEY,
+      group_folder TEXT NOT NULL,
+      chat_jid TEXT NOT NULL,
+      prompt TEXT NOT NULL,
+      schedule_type TEXT NOT NULL,
+      schedule_value TEXT NOT NULL,
+      context_mode TEXT DEFAULT 'isolated',
+      execution_type TEXT DEFAULT 'agent',
+      script_command TEXT,
+      next_run TEXT,
+      last_run TEXT,
+      last_result TEXT,
+      status TEXT DEFAULT 'active',
+      created_at TEXT NOT NULL,
+      created_by TEXT,
+      notify_channels TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_next_run ON scheduled_tasks(next_run);
+    CREATE INDEX IF NOT EXISTS idx_status ON scheduled_tasks(status);
+
+    CREATE TABLE IF NOT EXISTS task_run_logs (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      task_id TEXT NOT NULL,
+      run_at TEXT NOT NULL,
+      duration_ms INTEGER NOT NULL,
+      status TEXT NOT NULL,
+      result TEXT,
+      error TEXT,
+      FOREIGN KEY (task_id) REFERENCES scheduled_tasks(id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_task_run_logs ON task_run_logs(task_id, run_at);
+  `);
+    // State tables (replacing JSON files)
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS router_state (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS sessions (
+      group_folder TEXT NOT NULL,
+      session_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL DEFAULT '',
+      PRIMARY KEY (group_folder, agent_id)
+    );
+    CREATE TABLE IF NOT EXISTS registered_groups (
+      jid TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      folder TEXT NOT NULL,
+      added_at TEXT NOT NULL,
+      container_config TEXT,
+      created_by TEXT,
+      is_home INTEGER DEFAULT 0
+    );
+  `);
+    // Auth tables
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS users (
+      id TEXT PRIMARY KEY,
+      username TEXT NOT NULL UNIQUE,
+      password_hash TEXT NOT NULL,
+      display_name TEXT NOT NULL DEFAULT '',
+      role TEXT NOT NULL DEFAULT 'member',
+      status TEXT NOT NULL DEFAULT 'active',
+      permissions TEXT NOT NULL DEFAULT '[]',
+      must_change_password INTEGER NOT NULL DEFAULT 0,
+      disable_reason TEXT,
+      notes TEXT,
+      avatar_emoji TEXT,
+      avatar_color TEXT,
+      ai_name TEXT,
+      ai_avatar_emoji TEXT,
+      ai_avatar_color TEXT,
+      ai_avatar_url TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      last_login_at TEXT,
+      deleted_at TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS invite_codes (
+      code TEXT PRIMARY KEY,
+      created_by TEXT NOT NULL,
+      role TEXT NOT NULL DEFAULT 'member',
+      permission_template TEXT,
+      permissions TEXT NOT NULL DEFAULT '[]',
+      max_uses INTEGER NOT NULL DEFAULT 1,
+      used_count INTEGER NOT NULL DEFAULT 0,
+      expires_at TEXT,
+      created_at TEXT NOT NULL,
+      FOREIGN KEY (created_by) REFERENCES users(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS user_sessions (
+      id TEXT PRIMARY KEY,
+      user_id TEXT NOT NULL,
+      ip_address TEXT,
+      user_agent TEXT,
+      created_at TEXT NOT NULL,
+      expires_at TEXT NOT NULL,
+      last_active_at TEXT NOT NULL,
+      FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+    );
+
+    CREATE TABLE IF NOT EXISTS auth_audit_log (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      event_type TEXT NOT NULL,
+      username TEXT NOT NULL,
+      actor_username TEXT,
+      ip_address TEXT,
+      user_agent TEXT,
+      details TEXT,
+      created_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_auth_audit_created ON auth_audit_log(created_at);
+    CREATE INDEX IF NOT EXISTS idx_user_sessions_user ON user_sessions(user_id);
+    CREATE INDEX IF NOT EXISTS idx_user_sessions_expires ON user_sessions(expires_at);
+    CREATE INDEX IF NOT EXISTS idx_users_status_role ON users(status, role);
+    CREATE INDEX IF NOT EXISTS idx_users_created_at ON users(created_at);
+    CREATE INDEX IF NOT EXISTS idx_invites_created_at ON invite_codes(created_at);
+  `);
+    // Group members table for shared workspaces
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS group_members (
+      group_folder TEXT NOT NULL,
+      user_id TEXT NOT NULL,
+      role TEXT NOT NULL DEFAULT 'member',
+      added_at TEXT NOT NULL,
+      added_by TEXT,
+      PRIMARY KEY (group_folder, user_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_group_members_user ON group_members(user_id);
+  `);
+    // User pinned groups (per-user workspace pinning)
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS user_pinned_groups (
+      user_id TEXT NOT NULL,
+      jid TEXT NOT NULL,
+      pinned_at TEXT NOT NULL,
+      PRIMARY KEY (user_id, jid)
+    );
+  `);
+    // Sub-agents table for multi-agent parallel execution
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS agents (
+      id TEXT PRIMARY KEY,
+      group_folder TEXT NOT NULL,
+      chat_jid TEXT NOT NULL,
+      name TEXT NOT NULL,
+      prompt TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'running',
+      created_by TEXT,
+      created_at TEXT NOT NULL,
+      completed_at TEXT,
+      result_summary TEXT,
+      last_im_jid TEXT,
+      spawned_from_jid TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_agents_group ON agents(group_folder);
+    CREATE INDEX IF NOT EXISTS idx_agents_jid ON agents(chat_jid);
+    CREATE INDEX IF NOT EXISTS idx_agents_status ON agents(status);
+  `);
+    // Billing tables
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS billing_plans (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      description TEXT,
+      tier INTEGER NOT NULL DEFAULT 0,
+      monthly_cost_usd REAL NOT NULL DEFAULT 0,
+      monthly_token_quota INTEGER,
+      monthly_cost_quota REAL,
+      daily_cost_quota REAL,
+      weekly_cost_quota REAL,
+      daily_token_quota INTEGER,
+      weekly_token_quota INTEGER,
+      rate_multiplier REAL NOT NULL DEFAULT 1.0,
+      trial_days INTEGER,
+      sort_order INTEGER NOT NULL DEFAULT 0,
+      display_price TEXT,
+      highlight INTEGER NOT NULL DEFAULT 0,
+      max_groups INTEGER,
+      max_concurrent_containers INTEGER,
+      max_im_channels INTEGER,
+      max_mcp_servers INTEGER,
+      max_storage_mb INTEGER,
+      allow_overage INTEGER NOT NULL DEFAULT 0,
+      features TEXT NOT NULL DEFAULT '[]',
+      is_default INTEGER NOT NULL DEFAULT 0,
+      is_active INTEGER NOT NULL DEFAULT 1,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS user_subscriptions (
+      id TEXT PRIMARY KEY,
+      user_id TEXT NOT NULL,
+      plan_id TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'active',
+      started_at TEXT NOT NULL,
+      expires_at TEXT,
+      cancelled_at TEXT,
+      trial_ends_at TEXT,
+      notes TEXT,
+      auto_renew INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL,
+      FOREIGN KEY (user_id) REFERENCES users(id),
+      FOREIGN KEY (plan_id) REFERENCES billing_plans(id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_user_sub_user ON user_subscriptions(user_id);
+    CREATE INDEX IF NOT EXISTS idx_user_sub_status ON user_subscriptions(status);
+
+    CREATE TABLE IF NOT EXISTS user_balances (
+      user_id TEXT PRIMARY KEY,
+      balance_usd REAL NOT NULL DEFAULT 0,
+      total_deposited_usd REAL NOT NULL DEFAULT 0,
+      total_consumed_usd REAL NOT NULL DEFAULT 0,
+      updated_at TEXT NOT NULL,
+      FOREIGN KEY (user_id) REFERENCES users(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS balance_transactions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      user_id TEXT NOT NULL,
+      type TEXT NOT NULL,
+      amount_usd REAL NOT NULL,
+      balance_after REAL NOT NULL,
+      description TEXT,
+      reference_type TEXT,
+      reference_id TEXT,
+      actor_id TEXT,
+      source TEXT NOT NULL DEFAULT 'system_adjustment',
+      operator_type TEXT NOT NULL DEFAULT 'system',
+      notes TEXT,
+      idempotency_key TEXT,
+      created_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_bal_tx_user ON balance_transactions(user_id);
+    CREATE INDEX IF NOT EXISTS idx_bal_tx_created ON balance_transactions(created_at);
+
+    CREATE TABLE IF NOT EXISTS monthly_usage (
+      user_id TEXT NOT NULL,
+      month TEXT NOT NULL,
+      total_input_tokens INTEGER NOT NULL DEFAULT 0,
+      total_output_tokens INTEGER NOT NULL DEFAULT 0,
+      total_cost_usd REAL NOT NULL DEFAULT 0,
+      message_count INTEGER NOT NULL DEFAULT 0,
+      updated_at TEXT NOT NULL,
+      PRIMARY KEY (user_id, month)
+    );
+
+    CREATE TABLE IF NOT EXISTS redeem_codes (
+      code TEXT PRIMARY KEY,
+      type TEXT NOT NULL,
+      value_usd REAL,
+      plan_id TEXT,
+      duration_days INTEGER,
+      max_uses INTEGER NOT NULL DEFAULT 1,
+      used_count INTEGER NOT NULL DEFAULT 0,
+      expires_at TEXT,
+      created_by TEXT NOT NULL,
+      notes TEXT,
+      batch_id TEXT,
+      created_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS redeem_code_usage (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      code TEXT NOT NULL,
+      user_id TEXT NOT NULL,
+      redeemed_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_redeem_usage_user ON redeem_code_usage(user_id);
+
+    CREATE TABLE IF NOT EXISTS billing_audit_log (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      event_type TEXT NOT NULL,
+      user_id TEXT NOT NULL,
+      actor_id TEXT,
+      details TEXT,
+      created_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_bill_audit_user ON billing_audit_log(user_id);
+    CREATE INDEX IF NOT EXISTS idx_bill_audit_created ON billing_audit_log(created_at);
+
+    CREATE TABLE IF NOT EXISTS daily_usage (
+      user_id TEXT NOT NULL,
+      date TEXT NOT NULL,
+      total_input_tokens INTEGER NOT NULL DEFAULT 0,
+      total_output_tokens INTEGER NOT NULL DEFAULT 0,
+      total_cost_usd REAL NOT NULL DEFAULT 0,
+      message_count INTEGER NOT NULL DEFAULT 0,
+      PRIMARY KEY (user_id, date)
+    );
+    CREATE INDEX IF NOT EXISTS idx_daily_usage_date ON daily_usage(date);
+    CREATE INDEX IF NOT EXISTS idx_daily_usage_user_date ON daily_usage(user_id, date);
+  `);
+    // Token usage tracking tables
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS usage_records (
+      id TEXT PRIMARY KEY,
+      user_id TEXT NOT NULL,
+      group_folder TEXT NOT NULL,
+      agent_id TEXT,
+      message_id TEXT,
+      model TEXT NOT NULL DEFAULT 'unknown',
+      input_tokens INTEGER NOT NULL DEFAULT 0,
+      output_tokens INTEGER NOT NULL DEFAULT 0,
+      cache_read_input_tokens INTEGER NOT NULL DEFAULT 0,
+      cache_creation_input_tokens INTEGER NOT NULL DEFAULT 0,
+      cost_usd REAL NOT NULL DEFAULT 0,
+      duration_ms INTEGER DEFAULT 0,
+      num_turns INTEGER DEFAULT 0,
+      source TEXT NOT NULL DEFAULT 'agent',
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_usage_user_date ON usage_records(user_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_usage_group_date ON usage_records(group_folder, created_at);
+    CREATE INDEX IF NOT EXISTS idx_usage_model_date ON usage_records(model, created_at);
+
+    CREATE TABLE IF NOT EXISTS usage_daily_summary (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      user_id TEXT NOT NULL,
+      model TEXT NOT NULL,
+      date TEXT NOT NULL,
+      total_input_tokens INTEGER NOT NULL DEFAULT 0,
+      total_output_tokens INTEGER NOT NULL DEFAULT 0,
+      total_cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+      total_cache_creation_tokens INTEGER NOT NULL DEFAULT 0,
+      total_cost_usd REAL NOT NULL DEFAULT 0,
+      request_count INTEGER NOT NULL DEFAULT 0,
+      updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+      UNIQUE(user_id, model, date)
+    );
+    CREATE INDEX IF NOT EXISTS idx_daily_user_date ON usage_daily_summary(user_id, date);
+
+    CREATE TABLE IF NOT EXISTS user_quotas (
+      user_id TEXT PRIMARY KEY,
+      monthly_cost_limit_usd REAL NOT NULL DEFAULT -1,
+      monthly_token_limit INTEGER NOT NULL DEFAULT -1,
+      daily_cost_limit_usd REAL NOT NULL DEFAULT -1,
+      daily_request_limit INTEGER NOT NULL DEFAULT -1,
+      billing_cycle_start TEXT,
+      subscription_tier TEXT,
+      subscription_expires_at TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+    // Lightweight migrations for existing DBs
+    ensureColumn('users', 'permissions', "TEXT NOT NULL DEFAULT '[]'");
+    ensureColumn('users', 'must_change_password', 'INTEGER NOT NULL DEFAULT 0');
+    ensureColumn('users', 'disable_reason', 'TEXT');
+    ensureColumn('users', 'notes', 'TEXT');
+    ensureColumn('users', 'deleted_at', 'TEXT');
+    ensureColumn('invite_codes', 'permission_template', 'TEXT');
+    ensureColumn('invite_codes', 'permissions', "TEXT NOT NULL DEFAULT '[]'");
+    ensureColumn('users', 'avatar_emoji', 'TEXT');
+    ensureColumn('users', 'avatar_color', 'TEXT');
+    ensureColumn('registered_groups', 'execution_mode', "TEXT DEFAULT 'container'");
+    ensureColumn('registered_groups', 'agent_type', "TEXT DEFAULT 'claude'");
+    ensureColumn('registered_groups', 'model', 'TEXT');
+    ensureColumn('registered_groups', 'reasoning_effort', 'TEXT');
+    ensureColumn('registered_groups', 'custom_cwd', 'TEXT');
+    ensureColumn('registered_groups', 'init_source_path', 'TEXT');
+    ensureColumn('registered_groups', 'init_git_url', 'TEXT');
+    ensureColumn('messages', 'attachments', 'TEXT');
+    ensureColumn('messages', 'source_jid', 'TEXT');
+    ensureColumn('registered_groups', 'created_by', 'TEXT');
+    ensureColumn('registered_groups', 'is_home', 'INTEGER DEFAULT 0');
+    ensureColumn('users', 'avatar_url', 'TEXT');
+    ensureColumn('users', 'ai_name', 'TEXT');
+    ensureColumn('users', 'ai_avatar_emoji', 'TEXT');
+    ensureColumn('users', 'ai_avatar_color', 'TEXT');
+    ensureColumn('users', 'ai_avatar_url', 'TEXT');
+    ensureColumn('scheduled_tasks', 'created_by', 'TEXT');
+    ensureColumn('scheduled_tasks', 'execution_type', "TEXT DEFAULT 'agent'");
+    ensureColumn('scheduled_tasks', 'script_command', 'TEXT');
+    ensureColumn('scheduled_tasks', 'notify_channels', 'TEXT');
+    ensureColumn('scheduled_tasks', 'execution_mode', 'TEXT');
+    ensureColumn('scheduled_tasks', 'workspace_jid', 'TEXT');
+    ensureColumn('scheduled_tasks', 'workspace_folder', 'TEXT');
+    ensureColumn('registered_groups', 'selected_skills', 'TEXT');
+    ensureColumn('sessions', 'agent_id', "TEXT NOT NULL DEFAULT ''");
+    ensureColumn('agents', 'kind', "TEXT NOT NULL DEFAULT 'task'");
+    ensureColumn('registered_groups', 'target_agent_id', 'TEXT');
+    ensureColumn('registered_groups', 'target_main_jid', 'TEXT');
+    ensureColumn('registered_groups', 'reply_policy', "TEXT DEFAULT 'source_only'");
+    ensureColumn('registered_groups', 'require_mention', 'INTEGER DEFAULT 0');
+    ensureColumn('registered_groups', 'mcp_mode', "TEXT DEFAULT 'inherit'");
+    ensureColumn('registered_groups', 'selected_mcps', 'TEXT');
+    ensureColumn('registered_groups', 'activation_mode', "TEXT DEFAULT 'auto'");
+    ensureColumn('messages', 'token_usage', 'TEXT');
+    ensureColumn('messages', 'runtime_identity', 'TEXT');
+    ensureColumn('messages', 'turn_id', 'TEXT');
+    ensureColumn('messages', 'session_id', 'TEXT');
+    ensureColumn('messages', 'sdk_message_uuid', 'TEXT');
+    ensureColumn('messages', 'source_kind', 'TEXT');
+    ensureColumn('messages', 'finalization_reason', 'TEXT');
+    // Add index on target_agent_id for fast lookup of IM bindings
+    db.exec('CREATE INDEX IF NOT EXISTS idx_rg_target_agent ON registered_groups(target_agent_id)');
+    db.exec('CREATE INDEX IF NOT EXISTS idx_rg_target_main ON registered_groups(target_main_jid)');
+    // Migration: remove UNIQUE constraint from registered_groups.folder
+    // Multiple groups (web:main + feishu chats) share folder='main' by design.
+    // The old UNIQUE constraint caused INSERT OR REPLACE to silently delete
+    // the conflicting row, making web:main and feishu groups mutually exclusive.
+    const hasUniqueFolder = db
+        .prepare(`SELECT COUNT(*) as cnt FROM sqlite_master
+         WHERE type='index' AND tbl_name='registered_groups'
+         AND name='sqlite_autoindex_registered_groups_2'`)
+        .get().cnt > 0;
+    if (hasUniqueFolder) {
+        db.transaction(() => {
+            db.exec(`
+        CREATE TABLE registered_groups_new (
+          jid TEXT PRIMARY KEY,
+          name TEXT NOT NULL,
+          folder TEXT NOT NULL,
+          added_at TEXT NOT NULL,
+          container_config TEXT,
+          agent_type TEXT DEFAULT 'claude',
+          execution_mode TEXT DEFAULT 'container',
+          custom_cwd TEXT,
+          init_source_path TEXT,
+          init_git_url TEXT,
+          created_by TEXT,
+          is_home INTEGER DEFAULT 0
+        );
+        INSERT INTO registered_groups_new SELECT jid, name, folder, added_at, container_config, 'claude', execution_mode, custom_cwd, NULL, NULL, NULL, 0 FROM registered_groups;
+        DROP TABLE registered_groups;
+        ALTER TABLE registered_groups_new RENAME TO registered_groups;
+      `);
+        })();
+    }
+    // v19→v20 migration: add token_usage column to messages
+    ensureColumn('messages', 'token_usage', 'TEXT');
+    assertSchema('messages', [
+        'id',
+        'chat_jid',
+        'source_jid',
+        'sender',
+        'sender_name',
+        'content',
+        'timestamp',
+        'is_from_me',
+        'attachments',
+        'token_usage',
+        'runtime_identity',
+    ]);
+    assertSchema('scheduled_tasks', [
+        'id',
+        'group_folder',
+        'chat_jid',
+        'prompt',
+        'schedule_type',
+        'schedule_value',
+        'context_mode',
+        'next_run',
+        'last_run',
+        'last_result',
+        'status',
+        'created_at',
+        'created_by',
+    ]);
+    assertSchema('registered_groups', [
+        'jid',
+        'name',
+        'folder',
+        'added_at',
+        'container_config',
+        'agent_type',
+        'execution_mode',
+        'custom_cwd',
+        'init_source_path',
+        'init_git_url',
+        'created_by',
+        'is_home',
+        'selected_skills',
+        'target_agent_id',
+        'target_main_jid',
+        'reply_policy',
+    ], ['trigger_pattern', 'requires_trigger']);
+    assertSchema('users', [
+        'id',
+        'username',
+        'password_hash',
+        'display_name',
+        'role',
+        'status',
+        'permissions',
+        'must_change_password',
+        'disable_reason',
+        'notes',
+        'avatar_emoji',
+        'avatar_color',
+        'avatar_url',
+        'ai_name',
+        'ai_avatar_emoji',
+        'ai_avatar_color',
+        'ai_avatar_url',
+        'created_at',
+        'updated_at',
+        'last_login_at',
+        'deleted_at',
+    ]);
+    assertSchema('user_sessions', [
+        'id',
+        'user_id',
+        'ip_address',
+        'user_agent',
+        'created_at',
+        'expires_at',
+        'last_active_at',
+    ]);
+    assertSchema('invite_codes', [
+        'code',
+        'created_by',
+        'role',
+        'permission_template',
+        'permissions',
+        'max_uses',
+        'used_count',
+        'expires_at',
+        'created_at',
+    ]);
+    assertSchema('auth_audit_log', [
+        'id',
+        'event_type',
+        'username',
+        'actor_username',
+        'ip_address',
+        'user_agent',
+        'details',
+        'created_at',
+    ]);
+    // Store schema version after all migrations complete
+    // Migrate existing web groups: assign to first admin
+    db.exec(`
+    UPDATE registered_groups SET created_by = (
+      SELECT id FROM users WHERE role = 'admin' AND status = 'active' ORDER BY created_at ASC LIMIT 1
+    ) WHERE jid LIKE 'web:%' AND folder != 'main' AND created_by IS NULL
+  `);
+    // Backfill owner for legacy web:main if missing.
+    db.exec(`
+    UPDATE registered_groups SET created_by = (
+      SELECT id FROM users WHERE role = 'admin' AND status = 'active' ORDER BY created_at ASC LIMIT 1
+    ) WHERE jid = 'web:main' AND created_by IS NULL
+  `);
+    // Backfill created_by for feishu/telegram groups by matching sibling groups in the same folder.
+    // Only backfill when the folder has exactly one distinct owner; otherwise keep NULL
+    // to avoid misrouting in ambiguous folders (e.g., shared admin main).
+    db.exec(`
+    UPDATE registered_groups
+    SET created_by = (
+      SELECT MIN(rg2.created_by)
+      FROM registered_groups rg2
+      WHERE rg2.folder = registered_groups.folder
+        AND rg2.created_by IS NOT NULL
+    )
+    WHERE (jid LIKE 'feishu:%' OR jid LIKE 'telegram:%')
+      AND created_by IS NULL
+      AND (
+        SELECT COUNT(DISTINCT rg3.created_by)
+        FROM registered_groups rg3
+        WHERE rg3.folder = registered_groups.folder
+          AND rg3.created_by IS NOT NULL
+      ) = 1
+  `);
+    // v13 migration: mark existing web:main group as is_home=1
+    db.exec(`
+    UPDATE registered_groups SET is_home = 1
+    WHERE jid = 'web:main' AND folder = 'main' AND is_home = 0
+  `);
+    // v15 migration: backfill group_members for existing web groups
+    const currentVersion = getRouterStateInternal('schema_version');
+    if (!currentVersion || parseInt(currentVersion, 10) < 15) {
+        db.transaction(() => {
+            // Backfill owner records for all web groups with created_by set
+            const webGroups = db
+                .prepare("SELECT DISTINCT folder, created_by FROM registered_groups WHERE jid LIKE 'web:%' AND created_by IS NOT NULL")
+                .all();
+            for (const g of webGroups) {
+                db.prepare(`INSERT OR IGNORE INTO group_members (group_folder, user_id, role, added_at, added_by)
+           VALUES (?, ?, 'owner', ?, ?)`).run(g.folder, g.created_by, new Date().toISOString(), g.created_by);
+            }
+        })();
+    }
+    // v16→v17 migration: rebuild sessions table with composite primary key
+    // Old PK was (group_folder), which cannot store multiple agent sessions per folder.
+    // New PK is (group_folder, COALESCE(agent_id, '')) to support per-agent sessions.
+    const curVer = getRouterStateInternal('schema_version');
+    if (curVer && parseInt(curVer, 10) < 17) {
+        db.transaction(() => {
+            // Check if the old table has single-column PK by inspecting table_info
+            const pkCols = db.prepare("PRAGMA table_info('sessions')").all().filter((c) => c.pk > 0);
+            // Old schema: single PK column 'group_folder'. New schema: composite PK needs rebuild.
+            if (pkCols.length === 1 && pkCols[0].name === 'group_folder') {
+                db.exec(`
+          CREATE TABLE sessions_new (
+            group_folder TEXT NOT NULL,
+            session_id TEXT NOT NULL,
+            agent_id TEXT NOT NULL DEFAULT '',
+            PRIMARY KEY (group_folder, agent_id)
+          );
+          INSERT OR IGNORE INTO sessions_new (group_folder, session_id, agent_id)
+            SELECT group_folder, session_id, COALESCE(agent_id, '') FROM sessions;
+          DROP TABLE sessions;
+          ALTER TABLE sessions_new RENAME TO sessions;
+        `);
+            }
+        })();
+    }
+    // v22: Fix target_main_jid that used folder-based JID (web:${folder})
+    // instead of actual registered group JID (web:${uuid}).
+    // Only affects non-home workspaces where folder != uuid.
+    if (curVer && parseInt(curVer, 10) < 22) {
+        const rows = db
+            .prepare("SELECT jid, target_main_jid FROM registered_groups WHERE target_main_jid IS NOT NULL AND target_main_jid != ''")
+            .all();
+        for (const row of rows) {
+            const targetJid = row.target_main_jid;
+            // Check if target_main_jid is a real registered group JID
+            const exists = db
+                .prepare('SELECT 1 FROM registered_groups WHERE jid = ?')
+                .get(targetJid);
+            if (exists)
+                continue;
+            // Not a valid JID — try to resolve via folder
+            if (!targetJid.startsWith('web:'))
+                continue;
+            const folder = targetJid.slice(4);
+            const candidates = db
+                .prepare("SELECT jid FROM registered_groups WHERE folder = ? AND jid LIKE 'web:%'")
+                .all(folder);
+            if (candidates.length === 1) {
+                db.prepare('UPDATE registered_groups SET target_main_jid = ? WHERE jid = ?').run(candidates[0].jid, row.jid);
+            }
+        }
+    }
+    // v23→v24 migration: billing system initialization
+    ensureColumn('users', 'subscription_plan_id', 'TEXT');
+    const v24Ver = getRouterStateInternal('schema_version');
+    if (!v24Ver || parseInt(v24Ver, 10) < 24) {
+        db.transaction(() => {
+            // Ensure a default free plan exists
+            const existingDefault = db
+                .prepare('SELECT id FROM billing_plans WHERE is_default = 1')
+                .get();
+            if (!existingDefault) {
+                const now = new Date().toISOString();
+                db.prepare(`INSERT OR IGNORE INTO billing_plans (id, name, description, tier, monthly_cost_usd, allow_overage, features, is_default, is_active, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run('free', '免费版', '基础免费套餐', 0, 0, 0, '[]', 1, 1, now, now);
+            }
+            // Initialize balances for all existing users
+            const users = db
+                .prepare("SELECT id FROM users WHERE status != 'deleted'")
+                .all();
+            const now = new Date().toISOString();
+            for (const u of users) {
+                db.prepare('INSERT OR IGNORE INTO user_balances (user_id, balance_usd, total_deposited_usd, total_consumed_usd, updated_at) VALUES (?, 0, 0, 0, ?)').run(u.id, now);
+            }
+            // Create active subscriptions for existing users → free plan
+            const freePlan = db
+                .prepare('SELECT id FROM billing_plans WHERE is_default = 1')
+                .get();
+            if (freePlan) {
+                for (const u of users) {
+                    const existing = db
+                        .prepare("SELECT id FROM user_subscriptions WHERE user_id = ? AND status = 'active'")
+                        .get(u.id);
+                    if (!existing) {
+                        const subId = `sub_${u.id}_${Date.now()}`;
+                        db.prepare(`INSERT INTO user_subscriptions (id, user_id, plan_id, status, started_at, created_at)
+               VALUES (?, ?, ?, 'active', ?, ?)`).run(subId, u.id, freePlan.id, now, now);
+                    }
+                }
+            }
+        })();
+    }
+    // v24→v25 migration: billing system enhancement (daily/weekly quotas, rate_multiplier, trial)
+    ensureColumn('billing_plans', 'daily_cost_quota', 'REAL');
+    ensureColumn('billing_plans', 'weekly_cost_quota', 'REAL');
+    ensureColumn('billing_plans', 'daily_token_quota', 'INTEGER');
+    ensureColumn('billing_plans', 'weekly_token_quota', 'INTEGER');
+    ensureColumn('billing_plans', 'rate_multiplier', 'REAL NOT NULL DEFAULT 1.0');
+    ensureColumn('billing_plans', 'trial_days', 'INTEGER');
+    ensureColumn('billing_plans', 'sort_order', 'INTEGER NOT NULL DEFAULT 0');
+    ensureColumn('billing_plans', 'display_price', 'TEXT');
+    ensureColumn('billing_plans', 'highlight', 'INTEGER NOT NULL DEFAULT 0');
+    ensureColumn('user_subscriptions', 'trial_ends_at', 'TEXT');
+    ensureColumn('user_subscriptions', 'notes', 'TEXT');
+    ensureColumn('redeem_codes', 'batch_id', 'TEXT');
+    // v25→v26 migration: cost_usd on messages + idempotency key for balance transactions
+    ensureColumn('messages', 'cost_usd', 'REAL');
+    // idempotency key for balance transactions
+    ensureColumn('balance_transactions', 'idempotency_key', 'TEXT');
+    ensureColumn('balance_transactions', 'source', "TEXT NOT NULL DEFAULT 'system_adjustment'");
+    ensureColumn('balance_transactions', 'operator_type', "TEXT NOT NULL DEFAULT 'system'");
+    ensureColumn('balance_transactions', 'notes', 'TEXT');
+    // Create unique index only if it doesn't exist
+    db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_bal_tx_idempotency ON balance_transactions(idempotency_key) WHERE idempotency_key IS NOT NULL`);
+    // v26→v27 migration: wallet-first commercialization baseline
+    const v27Ver = getRouterStateInternal('schema_version');
+    if (!v27Ver || parseInt(v27Ver, 10) < 27) {
+        db.transaction(() => {
+            const now = new Date().toISOString();
+            const users = db
+                .prepare("SELECT id, role FROM users WHERE status != 'deleted' AND role != 'admin'")
+                .all();
+            for (const user of users) {
+                db.prepare(`INSERT OR IGNORE INTO user_balances (
+            user_id, balance_usd, total_deposited_usd, total_consumed_usd, updated_at
+          ) VALUES (?, 0, 0, 0, ?)`).run(user.id, now);
+                db.prepare(`UPDATE user_balances
+           SET balance_usd = 0, total_deposited_usd = 0, total_consumed_usd = 0, updated_at = ?
+           WHERE user_id = ?`).run(now, user.id);
+                const hasOpening = db
+                    .prepare("SELECT 1 FROM balance_transactions WHERE user_id = ? AND source = 'migration_opening' LIMIT 1")
+                    .get(user.id);
+                if (!hasOpening) {
+                    db.prepare(`INSERT INTO balance_transactions (
+              user_id, type, amount_usd, balance_after, description, reference_type,
+              reference_id, actor_id, source, operator_type, notes, idempotency_key, created_at
+            ) VALUES (?, 'adjustment', 0, 0, ?, NULL, NULL, NULL, 'migration_opening', 'system', ?, NULL, ?)`).run(user.id, '商业化计费上线初始化', '上线迁移：普通用户默认余额归零，需充值后使用', now);
+                }
+            }
+        })();
+    }
+    // v27→v28: Token usage tables + history migration
+    const v28Check = getRouterStateInternal('schema_version');
+    if (!v28Check || parseInt(v28Check, 10) < 28) {
+        db.transaction(() => {
+            // Count messages with token_usage for logging
+            const countBefore = db
+                .prepare("SELECT COUNT(*) as cnt FROM messages WHERE token_usage IS NOT NULL AND json_extract(token_usage, '$.modelUsage') IS NOT NULL")
+                .get().cnt;
+            // Migrate from messages.token_usage modelUsage into usage_records
+            db.exec(`
+        INSERT OR IGNORE INTO usage_records (id, user_id, group_folder, message_id, model,
+          input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens,
+          cost_usd, duration_ms, num_turns, source, created_at)
+        SELECT
+          lower(hex(randomblob(16))),
+          COALESCE(rg.created_by, 'system'),
+          COALESCE(rg.folder, m.chat_jid),
+          m.id,
+          COALESCE(jme.key, 'unknown'),
+          COALESCE(json_extract(jme.value, '$.inputTokens'), 0),
+          COALESCE(json_extract(jme.value, '$.outputTokens'), 0),
+          0, 0,
+          COALESCE(json_extract(jme.value, '$.costUSD'), 0),
+          COALESCE(json_extract(m.token_usage, '$.durationMs'), 0),
+          COALESCE(json_extract(m.token_usage, '$.numTurns'), 0),
+          'agent',
+          m.timestamp
+        FROM messages m
+          JOIN json_each(json_extract(m.token_usage, '$.modelUsage')) jme
+          LEFT JOIN registered_groups rg ON rg.jid = m.chat_jid
+        WHERE m.token_usage IS NOT NULL
+          AND json_extract(m.token_usage, '$.modelUsage') IS NOT NULL
+      `);
+            // Migrate messages without modelUsage (legacy) using root-level fields
+            db.exec(`
+        INSERT OR IGNORE INTO usage_records (id, user_id, group_folder, message_id, model,
+          input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens,
+          cost_usd, duration_ms, num_turns, source, created_at)
+        SELECT
+          lower(hex(randomblob(16))),
+          COALESCE(rg.created_by, 'system'),
+          COALESCE(rg.folder, m.chat_jid),
+          m.id,
+          'legacy-unknown',
+          COALESCE(json_extract(m.token_usage, '$.inputTokens'), 0),
+          COALESCE(json_extract(m.token_usage, '$.outputTokens'), 0),
+          COALESCE(json_extract(m.token_usage, '$.cacheReadInputTokens'), 0),
+          COALESCE(json_extract(m.token_usage, '$.cacheCreationInputTokens'), 0),
+          COALESCE(json_extract(m.token_usage, '$.costUSD'), 0),
+          COALESCE(json_extract(m.token_usage, '$.durationMs'), 0),
+          COALESCE(json_extract(m.token_usage, '$.numTurns'), 0),
+          'agent',
+          m.timestamp
+        FROM messages m
+          LEFT JOIN registered_groups rg ON rg.jid = m.chat_jid
+        WHERE m.token_usage IS NOT NULL
+          AND (json_extract(m.token_usage, '$.modelUsage') IS NULL
+               OR json_type(json_extract(m.token_usage, '$.modelUsage')) != 'object')
+      `);
+            // Build daily summary from usage_records
+            db.exec(`
+        INSERT OR REPLACE INTO usage_daily_summary (user_id, model, date,
+          total_input_tokens, total_output_tokens,
+          total_cache_read_tokens, total_cache_creation_tokens,
+          total_cost_usd, request_count, updated_at)
+        SELECT
+          user_id, model, date(created_at, 'localtime'),
+          SUM(input_tokens), SUM(output_tokens),
+          SUM(cache_read_input_tokens), SUM(cache_creation_input_tokens),
+          SUM(cost_usd), COUNT(*), datetime('now')
+        FROM usage_records
+        GROUP BY user_id, model, date(created_at, 'localtime')
+      `);
+            const countAfter = db.prepare('SELECT COUNT(*) as cnt FROM usage_records').get().cnt;
+            logger.info({ countBefore, countAfter }, 'Token usage migration v27→v28 completed');
+        })();
+    }
+    // v29 → v30: Add last_im_jid to agents table (#225)
+    if (!db
+        .prepare("PRAGMA table_info('agents')")
+        .all()
+        .some((c) => c.name === 'last_im_jid')) {
+        db.exec('ALTER TABLE agents ADD COLUMN last_im_jid TEXT');
+    }
+    // v31 → v32: Add spawned_from_jid to agents table (spawn parallel tasks)
+    if (!db
+        .prepare("PRAGMA table_info('agents')")
+        .all()
+        .some((c) => c.name === 'spawned_from_jid')) {
+        db.exec('ALTER TABLE agents ADD COLUMN spawned_from_jid TEXT');
+    }
+    const SCHEMA_VERSION = '33';
+    db.prepare('INSERT OR REPLACE INTO router_state (key, value) VALUES (?, ?)').run('schema_version', SCHEMA_VERSION);
+}
+/**
+ * Store chat metadata only (no message content).
+ * Used for all chats to enable group discovery without storing sensitive content.
+ */
+export function storeChatMetadata(chatJid, timestamp, name) {
+    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 for existing chats.
+ * New chats get the current time as their initial timestamp.
+ * Used during group metadata sync.
+ */
+export function updateChatName(chatJid, name) {
+    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().toISOString());
+}
+/**
+ * Get all known chats, ordered by most recent activity.
+ */
+export function getAllChats() {
+    return db
+        .prepare(`
+    SELECT jid, name, last_message_time
+    FROM chats
+    ORDER BY last_message_time DESC
+  `)
+        .all();
+}
+/**
+ * Get timestamp of last group metadata sync.
+ */
+export function getLastGroupSync() {
+    // Store sync time in a special chat entry
+    const row = db
+        .prepare(`SELECT last_message_time FROM chats WHERE jid = '__group_sync__'`)
+        .get();
+    return row?.last_message_time || null;
+}
+/**
+ * Record that group metadata was synced.
+ */
+export function setLastGroupSync() {
+    const now = new Date().toISOString();
+    db.prepare(`INSERT OR REPLACE INTO chats (jid, name, last_message_time) VALUES ('__group_sync__', '__group_sync__', ?)`).run(now);
+}
+/**
+ * Ensure a chat row exists in the chats table (avoids FK violation on messages insert).
+ */
+export function ensureChatExists(chatJid) {
+    db.prepare(`INSERT OR IGNORE INTO chats (jid, name, last_message_time) VALUES (?, ?, ?)`).run(chatJid, chatJid, new Date().toISOString());
+}
+/**
+ * Store a message with full content (channel-agnostic).
+ * Only call this for registered groups where message history is needed.
+ */
+export function storeMessageDirect(msgId, chatJid, sender, senderName, content, timestamp, isFromMe, opts) {
+    const { attachments, tokenUsage, sourceJid, meta } = opts ?? {};
+    const existingFinalRow = meta?.sourceKind === 'sdk_final' && meta.turnId
+        ? stmts().storeMessageSelect.get(chatJid, meta.turnId)
+        : undefined;
+    const effectiveMsgId = existingFinalRow?.id || msgId;
+    stmts().storeMessageInsert.run(effectiveMsgId, chatJid, sourceJid ?? chatJid, sender, senderName, content, timestamp, isFromMe ? 1 : 0, attachments ?? null, tokenUsage ?? null, serializeRuntimeIdentity(meta?.runtimeIdentity), meta?.turnId ?? null, meta?.sessionId ?? null, meta?.sdkMessageUuid ?? null, meta?.sourceKind ?? null, meta?.finalizationReason ?? null);
+    return effectiveMsgId;
+}
+/**
+ * Update the token_usage field on a specific agent message, or fall back to
+ * the most recent agent message without token_usage for the given chat.
+ * When msgId is provided, uses precise `WHERE id = ? AND chat_jid = ?` match
+ * to avoid race conditions in concurrent scenarios.
+ */
+export function updateLatestMessageTokenUsage(chatJid, tokenUsage, msgId, costUsd) {
+    if (msgId) {
+        stmts().updateTokenUsageById.run(tokenUsage, costUsd ?? null, msgId, chatJid);
+    }
+    else {
+        stmts().updateTokenUsageLatest.run(tokenUsage, costUsd ?? null, chatJid);
+    }
+}
+/**
+ * Get token usage statistics aggregated by date.
+ */
+export function getTokenUsageStats(days, chatJids) {
+    const since = new Date();
+    since.setDate(since.getDate() - days);
+    const sinceStr = since.toISOString();
+    const jidFilter = chatJids && chatJids.length > 0
+        ? `AND m.chat_jid IN (${chatJids.map(() => '?').join(',')})`
+        : '';
+    const params = [sinceStr, ...(chatJids || [])];
+    const baseQuery = `
+    SELECT
+      date(m.timestamp) as date,
+      json_extract(m.token_usage, '$.modelUsage') as model_usage_json,
+      json_extract(m.token_usage, '$.inputTokens') as input_tokens,
+      json_extract(m.token_usage, '$.outputTokens') as output_tokens,
+      json_extract(m.token_usage, '$.cacheReadInputTokens') as cache_read_tokens,
+      json_extract(m.token_usage, '$.cacheCreationInputTokens') as cache_creation_tokens,
+      json_extract(m.token_usage, '$.costUSD') as cost_usd
+    FROM messages m
+    WHERE m.token_usage IS NOT NULL
+      AND m.timestamp >= ?
+      ${jidFilter}
+    ORDER BY m.timestamp ASC
+  `;
+    const rows = db.prepare(baseQuery).all(...params);
+    const aggregated = new Map();
+    function addToAggregated(date, model, inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens, costUsd) {
+        const key = `${date}|${model}`;
+        const existing = aggregated.get(key);
+        if (existing) {
+            existing.input_tokens += inputTokens;
+            existing.output_tokens += outputTokens;
+            existing.cache_read_tokens += cacheReadTokens;
+            existing.cache_creation_tokens += cacheCreationTokens;
+            existing.cost_usd += costUsd;
+            existing.message_count += 1;
+        }
+        else {
+            aggregated.set(key, {
+                date,
+                model,
+                input_tokens: inputTokens,
+                output_tokens: outputTokens,
+                cache_read_tokens: cacheReadTokens,
+                cache_creation_tokens: cacheCreationTokens,
+                cost_usd: costUsd,
+                message_count: 1,
+            });
+        }
+    }
+    for (const row of rows) {
+        if (row.model_usage_json) {
+            try {
+                const modelUsage = JSON.parse(row.model_usage_json);
+                for (const [model, usage] of Object.entries(modelUsage)) {
+                    addToAggregated(row.date, model, usage.inputTokens || 0, usage.outputTokens || 0, 0, 0, usage.costUSD || 0);
+                }
+            }
+            catch (e) {
+                logger.warn({ date: row.date, error: e }, 'Failed to parse model_usage_json');
+                // fallback: use aggregate fields
+                addToAggregated(row.date, 'unknown', row.input_tokens || 0, row.output_tokens || 0, row.cache_read_tokens || 0, row.cache_creation_tokens || 0, row.cost_usd || 0);
+            }
+        }
+        else {
+            addToAggregated(row.date, 'unknown', row.input_tokens || 0, row.output_tokens || 0, row.cache_read_tokens || 0, row.cache_creation_tokens || 0, row.cost_usd || 0);
+        }
+    }
+    return Array.from(aggregated.values());
+}
+/**
+ * Get token usage summary totals.
+ */
+export function getTokenUsageSummary(days, chatJids) {
+    const since = new Date();
+    since.setDate(since.getDate() - days);
+    const sinceStr = since.toISOString();
+    const jidFilter = chatJids && chatJids.length > 0
+        ? `AND chat_jid IN (${chatJids.map(() => '?').join(',')})`
+        : '';
+    const params = [sinceStr, ...(chatJids || [])];
+    const row = db
+        .prepare(`
+    SELECT
+      COALESCE(SUM(json_extract(token_usage, '$.inputTokens')), 0) as total_input,
+      COALESCE(SUM(json_extract(token_usage, '$.outputTokens')), 0) as total_output,
+      COALESCE(SUM(json_extract(token_usage, '$.cacheReadInputTokens')), 0) as total_cache_read,
+      COALESCE(SUM(json_extract(token_usage, '$.cacheCreationInputTokens')), 0) as total_cache_creation,
+      COALESCE(SUM(json_extract(token_usage, '$.costUSD')), 0) as total_cost,
+      COUNT(*) as total_messages,
+      COUNT(DISTINCT date(timestamp)) as total_active_days
+    FROM messages
+    WHERE token_usage IS NOT NULL AND timestamp >= ?
+      ${jidFilter}
+  `)
+        .get(...params);
+    return {
+        totalInputTokens: row.total_input,
+        totalOutputTokens: row.total_output,
+        totalCacheReadTokens: row.total_cache_read,
+        totalCacheCreationTokens: row.total_cache_creation,
+        totalCostUSD: row.total_cost,
+        totalMessages: row.total_messages,
+        totalActiveDays: row.total_active_days,
+    };
+}
+/**
+ * Get a local timezone date string (YYYY-MM-DD) from a Date or ISO string.
+ */
+function toLocalDateString(date) {
+    const d = date ? new Date(date) : new Date();
+    const year = d.getFullYear();
+    const month = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+/**
+ * Insert a usage record and update daily summary.
+ */
+export function insertUsageRecord(record) {
+    const id = crypto.randomUUID();
+    const now = new Date().toISOString();
+    const localDate = toLocalDateString();
+    db.transaction(() => {
+        stmts().insertUsageInsert.run(id, record.userId, record.groupFolder, record.agentId ?? null, record.messageId ?? null, record.model, record.inputTokens, record.outputTokens, record.cacheReadInputTokens, record.cacheCreationInputTokens, record.costUSD, record.durationMs ?? 0, record.numTurns ?? 0, record.source ?? 'agent', now);
+        stmts().insertUsageUpsert.run(record.userId, record.model, localDate, record.inputTokens, record.outputTokens, record.cacheReadInputTokens, record.cacheCreationInputTokens, record.costUSD);
+    })();
+}
+/**
+ * Get usage stats from daily summary table (fixes timezone + token KPI issues).
+ */
+export function getUsageDailyStats(days, userId, modelFilter) {
+    const sinceDate = toLocalDateString(new Date(Date.now() - days * 86400000));
+    const conditions = ['date >= ?'];
+    const params = [sinceDate];
+    if (userId) {
+        conditions.push('user_id = ?');
+        params.push(userId);
+    }
+    if (modelFilter) {
+        conditions.push('model = ?');
+        params.push(modelFilter);
+    }
+    const whereClause = conditions.join(' AND ');
+    return db
+        .prepare(`
+    SELECT date, model, user_id,
+      total_input_tokens as input_tokens,
+      total_output_tokens as output_tokens,
+      total_cache_read_tokens as cache_read_tokens,
+      total_cache_creation_tokens as cache_creation_tokens,
+      total_cost_usd as cost_usd,
+      request_count
+    FROM usage_daily_summary
+    WHERE ${whereClause}
+    ORDER BY date ASC
+  `)
+        .all(...params);
+}
+/**
+ * Get usage summary from daily summary table.
+ */
+export function getUsageDailySummary(days, userId, modelFilter) {
+    const sinceDate = toLocalDateString(new Date(Date.now() - days * 86400000));
+    const conditions = ['date >= ?'];
+    const params = [sinceDate];
+    if (userId) {
+        conditions.push('user_id = ?');
+        params.push(userId);
+    }
+    if (modelFilter) {
+        conditions.push('model = ?');
+        params.push(modelFilter);
+    }
+    const whereClause = conditions.join(' AND ');
+    const row = db
+        .prepare(`
+    SELECT
+      COALESCE(SUM(total_input_tokens), 0) as total_input,
+      COALESCE(SUM(total_output_tokens), 0) as total_output,
+      COALESCE(SUM(total_cache_read_tokens), 0) as total_cache_read,
+      COALESCE(SUM(total_cache_creation_tokens), 0) as total_cache_creation,
+      COALESCE(SUM(total_cost_usd), 0) as total_cost,
+      COALESCE(SUM(request_count), 0) as total_messages,
+      COUNT(DISTINCT date) as total_active_days
+    FROM usage_daily_summary
+    WHERE ${whereClause}
+  `)
+        .get(...params);
+    return {
+        totalInputTokens: row.total_input,
+        totalOutputTokens: row.total_output,
+        totalCacheReadTokens: row.total_cache_read,
+        totalCacheCreationTokens: row.total_cache_creation,
+        totalCostUSD: row.total_cost,
+        totalMessages: row.total_messages,
+        totalActiveDays: row.total_active_days,
+    };
+}
+/**
+ * Get list of all models that have usage data.
+ */
+export function getUsageModels() {
+    const rows = db
+        .prepare('SELECT DISTINCT model FROM usage_daily_summary ORDER BY model')
+        .all();
+    return rows.map((r) => r.model);
+}
+/**
+ * Get list of users that have usage data.
+ */
+export function getUsageUsers() {
+    const rows = db
+        .prepare(`
+    SELECT DISTINCT uds.user_id as id, COALESCE(u.username, uds.user_id) as username
+    FROM usage_daily_summary uds
+    LEFT JOIN users u ON u.id = uds.user_id
+    ORDER BY u.username
+  `)
+        .all();
+    return rows;
+}
+export function getNewMessages(jids, cursor) {
+    if (jids.length === 0)
+        return { messages: [], newCursor: cursor };
+    const rows = getNewMessagesStmt(jids.length).all(cursor.timestamp, cursor.timestamp, cursor.id, ...jids);
+    const messages = rows.map((row) => ({
+        ...mapDbMessageRow(row),
+    }));
+    const last = messages[messages.length - 1];
+    return {
+        messages,
+        newCursor: last ? { timestamp: last.timestamp, id: last.id } : cursor,
+    };
+}
+export function getMessagesSince(chatJid, cursor) {
+    const rows = stmts().getMessagesSince.all(chatJid, cursor.timestamp, cursor.timestamp, cursor.id);
+    return rows.map((row) => ({
+        ...row,
+        runtime_identity: parseRuntimeIdentity(row.runtime_identity),
+    }));
+}
+export function createTask(task) {
+    db.prepare(`
+    INSERT INTO scheduled_tasks (id, group_folder, chat_jid, prompt, schedule_type, schedule_value, context_mode, execution_type, script_command, execution_mode, next_run, status, created_at, created_by, notify_channels)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(task.id, task.group_folder, task.chat_jid, task.prompt, task.schedule_type, task.schedule_value, task.context_mode || 'group', task.execution_type || 'agent', task.script_command ?? null, task.execution_mode ?? null, task.next_run, task.status, task.created_at, task.created_by ?? null, task.notify_channels != null ? JSON.stringify(task.notify_channels) : null);
+}
+/** Parse notify_channels from JSON string stored in DB and normalize new fields */
+function mapTaskRow(row) {
+    const r = row;
+    if (typeof r.notify_channels === 'string') {
+        try {
+            r.notify_channels = JSON.parse(r.notify_channels);
+        }
+        catch {
+            r.notify_channels = null;
+        }
+    }
+    else if (r.notify_channels === undefined) {
+        r.notify_channels = null;
+    }
+    // Normalize new nullable fields
+    if (r.execution_mode === undefined)
+        r.execution_mode = null;
+    if (r.workspace_jid === undefined)
+        r.workspace_jid = null;
+    if (r.workspace_folder === undefined)
+        r.workspace_folder = null;
+    return r;
+}
+export function getTaskById(id) {
+    const row = db.prepare('SELECT * FROM scheduled_tasks WHERE id = ?').get(id);
+    return row ? mapTaskRow(row) : undefined;
+}
+export function getTasksForGroup(groupFolder) {
+    return db
+        .prepare('SELECT * FROM scheduled_tasks WHERE group_folder = ? ORDER BY created_at DESC')
+        .all(groupFolder)
+        .map(mapTaskRow);
+}
+export function getAllTasks() {
+    return db
+        .prepare('SELECT * FROM scheduled_tasks ORDER BY created_at DESC')
+        .all()
+        .map(mapTaskRow);
+}
+export function updateTask(id, updates) {
+    const fields = [];
+    const values = [];
+    if (updates.prompt !== undefined) {
+        fields.push('prompt = ?');
+        values.push(updates.prompt);
+    }
+    if (updates.schedule_type !== undefined) {
+        fields.push('schedule_type = ?');
+        values.push(updates.schedule_type);
+    }
+    if (updates.schedule_value !== undefined) {
+        fields.push('schedule_value = ?');
+        values.push(updates.schedule_value);
+    }
+    if (updates.context_mode !== undefined) {
+        fields.push('context_mode = ?');
+        values.push(updates.context_mode);
+    }
+    if (updates.execution_type !== undefined) {
+        fields.push('execution_type = ?');
+        values.push(updates.execution_type);
+    }
+    if (updates.execution_mode !== undefined) {
+        fields.push('execution_mode = ?');
+        values.push(updates.execution_mode);
+    }
+    if (updates.script_command !== undefined) {
+        fields.push('script_command = ?');
+        values.push(updates.script_command);
+    }
+    if (updates.next_run !== undefined) {
+        fields.push('next_run = ?');
+        values.push(updates.next_run);
+    }
+    if (updates.status !== undefined) {
+        fields.push('status = ?');
+        values.push(updates.status);
+    }
+    if (updates.notify_channels !== undefined) {
+        fields.push('notify_channels = ?');
+        values.push(updates.notify_channels != null
+            ? JSON.stringify(updates.notify_channels)
+            : null);
+    }
+    if (fields.length === 0)
+        return;
+    values.push(id);
+    db.prepare(`UPDATE scheduled_tasks SET ${fields.join(', ')} WHERE id = ?`).run(...values);
+}
+export function updateTaskWorkspace(id, workspaceJid, workspaceFolder) {
+    db.prepare('UPDATE scheduled_tasks SET workspace_jid = ?, workspace_folder = ? WHERE id = ?').run(workspaceJid, workspaceFolder, id);
+}
+export function deleteTask(id) {
+    // Delete child records first (FK constraint)
+    db.prepare('DELETE FROM task_run_logs WHERE task_id = ?').run(id);
+    db.prepare('DELETE FROM scheduled_tasks WHERE id = ?').run(id);
+}
+export function deleteTasksForGroup(groupFolder) {
+    const tx = db.transaction((folder) => {
+        db.prepare(`
+      DELETE FROM task_run_logs
+      WHERE task_id IN (
+        SELECT id FROM scheduled_tasks WHERE group_folder = ?
+      )
+      `).run(folder);
+        db.prepare('DELETE FROM scheduled_tasks WHERE group_folder = ?').run(folder);
+    });
+    tx(groupFolder);
+}
+export function getDueTasks() {
+    const now = new Date().toISOString();
+    return db
+        .prepare(`
+    SELECT * FROM scheduled_tasks
+    WHERE status = 'active' AND next_run IS NOT NULL AND next_run <= ?
+    ORDER BY next_run
+  `)
+        .all(now)
+        .map(mapTaskRow);
+}
+export function updateTaskAfterRun(id, nextRun, lastResult) {
+    const now = new Date().toISOString();
+    db.prepare(`
+    UPDATE scheduled_tasks
+    SET next_run = ?, last_run = ?, last_result = ?, status = CASE WHEN ? IS NULL THEN 'completed' ELSE status END
+    WHERE id = ?
+  `).run(nextRun, now, lastResult, nextRun, id);
+}
+export function logTaskRun(log) {
+    db.prepare(`
+    INSERT INTO task_run_logs (task_id, run_at, duration_ms, status, result, error)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(log.task_id, log.run_at, log.duration_ms, log.status, log.result, log.error);
+}
+export function logTaskRunStart(taskId) {
+    const result = db
+        .prepare(`
+    INSERT INTO task_run_logs (task_id, run_at, duration_ms, status, result, error)
+    VALUES (?, ?, 0, 'running', NULL, NULL)
+  `)
+        .run(taskId, new Date().toISOString());
+    return Number(result.lastInsertRowid);
+}
+export function updateTaskRunLog(id, updates) {
+    db.prepare(`
+    UPDATE task_run_logs SET duration_ms = ?, status = ?, result = ?, error = ?
+    WHERE id = ?
+  `).run(updates.duration_ms, updates.status, updates.result, updates.error, id);
+}
+export function cleanupStaleRunningLogs() {
+    const result = db
+        .prepare(`
+    UPDATE task_run_logs SET status = 'error', error = 'Process crashed before completion'
+    WHERE status = 'running'
+  `)
+        .run();
+    return result.changes;
+}
+export function cleanupOldTaskRunLogs(retentionDays = 30) {
+    const cutoff = new Date(Date.now() - retentionDays * 24 * 60 * 60 * 1000).toISOString();
+    const result = db
+        .prepare(`DELETE FROM task_run_logs WHERE run_at < ?`)
+        .run(cutoff);
+    return result.changes;
+}
+export function cleanupOldDailyUsage(retentionDays = 90) {
+    const cutoff = new Date(Date.now() - retentionDays * 24 * 60 * 60 * 1000)
+        .toISOString()
+        .slice(0, 10);
+    const result = db
+        .prepare('DELETE FROM daily_usage WHERE date < ?')
+        .run(cutoff);
+    return result.changes;
+}
+export function cleanupOldBillingAuditLog(retentionDays = 365) {
+    const cutoff = new Date(Date.now() - retentionDays * 24 * 60 * 60 * 1000).toISOString();
+    const result = db
+        .prepare('DELETE FROM billing_audit_log WHERE created_at < ?')
+        .run(cutoff);
+    return result.changes;
+}
+// --- Router state accessors ---
+export function getRouterState(key) {
+    const row = db
+        .prepare('SELECT value FROM router_state WHERE key = ?')
+        .get(key);
+    return row?.value;
+}
+export function setRouterState(key, value) {
+    db.prepare('INSERT OR REPLACE INTO router_state (key, value) VALUES (?, ?)').run(key, value);
+}
+export function deleteRouterState(key) {
+    db.prepare('DELETE FROM router_state WHERE key = ?').run(key);
+}
+export function getRouterStateByPrefix(prefix) {
+    return db
+        .prepare('SELECT key, value FROM router_state WHERE key LIKE ?')
+        .all(`${prefix}%`);
+}
+// --- Session accessors ---
+export function getSession(groupFolder, agentId) {
+    const effectiveAgentId = agentId || '';
+    const row = db
+        .prepare('SELECT session_id FROM sessions WHERE group_folder = ? AND agent_id = ?')
+        .get(groupFolder, effectiveAgentId);
+    return row?.session_id;
+}
+export function setSession(groupFolder, sessionId, agentId) {
+    const effectiveAgentId = agentId || '';
+    db.prepare(`INSERT INTO sessions (group_folder, session_id, agent_id) VALUES (?, ?, ?)
+     ON CONFLICT(group_folder, agent_id) DO UPDATE SET session_id = excluded.session_id`).run(groupFolder, sessionId, effectiveAgentId);
+}
+export function deleteSession(groupFolder, agentId) {
+    const effectiveAgentId = agentId || '';
+    db.prepare('DELETE FROM sessions WHERE group_folder = ? AND agent_id = ?').run(groupFolder, effectiveAgentId);
+}
+export function deleteAllSessionsForFolder(groupFolder) {
+    db.prepare('DELETE FROM sessions WHERE group_folder = ?').run(groupFolder);
+}
+export function getAllSessions() {
+    const rows = db
+        .prepare("SELECT group_folder, session_id FROM sessions WHERE agent_id = ''")
+        .all();
+    const result = {};
+    for (const row of rows) {
+        result[row.group_folder] = row.session_id;
+    }
+    return result;
+}
+// --- Registered group accessors ---
+function parseExecutionMode(raw, context) {
+    if (raw === 'container' || raw === 'host')
+        return raw;
+    if (raw !== null && raw !== '') {
+        console.warn(`Invalid execution_mode "${raw}" for ${context}, falling back to "container"`);
+    }
+    return 'container';
+}
+function parseAgentType(raw) {
+    return raw === 'codex' ? 'codex' : 'claude';
+}
+/** Convert a raw DB row into a RegisteredGroup domain object. */
+function parseGroupRow(row) {
+    return {
+        jid: row.jid,
+        name: row.name,
+        folder: row.folder,
+        added_at: row.added_at,
+        containerConfig: row.container_config
+            ? JSON.parse(row.container_config)
+            : undefined,
+        agentType: parseAgentType(row.agent_type),
+        executionMode: parseExecutionMode(row.execution_mode, `group ${row.jid}`),
+        model: row.model ?? null,
+        reasoningEffort: row.reasoning_effort ?? null,
+        customCwd: row.custom_cwd ?? undefined,
+        initSourcePath: row.init_source_path ?? undefined,
+        initGitUrl: row.init_git_url ?? undefined,
+        created_by: row.created_by ?? undefined,
+        is_home: row.is_home === 1,
+        target_agent_id: row.target_agent_id ?? undefined,
+        target_main_jid: row.target_main_jid ?? undefined,
+        reply_policy: row.reply_policy === 'mirror' ? 'mirror' : 'source_only',
+        require_mention: row.require_mention === 1,
+        activation_mode: parseActivationMode(row.activation_mode),
+    };
+}
+const VALID_ACTIVATION_MODES = new Set([
+    'auto',
+    'always',
+    'when_mentioned',
+    'disabled',
+]);
+function parseActivationMode(raw) {
+    if (raw && VALID_ACTIVATION_MODES.has(raw))
+        return raw;
+    return 'auto';
+}
+export function getRegisteredGroup(jid) {
+    const row = db
+        .prepare('SELECT * FROM registered_groups WHERE jid = ?')
+        .get(jid);
+    if (!row)
+        return undefined;
+    return parseGroupRow(row);
+}
+export function setRegisteredGroup(jid, group) {
+    db.prepare(`INSERT OR REPLACE INTO registered_groups (jid, name, folder, added_at, container_config, agent_type, execution_mode, model, reasoning_effort, custom_cwd, init_source_path, init_git_url, created_by, is_home, selected_skills, target_agent_id, target_main_jid, reply_policy, require_mention, activation_mode, mcp_mode, selected_mcps)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(jid, group.name, group.folder, group.added_at, group.containerConfig ? JSON.stringify(group.containerConfig) : null, group.agentType ?? 'claude', group.executionMode ?? 'container', group.model ?? null, group.reasoningEffort ?? null, group.customCwd ?? null, group.initSourcePath ?? null, group.initGitUrl ?? null, group.created_by ?? null, group.is_home ? 1 : 0, null, // selected_skills: deprecated, always null (user-level skills apply globally)
+    group.target_agent_id ?? null, group.target_main_jid ?? null, group.reply_policy ?? 'source_only', group.require_mention === true ? 1 : 0, group.activation_mode ?? 'auto', 'inherit', // mcp_mode: deprecated, always inherit (user-level MCP applies globally)
+    null);
+}
+export function deleteRegisteredGroup(jid) {
+    db.prepare('DELETE FROM registered_groups WHERE jid = ?').run(jid);
+}
+/** Get all JIDs that share the same folder (e.g., all JIDs with folder='main'). */
+export function getJidsByFolder(folder) {
+    const rows = db
+        .prepare('SELECT jid FROM registered_groups WHERE folder = ?')
+        .all(folder);
+    return rows.map((r) => r.jid);
+}
+/** Check if any registered group uses container execution mode (efficient targeted query). */
+export function hasContainerModeGroups() {
+    const row = db
+        .prepare("SELECT 1 FROM registered_groups WHERE execution_mode = 'container' OR execution_mode IS NULL LIMIT 1")
+        .get();
+    return row !== undefined;
+}
+export function getAllRegisteredGroups() {
+    const rows = db
+        .prepare('SELECT * FROM registered_groups')
+        .all();
+    const result = {};
+    for (const row of rows) {
+        result[row.jid] = parseGroupRow(row);
+    }
+    return result;
+}
+/**
+ * Get all registered groups that route to a specific conversation agent.
+ * Returns array of { jid, group } for each IM group targeting the given agentId.
+ */
+export function getGroupsByTargetAgent(agentId) {
+    const rows = db
+        .prepare('SELECT * FROM registered_groups WHERE target_agent_id = ?')
+        .all(agentId);
+    return rows.map((row) => ({ jid: row.jid, group: parseGroupRow(row) }));
+}
+/**
+ * Get all registered groups that route to a specific workspace's main conversation.
+ */
+export function getGroupsByTargetMainJid(webJid) {
+    const rows = db
+        .prepare('SELECT * FROM registered_groups WHERE target_main_jid = ?')
+        .all(webJid);
+    return rows.map((row) => ({ jid: row.jid, group: parseGroupRow(row) }));
+}
+/**
+ * Find a user's home group (is_home=1 + created_by=userId).
+ * For admin users, also matches web:main even if created_by differs
+ * (all admins share folder=main).
+ */
+export function getUserHomeGroup(userId) {
+    // First try exact match: is_home=1 AND created_by=userId
+    let row = db
+        .prepare('SELECT * FROM registered_groups WHERE is_home = 1 AND created_by = ?')
+        .get(userId);
+    // Fallback for admin users: all admins share web:main (folder=main).
+    // If no exact match, check if the user is an admin and web:main exists.
+    if (!row) {
+        const user = db
+            .prepare("SELECT role FROM users WHERE id = ? AND status = 'active'")
+            .get(userId);
+        if (user?.role === 'admin') {
+            row = db
+                .prepare("SELECT * FROM registered_groups WHERE jid = 'web:main' AND is_home = 1")
+                .get();
+        }
+    }
+    if (!row)
+        return undefined;
+    return parseGroupRow(row);
+}
+/**
+ * Ensure a user has a home group. If not, create one.
+ * Admin gets folder='main' with executionMode='host'.
+ * Member gets folder='home-{userId}' with executionMode='container'.
+ * Returns the JID of the home group.
+ */
+export function ensureUserHomeGroup(userId, role, username) {
+    const existing = getUserHomeGroup(userId);
+    if (existing)
+        return existing.jid;
+    const now = new Date().toISOString();
+    const isAdmin = role === 'admin';
+    const jid = isAdmin ? 'web:main' : `web:home-${userId}`;
+    const folder = isAdmin ? 'main' : `home-${userId}`;
+    // For admin: check if web:main already exists (created by another admin)
+    // In that case, reuse it rather than overwriting created_by
+    if (isAdmin) {
+        const existingMain = getRegisteredGroup(jid);
+        if (existingMain) {
+            // web:main already exists.
+            // Ensure is_home, created_by, and executionMode are correct for owner-based routing.
+            const patched = { ...existingMain };
+            let changed = false;
+            if (!patched.is_home) {
+                patched.is_home = true;
+                changed = true;
+            }
+            if (!patched.created_by) {
+                patched.created_by = userId;
+                changed = true;
+            }
+            // Admin home container must use host mode
+            if (patched.executionMode !== 'host') {
+                patched.executionMode = 'host';
+                changed = true;
+            }
+            if (changed) {
+                setRegisteredGroup(jid, patched);
+            }
+            ensureChatExists(jid);
+            return jid;
+        }
+    }
+    const name = username ? `${username} Home` : isAdmin ? 'Main' : 'Home';
+    const group = {
+        name,
+        folder,
+        added_at: now,
+        agentType: 'claude',
+        executionMode: isAdmin ? 'host' : 'container',
+        created_by: userId,
+        is_home: true,
+    };
+    setRegisteredGroup(jid, group);
+    // Ensure chat row exists
+    ensureChatExists(jid);
+    // Create user-global memory directory and initialize AGENTS.md from template
+    const userGlobalDir = path.join(GROUPS_DIR, 'user-global', userId);
+    fs.mkdirSync(userGlobalDir, { recursive: true });
+    const userAgentMemory = getAgentMemoryPath(userGlobalDir);
+    if (!fs.existsSync(userAgentMemory)) {
+        const templatePath = resolveAppPath('config', AGENT_MEMORY_TEMPLATE_FILENAME);
+        if (fs.existsSync(templatePath)) {
+            try {
+                fs.writeFileSync(userAgentMemory, fs.readFileSync(templatePath, 'utf-8'), {
+                    flag: 'wx',
+                });
+            }
+            catch {
+                // EEXIST race or read error — ignore
+            }
+        }
+    }
+    return jid;
+}
+export function deleteChatHistory(chatJid) {
+    const tx = db.transaction((jid) => {
+        db.prepare('DELETE FROM messages WHERE chat_jid = ?').run(jid);
+        db.prepare('DELETE FROM chats WHERE jid = ?').run(jid);
+    });
+    tx(chatJid);
+}
+export function deleteGroupData(jid, folder) {
+    const tx = db.transaction(() => {
+        // 1. 删除定时任务运行日志 + 定时任务
+        db.prepare('DELETE FROM task_run_logs WHERE task_id IN (SELECT id FROM scheduled_tasks WHERE group_folder = ?)').run(folder);
+        db.prepare('DELETE FROM scheduled_tasks WHERE group_folder = ?').run(folder);
+        // 2. 删除成员记录
+        db.prepare('DELETE FROM group_members WHERE group_folder = ?').run(folder);
+        // 3. 删除注册信息
+        db.prepare('DELETE FROM registered_groups WHERE jid = ?').run(jid);
+        // 4. 删除会话
+        db.prepare('DELETE FROM sessions WHERE group_folder = ?').run(folder);
+        // 5. 删除聊天记录
+        db.prepare('DELETE FROM messages WHERE chat_jid = ?').run(jid);
+        db.prepare('DELETE FROM chats WHERE jid = ?').run(jid);
+        // 6. 删除 pin 记录
+        db.prepare('DELETE FROM user_pinned_groups WHERE jid = ?').run(jid);
+        // 7. 清除定时任务的工作区关联（任务本身不删，只断开绑定）
+        db.prepare('UPDATE scheduled_tasks SET workspace_jid = NULL, workspace_folder = NULL WHERE workspace_jid = ?').run(jid);
+    });
+    tx();
+}
+// --- User pinned groups ---
+export function getUserPinnedGroups(userId) {
+    const rows = db
+        .prepare('SELECT jid, pinned_at FROM user_pinned_groups WHERE user_id = ?')
+        .all(userId);
+    const result = {};
+    for (const row of rows)
+        result[row.jid] = row.pinned_at;
+    return result;
+}
+export function pinGroup(userId, jid) {
+    const pinned_at = new Date().toISOString();
+    db.prepare('INSERT OR REPLACE INTO user_pinned_groups (user_id, jid, pinned_at) VALUES (?, ?, ?)').run(userId, jid, pinned_at);
+    return pinned_at;
+}
+export function unpinGroup(userId, jid) {
+    db.prepare('DELETE FROM user_pinned_groups WHERE user_id = ? AND jid = ?').run(userId, jid);
+}
+// --- Web API accessors ---
+/**
+ * Get paginated messages for a chat, cursor-based pagination.
+ * Returns messages in descending timestamp order (newest first).
+ */
+export function getMessagesPage(chatJid, before, limit = 50) {
+    const normalizedBefore = normalizeHistoryCursor(before, chatJid);
+    const sql = normalizedBefore
+        ? normalizedBefore.precise
+            ? `
+      SELECT id, chat_jid, source_jid, runtime_identity, sender, sender_name, content, timestamp, is_from_me, attachments, token_usage,
+             turn_id, session_id, sdk_message_uuid, source_kind, finalization_reason
+      FROM messages
+      WHERE chat_jid = ?
+        AND (timestamp < ? OR (timestamp = ? AND id < ?))
+      ORDER BY timestamp DESC, id DESC
+      LIMIT ?
+    `
+            : `
+      SELECT id, chat_jid, source_jid, runtime_identity, sender, sender_name, content, timestamp, is_from_me, attachments, token_usage,
+             turn_id, session_id, sdk_message_uuid, source_kind, finalization_reason
+      FROM messages
+      WHERE chat_jid = ? AND timestamp < ?
+      ORDER BY timestamp DESC
+      LIMIT ?
+    `
+        : `
+      SELECT id, chat_jid, source_jid, runtime_identity, sender, sender_name, content, timestamp, is_from_me, attachments, token_usage,
+             turn_id, session_id, sdk_message_uuid, source_kind, finalization_reason
+      FROM messages
+      WHERE chat_jid = ?
+      ORDER BY timestamp DESC
+      LIMIT ?
+    `;
+    const params = normalizedBefore
+        ? normalizedBefore.precise
+            ? [
+                chatJid,
+                normalizedBefore.timestamp,
+                normalizedBefore.timestamp,
+                normalizedBefore.id,
+                limit,
+            ]
+            : [chatJid, normalizedBefore.timestamp, limit]
+        : [chatJid, limit];
+    const rows = db.prepare(sql).all(...params);
+    return rows.map(mapDbMessageRow);
+}
+/**
+ * Get messages after a given timestamp (for polling new messages).
+ * Returns in ASC order (oldest first).
+ */
+export function getMessagesAfter(chatJid, after, limit = 50) {
+    const normalizedAfter = normalizeHistoryCursor(after, chatJid);
+    const rows = db
+        .prepare(normalizedAfter?.precise
+        ? `SELECT id, chat_jid, source_jid, runtime_identity, sender, sender_name, content, timestamp, is_from_me, attachments, token_usage,
+              turn_id, session_id, sdk_message_uuid, source_kind, finalization_reason
+       FROM messages
+       WHERE chat_jid = ?
+         AND (timestamp > ? OR (timestamp = ? AND id > ?))
+       ORDER BY timestamp ASC, id ASC
+       LIMIT ?`
+        : `SELECT id, chat_jid, source_jid, runtime_identity, sender, sender_name, content, timestamp, is_from_me, attachments, token_usage,
+              turn_id, session_id, sdk_message_uuid, source_kind, finalization_reason
+       FROM messages
+       WHERE chat_jid = ? AND timestamp > ?
+       ORDER BY timestamp ASC
+       LIMIT ?`)
+        .all(...(normalizedAfter?.precise
+        ? [
+            chatJid,
+            normalizedAfter.timestamp,
+            normalizedAfter.timestamp,
+            normalizedAfter.id,
+            limit,
+        ]
+        : [chatJid, normalizedAfter?.timestamp || '', limit]));
+    return rows.map(mapDbMessageRow);
+}
+function normalizeHistoryCursor(cursor, fallbackChatJid) {
+    if (!cursor)
+        return undefined;
+    if (typeof cursor === 'string') {
+        return {
+            timestamp: cursor,
+            chat_jid: fallbackChatJid || '',
+            id: '',
+            precise: false,
+        };
+    }
+    const timestamp = typeof cursor.timestamp === 'string' ? cursor.timestamp : undefined;
+    if (!timestamp)
+        return undefined;
+    const id = typeof cursor.id === 'string' ? cursor.id : '';
+    const chat_jid = typeof cursor.chat_jid === 'string'
+        ? cursor.chat_jid
+        : fallbackChatJid || '';
+    return {
+        timestamp,
+        chat_jid,
+        id,
+        precise: !!id && !!chat_jid,
+    };
+}
+/**
+ * 多 JID 分页查询（用于主容器合并 web:main + feishu:xxx 消息）。
+ */
+export function getMessagesPageMulti(chatJids, before, limit = 50) {
+    if (chatJids.length === 0)
+        return [];
+    if (chatJids.length === 1)
+        return getMessagesPage(chatJids[0], before, limit);
+    const normalizedBefore = normalizeHistoryCursor(before);
+    const placeholders = chatJids.map(() => '?').join(',');
+    const sql = normalizedBefore
+        ? normalizedBefore.precise
+            ? `SELECT id, chat_jid, source_jid, runtime_identity, sender, sender_name, content, timestamp, is_from_me, attachments, token_usage,
+              turn_id, session_id, sdk_message_uuid, source_kind, finalization_reason
+       FROM messages
+       WHERE chat_jid IN (${placeholders})
+         AND (
+           timestamp < ?
+           OR (timestamp = ? AND chat_jid < ?)
+           OR (timestamp = ? AND chat_jid = ? AND id < ?)
+         )
+       ORDER BY timestamp DESC, chat_jid DESC, id DESC
+       LIMIT ?`
+            : `SELECT id, chat_jid, source_jid, runtime_identity, sender, sender_name, content, timestamp, is_from_me, attachments, token_usage,
+              turn_id, session_id, sdk_message_uuid, source_kind, finalization_reason
+       FROM messages
+       WHERE chat_jid IN (${placeholders}) AND timestamp < ?
+       ORDER BY timestamp DESC
+       LIMIT ?`
+        : `SELECT id, chat_jid, source_jid, runtime_identity, sender, sender_name, content, timestamp, is_from_me, attachments, token_usage,
+              turn_id, session_id, sdk_message_uuid, source_kind, finalization_reason
+       FROM messages
+       WHERE chat_jid IN (${placeholders})
+       ORDER BY timestamp DESC, chat_jid DESC, id DESC
+       LIMIT ?`;
+    const params = normalizedBefore
+        ? normalizedBefore.precise
+            ? [
+                ...chatJids,
+                normalizedBefore.timestamp,
+                normalizedBefore.timestamp,
+                normalizedBefore.chat_jid,
+                normalizedBefore.timestamp,
+                normalizedBefore.chat_jid,
+                normalizedBefore.id,
+                limit,
+            ]
+            : [...chatJids, normalizedBefore.timestamp, limit]
+        : [...chatJids, limit];
+    const rows = db.prepare(sql).all(...params);
+    return rows.map(mapDbMessageRow);
+}
+/**
+ * 多 JID 增量查询（用于主容器轮询合并消息）。
+ */
+export function getMessagesAfterMulti(chatJids, after, limit = 50) {
+    if (chatJids.length === 0)
+        return [];
+    if (chatJids.length === 1)
+        return getMessagesAfter(chatJids[0], after, limit);
+    const normalizedAfter = normalizeHistoryCursor(after);
+    const placeholders = chatJids.map(() => '?').join(',');
+    const rows = db
+        .prepare(normalizedAfter?.precise
+        ? `SELECT id, chat_jid, source_jid, runtime_identity, sender, sender_name, content, timestamp, is_from_me, attachments, token_usage,
+              turn_id, session_id, sdk_message_uuid, source_kind, finalization_reason
+       FROM messages
+       WHERE chat_jid IN (${placeholders})
+         AND (
+           timestamp > ?
+           OR (timestamp = ? AND chat_jid > ?)
+           OR (timestamp = ? AND chat_jid = ? AND id > ?)
+         )
+       ORDER BY timestamp ASC, chat_jid ASC, id ASC
+       LIMIT ?`
+        : `SELECT id, chat_jid, source_jid, runtime_identity, sender, sender_name, content, timestamp, is_from_me, attachments, token_usage,
+              turn_id, session_id, sdk_message_uuid, source_kind, finalization_reason
+       FROM messages
+       WHERE chat_jid IN (${placeholders}) AND timestamp > ?
+       ORDER BY timestamp ASC
+       LIMIT ?`)
+        .all(...(normalizedAfter?.precise
+        ? [
+            ...chatJids,
+            normalizedAfter.timestamp,
+            normalizedAfter.timestamp,
+            normalizedAfter.chat_jid,
+            normalizedAfter.timestamp,
+            normalizedAfter.chat_jid,
+            normalizedAfter.id,
+            limit,
+        ]
+        : [...chatJids, normalizedAfter?.timestamp || '', limit]));
+    return rows.map(mapDbMessageRow);
+}
+/**
+ * Get task run logs for a specific task, ordered by most recent first.
+ */
+export function getTaskRunLogs(taskId, limit = 20) {
+    return db
+        .prepare(`
+    SELECT id, task_id, run_at, duration_ms, status, result, error
+    FROM task_run_logs
+    WHERE task_id = ?
+    ORDER BY run_at DESC
+    LIMIT ?
+  `)
+        .all(taskId, limit);
+}
+// ===================== Daily Summary Queries =====================
+/**
+ * Get messages for a chat within a time range, ordered by timestamp ASC.
+ */
+export function getMessagesByTimeRange(chatJid, startTs, endTs, limit = 500) {
+    const startIso = new Date(startTs).toISOString();
+    const endIso = new Date(endTs).toISOString();
+    const rows = db
+        .prepare(`SELECT id, chat_jid, source_jid, runtime_identity, sender, sender_name, content, timestamp, is_from_me, attachments,
+              turn_id, session_id, sdk_message_uuid, source_kind, finalization_reason
+       FROM messages
+       WHERE chat_jid = ? AND timestamp >= ? AND timestamp < ?
+       ORDER BY timestamp ASC
+       LIMIT ?`)
+        .all(chatJid, startIso, endIso, limit);
+    return rows.map(mapDbMessageRow);
+}
+/**
+ * Get all registered groups owned by a specific user.
+ */
+export function getGroupsByOwner(userId) {
+    const rows = db
+        .prepare('SELECT * FROM registered_groups WHERE created_by = ?')
+        .all(userId);
+    return rows.map((row) => ({
+        jid: row.jid,
+        name: row.name,
+        folder: row.folder,
+        added_at: row.added_at,
+        containerConfig: row.container_config
+            ? JSON.parse(row.container_config)
+            : undefined,
+        agentType: parseAgentType(row.agent_type),
+        executionMode: parseExecutionMode(row.execution_mode, `group ${row.jid}`),
+        customCwd: row.custom_cwd ?? undefined,
+        initSourcePath: row.init_source_path ?? undefined,
+        initGitUrl: row.init_git_url ?? undefined,
+        created_by: row.created_by ?? undefined,
+        is_home: row.is_home === 1,
+    }));
+}
+// ===================== Auth CRUD =====================
+function parseUserRole(value) {
+    return value === 'admin' ? 'admin' : 'member';
+}
+function parseUserStatus(value) {
+    if (value === 'deleted')
+        return 'deleted';
+    if (value === 'disabled')
+        return 'disabled';
+    return 'active';
+}
+function parsePermissionsFromDb(raw, role) {
+    if (typeof raw === 'string') {
+        try {
+            const parsed = normalizePermissions(JSON.parse(raw));
+            if (parsed.length > 0)
+                return parsed;
+        }
+        catch {
+            // ignore and fall back to role defaults
+        }
+    }
+    return getDefaultPermissions(role);
+}
+function parseJsonDetails(raw) {
+    if (typeof raw !== 'string' || !raw.trim())
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed === 'object' && parsed !== null
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function mapUserRow(row) {
+    const role = parseUserRole(row.role);
+    const status = parseUserStatus(row.status);
+    return {
+        id: String(row.id),
+        username: String(row.username),
+        password_hash: String(row.password_hash),
+        display_name: String(row.display_name ?? ''),
+        role,
+        status,
+        permissions: parsePermissionsFromDb(row.permissions, role),
+        must_change_password: !!row.must_change_password,
+        disable_reason: typeof row.disable_reason === 'string' ? row.disable_reason : null,
+        notes: typeof row.notes === 'string' ? row.notes : null,
+        avatar_emoji: typeof row.avatar_emoji === 'string' ? row.avatar_emoji : null,
+        avatar_color: typeof row.avatar_color === 'string' ? row.avatar_color : null,
+        avatar_url: typeof row.avatar_url === 'string' ? row.avatar_url : null,
+        ai_name: typeof row.ai_name === 'string' ? row.ai_name : null,
+        ai_avatar_emoji: typeof row.ai_avatar_emoji === 'string' ? row.ai_avatar_emoji : null,
+        ai_avatar_color: typeof row.ai_avatar_color === 'string' ? row.ai_avatar_color : null,
+        ai_avatar_url: typeof row.ai_avatar_url === 'string' ? row.ai_avatar_url : null,
+        created_at: String(row.created_at),
+        updated_at: String(row.updated_at),
+        last_login_at: typeof row.last_login_at === 'string' ? row.last_login_at : null,
+        deleted_at: typeof row.deleted_at === 'string' ? row.deleted_at : null,
+    };
+}
+function toUserPublic(user, lastActiveAt) {
+    return {
+        id: user.id,
+        username: user.username,
+        display_name: user.display_name,
+        role: user.role,
+        status: user.status,
+        permissions: user.permissions,
+        must_change_password: user.must_change_password,
+        disable_reason: user.disable_reason,
+        notes: user.notes,
+        avatar_emoji: user.avatar_emoji,
+        avatar_color: user.avatar_color,
+        avatar_url: user.avatar_url,
+        ai_name: user.ai_name,
+        ai_avatar_emoji: user.ai_avatar_emoji,
+        ai_avatar_color: user.ai_avatar_color,
+        ai_avatar_url: user.ai_avatar_url,
+        created_at: user.created_at,
+        last_login_at: user.last_login_at,
+        last_active_at: lastActiveAt,
+        deleted_at: user.deleted_at,
+    };
+}
+function initializeBillingForUser(userId, role, createdAt) {
+    const now = createdAt || new Date().toISOString();
+    db.prepare('INSERT OR IGNORE INTO user_balances (user_id, balance_usd, total_deposited_usd, total_consumed_usd, updated_at) VALUES (?, 0, 0, 0, ?)').run(userId, now);
+    if (role === 'admin')
+        return;
+    const defaultPlan = getDefaultBillingPlan();
+    if (!defaultPlan)
+        return;
+    const activeSubscription = db
+        .prepare("SELECT id FROM user_subscriptions WHERE user_id = ? AND status = 'active'")
+        .get(userId);
+    if (activeSubscription)
+        return;
+    const subId = `sub_${userId}_${Date.now()}`;
+    db.prepare(`INSERT INTO user_subscriptions (id, user_id, plan_id, status, started_at, created_at)
+     VALUES (?, ?, ?, 'active', ?, ?)`).run(subId, userId, defaultPlan.id, now, now);
+    db.prepare('UPDATE users SET subscription_plan_id = ? WHERE id = ?').run(defaultPlan.id, userId);
+    const hasOpening = db
+        .prepare("SELECT 1 FROM balance_transactions WHERE user_id = ? AND source = 'migration_opening' LIMIT 1")
+        .get(userId);
+    if (!hasOpening) {
+        db.prepare(`INSERT INTO balance_transactions (
+        user_id, type, amount_usd, balance_after, description, reference_type,
+        reference_id, actor_id, source, operator_type, notes, idempotency_key, created_at
+      ) VALUES (?, 'adjustment', 0, 0, ?, NULL, NULL, NULL, 'migration_opening', 'system', ?, NULL, ?)`).run(userId, '用户钱包初始化', '新用户默认余额为 0，需管理员充值或兑换后方可消费', now);
+    }
+}
+export function createUser(user) {
+    const permissions = normalizePermissions(user.permissions ?? getDefaultPermissions(user.role));
+    db.prepare(`INSERT INTO users (
+      id, username, password_hash, display_name, role, status, permissions, must_change_password,
+      disable_reason, notes, created_at, updated_at, last_login_at, deleted_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(user.id, user.username, user.password_hash, user.display_name, user.role, user.status, JSON.stringify(permissions), user.must_change_password ? 1 : 0, user.disable_reason ?? null, user.notes ?? null, user.created_at, user.updated_at, user.last_login_at ?? null, user.deleted_at ?? null);
+    initializeBillingForUser(user.id, user.role, user.created_at);
+}
+export function createInitialAdminUser(user) {
+    const tx = db.transaction((input) => {
+        const row = db.prepare('SELECT COUNT(*) as count FROM users').get();
+        if (row.count > 0)
+            return { ok: false, reason: 'already_initialized' };
+        createUser(input);
+        return { ok: true };
+    });
+    try {
+        return tx(user);
+    }
+    catch (err) {
+        if (err instanceof Error &&
+            err.message.includes('UNIQUE constraint failed: users.username')) {
+            return { ok: false, reason: 'username_taken' };
+        }
+        throw err;
+    }
+}
+export function getUserById(id) {
+    const row = db.prepare('SELECT * FROM users WHERE id = ?').get(id);
+    return row ? mapUserRow(row) : undefined;
+}
+export function getUserByUsername(username) {
+    const row = db
+        .prepare('SELECT * FROM users WHERE username = ?')
+        .get(username);
+    return row ? mapUserRow(row) : undefined;
+}
+export function listUsers(options = {}) {
+    const role = options.role && options.role !== 'all' ? options.role : null;
+    const status = options.status && options.status !== 'all' ? options.status : null;
+    const query = options.query?.trim() || '';
+    const page = Math.max(1, Math.floor(options.page || 1));
+    const pageSize = Math.min(200, Math.max(1, Math.floor(options.pageSize || 50)));
+    const offset = (page - 1) * pageSize;
+    const whereParts = [];
+    const params = [];
+    if (role) {
+        whereParts.push('u.role = ?');
+        params.push(role);
+    }
+    if (status) {
+        whereParts.push('u.status = ?');
+        params.push(status);
+    }
+    if (query) {
+        whereParts.push("(u.username LIKE ? OR u.display_name LIKE ? OR COALESCE(u.notes, '') LIKE ?)");
+        const like = `%${query}%`;
+        params.push(like, like, like);
+    }
+    const whereClause = whereParts.length > 0 ? `WHERE ${whereParts.join(' AND ')}` : '';
+    const totalRow = db
+        .prepare(`SELECT COUNT(*) as count FROM users u ${whereClause}`)
+        .get(...params);
+    const rows = db
+        .prepare(`
+      SELECT u.*, MAX(s.last_active_at) AS last_active_at
+      FROM users u
+      LEFT JOIN user_sessions s ON s.user_id = u.id
+      ${whereClause}
+      GROUP BY u.id
+      ORDER BY
+        CASE u.status
+          WHEN 'active' THEN 0
+          WHEN 'disabled' THEN 1
+          ELSE 2
+        END,
+        u.created_at DESC
+      LIMIT ? OFFSET ?
+      `)
+        .all(...params, pageSize, offset);
+    return {
+        users: rows.map((row) => {
+            const user = mapUserRow(row);
+            const lastActiveAt = typeof row.last_active_at === 'string' ? row.last_active_at : null;
+            return toUserPublic(user, lastActiveAt);
+        }),
+        total: totalRow.count,
+        page,
+        pageSize,
+    };
+}
+export function getAllUsers() {
+    return listUsers({ role: 'all', status: 'all', page: 1, pageSize: 1000 })
+        .users;
+}
+export function getUserCount(includeDeleted = false) {
+    const row = includeDeleted
+        ? db.prepare('SELECT COUNT(*) as count FROM users').get()
+        : db
+            .prepare('SELECT COUNT(*) as count FROM users WHERE status != ?')
+            .get('deleted');
+    return row.count;
+}
+export function getActiveAdminCount() {
+    const row = db
+        .prepare(`SELECT COUNT(*) as count
+       FROM users
+       WHERE role = 'admin' AND status = 'active'`)
+        .get();
+    return row.count;
+}
+export function updateUserFields(id, updates) {
+    const fields = [];
+    const values = [];
+    if (updates.username !== undefined) {
+        fields.push('username = ?');
+        values.push(updates.username);
+    }
+    if (updates.display_name !== undefined) {
+        fields.push('display_name = ?');
+        values.push(updates.display_name);
+    }
+    if (updates.role !== undefined) {
+        fields.push('role = ?');
+        values.push(updates.role);
+    }
+    if (updates.status !== undefined) {
+        fields.push('status = ?');
+        values.push(updates.status);
+    }
+    if (updates.password_hash !== undefined) {
+        fields.push('password_hash = ?');
+        values.push(updates.password_hash);
+    }
+    if (updates.last_login_at !== undefined) {
+        fields.push('last_login_at = ?');
+        values.push(updates.last_login_at);
+    }
+    if (updates.permissions !== undefined) {
+        fields.push('permissions = ?');
+        values.push(JSON.stringify(normalizePermissions(updates.permissions)));
+    }
+    if (updates.must_change_password !== undefined) {
+        fields.push('must_change_password = ?');
+        values.push(updates.must_change_password ? 1 : 0);
+    }
+    if (updates.disable_reason !== undefined) {
+        fields.push('disable_reason = ?');
+        values.push(updates.disable_reason);
+    }
+    if (updates.notes !== undefined) {
+        fields.push('notes = ?');
+        values.push(updates.notes);
+    }
+    if (updates.avatar_emoji !== undefined) {
+        fields.push('avatar_emoji = ?');
+        values.push(updates.avatar_emoji);
+    }
+    if (updates.avatar_color !== undefined) {
+        fields.push('avatar_color = ?');
+        values.push(updates.avatar_color);
+    }
+    if (updates.avatar_url !== undefined) {
+        fields.push('avatar_url = ?');
+        values.push(updates.avatar_url);
+    }
+    if (updates.ai_name !== undefined) {
+        fields.push('ai_name = ?');
+        values.push(updates.ai_name);
+    }
+    if (updates.ai_avatar_emoji !== undefined) {
+        fields.push('ai_avatar_emoji = ?');
+        values.push(updates.ai_avatar_emoji);
+    }
+    if (updates.ai_avatar_color !== undefined) {
+        fields.push('ai_avatar_color = ?');
+        values.push(updates.ai_avatar_color);
+    }
+    if (updates.ai_avatar_url !== undefined) {
+        fields.push('ai_avatar_url = ?');
+        values.push(updates.ai_avatar_url);
+    }
+    if (updates.deleted_at !== undefined) {
+        fields.push('deleted_at = ?');
+        values.push(updates.deleted_at);
+    }
+    if (fields.length === 0)
+        return;
+    fields.push('updated_at = ?');
+    values.push(new Date().toISOString());
+    values.push(id);
+    db.prepare(`UPDATE users SET ${fields.join(', ')} WHERE id = ?`).run(...values);
+}
+export function deleteUser(id) {
+    const now = new Date().toISOString();
+    const tx = db.transaction((userId) => {
+        db.prepare('DELETE FROM user_sessions WHERE user_id = ?').run(userId);
+        db.prepare(`UPDATE users
+       SET status = 'deleted', deleted_at = ?, disable_reason = COALESCE(disable_reason, 'deleted_by_admin'), updated_at = ?
+       WHERE id = ?`).run(now, now, userId);
+    });
+    tx(id);
+}
+export function restoreUser(id) {
+    db.prepare(`UPDATE users
+     SET status = 'disabled', deleted_at = NULL, disable_reason = NULL, updated_at = ?
+     WHERE id = ?`).run(new Date().toISOString(), id);
+}
+// --- User Sessions ---
+export function createUserSession(session) {
+    db.prepare(`INSERT INTO user_sessions (id, user_id, ip_address, user_agent, created_at, expires_at, last_active_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`).run(session.id, session.user_id, session.ip_address, session.user_agent, session.created_at, session.expires_at, session.last_active_at);
+}
+export function getSessionWithUser(sessionId) {
+    const row = stmts().getSessionWithUser.get(sessionId);
+    if (!row)
+        return undefined;
+    const role = parseUserRole(row.role);
+    return {
+        id: String(row.id),
+        user_id: String(row.user_id),
+        ip_address: typeof row.ip_address === 'string' ? row.ip_address : null,
+        user_agent: typeof row.user_agent === 'string' ? row.user_agent : null,
+        created_at: String(row.created_at),
+        expires_at: String(row.expires_at),
+        last_active_at: String(row.last_active_at),
+        username: String(row.username),
+        role,
+        status: parseUserStatus(row.status),
+        display_name: String(row.display_name ?? ''),
+        permissions: parsePermissionsFromDb(row.permissions, role),
+        must_change_password: !!row.must_change_password,
+    };
+}
+export function getUserSessions(userId) {
+    return db
+        .prepare(`SELECT * FROM user_sessions WHERE user_id = ? ORDER BY last_active_at DESC`)
+        .all(userId);
+}
+export function deleteUserSession(sessionId) {
+    stmts().deleteSession.run(sessionId);
+}
+export function deleteUserSessionsByUserId(userId) {
+    db.prepare('DELETE FROM user_sessions WHERE user_id = ?').run(userId);
+}
+export function updateSessionLastActive(sessionId) {
+    stmts().updateSessionLastActive.run(new Date().toISOString(), sessionId);
+}
+export function getExpiredSessionIds() {
+    const now = new Date().toISOString();
+    return stmts().getExpiredSessionIds.all(now).map((r) => r.id);
+}
+export function deleteExpiredSessions() {
+    const now = new Date().toISOString();
+    const result = db
+        .prepare('DELETE FROM user_sessions WHERE expires_at < ?')
+        .run(now);
+    return result.changes;
+}
+// --- Invite Codes ---
+export function createInviteCode(invite) {
+    const permissions = normalizePermissions(invite.permissions);
+    db.prepare(`INSERT INTO invite_codes (code, created_by, role, permission_template, permissions, max_uses, used_count, expires_at, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(invite.code, invite.created_by, invite.role, invite.permission_template ?? null, JSON.stringify(permissions), invite.max_uses, invite.used_count, invite.expires_at, invite.created_at);
+}
+export function getInviteCode(code) {
+    const row = db
+        .prepare('SELECT * FROM invite_codes WHERE code = ?')
+        .get(code);
+    if (!row)
+        return undefined;
+    const role = parseUserRole(row.role);
+    return {
+        code: String(row.code),
+        created_by: String(row.created_by),
+        role,
+        permission_template: typeof row.permission_template === 'string'
+            ? row.permission_template
+            : null,
+        permissions: parsePermissionsFromDb(row.permissions, role),
+        max_uses: Number(row.max_uses),
+        used_count: Number(row.used_count),
+        expires_at: typeof row.expires_at === 'string' ? row.expires_at : null,
+        created_at: String(row.created_at),
+    };
+}
+export function registerUserWithInvite(input) {
+    const tx = db.transaction((params) => {
+        const inviteRow = db
+            .prepare(`SELECT code, role, permissions, max_uses, expires_at
+         FROM invite_codes
+         WHERE code = ?`)
+            .get(params.invite_code);
+        if (!inviteRow)
+            return { ok: false, reason: 'invalid_or_expired_invite' };
+        const inviteRole = parseUserRole(inviteRow.role);
+        const invitePermissions = parsePermissionsFromDb(inviteRow.permissions, inviteRole);
+        const inviteExpiresAt = typeof inviteRow.expires_at === 'string' ? inviteRow.expires_at : null;
+        if (inviteExpiresAt) {
+            const expiresAt = Date.parse(inviteExpiresAt);
+            if (!Number.isFinite(expiresAt) || expiresAt < Date.now()) {
+                return { ok: false, reason: 'invalid_or_expired_invite' };
+            }
+        }
+        const existing = db
+            .prepare('SELECT id FROM users WHERE username = ?')
+            .get(params.username);
+        if (existing)
+            return { ok: false, reason: 'username_taken' };
+        const inviteUsage = db
+            .prepare(`UPDATE invite_codes
+         SET used_count = used_count + 1
+         WHERE code = ?
+           AND (max_uses = 0 OR used_count < max_uses)`)
+            .run(params.invite_code);
+        if (inviteUsage.changes === 0) {
+            return { ok: false, reason: 'invite_exhausted' };
+        }
+        const permissions = normalizePermissions(invitePermissions);
+        db.prepare(`INSERT INTO users (
+        id, username, password_hash, display_name, role, status, permissions, must_change_password,
+        disable_reason, notes, created_at, updated_at, last_login_at, deleted_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(params.id, params.username, params.password_hash, params.display_name, inviteRole, 'active', JSON.stringify(permissions), 0, null, null, params.created_at, params.updated_at, null, null);
+        initializeBillingForUser(params.id, inviteRole, params.created_at);
+        return { ok: true, role: inviteRole, permissions };
+    });
+    try {
+        return tx(input);
+    }
+    catch (err) {
+        if (err instanceof Error &&
+            err.message.includes('UNIQUE constraint failed: users.username')) {
+            return { ok: false, reason: 'username_taken' };
+        }
+        throw err;
+    }
+}
+export function registerUserWithoutInvite(input) {
+    const role = 'member';
+    const permissions = [];
+    try {
+        db.prepare(`INSERT INTO users (
+        id, username, password_hash, display_name, role, status, permissions, must_change_password,
+        disable_reason, notes, created_at, updated_at, last_login_at, deleted_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(input.id, input.username, input.password_hash, input.display_name, role, 'active', JSON.stringify(permissions), 0, null, null, input.created_at, input.updated_at, null, null);
+        initializeBillingForUser(input.id, role, input.created_at);
+        return { ok: true, role, permissions };
+    }
+    catch (err) {
+        if (err instanceof Error &&
+            err.message.includes('UNIQUE constraint failed: users.username')) {
+            return { ok: false, reason: 'username_taken' };
+        }
+        throw err;
+    }
+}
+export function getAllInviteCodes() {
+    const rows = db
+        .prepare(`SELECT i.*, u.username as creator_username
+       FROM invite_codes i
+       JOIN users u ON i.created_by = u.id
+       ORDER BY i.created_at DESC`)
+        .all();
+    return rows.map((row) => {
+        const role = parseUserRole(row.role);
+        return {
+            code: String(row.code),
+            created_by: String(row.created_by),
+            creator_username: String(row.creator_username),
+            role,
+            permission_template: typeof row.permission_template === 'string'
+                ? row.permission_template
+                : null,
+            permissions: parsePermissionsFromDb(row.permissions, role),
+            max_uses: Number(row.max_uses),
+            used_count: Number(row.used_count),
+            expires_at: typeof row.expires_at === 'string' ? row.expires_at : null,
+            created_at: String(row.created_at),
+        };
+    });
+}
+export function deleteInviteCode(code) {
+    db.prepare('DELETE FROM invite_codes WHERE code = ?').run(code);
+}
+// --- Auth Audit Log ---
+export function logAuthEvent(event) {
+    db.prepare(`INSERT INTO auth_audit_log (event_type, username, actor_username, ip_address, user_agent, details, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`).run(event.event_type, event.username, event.actor_username ?? null, event.ip_address ?? null, event.user_agent ?? null, event.details ? JSON.stringify(event.details) : null, new Date().toISOString());
+}
+export function queryAuthAuditLogs(query = {}) {
+    const limit = Math.min(500, Math.max(1, Math.floor(query.limit || 100)));
+    const offset = Math.max(0, Math.floor(query.offset || 0));
+    const whereParts = [];
+    const params = [];
+    if (query.event_type && query.event_type !== 'all') {
+        whereParts.push('event_type = ?');
+        params.push(query.event_type);
+    }
+    if (query.username?.trim()) {
+        whereParts.push('username LIKE ?');
+        params.push(`%${query.username.trim()}%`);
+    }
+    if (query.actor_username?.trim()) {
+        whereParts.push('actor_username LIKE ?');
+        params.push(`%${query.actor_username.trim()}%`);
+    }
+    if (query.from) {
+        whereParts.push('created_at >= ?');
+        params.push(query.from);
+    }
+    if (query.to) {
+        whereParts.push('created_at <= ?');
+        params.push(query.to);
+    }
+    const whereClause = whereParts.length > 0 ? `WHERE ${whereParts.join(' AND ')}` : '';
+    const total = db
+        .prepare(`SELECT COUNT(*) as count FROM auth_audit_log ${whereClause}`)
+        .get(...params).count;
+    const rows = db
+        .prepare(`SELECT * FROM auth_audit_log ${whereClause} ORDER BY created_at DESC LIMIT ? OFFSET ?`)
+        .all(...params, limit, offset);
+    const logs = rows.map((row) => ({
+        id: Number(row.id),
+        event_type: row.event_type,
+        username: String(row.username),
+        actor_username: typeof row.actor_username === 'string' ? row.actor_username : null,
+        ip_address: typeof row.ip_address === 'string' ? row.ip_address : null,
+        user_agent: typeof row.user_agent === 'string' ? row.user_agent : null,
+        details: parseJsonDetails(row.details),
+        created_at: String(row.created_at),
+    }));
+    return { logs, total, limit, offset };
+}
+export function getAuthAuditLogs(limit = 100, offset = 0) {
+    return queryAuthAuditLogs({ limit, offset }).logs;
+}
+export function checkLoginRateLimitFromAudit(username, ip, maxAttempts, lockoutMinutes) {
+    if (maxAttempts <= 0)
+        return { allowed: true, attempts: 0 };
+    const windowStart = new Date(Date.now() - lockoutMinutes * 60 * 1000).toISOString();
+    const rows = db
+        .prepare(`
+      SELECT created_at
+      FROM auth_audit_log
+      WHERE event_type = 'login_failed'
+        AND username = ?
+        AND ip_address = ?
+        AND created_at >= ?
+        AND (details IS NULL OR details NOT LIKE '%"reason":"rate_limited"%')
+      ORDER BY created_at ASC
+      `)
+        .all(username, ip, windowStart);
+    const attempts = rows.length;
+    if (attempts < maxAttempts)
+        return { allowed: true, attempts };
+    const oldest = rows[0]?.created_at;
+    const oldestTs = oldest ? Date.parse(oldest) : Date.now();
+    const retryAt = oldestTs + lockoutMinutes * 60 * 1000;
+    const retryAfterSeconds = Math.max(1, Math.ceil((retryAt - Date.now()) / 1000));
+    return { allowed: false, retryAfterSeconds, attempts };
+}
+// ===================== Group Members =====================
+export function addGroupMember(groupFolder, userId, role, addedBy) {
+    db.prepare(`INSERT INTO group_members (group_folder, user_id, role, added_at, added_by)
+     VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT(group_folder, user_id) DO UPDATE SET
+       role = CASE WHEN excluded.role = 'owner' THEN 'owner'
+                   WHEN group_members.role = 'owner' THEN 'owner'
+                   ELSE excluded.role END,
+       added_by = COALESCE(excluded.added_by, group_members.added_by)`).run(groupFolder, userId, role, new Date().toISOString(), addedBy ?? null);
+}
+export function removeGroupMember(groupFolder, userId) {
+    db.prepare('DELETE FROM group_members WHERE group_folder = ? AND user_id = ?').run(groupFolder, userId);
+}
+export function getGroupMembers(groupFolder) {
+    const rows = db
+        .prepare(`SELECT gm.user_id, gm.role, gm.added_at, gm.added_by,
+              u.username, COALESCE(u.display_name, '') as display_name
+       FROM group_members gm
+       JOIN users u ON gm.user_id = u.id
+       WHERE gm.group_folder = ?
+       ORDER BY gm.role DESC, gm.added_at ASC`)
+        .all(groupFolder);
+    return rows.map((r) => ({
+        user_id: r.user_id,
+        role: r.role,
+        added_at: r.added_at,
+        added_by: r.added_by ?? undefined,
+        username: r.username,
+        display_name: r.display_name,
+    }));
+}
+export function getGroupMemberRole(groupFolder, userId) {
+    const row = db
+        .prepare('SELECT role FROM group_members WHERE group_folder = ? AND user_id = ?')
+        .get(groupFolder, userId);
+    if (!row)
+        return null;
+    return row.role;
+}
+export function getUserMemberFolders(userId) {
+    const rows = db
+        .prepare('SELECT group_folder, role FROM group_members WHERE user_id = ?')
+        .all(userId);
+    return rows.map((r) => ({
+        group_folder: r.group_folder,
+        role: r.role,
+    }));
+}
+// ===================== Sub-Agent CRUD =====================
+export function createAgent(agent) {
+    db.prepare(`INSERT INTO agents (id, group_folder, chat_jid, name, prompt, status, kind, created_by, created_at, completed_at, result_summary, spawned_from_jid)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(agent.id, agent.group_folder, agent.chat_jid, agent.name, agent.prompt, agent.status, agent.kind || 'task', agent.created_by ?? null, agent.created_at, agent.completed_at ?? null, agent.result_summary ?? null, agent.spawned_from_jid ?? null);
+}
+export function getAgent(id) {
+    const row = db.prepare('SELECT * FROM agents WHERE id = ?').get(id);
+    if (!row)
+        return undefined;
+    return mapAgentRow(row);
+}
+export function listAgentsByFolder(folder) {
+    const rows = db
+        .prepare('SELECT * FROM agents WHERE group_folder = ? ORDER BY created_at DESC')
+        .all(folder);
+    return rows.map(mapAgentRow);
+}
+export function listAgentsByJid(chatJid) {
+    const rows = db
+        .prepare('SELECT * FROM agents WHERE chat_jid = ? ORDER BY created_at DESC')
+        .all(chatJid);
+    return rows.map(mapAgentRow);
+}
+export function updateAgentStatus(id, status, resultSummary) {
+    const completedAt = status !== 'running' && status !== 'idle' ? new Date().toISOString() : null;
+    db.prepare('UPDATE agents SET status = ?, completed_at = ?, result_summary = ? WHERE id = ?').run(status, completedAt, resultSummary ?? null, id);
+}
+export function updateAgentLastImJid(id, lastImJid) {
+    db.prepare('UPDATE agents SET last_im_jid = ? WHERE id = ?').run(lastImJid, id);
+}
+export function updateAgentInfo(id, name, prompt) {
+    db.prepare('UPDATE agents SET name = ?, prompt = ? WHERE id = ?').run(name, prompt, id);
+}
+export function deleteCompletedAgents(beforeTimestamp) {
+    const result = db
+        .prepare("DELETE FROM agents WHERE kind IN ('task', 'spawn') AND status IN ('completed', 'error') AND completed_at IS NOT NULL AND completed_at < ?")
+        .run(beforeTimestamp);
+    return result.changes;
+}
+export function getRunningTaskAgentsByChat(chatJid) {
+    const rows = db
+        .prepare("SELECT * FROM agents WHERE chat_jid = ? AND kind = 'task' AND status = 'running'")
+        .all(chatJid);
+    return rows.map(mapAgentRow);
+}
+export function markRunningTaskAgentsAsError(chatJid) {
+    const now = new Date().toISOString();
+    const result = db
+        .prepare("UPDATE agents SET status = 'error', completed_at = ? WHERE chat_jid = ? AND kind = 'task' AND status = 'running'")
+        .run(now, chatJid);
+    return result.changes;
+}
+export function markAllRunningTaskAgentsAsError(summary = '进程重启，任务中断') {
+    const now = new Date().toISOString();
+    const result = db
+        .prepare("UPDATE agents SET status = 'error', completed_at = ?, result_summary = COALESCE(result_summary, ?) WHERE kind = 'task' AND status = 'running'")
+        .run(now, summary);
+    return result.changes;
+}
+/**
+ * Mark stale spawn agents (idle/running) as error at startup.
+ * After a process restart, spawn agents that were idle or running can never
+ * resume — their in-memory task callbacks are lost. Mark them as error so
+ * they don't render as "正在思考..." in the frontend.
+ */
+export function markStaleSpawnAgentsAsError(summary = '进程重启，并行任务中断') {
+    const now = new Date().toISOString();
+    const result = db
+        .prepare("UPDATE agents SET status = 'error', completed_at = ?, result_summary = COALESCE(result_summary, ?) WHERE kind = 'spawn' AND status IN ('idle', 'running')")
+        .run(now, summary);
+    return result.changes;
+}
+export function listActiveConversationAgents() {
+    return db
+        .prepare("SELECT * FROM agents WHERE kind IN ('conversation', 'spawn') AND status IN ('running', 'idle')")
+        .all().map(mapAgentRow);
+}
+export function deleteAgent(id) {
+    // Delete associated session
+    db.prepare('DELETE FROM sessions WHERE agent_id = ?').run(id);
+    db.prepare('DELETE FROM agents WHERE id = ?').run(id);
+}
+function mapAgentRow(row) {
+    return {
+        id: String(row.id),
+        group_folder: String(row.group_folder),
+        chat_jid: String(row.chat_jid),
+        name: String(row.name),
+        prompt: String(row.prompt),
+        status: row.status || 'running',
+        kind: row.kind || 'task',
+        created_by: typeof row.created_by === 'string' ? row.created_by : null,
+        created_at: String(row.created_at),
+        completed_at: typeof row.completed_at === 'string' ? row.completed_at : null,
+        result_summary: typeof row.result_summary === 'string' ? row.result_summary : null,
+        last_im_jid: typeof row.last_im_jid === 'string' ? row.last_im_jid : null,
+        spawned_from_jid: typeof row.spawned_from_jid === 'string' ? row.spawned_from_jid : null,
+    };
+}
+export function deleteMessagesForChatJid(chatJid) {
+    db.prepare('DELETE FROM messages WHERE chat_jid = ?').run(chatJid);
+    db.prepare('DELETE FROM chats WHERE jid = ?').run(chatJid);
+}
+export function getMessage(chatJid, messageId) {
+    const row = db
+        .prepare('SELECT id, chat_jid, sender, is_from_me FROM messages WHERE id = ? AND chat_jid = ?')
+        .get(messageId, chatJid);
+    return row ?? null;
+}
+export function deleteMessage(chatJid, messageId) {
+    const result = db
+        .prepare('DELETE FROM messages WHERE id = ? AND chat_jid = ?')
+        .run(messageId, chatJid);
+    return result.changes > 0;
+}
+export function isGroupShared(groupFolder) {
+    const row = db
+        .prepare('SELECT COUNT(*) as cnt FROM group_members WHERE group_folder = ?')
+        .get(groupFolder);
+    return row.cnt > 1;
+}
+// --- Billing CRUD functions ---
+export function getBillingPlan(id) {
+    const row = db.prepare('SELECT * FROM billing_plans WHERE id = ?').get(id);
+    return row ? mapBillingPlanRow(row) : undefined;
+}
+export function getActiveBillingPlans() {
+    return db
+        .prepare('SELECT * FROM billing_plans WHERE is_active = 1 ORDER BY tier ASC, name ASC')
+        .all().map(mapBillingPlanRow);
+}
+export function getAllBillingPlans() {
+    return db
+        .prepare('SELECT * FROM billing_plans ORDER BY tier ASC, name ASC')
+        .all().map(mapBillingPlanRow);
+}
+export function getDefaultBillingPlan() {
+    const row = db
+        .prepare('SELECT * FROM billing_plans WHERE is_default = 1')
+        .get();
+    return row ? mapBillingPlanRow(row) : undefined;
+}
+export function createBillingPlan(plan) {
+    db.transaction(() => {
+        // Clear old default BEFORE inserting the new plan to avoid brief dual-default
+        if (plan.is_default) {
+            db.prepare('UPDATE billing_plans SET is_default = 0 WHERE is_default = 1').run();
+        }
+        db.prepare(`INSERT INTO billing_plans (id, name, description, tier, monthly_cost_usd, monthly_token_quota, monthly_cost_quota,
+       daily_cost_quota, weekly_cost_quota, daily_token_quota, weekly_token_quota,
+       rate_multiplier, trial_days, sort_order, display_price, highlight,
+       max_groups, max_concurrent_containers, max_im_channels, max_mcp_servers, max_storage_mb,
+       allow_overage, features, is_default, is_active, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(plan.id, plan.name, plan.description, plan.tier, plan.monthly_cost_usd, plan.monthly_token_quota, plan.monthly_cost_quota, plan.daily_cost_quota, plan.weekly_cost_quota, plan.daily_token_quota, plan.weekly_token_quota, plan.rate_multiplier, plan.trial_days, plan.sort_order, plan.display_price, plan.highlight ? 1 : 0, plan.max_groups, plan.max_concurrent_containers, plan.max_im_channels, plan.max_mcp_servers, plan.max_storage_mb, plan.allow_overage ? 1 : 0, JSON.stringify(plan.features), plan.is_default ? 1 : 0, plan.is_active ? 1 : 0, plan.created_at, plan.updated_at);
+    })();
+}
+export function updateBillingPlan(id, updates) {
+    const fields = [];
+    const values = [];
+    if (updates.name !== undefined) {
+        fields.push('name = ?');
+        values.push(updates.name);
+    }
+    if (updates.description !== undefined) {
+        fields.push('description = ?');
+        values.push(updates.description);
+    }
+    if (updates.tier !== undefined) {
+        fields.push('tier = ?');
+        values.push(updates.tier);
+    }
+    if (updates.monthly_cost_usd !== undefined) {
+        fields.push('monthly_cost_usd = ?');
+        values.push(updates.monthly_cost_usd);
+    }
+    if (updates.monthly_token_quota !== undefined) {
+        fields.push('monthly_token_quota = ?');
+        values.push(updates.monthly_token_quota);
+    }
+    if (updates.monthly_cost_quota !== undefined) {
+        fields.push('monthly_cost_quota = ?');
+        values.push(updates.monthly_cost_quota);
+    }
+    if (updates.daily_cost_quota !== undefined) {
+        fields.push('daily_cost_quota = ?');
+        values.push(updates.daily_cost_quota);
+    }
+    if (updates.weekly_cost_quota !== undefined) {
+        fields.push('weekly_cost_quota = ?');
+        values.push(updates.weekly_cost_quota);
+    }
+    if (updates.daily_token_quota !== undefined) {
+        fields.push('daily_token_quota = ?');
+        values.push(updates.daily_token_quota);
+    }
+    if (updates.weekly_token_quota !== undefined) {
+        fields.push('weekly_token_quota = ?');
+        values.push(updates.weekly_token_quota);
+    }
+    if (updates.rate_multiplier !== undefined) {
+        fields.push('rate_multiplier = ?');
+        values.push(updates.rate_multiplier);
+    }
+    if (updates.trial_days !== undefined) {
+        fields.push('trial_days = ?');
+        values.push(updates.trial_days);
+    }
+    if (updates.sort_order !== undefined) {
+        fields.push('sort_order = ?');
+        values.push(updates.sort_order);
+    }
+    if (updates.display_price !== undefined) {
+        fields.push('display_price = ?');
+        values.push(updates.display_price);
+    }
+    if (updates.highlight !== undefined) {
+        fields.push('highlight = ?');
+        values.push(updates.highlight ? 1 : 0);
+    }
+    if (updates.max_groups !== undefined) {
+        fields.push('max_groups = ?');
+        values.push(updates.max_groups);
+    }
+    if (updates.max_concurrent_containers !== undefined) {
+        fields.push('max_concurrent_containers = ?');
+        values.push(updates.max_concurrent_containers);
+    }
+    if (updates.max_im_channels !== undefined) {
+        fields.push('max_im_channels = ?');
+        values.push(updates.max_im_channels);
+    }
+    if (updates.max_mcp_servers !== undefined) {
+        fields.push('max_mcp_servers = ?');
+        values.push(updates.max_mcp_servers);
+    }
+    if (updates.max_storage_mb !== undefined) {
+        fields.push('max_storage_mb = ?');
+        values.push(updates.max_storage_mb);
+    }
+    if (updates.allow_overage !== undefined) {
+        fields.push('allow_overage = ?');
+        values.push(updates.allow_overage ? 1 : 0);
+    }
+    if (updates.features !== undefined) {
+        fields.push('features = ?');
+        values.push(JSON.stringify(updates.features));
+    }
+    if (updates.is_default !== undefined) {
+        fields.push('is_default = ?');
+        values.push(updates.is_default ? 1 : 0);
+    }
+    if (updates.is_active !== undefined) {
+        fields.push('is_active = ?');
+        values.push(updates.is_active ? 1 : 0);
+    }
+    if (fields.length === 0)
+        return;
+    fields.push('updated_at = ?');
+    values.push(new Date().toISOString());
+    values.push(id);
+    db.transaction(() => {
+        // Clear old default BEFORE setting new one to avoid brief dual-default state
+        if (updates.is_default) {
+            db.prepare('UPDATE billing_plans SET is_default = 0 WHERE id != ?').run(id);
+        }
+        db.prepare(`UPDATE billing_plans SET ${fields.join(', ')} WHERE id = ?`).run(...values);
+    })();
+}
+export function deleteBillingPlan(id) {
+    // Don't delete if users are subscribed
+    const hasSubscribers = db
+        .prepare("SELECT COUNT(*) as cnt FROM user_subscriptions WHERE plan_id = ? AND status = 'active'")
+        .get(id);
+    if (hasSubscribers.cnt > 0)
+        return false;
+    const result = db.prepare('DELETE FROM billing_plans WHERE id = ?').run(id);
+    return result.changes > 0;
+}
+function mapBillingPlanRow(row) {
+    return {
+        id: String(row.id),
+        name: String(row.name),
+        description: typeof row.description === 'string' ? row.description : null,
+        tier: Number(row.tier) || 0,
+        monthly_cost_usd: Number(row.monthly_cost_usd) || 0,
+        monthly_token_quota: row.monthly_token_quota != null ? Number(row.monthly_token_quota) : null,
+        monthly_cost_quota: row.monthly_cost_quota != null ? Number(row.monthly_cost_quota) : null,
+        daily_cost_quota: row.daily_cost_quota != null ? Number(row.daily_cost_quota) : null,
+        weekly_cost_quota: row.weekly_cost_quota != null ? Number(row.weekly_cost_quota) : null,
+        daily_token_quota: row.daily_token_quota != null ? Number(row.daily_token_quota) : null,
+        weekly_token_quota: row.weekly_token_quota != null ? Number(row.weekly_token_quota) : null,
+        rate_multiplier: Number(row.rate_multiplier) || 1.0,
+        trial_days: row.trial_days != null ? Number(row.trial_days) : null,
+        sort_order: Number(row.sort_order) || 0,
+        display_price: typeof row.display_price === 'string' ? row.display_price : null,
+        highlight: !!row.highlight,
+        max_groups: row.max_groups != null ? Number(row.max_groups) : null,
+        max_concurrent_containers: row.max_concurrent_containers != null
+            ? Number(row.max_concurrent_containers)
+            : null,
+        max_im_channels: row.max_im_channels != null ? Number(row.max_im_channels) : null,
+        max_mcp_servers: row.max_mcp_servers != null ? Number(row.max_mcp_servers) : null,
+        max_storage_mb: row.max_storage_mb != null ? Number(row.max_storage_mb) : null,
+        allow_overage: !!row.allow_overage,
+        features: safeParseJsonArray(row.features),
+        is_default: !!row.is_default,
+        is_active: !!row.is_active,
+        created_at: String(row.created_at),
+        updated_at: String(row.updated_at),
+    };
+}
+function safeParseJsonArray(val) {
+    if (typeof val !== 'string')
+        return [];
+    try {
+        const parsed = JSON.parse(val);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+// --- User Subscriptions ---
+export function getUserActiveSubscription(userId) {
+    const row = db
+        .prepare(`SELECT s.*, p.name as plan_name FROM user_subscriptions s
+       JOIN billing_plans p ON s.plan_id = p.id
+       WHERE s.user_id = ? AND s.status = 'active'
+       ORDER BY s.created_at DESC LIMIT 1`)
+        .get(userId);
+    if (!row)
+        return undefined;
+    const plan = getBillingPlan(String(row.plan_id));
+    if (!plan)
+        return undefined;
+    return { ...mapSubscriptionRow(row), plan };
+}
+export function createUserSubscription(sub) {
+    // Cancel existing active subscriptions
+    db.prepare("UPDATE user_subscriptions SET status = 'cancelled', cancelled_at = ? WHERE user_id = ? AND status = 'active'").run(new Date().toISOString(), sub.user_id);
+    db.prepare(`INSERT INTO user_subscriptions (id, user_id, plan_id, status, started_at, expires_at, cancelled_at, trial_ends_at, notes, auto_renew, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(sub.id, sub.user_id, sub.plan_id, sub.status, sub.started_at, sub.expires_at, sub.cancelled_at, sub.trial_ends_at, sub.notes, sub.auto_renew ? 1 : 0, sub.created_at);
+    // Update user's subscription_plan_id
+    db.prepare('UPDATE users SET subscription_plan_id = ? WHERE id = ?').run(sub.plan_id, sub.user_id);
+}
+export function cancelUserSubscription(userId) {
+    const now = new Date().toISOString();
+    db.prepare("UPDATE user_subscriptions SET status = 'cancelled', cancelled_at = ? WHERE user_id = ? AND status = 'active'").run(now, userId);
+    db.prepare('UPDATE users SET subscription_plan_id = NULL WHERE id = ?').run(userId);
+}
+export function expireSubscriptions() {
+    const now = new Date().toISOString();
+    // Phase 1: Handle auto_renew=1 subscriptions — renew them instead of expiring
+    const renewableRows = db
+        .prepare("SELECT * FROM user_subscriptions WHERE status = 'active' AND auto_renew = 1 AND expires_at IS NOT NULL AND expires_at <= ?")
+        .all(now);
+    let renewed = 0;
+    for (const row of renewableRows) {
+        const userId = String(row.user_id);
+        const planId = String(row.plan_id);
+        const oldId = String(row.id);
+        const oldStarted = String(row.started_at);
+        const oldExpires = String(row.expires_at);
+        // Calculate same duration as original subscription
+        const startMs = new Date(oldStarted).getTime();
+        const expiresMs = new Date(oldExpires).getTime();
+        const durationMs = expiresMs - startMs;
+        if (durationMs <= 0)
+            continue;
+        const plan = getBillingPlan(planId);
+        if (!plan || !plan.is_active) {
+            // Plan no longer active, expire instead
+            continue;
+        }
+        // Check if user has sufficient balance for paid plans
+        if (plan.monthly_cost_usd > 0) {
+            const balance = getUserBalance(userId);
+            if (balance.balance_usd < plan.monthly_cost_usd) {
+                // Insufficient balance, expire instead
+                logBillingAudit('subscription_expired', userId, null, {
+                    planId,
+                    planName: plan.name,
+                    reason: 'insufficient_balance_for_renewal',
+                    balance: balance.balance_usd,
+                    required: plan.monthly_cost_usd,
+                });
+                continue;
+            }
+        }
+        // Wrap the entire renewal in a transaction for atomicity
+        const renewTx = db.transaction(() => {
+            // Deduct subscription cost (if paid plan)
+            if (plan.monthly_cost_usd > 0) {
+                adjustUserBalance(userId, -plan.monthly_cost_usd, 'deduction', `自动续费: ${plan.name}`, 'subscription', oldId, null, null, {
+                    source: 'subscription_renewal',
+                    operatorType: 'system',
+                    notes: `自动续费扣款: ${plan.name}`,
+                });
+            }
+            // Expire old subscription
+            db.prepare("UPDATE user_subscriptions SET status = 'expired' WHERE id = ?").run(oldId);
+            // Create new subscription with same duration
+            const newNow = new Date();
+            const newExpires = new Date(newNow.getTime() + durationMs).toISOString();
+            const newSub = {
+                id: `sub_${userId}_${Date.now()}_renew`,
+                user_id: userId,
+                plan_id: planId,
+                status: 'active',
+                started_at: newNow.toISOString(),
+                expires_at: newExpires,
+                cancelled_at: null,
+                trial_ends_at: null,
+                notes: '自动续费',
+                auto_renew: 1,
+                created_at: newNow.toISOString(),
+            };
+            db.prepare(`INSERT INTO user_subscriptions (id, user_id, plan_id, status, started_at, expires_at, cancelled_at, trial_ends_at, notes, auto_renew, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(newSub.id, newSub.user_id, newSub.plan_id, newSub.status, newSub.started_at, newSub.expires_at, newSub.cancelled_at, newSub.trial_ends_at, newSub.notes, newSub.auto_renew, newSub.created_at);
+            logBillingAudit('subscription_assigned', userId, null, {
+                planId,
+                planName: plan.name,
+                autoRenew: true,
+                renewedFrom: oldId,
+            });
+        });
+        try {
+            renewTx();
+            renewed++;
+        }
+        catch (err) {
+            logBillingAudit('subscription_expired', userId, null, {
+                planId,
+                planName: plan.name,
+                reason: 'renewal_transaction_failed',
+                error: String(err),
+            });
+        }
+    }
+    // Phase 2: Expire remaining (non-auto-renew or failed renewal)
+    const result = db
+        .prepare("UPDATE user_subscriptions SET status = 'expired' WHERE status = 'active' AND expires_at IS NOT NULL AND expires_at <= ?")
+        .run(now);
+    return result.changes + renewed;
+}
+export function updateSubscriptionAutoRenew(userId, autoRenew) {
+    const result = db
+        .prepare("UPDATE user_subscriptions SET auto_renew = ? WHERE user_id = ? AND status = 'active'")
+        .run(autoRenew ? 1 : 0, userId);
+    return result.changes > 0;
+}
+function mapSubscriptionRow(row) {
+    return {
+        id: String(row.id),
+        user_id: String(row.user_id),
+        plan_id: String(row.plan_id),
+        status: String(row.status),
+        started_at: String(row.started_at),
+        expires_at: typeof row.expires_at === 'string' ? row.expires_at : null,
+        cancelled_at: typeof row.cancelled_at === 'string' ? row.cancelled_at : null,
+        trial_ends_at: typeof row.trial_ends_at === 'string' ? row.trial_ends_at : null,
+        notes: typeof row.notes === 'string' ? row.notes : null,
+        auto_renew: !!row.auto_renew,
+        created_at: String(row.created_at),
+    };
+}
+// --- User Balances ---
+export function getUserBalance(userId) {
+    const row = db
+        .prepare('SELECT * FROM user_balances WHERE user_id = ?')
+        .get(userId);
+    if (!row) {
+        // Auto-init balance
+        const now = new Date().toISOString();
+        db.prepare('INSERT OR IGNORE INTO user_balances (user_id, balance_usd, total_deposited_usd, total_consumed_usd, updated_at) VALUES (?, 0, 0, 0, ?)').run(userId, now);
+        return {
+            user_id: userId,
+            balance_usd: 0,
+            total_deposited_usd: 0,
+            total_consumed_usd: 0,
+            updated_at: now,
+        };
+    }
+    return {
+        user_id: String(row.user_id),
+        balance_usd: Number(row.balance_usd) || 0,
+        total_deposited_usd: Number(row.total_deposited_usd) || 0,
+        total_consumed_usd: Number(row.total_consumed_usd) || 0,
+        updated_at: String(row.updated_at),
+    };
+}
+export function adjustUserBalance(userId, amount, type, description, referenceType, referenceId, actorId, idempotencyKey, options) {
+    const source = options?.source ?? 'system_adjustment';
+    const operatorType = options?.operatorType ?? 'system';
+    const notes = options?.notes ?? description ?? null;
+    const allowNegative = options?.allowNegative ?? false;
+    // Idempotency check: if key already used, return the existing transaction
+    if (idempotencyKey) {
+        const existing = db
+            .prepare('SELECT * FROM balance_transactions WHERE idempotency_key = ?')
+            .get(idempotencyKey);
+        if (existing) {
+            return {
+                id: Number(existing.id),
+                user_id: String(existing.user_id),
+                type: String(existing.type),
+                amount_usd: Number(existing.amount_usd),
+                balance_after: Number(existing.balance_after),
+                description: typeof existing.description === 'string'
+                    ? existing.description
+                    : null,
+                reference_type: typeof existing.reference_type === 'string'
+                    ? existing.reference_type
+                    : null,
+                reference_id: typeof existing.reference_id === 'string'
+                    ? existing.reference_id
+                    : null,
+                actor_id: typeof existing.actor_id === 'string' ? existing.actor_id : null,
+                source: typeof existing.source === 'string'
+                    ? existing.source
+                    : 'system_adjustment',
+                operator_type: typeof existing.operator_type === 'string'
+                    ? existing.operator_type
+                    : 'system',
+                notes: typeof existing.notes === 'string' ? existing.notes : null,
+                idempotency_key: typeof existing.idempotency_key === 'string'
+                    ? existing.idempotency_key
+                    : null,
+                created_at: String(existing.created_at),
+            };
+        }
+    }
+    const now = new Date().toISOString();
+    // Wrap read-check-update-record in a transaction for atomicity
+    const txFn = db.transaction(() => {
+        // Ensure balance row exists
+        db.prepare('INSERT OR IGNORE INTO user_balances (user_id, balance_usd, total_deposited_usd, total_consumed_usd, updated_at) VALUES (?, 0, 0, 0, ?)').run(userId, now);
+        const currentRow = db
+            .prepare('SELECT balance_usd FROM user_balances WHERE user_id = ?')
+            .get(userId);
+        const currentBalance = Number(currentRow.balance_usd);
+        const nextBalance = currentBalance + amount;
+        if (!allowNegative && nextBalance < 0) {
+            throw new Error(`Balance cannot be negative: current=${currentBalance.toFixed(2)} next=${nextBalance.toFixed(2)}`);
+        }
+        // Update balance
+        if (amount > 0) {
+            db.prepare('UPDATE user_balances SET balance_usd = balance_usd + ?, total_deposited_usd = total_deposited_usd + ?, updated_at = ? WHERE user_id = ?').run(amount, amount, now, userId);
+        }
+        else {
+            db.prepare('UPDATE user_balances SET balance_usd = balance_usd + ?, total_consumed_usd = total_consumed_usd + ?, updated_at = ? WHERE user_id = ?').run(amount, Math.abs(amount), now, userId);
+        }
+        // Read new balance within the same transaction
+        const newRow = db
+            .prepare('SELECT balance_usd FROM user_balances WHERE user_id = ?')
+            .get(userId);
+        const balanceAfter = Number(newRow.balance_usd);
+        // Record transaction
+        const result = db
+            .prepare(`INSERT INTO balance_transactions (
+        user_id, type, amount_usd, balance_after, description, reference_type,
+        reference_id, actor_id, source, operator_type, notes, created_at, idempotency_key
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(userId, type, amount, balanceAfter, description, referenceType, referenceId, actorId, source, operatorType, notes, now, idempotencyKey ?? null);
+        return {
+            id: Number(result.lastInsertRowid),
+            balanceAfter,
+        };
+    });
+    const { id: txId, balanceAfter } = txFn();
+    return {
+        id: txId,
+        user_id: userId,
+        type,
+        amount_usd: amount,
+        balance_after: balanceAfter,
+        description,
+        reference_type: referenceType,
+        reference_id: referenceId,
+        actor_id: actorId,
+        source,
+        operator_type: operatorType,
+        notes,
+        idempotency_key: idempotencyKey ?? null,
+        created_at: now,
+    };
+}
+export function getBalanceTransactions(userId, limit = 50, offset = 0) {
+    const total = db
+        .prepare('SELECT COUNT(*) as cnt FROM balance_transactions WHERE user_id = ?')
+        .get(userId).cnt;
+    const rows = db
+        .prepare('SELECT * FROM balance_transactions WHERE user_id = ? ORDER BY created_at DESC LIMIT ? OFFSET ?')
+        .all(userId, limit, offset);
+    return {
+        transactions: rows.map((r) => ({
+            id: Number(r.id),
+            user_id: String(r.user_id),
+            type: String(r.type),
+            amount_usd: Number(r.amount_usd),
+            balance_after: Number(r.balance_after),
+            description: typeof r.description === 'string' ? r.description : null,
+            reference_type: typeof r.reference_type === 'string'
+                ? r.reference_type
+                : null,
+            reference_id: typeof r.reference_id === 'string' ? r.reference_id : null,
+            actor_id: typeof r.actor_id === 'string' ? r.actor_id : null,
+            source: typeof r.source === 'string'
+                ? r.source
+                : 'system_adjustment',
+            operator_type: typeof r.operator_type === 'string'
+                ? r.operator_type
+                : 'system',
+            notes: typeof r.notes === 'string' ? r.notes : null,
+            idempotency_key: typeof r.idempotency_key === 'string' ? r.idempotency_key : null,
+            created_at: String(r.created_at),
+        })),
+        total,
+    };
+}
+// --- Monthly Usage ---
+function mapMonthlyUsageRow(row) {
+    return {
+        user_id: String(row.user_id),
+        month: String(row.month),
+        total_input_tokens: Number(row.total_input_tokens) || 0,
+        total_output_tokens: Number(row.total_output_tokens) || 0,
+        total_cost_usd: Number(row.total_cost_usd) || 0,
+        message_count: Number(row.message_count) || 0,
+        updated_at: String(row.updated_at),
+    };
+}
+export function getMonthlyUsage(userId, month) {
+    const row = db
+        .prepare('SELECT * FROM monthly_usage WHERE user_id = ? AND month = ?')
+        .get(userId, month);
+    if (!row)
+        return undefined;
+    return mapMonthlyUsageRow(row);
+}
+export function incrementMonthlyUsage(userId, month, inputTokens, outputTokens, costUsd) {
+    const now = new Date().toISOString();
+    db.prepare(`INSERT INTO monthly_usage (user_id, month, total_input_tokens, total_output_tokens, total_cost_usd, message_count, updated_at)
+     VALUES (?, ?, ?, ?, ?, 1, ?)
+     ON CONFLICT(user_id, month) DO UPDATE SET
+       total_input_tokens = total_input_tokens + excluded.total_input_tokens,
+       total_output_tokens = total_output_tokens + excluded.total_output_tokens,
+       total_cost_usd = total_cost_usd + excluded.total_cost_usd,
+       message_count = message_count + 1,
+       updated_at = excluded.updated_at`).run(userId, month, inputTokens, outputTokens, costUsd, now);
+}
+export function getUserMonthlyUsageHistory(userId, months = 6) {
+    return db
+        .prepare('SELECT * FROM monthly_usage WHERE user_id = ? ORDER BY month DESC LIMIT ?')
+        .all(userId, months).map(mapMonthlyUsageRow);
+}
+// --- Redeem Codes ---
+export function getRedeemCode(code) {
+    const row = db
+        .prepare('SELECT * FROM redeem_codes WHERE code = ?')
+        .get(code);
+    if (!row)
+        return undefined;
+    return mapRedeemCodeRow(row);
+}
+export function getAllRedeemCodes() {
+    return db
+        .prepare('SELECT * FROM redeem_codes ORDER BY created_at DESC')
+        .all().map(mapRedeemCodeRow);
+}
+export function createRedeemCode(code) {
+    db.prepare(`INSERT INTO redeem_codes (code, type, value_usd, plan_id, duration_days, max_uses, used_count, expires_at, created_by, notes, batch_id, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(code.code, code.type, code.value_usd, code.plan_id, code.duration_days, code.max_uses, code.used_count, code.expires_at, code.created_by, code.notes, code.batch_id, code.created_at);
+}
+export function incrementRedeemCodeUsage(code, userId) {
+    const now = new Date().toISOString();
+    db.prepare('UPDATE redeem_codes SET used_count = used_count + 1 WHERE code = ?').run(code);
+    db.prepare('INSERT INTO redeem_code_usage (code, user_id, redeemed_at) VALUES (?, ?, ?)').run(code, userId, now);
+}
+export function deleteRedeemCode(code) {
+    const result = db
+        .prepare('DELETE FROM redeem_codes WHERE code = ?')
+        .run(code);
+    return result.changes > 0;
+}
+export function hasUserRedeemedCode(userId, code) {
+    const row = db
+        .prepare('SELECT COUNT(*) as cnt FROM redeem_code_usage WHERE user_id = ? AND code = ?')
+        .get(userId, code);
+    return row.cnt > 0;
+}
+function mapRedeemCodeRow(row) {
+    return {
+        code: String(row.code),
+        type: String(row.type),
+        value_usd: row.value_usd != null ? Number(row.value_usd) : null,
+        plan_id: typeof row.plan_id === 'string' ? row.plan_id : null,
+        duration_days: row.duration_days != null ? Number(row.duration_days) : null,
+        max_uses: Number(row.max_uses) || 1,
+        used_count: Number(row.used_count) || 0,
+        expires_at: typeof row.expires_at === 'string' ? row.expires_at : null,
+        created_by: String(row.created_by),
+        notes: typeof row.notes === 'string' ? row.notes : null,
+        batch_id: typeof row.batch_id === 'string' ? row.batch_id : null,
+        created_at: String(row.created_at),
+    };
+}
+// --- Billing Audit Log ---
+export function logBillingAudit(eventType, userId, actorId, details) {
+    db.prepare('INSERT INTO billing_audit_log (event_type, user_id, actor_id, details, created_at) VALUES (?, ?, ?, ?, ?)').run(eventType, userId, actorId, details ? JSON.stringify(details) : null, new Date().toISOString());
+}
+export function getBillingAuditLog(limit = 50, offset = 0, userId, eventType) {
+    const conditions = [];
+    const params = [];
+    if (userId) {
+        conditions.push('user_id = ?');
+        params.push(userId);
+    }
+    if (eventType) {
+        conditions.push('event_type = ?');
+        params.push(eventType);
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+    const total = db
+        .prepare(`SELECT COUNT(*) as cnt FROM billing_audit_log ${where}`)
+        .get(...params).cnt;
+    const rows = db
+        .prepare(`SELECT * FROM billing_audit_log ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`)
+        .all(...params, limit, offset);
+    return {
+        logs: rows.map((r) => ({
+            id: Number(r.id),
+            event_type: String(r.event_type),
+            user_id: String(r.user_id),
+            actor_id: typeof r.actor_id === 'string' ? r.actor_id : null,
+            details: typeof r.details === 'string'
+                ? JSON.parse(r.details)
+                : null,
+            created_at: String(r.created_at),
+        })),
+        total,
+    };
+}
+// --- Billing summary helpers ---
+export function getUserGroupCount(userId) {
+    const row = db
+        .prepare("SELECT COUNT(DISTINCT rg.folder) as cnt FROM registered_groups rg WHERE rg.created_by = ? AND rg.jid LIKE 'web:%'")
+        .get(userId);
+    return row.cnt;
+}
+export function getAllUserBillingOverview() {
+    const month = new Date().toISOString().slice(0, 7);
+    return db
+        .prepare(`SELECT u.id as user_id, u.username, u.display_name, u.role,
+              s.plan_id, p.name as plan_name,
+              COALESCE(b.balance_usd, 0) as balance_usd,
+              COALESCE(mu.total_cost_usd, 0) as current_month_cost
+       FROM users u
+       LEFT JOIN user_subscriptions s ON s.user_id = u.id AND s.status = 'active'
+       LEFT JOIN billing_plans p ON p.id = s.plan_id
+       LEFT JOIN user_balances b ON b.user_id = u.id
+       LEFT JOIN monthly_usage mu ON mu.user_id = u.id AND mu.month = ?
+       WHERE u.status != 'deleted'
+       ORDER BY u.created_at ASC`)
+        .all(month);
+}
+export function getRevenueStats() {
+    const month = new Date().toISOString().slice(0, 7);
+    const deposited = db
+        .prepare('SELECT COALESCE(SUM(total_deposited_usd), 0) as total FROM user_balances')
+        .get().total;
+    const consumed = db
+        .prepare('SELECT COALESCE(SUM(total_consumed_usd), 0) as total FROM user_balances')
+        .get().total;
+    const activeSubs = db
+        .prepare("SELECT COUNT(*) as cnt FROM user_subscriptions WHERE status = 'active'")
+        .get().cnt;
+    const monthRevenue = db
+        .prepare('SELECT COALESCE(SUM(total_cost_usd), 0) as total FROM monthly_usage WHERE month = ?')
+        .get(month).total;
+    return {
+        totalDeposited: deposited,
+        totalConsumed: consumed,
+        activeSubscriptions: activeSubs,
+        currentMonthRevenue: monthRevenue,
+    };
+}
+// --- Daily Usage ---
+function mapDailyUsageRow(row) {
+    return {
+        user_id: String(row.user_id),
+        date: String(row.date),
+        total_input_tokens: Number(row.total_input_tokens) || 0,
+        total_output_tokens: Number(row.total_output_tokens) || 0,
+        total_cost_usd: Number(row.total_cost_usd) || 0,
+        message_count: Number(row.message_count) || 0,
+    };
+}
+export function incrementDailyUsage(userId, date, inputTokens, outputTokens, costUsd) {
+    db.prepare(`INSERT INTO daily_usage (user_id, date, total_input_tokens, total_output_tokens, total_cost_usd, message_count)
+     VALUES (?, ?, ?, ?, ?, 1)
+     ON CONFLICT(user_id, date) DO UPDATE SET
+       total_input_tokens = total_input_tokens + excluded.total_input_tokens,
+       total_output_tokens = total_output_tokens + excluded.total_output_tokens,
+       total_cost_usd = total_cost_usd + excluded.total_cost_usd,
+       message_count = message_count + 1`).run(userId, date, inputTokens, outputTokens, costUsd);
+}
+export function getDailyUsage(userId, date) {
+    const row = db
+        .prepare('SELECT * FROM daily_usage WHERE user_id = ? AND date = ?')
+        .get(userId, date);
+    if (!row)
+        return undefined;
+    return mapDailyUsageRow(row);
+}
+export function getWeeklyUsageSummary(userId) {
+    // Align to calendar week (Monday–Sunday) to match checkQuota() reset logic
+    const now = new Date();
+    const dayOfWeek = now.getDay(); // 0=Sun, 1=Mon, ...
+    const daysSinceMonday = dayOfWeek === 0 ? 6 : dayOfWeek - 1;
+    const monday = new Date(now);
+    monday.setDate(now.getDate() - daysSinceMonday);
+    const startDate = monday.toISOString().slice(0, 10);
+    const row = db
+        .prepare(`SELECT COALESCE(SUM(total_cost_usd), 0) as totalCost,
+              COALESCE(SUM(total_input_tokens + total_output_tokens), 0) as totalTokens
+       FROM daily_usage WHERE user_id = ? AND date >= ?`)
+        .get(userId, startDate);
+    return { totalCost: row.totalCost, totalTokens: row.totalTokens };
+}
+export function getUserDailyUsageHistory(userId, days = 14) {
+    return db
+        .prepare('SELECT * FROM daily_usage WHERE user_id = ? ORDER BY date DESC LIMIT ?')
+        .all(userId, days).map(mapDailyUsageRow);
+}
+export function getDailyUsageSumForMonth(userId, month) {
+    const startDate = `${month}-01`;
+    // End date: first day of next month
+    const [y, m] = month.split('-').map(Number);
+    const nextMonth = m === 12 ? `${y + 1}-01` : `${y}-${String(m + 1).padStart(2, '0')}`;
+    const endDate = `${nextMonth}-01`;
+    const row = db
+        .prepare(`SELECT COALESCE(SUM(total_input_tokens), 0) as totalInputTokens,
+              COALESCE(SUM(total_output_tokens), 0) as totalOutputTokens,
+              COALESCE(SUM(total_cost_usd), 0) as totalCost,
+              COALESCE(SUM(message_count), 0) as messageCount
+       FROM daily_usage WHERE user_id = ? AND date >= ? AND date < ?`)
+        .get(userId, startDate, endDate);
+    return row;
+}
+export function correctMonthlyUsage(userId, month, inputTokens, outputTokens, costUsd, messageCount) {
+    const now = new Date().toISOString();
+    db.prepare(`INSERT INTO monthly_usage (user_id, month, total_input_tokens, total_output_tokens, total_cost_usd, message_count, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(user_id, month) DO UPDATE SET
+       total_input_tokens = excluded.total_input_tokens,
+       total_output_tokens = excluded.total_output_tokens,
+       total_cost_usd = excluded.total_cost_usd,
+       message_count = excluded.message_count,
+       updated_at = excluded.updated_at`).run(userId, month, inputTokens, outputTokens, costUsd, messageCount, now);
+}
+export function getSubscriptionHistory(userId) {
+    return db
+        .prepare(`SELECT s.*, p.name as plan_name FROM user_subscriptions s
+         JOIN billing_plans p ON s.plan_id = p.id
+         WHERE s.user_id = ?
+         ORDER BY s.created_at DESC`)
+        .all(userId).map((row) => ({
+        ...mapSubscriptionRow(row),
+        plan_name: String(row.plan_name),
+    }));
+}
+export function getRedeemCodeUsageDetails(code) {
+    return db
+        .prepare(`SELECT rcu.user_id, u.username, rcu.redeemed_at
+       FROM redeem_code_usage rcu
+       LEFT JOIN users u ON u.id = rcu.user_id
+       WHERE rcu.code = ?
+       ORDER BY rcu.redeemed_at DESC`)
+        .all(code);
+}
+export function getDashboardStats() {
+    const today = new Date().toISOString().slice(0, 10);
+    const month = new Date().toISOString().slice(0, 7);
+    const totalUsers = db
+        .prepare("SELECT COUNT(*) as cnt FROM users WHERE status != 'deleted'")
+        .get().cnt;
+    const activeUsers = db
+        .prepare('SELECT COUNT(DISTINCT user_id) as cnt FROM daily_usage WHERE date = ?')
+        .get(today).cnt;
+    const planDistribution = db
+        .prepare(`SELECT COALESCE(p.name, '无套餐') as plan_name, COUNT(*) as count
+       FROM users u
+       LEFT JOIN user_subscriptions s ON s.user_id = u.id AND s.status = 'active'
+       LEFT JOIN billing_plans p ON p.id = s.plan_id
+       WHERE u.status != 'deleted'
+       GROUP BY p.name
+       ORDER BY count DESC`)
+        .all();
+    const todayCost = db
+        .prepare('SELECT COALESCE(SUM(total_cost_usd), 0) as total FROM daily_usage WHERE date = ?')
+        .get(today).total;
+    const monthCost = db
+        .prepare('SELECT COALESCE(SUM(total_cost_usd), 0) as total FROM monthly_usage WHERE month = ?')
+        .get(month).total;
+    const activeSubscriptions = db
+        .prepare("SELECT COUNT(*) as cnt FROM user_subscriptions WHERE status = 'active'")
+        .get().cnt;
+    return {
+        activeUsers,
+        totalUsers,
+        planDistribution,
+        todayCost,
+        monthCost,
+        activeSubscriptions,
+    };
+}
+export function getRevenueTrend(months = 6) {
+    return db
+        .prepare(`SELECT month, SUM(total_cost_usd) as revenue, COUNT(DISTINCT user_id) as users
+       FROM monthly_usage
+       GROUP BY month
+       ORDER BY month DESC
+       LIMIT ?`)
+        .all(months);
+}
+export function batchAssignPlan(userIds, planId, actorId, durationDays) {
+    const plan = getBillingPlan(planId);
+    if (!plan)
+        throw new Error(`Plan not found: ${planId}`);
+    const now = new Date();
+    const expiresAt = durationDays
+        ? new Date(now.getTime() + durationDays * 24 * 60 * 60 * 1000).toISOString()
+        : null;
+    let count = 0;
+    const txn = db.transaction(() => {
+        for (const userId of userIds) {
+            // Cancel existing
+            db.prepare("UPDATE user_subscriptions SET status = 'cancelled', cancelled_at = ? WHERE user_id = ? AND status = 'active'").run(now.toISOString(), userId);
+            const subId = `sub_${userId}_${Date.now()}_${count}`;
+            db.prepare(`INSERT INTO user_subscriptions (id, user_id, plan_id, status, started_at, expires_at, auto_renew, created_at)
+         VALUES (?, ?, ?, 'active', ?, ?, 0, ?)`).run(subId, userId, planId, now.toISOString(), expiresAt, now.toISOString());
+            db.prepare('UPDATE users SET subscription_plan_id = ? WHERE id = ?').run(planId, userId);
+            logBillingAudit('subscription_assigned', userId, actorId, {
+                planId,
+                planName: plan.name,
+                durationDays: durationDays ?? null,
+                batch: true,
+            });
+            count++;
+        }
+    });
+    txn();
+    return count;
+}
+export function getPlanSubscriberCount(planId) {
+    const row = db
+        .prepare("SELECT COUNT(*) as cnt FROM user_subscriptions WHERE plan_id = ? AND status = 'active'")
+        .get(planId);
+    return row.cnt;
+}
+export function getAllPlanSubscriberCounts() {
+    const rows = db
+        .prepare("SELECT plan_id, COUNT(*) as cnt FROM user_subscriptions WHERE status = 'active' GROUP BY plan_id")
+        .all();
+    const result = {};
+    for (const row of rows) {
+        result[row.plan_id] = row.cnt;
+    }
+    return result;
+}
+/**
+ * Atomically increment redeem code usage with optimistic locking.
+ * Returns true if the increment succeeded (used_count < max_uses).
+ */
+export function tryIncrementRedeemCodeUsage(code, userId) {
+    const now = new Date().toISOString();
+    return db.transaction(() => {
+        const result = db
+            .prepare('UPDATE redeem_codes SET used_count = used_count + 1 WHERE code = ? AND used_count < max_uses')
+            .run(code);
+        if (result.changes === 0)
+            return false;
+        db.prepare('INSERT INTO redeem_code_usage (code, user_id, redeemed_at) VALUES (?, ?, ?)').run(code, userId, now);
+        return true;
+    })();
+}
+/**
+ * Close the database connection.
+ * Should be called during graceful shutdown.
+ */
+export function closeDatabase() {
+    _stmts = null;
+    _newMsgStmtCache.clear();
+    if (db) {
+        db.close();
+    }
+}