feishu-user-plugin 1.3.7 → 1.3.9

package/src/events/ws-server.js

@@ -0,0 +1,156 @@
+// src/events/ws-server.js — rewritten for v1.3.9 owner-arbitrated mode.
+//
+// What this owns:
+//   - createWSServer(opts) — factory for WS client + event dispatcher.
+//   - v1.3.9: In owner mode (logPath provided), events go to events.jsonl
+//     directly instead of the in-memory buffer.
+//   - Tracks wsState / wsProfile so downstream can filter dropped events.
+//
+// What it does NOT own:
+//   - Owner-lock acquisition (src/events/owner.js).
+//   - Cursor protocol (src/events/cursor.js).
+
+'use strict';
+
+const lark = require('@larksuiteoapi/node-sdk');
+const { EventBuffer, DEFAULT_CAP } = require('./event-buffer');
+const { stderrLogger } = require('../logger');
+const { appendEvent } = require('./event-log');
+
+// Build the handler that writes a normalised event row.
+// In v1.3.9 owner mode, we write to events.jsonl directly with a profile tag.
+// In legacy mode (no logPath given) we fall back to the in-memory buffer.
+function _eventRowHandler({ buffer, eventType, getProfile, getWsState, logPath }) {
+  return async (data) => {
+    const wsState = getWsState();
+    if (wsState !== 'connected') {
+      // Drop events received during 'switching' / 'disconnected' — we don't
+      // know which profile they belong to.
+      return;
+    }
+    const event = {
+      event_id: data?.event_id || data?.header?.event_id || 'evt_' + Math.random().toString(36).slice(2),
+      ts: Date.now(),
+      profile: getProfile(),
+      event_type: eventType,
+      header: data?.header || null,
+      event: data?.event || data,
+    };
+    if (logPath) {
+      try {
+        appendEvent(logPath, event);
+      } catch (e) {
+        // Disk-full or similar — fall back to in-memory buffer.
+        console.error(`[feishu-user-plugin] events.jsonl append failed: ${e.message}; falling back to in-memory buffer`);
+        buffer.push(event);
+      }
+    } else {
+      buffer.push(event);
+    }
+  };
+}
+
+function createWSServer({
+  appId, appSecret,
+  bufferCap = DEFAULT_CAP,
+  registrations = ['im.message.receive_v1'],
+  logPath = null,                 // NEW: when set, events go to events.jsonl
+  initialProfile = 'default',     // NEW: profile name to tag events with
+} = {}) {
+  if (!appId || !appSecret) throw new Error('createWSServer: appId + appSecret required');
+
+  const buffer = new EventBuffer({ cap: bufferCap });
+  let wsClient = null;
+  let started = false;
+  let stopped = false;
+  let wsProfile = initialProfile;
+  let wsState = 'disconnected';   // disconnected | connected | switching
+  let lastReconnectAt = null;
+  let reconnectAttempts = 0;
+
+  const dispatcher = new lark.EventDispatcher({
+    logger: stderrLogger,
+    loggerLevel: lark.LoggerLevel.warn,
+  });
+
+  const handlers = {};
+  for (const t of registrations) {
+    handlers[t] = _eventRowHandler({
+      buffer, eventType: t,
+      getProfile: () => wsProfile,
+      getWsState: () => wsState,
+      logPath,
+    });
+  }
+  try {
+    dispatcher.register(handlers);
+  } catch (e) {
+    console.error(`[feishu-user-plugin] WS event registration failed: ${e.message}; falling back to im.message.receive_v1 only`);
+    dispatcher.register({
+      'im.message.receive_v1': _eventRowHandler({
+        buffer, eventType: 'im.message.receive_v1',
+        getProfile: () => wsProfile, getWsState: () => wsState, logPath,
+      }),
+    });
+  }
+
+  async function start() {
+    if (started) return;
+    started = true;
+    wsState = 'switching';
+    wsClient = new lark.WSClient({
+      appId, appSecret,
+      logger: stderrLogger,
+      loggerLevel: lark.LoggerLevel.warn,
+    });
+    try {
+      await wsClient.start({ eventDispatcher: dispatcher });
+      wsState = 'connected';
+      lastReconnectAt = Date.now();
+      console.error(`[feishu-user-plugin] WS connected (profile=${wsProfile}) — listening for: ${registrations.join(', ')}`);
+    } catch (e) {
+      wsState = 'disconnected';
+      reconnectAttempts++;
+      console.error(`[feishu-user-plugin] WS start failed: ${e.message}. Continuing without realtime events.`);
+      started = false;
+      wsClient = null;
+    }
+  }
+
+  async function stop() {
+    if (stopped) return;
+    stopped = true;
+    wsState = 'disconnected';
+    if (wsClient) {
+      try { wsClient.close(); } catch (_) {}
+      wsClient = null;
+    }
+  }
+
+  // For switching: stop, then start with a new profile/registrations.
+  // The registrations list is currently fixed at construction; full switching
+  // requires re-creating the WSClient. This helper just stops + nulls so the
+  // caller can construct a new server.
+  async function reconfigureProfile(newProfile) {
+    wsState = 'switching';
+    wsProfile = 'switching';   // tag-irrelevant during transition
+    await stop();
+    started = false; stopped = false;
+    wsProfile = newProfile;
+    await start();
+  }
+
+  function getStatus() {
+    return {
+      state: wsState,
+      wsProfile,
+      subscribed_events: registrations.slice(),
+      lastReconnectAt,
+      reconnectAttempts,
+    };
+  }
+
+  return { buffer, start, stop, reconfigureProfile, getStatus, get isRunning() { return started && !stopped; } };
+}
+
+module.exports = { createWSServer };

package/src/oauth.js

@@ -14,9 +14,44 @@
 
 const http = require('http');
 const { execSync } = require('child_process');
-const { readCredentials, persistToConfig } = require('./config');
+const credentialsModule = require('./auth/credentials');
+const legacyConfig = require('./config');
 
-const creds = readCredentials();
+// v1.3.9: profile-aware. Accepts `--profile <name>` (defaults to credentials.json::active);
+// reads APP_ID/SECRET from that profile, persists UAT back to that profile.
+// When credentials.json doesn't exist, falls back to legacy harness env path
+// (which is what v1.3.6 → v1.3.8 did).
+function _parseTargetProfile() {
+  const argv = process.argv.slice(2);
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--profile' && argv[i + 1]) return argv[++i];
+  }
+  return null;
+}
+
+const TARGET_PROFILE = _parseTargetProfile();
+const _hasCanonical = !!credentialsModule.readCanonical();
+let creds;
+let profileLabel;
+if (_hasCanonical) {
+  const targetName = TARGET_PROFILE || credentialsModule.getActiveProfileName();
+  try {
+    creds = credentialsModule.getActiveProfileEnv(targetName);
+    profileLabel = `credentials.json::profiles[${targetName}]`;
+  } catch (e) {
+    console.error(`OAuth target profile error: ${e.message}`);
+    console.error(`Available: ${credentialsModule.listProfileNames().join(', ')}`);
+    process.exit(1);
+  }
+  if (TARGET_PROFILE) console.log(`OAuth target profile: ${TARGET_PROFILE}`);
+} else {
+  if (TARGET_PROFILE) {
+    console.error(`--profile flag given but credentials.json doesn't exist. Run \`npx feishu-user-plugin migrate --confirm\` first, or remove --profile to use legacy env path.`);
+    process.exit(1);
+  }
+  creds = legacyConfig.readCredentials();
+  profileLabel = 'harness env (legacy)';
+}
 const APP_ID = creds.LARK_APP_ID;
 const APP_SECRET = creds.LARK_APP_SECRET;
 const PORT = 9997;
@@ -118,12 +153,18 @@ function saveToken(tokenData) {
     LARK_UAT_EXPIRES: String(Math.floor(Date.now() / 1000 + (typeof tokenData.expires_in === 'number' && tokenData.expires_in > 0 ? tokenData.expires_in : 7200))),
   };
 
-  const ok = persistToConfig(updates);
+  let ok = false;
+  if (_hasCanonical) {
+    const targetName = TARGET_PROFILE || credentialsModule.getActiveProfileName();
+    ok = credentialsModule.persistProfileUpdate(targetName, updates);
+    if (ok) console.log(`Tokens written to ${profileLabel}`);
+  } else {
+    ok = legacyConfig.persistToConfig(updates);
+    if (ok) console.log(`Tokens written to ${profileLabel}`);
+  }
   if (!ok) {
-    console.error('WARNING: Tokens could not be saved to config. Copy them manually:');
-    for (const [k, v] of Object.entries(updates)) {
-      console.error(`  ${k}=${v}`);
-    }
+    console.error('WARNING: Tokens could not be saved. Copy them manually:');
+    for (const [k, v] of Object.entries(updates)) console.error(`  ${k}=${v}`);
   }
 }
 

package/src/resolver.js

@@ -144,8 +144,18 @@ async function resolveToken(input, official) {
   return r.obj_token;
 }
 
+/**
+ * Clear the wiki-node resolution cache. Called by the profile-sync hook in
+ * server.js when the active profile changes, so that wiki nodes belonging to
+ * the previous profile's app credentials don't poison lookups for the new one.
+ */
+function clearCache() {
+  _cache.clear();
+}
+
 module.exports = {
   parseFeishuInput,
   resolveToObj,
   resolveToken,
+  clearCache,
 };

package/src/server.js

@@ -13,6 +13,8 @@
 //   - Config discovery / persistence: src/config/*.
 
 const path = require('path');
+const fs = require('fs');
+const os = require('os');
 const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
@@ -26,6 +28,7 @@ const { LarkOfficialClient } = require('./clients/official');
 const { resolveToken } = require('./resolver');
 const { listPrompts, getPrompt } = require('./prompts');
 const credentials = require('./auth/credentials');
+const profileRouter = require('./auth/profile-router');
 
 // --- Tool modules ---
 // Adding a new domain: create src/tools/<x>.js exporting { schemas, handlers }
@@ -38,6 +41,7 @@ const TOOL_MODULES = [
   require('./tools/diagnostics'),
   require('./tools/docs'),
   require('./tools/drive'),
+  require('./tools/events'),
   require('./tools/groups'),
   require('./tools/im-read'),
   require('./tools/messaging-bot'),
@@ -63,12 +67,48 @@ const HANDLERS = Object.fromEntries(TOOL_MODULES.flatMap((m) => Object.entries(m
 // When credentials.json exists, switching also persists the active field so
 // cross-process MCP servers see the same active profile after restart.
 
+const events = require('./events');
+
+const FEISHU_HOME = path.join(os.homedir(), '.feishu-user-plugin');
+const EVENTS_LOG_PATH = path.join(FEISHU_HOME, 'events.jsonl');
+
 let userClient = null;
 let officialClient = null;
+let wsServer = null;
+let ownerHandle = null;       // returned by tryClaim when isOwner
+let ownerHeartbeatTimer = null;
+let nonOwnerPollTimer = null;
+let _ownerStartCallbacks = [];
+
+function _onBecomeOwner(cb) { _ownerStartCallbacks.push(cb); }
+
+function _stopHeartbeat() {
+  if (ownerHeartbeatTimer) { clearInterval(ownerHeartbeatTimer); ownerHeartbeatTimer = null; }
+}
+function _stopNonOwnerPoll() {
+  if (nonOwnerPollTimer) { clearInterval(nonOwnerPollTimer); nonOwnerPollTimer = null; }
+}
+
+function getEventBuffer() {
+  return wsServer ? wsServer.buffer : null;
+}
 // The "current" profile this in-memory MCP server is pinned to. Initialised
 // from the persisted active profile (credentials.json) at boot, but in-process
 // switches may diverge from the persisted active until the next server restart.
+//
+// Profile selection precedence (v1.3.9 A.2 — SSOT):
+//   1. credentials.json::active — single-file persisted active (canonical SSOT)
+//   2. process.env.FEISHU_PLUGIN_PROFILE — harness pointer (bootstrap-only, when
+//      credentials.json does not exist)
+//   3. 'default' — legacy zero-config path
+// Note: FEISHU_PLUGIN_PROFILE in the harness env is now a bootstrap pointer only.
+// Once credentials.json exists, its `active` field is authoritative; cross-process
+// sync propagates active-profile changes without a server restart.
 let currentProfile = credentials.getActiveProfileName();
+if (!credentials.readCanonical() && process.env.FEISHU_PLUGIN_PROFILE) {
+  // Bootstrap-only: legacy env users without canonical credentials file.
+  currentProfile = process.env.FEISHU_PLUGIN_PROFILE;
+}
 
 function profileEnv(name) {
   return credentials.getActiveProfileEnv(name);
@@ -122,6 +162,157 @@ function loadUATFromEnv(client, env) {
   client._uatExpires = expires || client._decodeTokenExpiry(token);
 }
 
+// --- Owner control loop (v1.3.9 A.1) ---
+
+async function _claimAndStart() {
+  const claim = events.owner.tryClaim(FEISHU_HOME, { info: { role: 'ws_owner' } });
+  if (!claim.isOwner) {
+    // Become non-owner: poll lock health every 30s, attempt takeover when stale.
+    if (!nonOwnerPollTimer) {
+      nonOwnerPollTimer = setInterval(() => {
+        const info = events.owner.readOwnerInfo(FEISHU_HOME);
+        if (!info.exists || !info.alive) {
+          _claimAndStart().catch((e) => console.error(`[feishu-user-plugin] takeover attempt failed: ${e.message}`));
+        }
+      }, events.owner.TAKEOVER_POLL_INTERVAL_MS);
+      nonOwnerPollTimer.unref?.();
+    }
+    return;
+  }
+
+  ownerHandle = claim;
+  _stopNonOwnerPoll();
+  // Repair tail before WS starts pushing events
+  try { events.log.repairTail(EVENTS_LOG_PATH); } catch (_) {}
+
+  // Start WS with current active profile and its events list.
+  const profileName = currentProfile;
+  let activeEnv;
+  try { activeEnv = profileEnv(profileName); } catch (_) { return; }
+  if (!activeEnv.LARK_APP_ID || !activeEnv.LARK_APP_SECRET) return;
+
+  const eventsList = _getProfileEventsList(profileName);
+  wsServer = events.createWSServer({
+    appId: activeEnv.LARK_APP_ID,
+    appSecret: activeEnv.LARK_APP_SECRET,
+    registrations: eventsList,
+    logPath: EVENTS_LOG_PATH,
+    initialProfile: profileName,
+  });
+  wsServer.start().catch((e) => console.error(`[feishu-user-plugin] WS start error: ${e.message}`));
+
+  // Heartbeat + check active changes every 15s.
+  let lastCredMtime = _credMtime();
+  ownerHeartbeatTimer = setInterval(() => {
+    if (ownerHandle) ownerHandle.heartbeat();
+    const m = _credMtime();
+    if (m !== null && m !== lastCredMtime) {
+      lastCredMtime = m;
+      _maybeReconfigure().catch((e) => console.error(`[feishu-user-plugin] reconfigure failed: ${e.message}`));
+    }
+    // Defer-rotate check
+    try {
+      const snap = events.cursor.readSnapshot(FEISHU_HOME);
+      const SOFT_CAP = 10 * 1024 * 1024;
+      const HARD_CAP = 20 * 1024 * 1024;
+      const rot = events.log.maybeRotate(EVENTS_LOG_PATH, snap.cursor.offset, SOFT_CAP);
+      if (rot.rotated) {
+        events.cursor.resetCursorTo(FEISHU_HOME, 0);
+      } else if (snap.fileSize > HARD_CAP) {
+        events.log.forceRotate(EVENTS_LOG_PATH, snap.fileSize);
+        events.cursor.resetCursorTo(FEISHU_HOME, 0);
+      }
+      // Also clean up old .dropped files daily-ish (every heartbeat is cheap)
+      events.log.cleanupDropped(EVENTS_LOG_PATH, 7);
+    } catch (e) {
+      console.error(`[feishu-user-plugin] rotation check failed: ${e.message}`);
+    }
+  }, events.owner.HEARTBEAT_INTERVAL_MS);
+  ownerHeartbeatTimer.unref?.();
+
+  for (const cb of _ownerStartCallbacks) {
+    try { cb(); } catch (_) {}
+  }
+}
+
+function _credMtime() {
+  try {
+    const p = path.join(FEISHU_HOME, 'credentials.json');
+    return fs.statSync(p).mtimeMs;
+  } catch (_) { return null; }
+}
+
+// Cross-process active-profile sync (v1.3.9 A.2).
+// Each tool call: stat credentials.json; if mtime changed AND active differs
+// from in-memory currentProfile, do an in-process setActiveProfile().
+// _credMtimeBaseline starts null — first call sets the baseline without syncing.
+let _credMtimeBaseline = null;
+
+function _syncActiveProfileFromDisk() {
+  const m = _credMtime();
+  if (m === null) return; // no credentials.json — nothing to sync
+  if (_credMtimeBaseline === null) { _credMtimeBaseline = m; return; }
+  if (m === _credMtimeBaseline) return; // unchanged
+  _credMtimeBaseline = m;
+  let newActive;
+  try { newActive = credentials.getActiveProfileName(); } catch (_) { return; }
+  if (newActive === currentProfile) return;
+  console.error(`[feishu-user-plugin] active profile changed on disk: ${currentProfile} → ${newActive}`);
+  // Use the same setActiveProfile flow that switch_profile uses, except don't
+  // re-write credentials.json (which it already reflects the change).
+  try {
+    credentials.getActiveProfileEnv(newActive); // validate profile exists
+    currentProfile = newActive;
+    userClient = null;
+    officialClient = null;
+    // resolver.js has a wiki-node resolution cache; clear it on profile switch
+    // so wiki nodes belonging to the previous app-id don't cross-contaminate.
+    require('./resolver').clearCache();
+  } catch (e) {
+    console.error(`[feishu-user-plugin] sync to "${newActive}" failed: ${e.message}; staying on "${currentProfile}"`);
+  }
+}
+
+async function _maybeReconfigure() {
+  if (!ownerHandle || !wsServer) return;
+  const newActive = credentials.getActiveProfileName();
+  const newEvents = _getProfileEventsList(newActive);
+  const status = wsServer.getStatus();
+  const sameProfile = status.wsProfile === newActive;
+  const sameEvents = JSON.stringify(status.subscribed_events) === JSON.stringify(newEvents);
+  if (sameProfile && sameEvents) return;
+
+  console.error(`[feishu-user-plugin] WS reconfigure: profile ${status.wsProfile}→${newActive}, events ${status.subscribed_events.length}→${newEvents.length}`);
+
+  // Tear down + rebuild because registrations are fixed at construction.
+  await wsServer.stop();
+  let activeEnv;
+  try { activeEnv = profileEnv(newActive); } catch (_) { return; }
+  if (!activeEnv.LARK_APP_ID || !activeEnv.LARK_APP_SECRET) return;
+  wsServer = events.createWSServer({
+    appId: activeEnv.LARK_APP_ID,
+    appSecret: activeEnv.LARK_APP_SECRET,
+    registrations: newEvents,
+    logPath: EVENTS_LOG_PATH,
+    initialProfile: newActive,
+  });
+  await wsServer.start();
+}
+
+function _getProfileEventsList(profileName) {
+  const canonical = credentials.readCanonical();
+  if (canonical && canonical.profiles[profileName]?.events) {
+    return canonical.profiles[profileName].events.slice();
+  }
+  // Bootstrap: env override
+  const env = process.env.FEISHU_PLUGIN_EXTRA_EVENTS;
+  if (env) {
+    const list = env.split(',').map(s => s.trim()).filter(Boolean);
+    if (list.length) return ['im.message.receive_v1', ...list];
+  }
+  return ['im.message.receive_v1'];
+}
+
 // Resolver helper: turn document_id / app_token / wiki node / Feishu URL into
 // a native token. No-op for already-native inputs. See src/resolver.js.
 async function resolveDocId(input) {
@@ -137,6 +328,7 @@ function buildCtx() {
   return {
     getUserClient,
     getOfficialClient,
+    getEventBuffer,
     listProfiles: () => credentials.listProfileNames(),
     getActiveProfile: () => currentProfile,
     setActiveProfile: (n) => {
@@ -145,11 +337,45 @@ function buildCtx() {
       currentProfile = n;
       userClient = null;
       officialClient = null;
+      // Clear resolver cache so wiki-node lookups don't carry over from the old profile.
+      require('./resolver').clearCache();
       // Persist the active-field flip when credentials.json exists so peer MCP
-      // servers see the new active profile on next read. Tolerated when no file.
-      try { credentials.setActiveProfile(n); } catch (_) {}
+      // servers see the new active profile on next read. The credentials module
+      // throws if credentials.json doesn't exist OR if `n` isn't in profiles[];
+      // the first is benign (legacy mode), the second is a real bug — log it
+      // either way at warn level instead of swallowing silently.
+      try { credentials.setActiveProfile(n); }
+      catch (e) {
+        const cred = credentials.readCanonical();
+        if (cred) {
+          console.error(`[feishu-user-plugin] WARN: setActiveProfile("${n}") failed to persist to credentials.json: ${e.message}. In-memory currentProfile updated anyway, but other MCP processes won't see the switch.`);
+        }
+      }
+      // Re-baseline mtime so _syncActiveProfileFromDisk doesn't immediately
+      // trigger a redundant sync on the next tool call after we just wrote.
+      _credMtimeBaseline = _credMtime();
     },
     resolveDocId,
+    getWsServer: () => wsServer,
+    requestClaim: async ({ force = false } = {}) => {
+      const claim = events.owner.tryClaim(FEISHU_HOME, { info: { role: 'ws_owner' }, force });
+      if (claim.isOwner) {
+        ownerHandle = claim;
+        await _claimAndStart();
+        return { ok: true, became_owner: true };
+      }
+      return { ok: false, reason: 'lock_active_no_force', owner_pid: claim.ownerInfo?.pid };
+    },
+    requestReconfigure: async () => {
+      const before = wsServer?.getStatus() || {};
+      await _maybeReconfigure();
+      const after = wsServer?.getStatus() || {};
+      return {
+        prev_subscriptions: before.subscribed_events || [],
+        next_subscriptions: after.subscribed_events || [],
+        no_change: JSON.stringify(before.subscribed_events) === JSON.stringify(after.subscribed_events) && before.wsProfile === after.wsProfile,
+      };
+    },
   };
 }
 
@@ -163,13 +389,23 @@ const server = new Server(
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  // Cross-process active-profile sync (v1.3.9 A.2): if another MCP process
+  // wrote a new `active` field to credentials.json, pick it up before dispatch.
+  _syncActiveProfileFromDisk();
   const { name, arguments: args } = request.params;
   const handler = HANDLERS[name];
   if (!handler) {
     return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
   }
+  // Strip via_profile from args before passing to the handler — it's a
+  // routing-layer concern, not a tool argument. Keep a copy for routing.
+  const cleanArgs = (args && typeof args === 'object') ? { ...args } : {};
+  delete cleanArgs.via_profile;
+
   try {
-    return await handler(args || {}, buildCtx());
+    return await profileRouter.withProfileRouting(buildCtx(), name, args || {}, async () => {
+      return handler(cleanArgs, buildCtx());
+    });
   } catch (err) {
     return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
   }
@@ -191,6 +427,18 @@ process.on('uncaughtException', (err) => {
 process.on('unhandledRejection', (reason) => {
   console.error('[feishu-user-plugin] Unhandled rejection:', reason);
 });
+process.on('SIGTERM', () => {
+  _stopHeartbeat(); _stopNonOwnerPoll();
+  try { wsServer?.stop(); } catch {}
+  try { ownerHandle?.release(); } catch {}
+  process.exit(0);
+});
+process.on('SIGINT', () => {
+  _stopHeartbeat(); _stopNonOwnerPoll();
+  try { wsServer?.stop(); } catch {}
+  try { ownerHandle?.release(); } catch {}
+  process.exit(0);
+});
 
 // --- main ---
 
@@ -200,6 +448,18 @@ async function main() {
 
   // Startup diagnostics — use the resolved active-profile env so users on
   // credentials.json (where process.env may not have LARK_*) get accurate flags.
+  // Bootstrap-only validation: when credentials.json doesn't exist and
+  // FEISHU_PLUGIN_PROFILE is set, validate the name against known legacy profiles.
+  // If credentials.json exists, FEISHU_PLUGIN_PROFILE is ignored — the file's
+  // `active` field is the SSOT and cross-process sync keeps it up to date.
+  if (!credentials.readCanonical() && process.env.FEISHU_PLUGIN_PROFILE) {
+    const known = credentials.listProfileNames();
+    if (!known.includes(currentProfile)) {
+      console.error(`[feishu-user-plugin] FATAL: FEISHU_PLUGIN_PROFILE="${currentProfile}" not found. Known: ${known.join(', ')}.`);
+      console.error('[feishu-user-plugin] Fix: edit harness env block, or add the profile to ~/.feishu-user-plugin/credentials.json.');
+      process.exit(2);
+    }
+  }
   let activeEnv = {};
   try { activeEnv = profileEnv(currentProfile); } catch (_) { /* unknown profile is reported below */ }
   const hasCanonical = !!credentials.readCanonical();
@@ -212,6 +472,15 @@ async function main() {
   if (!hasCookie) console.error('[feishu-user-plugin] WARNING: LARK_COOKIE not set — user identity tools (send_to_user, etc.) will fail');
   if (!hasApp) console.error('[feishu-user-plugin] WARNING: LARK_APP_ID/SECRET not set — official API tools (read_messages, docs, etc.) will fail');
   if (!hasUAT) console.error('[feishu-user-plugin] WARNING: LARK_USER_ACCESS_TOKEN not set — P2P chat reading (read_p2p_messages) will fail');
+  // Warn when both credentials.json AND legacy env vars exist — they may
+  // diverge silently after a UAT refresh (we always write credentials.json).
+  if (hasCanonical && (process.env.LARK_COOKIE || process.env.LARK_APP_ID || process.env.LARK_USER_ACCESS_TOKEN)) {
+    console.error('[feishu-user-plugin] NOTE: credentials.json AND legacy LARK_* env vars are both set. Plugin reads credentials.json; the env vars are ignored. To clean up: remove the LARK_* keys from your harness config, leaving FEISHU_PLUGIN_PROFILE only.');
+  }
+  // Nudge legacy env-only users to migrate.
+  if (!hasCanonical && (hasCookie || hasApp || hasUAT)) {
+    console.error('[feishu-user-plugin] TIP: run `npx feishu-user-plugin migrate --confirm` to consolidate credentials into ~/.feishu-user-plugin/credentials.json (single source of truth, removes UAT-refresh drift across harnesses).');
+  }
 
   // Validate APP_ID/SECRET against Feishu before serving any tool calls.
   // Catches the "Claude filled in a wrong/stale APP_ID during install" failure
@@ -233,6 +502,19 @@ async function main() {
       console.error(`[feishu-user-plugin] WARNING: Could not verify APP_ID (${e.message}); network issue or cold start. Proceeding anyway.`);
     }
   }
+
+  // --- Real-time events (v1.3.9 — owner-arbitrated) ---
+  if (hasApp) {
+    _claimAndStart().catch((e) => {
+      console.error(`[feishu-user-plugin] owner claim failed: ${e.message}; will retry every 30s`);
+      if (!nonOwnerPollTimer) {
+        nonOwnerPollTimer = setInterval(_claimAndStart, events.owner.TAKEOVER_POLL_INTERVAL_MS);
+        nonOwnerPollTimer.unref?.();
+      }
+    });
+  } else {
+    console.error('[feishu-user-plugin] WS not started — APP_ID/SECRET missing. Realtime events (get_new_events) will return empty.');
+  }
 }
 
 module.exports = { main, TOOLS, HANDLERS };