feishu-user-plugin 1.3.11 → 1.3.13

package/src/cli.js

@@ -33,6 +33,9 @@ switch (cmd) {
     }
     break;
   }
+  case 'tool':
+    runTool();
+    break;
   case 'migrate':
     migrate();
     break;
@@ -60,6 +63,10 @@ Commands:
   migrate     One-time consolidation: copy creds from harness configs into
               ~/.feishu-user-plugin/credentials.json (single source of truth).
               Dry-run by default. Add --confirm to actually write.
+  tool        Invoke any MCP tool from the shell (v1.3.12):
+              \`tool list\`                — list all tool names
+              \`tool help <name>\`         — print schema for <name>
+              \`tool <name> '<json-args>'\` — invoke <name>, print response
   help        Show this help
 
 Setup options:
@@ -106,6 +113,86 @@ Auto-renewal (optional):
 `);
 }
 
+// `tool` subcommand — invoke any MCP tool from the shell (v1.3.12).
+//
+// Usage:
+//   npx feishu-user-plugin tool list
+//   npx feishu-user-plugin tool help <name>
+//   npx feishu-user-plugin tool <name> '<json-args>'
+//
+// Reuses src/server.js's HANDLERS + buildCtx, so behaviour is identical to
+// calling the tool from an MCP client. Output: tool's content[0].text
+// (which is JSON for most tools — pipe through `jq` if you like).
+async function runTool() {
+  const { TOOLS, HANDLERS, buildCtx } = require('./server');
+  const sub = process.argv[3];
+
+  if (!sub || sub === '--help' || sub === '-h') {
+    console.log(`Usage:
+  npx feishu-user-plugin tool list
+      List all ${TOOLS.length} registered tool names.
+  npx feishu-user-plugin tool help <name>
+      Print the inputSchema for <name>.
+  npx feishu-user-plugin tool <name> '<json-args>'
+      Invoke <name> with the given JSON args, print response text to stdout.
+
+Examples:
+  npx feishu-user-plugin tool list
+  npx feishu-user-plugin tool help send_as_user
+  npx feishu-user-plugin tool get_login_status '{}'
+  npx feishu-user-plugin tool search_messages '{"query":"周报","page_size":5}'
+`);
+    process.exit(sub ? 0 : 2);
+  }
+
+  if (sub === 'list') {
+    for (const t of TOOLS) {
+      console.log(t.name);
+    }
+    return;
+  }
+
+  if (sub === 'help') {
+    const name = process.argv[4];
+    if (!name) { console.error('Usage: tool help <name>'); process.exit(2); }
+    const t = TOOLS.find((x) => x.name === name);
+    if (!t) { console.error(`Unknown tool: ${name}. Try \`tool list\`.`); process.exit(2); }
+    console.log(`# ${t.name}\n`);
+    console.log(t.description || '(no description)');
+    console.log('\n## inputSchema\n');
+    console.log(JSON.stringify(t.inputSchema || {}, null, 2));
+    return;
+  }
+
+  // Dispatch path: sub is the tool name, argv[4] is the JSON args.
+  const name = sub;
+  const handler = HANDLERS[name];
+  if (!handler) { console.error(`Unknown tool: ${name}. Try \`tool list\`.`); process.exit(2); }
+
+  const jsonArgs = process.argv[4] || '{}';
+  let args;
+  try { args = JSON.parse(jsonArgs); }
+  catch (e) {
+    console.error(`tool ${name}: failed to parse JSON args (${e.message}). Pass a single quoted JSON string, e.g. '{"key":"value"}'.`);
+    process.exit(2);
+  }
+
+  try {
+    const ctx = buildCtx();
+    const result = await handler(args, ctx);
+    const text = result?.content?.[0]?.text;
+    if (typeof text === 'string') {
+      console.log(text);
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+    if (result?.isError) process.exit(1);
+  } catch (e) {
+    console.error(`tool ${name}: ${e.message}`);
+    process.exit(1);
+  }
+}
+
 function migrate() {
   const { migrate: runMigrate } = require('./auth/credentials');
   const confirm = process.argv.includes('--confirm');

package/src/clients/official/base.js

@@ -1,5 +1,5 @@
 const lark = require('@larksuiteoapi/node-sdk');
-const { fetchWithTimeout } = require('../../utils');
+const { fetchWithTimeout, LRUCache } = require('../../utils');
 const { stderrLogger } = require('../../logger');
 const uatLifecycle = require('../../auth/uat');
 
@@ -11,7 +11,13 @@ class LarkOfficialClient {
     this._uat = null;
     this._uatRefresh = null;
     this._uatExpires = 0;
-    this._userNameCache = new Map(); // open_id → display name
+    // v1.3.12: bounded caches with TTL. Pre-v1.3.12 these were plain Maps that
+    // grew without bound and never expired, so a week-old server would carry
+    // stale display names. 500 entries / 10min covers the common chat-volume
+    // working set without keeping cold entries forever.
+    this._userNameCache = new LRUCache({ max: 500, ttlMs: 600_000 }); // open_id → display name
+    this._appNameCache = new LRUCache({ max: 100, ttlMs: 600_000 });  // app_id (cli_xxx) → app name
+    this._selfTenantKey = null;      // populated lazily on first message read
   }
 
   // --- UAT (User Access Token) Management ---
@@ -109,20 +115,58 @@ class LarkOfficialClient {
   }
 
   async _populateSenderNames(items, userClient) {
-    // Collect unique sender IDs that aren't cached
-    const unknownIds = new Set();
+    // Step 0: harvest mention name data — Feishu IM API ships mentions[].name
+    // alongside each message body, so we get (id, name) pairs for any user
+    // who got @-mentioned without spending a contact API call.
     for (const item of items) {
-      if (item.senderId && !this._userNameCache.has(item.senderId)) {
-        unknownIds.add(item.senderId);
+      if (Array.isArray(item.mentions)) {
+        for (const m of item.mentions) {
+          if (m.id && m.name && !this._userNameCache.has(m.id)) {
+            this._userNameCache.set(m.id, m.name);
+          }
+        }
       }
     }
-    // Parallel resolve via official contact API (instead of sequential N calls)
-    if (unknownIds.size > 0) {
-      await Promise.allSettled([...unknownIds].map(id => this.getUserById(id)));
+
+    // Step 1: lazy-resolve our own tenant_key so we can flag isExternal senders.
+    if (this._selfTenantKey === null) {
+      await this._resolveSelfTenantKey().catch(() => {});
+    }
+
+    // Step 2: collect unique unknown user / app ids
+    const unknownUserIds = new Set();
+    const unknownAppIds = new Set();
+    for (const item of items) {
+      if (!item.senderId) continue;
+      if (item.senderType === 'app') {
+        if (!this._appNameCache.has(item.senderId)) unknownAppIds.add(item.senderId);
+      } else if (!this._userNameCache.has(item.senderId)) {
+        unknownUserIds.add(item.senderId);
+      }
+    }
+
+    // Step 3: parallel resolve users via contact API.
+    // v1.3.12: read result.status so failed lookups don't disappear silently.
+    // The 2026-05 incident had ~100% lookup failure for weeks (UAT revoked +
+    // tenant scope gap) and senderName=null without any breadcrumb in stderr.
+    if (unknownUserIds.size > 0) {
+      const userIds = [...unknownUserIds];
+      const results = await Promise.allSettled(userIds.map(id => this.getUserById(id)));
+      const failed = [];
+      for (let i = 0; i < results.length; i++) {
+        if (results[i].status === 'rejected') {
+          failed.push({ id: userIds[i], reason: results[i].reason?.message || String(results[i].reason) });
+        }
+      }
+      if (failed.length) {
+        const sample = failed.slice(0, 3).map(f => `${f.id}(${f.reason})`).join(', ');
+        const tail = failed.length > 3 ? ` (+${failed.length - 3} more)` : '';
+        console.error(`[feishu-user-plugin] sender name lookup failed for ${failed.length}/${userIds.length} ids: ${sample}${tail}`);
+      }
     }
-    // Fallback: resolve remaining unknowns via cookie-based user identity client
+    // Cookie fallback for any user still unknown
     if (userClient) {
-      for (const id of unknownIds) {
+      for (const id of unknownUserIds) {
         if (!this._userNameCache.has(id)) {
           try {
             const name = await userClient.getUserName(id);
@@ -131,12 +175,114 @@ class LarkOfficialClient {
         }
       }
     }
-    // Populate senderName field
+    // Parallel resolve apps (best-effort; usually only self-app appears).
+    // v1.3.12: same Promise.allSettled status-reading fix as the user path.
+    if (unknownAppIds.size > 0) {
+      const appIds = [...unknownAppIds];
+      const results = await Promise.allSettled(appIds.map(id => this.getAppName(id)));
+      const failed = [];
+      for (let i = 0; i < results.length; i++) {
+        if (results[i].status === 'rejected') {
+          failed.push({ id: appIds[i], reason: results[i].reason?.message || String(results[i].reason) });
+        }
+      }
+      if (failed.length) {
+        const sample = failed.slice(0, 3).map(f => `${f.id}(${f.reason})`).join(', ');
+        const tail = failed.length > 3 ? ` (+${failed.length - 3} more)` : '';
+        console.error(`[feishu-user-plugin] app name lookup failed for ${failed.length}/${appIds.length} ids: ${sample}${tail}`);
+      }
+    }
+
+    // v1.3.12 negative cache: any id we tried to resolve but couldn't gets
+    // a null sentinel under the same LRU+TTL. The 10-min TTL on the cache
+    // gives renamed / newly-joined users a re-resolution window without
+    // dispatching N redundant API calls per read_messages on hot chats.
+    // has(id)==true / get(id)==null lets _computeDisplayLabel fall back to
+    // "(open_id)" exactly the same way as before.
+    //
+    // PR #103 Copilot followup: getUserById / getAppName return null on
+    // non-zero Feishu codes (e.g. 99991672, scope missing) WITHOUT rejecting,
+    // so the per-batch Promise.allSettled rejection log misses these. Log
+    // the ids that ended without a name as a separate stderr line so failure
+    // shape is observable regardless of whether the underlying lookup
+    // returned null or rejected.
+    const unresolvedUserIds = [];
+    for (const id of unknownUserIds) {
+      if (!this._userNameCache.has(id) || this._userNameCache.get(id) === null) {
+        this._userNameCache.set(id, null);
+        unresolvedUserIds.push(id);
+      }
+    }
+    if (unresolvedUserIds.length) {
+      const sample = unresolvedUserIds.slice(0, 5).join(', ');
+      const tail = unresolvedUserIds.length > 5 ? ` (+${unresolvedUserIds.length - 5} more)` : '';
+      console.error(`[feishu-user-plugin] sender name unresolved (cached null) for ${unresolvedUserIds.length} id(s): ${sample}${tail}`);
+    }
+    const unresolvedAppIds = [];
+    for (const id of unknownAppIds) {
+      if (!this._appNameCache.has(id) || this._appNameCache.get(id) === null) {
+        this._appNameCache.set(id, null);
+        unresolvedAppIds.push(id);
+      }
+    }
+    if (unresolvedAppIds.length) {
+      const sample = unresolvedAppIds.slice(0, 5).join(', ');
+      const tail = unresolvedAppIds.length > 5 ? ` (+${unresolvedAppIds.length - 5} more)` : '';
+      console.error(`[feishu-user-plugin] app name unresolved (cached null) for ${unresolvedAppIds.length} id(s): ${sample}${tail}`);
+    }
+
+    // Step 4: populate senderName, isExternal, displayLabel
     for (const item of items) {
-      if (item.senderId) {
-        item.senderName = this._userNameCache.get(item.senderId) || null;
+      item.senderName = item.senderId ? (this._userNameCache.get(item.senderId) || null) : null;
+      if (this._selfTenantKey && item.senderTenantKey && item.senderTenantKey !== this._selfTenantKey) {
+        item.isExternal = true;
+      }
+      item.displayLabel = this._computeDisplayLabel(item);
+    }
+  }
+
+  _computeDisplayLabel(item) {
+    const prefix = item.isRecalled ? '[已撤回] ' : '';
+    if (!item.senderId) return prefix + '[系统]';
+    if (item.senderType === 'anonymous') return prefix + '[匿名]';
+    if (item.senderType === 'app') {
+      const appName = this._appNameCache.get(item.senderId);
+      return prefix + `[Bot] ${appName || `(${item.senderId})`}`;
+    }
+    return prefix + (item.senderName || `(${item.senderId})`);
+  }
+
+  async getAppName(appId) {
+    if (this._appNameCache.has(appId)) return this._appNameCache.get(appId);
+    try {
+      const token = await this._getAppToken();
+      const res = await fetchWithTimeout(
+        `https://open.feishu.cn/open-apis/application/v6/applications/${encodeURIComponent(appId)}?lang=zh_cn`,
+        { headers: { 'Authorization': `Bearer ${token}` }, timeoutMs: 10000 },
+      );
+      const data = await res.json();
+      const name = data?.data?.app?.app_name;
+      if (name) {
+        this._appNameCache.set(appId, name);
+        return name;
       }
+    } catch {
+      // best-effort; null means "couldn't resolve, fall back to id"
     }
+    return null;
+  }
+
+  async _resolveSelfTenantKey() {
+    if (this._selfTenantKey) return this._selfTenantKey;
+    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: this.appId, app_secret: this.appSecret }),
+      timeoutMs: 10000,
+    });
+    const data = await res.json();
+    if (data?.tenant_key) this._selfTenantKey = data.tenant_key;
+    return this._selfTenantKey;
   }
 
   // --- Helpers ---
@@ -145,6 +291,10 @@ class LarkOfficialClient {
     if (!m) return null;
     let body = m.body?.content || '';
     try { body = JSON.parse(body); } catch {}
+    // Feishu signals recall by replacing body content with the literal string
+    // "This message was recalled" (not a JSON object). Surface as boolean so
+    // the LLM doesn't have to pattern-match the string.
+    const isRecalled = (typeof body === 'string' && /recalled/i.test(body));
     const out = {
       messageId: m.message_id,
       chatId: m.chat_id,
@@ -155,6 +305,12 @@ class LarkOfficialClient {
       createTime: this._normalizeTimestamp(m.create_time),
       updateTime: this._normalizeTimestamp(m.update_time),
     };
+    // Raw sender metadata — LLM may need id_type (to pick the right
+    // user_id_type for contact API) or tenant_key (to know cross-tenant).
+    if (m.sender?.id_type) out.senderIdType = m.sender.id_type;
+    if (m.sender?.tenant_key) out.senderTenantKey = m.sender.tenant_key;
+    if (isRecalled) out.isRecalled = true;
+    if (m.parent_id) out.isThreadReply = true;
     if (Array.isArray(m.mentions) && m.mentions.length > 0) out.mentions = m.mentions;
     if (m.upper_message_id) out.upperMessageId = m.upper_message_id;
     if (m.root_id) out.rootId = m.root_id;

package/src/clients/official/calendar.js

@@ -68,7 +68,9 @@ module.exports = {
   },
 
   // --- Calendar write (v1.3.7) ---
-  // Requires `calendar:calendar.event:write` scope on app + UAT.
+  // Requires the 4 verb-specific scopes on app + UAT:
+  //   calendar:calendar.event:create / update / delete / reply
+  // Feishu has no umbrella `:write` scope — using it 422-rejects OAuth.
 
   async createCalendarEvent(calendarId, eventData) {
     if (!calendarId) throw new Error('createCalendarEvent: calendarId is required');

package/src/clients/official/im.js

@@ -329,6 +329,22 @@ module.exports = {
       return f;
     });
     await this._populateSenderNames(children, userClient);
+    // Best-effort: surface the origin chat NAME for each child so the LLM doesn't
+    // misread the children as native messages of the current chat. A single
+    // merge_forward usually has 1 origin chat → 1 API call. Failures are silent
+    // (bot may not be in the origin chat) and the field is simply absent.
+    const originChatIds = [...new Set(children.map(c => c.originChatId).filter(Boolean))];
+    const chatNameMap = new Map();
+    await Promise.allSettled(originChatIds.map(async (cid) => {
+      try {
+        const info = await this.getChatInfo(cid);
+        if (info?.name) chatNameMap.set(cid, info.name);
+      } catch {}
+    }));
+    for (const c of children) {
+      const name = c.originChatId && chatNameMap.get(c.originChatId);
+      if (name) c.forwardedFromChatName = name;
+    }
     return children;
   },
 
@@ -366,7 +382,10 @@ module.exports = {
   //
   // Throws a single, wrapped error if BOTH paths fail or if UAT is absent and
   // the bot failed; the message points the user at `npx feishu-user-plugin oauth`.
-  async readMessagesWithFallback(chatId, options, userClient, { skipBot = false, via = 'bot' } = {}) {
+  async readMessagesWithFallback(chatId, options, userClient, { skipBot = false, skipUat = false, via = 'bot' } = {}) {
+    if (skipBot && skipUat) {
+      throw new Error('readMessagesWithFallback: cannot set both skipBot and skipUat — at least one identity path must be allowed');
+    }
     const tryUAT = async (viaLabel, reason) => {
       if (!this.hasUAT) {
         const hint = 'To read external / private groups, configure UAT via: npx feishu-user-plugin oauth';
@@ -381,7 +400,16 @@ module.exports = {
     };
 
     if (skipBot) {
-      return tryUAT(via || 'contacts', 'contacts_resolved_external');
+      // Two reasons we skipBot:
+      //   Path B (im-read.js): via='contacts' — chat was found only via
+      //   cookie search_contacts, bot definitely can't see it. Reason
+      //   field surfaces this to the LLM as "contacts_resolved_external".
+      //   v1.3.12 via_user=true: caller explicitly opted for UAT. No
+      //   failure happened; no reason needed.
+      if (via === 'contacts') {
+        return tryUAT('contacts', 'contacts_resolved_external');
+      }
+      return tryUAT(via && via !== 'bot' ? via : 'user');
     }
 
     // Attempt 1 — bot identity.
@@ -406,9 +434,55 @@ module.exports = {
         }
       }
 
+      // v1.3.12: when caller passes via_user=false (skipUat=true), surface
+      // the bot error instead of silently falling through to UAT. The user
+      // explicitly opted out of cross-identity fallback.
+      if (skipUat) {
+        throw new Error(`Bot path failed and via_user=false specified: ${botErr.message}`);
+      }
       // Fall through to UAT — if UAT is missing, tryUAT throws the user-friendly
       // "run npx feishu-user-plugin oauth" error instead of the raw Feishu payload.
       return tryUAT('user', klass.reason);
     }
   },
+
+  // --- Message search (v1.3.12, B.5) ---
+  //
+  // Wraps POST /open-apis/search/v2/message. UAT-only (Feishu doesn't expose
+  // bot path; probed 2026-05-15 — bot returns 99991668 "user access token not
+  // support"). Requires the `search:message` OAuth scope; without it the API
+  // returns 99991679 (permission_violations.subject="search:message"). Caller
+  // should re-run `npx feishu-user-plugin oauth` after adding the scope.
+  //
+  // Returns the raw shape from Feishu: { items: [{ message_id, ... }], page_token, has_more }.
+  // Items are message-id pointers — call read_messages / read_p2p_messages
+  // with the parent chat_id to fetch full bodies if needed.
+  async searchMessages({ query, fromIds, chatIds, messageTypes, atUserIds, fromTypes, pageSize = 20, pageToken } = {}) {
+    if (!query || typeof query !== 'string') {
+      throw new Error('searchMessages: query (search keyword string) is required');
+    }
+    if (!this.hasUAT) {
+      throw new Error('search_messages requires UAT (Feishu does not expose a bot-path search). Run: npx feishu-user-plugin oauth');
+    }
+    const body = { query };
+    if (pageSize) body.page_size = pageSize;
+    if (pageToken) body.page_token = pageToken;
+    if (Array.isArray(fromIds) && fromIds.length) body.from_ids = fromIds;
+    if (Array.isArray(chatIds) && chatIds.length) body.chat_ids = chatIds;
+    if (Array.isArray(messageTypes) && messageTypes.length) body.message_type_list = messageTypes;
+    if (Array.isArray(atUserIds) && atUserIds.length) body.at_chatter_ids = atUserIds;
+    if (Array.isArray(fromTypes) && fromTypes.length) body.from_types = fromTypes;
+    const data = await this._uatREST('POST', '/open-apis/search/v2/message', { body });
+    if (data.code === 99991679) {
+      throw new Error(`search_messages: UAT lacks the search:message scope. Re-run \`npx feishu-user-plugin oauth\` after the v1.3.12 SCOPES update.`);
+    }
+    if (data.code !== 0) {
+      throw new Error(`search_messages failed (code=${data.code}): ${data.msg}`);
+    }
+    return {
+      items: data.data?.items || [],
+      pageToken: data.data?.page_token || null,
+      hasMore: !!data.data?.has_more,
+    };
+  },
 };

package/src/clients/official/okr.js

@@ -57,7 +57,8 @@ module.exports = {
   },
 
   // --- OKR progress record write (v1.3.7) ---
-  // Requires `okr:okr.content:write` (or wider okr:okr) on the OAuth.
+  // Requires `okr:okr.content:writeonly` (or wider okr:okr) on the OAuth.
+  // Note: Feishu uses `:writeonly` (one word), not `:write`.
 
   async createOkrProgressRecord({ targetId, targetType, content, sourceTitle, sourceUrl, sourceUrlPc, sourceUrlMobile, progressRate, userIdType = 'open_id' }) {
     if (!targetId) throw new Error('createOkrProgressRecord: target_id is required (the key_result_id or objective_id)');

package/src/error-codes.js

@@ -26,6 +26,28 @@ const FAILURE_MAP = {
   // Chat does not exist (from the bot's POV — may still be accessible to user).
   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
+  // 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
+  // fallback caller would route to UAT once and surface revocation.
+  20064: { action: 'uat', reason: 'uat_revoked' },
+  // Cross-tenant bot block — bot lives in tenant A, target resource is in
+  // tenant B. Will never be granted. Distinct from 240001 (which is the
+  // older code form for the same shape); both surface in production.
+  91403: { action: 'uat', reason: 'bot_cross_tenant' },
+
+  // Upload pipeline transient errors — the Feishu upload gateway is
+  // intermittently flaky; one retry after a moment usually clears.
+  // 1254000 / 1254001 are generic upload failures, 1254301 is multipart
+  // size mismatch (rare race when the body is being computed concurrently),
+  // 1254400 is "upload service busy" the gateway returns under load.
+  1254000: { action: 'retry', reason: 'upload_transient' },
+  1254001: { action: 'retry', reason: 'upload_transient' },
+  1254301: { action: 'retry', reason: 'upload_transient' },
+  1254400: { action: 'retry', reason: 'upload_transient' },
+
   // Rate limited — Feishu throttles, try once more after a brief pause.
   42101:  { action: 'retry', reason: 'bot_rate_limited' },
   // Frequency control variants occasionally observed.
@@ -41,8 +63,21 @@ const TRANSIENT_PATTERNS = [
   /ETIMEDOUT/i,
   /fetch timeout after/i, // from utils.fetchWithTimeout
   /socket hang up/i,
+  /Unexpected end of JSON input/i,
+  /Unexpected token .* in JSON/i,
 ];
 
+// Recognise res.json() parse failures so withUAT widens retry to them too.
+// The Feishu gateway occasionally returns a truncated body that crashes
+// JSON.parse — classifying the SyntaxError as transient lets the wrapper
+// recover with a single retry instead of bubbling a cryptic parse error.
+function _isJsonParseError(err) {
+  if (!err) return false;
+  if (err.name === 'SyntaxError') return true;
+  const msg = err.message || '';
+  return /Unexpected end of JSON input/i.test(msg) || /Unexpected token .* in JSON/i.test(msg);
+}
+
 /**
  * Classify an error thrown by a bot-API path.
  * Input is either the Feishu code number (preferred) or the Error object —
@@ -65,6 +100,11 @@ function classifyError(errOrCode) {
   if (code != null && FAILURE_MAP[code]) {
     return { ...FAILURE_MAP[code], code };
   }
+  // res.json() parse failures get a dedicated reason so logs disambiguate
+  // them from generic network flakes (different remediation in monitoring).
+  if (errOrCode && typeof errOrCode === 'object' && _isJsonParseError(errOrCode)) {
+    return { action: 'retry', reason: 'response_parse_error', code };
+  }
   for (const re of TRANSIENT_PATTERNS) {
     if (re.test(msg)) return { action: 'retry', reason: 'bot_network_error', code };
   }

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);