feishu-user-plugin 1.3.13 → 1.3.14

package/src/auth/uat.js

@@ -28,13 +28,36 @@ const path = require('path');
 const os = require('os');
 const { fetchWithTimeout } = require('../utils');
 
+// One-warning-per-malformed-token tracker. Without this, a persistently bad
+// JWT would flood stderr every tool call (getValidUAT calls decode whenever
+// _uatExpires falsy, which it stays at 0 if decode returns 0). 1024-entry cap
+// is conservative — real tokens are rotated rarely; cap prevents OOM in the
+// unlikely event of a malformed-token spray.
+const _warnedMalformedTokens = new Set();
+function _markWarnedMalformedToken(token) {
+  if (typeof token !== 'string' || token.length === 0) return false;
+  const key = require('crypto').createHash('sha256').update(token, 'utf8').digest('hex').slice(0, 16);
+  if (_warnedMalformedTokens.has(key)) return false;
+  if (_warnedMalformedTokens.size >= 1024) _warnedMalformedTokens.clear();
+  _warnedMalformedTokens.add(key);
+  return true;
+}
+
 function decodeTokenExpiry(token) {
   try {
     const payload = token?.split('.')?.[1];
     if (!payload) return 0;
     const data = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
     return typeof data.exp === 'number' ? data.exp : 0;
-  } catch (_) {
+  } catch (e) {
+    // Log breadcrumb so silently-malformed UATs are observable, but only once
+    // per distinct bad token (hashed). We still return 0 (caller treats 0 as
+    // "never decoded — let refresh path decide") instead of throwing, because
+    // a bad JWT shouldn't crash tool dispatch — the next 99991663/99991668
+    // response will trigger refresh anyway.
+    if (_markWarnedMalformedToken(token)) {
+      console.error(`[feishu-user-plugin] decodeTokenExpiry: malformed JWT payload (${e.message}); will rely on Feishu rejection for refresh trigger`);
+    }
     return 0;
   }
 }
@@ -73,7 +96,12 @@ function adoptPersistedUATIfNewer(client) {
 }
 
 function uatLockPath() {
-  return path.join(os.homedir(), '.claude', 'feishu-uat-refresh.lock');
+  // v1.3.14: moved from ~/.claude/feishu-uat-refresh.lock to canonical
+  // ~/.feishu-user-plugin/ so Codex-only / non-Claude-Code users (whose
+  // ~/.claude/ may not exist) still get cross-process mutual exclusion.
+  // Mixed-version concern is N/A — running two different versions of this
+  // plugin in parallel is not a supported configuration.
+  return path.join(os.homedir(), '.feishu-user-plugin', 'uat-refresh.lock');
 }
 
 async function acquireRefreshLock(lockPath, { staleMs = 30000, pollMs = 200, timeoutMs = 20000 } = {}) {
@@ -105,13 +133,32 @@ function releaseRefreshLock(lockPath) {
 }
 
 async function refreshUAT(client) {
+  // v1.3.14 — Pre-lock cheap path: maybe a peer process already refreshed and
+  // persisted a valid token. Adopt it before paying for the file lock. This
+  // dramatically reduces lock contention in deployments with 10+ concurrent
+  // MCP server processes (one per Claude Code session).
+  let now = Math.floor(Date.now() / 1000);
+  if (adoptPersistedUATIfNewer(client) && client._uatExpires > now + 300) {
+    return client._uat;
+  }
+
   const lockPath = uatLockPath();
   const acquired = await acquireRefreshLock(lockPath);
   if (!acquired) {
-    console.error('[feishu-user-plugin] UAT refresh lock timed out; proceeding without mutual exclusion');
+    // Lock timed out (>20s of contention). Before falling through to an
+    // un-coordinated refresh — which can burn the refresh_token chain on the
+    // Feishu side — give disk one more chance: a peer may have written a
+    // fresh token between our pre-check and now.
+    now = Math.floor(Date.now() / 1000);
+    if (adoptPersistedUATIfNewer(client) && client._uatExpires > now + 300) {
+      return client._uat;
+    }
+    console.error('[feishu-user-plugin] UAT refresh lock timed out; proceeding without mutual exclusion (this may burn refresh_token chain — investigate if it happens often)');
   }
   try {
-    const now = Math.floor(Date.now() / 1000);
+    // Inside the lock: re-check disk one more time. Between acquireRefreshLock
+    // returning and this point, another holder may have released after writing.
+    now = Math.floor(Date.now() / 1000);
     if (adoptPersistedUATIfNewer(client) && client._uatExpires > now + 300) {
       return client._uat;
     }
@@ -128,7 +175,28 @@ async function refreshUAT(client) {
     });
     const data = await res.json();
     const tokenData = data.access_token ? data : data.data;
-    if (!tokenData?.access_token) throw new Error(`UAT refresh failed: ${JSON.stringify(data)}. Run: npx feishu-user-plugin oauth`);
+    if (!tokenData?.access_token) {
+      // v1.3.14 — never dump the raw response body. Some Feishu error paths
+      // echo back portions of the request including refresh_token bytes, and
+      // this message bubbles up to Error.message → MCP content[0].text →
+      // LLM transcript. Surface only the structured error code/msg.
+      const errCode = data?.error ?? data?.code ?? 'unknown';
+      const errMsg = data?.error_description ?? data?.msg ?? '(no error message from Feishu)';
+      // Distinguish refresh_token rejection (must re-oauth) from transient
+      // server-side errors so the identity state machine can flip to
+      // UAT_REVOKED, and withIdentityFallback can give the LLM clear guidance.
+      const isInvalidGrant = errCode === 'invalid_grant' || errCode === 20064;
+      if (isInvalidGrant) {
+        try {
+          const { _refineIdentity, IdentityState } = require('./identity-state');
+          _refineIdentity(client, IdentityState.UAT_REVOKED);
+        } catch (_) { /* identity-state may not be loaded in CLI subcommands; non-fatal */ }
+        const err = new Error('UAT refresh_token rejected by Feishu (invalid_grant). The 7-day refresh chain is broken. Run: npx feishu-user-plugin oauth to re-authorize.');
+        err.uatRevoked = true;
+        throw err;
+      }
+      throw new Error(`UAT refresh failed (code=${errCode}: ${errMsg}). If persistent, run: npx feishu-user-plugin oauth.`);
+    }
     client._uat = tokenData.access_token;
     client._uatRefresh = tokenData.refresh_token || client._uatRefresh;
     const expiresIn = typeof tokenData.expires_in === 'number' && tokenData.expires_in > 0 ? tokenData.expires_in : 7200;
@@ -164,9 +232,15 @@ async function withUAT(client, fn) {
   } catch (err) {
     const cls = classifyError(err);
     if (cls.action === 'retry') {
-      return fn(uat);
+      // v1.3.14 — fall through into the auth-code check below instead of
+      // returning the retry result raw. A token rotated between our first
+      // attempt and the retry (peer process refreshed) can manifest as a
+      // 99991663/99991668 in the retry response, and we want refreshUAT to
+      // run before bubbling that up as a hard failure.
+      data = await fn(uat);
+    } else {
+      throw err;
     }
-    throw err;
   }
 
   if (data.code === 99991668 || data.code === 99991663 || data.code === 99991677) {
@@ -242,4 +316,9 @@ module.exports = {
   asUserOrApp,
   persistUAT,
   adoptPersistedUATIfNewer,
+  // v1.3.14 — exposed for testing (lifecycle + race tests). Not part of the
+  // stable API; do not use outside src/test-* or scripts/test-* harnesses.
+  uatLockPath,
+  acquireRefreshLock,
+  releaseRefreshLock,
 };

package/src/cli.js

@@ -248,9 +248,10 @@ async function keepalive() {
       const needSwitch = all && prevActive !== profileName;
       try {
         if (needSwitch) cred.setActiveProfile(profileName);
-        // Set process.env so LarkOfficialClient.loadUAT() picks the right tokens
-        process.env.LARK_USER_ACCESS_TOKEN = env.LARK_USER_ACCESS_TOKEN;
-        process.env.LARK_USER_REFRESH_TOKEN = env.LARK_USER_REFRESH_TOKEN;
+        // v1.3.14 — direct field assignment is the source of truth; do NOT
+        // also set process.env (previous comment claimed LarkOfficialClient
+        // would read process.env, but loadUAT() is dead code and process.env
+        // pollution leaked between iterations of the --all loop).
         const official = new LarkOfficialClient(env.LARK_APP_ID, env.LARK_APP_SECRET);
         official._uat = env.LARK_USER_ACCESS_TOKEN;
         official._uatRefresh = env.LARK_USER_REFRESH_TOKEN;

package/src/clients/official/base.js

@@ -21,16 +21,21 @@ class LarkOfficialClient {
   }
 
   // --- UAT (User Access Token) Management ---
+  //
+  // v1.3.14 — preferred entry is src/server.js::loadUATFromEnv(client, env),
+  // which reads from a specific env block (credentials.json profile or harness
+  // env) rather than from process.env. `loadUAT()` below is kept for backward
+  // compat with `src/test-all.js` and any external callers, but new code in
+  // this repo should NOT use it — it can't see credentials.json profiles and
+  // doesn't participate in the profile-switch hot-reload path.
 
+  /** @deprecated v1.3.14 — use server.loadUATFromEnv(client, env) instead. */
   loadUAT() {
     const token = process.env.LARK_USER_ACCESS_TOKEN;
-    const refresh = process.env.LARK_USER_REFRESH_TOKEN;
-    const expires = parseInt(process.env.LARK_UAT_EXPIRES || '0');
-    if (token) {
-      this._uat = token;
-      this._uatRefresh = refresh || null;
-      this._uatExpires = expires || this._decodeTokenExpiry(token);
-    }
+    if (!token) return;
+    this._uat = token;
+    this._uatRefresh = process.env.LARK_USER_REFRESH_TOKEN || null;
+    this._uatExpires = parseInt(process.env.LARK_UAT_EXPIRES || '0') || this._decodeTokenExpiry(token);
   }
 
   get hasUAT() {

package/src/error-codes.js

@@ -27,7 +27,8 @@ const FAILURE_MAP = {
   19001:  { action: 'uat', reason: 'bot_chat_not_found' },
 
   // UAT revoked — refresh_token explicitly invalid_grant (user revoked OAuth
-  // or 30-day window elapsed). The live trigger for this code lives in
+  // or the 7-day refresh_token window elapsed without any successful refresh
+  // to roll it forward). The live trigger for this code lives in
   // identity-state.js::_classifyUatFailure (UAT REST throws / returns 20064);
   // this entry exists for *symmetry* — should a bot-side surface ever return
   // 20064 (it shouldn't, bot uses app_access_token not refresh_token), the

package/src/oauth.js

@@ -16,6 +16,7 @@ const http = require('http');
 const { execSync } = require('child_process');
 const credentialsModule = require('./auth/credentials');
 const legacyConfig = require('./config');
+const { fetchWithTimeout } = require('./utils');
 
 // 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.
@@ -105,10 +106,11 @@ if (!APP_ID || !APP_SECRET) {
 async function getAppInfo() {
   try {
     // Get app_access_token to query app details
-    const tokenRes = await fetch('https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal', {
+    const tokenRes = await fetchWithTimeout('https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal', {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({ app_id: APP_ID, app_secret: APP_SECRET }),
+      timeoutMs: 10000,
     });
     const tokenData = await tokenRes.json();
     if (!tokenData.app_access_token) {
@@ -118,8 +120,9 @@ async function getAppInfo() {
 
     // Get app info — try the direct app query first, fall back to underauditlist
     let appName = null;
-    const directRes = await fetch(`https://open.feishu.cn/open-apis/application/v6/applications/${APP_ID}?lang=zh_cn`, {
+    const directRes = await fetchWithTimeout(`https://open.feishu.cn/open-apis/application/v6/applications/${APP_ID}?lang=zh_cn`, {
       headers: { 'Authorization': `Bearer ${tokenData.app_access_token}` },
+      timeoutMs: 10000,
     });
     const directData = await directRes.json();
     appName = directData?.data?.app?.app_name;
@@ -134,8 +137,9 @@ async function getAppInfo() {
       } 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', {
+      const listRes = await fetchWithTimeout('https://open.feishu.cn/open-apis/application/v6/applications/underauditlist?lang=zh_cn&page_size=1', {
         headers: { 'Authorization': `Bearer ${tokenData.app_access_token}` },
+        timeoutMs: 10000,
       });
       const listData = await listRes.json();
       appName = listData?.data?.items?.[0]?.app_name;
@@ -156,11 +160,15 @@ async function exchangeCode(code) {
     code,
     redirect_uri: REDIRECT_URI,
   };
-  console.log('Token exchange request:', JSON.stringify({ ...body, client_secret: '***' }));
-  const tokenRes = await fetch('https://open.feishu.cn/open-apis/authen/v2/oauth/token', {
+  // v1.3.14 — redact `code` too: the authorization code is short-lived but
+  // it IS an exchangeable credential while it's still valid (~60s pre-exchange).
+  // Logging it to stdout means transcripts retain a usable credential window.
+  console.log('Token exchange request:', JSON.stringify({ ...body, client_secret: '***', code: '***' }));
+  const tokenRes = await fetchWithTimeout('https://open.feishu.cn/open-apis/authen/v2/oauth/token', {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: JSON.stringify(body),
+    timeoutMs: 15000,
   });
   const raw = await tokenRes.text();
   // v1.3.13 security followup: don't log the full raw body — it contains the
@@ -236,11 +244,15 @@ const server = http.createServer(async (req, res) => {
 
       const hasRefresh = !!tokenData.refresh_token;
       res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+      // v1.3.14 — do not display any token bytes in the browser callback.
+      // Browser history / screenshots / OS screen recordings would otherwise
+      // retain the first 20 chars of the access token. Replaced with a length
+      // attestation so the user still sees the flow succeeded.
       res.end(`<h2>✅ 授权成功!</h2>
-<p>access_token: ${tokenData.access_token.slice(0, 20)}...</p>
+<p>access_token: ✅ 已获取（${tokenData.access_token.length} chars）</p>
 <p>scope: ${tokenData.scope}</p>
 <p>expires_in: ${tokenData.expires_in}s</p>
-<p>refresh_token: ${hasRefresh ? '✅ 已获取（30天有效，支持自动续期）' : '❌ 未返回（token 将在 2 小时后过期，需重新授权）'}</p>
+<p>refresh_token: ${hasRefresh ? '✅ 已获取（7天有效，支持自动续期；每次 refresh 滚动续 7 天）' : '❌ 未返回（token 将在 2 小时后过期，需重新授权）'}</p>
 <p>已保存到 MCP 配置文件，可以关闭此页面。</p>`);
 
       console.log('\n=== OAuth 授权成功 ===');

package/src/server.js

@@ -83,8 +83,15 @@ let nonOwnerPollTimer = null;
 let _ownerStartCallbacks = [];
 
 // Lark Desktop reactor state (v1.3.11 §A) — owned by the heartbeat callback.
+// v1.3.14 — `_lastSwitchAt = 0` was previously misinterpreted as "no recent
+// switch" by the lark-desktop reactor's debounce, so a cold-start owner that
+// hadn't observed any switch would still fire-on-first-tick if the snapshot
+// looked stale. We rebaseline `_lastSwitchAt` to the owner-claim wallclock on
+// first reactor invocation so the cold start window has the same debounce
+// budget as a long-running owner. See `_runLarkDesktopReactor` below.
 let _lastHashMtimes = {};
 let _lastSwitchAt = 0;
+let _reactorFirstTickDone = false;
 const _seenUnboundHashes = new Set();
 
 function _onBecomeOwner(cb) { _ownerStartCallbacks.push(cb); }
@@ -157,11 +164,14 @@ function getOfficialClient() {
   return officialClient;
 }
 
-// Mirror of LarkOfficialClient.loadUAT() but sourced from a specific env block
-// 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
+// UAT loader sourced from a specific env block (credentials.json profile or
+// harness env). Used both at startup and as the hot-reload entry point from
+// credMonitor.onUatChange. When `env` has no UAT (user nuked the token via
+// `oauth` --revoke or manual edit), clears the in-memory copy instead of
 // silently leaving the stale token in place.
+//
+// v1.3.14 — replaced the dead `LarkOfficialClient.loadUAT()` helper that
+// read from process.env. All UAT loading now goes through this function.
 function loadUATFromEnv(client, env) {
   const token = env?.LARK_USER_ACCESS_TOKEN || null;
   const refresh = env?.LARK_USER_REFRESH_TOKEN || null;
@@ -274,6 +284,14 @@ function _credMtime() {
 // the WS client with the new profile's events list).
 function _runLarkDesktopReactor() {
   const ld = require('./auth/lark-desktop');
+  // v1.3.14 — cold-start debounce: prevent the first reactor tick from
+  // treating a long-pre-existing snapshot as a "recent switch". By stamping
+  // _lastSwitchAt at first tick we give the debounce the same baseline as a
+  // long-running owner that just hot-took-over.
+  if (!_reactorFirstTickDone) {
+    _reactorFirstTickDone = true;
+    if (_lastSwitchAt === 0) _lastSwitchAt = Date.now();
+  }
   const out = ld.detectSwitch({
     prevSnapshot: _lastHashMtimes,
     lastSwitchAt: _lastSwitchAt,

package/src/setup.js

@@ -102,10 +102,12 @@ async function main() {
   // Validate app credentials
   console.log('\nValidating app credentials...');
   try {
-    const res = await fetch('https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal', {
+    const { fetchWithTimeout } = require('./utils');
+    const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal', {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
+      timeoutMs: 10000,
     });
     const data = await res.json();
     if (data.app_access_token) {

package/src/test-all.js

@@ -4,6 +4,12 @@
  * Sends test messages to "飞书plugin测试群".
  */
 require('dotenv').config({ path: require('path').join(__dirname, '..', '.env') });
+
+// v1.3.14 — backfill process.env from canonical credentials store so
+// `npm test` works for users who moved creds to ~/.feishu-user-plugin/.
+// See src/auth/env-backfill.js for full rationale.
+require('./auth/env-backfill').backfillFromCanonical();
+
 const { LarkUserClient } = require('./clients/user');
 const { LarkOfficialClient } = require('./clients/official');
 
@@ -333,6 +339,11 @@ main().catch(console.error).finally(() => {
     console.error('with-uat-retry: FAIL', e);
     process.exitCode = 1;
   });
+  require('./test-uat-lifecycle').run().catch(e => {
+    console.error('uat-lifecycle: FAIL', e);
+    process.exitCode = 1;
+  });
+  require('./test-cookie-heartbeat').run();
   require('./test-populate-sender-names').run().catch(e => {
     console.error('populate-sender-names: FAIL', e);
     process.exitCode = 1;

package/src/test-comprehensive.js

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 /**
  * Comprehensive test: exercises every tool category in feishu-user-plugin.
- * Reads credentials from .env, tests each layer independently.
+ * Reads credentials from .env, then backfills from canonical store. Tests
+ * each layer independently.
  */
 const path = require('path');
 require('dotenv').config({ path: path.join(__dirname, '..', '.env') });
+// v1.3.14 — let users on canonical store run this without exporting env vars
+// or maintaining a stale .env. .env still wins via dotenv when present.
+require('./auth/env-backfill').backfillFromCanonical();
 
 const { LarkUserClient } = require('./clients/user');
 const { LarkOfficialClient } = require('./clients/official');
@@ -274,7 +278,8 @@ async function testUAT() {
 }
 
 async function main() {
-  console.log('=== feishu-user-plugin v1.1.3 — Comprehensive Test ===\n');
+  const pkgVersion = require('../package.json').version;
+  console.log(`=== feishu-user-plugin v${pkgVersion} — Comprehensive Test ===\n`);
 
   await testUserIdentity();
   console.log('');

package/src/test-cookie-heartbeat.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// Tests for src/auth/cookie.js owner-gated heartbeat (v1.3.14).
+//
+// Covers:
+//   - _isHeartbeatRunner: returns true when this process IS the ws-owner
+//   - _isHeartbeatRunner: returns false when another pid owns ws-owner.lock
+//   - _isHeartbeatRunner: returns true when ws-owner.lock is missing (fallback)
+//   - _isHeartbeatRunner: returns true when lock body is malformed (fallback)
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const assert = require('assert');
+
+let pass = 0;
+let fail = 0;
+
+function ok(name, fn) {
+  try {
+    fn();
+    console.log(`  OK  ${name}`);
+    pass++;
+  } catch (e) {
+    console.log(`  FAIL ${name}: ${e.message}`);
+    fail++;
+  }
+}
+
+function run() {
+  console.log('=== test-cookie-heartbeat ===');
+
+  const { _isHeartbeatRunner } = require('./auth/cookie');
+
+  // Use a tmpdir + override lockPath/pid for hermetic testing
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'test-cookie-hb-'));
+  const fakeLock = path.join(tmpDir, 'ws-owner.lock');
+
+  ok('returns true when this pid IS the lock owner', () => {
+    fs.writeFileSync(fakeLock, JSON.stringify({
+      version: 1, pid: 12345, start_time: Date.now() / 1000, role: 'ws_owner',
+    }));
+    const r = _isHeartbeatRunner(fakeLock, 12345);
+    assert.strictEqual(r, true);
+  });
+
+  ok('returns false when another pid owns the lock', () => {
+    fs.writeFileSync(fakeLock, JSON.stringify({
+      version: 1, pid: 99999, start_time: Date.now() / 1000, role: 'ws_owner',
+    }));
+    const r = _isHeartbeatRunner(fakeLock, 12345);
+    assert.strictEqual(r, false);
+  });
+
+  ok('returns true (fallback) when lock file missing', () => {
+    try { fs.unlinkSync(fakeLock); } catch (_) {}
+    const r = _isHeartbeatRunner(fakeLock, 12345);
+    assert.strictEqual(r, true, 'no owner claimed → every process runs heartbeat');
+  });
+
+  ok('returns true (fallback) when lock body malformed', () => {
+    fs.writeFileSync(fakeLock, 'not-valid-json');
+    const r = _isHeartbeatRunner(fakeLock, 12345);
+    assert.strictEqual(r, true);
+  });
+
+  ok('returns true (fallback) when lock body has no pid field', () => {
+    fs.writeFileSync(fakeLock, JSON.stringify({ version: 1, start_time: 1, role: 'ws_owner' }));
+    const r = _isHeartbeatRunner(fakeLock, 12345);
+    assert.strictEqual(r, true);
+  });
+
+  ok('returns true (fallback) when lock body pid is a string', () => {
+    fs.writeFileSync(fakeLock, JSON.stringify({ version: 1, pid: '12345', start_time: 1 }));
+    const r = _isHeartbeatRunner(fakeLock, 12345);
+    assert.strictEqual(r, true, 'malformed pid type → fall back to running');
+  });
+
+  // --- _heartbeatTick: the tick path itself ---
+
+  const { _heartbeatTick } = require('./auth/cookie');
+
+  // Helper to assert tick behavior with injectable deps.
+  async function tickWith({ isOwner, expectGetCsrf, expectPersist, expectReturn, throwCsrf = false }) {
+    let getCsrfCalled = false;
+    let persistCalled = false;
+    let persistArg = null;
+    const client = {
+      cookieStr: 'session=abc; sl_session=def',
+      _getCsrfToken: async () => {
+        getCsrfCalled = true;
+        if (throwCsrf) throw new Error('network down');
+      },
+    };
+    const result = await _heartbeatTick(client, {
+      isHeartbeatRunner: () => isOwner,
+      persistToConfig: (updates) => { persistCalled = true; persistArg = updates; },
+    });
+    assert.strictEqual(result, expectReturn, `expected return value ${expectReturn}, got ${result}`);
+    assert.strictEqual(getCsrfCalled, expectGetCsrf, `_getCsrfToken called=${getCsrfCalled} expected ${expectGetCsrf}`);
+    assert.strictEqual(persistCalled, expectPersist, `persistToConfig called=${persistCalled} expected ${expectPersist}`);
+    if (expectPersist) {
+      assert.deepStrictEqual(persistArg, { LARK_COOKIE: 'session=abc; sl_session=def' },
+        `persist called with wrong payload: ${JSON.stringify(persistArg)}`);
+    }
+  }
+
+  ok('_heartbeatTick: non-owner skips network call AND persist', async () => {
+    await tickWith({ isOwner: false, expectGetCsrf: false, expectPersist: false, expectReturn: 'skip' });
+  });
+
+  ok('_heartbeatTick: owner calls _getCsrfToken + persists refreshed cookie', async () => {
+    await tickWith({ isOwner: true, expectGetCsrf: true, expectPersist: true, expectReturn: 'refreshed' });
+  });
+
+  ok('_heartbeatTick: owner with _getCsrfToken throw → returns error WITHOUT persist', async () => {
+    await tickWith({ isOwner: true, expectGetCsrf: true, expectPersist: false, expectReturn: 'error', throwCsrf: true });
+  });
+
+  // Cleanup
+  try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) {}
+
+  console.log(`\n=== test-cookie-heartbeat: ${pass} passed, ${fail} failed ===`);
+  if (fail > 0) process.exit(1);
+}
+
+if (require.main === module) {
+  try { run(); } catch (e) { console.error('test-cookie-heartbeat harness error:', e); process.exit(1); }
+}
+
+module.exports = { run };