@foxden-app/foxclaw 0.4.16 → 0.5.0

package/.env.example

@@ -40,7 +40,9 @@ CODEX_CLI_BIN=/absolute/path/to/codex
 # Optional cross-node Codex auth sync.
 # Disabled by default. When enabled, FoxClaw uses Telegram Bot-to-Bot private
 # messages to move encrypted auth bundles between nodes. Enable Bot-to-Bot
-# Communication Mode for the participating bots in BotFather first.
+# Communication Mode for each node's contact bot in BotFather first.
+# In TG_BOT_TOKENS multi-bot mode, the first token is the default contact bot;
+# put the node's contact token first and list peer contact @usernames below.
 # AUTH_SYNC_ENABLED=true
 # AUTH_SYNC_KEY=<shared-key-with-at-least-32-bytes>
 # AUTH_SYNC_PEERS=@other_node_bot,@third_node_bot

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 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.0 - 2026-06-04
+
+### 中文
+- 明确跨节点 auth 同步推荐架构：每节点一个联系人 bot；多 bot 模式默认使用 `TG_BOT_TOKENS` 的第一个 token 作为联系人，同节点其他 bot 继续走本机 auth 镜像。
+- `/auth sync status` 和 `/status` 现在显示联系人 bot，避免在非联系人 bot 上执行命令时误判实际发包身份。
+- `/auth sync test` 升级为等待 peer 加密 pong 的真实握手，并显示未回应 peer；同时文档补充 BotFather MiniApp 入口、不要误进 Configure Mini App，以及 `push all` 只代表发送成功、不代表对端已导入。
+- 跨节点 auth 同步现在会通过联系人 bot 私聊通知发送、接收、排队、导入、跳过、失败和恢复查询进度；所有 peer 都无法提供可用副本时会明确提示人工介入。
+
+### English
+- Clarified the recommended cross-node auth sync topology: one contact bot per node. In multi-bot mode, the first `TG_BOT_TOKENS` entry is the default contact while other same-node bots keep using local auth mirroring.
+- `/auth sync status` and `/status` now show the contact bot so commands run from a non-contact bot no longer obscure the actual sender identity.
+- `/auth sync test` now waits for encrypted peer pong replies and reports missing peers. Documentation now covers the BotFather MiniApp entry point, avoids the Configure Mini App confusion, and explains that `push all` only proves send success, not peer import.
+- Cross-node auth sync now sends contact-bot private notifications for send, receive, queue, import, skip, failure, and recovery query progress; it explicitly asks for manual intervention when every peer lacks an importable copy.
+
 ## 0.4.16 - 2026-06-04
 
 ### 中文

package/README.md

@@ -212,7 +212,7 @@ TG_BOT_TOKEN=123456:token_a
 
 FoxClaw 仍然只运行一个系统服务。默认情况下，它会为每个 bot 启动独立 `codex app-server` 和独立 `CODEX_HOME`。因此 A 私聊运行 turn 时，B 私聊仍可独立切换自己的 `/auth`。候选凭据由 FoxClaw 在登录或刷新在线验证后镜像同步；切换或重载前还会从其他 Codex home 恢复同账号较新凭据。各 bot 的当前选择互不影响。每个 bot 首次私聊发送 `/help` 和 `/status`；`/auth` 会标明正在操作的 bot runtime，`/status` 会列出全部 bot 的连接、runtime 类型、当前 auth 和活动 turn 摘要。
 
-多台机器共享同一合法账号池时，可以启用可选跨节点 auth 同步：`AUTH_SYNC_ENABLED=true`、`AUTH_SYNC_KEY` 和 `AUTH_SYNC_PEERS=@peer_bot`。FoxClaw 会通过 Telegram Bot-to-Bot 私聊传输加密 auth 包；本机验证刷新后主动 push，发现本机候选失效时主动 pull peer 已持有的有效副本。跨节点恢复不会自动刷新 token，`/auth refresh all confirm` 会先申请跨节点刷新锁。完整配置、`@BotFather` 操作和验证步骤见 [跨节点 auth 同步配置指南](./docs/zh/cross-node-auth-sync.md)。
+多台机器共享同一合法账号池时，可以启用可选跨节点 auth 同步：`AUTH_SYNC_ENABLED=true`、`AUTH_SYNC_KEY` 和 `AUTH_SYNC_PEERS=@peer_contact_bot`。推荐每台机器只选一个联系人 bot；同一节点内的其他 bot 继续走本机 auth 镜像。多 bot 模式下，默认用 `TG_BOT_TOKENS` 的第一个 token 作为联系人 bot。FoxClaw 会通过 Telegram Bot-to-Bot 私聊传输加密 auth 包；本机验证刷新后主动 push，发现本机候选失效时主动 pull peer 已持有的有效副本，并在联系人 bot 私聊里报告发送、接收、排队、导入、失败和人工介入提示。跨节点恢复不会自动刷新 token，`/auth refresh all confirm` 会先申请跨节点刷新锁。完整配置、`@BotFather` 操作和验证步骤见 [跨节点 auth 同步配置指南](./docs/zh/cross-node-auth-sync.md)。
 
 如果你需要一路 Telegram 与终端互通 session，把同一个 token 同时填入 `TG_BOT_TOKENS` 和 `TG_BOT_TOKEN`。这个 bot 使用默认 `CODEX_HOME`（未设置时通常是 `~/.codex`）和默认 auth，因此能看到终端 Codex 的本地线程；它不再享有隔离 runtime 的“互不影响”保证，切换 auth 会影响终端和其他默认 runtime。
 

package/README_EN.md

@@ -212,7 +212,7 @@ TG_BOT_TOKEN=123456:token_a
 
 FoxClaw remains one system service. By default, it starts an independent `codex app-server` and `CODEX_HOME` for each bot. While bot A is running a turn, bot B can switch its own `/auth` selection. Candidate credentials are mirrored only after online-validated login or refresh; before switching or reloading, FoxClaw also restores a newer same-account credential from another Codex home when available. Current selections remain independent. Send `/help` and `/status` in a private chat with each bot after installation; `/auth` names the runtime being managed, and `/status` summarizes every bot's connection, runtime type, selected auth, and active turns.
 
-When multiple machines share the same legally owned account pool, optional cross-node auth sync can be enabled with `AUTH_SYNC_ENABLED=true`, `AUTH_SYNC_KEY`, and `AUTH_SYNC_PEERS=@peer_bot`. FoxClaw sends encrypted auth bundles through Telegram Bot-to-Bot private messages. A locally verified refresh is pushed to peers, and a node with a bad local candidate can pull an already-held valid peer copy. Cross-node recovery never auto-refreshes tokens; `/auth refresh all confirm` first requests a cross-node refresh lease. For full config, `@BotFather` operations, and verification steps, read the [Cross-Node Auth Sync Setup Guide](./docs/cross-node-auth-sync.md).
+When multiple machines share the same legally owned account pool, optional cross-node auth sync can be enabled with `AUTH_SYNC_ENABLED=true`, `AUTH_SYNC_KEY`, and `AUTH_SYNC_PEERS=@peer_contact_bot`. The recommended topology is one contact bot per node; other bots on the same node continue to use local auth mirroring. In multi-bot mode, the first token in `TG_BOT_TOKENS` is the default contact bot. FoxClaw sends encrypted auth bundles through Telegram Bot-to-Bot private messages. A locally verified refresh is pushed to peers, and a node with a bad local candidate can pull an already-held valid peer copy. The contact bot private chat reports send, receive, queue, import, failure, and manual-intervention states. Cross-node recovery never auto-refreshes tokens; `/auth refresh all confirm` first requests a cross-node refresh lease. For full config, `@BotFather` operations, and verification steps, read the [Cross-Node Auth Sync Setup Guide](./docs/cross-node-auth-sync.md).
 
 To keep one Telegram bot interoperable with terminal Codex sessions, put the same token in both `TG_BOT_TOKENS` and `TG_BOT_TOKEN`. That bot uses the default `CODEX_HOME` (usually `~/.codex` when unset) and default auth, so it can see local terminal sessions. It no longer has the isolated runtime guarantee: `/auth` switches also affect the terminal and other default runtimes.
 

package/dist/auth/cross_node_sync.d.ts

@@ -3,6 +3,7 @@ import type { AuthMirrorCandidateRecord, AuthMirrorImportResult } from './mirror
 export interface AuthSyncConfig {
     enabled: boolean;
     transport: 'telegram-private';
+    transportLabel?: string | null;
     key: string | null;
     peers: string[];
     nodeId: string | null;
@@ -18,6 +19,7 @@ export interface AuthSyncStatus {
     enabled: boolean;
     nodeId: string | null;
     transport: 'telegram-private';
+    transportLabel: string | null;
     peers: string[];
     pendingImports: number;
     lastSentAt: string | null;
@@ -33,6 +35,101 @@ export interface AuthSyncValidationResult {
     ok: boolean;
     reason?: string | null;
 }
+export type AuthSyncRemoteImportMode = 'push' | 'pull';
+export type AuthSyncPullResponseResult = 'sent' | 'candidate_not_found' | 'account_mismatch' | 'not_newer';
+export type AuthSyncNotification = {
+    kind: 'candidate_publish_started';
+    candidateName: string;
+    peers: string[];
+} | {
+    kind: 'candidate_publish_completed';
+    candidateName: string;
+    peers: string[];
+} | {
+    kind: 'candidate_publish_failed';
+    candidateName: string;
+    peers: string[];
+    reason: string;
+} | {
+    kind: 'push_all_started';
+    candidateCount: number;
+    peers: string[];
+} | {
+    kind: 'push_all_completed';
+    sent: number;
+    skipped: number;
+    peers: string[];
+} | {
+    kind: 'push_all_failed';
+    sent: number;
+    skipped: number;
+    peers: string[];
+    reason: string;
+} | {
+    kind: 'remote_bundle_received';
+    candidateName: string;
+    sourceNodeId: string;
+    sourceLabel: string;
+    peer: string;
+    queued: boolean;
+    queueLength: number;
+} | {
+    kind: 'remote_import_imported';
+    candidateName: string;
+    sourceNodeId: string;
+    sourceLabel: string;
+    peer: string;
+    mode: AuthSyncRemoteImportMode;
+} | {
+    kind: 'remote_import_skipped';
+    candidateName: string;
+    sourceNodeId: string;
+    sourceLabel: string;
+    peer: string;
+    mode: AuthSyncRemoteImportMode;
+    reason: string;
+} | {
+    kind: 'remote_import_failed';
+    candidateName: string;
+    sourceNodeId: string;
+    sourceLabel: string;
+    peer: string;
+    mode: AuthSyncRemoteImportMode;
+    reason: string;
+} | {
+    kind: 'recovery_started';
+    candidateName: string;
+    peers: string[];
+} | {
+    kind: 'recovery_peer_empty';
+    candidateName: string;
+    peer: string;
+    reason: string;
+} | {
+    kind: 'recovery_peer_bundle_received';
+    candidateName: string;
+    peer: string;
+    sourceNodeId: string;
+} | {
+    kind: 'recovery_failed';
+    candidateName: string;
+    peers: string[];
+    reason: string;
+} | {
+    kind: 'pull_request_received';
+    candidateName: string;
+    peer: string;
+    requesterNodeId: string;
+} | {
+    kind: 'pull_response_sent';
+    candidateName: string;
+    peer: string;
+    result: AuthSyncPullResponseResult;
+    reason: string | null;
+} | {
+    kind: 'sync_error';
+    reason: string;
+};
 export interface AuthSyncImportCallbacks {
     readLocalCandidate: (candidateName: string) => Promise<AuthMirrorCandidateRecord | null>;
     listLocalCandidates: () => Promise<AuthMirrorCandidateRecord[]>;
@@ -42,6 +139,7 @@ export interface AuthSyncImportCallbacks {
         label?: string | null;
     }) => Promise<AuthMirrorImportResult>;
     isIdle: () => boolean;
+    notify?: (event: AuthSyncNotification) => Promise<void>;
 }
 export interface AuthSyncTransport {
     send: (peer: string, envelope: string) => Promise<void>;
@@ -51,6 +149,11 @@ export interface AuthSyncLeaseResult {
     leaseId: string | null;
     reason?: string | null;
 }
+export interface AuthSyncTestResult {
+    sent: number;
+    replied: number;
+    missing: string[];
+}
 export declare class CrossNodeAuthSync {
     private readonly config;
     private readonly logger;
@@ -63,10 +166,12 @@ export declare class CrossNodeAuthSync {
     private readonly pendingImports;
     private readonly pendingPulls;
     private readonly pendingLeases;
+    private readonly pendingTests;
     private seenNonces;
     private timer;
     private activeRemoteLease;
     private activeLocalLease;
+    private lastNotifiedError;
     private state;
     constructor(config: AuthSyncConfig, logger: Logger, transport: AuthSyncTransport, callbacks: AuthSyncImportCallbacks);
     initialize(): Promise<void>;
@@ -86,13 +191,12 @@ export declare class CrossNodeAuthSync {
     }): Promise<boolean>;
     acquireRefreshLease(reason: string): Promise<AuthSyncLeaseResult>;
     releaseRefreshLease(leaseId: string | null): Promise<void>;
-    testPeers(): Promise<{
-        sent: number;
-    }>;
+    testPeers(): Promise<AuthSyncTestResult>;
     handleIncomingEnvelope(rawEnvelope: string, peer: AuthSyncPeerIdentity): Promise<boolean>;
     private handleMessage;
     private handlePullRequest;
     private handlePullResponse;
+    private markPullPeerUnavailable;
     private handleDigest;
     private handleLeaseRequest;
     private handleLeaseReply;
@@ -101,12 +205,18 @@ export declare class CrossNodeAuthSync {
     private validateAndImport;
     private sendToAll;
     private sendToPeer;
+    private handleTestPong;
+    private finishPendingTest;
     private sealEnvelope;
     private openEnvelope;
     private isReady;
     private isAllowedPeer;
+    private matchConfiguredPeer;
     private expireLeases;
     private recordError;
+    private rejectImport;
+    private notify;
+    private notifyError;
     private writeState;
 }
 export declare function readAccessTokenExpiresAtMs(raw: string): number | null;