feishu-user-plugin 1.3.11 → 1.3.13

package/src/test-display-label.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// src/test-display-label.js — unit test for LarkOfficialClient._computeDisplayLabel
+//
+// _computeDisplayLabel maps a formatted message (with senderId/senderType/senderName/
+// isRecalled fields) to a human-friendly string for LLM consumption. This covers the
+// 6 sender shapes Feishu actually produces:
+//
+//   1. user with resolved name           → name
+//   2. user with senderName=null         → "(open_id)" fallback
+//   3. app (bot) with name in cache      → "[Bot] AppName"
+//   4. app (bot) without name            → "[Bot] (cli_xxx)"
+//   5. anonymous sender                  → "[匿名]"
+//   6. system message (no sender)        → "[系统]"
+//   7. recalled-message prefix           → "[已撤回] " + base label
+//
+// Without the implementation this script fails (which is what we want pre-fix).
+
+const { LarkOfficialClient } = require('./clients/official/base');
+
+const client = new LarkOfficialClient('cli_dummy', 'dummy_secret');
+client._appNameCache.set('cli_named_bot', 'Claude聊天助手');
+
+const tests = [
+  {
+    name: 'user with resolved name',
+    input: { senderType: 'user', senderId: 'ou_x', senderName: '周宇' },
+    expected: '周宇',
+  },
+  {
+    name: 'user with null senderName',
+    input: { senderType: 'user', senderId: 'ou_abc123', senderName: null },
+    expected: '(ou_abc123)',
+  },
+  {
+    name: 'app with name in cache',
+    input: { senderType: 'app', senderId: 'cli_named_bot' },
+    expected: '[Bot] Claude聊天助手',
+  },
+  {
+    name: 'app without name',
+    input: { senderType: 'app', senderId: 'cli_unknown' },
+    expected: '[Bot] (cli_unknown)',
+  },
+  {
+    name: 'anonymous',
+    input: { senderType: 'anonymous', senderId: 'ou_x' },
+    expected: '[匿名]',
+  },
+  {
+    name: 'system (no senderId)',
+    input: { senderId: undefined },
+    expected: '[系统]',
+  },
+  {
+    name: 'recalled user message',
+    input: { senderType: 'user', senderId: 'ou_x', senderName: '怪兽', isRecalled: true },
+    expected: '[已撤回] 怪兽',
+  },
+  {
+    name: 'recalled with null senderName',
+    input: { senderType: 'user', senderId: 'ou_y', senderName: null, isRecalled: true },
+    expected: '[已撤回] (ou_y)',
+  },
+];
+
+let failures = 0;
+for (const t of tests) {
+  let actual;
+  try {
+    actual = client._computeDisplayLabel(t.input);
+  } catch (e) {
+    console.error(`FAIL ${t.name}: threw ${e.message}`);
+    failures++;
+    continue;
+  }
+  if (actual !== t.expected) {
+    console.error(`FAIL ${t.name}: expected ${JSON.stringify(t.expected)}, got ${JSON.stringify(actual)}`);
+    failures++;
+  } else {
+    console.log(`OK   ${t.name}`);
+  }
+}
+
+if (failures) {
+  console.error(`\n${failures} test(s) failed`);
+  process.exit(1);
+}
+console.log(`\nAll ${tests.length} display-label tests passed`);

package/src/test-error-codes.js

@@ -0,0 +1,85 @@
+// src/test-error-codes.js — unit test for src/error-codes.js classifyError.
+//
+// Covers the v1.3.12 widening:
+//   - 20064 (invalid_grant — UAT revoked, permanent)
+//   - 91403 (cross-tenant bot — bot can never access, route to UAT)
+//   - 1254xxx upload errors (transient — retry once)
+//   - res.json() parse failure messages → 'retry' (transient)
+//
+// Each case maps an error code (or Error object) to { action, reason } the
+// classifier should output. Run via `node src/test-error-codes.js` or as part
+// of `npm test` (imported from src/test-all.js).
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const { classifyError, FAILURE_MAP, TRANSIENT_PATTERNS } = require('./error-codes');
+
+function run() {
+  // --- Existing classifications (regression guard) ---
+  assert.deepEqual(
+    classifyError(240001),
+    { action: 'uat', reason: 'bot_external_tenant', code: 240001 },
+    '240001 → bot_external_tenant',
+  );
+  assert.deepEqual(
+    classifyError(70009),
+    { action: 'uat', reason: 'bot_no_permission', code: 70009 },
+  );
+  assert.deepEqual(
+    classifyError(42101),
+    { action: 'retry', reason: 'bot_rate_limited', code: 42101 },
+  );
+
+  // --- New v1.3.12 entries ---
+  const m20064 = classifyError(20064);
+  assert.equal(m20064.action, 'uat', '20064 should escalate to UAT path (revoked permanent)');
+  assert.equal(m20064.reason, 'uat_revoked', '20064 reason should be uat_revoked');
+
+  const m91403 = classifyError(91403);
+  assert.equal(m91403.action, 'uat', '91403 cross-tenant bot');
+  assert.equal(m91403.reason, 'bot_cross_tenant');
+
+  // 1254xxx — a sample of upload failures observed in production
+  for (const code of [1254000, 1254001, 1254301, 1254400]) {
+    const c = classifyError(code);
+    assert.equal(c.action, 'retry', `${code} should be transient (retry)`);
+    assert.equal(c.reason, 'upload_transient', `${code} reason`);
+  }
+
+  // --- res.json() parse failures should retry once ---
+  // Real-world: feishu's gateway occasionally returns truncated bodies that
+  // make response.json() throw SyntaxError; one retry usually clears it.
+  const parseErr = new Error('Unexpected end of JSON input');
+  parseErr.name = 'SyntaxError';
+  const parseClass = classifyError(parseErr);
+  assert.equal(parseClass.action, 'retry', 'JSON parse error → retry');
+  assert.equal(parseClass.reason, 'response_parse_error');
+
+  // --- Existing transient patterns still work ---
+  const networkErr = new Error('fetch timeout after 10000ms');
+  assert.equal(classifyError(networkErr).action, 'retry');
+
+  const httpFive = new Error('readMessages failed (HTTP 503, code=99991400): rate limited');
+  // Note: code=99991400 hits FAILURE_MAP before the pattern. Either way action=retry.
+  assert.equal(classifyError(httpFive).action, 'retry');
+
+  // --- Unknown codes preserve fallback behavior ---
+  assert.deepEqual(
+    classifyError(99999),
+    { action: 'unknown', reason: 'bot_unknown_error', code: 99999 },
+  );
+
+  // --- TRANSIENT_PATTERNS still exported ---
+  assert.ok(Array.isArray(TRANSIENT_PATTERNS) && TRANSIENT_PATTERNS.length >= 5);
+
+  // --- FAILURE_MAP coverage: all new codes are registered ---
+  assert.ok(FAILURE_MAP[20064], 'FAILURE_MAP must register 20064');
+  assert.ok(FAILURE_MAP[91403], 'FAILURE_MAP must register 91403');
+  assert.ok(FAILURE_MAP[1254000], 'FAILURE_MAP must register 1254000');
+
+  console.log('error-codes.js: PASS');
+}
+
+if (require.main === module) run();
+module.exports = { run };

package/src/test-identity-state.js

@@ -0,0 +1,177 @@
+// src/test-identity-state.js — unit test for src/auth/identity-state.js.
+//
+// resolveIdentity + withIdentityFallback are the v1.3.12 replacement for
+// asUserOrApp's silent fallback. Behaviour we test:
+//
+//   1. resolveIdentity reads in-memory client state (no API call by default)
+//      and returns one of: VALID_USER / UAT_EXPIRED / BOT_ONLY / NO_CREDENTIALS.
+//   2. withIdentityFallback wraps a UAT-first / bot-fallback flow, attaches
+//      via / via_reason / identity to the response, refines the cached
+//      identity on UAT failure (e.g. 20064 → UAT_REVOKED), and returns a
+//      well-formed combined error when both sides fail.
+//   3. invalidateIdentity clears the 30s cache so a new probe is taken next
+//      time (CredentialsMonitor will call this on UAT change).
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const {
+  IdentityState,
+  resolveIdentity,
+  withIdentityFallback,
+  invalidateIdentity,
+} = require('./auth/identity-state');
+
+// Minimal fake client. Real LarkOfficialClient exposes hasUAT (getter), appId,
+// _uat, _uatExpires; tests only need those.
+function fakeClient({ hasUAT = false, appId = 'cli_test', expires = 0 } = {}) {
+  return {
+    appId,
+    appSecret: 'secret',
+    _uat: hasUAT ? 'token' : null,
+    _uatRefresh: hasUAT ? 'refresh' : null,
+    _uatExpires: expires,
+    get hasUAT() { return !!this._uat; },
+  };
+}
+
+async function run() {
+  // --- 1. enum values are exported ---
+  for (const k of ['VALID_USER', 'UAT_EXPIRED', 'UAT_REVOKED', 'UAT_MISSING_SCOPE', 'BOT_ONLY', 'NO_CREDENTIALS']) {
+    assert.ok(IdentityState[k], `IdentityState.${k} should be defined`);
+  }
+
+  // --- 2. resolveIdentity, no UAT, has app ---
+  const c1 = fakeClient({ hasUAT: false, appId: 'cli_x' });
+  invalidateIdentity(c1);
+  assert.equal(await resolveIdentity(c1), IdentityState.BOT_ONLY);
+
+  // --- 3. resolveIdentity, no UAT, no app ---
+  const c2 = fakeClient({ hasUAT: false, appId: null });
+  invalidateIdentity(c2);
+  assert.equal(await resolveIdentity(c2), IdentityState.NO_CREDENTIALS);
+
+  // --- 4. resolveIdentity, valid UAT (future expiry) ---
+  const c3 = fakeClient({ hasUAT: true, expires: Math.floor(Date.now() / 1000) + 3600 });
+  invalidateIdentity(c3);
+  assert.equal(await resolveIdentity(c3), IdentityState.VALID_USER);
+
+  // --- 5. resolveIdentity, expired UAT (past expiry) ---
+  const c4 = fakeClient({ hasUAT: true, expires: Math.floor(Date.now() / 1000) - 100 });
+  invalidateIdentity(c4);
+  assert.equal(await resolveIdentity(c4), IdentityState.UAT_EXPIRED);
+
+  // --- 6. resolveIdentity cache: change underlying state, get cached value ---
+  invalidateIdentity(c1);
+  assert.equal(await resolveIdentity(c1), IdentityState.BOT_ONLY);
+  c1._uat = 'token'; // simulate adopt-persisted-uat happened mid-flight
+  c1._uatExpires = Math.floor(Date.now() / 1000) + 3600;
+  // Still cached — 30s window not elapsed.
+  assert.equal(await resolveIdentity(c1), IdentityState.BOT_ONLY, 'cache should hold within 30s');
+  invalidateIdentity(c1);
+  assert.equal(await resolveIdentity(c1), IdentityState.VALID_USER, 'invalidate reads fresh state');
+
+  // --- 7. withIdentityFallback: UAT path succeeds ---
+  const cOk = fakeClient({ hasUAT: true, expires: Math.floor(Date.now() / 1000) + 3600 });
+  invalidateIdentity(cOk);
+  const r1 = await withIdentityFallback({
+    client: cOk,
+    uatFn: async () => ({ code: 0, data: { ok: true } }),
+    botFn: async () => { throw new Error('should not run'); },
+    label: 'test_op',
+  });
+  assert.equal(r1.via, 'uat');
+  assert.equal(r1.identity, IdentityState.VALID_USER);
+  assert.equal(r1.data.code, 0);
+  assert.equal(r1.data.ok, undefined, 'should pass through fields, not double-wrap');
+  assert.equal(r1.data.data.ok, true);
+  assert.equal(r1.viaReason, undefined, 'no fallback → no via_reason');
+  // PR #103 Codex P1 followup: UAT success must set the legacy _viaUser=true
+  // marker so 15+ _asUserOrApp callsites (calendar/docs/bitable/wiki/okr/tasks
+  // /drive) report viaUser:true. Without this flag downstream code thinks the
+  // resource was created by the bot.
+  assert.equal(r1.data._viaUser, true, 'UAT success path must mark _viaUser=true on response');
+
+  // --- 8. withIdentityFallback: UAT returns 20064 → bot fallback, identity refined ---
+  let botRan = false;
+  const cRevoked = fakeClient({ hasUAT: true, expires: Math.floor(Date.now() / 1000) + 3600 });
+  invalidateIdentity(cRevoked);
+  const r2 = await withIdentityFallback({
+    client: cRevoked,
+    uatFn: async () => ({ code: 20064, msg: 'invalid_grant' }),
+    botFn: async () => { botRan = true; return { code: 0, data: { from: 'bot' } }; },
+    label: 'test_revoked',
+  });
+  assert.equal(botRan, true);
+  assert.equal(r2.via, 'bot');
+  assert.equal(r2.identity, IdentityState.UAT_REVOKED, 'identity refined on 20064');
+  assert.ok(typeof r2.viaReason === 'string' && r2.viaReason.includes('20064'));
+  assert.ok(r2.fallbackWarning && r2.fallbackWarning.includes('UAT'));
+
+  // Subsequent resolveIdentity sees the refined cached state without re-probe.
+  assert.equal(await resolveIdentity(cRevoked), IdentityState.UAT_REVOKED);
+
+  // --- 9. withIdentityFallback: UAT 99991668 → UAT_MISSING_SCOPE ---
+  const cScope = fakeClient({ hasUAT: true, expires: Math.floor(Date.now() / 1000) + 3600 });
+  invalidateIdentity(cScope);
+  const r3 = await withIdentityFallback({
+    client: cScope,
+    uatFn: async () => ({ code: 99991668, msg: 'scope not granted' }),
+    botFn: async () => ({ code: 0, data: { ok: true } }),
+    label: 'test_scope',
+  });
+  assert.equal(r3.identity, IdentityState.UAT_MISSING_SCOPE);
+  assert.equal(r3.via, 'bot');
+
+  // --- 10. withIdentityFallback: UAT throws → bot fallback ---
+  const cThrow = fakeClient({ hasUAT: true, expires: Math.floor(Date.now() / 1000) + 3600 });
+  invalidateIdentity(cThrow);
+  const r4 = await withIdentityFallback({
+    client: cThrow,
+    uatFn: async () => { throw new Error('network blew up'); },
+    botFn: async () => ({ code: 0, data: { ok: 'bot' } }),
+    label: 'test_throw',
+  });
+  assert.equal(r4.via, 'bot');
+  assert.ok(r4.viaReason.includes('network blew up'));
+
+  // --- 11. withIdentityFallback: BOT_ONLY → no uat attempted, informational warning ---
+  const cBotOnly = fakeClient({ hasUAT: false, appId: 'cli_x' });
+  invalidateIdentity(cBotOnly);
+  let uatRan = false;
+  const r5 = await withIdentityFallback({
+    client: cBotOnly,
+    uatFn: async () => { uatRan = true; return { code: 0 }; },
+    botFn: async () => ({ code: 0, data: { ok: 'bot' } }),
+    label: 'test_botonly',
+  });
+  assert.equal(uatRan, false, 'BOT_ONLY must not invoke uatFn');
+  assert.equal(r5.via, 'bot');
+  assert.equal(r5.identity, IdentityState.BOT_ONLY);
+  // BOT_ONLY still attaches the legacy "未配置 UAT" informational warning so
+  // users notice that resources will be owned by the shared bot.
+  assert.ok(r5.fallbackWarning && r5.fallbackWarning.includes('未配置 UAT'));
+
+  // --- 12. withIdentityFallback: both sides fail → throws combined error ---
+  const cBoth = fakeClient({ hasUAT: true, expires: Math.floor(Date.now() / 1000) + 3600 });
+  invalidateIdentity(cBoth);
+  let caught;
+  try {
+    await withIdentityFallback({
+      client: cBoth,
+      uatFn: async () => ({ code: 99991668, msg: 'no scope' }),
+      botFn: async () => { throw new Error('bot not in chat'); },
+      label: 'test_both_fail',
+    });
+  } catch (e) { caught = e; }
+  assert.ok(caught, 'both-fail should throw');
+  assert.ok(caught.message.includes('test_both_fail'));
+  assert.ok(caught.message.includes('bot not in chat'));
+  assert.ok(caught.uatSummary, 'combined error carries uatSummary');
+  assert.ok(caught.botError, 'combined error carries botError');
+
+  console.log('identity-state.js: PASS');
+}
+
+if (require.main === module) run().catch(e => { console.error(e); process.exit(1); });
+module.exports = { run };

package/src/test-lark-desktop.js

@@ -298,3 +298,4 @@ function run() {
 if (require.main === module) {
   run();
 }
+module.exports = { run };

package/src/test-lockfile-pid.js

@@ -0,0 +1,90 @@
+// src/test-lockfile-pid.js — verify acquireLongLived's v1.3.12 PID
+// liveness check.
+//
+// Pre-v1.3.12 the lock was judged "alive" purely by mtime: heartbeat every
+// 15s, stale after 60s. If the owner process got SIGKILL'd (or crashed
+// mid-heartbeat), the lock looked alive for up to 60s. With the WS event
+// subscription tied to the lock, a hung owner blocked event ingestion for
+// the entire window.
+//
+// New behaviour: when stat says mtime is fresh, ALSO read the lock body and
+// `process.kill(pid, 0)`. If ESRCH → process is gone, lock is steal-eligible
+// immediately regardless of mtime.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const assert = require('node:assert/strict');
+const { acquireLongLived } = require('./events/lockfile');
+
+function run() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fish-pid-lock-'));
+  const lockPath = path.join(dir, 'test.lock');
+
+  // --- 1. Write a lock body for a pid that definitely doesn't exist.
+  //        PID 1 is init/launchd — always exists; we need a pid that's
+  //        certainly gone. Use a huge integer well outside the kernel's
+  //        normal range; the most portable check is process.kill(pid, 0).
+  const fakePid = 999_999_999;
+  const body = JSON.stringify({ version: 1, pid: fakePid, start_time: Math.floor(Date.now() / 1000), role: 'test_dead_owner' });
+  fs.writeFileSync(lockPath, body, { mode: 0o600 });
+  // Fresh mtime — pre-v1.3.12 this would block acquisition for 60s.
+  fs.utimesSync(lockPath, new Date(), new Date());
+
+  const handle = acquireLongLived(lockPath, { info: { role: 'new_owner' }, staleMs: 60_000 });
+  assert.ok(handle, 'should be able to steal lock when holder pid is dead, even when mtime is fresh');
+
+  // Read body — should now contain THIS process's pid.
+  const newBody = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+  assert.equal(newBody.pid, process.pid);
+
+  handle.release();
+
+  // --- 2. Live pid (this process) prevents acquisition even past staleMs
+  //        when content shows we're still alive — but for safety we treat
+  //        EPERM (different user, can't probe) as alive too. Skip EPERM
+  //        case since it requires multi-user setup.
+  const livePid = process.pid;
+  const liveBody = JSON.stringify({ version: 1, pid: livePid, start_time: Math.floor(Date.now() / 1000), role: 'live_owner' });
+  fs.writeFileSync(lockPath, liveBody, { mode: 0o600 });
+  fs.utimesSync(lockPath, new Date(), new Date());
+  const blocked = acquireLongLived(lockPath, { info: {}, staleMs: 60_000 });
+  assert.equal(blocked, null, 'live pid + fresh mtime → cannot steal');
+  fs.unlinkSync(lockPath); // cleanup
+
+  // --- 3. Stale mtime + live pid: previously would have stolen; new behaviour
+  //        keeps the steal because mtime says heartbeat is dead.
+  //        (We don't try to second-guess a stuck process — mtime is the
+  //        primary signal; PID check only adds the ability to reclaim
+  //        FASTER when process is definitively dead.)
+  fs.writeFileSync(lockPath, JSON.stringify({ version: 1, pid: livePid, start_time: Math.floor(Date.now() / 1000) - 999 }), { mode: 0o600 });
+  // Backdate mtime well past staleMs.
+  const backdate = new Date(Date.now() - 120_000);
+  fs.utimesSync(lockPath, backdate, backdate);
+  const stolenLive = acquireLongLived(lockPath, { info: {}, staleMs: 60_000 });
+  assert.ok(stolenLive, 'stale mtime should still allow takeover (back-compat)');
+  stolenLive.release();
+
+  // --- 4. Body missing pid field (legacy locks from older versions) — fall
+  //        back to mtime-only check (existing behaviour, no regression).
+  fs.writeFileSync(lockPath, JSON.stringify({ version: 1 }), { mode: 0o600 });
+  fs.utimesSync(lockPath, new Date(), new Date());
+  const noPidBlocked = acquireLongLived(lockPath, { info: {}, staleMs: 60_000 });
+  assert.equal(noPidBlocked, null, 'no pid in body → fall back to mtime, fresh mtime blocks');
+  fs.unlinkSync(lockPath);
+
+  // --- 5. Malformed lock body (not JSON) — mtime-only fallback.
+  fs.writeFileSync(lockPath, 'not json at all', { mode: 0o600 });
+  fs.utimesSync(lockPath, new Date(), new Date());
+  const malformedBlocked = acquireLongLived(lockPath, { info: {}, staleMs: 60_000 });
+  assert.equal(malformedBlocked, null, 'malformed body → fall back to mtime, fresh mtime blocks');
+  fs.unlinkSync(lockPath);
+
+  fs.rmSync(dir, { recursive: true, force: true });
+  console.log('lockfile-pid.js: PASS');
+}
+
+if (require.main === module) run();
+module.exports = { run };

package/src/test-lru-cache.js

@@ -0,0 +1,145 @@
+// src/test-lru-cache.js — unit test for the LRUCache class exported by src/utils.js.
+//
+// Replaces the v1.3.12 `new Map()` _userNameCache / _appNameCache. Pre-fix the
+// caches grew unboundedly across the server's lifetime (one entry per unique
+// open_id ever seen) and never expired — a 1-week-uptime MCP would carry
+// stale display names from messages of users who renamed themselves days ago.
+//
+// LRU with TTL solves both:
+//   - max=500 caps the per-process memory at O(KiB) regardless of message volume
+//   - ttlMs=10min ensures rename / leave-tenant changes get re-resolved
+//
+// We test the basic operations + interactions between TTL and LRU.
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const { LRUCache } = require('./utils');
+
+async function run() {
+  // --- 1. set/get/has roundtrip ---
+  {
+    const c = new LRUCache({ max: 5, ttlMs: 1000 });
+    c.set('a', 1);
+    assert.equal(c.get('a'), 1);
+    assert.equal(c.has('a'), true);
+    assert.equal(c.get('missing'), undefined);
+    assert.equal(c.has('missing'), false);
+    assert.equal(c.size, 1);
+  }
+
+  // --- 2. LRU eviction: oldest dropped when over max ---
+  {
+    const c = new LRUCache({ max: 3, ttlMs: 60_000 });
+    c.set('a', 1);
+    c.set('b', 2);
+    c.set('c', 3);
+    c.set('d', 4); // evicts 'a'
+    assert.equal(c.has('a'), false);
+    assert.equal(c.get('b'), 2);
+    assert.equal(c.get('c'), 3);
+    assert.equal(c.get('d'), 4);
+    assert.equal(c.size, 3);
+  }
+
+  // --- 3. Access promotes recency: get prevents eviction ---
+  {
+    const c = new LRUCache({ max: 3, ttlMs: 60_000 });
+    c.set('a', 1);
+    c.set('b', 2);
+    c.set('c', 3);
+    c.get('a'); // 'a' becomes most-recently-used; 'b' is now LRU
+    c.set('d', 4); // evicts 'b'
+    assert.equal(c.has('a'), true);
+    assert.equal(c.has('b'), false);
+    assert.equal(c.has('c'), true);
+    assert.equal(c.has('d'), true);
+  }
+
+  // --- 4. TTL expiry: get returns undefined for expired ---
+  {
+    const c = new LRUCache({ max: 10, ttlMs: 50 });
+    c.set('a', 1);
+    assert.equal(c.get('a'), 1);
+    await new Promise(r => setTimeout(r, 80));
+    assert.equal(c.get('a'), undefined, 'expired entries return undefined');
+    assert.equal(c.has('a'), false);
+    // Expired entry is purged: size drops.
+    assert.equal(c.size, 0);
+  }
+
+  // --- 5. Setting an existing key refreshes TTL ---
+  {
+    const c = new LRUCache({ max: 10, ttlMs: 100 });
+    c.set('a', 1);
+    await new Promise(r => setTimeout(r, 60));
+    c.set('a', 1); // refresh
+    await new Promise(r => setTimeout(r, 60));
+    // 120ms total since first set, only 60ms since refresh — still valid.
+    assert.equal(c.get('a'), 1);
+  }
+
+  // --- 6. delete + clear ---
+  {
+    const c = new LRUCache({ max: 5, ttlMs: 1000 });
+    c.set('a', 1);
+    c.set('b', 2);
+    c.delete('a');
+    assert.equal(c.has('a'), false);
+    assert.equal(c.size, 1);
+    c.clear();
+    assert.equal(c.size, 0);
+    assert.equal(c.has('b'), false);
+  }
+
+  // --- 7. Map-compatible shim (we replace `new Map()` in base.js — the
+  // existing call sites use .has / .get / .set / .clear, which the class
+  // implements identically. Smoke-check parity here.) ---
+  {
+    const c = new LRUCache({ max: 5, ttlMs: 1000 });
+    c.set('open_x', 'Alice');
+    assert.equal(c.has('open_x'), true);
+    assert.equal(c.get('open_x'), 'Alice');
+  }
+
+  // --- 8. Iteration support: the comment claims "API-compatible with the
+  // old Map", so spread / for-of / entries / keys / values must all work.
+  // Map is iterable via Symbol.iterator yielding [key, value] tuples.
+  {
+    const c = new LRUCache({ max: 5, ttlMs: 60_000 });
+    c.set('a', 1);
+    c.set('b', 2);
+    c.set('c', 3);
+    const collected = [...c];
+    assert.equal(collected.length, 3);
+    // Map insertion order, [key, value] tuples.
+    assert.deepEqual(collected[0], ['a', 1]);
+    assert.deepEqual(collected[2], ['c', 3]);
+
+    const forOfKeys = [];
+    for (const [k] of c) forOfKeys.push(k);
+    assert.deepEqual(forOfKeys, ['a', 'b', 'c']);
+
+    assert.deepEqual([...c.keys()], ['a', 'b', 'c']);
+    assert.deepEqual([...c.values()], [1, 2, 3]);
+    assert.deepEqual([...c.entries()], [['a', 1], ['b', 2], ['c', 3]]);
+  }
+
+  // --- 9. Iteration skips expired entries (TTL gate is consistent across
+  // get/has and iteration so callers don't see stale data via spread).
+  {
+    const c = new LRUCache({ max: 5, ttlMs: 50 });
+    c.set('a', 1);
+    c.set('b', 2);
+    await new Promise(r => setTimeout(r, 80));
+    c.set('c', 3); // fresh after expiry of a/b
+    const collected = [...c];
+    assert.equal(collected.length, 1);
+    assert.deepEqual(collected[0], ['c', 3]);
+  }
+
+  console.log('lru-cache.js: PASS');
+}
+
+if (require.main === module) run().catch(e => { console.error(e); process.exit(1); });
+module.exports = { run };

package/src/test-negative-cache.js

@@ -0,0 +1,85 @@
+// src/test-negative-cache.js — verify _populateSenderNames writes a null
+// sentinel for un-resolvable open_ids so repeated read_messages calls
+// don't re-fire the same contact API request.
+//
+// Pre-fix bug: contacts.js::getUserById returned null on failure without
+// writing to _userNameCache, so every subsequent _populateSenderNames
+// invocation re-added the same id to unknownUserIds and dispatched another
+// API call. In a hot chat with N un-resolvable senders that's N redundant
+// API calls per read_messages — observed in the 2026-05 incident's stderr.
+//
+// Fix lives in _populateSenderNames itself (not in contacts.js): after each
+// Promise.allSettled batch, ids still absent from _userNameCache get a null
+// sentinel written. has(id)==true / get(id)==null on next call → the loop
+// skips the id entirely, _computeDisplayLabel falls back to "(open_id)"
+// the same way it would have without a cache.
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const { LarkOfficialClient } = require('./clients/official');
+
+async function run() {
+  const c = new LarkOfficialClient('cli_test', 'fake_secret');
+  // Stub self tenant probe so the real one doesn't hit Feishu.
+  c._resolveSelfTenantKey = async () => 'tenant_self';
+  c._selfTenantKey = 'tenant_self';
+
+  // Mock getUserById to simulate a un-resolvable user: cache nothing,
+  // return null. The fix in _populateSenderNames is what should write the
+  // null sentinel afterwards.
+  let userCallCount = 0;
+  c.getUserById = async (userId) => {
+    if (c._userNameCache.has(userId)) return c._userNameCache.get(userId);
+    userCallCount++;
+    return null;
+  };
+
+  // Same for getAppName.
+  let appCallCount = 0;
+  c.getAppName = async (appId) => {
+    if (c._appNameCache.has(appId)) return c._appNameCache.get(appId);
+    appCallCount++;
+    return null;
+  };
+
+  // --- 1. User negative-cache: un-resolvable ou_bad ---
+  const items1 = [{ senderId: 'ou_bad', senderType: 'user' }];
+  await c._populateSenderNames(items1, null);
+  assert.equal(userCallCount, 1, 'first populate dispatches one API call');
+  assert.equal(items1[0].senderName, null);
+  assert.equal(items1[0].displayLabel, '(ou_bad)');
+
+  // Cache must now hold a null sentinel.
+  assert.equal(c._userNameCache.has('ou_bad'), true, 'null sentinel written for un-resolvable id');
+  assert.equal(c._userNameCache.get('ou_bad'), null);
+
+  // --- 2. Same id, second populate → cache hit, no new API call ---
+  const items2 = [{ senderId: 'ou_bad', senderType: 'user' }];
+  await c._populateSenderNames(items2, null);
+  assert.equal(userCallCount, 1, 'cached null skips dispatch');
+  assert.equal(items2[0].displayLabel, '(ou_bad)');
+
+  // --- 3. Mixed batch: new id triggers exactly one new call ---
+  const items3 = [
+    { senderId: 'ou_bad', senderType: 'user' },
+    { senderId: 'ou_new', senderType: 'user' },
+  ];
+  await c._populateSenderNames(items3, null);
+  assert.equal(userCallCount, 2, 'new id alone dispatches one new call');
+
+  // --- 4. App negative-cache: un-resolvable cli_bad ---
+  const items4 = [{ senderId: 'cli_bad', senderType: 'app' }];
+  await c._populateSenderNames(items4, null);
+  assert.equal(appCallCount, 1);
+  assert.equal(items4[0].displayLabel, '[Bot] (cli_bad)');
+
+  const items5 = [{ senderId: 'cli_bad', senderType: 'app' }];
+  await c._populateSenderNames(items5, null);
+  assert.equal(appCallCount, 1, 'cached null app skips dispatch');
+
+  console.log('negative-cache.js: PASS');
+}
+
+if (require.main === module) run().catch(e => { console.error(e); process.exit(1); });
+module.exports = { run };