feishu-user-plugin 1.3.11 → 1.3.13

package/src/logger.js

@@ -1,10 +1,16 @@
 // Global stdout guard. MCP stdio uses stdout for JSON-RPC; ANY accidental write
 // from this process or its dependencies corrupts the transport and disconnects
 // the client. Defense-in-depth: redirect every console.log / console.info to
-// stderr at module load. REQUIRE THIS BEFORE ANY OTHER MODULE so even early
-// log calls during dependency init are captured.
-console.log = (...args) => console.error(...args);
-console.info = (...args) => console.error(...args);
+// stderr.
+//
+// v1.3.12: the guard is now opt-in via installStdoutGuard() so the CLI tool
+// mode (\`npx feishu-user-plugin tool ...\`) can print structured JSON to the
+// real stdout. index.js (the MCP server entry) calls it on the first line;
+// cli.js doesn't, except when dispatching to MCP server mode.
+function installStdoutGuard() {
+  console.log = (...args) => console.error(...args);
+  console.info = (...args) => console.error(...args);
+}
 
 // Stderr-only logger for the Lark SDK (the SDK's defaultLogger.error() writes
 // to stdout via console.log, which would also corrupt MCP stdio). Shape and
@@ -17,4 +23,4 @@ const stderrLogger = {
   trace: () => {},
 };
 
-module.exports = { stderrLogger };
+module.exports = { stderrLogger, installStdoutGuard };

package/src/oauth.js

@@ -33,11 +33,18 @@ const TARGET_PROFILE = _parseTargetProfile();
 const _hasCanonical = !!credentialsModule.readCanonical();
 let creds;
 let profileLabel;
+// v1.3.12 (PR #45 P2): capture targetName at module init, NOT at OAuth
+// callback time. If we re-read getActiveProfileName() inside saveToken (as
+// the v1.3.6 code did), a concurrent `switch_profile` or Lark Desktop
+// account flip between "open browser for authorize" and "callback fires"
+// would write tokens to the WRONG profile silently. The whole oauth flow
+// is anchored to the profile name resolved here.
+let RESOLVED_PROFILE = null;
 if (_hasCanonical) {
-  const targetName = TARGET_PROFILE || credentialsModule.getActiveProfileName();
+  RESOLVED_PROFILE = TARGET_PROFILE || credentialsModule.getActiveProfileName();
   try {
-    creds = credentialsModule.getActiveProfileEnv(targetName);
-    profileLabel = `credentials.json::profiles[${targetName}]`;
+    creds = credentialsModule.getActiveProfileEnv(RESOLVED_PROFILE);
+    profileLabel = `credentials.json::profiles[${RESOLVED_PROFILE}]`;
   } catch (e) {
     console.error(`OAuth target profile error: ${e.message}`);
     console.error(`Available: ${credentialsModule.listProfileNames().join(', ')}`);
@@ -67,10 +74,25 @@ const REDIRECT_URI = `http://127.0.0.1:${PORT}/callback`;
 //   sheets:spreadsheet                     for sheet_image / sheet_file media uploads
 //   drive:file:upload                      narrower scope for drive/v1/files/upload_all (independent of drive:drive)
 // v1.3.7 additions:
-//   calendar:calendar.event:write          create/update/delete/respond calendar events
+//   calendar:calendar.event:{create,update,delete,reply}   calendar write — Feishu splits
+//                                          "write" into 4 verbs. Using the umbrella name
+//                                          `calendar:calendar.event:write` makes the
+//                                          OAuth authorize endpoint 422-reject the whole
+//                                          request. scripts/check-scopes.js bans it.
 //   task:task                              full Task v2 read+write
-//   okr:okr.content:write                  create/delete OKR progress records
-const SCOPES = 'offline_access auth:user.id:read im:message im:message:readonly im:chat im:chat:readonly contact:user.base:readonly contact:user.id:readonly docx:document drive:drive drive:file:upload bitable:app wiki:wiki:readonly wiki:wiki okr:okr:readonly okr:okr.period:readonly okr:okr.content:readonly okr:okr.content:write calendar:calendar:readonly calendar:calendar.event:read calendar:calendar.event:write docs:document.media:download docs:document.media:upload sheets:spreadsheet task:task';
+//   okr:okr.content:writeonly              create/delete OKR progress records.
+//                                          Note: Feishu uses `:writeonly` (one word),
+//                                          not `:write` (check-scopes.js banlist).
+// v1.3.12 additions:
+//   contact:contact.base:readonly          broader contact lookup (员工通讯录基本信息)
+//   im:resource                            user-side image/file download from messages
+//   search:message                         search_messages tool — search the user's IM
+//                                          history (POST /open-apis/search/v2/message,
+//                                          UAT-only; Feishu does NOT expose bot path).
+//
+// To add a scope: edit this line + add a row in docs/AUTH-SETUP.md scope table.
+// scripts/check-scopes.js enforces both in CI.
+const SCOPES = 'offline_access auth:user.id:read im:message im:message:readonly im:chat im:chat:readonly im:resource search:message contact:user.base:readonly contact:user.id:readonly contact:contact.base:readonly docx:document drive:drive drive:file:upload bitable:app wiki:wiki:readonly wiki:wiki okr:okr:readonly okr:okr.period:readonly okr:okr.content:readonly okr:okr.content:writeonly calendar:calendar:readonly calendar:calendar.event:read calendar:calendar.event:create calendar:calendar.event:update calendar:calendar.event:delete calendar:calendar.event:reply docs:document.media:download docs:document.media:upload sheets:spreadsheet task:task';
 
 if (!APP_ID || !APP_SECRET) {
   console.error('Missing LARK_APP_ID or LARK_APP_SECRET.');
@@ -89,7 +111,10 @@ async function getAppInfo() {
       body: JSON.stringify({ app_id: APP_ID, app_secret: APP_SECRET }),
     });
     const tokenData = await tokenRes.json();
-    if (!tokenData.app_access_token) return null;
+    if (!tokenData.app_access_token) {
+      console.error(`[oauth] app_access_token request returned no token: ${JSON.stringify(tokenData)}`);
+      return null;
+    }
 
     // Get app info — try the direct app query first, fall back to underauditlist
     let appName = null;
@@ -100,6 +125,15 @@ async function getAppInfo() {
     appName = directData?.data?.app?.app_name;
 
     if (!appName) {
+      // v1.3.12: 99991672 specifically means "no permission to read application
+      // info" — caused by missing tenant-side scope `application:application:self_manage`
+      // (no admin review required, see docs/AUTH-SETUP.md). Without it the
+      // sender displayLabel for bot messages falls back to "[Bot] (cli_xxx)".
+      if (directData?.code === 99991672) {
+        console.error(`[oauth] App name resolve failed (code=99991672): need application:application:self_manage scope (tenant-side, 免审). displayLabel will fall back to '[Bot] (cli_xxx)'`);
+      } else if (directData?.code && directData.code !== 0) {
+        console.error(`[oauth] App name resolve failed: code=${directData.code} msg=${directData.msg}`);
+      }
       const listRes = await fetch('https://open.feishu.cn/open-apis/application/v6/applications/underauditlist?lang=zh_cn&page_size=1', {
         headers: { 'Authorization': `Bearer ${tokenData.app_access_token}` },
       });
@@ -108,7 +142,8 @@ async function getAppInfo() {
     }
 
     return { appName, tenantKey: tokenData.tenant_key };
-  } catch {
+  } catch (e) {
+    console.error(`[oauth] App name lookup threw: ${e.message}`);
     return null;
   }
 }
@@ -128,10 +163,16 @@ async function exchangeCode(code) {
     body: JSON.stringify(body),
   });
   const raw = await tokenRes.text();
-  console.log('Token exchange raw response:', raw.slice(0, 500));
+  // v1.3.13 security followup: don't log the full raw body — it contains the
+  // bare access_token + refresh_token. Log only the http status and a hint of
+  // success/failure; the parsed token never leaves this function except via
+  // saveToken (which writes the file with 0600 perms).
+  console.log(`Token exchange HTTP ${tokenRes.status} (body ${raw.length} bytes)`);
   let tokenData;
   try { tokenData = JSON.parse(raw); } catch (e) {
-    throw new Error(`Response not JSON: ${raw.slice(0, 200)}`);
+    // Parse error path: redact body in the thrown message so an upstream
+    // log line doesn't accidentally surface tokens.
+    throw new Error(`Response not JSON (HTTP ${tokenRes.status}, ${raw.length} bytes): ${raw.slice(0, 100).replace(/[A-Za-z0-9._-]{40,}/g, '<redacted>')}`);
   }
   if (tokenData.error) {
     throw new Error(`${tokenData.error}: ${tokenData.error_description}`);
@@ -155,16 +196,26 @@ function saveToken(tokenData) {
 
   let ok = false;
   if (_hasCanonical) {
-    const targetName = TARGET_PROFILE || credentialsModule.getActiveProfileName();
-    ok = credentialsModule.persistProfileUpdate(targetName, updates);
+    // Use the profile name captured at module init, not whatever
+    // credentials.json::active is *now*. See PR #45 race condition fix.
+    ok = credentialsModule.persistProfileUpdate(RESOLVED_PROFILE, 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. Copy them manually:');
-    for (const [k, v] of Object.entries(updates)) console.error(`  ${k}=${v}`);
+    // v1.3.13 security followup: never dump full token bytes to stderr.
+    // Caller can find them by re-running OAuth or reading the credentials
+    // file. Show only the field shape so user knows what fields exist.
+    console.error('WARNING: Tokens could not be saved automatically. Re-run `npx feishu-user-plugin oauth` after fixing the config path, or check that `~/.feishu-user-plugin/credentials.json` is writable.');
+    console.error('Fields that would have been written (values redacted):');
+    for (const [k, v] of Object.entries(updates)) {
+      const preview = typeof v === 'string' && v.length > 0
+        ? `${v.slice(0, 6)}…(${v.length} chars)`
+        : '<empty>';
+      console.error(`  ${k}=${preview}`);
+    }
   }
 }
 

package/src/server.js

@@ -29,6 +29,8 @@ const { resolveToken } = require('./resolver');
 const { listPrompts, getPrompt } = require('./prompts');
 const credentials = require('./auth/credentials');
 const profileRouter = require('./auth/profile-router');
+const { createCredentialsMonitor } = require('./auth/credentials-monitor');
+const identityState = require('./auth/identity-state');
 
 // --- Tool modules ---
 // Adding a new domain: create src/tools/<x>.js exporting { schemas, handlers }
@@ -156,14 +158,22 @@ function getOfficialClient() {
 }
 
 // Mirror of LarkOfficialClient.loadUAT() but sourced from a specific env block
-// instead of process.env, so credentials.json profiles work uniformly.
+// instead of process.env, so credentials.json profiles work uniformly. Also
+// the hot-reload entry point used by credMonitor.onUatChange: when `env` has
+// no UAT (user nuked the token), clear the in-memory copy instead of
+// silently leaving the stale token in place.
 function loadUATFromEnv(client, env) {
-  const token = env.LARK_USER_ACCESS_TOKEN;
-  const refresh = env.LARK_USER_REFRESH_TOKEN;
-  const expires = parseInt(env.LARK_UAT_EXPIRES || '0');
-  if (!token) return;
+  const token = env?.LARK_USER_ACCESS_TOKEN || null;
+  const refresh = env?.LARK_USER_REFRESH_TOKEN || null;
+  const expires = parseInt(env?.LARK_UAT_EXPIRES || '0') || 0;
+  if (!token) {
+    client._uat = null;
+    client._uatRefresh = null;
+    client._uatExpires = 0;
+    return;
+  }
   client._uat = token;
-  client._uatRefresh = refresh || null;
+  client._uatRefresh = refresh;
   client._uatExpires = expires || client._decodeTokenExpiry(token);
 }
 
@@ -284,36 +294,58 @@ function _runLarkDesktopReactor() {
     .reduce((acc, h) => { acc[h.hash] = h.mtimeMs; return acc; }, {});
 }
 
-// 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).
+// Cross-process credentials sync (v1.3.12 — CredentialsMonitor).
+// One poller, multiple hooks. Each tool call entry runs `credMonitor.sync()`
+// which:
+//   - active profile changed → flips in-memory currentProfile + clears caches
+//   - UAT field changed     → reloads officialClient._uat without restart
+//   - cookie field changed  → (no-op for now — userClient already re-inits
+//                              on next getUserClient call when nulled)
+//   - any change            → invalidates the identity-state cache so the
+//                              next call re-probes
+//
+// This replaces v1.3.9's _syncActiveProfileFromDisk (active-only) + the
+// "restart Claude Code to pick up new UAT" hand-off pattern.
+const credMonitor = createCredentialsMonitor();
+
+credMonitor.onProfileSwitch(({ to }) => {
+  if (!to || to === currentProfile) return;
   try {
-    credentials.getActiveProfileEnv(newActive); // validate profile exists
-    currentProfile = newActive;
+    credentials.getActiveProfileEnv(to); // validate profile exists
+    console.error(`[feishu-user-plugin] active profile changed on disk: ${currentProfile} → ${to}`);
+    currentProfile = to;
     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}"`);
+    console.error(`[feishu-user-plugin] sync to "${to}" failed: ${e.message}; staying on "${currentProfile}"`);
   }
-}
+});
+
+credMonitor.onUatChange((env) => {
+  // Hot-reload UAT into the running officialClient. No restart needed.
+  // Routing through loadUATFromEnv keeps the field-write logic in one
+  // place — same helper used at getOfficialClient() startup.
+  if (!officialClient) return; // next getOfficialClient() reads env directly
+  loadUATFromEnv(officialClient, env);
+  identityState.invalidateIdentity(officialClient);
+  console.error('[feishu-user-plugin] UAT reloaded from credentials.json (no restart needed)');
+});
+
+credMonitor.onCookieChange(() => {
+  // Cookie rotation: null the LarkUserClient singleton so the next
+  // getUserClient() call rebuilds it with the fresh cookie from env.
+  // Without this, cookie-based tools (send_to_user / search_contacts /
+  // get_login_status / send_as_user / batch_send) keep using the stale
+  // cookie until restart. PR #103 Codex P2 followup.
+  if (!userClient) return;
+  userClient = null;
+  console.error('[feishu-user-plugin] cookie rotation detected — userClient nulled, rebuilds on next tool call');
+});
+
+credMonitor.onCacheInvalidate(() => {
+  if (officialClient) identityState.invalidateIdentity(officialClient);
+});
 
 async function _maybeReconfigure() {
   if (!ownerHandle || !wsServer) return;
@@ -393,9 +425,11 @@ function buildCtx() {
           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();
+      // Run a sync so credMonitor adopts the just-written file as its
+      // baseline. The onProfileSwitch hook will see `to === currentProfile`
+      // and short-circuit; UAT/cookie hooks fire only if those fields
+      // actually differ from the prior active profile, which is harmless.
+      credMonitor.sync();
     },
     resolveDocId,
     getWsServer: () => wsServer,
@@ -431,9 +465,9 @@ 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();
+  // Credentials hot-reload (v1.3.12): poll credentials.json for changes and
+  // fire registered hooks (profile / UAT / cookie / invalidate).
+  credMonitor.sync();
   const { name, arguments: args } = request.params;
   const handler = HANDLERS[name];
   if (!handler) {
@@ -545,6 +579,11 @@ async function main() {
     }
   }
 
+  // Baseline credMonitor at startup so any credential changes between server
+  // boot and the first tool call fire hooks instead of being silently absorbed
+  // by the first sync()'s baselining branch. PR #103 Codex P2 followup.
+  credMonitor.sync();
+
   // --- Real-time events (v1.3.9 — owner-arbitrated) ---
   if (hasApp) {
     _claimAndStart().catch((e) => {
@@ -559,7 +598,7 @@ async function main() {
   }
 }
 
-module.exports = { main, TOOLS, HANDLERS };
+module.exports = { main, TOOLS, HANDLERS, buildCtx };
 
 if (require.main === module) {
   main().catch((err) => { console.error('Fatal:', err); process.exit(1); });

package/src/test-all.js

@@ -324,4 +324,45 @@ main().catch(console.error).finally(() => {
   require('./test-events-log').run();
   require('./test-events-cursor').run();
   require('./test-events-owner').run();
+  require('./test-error-codes').run();
+  require('./test-identity-state').run().catch(e => {
+    console.error('identity-state: FAIL', e);
+    process.exitCode = 1;
+  });
+  require('./test-with-uat-retry').run().catch(e => {
+    console.error('with-uat-retry: FAIL', e);
+    process.exitCode = 1;
+  });
+  require('./test-populate-sender-names').run().catch(e => {
+    console.error('populate-sender-names: FAIL', e);
+    process.exitCode = 1;
+  });
+  require('./test-credentials-monitor').run().catch(e => {
+    console.error('credentials-monitor: FAIL', e);
+    process.exitCode = 1;
+  });
+  require('./test-lru-cache').run().catch(e => {
+    console.error('lru-cache: FAIL', e);
+    process.exitCode = 1;
+  });
+  require('./test-lockfile-pid').run();
+  require('./test-negative-cache').run().catch(e => {
+    console.error('negative-cache: FAIL', e);
+    process.exitCode = 1;
+  });
+  require('./test-send-shape').run().catch(e => {
+    console.error('send-shape: FAIL', e);
+    process.exitCode = 1;
+  });
+  require('./test-via-user').run().catch(e => {
+    console.error('via-user: FAIL', e);
+    process.exitCode = 1;
+  });
+  require('./test-search-messages').run().catch(e => {
+    console.error('search-messages: FAIL', e);
+    process.exitCode = 1;
+  });
+  require('./test-cli-tool').run();
+  require('./test-lark-desktop').run();
+  require('./test-display-label');  // standalone — runs on require, exits non-zero on fail
 });

package/src/test-cli-tool.js

@@ -0,0 +1,87 @@
+// src/test-cli-tool.js — verify the v1.3.12 \`tool\` CLI subcommand.
+//
+// Spawns \`node src/cli.js tool <args>\` as child_process and asserts:
+//   - tool list prints 85 names, exit 0
+//   - tool help <known-name> prints the schema, exit 0
+//   - tool help <missing-name> prints error to stderr, exit 2
+//   - tool <unknown-name> '{}' fails with exit 2
+//   - tool help (no args) prints help to stderr, exit 2
+//
+// We don't actually invoke a tool here because handlers need credentials
+// — that's covered by the integration scripts. This test just covers the
+// CLI argv-parsing + dispatcher correctness.
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const assert = require('node:assert/strict');
+
+const CLI = path.join(__dirname, 'cli.js');
+
+function runCli(args) {
+  return spawnSync('node', [CLI, ...args], { encoding: 'utf8' });
+}
+
+function run() {
+  // --- 1. tool list — exit 0, 85 lines, all known tool names ---
+  {
+    const r = runCli(['tool', 'list']);
+    assert.equal(r.status, 0, 'tool list should exit 0');
+    const lines = r.stdout.trim().split('\n');
+    assert.equal(lines.length, 85, `tool list should print 85 names, got ${lines.length}`);
+    assert.ok(lines.includes('get_login_status'));
+    assert.ok(lines.includes('search_messages'));
+    assert.ok(lines.includes('send_as_user'));
+  }
+
+  // --- 2. tool help <known> — exit 0, contains schema ---
+  {
+    const r = runCli(['tool', 'help', 'get_login_status']);
+    assert.equal(r.status, 0, 'tool help <known> should exit 0');
+    assert.ok(r.stdout.includes('# get_login_status'));
+    assert.ok(r.stdout.includes('## inputSchema'));
+    assert.ok(r.stdout.includes('"type": "object"'));
+  }
+
+  // --- 3. tool help <unknown> — exit 2, stderr complains ---
+  {
+    const r = runCli(['tool', 'help', 'nonexistent_tool_xyz']);
+    assert.equal(r.status, 2, 'tool help <unknown> should exit 2');
+    assert.ok(r.stderr.includes('Unknown tool'));
+  }
+
+  // --- 4. tool <unknown-name> '{}' — exit 2 ---
+  {
+    const r = runCli(['tool', 'nonexistent_xyz', '{}']);
+    assert.equal(r.status, 2, 'tool <unknown> should exit 2');
+    assert.ok(r.stderr.includes('Unknown tool'));
+  }
+
+  // --- 5. tool <name> with malformed JSON args — exit 2 ---
+  {
+    const r = runCli(['tool', 'get_login_status', 'not a json']);
+    assert.equal(r.status, 2);
+    assert.ok(r.stderr.includes('failed to parse JSON'));
+  }
+
+  // --- 6. tool (no subcommand) — exit 2 with usage on stdout ---
+  {
+    const r = runCli(['tool']);
+    assert.equal(r.status, 2);
+    assert.ok(r.stdout.includes('npx feishu-user-plugin tool'));
+  }
+
+  // --- 7. tool --help — exit 0 ---
+  {
+    const r = runCli(['tool', '--help']);
+    assert.equal(r.status, 0);
+    assert.ok(r.stdout.includes('tool list'));
+    assert.ok(r.stdout.includes('tool help'));
+  }
+
+  console.log('cli-tool.js: PASS');
+}
+
+if (require.main === module) run();
+module.exports = { run };

package/src/test-credentials-monitor.js

@@ -0,0 +1,124 @@
+// src/test-credentials-monitor.js — unit test for src/auth/credentials-monitor.js.
+//
+// Pre-v1.3.12 hot-reload was partial: server.js stat-ed credentials.json mtime
+// and dispatched setActiveProfile() on change, but the UAT in-memory token,
+// _userNameCache, and lockfile heartbeat never observed the change. Users had
+// to restart Claude Code after `npx oauth` for the new UAT to take effect.
+//
+// CredentialsMonitor unifies the mtime + content-hash diff into a single
+// poll triggered per tool call. Owners register hooks for the parts they
+// care about: onUatChange / onCookieChange / onProfileSwitch / onCacheInvalidate.
+//
+// We test against a temporary credentials.json in a tmpdir so the test is
+// isolated from any real ~/.feishu-user-plugin state.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const assert = require('node:assert/strict');
+const { createCredentialsMonitor } = require('./auth/credentials-monitor');
+
+function writeCreds(dir, obj) {
+  const p = path.join(dir, 'credentials.json');
+  fs.writeFileSync(p, JSON.stringify(obj, null, 2) + '\n', { mode: 0o600 });
+  return p;
+}
+
+async function run() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fish-monitor-'));
+  const credPath = path.join(dir, 'credentials.json');
+
+  const baseCreds = {
+    version: 1,
+    active: 'default',
+    profiles: {
+      default: {
+        LARK_APP_ID: 'cli_a',
+        LARK_USER_ACCESS_TOKEN: 'uat_v1',
+        LARK_USER_REFRESH_TOKEN: 'ref_v1',
+        LARK_COOKIE: 'cookie_v1',
+      },
+    },
+  };
+  writeCreds(dir, baseCreds);
+
+  // Inject path so monitor doesn't read real ~/.feishu-user-plugin
+  const monitor = createCredentialsMonitor({ path: credPath });
+
+  // --- 1. First sync establishes baseline; no hooks fire ---
+  let uatFired = 0, cookieFired = 0, profileFired = 0, cacheFired = 0;
+  monitor.onUatChange(() => uatFired++);
+  monitor.onCookieChange(() => cookieFired++);
+  monitor.onProfileSwitch(() => profileFired++);
+  monitor.onCacheInvalidate(() => cacheFired++);
+
+  monitor.sync();
+  assert.equal(uatFired, 0, 'baseline sync should not fire hooks');
+  assert.equal(cookieFired, 0);
+  assert.equal(profileFired, 0);
+  assert.equal(cacheFired, 0);
+
+  // --- 2. Change UAT field → onUatChange fires, others don't ---
+  // We must advance the mtime AFTER content change; on fast filesystems writing
+  // the same path repeatedly within the same ms gives identical mtime. Set
+  // explicit mtime so behaviour doesn't depend on FS clock granularity.
+  const after1 = { ...baseCreds, profiles: { default: { ...baseCreds.profiles.default, LARK_USER_ACCESS_TOKEN: 'uat_v2', LARK_USER_REFRESH_TOKEN: 'ref_v2' } } };
+  writeCreds(dir, after1);
+  fs.utimesSync(credPath, new Date(Date.now() + 1000), new Date(Date.now() + 1000));
+  monitor.sync();
+  assert.equal(uatFired, 1, 'onUatChange should fire on UAT diff');
+  assert.equal(cookieFired, 0, 'unchanged cookie → no cookie hook');
+  assert.equal(profileFired, 0, 'unchanged active → no profile hook');
+  assert.equal(cacheFired, 1, 'any change should fire onCacheInvalidate once');
+
+  // --- 3. Same content, just touch mtime → no hook fires (content hash guards) ---
+  fs.utimesSync(credPath, new Date(Date.now() + 2000), new Date(Date.now() + 2000));
+  monitor.sync();
+  assert.equal(uatFired, 1, 'touch (no content change) should not fire UAT');
+  assert.equal(cacheFired, 1);
+
+  // --- 4. Change cookie → onCookieChange fires ---
+  const after2 = { ...after1, profiles: { default: { ...after1.profiles.default, LARK_COOKIE: 'cookie_v2' } } };
+  writeCreds(dir, after2);
+  fs.utimesSync(credPath, new Date(Date.now() + 3000), new Date(Date.now() + 3000));
+  monitor.sync();
+  assert.equal(cookieFired, 1);
+  assert.equal(profileFired, 0);
+
+  // --- 5. Change active profile → onProfileSwitch fires (legacy parity) ---
+  const after3 = { ...after2, active: 'work', profiles: { default: after2.profiles.default, work: { LARK_APP_ID: 'cli_b' } } };
+  writeCreds(dir, after3);
+  fs.utimesSync(credPath, new Date(Date.now() + 4000), new Date(Date.now() + 4000));
+  monitor.sync();
+  assert.equal(profileFired, 1, 'active flip → onProfileSwitch fires');
+
+  // --- 6. Hook receives the new credentials snapshot as argument ---
+  let receivedToken = null;
+  monitor.onUatChange((snap) => { receivedToken = snap?.LARK_USER_ACCESS_TOKEN; });
+  const after4 = { ...after3, profiles: { ...after3.profiles, work: { LARK_APP_ID: 'cli_b', LARK_USER_ACCESS_TOKEN: 'uat_work_v1', LARK_USER_REFRESH_TOKEN: 'ref_work_v1' } } };
+  writeCreds(dir, after4);
+  fs.utimesSync(credPath, new Date(Date.now() + 5000), new Date(Date.now() + 5000));
+  monitor.sync();
+  assert.equal(receivedToken, 'uat_work_v1', 'UAT hook should receive the active profile env block');
+
+  // --- 7. Monitor handles missing file gracefully (no throw) ---
+  fs.unlinkSync(credPath);
+  monitor.sync(); // should not throw
+
+  // --- 8. File reappears later → next sync detects + fires ---
+  writeCreds(dir, baseCreds);
+  fs.utimesSync(credPath, new Date(Date.now() + 6000), new Date(Date.now() + 6000));
+  monitor.sync();
+  // baseCreds.active='default' diff from previous 'work' → profile change
+  // baseCreds.UAT='uat_v1' diff from previous 'uat_work_v1' → uat change
+  assert.ok(profileFired >= 2);
+  assert.ok(uatFired >= 2);
+
+  fs.rmSync(dir, { recursive: true, force: true });
+  console.log('credentials-monitor.js: PASS');
+}
+
+if (require.main === module) run().catch(e => { console.error(e); process.exit(1); });
+module.exports = { run };