feishu-user-plugin 1.3.10 → 1.3.12

package/src/events/lockfile.js

@@ -24,10 +24,36 @@ function _writeLockBody(fd, info) {
   fs.writeSync(fd, body);
 }
 
+// Probe whether `pid` is a live process. Returns true when alive (or when we
+// can't tell for certain; we prefer "alive" on EPERM because falsely
+// declaring an EPERM'd process dead would race-steal a lock from another
+// user's MCP server). Returns false only when ESRCH says "no such process".
+function _isProcessAlive(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) return true; // unknown → safe default
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    if (e.code === 'ESRCH') return false;
+    // EPERM — process exists but we can't signal it. Treat as alive.
+    return true;
+  }
+}
+
+function _readPidFromLock(lockPath) {
+  try {
+    const body = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+    if (body && typeof body.pid === 'number' && body.pid > 0) return body.pid;
+  } catch (_) { /* malformed or unreadable — caller falls back to mtime */ }
+  return null;
+}
+
 // Long-lived (owner) acquisition.
 //
 // Returns { release(), heartbeat() } on success.
-// Returns null if lock active (mtime within staleMs).
+// Returns null if lock active (mtime within staleMs AND pid still alive).
+// v1.3.12: pid liveness check shortcircuits the 60s stale window when the
+// holder process is definitively gone (SIGKILL'd, crashed, host reboot).
 function acquireLongLived(lockPath, { info = {}, staleMs = 60_000 } = {}) {
   _ensureDir(lockPath);
 
@@ -38,8 +64,18 @@ function acquireLongLived(lockPath, { info = {}, staleMs = 60_000 } = {}) {
   }
   if (stat) {
     const ageMs = Date.now() - stat.mtimeMs;
-    if (ageMs < staleMs) return null;
-    // Stale — try to steal. Rename out of the way to make room for EXCL create.
+    const fresh = ageMs < staleMs;
+    let canSteal = !fresh;
+    if (fresh) {
+      // mtime suggests alive — verify by pid liveness. If the body has a pid
+      // and that pid is gone, the holder crashed and we can steal now.
+      const pid = _readPidFromLock(lockPath);
+      if (pid !== null && !_isProcessAlive(pid)) {
+        canSteal = true;
+      }
+    }
+    if (!canSteal) return null;
+    // Stealable — rename out of the way to make room for EXCL create.
     const stolenPath = lockPath + '.stale-' + process.pid + '-' + Date.now();
     try { fs.renameSync(lockPath, stolenPath); } catch (e) {
       // Race: someone else got there first; try again from scratch.
@@ -123,4 +159,4 @@ function withMutex(lockPath, fn, { staleMs = 30_000, retries = 30, retryDelayMs
   }
 }
 
-module.exports = { acquireLongLived, withMutex };
+module.exports = { acquireLongLived, withMutex, _isProcessAlive };

package/src/events/owner.js

@@ -7,7 +7,7 @@
 
 const path = require('path');
 const fs = require('fs');
-const { acquireLongLived } = require('./lockfile');
+const { acquireLongLived, _isProcessAlive } = require('./lockfile');
 
 const OWNER_LOCK_FILENAME = 'ws-owner.lock';
 const HEARTBEAT_INTERVAL_MS = 15_000;
@@ -43,6 +43,12 @@ function tryClaim(dir, { info = {}, force = false } = {}) {
 }
 
 // Read current owner info without modifying anything.
+//
+// v1.3.12: `alive` is now the conjunction of mtime-fresh AND pid-alive. The
+// non-owner poll in server.js calls readOwnerInfo every 30s; under the old
+// definition a SIGKILL'd owner kept the lock looking alive until the 60s
+// stale window elapsed. With the pid check, takeover happens on the next
+// poll after the crash regardless of mtime.
 function readOwnerInfo(dir) {
   const lockPath = _ownerLockPath(dir);
   let body = null;
@@ -53,13 +59,16 @@ function readOwnerInfo(dir) {
   } catch (_) {}
   if (!body) return { exists: false };
   const ageSec = mtimeMs ? Math.floor((Date.now() - mtimeMs) / 1000) : null;
+  const mtimeFresh = ageSec !== null && ageSec * 1000 < STALE_MS;
+  const pidAlive = typeof body.pid === 'number' ? _isProcessAlive(body.pid) : true;
   return {
     exists: true,
     pid: body.pid,
     start_time: body.start_time,
     mtimeMs,
     last_heartbeat_age_seconds: ageSec,
-    alive: ageSec !== null && ageSec * 1000 < STALE_MS,
+    pid_alive: pidAlive,
+    alive: mtimeFresh && pidAlive,
   };
 }
 

package/src/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-require('./logger'); // installs global stdout guard — MUST be first
+require('./logger').installStdoutGuard(); // redirect any stray console.log → stderr — MUST be first (MCP stdio uses stdout)
 require('./server').main().catch((err) => {
   console.error('Fatal:', err);
   process.exit(1);

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;
   }
 }
@@ -155,8 +190,9 @@ 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);

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 }
@@ -80,6 +82,11 @@ let ownerHeartbeatTimer = null;
 let nonOwnerPollTimer = null;
 let _ownerStartCallbacks = [];
 
+// Lark Desktop reactor state (v1.3.11 §A) — owned by the heartbeat callback.
+let _lastHashMtimes = {};
+let _lastSwitchAt = 0;
+const _seenUnboundHashes = new Set();
+
 function _onBecomeOwner(cb) { _ownerStartCallbacks.push(cb); }
 
 function _stopHeartbeat() {
@@ -151,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);
 }
 
@@ -203,6 +218,9 @@ async function _claimAndStart() {
 
   // Heartbeat + check active changes every 15s.
   let lastCredMtime = _credMtime();
+  // Bootstrap baseline so the very first heartbeat doesn't trigger a switch.
+  _lastHashMtimes = require('./auth/lark-desktop').listAccountHashes()
+    .reduce((acc, h) => { acc[h.hash] = h.mtimeMs; return acc; }, {});
   ownerHeartbeatTimer = setInterval(() => {
     if (ownerHandle) ownerHandle.heartbeat();
     const m = _credMtime();
@@ -210,6 +228,12 @@ async function _claimAndStart() {
       lastCredMtime = m;
       _maybeReconfigure().catch((e) => console.error(`[feishu-user-plugin] reconfigure failed: ${e.message}`));
     }
+    // Lark Desktop reactor (v1.3.11 §A)
+    try {
+      _runLarkDesktopReactor();
+    } catch (e) {
+      console.error(`[feishu-user-plugin] Lark reactor error: ${e.message}`);
+    }
     // Defer-rotate check
     try {
       const snap = events.cursor.readSnapshot(FEISHU_HOME);
@@ -242,36 +266,75 @@ function _credMtime() {
   } 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).
+// Lark Desktop reactor (v1.3.11 §A).
+// Called from the owner heartbeat. When the most-recently-active hash differs
+// from the active profile's bound hash AND its mtime advanced since the last
+// snapshot, flip credentials.json::active to the matching profile (the existing
+// _credMtime delta on the next tick triggers _maybeReconfigure which restarts
+// the WS client with the new profile's events list).
+function _runLarkDesktopReactor() {
+  const ld = require('./auth/lark-desktop');
+  const out = ld.detectSwitch({
+    prevSnapshot: _lastHashMtimes,
+    lastSwitchAt: _lastSwitchAt,
+    seenUnboundHashes: _seenUnboundHashes,
+  });
+  if (out.switchTo) {
+    _lastSwitchAt = Date.now();
+    console.error(
+      `[feishu-user-plugin] Lark Desktop account changed; switching profile to ` +
+      `"${out.switchTo.profile}" (hash ${out.switchTo.hash})`
+    );
+    try { credentials.setActiveProfile(out.switchTo.profile); }
+    catch (e) { console.error(`[feishu-user-plugin] setActiveProfile failed: ${e.message}`); }
+  }
+  // Refresh snapshot regardless of switch outcome — keeps debounce + advance
+  // detection consistent on subsequent ticks.
+  _lastHashMtimes = ld.listAccountHashes()
+    .reduce((acc, h) => { acc[h.hash] = h.mtimeMs; return acc; }, {});
+}
+
+// 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.onCacheInvalidate(() => {
+  if (officialClient) identityState.invalidateIdentity(officialClient);
+});
 
 async function _maybeReconfigure() {
   if (!ownerHandle || !wsServer) return;
@@ -351,9 +414,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,
@@ -389,9 +454,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) {
@@ -517,7 +582,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/setup.js

@@ -28,6 +28,8 @@ function parseArgs() {
     else if (argv[i] === '--force') args.force = true;
     else if (argv[i] === '--profile' && argv[i + 1]) args.profile = argv[++i];
     else if (argv[i] === '--activate') args.activate = true;
+    else if (argv[i] === '--bind-hash' && argv[i + 1]) args.bindHash = argv[++i];
+    else if (argv[i] === '--no-bind-hash') args.noBindHash = true;
   }
   return args;
 }
@@ -238,6 +240,48 @@ async function main() {
   }
   // mode === 'preserve': credentials.json is unchanged; we only update the harness pointer.
 
+  // --- Lark Desktop hash auto-bind (v1.3.11 §A) ---
+  // Triggers on fresh / update (i.e. whenever credentials.json was just modified).
+  // Skipped via --no-bind-hash. Explicit --bind-hash overrides auto-detect.
+  if ((mode === 'fresh' || mode === 'update') && !cliArgs.noBindHash) {
+    try {
+      const larkDesktop = require('./auth/lark-desktop');
+      const hashes = larkDesktop.listAccountHashes();
+      if (hashes.length > 0) {
+        let chosenHash = cliArgs.bindHash;
+        if (!chosenHash) {
+          if (hashes.length === 1) {
+            chosenHash = hashes[0].hash;
+            console.log(`\n[Lark Desktop] Detected single account hash: ${chosenHash}`);
+          } else if (nonInteractive) {
+            chosenHash = hashes[0].hash;
+            console.log(`\n[Lark Desktop] Detected ${hashes.length} accounts; auto-binding "${targetProfile}" to most-recent: ${chosenHash}`);
+            console.log(`  Other hashes (run setup --profile <name> --bind-hash <hash> to bind):`);
+            hashes.slice(1).forEach((h) => {
+              const ts = new Date(h.mtimeMs).toISOString();
+              console.log(`    - ${h.hash}  (last active ${ts})`);
+            });
+          } else {
+            console.log(`\n[Lark Desktop] Multiple accounts detected:`);
+            hashes.forEach((h, i) => {
+              const ts = new Date(h.mtimeMs).toISOString();
+              console.log(`  ${i + 1}. ${h.hash}  (last active ${ts})`);
+            });
+            const pick = (await ask(`Bind profile "${targetProfile}" to which? [1]: `)).trim() || '1';
+            const idx = parseInt(pick, 10) - 1;
+            chosenHash = (idx >= 0 && idx < hashes.length) ? hashes[idx].hash : hashes[0].hash;
+          }
+        }
+        credentials.setProfileLarkHash(targetProfile, chosenHash);
+        console.log(`Bound profile "${targetProfile}" to Lark account hash ${chosenHash}`);
+        console.log(`  → MCP will auto-switch to this profile when Lark Desktop activates this account.`);
+      }
+      // hashes.length === 0 → silent (Lark not installed, or non-darwin) — don't disrupt setup
+    } catch (e) {
+      console.error(`[Lark Desktop] auto-bind skipped: ${e.message}`);
+    }
+  }
+
   // --- Write harness config ---
   // Always write pointer-only env to harness configs (v1.3.9 SSOT).
   // The harness env block only needs FEISHU_PLUGIN_PROFILE; all real creds

package/src/test-all.js

@@ -324,4 +324,44 @@ 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-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 };