cc-viewer 1.6.345 → 1.7.0

package/server/lib/adapters/dingtalk-adapter.js

@@ -179,21 +179,35 @@ const dingtalkAdapter = {
 
   async connect(cfg, hooks) {
     let client;
+    // keepAlive is required for silent-drop detection: without it the SDK never pings, so a
+    // network loss with no FIN leaves the socket "open" and `client.connected` true forever.
+    // Known SDK quirk: dingtalk-stream arms a new heartbeat interval on every socket 'open'
+    // without clearing the previous one, so each reconnect leaks one 8s interval (bounded by
+    // reconnect count; disconnect() clears the last). Accepted — detection matters more.
+    const opts = { clientId: cfg.appKey, clientSecret: cfg.appSecret, keepAlive: true };
     if (clientFactory) {
-      client = clientFactory({ clientId: cfg.appKey, clientSecret: cfg.appSecret });
+      client = clientFactory(opts);
       if (typeof client.registerCallbackListener === 'function') {
         client.registerCallbackListener('__test__', (res) => hooks.onInbound(normalizeInbound(res), res));
       }
     } else {
       const mod = await import('dingtalk-stream');
       const { DWClient, TOPIC_ROBOT } = mod;
-      client = new DWClient({ clientId: cfg.appKey, clientSecret: cfg.appSecret });
+      client = new DWClient(opts);
       client.registerCallbackListener(TOPIC_ROBOT, (res) => hooks.onInbound(normalizeInbound(res), res));
     }
     await client.connect?.();
     return client;
   },
 
+  // dingtalk-stream emits no client-level lifecycle events (open/close/error live on an internal
+  // ws that is replaced on every reconnect), so the core polls this instead. `userDisconnect` is
+  // TS-private but a plain runtime field; it flips true only on manual disconnect().
+  connectionProbe(client) {
+    if (!client || client.userDisconnect) return 'disconnected';
+    return client.connected ? 'connected' : 'reconnecting';
+  },
+
   async disconnect(client) {
     try { await client?.disconnect?.(); } catch { /* best-effort */ }
   },

package/server/lib/adapters/discord-adapter.js

@@ -80,10 +80,21 @@ const discordAdapter = {
     });
     ctx.store.client = client;
     // Persistent error listener for the life of the client: a Node EventEmitter that emits 'error'
-    // with NO listener throws and crashes the process. The connect-window once('error') below is
-    // consumed on resolve, so without this a later gateway 'error' would be fatal. Swallow (the
-    // gateway auto-reconnects; connection state surfaces via the bridge status).
-    client.on('error', () => { /* swallowed — see comment */ });
+    // with NO listener throws and crashes the process. NOTE: the connect-window once('error') below
+    // is NOT consumed by a successful ClientReady resolve — it survives and must therefore be a
+    // settled-guarded no-op post-connect (see below). Record errors as lastError here (state flips
+    // come from the shard lifecycle events below; the gateway auto-reconnects).
+    client.on('error', (e) => hooks.onConnectionChange?.(null, e));
+    // Shard lifecycle → core tri-state. Single unsharded gateway = one shard, so no per-shard map.
+    // Events?.X ?? 'literal' keeps test fakes (whose Events map lacks shard constants) working.
+    client.on(Events?.ShardReconnecting ?? 'shardReconnecting', () => hooks.onConnectionChange?.('reconnecting'));
+    client.on(Events?.ShardResume ?? 'shardResume', () => hooks.onConnectionChange?.('connected'));
+    client.on(Events?.ShardReady ?? 'shardReady', () => hooks.onConnectionChange?.('connected'));
+    client.on(Events?.ShardDisconnect ?? 'shardDisconnect', (ev) =>
+      hooks.onConnectionChange?.('disconnected', new Error(`gateway closed (code ${ev?.code ?? 'unknown'})`)));
+    client.on(Events?.Invalidated ?? 'invalidated', () =>
+      hooks.onConnectionChange?.('disconnected', new Error('session invalidated')));
+    client.on(Events?.ShardError ?? 'shardError', (e) => hooks.onConnectionChange?.(null, e));
     client.on(Events.MessageCreate, (message) => {
       // Loop-guard: ignore the bot's own messages (Discord redelivers our send as a new event) and
       // all other bots. author.bot covers self; the id check is belt-and-suspenders.
@@ -98,8 +109,19 @@ const discordAdapter = {
       const timer = setTimeout(() => { try { client.destroy(); } catch { /* best-effort */ } finish(reject, new Error('connect timeout')); }, CONNECT_PROBE_MS);
       if (typeof timer.unref === 'function') timer.unref();
       client.once(Events.ClientReady, () => finish(resolve, client));
-      client.once('error', (e) => { try { client.destroy(); } catch { /* best-effort */ } finish(reject, new Error(String(e?.message || e))); });
-      client.login(cfg.botToken).catch((e) => { try { client.destroy(); } catch { /* best-effort */ } finish(reject, new Error(String(e?.message || e))); });
+      // Guard the destroy behind `settled`: this once-listener is NOT consumed by ClientReady, so
+      // an unguarded destroy would kill the LIVE client on the first post-connect 'error' event
+      // (freezing the bridge with no reconnect — the exact stale-status bug this adapter fixes).
+      client.once('error', (e) => {
+        if (settled) return; // post-connect errors are handled by the persistent listener above
+        try { client.destroy(); } catch { /* best-effort */ }
+        finish(reject, new Error(String(e?.message || e)));
+      });
+      client.login(cfg.botToken).catch((e) => {
+        if (settled) return;
+        try { client.destroy(); } catch { /* best-effort */ }
+        finish(reject, new Error(String(e?.message || e)));
+      });
     });
   },
 

package/server/lib/adapters/feishu-adapter.js

@@ -18,6 +18,10 @@ import { registerAdapter } from '../im-bridge-core.js';
 let sdkFactory = null;
 export function __setClientFactory(fn) { sdkFactory = fn; }
 
+// Internal connect guard (< core CONNECT_TIMEOUT_MS): bounds the onReady wait on hook-capable SDK
+// builds so a misconfigured app fails with lastError instead of leaking a background retry loop.
+const CONNECT_PROBE_MS = 12_000;
+
 const TOKEN_PATH = '/open-apis/auth/v3/tenant_access_token/internal';
 function tokenHost(region) {
   return region === 'lark' ? 'https://open.larksuite.com' : 'https://open.feishu.cn';
@@ -90,17 +94,59 @@ const feishuAdapter = {
     const base = { appId: cfg.appId, appSecret: cfg.appSecret, domain };
     // Outbound client (auto-manages the tenant_access_token cache).
     ctx.store.sendClient = new Lark.Client(base);
-    // Inbound long-connection event client. wsConfig is REQUIRED — omitting PingInterval/PingTimeout
-    // makes start() throw or hang on some SDK builds.
+    let settled = false;
+    let resolveReady, rejectReady;
+    const ready = new Promise((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });
+    ready.catch(() => {}); // detached guard: a pre-await rejection must not raise unhandledRejection
+    // Inbound long-connection event client. wsConfig keys per SDK build: 1.66.0 reads ONLY the
+    // lowercase `pingTimeout` (seconds) — it arms the pong/liveness watchdog that terminates a
+    // zombie socket after a SILENT network drop (NAT idle, sleep, no FIN) and triggers reconnect;
+    // without it such drops are never detected. The capitalized PingInterval/PingTimeout keys are
+    // kept for older builds that read them (1.66.0 ignores unknown keys, so both are safe).
     const ws = new Lark.WSClient({
       ...base,
       loggerLevel: Lark.LoggerLevel ? Lark.LoggerLevel.warn : undefined, // warn: avoid noisy info-level stdout
-      wsConfig: { PingInterval: 30, PingTimeout: 5 },
+      wsConfig: { PingInterval: 30, PingTimeout: 5, pingTimeout: 5 },
+      // Lifecycle hooks ship with newer SDK builds (present in the installed 1.66.0); an older
+      // build silently ignores unknown ctor options, so wiring them is always safe.
+      onReady: () => {
+        if (settled) { hooks.onConnectionChange?.('connected'); return; }
+        settled = true; resolveReady();
+      },
+      onReconnecting: () => hooks.onConnectionChange?.('reconnecting'),
+      onReconnected: () => hooks.onConnectionChange?.('connected'),
+      onError: (err) => {
+        if (settled) { hooks.onConnectionChange?.('disconnected', err); return; }
+        settled = true; rejectReady(err instanceof Error ? err : new Error(String(err?.message || err)));
+      },
     });
     const dispatcher = new Lark.EventDispatcher({}).register({
       'im.message.receive_v1': async (data) => hooks.onInbound(normalizeInbound(data), null),
     });
-    await ws.start({ eventDispatcher: dispatcher });
+    if (typeof ws.getConnectionStatus === 'function') {
+      // Hook-capable build (feature-detected): start() resolves before the handshake completes,
+      // so gate on onReady/onError; bound with an internal timeout below the core's connect race.
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        rejectReady(new Error('connect timeout'));
+      }, CONNECT_PROBE_MS);
+      if (typeof timer.unref === 'function') timer.unref();
+      try {
+        await ws.start({ eventDispatcher: dispatcher });
+        await ready;
+      } catch (e) {
+        // Stop the SDK's background retry loop so a failed connect doesn't leak.
+        try { await ws.close?.({}); } catch { /* best-effort */ }
+        throw e;
+      } finally {
+        clearTimeout(timer);
+      }
+    } else {
+      // Older SDK (and legacy test fakes): original behavior — start() is trusted, no
+      // lifecycle hooks fire, connection state stays start/stop-driven.
+      await ws.start({ eventDispatcher: dispatcher });
+    }
     return ws;
   },
 

package/server/lib/adapters/wecom-adapter.js

@@ -75,6 +75,30 @@ const wecomAdapter = {
     const client = new WSClient({ botId: cfg.botId, secret: cfg.secret });
     ctx.store.client = client; // single client for inbound + outbound (sendOne reads it)
     client.on('message.text', (frame) => hooks.onInbound(normalizeInbound(frame), null));
+    // Persistent lifecycle listeners → core tri-state. Registered up front (pre-connect emits are
+    // ignored by the core while not running); removed by disconnect()'s removeAllListeners.
+    // NOTE: one connection per bot — running testConnection against the SAME bot kicks the live
+    // bridge via disconnected_event, which the SDK treats as TERMINAL (isManualClose, no
+    // reconnect). The status will correctly show Disconnected until the bridge is restarted;
+    // auto-restart-after-test is a deliberate non-goal for now (backlog).
+    let kicked = false;
+    client.on('event.disconnected_event', () => {
+      // Server kicked this connection (a new one took over): the SDK sets isManualClose and will
+      // NOT reconnect, so this is terminal; the 'disconnected' emit that follows must not
+      // downgrade it to reconnecting.
+      kicked = true;
+      hooks.onConnectionChange?.('disconnected', new Error('kicked: new connection established'));
+    });
+    client.on('disconnected', (reason) => {
+      if (!kicked) hooks.onConnectionChange?.('reconnecting', reason ? new Error(String(reason)) : null);
+    });
+    client.on('reconnecting', () => hooks.onConnectionChange?.('reconnecting'));
+    client.on('authenticated', () => { kicked = false; hooks.onConnectionChange?.('connected'); });
+    client.on('error', (e) => {
+      const terminal = e?.name === 'WSReconnectExhaustedError' || e?.name === 'WSAuthFailureError'
+        || e?.code === 'WS_RECONNECT_EXHAUSTED';
+      hooks.onConnectionChange?.(terminal ? 'disconnected' : null, e);
+    });
     // connect() is synchronous; resolve once the WS handshake authenticates so the core's
     // `connected` flag and CONNECT_TIMEOUT_MS race are meaningful (bad creds → lastError, not a
     // false "connected"). Reject (and tear down) on error or an internal timeout.

package/server/lib/async-write-queue.js

@@ -36,8 +36,19 @@ export class AsyncWriteQueue {
   get pendingBytes() { return this._pendingBytes; }
 
   append(data, onDone) {
+    return this.appendTo(this._getPath(), data, onDone);
+  }
+
+  /**
+   * Explicit-path variant (wire-v2 S2): same queue, same ordering/drain
+   * machinery, caller supplies the target file. Within one drain batch, path
+   * groups are written in first-enqueue order, so a caller enqueuing
+   * conversation lines before the journal line keeps that relative order on
+   * disk (WIRE_FORMAT_V2.md §1.3 write-order protocol). Empty/falsy path stays
+   * a silent no-op — workspace mode and leaderless teammates rely on it.
+   */
+  appendTo(path, data, onDone) {
     if (this._closed) return;
-    const path = this._getPath();
     if (!path) {
       if (onDone) try { onDone(); } catch {}
       return;

package/server/lib/create_system_prompt.js

@@ -7,7 +7,7 @@
 //   node server/lib/create_system_prompt.js deepseek-v4-pro # a named preset
 //   node server/lib/create_system_prompt.js --list          # list presets
 
-import { execFileSync } from 'node:child_process'
+import { spawnSync } from 'node:child_process'
 import { readFileSync, statSync } from 'node:fs'
 import os from 'node:os'
 import { delimiter, join, sep } from 'node:path'
@@ -54,13 +54,16 @@ function envString(name) {
 }
 
 function commandOutput(command, args, cwd) {
-  return stringOrEmpty(() =>
-    execFileSync(command, args, {
+  return stringOrEmpty(() => {
+    const result = spawnSync(command, args, {
       cwd,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim(),
-  )
+      timeout: 15000, // 15s hard cap: hanging git (NFS / huge repo / broken index) must not block spawn
+    })
+    if (result.error || result.status !== 0) return ''
+    return result.stdout.trim()
+  })
 }
 
 function firstNonEmpty(...values) {
@@ -130,8 +133,11 @@ function resolveMemory(home, cwd) {
   return { dir, index, enabled: enabled ? 'true' : 'false' }
 }
 
-export function createSystemPromptVariables(overrides = {}) {
-  const cwd = stringOrEmpty(() => process.cwd())
+export function createSystemPromptVariables(overrides = {}, opts = {}) {
+  // opts.cwd: resolve cwd-dependent variables (environment.cwd, git.*, memory.dir) against a
+  // caller-supplied directory instead of process.cwd() — the spawn-time renderer passes the
+  // workspace being launched, which is not necessarily where the ccv server itself runs.
+  const cwd = (typeof opts.cwd === 'string' && opts.cwd) ? opts.cwd : stringOrEmpty(() => process.cwd())
   const now = new Date()
   const timeZone = stringOrEmpty(
     () => Intl.DateTimeFormat().resolvedOptions().timeZone,

package/server/lib/delta-reconstructor.js

@@ -88,7 +88,7 @@ function _seqGuardCheck(entry, st) {
 /**
  * 标记乱序条目并尽量就地补偿：accumulated 已包含更新的真值时，用其前缀
  * （= 截至该条目声称长度的最新内容）回填 body.messages，避免裸 delta 切片
- * 残留在请求详情面板 / mergeLogFiles 落盘产物中。
+ * 残留在请求详情面板中。
  * 返回 true 表示已补偿（messages 为一致全量），false 表示需后续 checkpoint 补偿。
  */
 function _markStaleEntry(entry, accumulated) {
@@ -142,7 +142,7 @@ function _integrityCheck(entry, accumulated, st) {
  * 2. 真值前缀 —— stale 就地补偿、超长 slice 修复（_staleReorder 置位，merge 跳过）；
  * 3. 裸 delta 切片待补偿 —— stale 就地补偿失败 / poisoned 冻结（_staleReorder 或
  *    _reconstructBroken 置位）：由第二遍 checkpoint 补偿回填，无第二遍的路径靠
- *    isMergeBlockedEntry 阻断 merge、mergeLogFiles 丢弃兜底。
+ *    isMergeBlockedEntry 阻断 merge 兜底。
  *
  * @param {object} entry - 单条日志条目（原地修改）
  * @param {{accumulated: Array, intState: {baselineSeen: boolean, poisoned: boolean},
@@ -239,7 +239,7 @@ export function reconstructEntries(entries) {
 
 /**
  * 用候选全量条目（checkpoint/旧格式，排除 teammate）补偿一条断裂条目。
- * 内容已是真值前缀，清除标记让批量 merge / mergeLogFiles 正常消费。
+ * 内容已是真值前缀，清除标记让批量 merge 正常消费。
  * @returns {boolean} true = 已补偿
  */
 function _tryRepairFromCandidate(brokenEntry, expectedCount, candidate) {

package/server/lib/error-report.js

@@ -0,0 +1,45 @@
+// CLIENT-SAFE: no node deps. Imported by src/ — do not add fs/process/node: imports.
+/**
+ * Error-reporting convention for swallowed catch blocks.
+ *
+ * Canonical home since wire-v2 S2 (moved verbatim from src/utils/errorReport.js,
+ * which remains as a re-export shell): server/lib/v2/* writers follow the same
+ * convention, and src/ is not shipped in the npm package.
+ *
+ * The rule (see CLAUDE.md): a `catch` whose failure has diagnostic value —
+ * anything where a throw means lost data or broken UI (SSE/WS event parsing,
+ * entry ingest, state updates, fetch response handling) — must call
+ * `reportSwallowed(tag, err)` instead of swallowing silently. Purely-benign
+ * best-effort guards (localStorage get/set, tabBridge IPC, revokeObjectURL,
+ * listener-cleanup `off()`) stay bare `catch {}`.
+ *
+ * Tag grammar: `<channel>.<event-name-verbatim>`, e.g. `sse.load_chunk`,
+ * `sse.stream-progress`, `ws.terminal-msg`. Keep the event name exactly as it
+ * appears in the code/protocol so a grep for the tag round-trips to the site.
+ * All reports share the greppable `[ccv:` console prefix.
+ *
+ * Dedup: identical failures usually repeat (e.g. every SSE event of a changed
+ * payload shape fails the same way), so each tag logs at most
+ * MAX_REPORTS_PER_TAG occurrences per session, then one suppression notice,
+ * then goes silent. Counter-based on purpose — no Date/timers, so this module
+ * is statically loadable and deterministic under `node --test`.
+ */
+export const MAX_REPORTS_PER_TAG = 5;
+
+const _counts = new Map();
+
+export function reportSwallowed(tag, err, extra) {
+  const n = (_counts.get(tag) || 0) + 1;
+  _counts.set(tag, n);
+  if (n > MAX_REPORTS_PER_TAG + 1) return;
+  if (n === MAX_REPORTS_PER_TAG + 1) {
+    console.warn(`[ccv:${tag}] further occurrences suppressed`);
+    return;
+  }
+  if (extra !== undefined) console.warn(`[ccv:${tag}]`, err, extra);
+  else console.warn(`[ccv:${tag}]`, err);
+}
+
+export function _resetForTest() {
+  _counts.clear();
+}

package/server/lib/im-bridge-core.js

@@ -43,6 +43,10 @@ const STREAM_MIN_DELTA = 20;             // 累计增长达 20 字才推一帧
 const STREAM_MAX_FRAMES = 25;            // 每回合中途流式帧硬上限；超限停推，finalize 仍落全文
 const STREAM_MAX_CHARS = 20_000;         // 卡片内容字符上限，超出截断
 
+// Poll interval for adapters that expose connectionProbe() instead of lifecycle events
+// (dingtalk-stream replaces its internal ws on every reconnect, so no listener survives).
+let CONN_POLL_MS = 5_000;
+
 // ─── registry + core-global single-flight ───
 const instances = new Map();             // platformId → instance
 let activeInjection = null;              // { platformId, since, target } — the one in-flight turn
@@ -61,6 +65,9 @@ function newInstance(adapter) {
     client: null,
     running: false,
     connected: false,
+    connectionState: 'disconnected',      // 'connected' | 'reconnecting' | 'disconnected'; invariant: connected === (connectionState === 'connected')
+    startGen: 0,                          // generation counter; stale adapter listeners from a previous start are ignored
+    connPollTimer: null,                  // fallback poll timer for adapters exposing connectionProbe()
     lastError: null,
     bridgeDeps: null,
     boundConversation: null,
@@ -88,9 +95,15 @@ function newInstance(adapter) {
  * @property {Object}  [capabilities]  Informational flags ({inboundAck, sdkManagesToken}); not read by the core.
  * @property {(cfg:Object)=>boolean}  hasCreds        True when cfg carries enough creds to connect.
  * @property {(cfg:Object)=>Object}   [statusFields]  Extra non-secret status fields for the admin API.
- * @property {(cfg:Object, hooks:{onInbound:(normalized:Object, ackCtx:*)=>void}, ctx:{fetch,store})=>Promise<*>} connect
+ * @property {(cfg:Object, hooks:{onInbound:(normalized:Object, ackCtx:*)=>void, onConnectionChange?:(state:?string, err?:*)=>void}, ctx:{fetch,store})=>Promise<*>} connect
  *           Open the long connection; return the live client. Call hooks.onInbound(normalized, ackCtx)
  *           per inbound message, where normalized = {text, conversationId, senderId, msgId, target}.
+ *           Optionally call hooks.onConnectionChange?.(state, err) on transport lifecycle changes,
+ *           where state ∈ 'connected'|'reconnecting'|'disconnected', or null to record err only.
+ *           Always invoke it with optional chaining — callers (tests) may pass onInbound alone.
+ * @property {(client:*)=>('connected'|'reconnecting'|'disconnected')} [connectionProbe]
+ *           For SDKs without usable lifecycle events: derive the live connection state from the
+ *           client's fields. When present, the core polls it every CONN_POLL_MS while running.
  * @property {(client:*, ctx:{fetch,store})=>Promise<void>} [disconnect]  Tear down the client (best-effort).
  * @property {(ackCtx:*, client:*)=>void} [ack]  Ack an inbound msg (platforms that redeliver if not acked).
  * @property {(cfg:Object, target:Object, content:string, ctx:{fetch,store})=>Promise<void>} sendOne  Send one chunk.
@@ -320,6 +333,26 @@ function armActiveInjection(inst, target, since) {
   }
 }
 
+/**
+ * Transition the tri-state connection status. `gen` binds the caller to one startBridge lifetime,
+ * so a stale adapter listener firing after stopBridge/reloadBridge can never flip the state.
+ * state === null records the error only; identical consecutive states are no-ops (collapses
+ * SDK error/reconnect storms into single audited transitions).
+ */
+function setConnectionState(inst, gen, state, err) {
+  if (gen !== inst.startGen || !inst.running) return;
+  const errStr = err != null ? String(err?.message || err) : null;
+  if (errStr) inst.lastError = errStr;
+  if (state == null || state === inst.connectionState) return;
+  inst.connectionState = state;
+  inst.connected = state === 'connected';
+  // Recovery clears the retained disconnect cause — the UI ranks lastError above connected, so
+  // keeping it would leave the status stuck on "Error" after every transient drop. Deduped
+  // repeats and null-state calls don't clear, preserving send-failure diagnostics while healthy.
+  if (state === 'connected' && !errStr) inst.lastError = null;
+  audit(inst, 'connection', { state, ...(errStr ? { error: errStr } : {}) });
+}
+
 // ─── small helpers ───
 function audit(inst, event, data) {
   try {
@@ -711,21 +744,45 @@ export async function startBridge(id, deps) {
   if (!inst.bridgeDeps || typeof inst.bridgeDeps.getConfig !== 'function') { audit(inst, 'start-skipped', { reason: 'no-deps' }); return; }
   const cfg = inst.bridgeDeps.getConfig();
   if (!cfg || !cfg.enabled || !inst.adapter.hasCreds(cfg)) return; // off / incomplete → no-op
+  // Bump AFTER the early-return guards: startBridge on an already-running instance is a legal
+  // no-op, and bumping there would orphan the live adapter's listeners (state frozen forever).
+  const gen = ++inst.startGen;
   try {
-    const hooks = { onInbound: (normalized, ackCtx) => handleInbound(inst, normalized, ackCtx) };
+    const hooks = {
+      onInbound: (normalized, ackCtx) => handleInbound(inst, normalized, ackCtx),
+      onConnectionChange: (state, err) => setConnectionState(inst, gen, state, err),
+    };
     // Bound the connect so a hung adapter (e.g. Feishu WSClient.start() on a misconfigured app)
     // becomes a lastError instead of blocking the whole startup chain.
-    inst.client = await Promise.race([
+    const client = await Promise.race([
       inst.adapter.connect(cfg, hooks, ctxFor(inst)),
       new Promise((_, reject) => { const tm = setTimeout(() => reject(new Error('connect timeout')), CONNECT_TIMEOUT_MS); if (typeof tm.unref === 'function') tm.unref(); }),
     ]);
+    if (gen !== inst.startGen) {
+      // stopBridge / reload ran while the connect was in flight: this start lost the race. Don't
+      // resurrect the instance — tear down the late-arriving client so it doesn't leak.
+      try { await inst.adapter.disconnect?.(client, ctxFor(inst)); } catch { /* best-effort */ }
+      audit(inst, 'start-superseded', {});
+      return;
+    }
+    inst.client = client;
     inst.running = true;
     inst.connected = true;
+    inst.connectionState = 'connected';
     inst.lastError = null;
+    if (typeof inst.adapter.connectionProbe === 'function') {
+      inst.connPollTimer = setInterval(() => {
+        try { setConnectionState(inst, gen, inst.adapter.connectionProbe(inst.client), null); }
+        catch { /* best-effort: a probe throw must not kill the interval */ }
+      }, CONN_POLL_MS);
+      if (typeof inst.connPollTimer.unref === 'function') inst.connPollTimer.unref();
+    }
     audit(inst, 'start', inst.adapter.statusFields ? inst.adapter.statusFields(cfg) : {});
   } catch (e) {
+    if (gen !== inst.startGen) return; // superseded by stop/reload — don't overwrite their state
     inst.lastError = String(e?.message || e);
     inst.connected = false;
+    inst.connectionState = 'disconnected';
     audit(inst, 'start-error', { error: inst.lastError });
   }
 }
@@ -733,6 +790,9 @@ export async function startBridge(id, deps) {
 export async function stopBridge(id) {
   const inst = instances.get(id);
   if (!inst) return;
+  // Invalidate connection hooks up front so anything the adapter teardown fires can't flip state.
+  inst.startGen++;
+  if (inst.connPollTimer) { clearInterval(inst.connPollTimer); inst.connPollTimer = null; }
   if (inst.ackCardPromise && activeInjection?.platformId === id) {
     await finalizeAckCard(inst, activeInjection.target, tr(inst, 'noSession'), 'error');
   } else {
@@ -743,6 +803,7 @@ export async function stopBridge(id) {
   inst.client = null;
   inst.running = false;
   inst.connected = false;
+  inst.connectionState = 'disconnected';
   inst.boundConversation = null;
   if (activeInjection && activeInjection.platformId === id) clearActiveInjection();
   inst.queue.length = 0;
@@ -760,10 +821,11 @@ export function isBridgeRunning(id) {
 
 export function getBridgeStatus(id) {
   const inst = instances.get(id);
-  if (!inst) return { running: false, connected: false, lastError: null, boundConversationId: null };
+  if (!inst) return { running: false, connected: false, connectionState: 'disconnected', lastError: null, boundConversationId: null };
   const base = {
     running: inst.running,
     connected: inst.connected,
+    connectionState: inst.connectionState,
     lastError: inst.lastError,
     boundConversationId: inst.boundConversation?.conversationId || null,
   };
@@ -799,6 +861,8 @@ export async function stopAll() {
 // ─── test seams ───
 export function __setStreamTickMsForTests(ms) { STREAM_TICK_MS = (ms == null ? 300 : ms); }
 
+export function __setConnPollMsForTests(ms) { CONN_POLL_MS = (ms == null ? 5_000 : ms); }
+
 export function __setMaxQueueForTests(id, n) {
   const inst = instances.get(id);
   if (inst) inst.maxQueueOverride = n;
@@ -809,6 +873,9 @@ export function __resetForTests(id) {
   const inst = instances.get(id);
   if (!inst) return;
   inst.client = null; inst.running = false; inst.connected = false; inst.lastError = null;
+  inst.connectionState = 'disconnected';
+  inst.startGen++; // orphan any listeners still bound to a previous start
+  if (inst.connPollTimer) { clearInterval(inst.connPollTimer); inst.connPollTimer = null; }
   inst.bridgeDeps = null; inst.boundConversation = null; inst.lastRepliedTurnTs = null;
   inst.maxQueueOverride = null;
   inst.seenMsgIds.length = 0; inst.queue.length = 0; inst.sendTimes.length = 0;

package/server/lib/im-lock.js

@@ -135,7 +135,15 @@ export function defaultProbe(id, port, { timeoutMs = 400 } = {}) {
               const j = JSON.parse(body);
               // 身份：能对「该 id」返回 IM status 形状的 loopback 服务即视为我们的 worker
               if (j && (j.connection || typeof j.enabled === 'boolean')) {
-                finish({ ok: true, connected: !!(j.connection && j.connection.connected), pid: j.pid });
+                finish({
+                  ok: true,
+                  connected: !!(j.connection && j.connection.connected),
+                  // Old workers (pre-tri-state builds) omit connectionState → derive from connected.
+                  connectionState: j.connection?.connectionState
+                    ?? (j.connection?.connected ? 'connected' : 'disconnected'),
+                  lastError: j.connection?.lastError ?? null,
+                  pid: j.pid,
+                });
               } else finish(null);
             } catch { finish(null); }
           });
@@ -178,7 +186,13 @@ export async function getImLiveness(id, opts = {}) {
 
   const res = await probe(id, lock.port);
   if (res && res.ok && (res.pid == null || res.pid === lock.pid)) {
-    return { state: 'ready', lock, connected: !!res.connected };
+    return {
+      state: 'ready',
+      lock,
+      connected: !!res.connected,
+      connectionState: res.connectionState ?? (res.connected ? 'connected' : 'disconnected'),
+      lastError: res.lastError ?? null,
+    };
   }
   return { state: pidAlive(lock.pid) ? 'hung' : 'dead', lock };
 }