@foxden-app/foxclaw 0.5.41 → 0.5.43

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable FoxClaw changes are listed here. Each release note is bilingual so GitHub Releases and the npm package are useful to both Chinese and English readers.
 
+## 0.5.43 - 2026-06-18
+
+### 中文
+- Codex 最终答复出现后，FoxClaw 会把本轮所有过程汇报合并到第一条过程消息，并编辑为默认收起的 Telegram RichMessage `details`；最终答复继续独立展示，使历史记录保持清晰的一问一答结构。
+- 折叠摘要显示过程条数和整体起止时间，展开后每段过程汇报保留精确到秒的起止时间及原有 Markdown 富文本效果；普通 Telegram 回合和 CLI 观察回合统一生效。
+- 如果 RichMessage 编辑失败，原过程消息全部保留且不执行删除；超出 Telegram 单条富消息上限时会明确标注未收入归档的条数。
+
+### English
+- After a Codex final answer arrives, FoxClaw consolidates all progress updates from the turn into the first progress message and edits it into a collapsed Telegram RichMessage `details` block; the final answer remains separate for a clean question-and-answer history.
+- The collapsed summary shows the update count and overall time range, while each expanded update preserves second-level start/end timestamps and Markdown-rich rendering; this applies to both normal Telegram turns and CLI-observed turns.
+- If RichMessage editing fails, every original progress message is preserved and no deletion is attempted; updates exceeding Telegram's single-rich-message limit are reported explicitly.
+
+## 0.5.42 - 2026-06-18
+
+### 中文
+- 新增跨节点升级广播：一个节点升级成功后会通过现有 auth sync 加密通道广播目标版本，其他节点收到后会在 runtime/auth sync 空闲时自动执行本机 self-update；终端 `foxclaw update` 成功后也会在服务重启时触发广播。
+- 为避免升级风暴，收到广播的节点如果已经是目标版本会跳过；远端请求会记录到 auth sync recent events，并可在 `/auth sync status/events` 中排查。
+- 精简终端 `foxclaw status` 默认输出，集中展示运行状态、Codex/app-server、工作队列、bot 概况、auth sync backlog、最近升级和错误；完整原始 JSON 可通过 `foxclaw status --json` 查看。
+
+### English
+- Added cross-node update broadcasting: after one node updates successfully, it broadcasts the target version over the existing encrypted auth sync channel, and peers schedule their own self-update when runtime/auth sync work is idle; terminal `foxclaw update` also broadcasts after the restarted service comes back.
+- To avoid update storms, peers skip broadcasts that target their current version; remote update requests are recorded in auth sync recent events for `/auth sync status/events` diagnostics.
+- Condensed terminal `foxclaw status` by default, focusing on runtime health, Codex/app-server, work queues, bot overview, auth sync backlog, recent update, and errors; full raw JSON remains available via `foxclaw status --json`.
+
 ## 0.5.41 - 2026-06-18
 
 ### 中文

package/dist/auth/cross_node_sync.d.ts

@@ -198,6 +198,20 @@ export type AuthSyncNotification = {
     peer: string;
     result: AuthSyncPullResponseResult;
     reason: string | null;
+} | {
+    kind: 'service_update_sent';
+    requestId: string;
+    targetVersion: string | null;
+    peers: string[];
+} | {
+    kind: 'service_update_received';
+    requestId: string;
+    targetVersion: string | null;
+    sourceNodeId: string;
+    sourceLabel: string;
+    peer: string;
+    accepted: boolean;
+    reason: string | null;
 } | {
     kind: 'sync_error';
     reason: string;
@@ -219,6 +233,16 @@ export interface AuthSyncImportCallbacks {
         deleted: boolean;
         reason?: string | null;
     }>;
+    scheduleServiceUpdate?: (source: {
+        requestId: string;
+        nodeId: string;
+        label?: string | null;
+        targetVersion: string | null;
+        requestedAt: string;
+    }) => Promise<{
+        accepted: boolean;
+        reason?: string | null;
+    }>;
     isIdle: () => boolean;
     notify?: (event: AuthSyncNotification) => Promise<void>;
 }
@@ -284,8 +308,13 @@ export declare class CrossNodeAuthSync {
     acquireRefreshLease(reason: string): Promise<AuthSyncLeaseResult>;
     releaseRefreshLease(leaseId: string | null): Promise<void>;
     testPeers(): Promise<AuthSyncTestResult>;
+    publishServiceUpdateRequest(targetVersion: string | null): Promise<{
+        sent: number;
+        peers: string[];
+    }>;
     handleIncomingEnvelope(rawEnvelope: string, peer: AuthSyncPeerIdentity): Promise<boolean>;
     private handleMessage;
+    private handleServiceUpdateRequest;
     private handlePullRequest;
     private handlePullResponse;
     private markPullPeerUnavailable;

package/dist/auth/cross_node_sync.js

@@ -460,6 +460,35 @@ export class CrossNodeAuthSync {
         }
         return resultPromise;
     }
+    async publishServiceUpdateRequest(targetVersion) {
+        if (!this.isReady()) {
+            return { sent: 0, peers: [] };
+        }
+        const requestId = crypto.randomUUID();
+        const peers = [...this.peers];
+        await this.sendToAll({
+            kind: 'service.update.request',
+            requestId,
+            targetVersion,
+            requestedAt: new Date().toISOString(),
+        });
+        this.recordEvent({
+            direction: 'local',
+            kind: 'service.update.request',
+            stage: 'broadcast',
+            peer: null,
+            requestId,
+            candidateName: null,
+            detail: targetVersion ? `target=${targetVersion}` : null,
+        });
+        this.notify({
+            kind: 'service_update_sent',
+            requestId,
+            targetVersion,
+            peers,
+        });
+        return { sent: peers.length, peers };
+    }
     async handleIncomingEnvelope(rawEnvelope, peer) {
         if (!this.isReady() || !this.isAllowedPeer(peer)) {
             return false;
@@ -531,10 +560,47 @@ export class CrossNodeAuthSync {
                     this.recordEvent({ direction: 'in', kind: 'lease.release', stage: 'released', peer: normalizePeerIdentity(peer), requestId: message.leaseId, candidateName: null, detail: null });
                 }
                 return;
+            case 'service.update.request':
+                await this.handleServiceUpdateRequest(message, senderNodeId, sourceLabel, normalizePeerIdentity(peer));
+                return;
             default:
                 return;
         }
     }
+    async handleServiceUpdateRequest(message, senderNodeId, sourceLabel, peer) {
+        let result = {
+            accepted: false,
+            reason: 'service update scheduling is not configured',
+        };
+        if (this.callbacks.scheduleServiceUpdate) {
+            result = await this.callbacks.scheduleServiceUpdate({
+                requestId: message.requestId,
+                nodeId: senderNodeId,
+                label: sourceLabel,
+                targetVersion: message.targetVersion,
+                requestedAt: message.requestedAt,
+            });
+        }
+        this.recordEvent({
+            direction: 'local',
+            kind: 'service.update.request',
+            stage: result.accepted ? 'accepted' : 'skipped',
+            peer,
+            requestId: message.requestId,
+            candidateName: null,
+            detail: result.reason ?? (message.targetVersion ? `target=${message.targetVersion}` : null),
+        });
+        this.notify({
+            kind: 'service_update_received',
+            requestId: message.requestId,
+            targetVersion: message.targetVersion,
+            sourceNodeId: senderNodeId,
+            sourceLabel,
+            peer,
+            accepted: result.accepted,
+            reason: result.reason ?? null,
+        });
+    }
     async handlePullRequest(message, requesterNodeId, peer) {
         if (!isAuthCandidateName(message.candidateName))
             return;
@@ -1413,6 +1479,7 @@ function requestIdFromMessage(message) {
         case 'delete.candidate':
         case 'test.ping':
         case 'test.pong':
+        case 'service.update.request':
             return message.requestId;
         case 'lease.request':
             return message.leaseId;

package/dist/controller/controller.d.ts

@@ -236,6 +236,7 @@ export declare class BridgeSessionCore {
     private deleteMessage;
     private sendTyping;
     private sendObservedCliUserMessage;
+    private collapseTurnCommentary;
     private cleanupObservedTransientMessages;
     private hasObservedPersistentReply;
     private ensureThreadReady;

package/dist/controller/controller.js

@@ -1855,6 +1855,7 @@ export class BridgeSessionCore {
         const segment = ensureTurnSegment(active, `${active.turnId}:codex-error`, 'final_answer', 'final_answer', false);
         segment.text = text;
         segment.completed = true;
+        segment.completedAtMs = Date.now();
         await this.queueTurnRender(active, { forceStatus: true, forceStream: true });
     }
     async finishTerminalErroredActiveTurn(active) {
@@ -3131,6 +3132,7 @@ export class BridgeSessionCore {
         let shouldMarkPartialOutput = false;
         try {
             await this.queueTurnRender(active, { forceStatus: true, forceStream: true });
+            await this.collapseTurnCommentary(active);
             const renderedMessages = active.segments.reduce((count, segment) => count + segment.messages.length, 0);
             if (renderedMessages === 0) {
                 const fallbackKey = active.interruptRequested ? 'interrupted' : 'completed';
@@ -3186,6 +3188,7 @@ export class BridgeSessionCore {
                     }
                 }
                 segment.completed = true;
+                segment.completedAtMs = Date.now();
                 await this.queueTurnRender(active, { forceStream: true, forceStatus: true });
                 return;
             }
@@ -3421,6 +3424,50 @@ export class BridgeSessionCore {
             await this.sendHtmlMessage(scopeId, body);
         }
     }
+    async collapseTurnCommentary(active) {
+        if (active.scopeId.startsWith(BRIDGE_SCOPE_WEIXIN_PREFIX) || !this.hasObservedPersistentReply(active)) {
+            return;
+        }
+        const segments = active.segments.filter(segment => (segment.outputKind === 'commentary' && Boolean(segment.text.trim()) && segment.messages.length > 0));
+        const messages = segments.flatMap(segment => segment.messages);
+        const firstMessage = messages[0];
+        if (!firstMessage) {
+            return;
+        }
+        const locale = this.localeForChat(active.scopeId);
+        const html = renderCollapsedCommentary(locale, segments);
+        const fallback = locale === 'zh'
+            ? `过程汇报（${segments.length} 条，已折叠）`
+            : `Progress updates (${segments.length}, collapsed)`;
+        try {
+            await this.messaging.editRichHtml(active.scopeId, firstMessage.messageId, html, fallback, []);
+        }
+        catch (error) {
+            this.logger.warn('telegram.commentary_collapse_failed', {
+                error: String(error),
+                turnId: active.turnId,
+                messageId: firstMessage.messageId,
+            });
+            return;
+        }
+        for (const message of messages.slice(1)) {
+            try {
+                await this.deleteMessage(active.scopeId, message.messageId);
+            }
+            catch (error) {
+                if (!isTelegramMessageGone(error)) {
+                    this.logger.warn('telegram.commentary_collapse_delete_failed', {
+                        error: String(error),
+                        turnId: active.turnId,
+                        messageId: message.messageId,
+                    });
+                }
+            }
+        }
+        for (const segment of segments) {
+            segment.messages = [];
+        }
+    }
     async cleanupObservedTransientMessages(active) {
         if (!active.isObserved || !this.hasObservedPersistentReply(active)) {
             return;
@@ -8235,11 +8282,50 @@ function ensureTurnSegment(active, itemId, phase, outputKind, isPlan) {
         isPlan: Boolean(isPlan),
         text: '',
         completed: false,
+        startedAtMs: Date.now(),
+        completedAtMs: null,
         messages: [],
     };
     active.segments.push(segment);
     return segment;
 }
+function renderCollapsedCommentary(locale, segments) {
+    const firstAt = segments[0]?.startedAtMs ?? Date.now();
+    const lastSegment = segments[segments.length - 1];
+    const lastAt = lastSegment?.completedAtMs ?? lastSegment?.startedAtMs ?? firstAt;
+    const range = firstAt === lastAt
+        ? formatClockTimestamp(firstAt)
+        : `${formatClockTimestamp(firstAt)} - ${formatClockTimestamp(lastAt)}`;
+    const summary = locale === 'zh'
+        ? `过程汇报 · ${segments.length} 条 · ${range}`
+        : `Progress · ${segments.length} updates · ${range}`;
+    const maxBodyLength = TELEGRAM_RICH_MESSAGE_TEXT_LIMIT - summary.length - 1024;
+    const blocks = [];
+    let bodyLength = 0;
+    let omitted = 0;
+    for (const segment of segments) {
+        const endAt = segment.completedAtMs ?? segment.startedAtMs;
+        const timestamp = endAt === segment.startedAtMs
+            ? formatClockTimestamp(segment.startedAtMs)
+            : `${formatClockTimestamp(segment.startedAtMs)} - ${formatClockTimestamp(endAt)}`;
+        const block = `<h4>${escapeTelegramHtml(timestamp)}</h4>\n${renderTelegramMarkdownRichHtml(segment.text)}`;
+        if (bodyLength + block.length > maxBodyLength) {
+            omitted += 1;
+            continue;
+        }
+        blocks.push(block);
+        bodyLength += block.length;
+    }
+    if (omitted > 0) {
+        blocks.push(`<p>${escapeTelegramHtml(locale === 'zh' ? `另有 ${omitted} 条过长内容未收入归档` : `${omitted} oversized updates omitted`)}</p>`);
+    }
+    return telegramDetails(summary, blocks.join('\n'));
+}
+function formatClockTimestamp(timestampMs) {
+    const date = new Date(timestampMs);
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
 function createToolBatchState() {
     return {
         openCallIds: new Set(),

package/dist/main.js

@@ -13,7 +13,7 @@ import { acquireProcessLock, LockHeldError } from './lock.js';
 import { readRuntimeStatus, writeRuntimeStatus } from './runtime.js';
 import { buildFoxclawLaunchdPlistText, extractNodePathFromLaunchdPlist, } from './launchd.js';
 import { buildFoxclawSystemdUnitText, buildSystemdRestartHelperArgs, cgroupContainsSystemdUnit, refreshFoxclawExecStartDropIns, removeFoxclawExecStartDropIns, } from './systemd.js';
-import { createSelfUpdateRuntime, inferPnpmHomeFromEntryPoint, performSelfUpdate, readSelfUpdateStatus, writeSelfUpdateStatus, } from './update.js';
+import { clearPendingClusterUpdateBroadcast, createSelfUpdateRuntime, inferPnpmHomeFromEntryPoint, performSelfUpdate, readPendingClusterUpdateBroadcast, readSelfUpdateStatus, writeSelfUpdateStatus, } from './update.js';
 const rawCommand = process.argv[2];
 const command = rawCommand || 'serve';
 loadEnv();
@@ -31,6 +31,86 @@ const PROXY_ENV_KEYS = [
 ];
 const STANDARD_NODE_PROXY_ENV_KEYS = ['HTTP_PROXY', 'HTTPS_PROXY', 'http_proxy', 'https_proxy'];
 const LOCAL_AUTH_REFRESH_LEASE_TTL_MS = 10 * 60_000;
+const CLUSTER_UPDATE_BROADCAST_PATH = path.join(APP_HOME, 'runtime', 'pending-cluster-update-broadcast.json');
+function createClusterUpdateScheduler(options) {
+    let pending = null;
+    let timer = null;
+    const scheduleRetry = () => {
+        if (timer)
+            return;
+        timer = setTimeout(() => {
+            timer = null;
+            void tryLaunch().catch((error) => {
+                options.logger.warn('cluster.update.launch_failed', { error: serializeError(error) });
+                scheduleRetry();
+            });
+        }, 30_000);
+        timer.unref();
+    };
+    const tryLaunch = async () => {
+        if (!pending)
+            return;
+        const source = pending;
+        if (source.targetVersion && source.targetVersion === options.currentVersion()) {
+            options.logger.info('cluster.update.skipped_current', { targetVersion: source.targetVersion, requestId: source.requestId });
+            pending = null;
+            return;
+        }
+        if (!options.canUpdate()) {
+            scheduleRetry();
+            return;
+        }
+        pending = null;
+        options.logger.info('cluster.update.starting', {
+            requestId: source.requestId,
+            sourceNodeId: source.nodeId,
+            sourceLabel: source.label ?? null,
+            targetVersion: source.targetVersion,
+        });
+        await options.selfUpdater.launch(`cluster:${source.nodeId}:${source.requestId}`, 'zh');
+    };
+    return {
+        schedule: async (source) => {
+            if (source.targetVersion && source.targetVersion === options.currentVersion()) {
+                return { accepted: false, reason: `already at ${source.targetVersion}` };
+            }
+            if (pending?.requestId === source.requestId) {
+                return { accepted: false, reason: 'update request is already scheduled' };
+            }
+            pending = source;
+            if (options.canUpdate()) {
+                void tryLaunch().catch((error) => {
+                    options.logger.warn('cluster.update.launch_failed', { error: serializeError(error) });
+                    scheduleRetry();
+                });
+            }
+            else {
+                scheduleRetry();
+            }
+            return { accepted: true, reason: options.canUpdate() ? 'starting when updater accepts the request' : 'queued until runtime is idle' };
+        },
+    };
+}
+async function publishPendingClusterUpdateBroadcast(authSync, logger) {
+    if (!authSync)
+        return;
+    const pending = readPendingClusterUpdateBroadcast(CLUSTER_UPDATE_BROADCAST_PATH);
+    if (!pending)
+        return;
+    try {
+        const result = await authSync.publishServiceUpdateRequest(pending.targetVersion);
+        clearPendingClusterUpdateBroadcast(CLUSTER_UPDATE_BROADCAST_PATH);
+        logger.info('cluster.update.broadcast_sent', {
+            targetVersion: pending.targetVersion,
+            fromVersion: pending.fromVersion,
+            sent: result.sent,
+            peers: result.peers,
+        });
+    }
+    catch (error) {
+        logger.warn('cluster.update.broadcast_failed', { error: serializeError(error) });
+    }
+}
 function createLocalAuthRefreshLease() {
     let active = null;
     const expire = () => {
@@ -98,6 +178,7 @@ async function main() {
             entryPoint,
             nodePath: process.execPath,
             version: readPackageVersion(),
+            clusterBroadcastFile: CLUSTER_UPDATE_BROADCAST_PATH,
             ...(process.env.CODEX_CLI_BIN || resolveCommand('codex')
                 ? { codexCliBin: process.env.CODEX_CLI_BIN || resolveCommand('codex') }
                 : {}),
@@ -129,7 +210,12 @@ async function main() {
             console.log('No runtime status found.');
             process.exit(1);
         }
-        console.log(JSON.stringify(status, null, 2));
+        if (process.argv.slice(3).includes('--json')) {
+            console.log(JSON.stringify(status, null, 2));
+        }
+        else {
+            console.log(formatRuntimeStatusSummary(status));
+        }
         return;
     }
     if (command === 'doctor') {
@@ -183,6 +269,77 @@ Usage:
   foxclaw --version
   foxclaw --help`);
 }
+function formatRuntimeStatusSummary(status) {
+    const lines = [];
+    const age = formatAge(status.updatedAt);
+    lines.push(`FoxClaw status: ${status.running ? 'running' : 'stopped'}${status.connected ? ', connected' : ', disconnected'}${age ? ` (${age})` : ''}`);
+    if (status.userAgent) {
+        lines.push(`Codex: ${status.userAgent}`);
+    }
+    if (status.codexAppServer) {
+        lines.push(`App server: ${status.codexAppServer.running ? 'running' : 'stopped'}${status.codexAppServer.pid ? ` pid=${status.codexAppServer.pid}` : ''}${status.codexAppServer.port ? ` port=${status.codexAppServer.port}` : ''}`);
+    }
+    lines.push(`Work: active ${status.activeTurns}, queued ${status.queuedTurns}, approvals ${status.pendingApprovals}, questions ${status.pendingUserInputs}`);
+    if (status.bots?.length) {
+        const activeBots = status.bots
+            .filter(bot => bot.activeTurns > 0 || !bot.connected)
+            .map(bot => `${bot.username ? `@${bot.username}` : bot.id}:${bot.connected ? `${bot.activeTurns} active` : 'offline'}`);
+        lines.push(`Bots: ${status.bots.length}${activeBots.length ? ` (${activeBots.join(', ')})` : ''}`);
+    }
+    else if (status.botUsername) {
+        lines.push(`Bot: @${status.botUsername}`);
+    }
+    if (status.weixinRuntime) {
+        lines.push(`Weixin: ${status.weixinRuntime.connected ? 'connected' : 'disconnected'}, active ${status.weixinRuntime.activeTurns}`);
+    }
+    if (status.authSync?.enabled) {
+        const failures = status.authSync.candidateFailures?.length ?? 0;
+        lines.push(`Auth sync: peers ${status.authSync.peers.length}, pending imports ${status.authSync.pendingImports}, failures ${failures}${status.authSync.lastReceivedAt ? `, last received ${formatAge(status.authSync.lastReceivedAt)}` : ''}`);
+        if (status.authSync.lastError) {
+            lines.push(`Auth sync error: ${status.authSync.lastError}`);
+        }
+        const latestFailure = status.authSync.candidateFailures?.[0];
+        if (latestFailure) {
+            lines.push(`Latest auth failure: ${latestFailure.candidateName}: ${truncateStatusLine(latestFailure.reason, 140)}`);
+        }
+    }
+    if (status.authMirror) {
+        lines.push(`Auth mirror: ${status.authMirror.candidateName} from ${status.authMirror.sourceLabel} ${formatAge(status.authMirror.syncedAt)}`);
+    }
+    if (status.authProactiveRefresh) {
+        lines.push(`Auth refresh: ${status.authProactiveRefresh.state}${status.authProactiveRefresh.finishedAt ? ` ${formatAge(status.authProactiveRefresh.finishedAt)}` : ''}`);
+    }
+    if (status.lastUpdate) {
+        lines.push(`Last update: ${status.lastUpdate.fromVersion} -> ${status.lastUpdate.toVersion ?? 'unknown'} ${formatAge(status.lastUpdate.updatedAt)}`);
+    }
+    if (status.lastError) {
+        lines.push(`Last error: ${truncateStatusLine(status.lastError, 160)}`);
+    }
+    lines.push('Use `foxclaw status --json` for full raw status.');
+    return lines.join('\n');
+}
+function formatAge(value) {
+    if (!value)
+        return '';
+    const ms = Date.now() - Date.parse(value);
+    if (!Number.isFinite(ms))
+        return value;
+    const seconds = Math.max(0, Math.round(ms / 1000));
+    if (seconds < 60)
+        return `${seconds}s ago`;
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 48)
+        return `${hours}h ago`;
+    const days = Math.round(hours / 24);
+    return `${days}d ago`;
+}
+function truncateStatusLine(value, maxLength) {
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    return normalized.length <= maxLength ? normalized : `${normalized.slice(0, Math.max(0, maxLength - 1))}…`;
+}
 async function runServeCli() {
     const [{ BridgeMessagingRouter }, { TelegramMessagingPort }, { WeixinChannelAdapter }, { WeixinMessagingPort }, { attachIlinkRuntimeFromBridgeLogger }, { loadWeixinAccount }, { Logger }, { BridgeStore }, { TelegramGateway }, { CodexAppClient }, { BridgeSessionCore }, { TelegramChannelAdapter }, { AuthCandidateMirror }, { CrossNodeAuthSync },] = await Promise.all([
         import('./channels/bridge_messaging_router.js'),
@@ -330,6 +487,13 @@ async function runServeCli() {
             const authSyncLocalIdle = () => runtimes.every((runtime) => runtime.core.isIdleForServiceUpdate())
                 && (!activeWeixinCore || activeWeixinCore.isIdleForServiceUpdate())
                 && mirror.isIdle();
+            const clusterUpdateScheduler = createClusterUpdateScheduler({
+                selfUpdater,
+                canUpdate: () => authSyncLocalIdle()
+                    && (authSync ? authSync.isIdle() : localAuthRefreshLease.isIdle()),
+                currentVersion: readPackageVersion,
+                logger,
+            });
             const coordinator = {
                 canSelfUpdate: () => authSyncLocalIdle()
                     && (authSync ? authSync.isIdle() : localAuthRefreshLease.isIdle()),
@@ -453,6 +617,7 @@ async function runServeCli() {
                         }
                         return { ok: true, deleted: true, reason: source.reason ?? null };
                     },
+                    scheduleServiceUpdate: (source) => clusterUpdateScheduler.schedule(source),
                     isIdle: authSyncLocalIdle,
                     notify: createAuthSyncNotifier(store, authSyncTransportBot.bot, authNotificationAggregator, {
                         quietAuthPoolMode: () => config.authAutoDeleteNeedsRepair,
@@ -463,6 +628,7 @@ async function runServeCli() {
                 activeAuthSync = authSync;
                 attachTelegramAuthSync(authSyncTransportBot.bot, authSync, config, logger);
                 authSync.start();
+                void publishPendingClusterUpdateBroadcast(authSync, logger);
             }
             mirror.start();
             process.on('unhandledRejection', (error) => {
@@ -522,6 +688,13 @@ async function runServeCli() {
         const singleLocalAuthRefreshLease = createLocalAuthRefreshLease();
         const singleAuthSyncLocalIdle = () => Boolean(core?.isIdleForServiceUpdate())
             && (!singleMirror || singleMirror.isIdle());
+        const singleClusterUpdateScheduler = createClusterUpdateScheduler({
+            selfUpdater,
+            canUpdate: () => singleAuthSyncLocalIdle()
+                && (singleAuthSync ? singleAuthSync.isIdle() : singleLocalAuthRefreshLease.isIdle()),
+            currentVersion: readPackageVersion,
+            logger,
+        });
         const singleCoordinator = config.authSyncEnabled ? {
             canSelfUpdate: () => singleAuthSyncLocalIdle()
                 && (singleAuthSync ? singleAuthSync.isIdle() : singleLocalAuthRefreshLease.isIdle()),
@@ -614,6 +787,7 @@ async function runServeCli() {
                     await core.handleExternalCodexAuthCandidateDeleted(candidateName, source.reason ?? null);
                     return { ok: true, deleted: true, reason: source.reason ?? null };
                 },
+                scheduleServiceUpdate: (source) => singleClusterUpdateScheduler.schedule(source),
                 isIdle: singleAuthSyncLocalIdle,
                 notify: createAuthSyncNotifier(store, bot, authNotificationAggregator, {
                     quietAuthPoolMode: () => config.authAutoDeleteNeedsRepair,
@@ -624,6 +798,7 @@ async function runServeCli() {
             activeAuthSync = singleAuthSync;
             attachTelegramAuthSync(bot, singleAuthSync, config, logger);
             singleAuthSync.start();
+            void publishPendingClusterUpdateBroadcast(singleAuthSync, logger);
             singleMirror.start();
         }
         const telegram = new TelegramChannelAdapter(core);
@@ -791,6 +966,8 @@ function isQuietAuthPoolNotification(event) {
         case 'recovery_failed':
         case 'pull_request_received':
         case 'pull_response_sent':
+        case 'service_update_sent':
+        case 'service_update_received':
             return true;
         default:
             return false;
@@ -871,6 +1048,15 @@ function formatAuthSyncNotification(locale, event) {
                 return `收到 peer 的 auth 查询：${event.candidateName}\nPeer：${event.peer}，请求节点：${event.requesterNodeId}`;
             case 'pull_response_sent':
                 return `已回应 peer 的 auth 查询：${event.candidateName}\nPeer：${event.peer}\n结果：${formatPullResponseResult(event.result, event.reason, locale)}`;
+            case 'service_update_sent':
+                return `跨节点升级广播已发出：${event.targetVersion ?? 'latest'}\nRequest：${event.requestId}\nPeer：${peers}`;
+            case 'service_update_received':
+                return [
+                    `收到跨节点升级请求：${event.targetVersion ?? 'latest'}`,
+                    `来源：${formatSource(event.sourceLabel, event.sourceNodeId)}，peer ${event.peer}`,
+                    `处理：${event.accepted ? '已安排本机空闲后升级' : '已跳过'}`,
+                    event.reason ? `原因：${event.reason}` : null,
+                ].filter(Boolean).join('\n');
             case 'sync_error':
                 return `auth sync 需要注意：\n${event.reason}`;
         }
@@ -937,6 +1123,15 @@ function formatAuthSyncNotification(locale, event) {
             return `Received peer auth recovery request: ${event.candidateName}\nPeer: ${event.peer}, requester node: ${event.requesterNodeId}`;
         case 'pull_response_sent':
             return `Replied to peer auth recovery request: ${event.candidateName}\nPeer: ${event.peer}\nResult: ${formatPullResponseResult(event.result, event.reason, locale)}`;
+        case 'service_update_sent':
+            return `Cross-node update broadcast sent: ${event.targetVersion ?? 'latest'}\nRequest: ${event.requestId}\nPeers: ${peers}`;
+        case 'service_update_received':
+            return [
+                `Received cross-node update request: ${event.targetVersion ?? 'latest'}`,
+                `Source: ${formatSource(event.sourceLabel, event.sourceNodeId)}, peer ${event.peer}`,
+                `Action: ${event.accepted ? 'scheduled local update when idle' : 'skipped'}`,
+                event.reason ? `Reason: ${event.reason}` : null,
+            ].filter(Boolean).join('\n');
         case 'sync_error':
             return `Auth sync needs attention:\n${event.reason}`;
     }

package/dist/update.d.ts

@@ -42,6 +42,7 @@ interface PerformSelfUpdateOptions {
     nodePath: string;
     version: string;
     notificationFile?: string;
+    clusterBroadcastFile?: string;
     codexCliBin?: string;
     env?: NodeJS.ProcessEnv;
 }
@@ -57,6 +58,11 @@ export interface SelfUpdateOutcome {
     toVersion: string | null;
     error: string | null;
 }
+export interface PendingClusterUpdateBroadcast {
+    targetVersion: string | null;
+    fromVersion: string;
+    updatedAt: string;
+}
 export declare function selfUpdateStatusPath(statusPath: string): string;
 export declare function inferPnpmHomeFromEntryPoint(entryPoint: string): string | null;
 export declare function resolveSelfUpdateInstaller(entryPoint: string, nodePath?: string, exists?: (target: string) => boolean, env?: NodeJS.ProcessEnv): SelfUpdateInstaller;
@@ -76,5 +82,8 @@ export declare function buildSelfUpdateLaunchCommand(options: {
     unitName?: string;
 }): SelfUpdateLaunchCommand;
 export declare function performSelfUpdate(options: PerformSelfUpdateOptions): SelfUpdateOutcome;
+export declare function readPendingClusterUpdateBroadcast(filePath: string): PendingClusterUpdateBroadcast | null;
+export declare function writePendingClusterUpdateBroadcast(filePath: string, value: PendingClusterUpdateBroadcast): void;
+export declare function clearPendingClusterUpdateBroadcast(filePath: string): void;
 export declare function extractReleaseNotes(changelog: string, version: string, locale: AppLocale): string[] | null;
 export {};

package/dist/update.js

@@ -308,6 +308,13 @@ export function performSelfUpdate(options) {
         console.log('[UPDATE] Running checks and restarting the FoxClaw service...');
         runInherited(options.nodePath, [updatedEntryPoint, 'start'], installerEnv);
         completeNotification(options.notificationFile, 'succeeded', toVersion, codexUpdate, null, releaseNotes);
+        if (options.clusterBroadcastFile && env.FOXCLAW_SUPPRESS_UPDATE_BROADCAST !== '1') {
+            writePendingClusterUpdateBroadcast(options.clusterBroadcastFile, {
+                targetVersion: toVersion,
+                fromVersion: options.version,
+                updatedAt: new Date().toISOString(),
+            });
+        }
         console.log(`[OK] FoxClaw updated and restarted: ${options.version} -> ${toVersion}`);
         return {
             ok: true,
@@ -328,6 +335,34 @@ export function performSelfUpdate(options) {
         };
     }
 }
+export function readPendingClusterUpdateBroadcast(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        if ((typeof parsed.targetVersion !== 'string' && parsed.targetVersion !== null)
+            || typeof parsed.fromVersion !== 'string'
+            || typeof parsed.updatedAt !== 'string'
+            || !Number.isFinite(Date.parse(parsed.updatedAt))) {
+            return null;
+        }
+        return {
+            targetVersion: parsed.targetVersion ?? null,
+            fromVersion: parsed.fromVersion,
+            updatedAt: parsed.updatedAt,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function writePendingClusterUpdateBroadcast(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const temporaryFile = `${filePath}.${process.pid}.tmp`;
+    fs.writeFileSync(temporaryFile, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    fs.renameSync(temporaryFile, filePath);
+}
+export function clearPendingClusterUpdateBroadcast(filePath) {
+    fs.rmSync(filePath, { force: true });
+}
 function updateManagedCodexCli(codexCliBin, nodePath, env) {
     const fromVersion = readCodexCliVersion(codexCliBin, env);
     if (!codexCliBin) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.5.41",
+  "version": "0.5.43",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",