@xmoxmo/bncr 0.2.7 → 0.2.9

package/src/plugin/setup.ts

@@ -0,0 +1,24 @@
+import { CHANNEL_ID } from '../core/accounts.ts';
+import { applyOpenClawAccountNameToChannelSection } from '../openclaw/sdk-helpers.ts';
+
+export const BNCR_SETUP_SURFACE = {
+  applyAccountName: ({ cfg, accountId, name }: any) =>
+    applyOpenClawAccountNameToChannelSection({
+      cfg,
+      channelKey: CHANNEL_ID,
+      accountId,
+      name,
+      alwaysUseAccounts: true,
+    }),
+  applyAccountConfig: ({ cfg, accountId }: any) => {
+    const next = { ...(cfg || {}) } as any;
+    next.channels = next.channels || {};
+    next.channels[CHANNEL_ID] = next.channels[CHANNEL_ID] || {};
+    next.channels[CHANNEL_ID].accounts = next.channels[CHANNEL_ID].accounts || {};
+    next.channels[CHANNEL_ID].accounts[accountId] = {
+      ...(next.channels[CHANNEL_ID].accounts[accountId] || {}),
+      enabled: true,
+    };
+    return next;
+  },
+};

package/src/plugin/status.ts

@@ -0,0 +1,38 @@
+import { BNCR_DEFAULT_ACCOUNT_ID, resolveAccount, resolveDefaultDisplayName } from '../core/accounts.ts';
+import { buildAccountStatusSnapshot } from '../core/status.ts';
+import { createOpenClawDefaultChannelRuntimeState } from '../openclaw/sdk-helpers.ts';
+
+export type BncrStatusBridge = {
+  getChannelSummary: (defaultAccountId: string) => unknown | Promise<unknown>;
+  getAccountRuntimeSnapshot: (accountId?: string) => unknown;
+  getStatusHeadline: (accountId?: string) => unknown;
+};
+
+export function createBncrStatusSurface(getBridge: () => BncrStatusBridge) {
+  return {
+    defaultRuntime: createOpenClawDefaultChannelRuntimeState(BNCR_DEFAULT_ACCOUNT_ID, {
+      mode: 'ws-offline',
+    }),
+    buildChannelSummary: async ({ defaultAccountId }: any) => {
+      return getBridge().getChannelSummary(defaultAccountId || BNCR_DEFAULT_ACCOUNT_ID);
+    },
+    buildAccountSnapshot: async ({ account, runtime }: any) => {
+      const runtimeBridge = getBridge();
+      const rt = runtime || runtimeBridge.getAccountRuntimeSnapshot(account?.accountId);
+      return buildAccountStatusSnapshot({
+        account,
+        runtime: rt,
+        healthSummary: runtimeBridge.getStatusHeadline(account?.accountId),
+        // default 名不可隐藏时，统一展示稳定默认值
+        displayName: resolveDefaultDisplayName(account?.name, account?.accountId),
+      });
+    },
+    resolveAccountState: ({ enabled, configured, account, cfg, runtime }: any) => {
+      if (!enabled) return 'disabled';
+      const resolved = resolveAccount(cfg, account?.accountId);
+      if (!(resolved.enabled && configured)) return 'not configured';
+      const rt = runtime || getBridge().getAccountRuntimeSnapshot(account?.accountId);
+      return (rt as any)?.connected ? 'linked' : 'configured';
+    },
+  };
+}

package/src/runtime/log-dedupe.ts

@@ -0,0 +1,56 @@
+export type LogDedupeStateEntry = {
+  at: number;
+  sig: string;
+};
+
+export type LogDedupeState = Map<string, LogDedupeStateEntry>;
+
+export const LOG_DEDUPE_STATE_TTL_MS = 10 * 60 * 1000;
+export const LOG_DEDUPE_STATE_MAX_ENTRIES = 1_000;
+
+export function pruneLogDedupeState(
+  state: LogDedupeState,
+  currentTime: number,
+  options?: {
+    ttlMs?: number;
+    maxEntries?: number;
+  },
+) {
+  const ttlMs = options?.ttlMs ?? LOG_DEDUPE_STATE_TTL_MS;
+  const maxEntries = options?.maxEntries ?? LOG_DEDUPE_STATE_MAX_ENTRIES;
+
+  for (const [key, entry] of state.entries()) {
+    if (currentTime - entry.at > ttlMs) {
+      state.delete(key);
+    }
+  }
+
+  while (state.size > maxEntries) {
+    const oldestKey = state.keys().next().value;
+    if (!oldestKey) break;
+    state.delete(oldestKey);
+  }
+}
+
+export function shouldEmitDedupLog(args: {
+  state: LogDedupeState;
+  key: string;
+  sig: string;
+  nowMs: number;
+  windowMs?: number;
+  ttlMs?: number;
+  maxEntries?: number;
+}) {
+  const windowMs = args.windowMs ?? 5 * 60 * 1000;
+  const pruneOptions = {
+    ttlMs: args.ttlMs,
+    maxEntries: args.maxEntries,
+  };
+
+  pruneLogDedupeState(args.state, args.nowMs, pruneOptions);
+  const prev = args.state.get(args.key) || null;
+  if (prev && prev.sig === args.sig && args.nowMs - prev.at < windowMs) return false;
+  args.state.set(args.key, { at: args.nowMs, sig: args.sig });
+  pruneLogDedupeState(args.state, args.nowMs, pruneOptions);
+  return true;
+}

package/src/runtime/outbound-ack-timeout.ts

@@ -0,0 +1,96 @@
+type ComputeBncrRecommendedAckTimeoutArgs = {
+  lateAckOkCount: number;
+  recentAckTimeoutCount: number;
+  lastLateAckPushLatencyMs: number | null;
+  lastLateAckOkAt?: number | null;
+  adaptiveAckRecoveryOkCount?: number;
+  nowMs: number;
+  defaultAckTimeoutMs: number;
+  minAckTimeoutMs: number;
+  maxAckTimeoutMs: number;
+  lateAckObservationTtlMs: number;
+  recoveryOkThreshold: number;
+};
+
+type ComputeBncrRecommendedAckTimeoutReasonArgs = ComputeBncrRecommendedAckTimeoutArgs & {
+  recommendedAckTimeoutMs?: number;
+};
+
+function isLateAckObservationExpired(args: {
+  lastLateAckOkAt?: number | null;
+  nowMs: number;
+  lateAckObservationTtlMs: number;
+}) {
+  const lastLateAckOkAt = typeof args.lastLateAckOkAt === 'number' ? args.lastLateAckOkAt : null;
+  return (
+    typeof lastLateAckOkAt === 'number' &&
+    lastLateAckOkAt > 0 &&
+    args.nowMs - lastLateAckOkAt > args.lateAckObservationTtlMs
+  );
+}
+
+function isAdaptiveAckRecovered(args: {
+  adaptiveAckRecoveryOkCount?: number;
+  recoveryOkThreshold: number;
+}) {
+  return (
+    typeof args.adaptiveAckRecoveryOkCount === 'number' &&
+    args.adaptiveAckRecoveryOkCount >= args.recoveryOkThreshold
+  );
+}
+
+export function computeBncrRecommendedAckTimeoutReason(
+  args: ComputeBncrRecommendedAckTimeoutReasonArgs,
+) {
+  if (args.recentAckTimeoutCount <= 0) return 'no-timeout-evidence';
+  if (args.lateAckOkCount <= 0) return 'no-late-ack-evidence';
+  if (typeof args.lastLateAckPushLatencyMs !== 'number') return 'missing-latency';
+  if (isLateAckObservationExpired(args)) return 'late-ack-expired';
+  if (isAdaptiveAckRecovered(args)) return 'recovered';
+  if (args.recommendedAckTimeoutMs === args.maxAckTimeoutMs) return 'capped-max';
+  return 'late-ack-observed';
+}
+
+export function computeBncrRecommendedAckTimeoutMs(args: ComputeBncrRecommendedAckTimeoutArgs) {
+  if (
+    args.lateAckOkCount <= 0 ||
+    args.recentAckTimeoutCount <= 0 ||
+    typeof args.lastLateAckPushLatencyMs !== 'number' ||
+    isLateAckObservationExpired(args) ||
+    isAdaptiveAckRecovered(args)
+  ) {
+    return args.defaultAckTimeoutMs;
+  }
+  const recommended = Math.ceil(args.lastLateAckPushLatencyMs * 1.25);
+  return Math.min(args.maxAckTimeoutMs, Math.max(args.minAckTimeoutMs, recommended));
+}
+
+function finiteNumberOr(value: unknown, fallback: number) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+function asString(value: unknown, fallback = '') {
+  return typeof value === 'string' ? value : fallback;
+}
+
+export function buildBncrRuntimeAckStrategy(args: {
+  ackObservability: Record<string, any>;
+  defaultAckTimeoutMs: number;
+  maxAckTimeoutMs: number;
+}) {
+  const { ackObservability } = args;
+  const currentMs = finiteNumberOr(ackObservability.currentAckTimeoutMs, args.defaultAckTimeoutMs);
+  const defaultMs = finiteNumberOr(ackObservability.defaultAckTimeoutMs, args.defaultAckTimeoutMs);
+  const reason = asString(ackObservability.recommendedAckTimeoutReason || 'unknown') || 'unknown';
+  return {
+    mode: ackObservability.adaptiveAckTimeoutEnabled === true ? 'adaptive' : 'fixed',
+    currentMs,
+    defaultMs,
+    maxMs: args.maxAckTimeoutMs,
+    reason,
+    active: currentMs > defaultMs,
+    lastLateAckAgeMs: ackObservability.lastLateAckAgeMs ?? null,
+    lateAckObservationTtlMs: ackObservability.lateAckObservationTtlMs ?? null,
+    recovered: ackObservability.adaptiveAckRecovered === true,
+  };
+}

package/src/runtime/outbound-flags.ts

@@ -0,0 +1,81 @@
+import { CHANNEL_ID, BNCR_DEFAULT_ACCOUNT_ID, normalizeAccountId } from '../core/accounts.ts';
+import { getOpenClawRuntimeConfig } from '../openclaw/config-runtime.ts';
+
+type RuntimeApiHolder = { api: unknown };
+
+type ResolveOutboundAckRequiredArgs = RuntimeApiHolder & {
+  accountId?: string;
+};
+
+export function resolveBncrOutboundAckRequired(args: ResolveOutboundAckRequiredArgs) {
+  try {
+    const cfg = getOpenClawRuntimeConfig(args.api as any);
+    const channelCfg = (cfg as any)?.channels?.[CHANNEL_ID];
+    const accountCfg =
+      args.accountId && channelCfg?.accounts && typeof channelCfg.accounts === 'object'
+        ? (channelCfg.accounts as Record<string, any>)[normalizeAccountId(args.accountId)]
+        : null;
+    const scoped = accountCfg?.outboundRequireAck;
+    const global = channelCfg?.outboundRequireAck;
+    if (typeof scoped === 'boolean') return scoped;
+    if (typeof global === 'boolean') return global;
+    return true;
+  } catch {
+    return true;
+  }
+}
+
+type BuildBncrRuntimeFlagsArgs = RuntimeApiHolder & {
+  accountId?: string;
+  resolveMessageAckTimeoutMs: (accountId?: string) => number;
+  adaptiveAckTimeoutEnabled: boolean;
+  defaultMessageAckTimeoutMs: number;
+  fileAckTimeoutMs: number;
+  debugVerbose: boolean;
+};
+
+export function buildBncrRuntimeStatusInput(args: {
+  accountId: string;
+  connected: boolean;
+  queueSnapshot: Record<string, any>;
+  eventCounters: Record<string, any>;
+  activitySnapshot: Record<string, any>;
+  startedAt: number | null;
+  running?: boolean;
+  channelRoot: string;
+}) {
+  return {
+    accountId: args.accountId,
+    connected: args.connected,
+    ...args.queueSnapshot,
+    ...args.eventCounters,
+    ...args.activitySnapshot,
+    startedAt: args.startedAt,
+    running: args.running,
+    channelRoot: args.channelRoot,
+  };
+}
+
+export function buildBncrRuntimeFlags(args: BuildBncrRuntimeFlagsArgs) {
+  let ackPolicySource: 'channel' | 'default' = 'default';
+  try {
+    const cfg = getOpenClawRuntimeConfig(args.api as any);
+    const global = (cfg as any)?.channels?.[CHANNEL_ID]?.outboundRequireAck;
+    if (typeof global === 'boolean') ackPolicySource = 'channel';
+  } catch {
+    // keep default source
+  }
+  const accountId = args.accountId ? normalizeAccountId(args.accountId) : BNCR_DEFAULT_ACCOUNT_ID;
+  return {
+    outboundRequireAck: resolveBncrOutboundAckRequired({
+      api: args.api,
+      accountId,
+    }),
+    ackPolicySource,
+    messageAckTimeoutMs: args.resolveMessageAckTimeoutMs(accountId),
+    adaptiveAckTimeoutEnabled: args.adaptiveAckTimeoutEnabled,
+    defaultMessageAckTimeoutMs: args.defaultMessageAckTimeoutMs,
+    fileAckTimeoutMs: args.fileAckTimeoutMs,
+    debugVerbose: args.debugVerbose,
+  };
+}

package/src/runtime/outbox-transitions.ts

@@ -0,0 +1,119 @@
+import type { OutboxEntry } from '../core/types.ts';
+import type {
+  PushFailureDecision,
+  RetryRerouteDecision,
+} from '../messaging/outbound/retry-policy.ts';
+
+export function applyBncrRetryRerouteDecisionToEntry(
+  entry: OutboxEntry,
+  decision: Extract<RetryRerouteDecision, { kind: 'retry' }>,
+): OutboxEntry {
+  return {
+    ...entry,
+    routeAttemptConnIds: decision.attemptedConnIds,
+    fastReroutePending: decision.fastReroutePending,
+    retryCount: decision.nextRetryCount,
+    lastAttemptAt: decision.lastAttemptAt,
+    nextAttemptAt: decision.nextAttemptAt,
+    lastError: decision.lastError,
+    routeAttemptRound: decision.routeAttemptRound,
+  };
+}
+
+export function applyBncrPushFailureDecisionToEntry(
+  entry: OutboxEntry,
+  decision: Extract<PushFailureDecision, { kind: 'retry' }>,
+): OutboxEntry {
+  return {
+    ...entry,
+    retryCount: decision.nextRetryCount,
+    lastAttemptAt: decision.lastAttemptAt,
+    nextAttemptAt: decision.nextAttemptAt,
+    lastError: decision.lastError,
+  };
+}
+
+export function buildBncrAckRetryEntryPatch(args: {
+  entry: OutboxEntry;
+  error: string;
+  nextAttemptAt: number;
+}): OutboxEntry {
+  return {
+    ...args.entry,
+    nextAttemptAt: args.nextAttemptAt,
+    lastError: args.error,
+    awaitingRetryPush: true,
+  };
+}
+
+export function buildBncrOutboxFailureEntryPatch(args: {
+  entry: OutboxEntry;
+  lastError: string;
+}): OutboxEntry {
+  return {
+    ...args.entry,
+    lastError: args.lastError,
+  };
+}
+
+export function buildBncrOutboxPushSuccessEntryPatch(args: {
+  entry: OutboxEntry;
+  connIds: Iterable<string>;
+  pushedAt: number;
+  ownerConnId?: string;
+  ownerClientId?: string;
+  clearLastError?: boolean;
+}): OutboxEntry {
+  const connIds = Array.from(args.connIds);
+  const lastPushConnId = args.ownerConnId || (connIds.length === 1 ? connIds[0] : undefined);
+  const routeAttemptConnIds = Array.isArray(args.entry.routeAttemptConnIds)
+    ? [...args.entry.routeAttemptConnIds]
+    : [];
+  if (lastPushConnId && !routeAttemptConnIds.includes(lastPushConnId)) {
+    routeAttemptConnIds.push(lastPushConnId);
+  }
+  return {
+    ...args.entry,
+    lastPushAt: args.pushedAt,
+    lastPushConnId,
+    lastPushClientId: args.ownerClientId,
+    awaitingRetryPush: false,
+    routeAttemptConnIds,
+    lastError: args.clearLastError ? undefined : args.entry.lastError,
+  };
+}
+
+function finiteNumberOr(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+export function buildBncrAckOkTelemetryPatch(args: {
+  entry: OutboxEntry;
+  ackAt: number;
+  defaultAckTimeoutMs: number;
+}): {
+  ackAt: number;
+  ackQueueLatencyMs: number;
+  ackPushLatencyMs: number | null;
+  lateAccepted: boolean;
+  shouldResetAdaptiveAckRecovery: boolean;
+  shouldIncrementAdaptiveAckRecovery: boolean;
+} {
+  const ackAt = finiteNumberOr(args.ackAt, 0);
+  const defaultAckTimeoutMs = Math.max(0, finiteNumberOr(args.defaultAckTimeoutMs, 0));
+  const ackQueueLatencyMs = Math.max(0, ackAt - finiteNumberOr(args.entry.createdAt, ackAt));
+  const ackPushLatencyMs =
+    typeof args.entry.lastPushAt === 'number'
+      ? Math.max(0, ackAt - args.entry.lastPushAt)
+      : null;
+  const lateAccepted = args.entry.awaitingRetryPush === true;
+  return {
+    ackAt,
+    ackQueueLatencyMs,
+    ackPushLatencyMs,
+    lateAccepted,
+    shouldResetAdaptiveAckRecovery: lateAccepted,
+    shouldIncrementAdaptiveAckRecovery:
+      !lateAccepted && typeof ackPushLatencyMs === 'number' && ackPushLatencyMs <= defaultAckTimeoutMs,
+  };
+}

package/src/runtime/status-snapshots.ts

@@ -0,0 +1,108 @@
+import { normalizeAccountId } from '../core/accounts.ts';
+import type { OutboxEntry } from '../core/types.ts';
+
+function getCounter(map: Map<string, number>, accountId: string): number {
+  return map.get(normalizeAccountId(accountId)) || 0;
+}
+
+export function buildRuntimeQueueSnapshot(args: {
+  accountId: string;
+  outboxEntries: Iterable<OutboxEntry>;
+  deadLetterEntries: Iterable<OutboxEntry>;
+  sessionRouteEntries: Iterable<{ accountId: string }>;
+  countInvalidOutboxSessionKeys: (accountId: string) => number;
+  countLegacyAccountResidue: (accountId: string) => number;
+}) {
+  const accountId = normalizeAccountId(args.accountId);
+  const pending = Array.from(args.outboxEntries).filter((v) => v.accountId === accountId).length;
+  const deadLetter = Array.from(args.deadLetterEntries).filter((v) => v.accountId === accountId).length;
+  const sessionRoutesCount = Array.from(args.sessionRouteEntries).filter(
+    (v) => v.accountId === accountId,
+  ).length;
+  return {
+    pending,
+    deadLetter,
+    sessionRoutesCount,
+    invalidOutboxSessionKeys: args.countInvalidOutboxSessionKeys(accountId),
+    legacyAccountResidue: args.countLegacyAccountResidue(accountId),
+  };
+}
+
+export function buildRuntimeEventCounters(args: {
+  accountId: string;
+  connectEventsByAccount: Map<string, number>;
+  inboundEventsByAccount: Map<string, number>;
+  activityEventsByAccount: Map<string, number>;
+  ackEventsByAccount: Map<string, number>;
+}) {
+  const accountId = normalizeAccountId(args.accountId);
+  return {
+    connectEvents: getCounter(args.connectEventsByAccount, accountId),
+    inboundEvents: getCounter(args.inboundEventsByAccount, accountId),
+    activityEvents: getCounter(args.activityEventsByAccount, accountId),
+    ackEvents: getCounter(args.ackEventsByAccount, accountId),
+  };
+}
+
+export function buildRuntimeActivitySnapshot(args: {
+  accountId: string;
+  activeConnectionCount: (accountId: string) => number;
+  lastSessionByAccount: Map<string, { sessionKey: string; scope: string; updatedAt: number }>;
+  lastActivityByAccount: Map<string, number>;
+  lastInboundByAccount: Map<string, number>;
+  lastOutboundByAccount: Map<string, number>;
+}) {
+  const accountId = normalizeAccountId(args.accountId);
+  return {
+    activeConnections: args.activeConnectionCount(accountId),
+    lastSession: args.lastSessionByAccount.get(accountId) || null,
+    lastActivityAt: args.lastActivityByAccount.get(accountId) || null,
+    lastInboundAt: args.lastInboundByAccount.get(accountId) || null,
+    lastOutboundAt: args.lastOutboundByAccount.get(accountId) || null,
+  };
+}
+
+export function buildRuntimeStatusSnapshots(args: {
+  accountId: string;
+  outboxEntries: Iterable<OutboxEntry>;
+  deadLetterEntries: Iterable<OutboxEntry>;
+  sessionRouteEntries: Iterable<{ accountId: string }>;
+  countInvalidOutboxSessionKeys: (accountId: string) => number;
+  countLegacyAccountResidue: (accountId: string) => number;
+  connectEventsByAccount: Map<string, number>;
+  inboundEventsByAccount: Map<string, number>;
+  activityEventsByAccount: Map<string, number>;
+  ackEventsByAccount: Map<string, number>;
+  activeConnectionCount: (accountId: string) => number;
+  lastSessionByAccount: Map<string, { sessionKey: string; scope: string; updatedAt: number }>;
+  lastActivityByAccount: Map<string, number>;
+  lastInboundByAccount: Map<string, number>;
+  lastOutboundByAccount: Map<string, number>;
+}) {
+  const accountId = normalizeAccountId(args.accountId);
+  return {
+    queueSnapshot: buildRuntimeQueueSnapshot({
+      accountId,
+      outboxEntries: args.outboxEntries,
+      deadLetterEntries: args.deadLetterEntries,
+      sessionRouteEntries: args.sessionRouteEntries,
+      countInvalidOutboxSessionKeys: args.countInvalidOutboxSessionKeys,
+      countLegacyAccountResidue: args.countLegacyAccountResidue,
+    }),
+    eventCounters: buildRuntimeEventCounters({
+      accountId,
+      connectEventsByAccount: args.connectEventsByAccount,
+      inboundEventsByAccount: args.inboundEventsByAccount,
+      activityEventsByAccount: args.activityEventsByAccount,
+      ackEventsByAccount: args.ackEventsByAccount,
+    }),
+    activitySnapshot: buildRuntimeActivitySnapshot({
+      accountId,
+      activeConnectionCount: args.activeConnectionCount,
+      lastSessionByAccount: args.lastSessionByAccount,
+      lastActivityByAccount: args.lastActivityByAccount,
+      lastInboundByAccount: args.lastInboundByAccount,
+      lastOutboundByAccount: args.lastOutboundByAccount,
+    }),
+  };
+}

package/src/runtime/status-worker.ts

@@ -0,0 +1,172 @@
+import { normalizeAccountId } from '../core/accounts.ts';
+
+type StatusWorkerContext = {
+  accountId: string;
+  getStatus?: () => Record<string, any>;
+  setStatus?: (status: Record<string, any>) => void;
+  abortSignal?: {
+    aborted?: boolean;
+    addEventListener?: (event: 'abort', listener: () => void, options?: { once?: boolean }) => void;
+    removeEventListener?: (event: 'abort', listener: () => void) => void;
+  };
+};
+
+export type ChannelAccountWorkerHandle = {
+  timer: NodeJS.Timeout;
+  finish: (reason: string) => void;
+  cleanupAbortListener?: () => void;
+};
+
+type StatusWorkerHooks = {
+  isOnline: (accountId: string) => boolean;
+  hasRecentInboundReachability: (accountId: string) => boolean;
+  getLastActivityAt: (accountId: string, previous: Record<string, any>) => number | null;
+  getActiveConnectionKey: (accountId: string) => string | null;
+  getActiveConnections: (accountId: string) => Array<Record<string, unknown>>;
+  buildStatusMeta: (accountId: string) => Record<string, any>;
+  logInfo: (scope: string | undefined, message: string, options?: { debugOnly?: boolean }) => void;
+  logInfoDedup: (
+    scope: string | undefined,
+    message: string,
+    options: { key: string; sig: string; debugOnly?: boolean; windowMs?: number },
+  ) => void;
+};
+
+type StatusWorkerRuntime = {
+  workers: Map<string, ChannelAccountWorkerHandle>;
+  bridgeId: string;
+  hooks: StatusWorkerHooks;
+};
+
+export function clearBncrStatusWorker(
+  runtime: StatusWorkerRuntime,
+  accountId: string,
+  reason: string,
+) {
+  const worker = runtime.workers.get(accountId);
+  if (!worker) return false;
+  worker.finish(reason);
+  runtime.hooks.logInfo(
+    'health',
+    `status-worker cleared ${JSON.stringify({ bridge: runtime.bridgeId, accountId, reason })}`,
+    { debugOnly: true },
+  );
+  return true;
+}
+
+export function clearAllBncrStatusWorkers(runtime: StatusWorkerRuntime, reason: string) {
+  for (const accountId of Array.from(runtime.workers.keys())) {
+    clearBncrStatusWorker(runtime, accountId, reason);
+  }
+}
+
+export async function startBncrStatusWorker(runtime: StatusWorkerRuntime, ctx: StatusWorkerContext) {
+  const accountId = normalizeAccountId(ctx.accountId);
+  clearBncrStatusWorker(runtime, accountId, 'start-replace');
+
+  const tick = () => {
+    const previous = ctx.getStatus?.() || {};
+    const onlineByConn = runtime.hooks.isOnline(accountId);
+    const recentInboundReachable = runtime.hooks.hasRecentInboundReachability(accountId);
+    const connected = onlineByConn || recentInboundReachable;
+    const lastActAt = runtime.hooks.getLastActivityAt(accountId, previous);
+    const activeConnections = runtime.hooks.getActiveConnections(accountId);
+    const healthSig = JSON.stringify({
+      bridge: runtime.bridgeId,
+      accountId,
+      connected,
+      onlineByConn,
+      recentInboundReachable,
+      activeConnectionKey: runtime.hooks.getActiveConnectionKey(accountId),
+      activeConnections,
+    });
+    const conns = activeConnections.length;
+    runtime.hooks.logInfoDedup(
+      'health',
+      `status-tick ${accountId}|changed|${connected ? 'linked' : 'configured'}|onlineByConn=${onlineByConn}|recentInboundReachable=${recentInboundReachable}|conns=${conns}`,
+      {
+        key: `health-status-tick:${accountId}`,
+        sig: healthSig,
+      },
+    );
+    runtime.hooks.logInfoDedup('health', `status-tick ${healthSig}`, {
+      key: `health-status-tick-debug:${accountId}`,
+      sig: healthSig,
+      debugOnly: true,
+    });
+
+    ctx.setStatus?.({
+      ...previous,
+      accountId,
+      running: true,
+      connected,
+      lastEventAt: lastActAt,
+      // 状态映射：在线=linked，离线=configured
+      mode: connected ? 'linked' : 'configured',
+      lastError: previous?.lastError ?? null,
+      meta: runtime.hooks.buildStatusMeta(accountId),
+    });
+  };
+
+  tick();
+  const timer = setInterval(tick, 5_000);
+  let worker!: ChannelAccountWorkerHandle;
+  const done = new Promise<void>((resolve) => {
+    let settled = false;
+    const finish = (reason: string) => {
+      if (settled) return;
+      settled = true;
+      const activeWorker = runtime.workers.get(accountId);
+      if (activeWorker === worker) {
+        runtime.workers.delete(accountId);
+      }
+      clearInterval(timer);
+      worker.cleanupAbortListener?.();
+      worker.cleanupAbortListener = undefined;
+      runtime.hooks.logInfo(
+        'health',
+        `status-worker finished ${JSON.stringify({ bridge: runtime.bridgeId, accountId, reason })}`,
+        { debugOnly: true },
+      );
+      runtime.hooks.logInfo('health', `status-worker finished ${accountId}|${reason}`);
+      resolve();
+    };
+
+    worker = { timer, finish };
+    runtime.workers.set(accountId, worker);
+
+    const onAbort = () => finish('abort');
+    const abortSignal = ctx.abortSignal;
+
+    if (abortSignal?.aborted) {
+      onAbort();
+      return;
+    }
+
+    abortSignal?.addEventListener?.('abort', onAbort, { once: true });
+    if (abortSignal?.removeEventListener) {
+      worker.cleanupAbortListener = () => abortSignal.removeEventListener?.('abort', onAbort);
+    }
+  });
+  await done;
+}
+
+export async function stopBncrStatusWorker(runtime: StatusWorkerRuntime, ctx: Partial<StatusWorkerContext>) {
+  const accountId = normalizeAccountId(ctx?.accountId);
+  const cleared = clearBncrStatusWorker(runtime, accountId, 'explicit-stop');
+  const previous = ctx?.getStatus?.() || {};
+  ctx?.setStatus?.({
+    ...previous,
+    accountId,
+    running: false,
+    restartPending: false,
+    lastStopAt: Date.now(),
+    meta: runtime.hooks.buildStatusMeta(accountId),
+  });
+  runtime.hooks.logInfo(
+    'health',
+    `status-stop ${JSON.stringify({ bridge: runtime.bridgeId, accountId, cleared })}`,
+    { debugOnly: true },
+  );
+  runtime.hooks.logInfo('health', `status-stop ${accountId}|cleared=${cleared}`);
+}