@foxden-app/foxclaw 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 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.3 - 2026-06-04
+
+### 中文
+- 修复 0.5.2 中 `/update` 完成回报丢失的问题：Linux 自升级子进程现在通过独立的 user systemd transient service 运行，不再留在 `foxclaw.service` control group 里，因此 `KillMode=control-group` 重启服务时不会提前杀掉 updater。
+- 保留 `KillMode=control-group` 的 app-server 清理能力，同时让升级进程能在服务重启后继续写入完成状态，由新服务启动后的轮询发送 Telegram 成功/失败回报。
+
+### English
+- Fixed missing `/update` completion reports in 0.5.2: on Linux the self-update worker now runs in a separate user systemd transient service instead of the `foxclaw.service` control group, so `KillMode=control-group` no longer kills the updater during service restart.
+- Kept `KillMode=control-group` app-server cleanup while allowing the updater to write its final status after restart; the newly started service polls that status and sends the Telegram success/failure report.
+
+## 0.5.2 - 2026-06-04
+
+### 中文
+- Linux systemd unit 改为停止整个 control group，避免升级或重启 FoxClaw 后旧的 `codex app-server --listen` 子进程残留。
+- 启动时自动修复 `auth.json -> .auth-sync-validate-*` 临时验证 symlink 残留，恢复到 mirror 状态候选或同目录最近修改且可解析的真实 `auth.json_*` 候选，并清理临时文件。
+- 跨节点 auth 同步把单候选验证/导入失败记录为“候选失败”，不再污染全局 `lastError`；`/status` 和 `/auth sync status` 会分开展示同步系统错误与候选失败。
+- 手动 `/auth` 切换和 `/auth reload` 只做同节点本地镜像恢复，不再主动向跨节点 peer 查询；只有自动 auth 故障恢复才会跨节点 pull。
+- auth 恢复超时通知补充 request id、候选名、peer、等待时长，并标明等待期间可达但本请求超时的 peer。
+
+### English
+- Changed the Linux systemd unit to stop the whole service control group so FoxClaw upgrades or restarts no longer leave old `codex app-server --listen` children behind.
+- Added startup recovery for `auth.json -> .auth-sync-validate-*` validation symlink leftovers, restoring to the mirror-status candidate or the newest parseable real `auth.json_*` candidate in the same directory and removing stale temp files.
+- Cross-node auth sync now records per-candidate validation/import failures as candidate failures instead of global `lastError`; `/status` and `/auth sync status` show sync-system errors separately from candidate failures.
+- Manual `/auth` switching and `/auth reload` now recover from same-node local mirrors only and no longer query cross-node peers; cross-node pull is reserved for automatic auth-failure recovery.
+- Auth recovery timeout notifications now include request id, candidate name, peers, wait duration, and whether a peer was reachable during the timed-out request.
+
 ## 0.5.1 - 2026-06-04
 
 ### 中文

package/dist/auth/cross_node_sync.d.ts

@@ -29,8 +29,18 @@ export interface AuthSyncStatus {
     lastPullAt: string | null;
     lastPullCandidate: string | null;
     lastError: string | null;
+    candidateFailures: AuthSyncCandidateFailure[];
     activeLeaseId: string | null;
 }
+export interface AuthSyncCandidateFailure {
+    candidateName: string;
+    reason: string;
+    sourceNodeId: string | null;
+    sourceLabel: string | null;
+    peer: string | null;
+    mode: AuthSyncRemoteImportMode;
+    updatedAt: string;
+}
 export interface AuthSyncValidationResult {
     ok: boolean;
     reason?: string | null;
@@ -99,7 +109,9 @@ export type AuthSyncNotification = {
 } | {
     kind: 'recovery_started';
     candidateName: string;
+    requestId: string;
     peers: string[];
+    timeoutMs: number;
 } | {
     kind: 'recovery_peer_empty';
     candidateName: string;
@@ -113,8 +125,11 @@ export type AuthSyncNotification = {
 } | {
     kind: 'recovery_failed';
     candidateName: string;
+    requestId?: string;
     peers: string[];
     reason: string;
+    waitMs?: number;
+    peerReachability?: AuthSyncPeerReachability[];
 } | {
     kind: 'pull_request_received';
     candidateName: string;
@@ -141,6 +156,11 @@ export interface AuthSyncImportCallbacks {
     isIdle: () => boolean;
     notify?: (event: AuthSyncNotification) => Promise<void>;
 }
+export interface AuthSyncPeerReachability {
+    peer: string;
+    reachableDuringRequest: boolean;
+    lastReceivedAt: string | null;
+}
 export interface AuthSyncTransport {
     send: (peer: string, envelope: string) => Promise<void>;
 }
@@ -168,6 +188,7 @@ export declare class CrossNodeAuthSync {
     private readonly pendingLeases;
     private readonly pendingTests;
     private seenNonces;
+    private lastPeerActivityAt;
     private timer;
     private importProcessorActive;
     private activeRemoteLease;
@@ -216,6 +237,10 @@ export declare class CrossNodeAuthSync {
     private expireLeases;
     private recordError;
     private rejectImport;
+    private recordCandidateFailure;
+    private clearCandidateFailure;
+    private notePeerActivity;
+    private describePeerReachability;
     private notify;
     private notifyError;
     private writeState;

package/dist/auth/cross_node_sync.js

@@ -24,6 +24,7 @@ export class CrossNodeAuthSync {
     pendingLeases = new Map();
     pendingTests = new Map();
     seenNonces = new Map();
+    lastPeerActivityAt = new Map();
     timer = null;
     importProcessorActive = false;
     activeRemoteLease = null;
@@ -37,6 +38,7 @@ export class CrossNodeAuthSync {
         lastPullAt: null,
         lastPullCandidate: null,
         lastError: null,
+        lastCandidateFailures: {},
     };
     constructor(config, logger, transport, callbacks) {
         this.config = config;
@@ -64,6 +66,7 @@ export class CrossNodeAuthSync {
             lastPullAt: stored.lastPullAt ?? null,
             lastPullCandidate: stored.lastPullCandidate ?? null,
             lastError: stored.lastError ?? null,
+            lastCandidateFailures: normalizeCandidateFailures(stored.lastCandidateFailures ?? {}),
         };
         await fs.mkdir(this.config.tempDir, { recursive: true, mode: 0o700 });
         await this.writeState();
@@ -103,6 +106,8 @@ export class CrossNodeAuthSync {
             lastPullAt: this.state.lastPullAt,
             lastPullCandidate: this.state.lastPullCandidate,
             lastError: this.state.lastError,
+            candidateFailures: Object.values(this.state.lastCandidateFailures)
+                .sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt)),
             activeLeaseId: this.activeLocalLease?.leaseId ?? this.activeRemoteLease?.leaseId ?? null,
         };
     }
@@ -188,30 +193,46 @@ export class CrossNodeAuthSync {
             return false;
         const requestId = crypto.randomUUID();
         const peers = [...this.peers];
-        this.notify({ kind: 'recovery_started', candidateName, peers });
+        const startedAt = Date.now();
+        this.notify({ kind: 'recovery_started', candidateName, requestId, peers, timeoutMs: PULL_TIMEOUT_MS });
         const result = await new Promise((resolve) => {
             const timer = setTimeout(() => {
                 const pending = this.pendingPulls.get(requestId);
                 if (pending) {
                     pending.finished = true;
                     this.pendingPulls.delete(requestId);
+                    const waitMs = Date.now() - pending.startedAt;
+                    const peerReachability = this.describePeerReachability(pending.peers, pending.startedAt);
+                    const reason = formatPullTimeoutReason(pending, waitMs, peerReachability);
+                    this.logger.warn('auth.sync.pull_timeout', {
+                        requestId,
+                        candidateName,
+                        peers: pending.peers,
+                        waitMs,
+                        peerReachability,
+                    });
                     this.notify({
                         kind: 'recovery_failed',
                         candidateName,
+                        requestId,
                         peers,
-                        reason: `timed out waiting for ${this.peers.length} auth sync peer response(s)`,
+                        reason,
+                        waitMs,
+                        peerReachability,
                     });
                     resolve(false);
                 }
             }, PULL_TIMEOUT_MS);
             timer.unref();
             this.pendingPulls.set(requestId, {
+                requestId,
                 candidateName,
                 peers,
                 emptyReplies: new Map(),
                 resolve,
                 timer,
                 finished: false,
+                startedAt,
             });
             void this.sendToAll({
                 kind: 'pull.request',
@@ -223,11 +244,15 @@ export class CrossNodeAuthSync {
                 clearTimeout(timer);
                 this.pendingPulls.delete(requestId);
                 this.recordError(`pull request failed: ${formatError(error)}`, false);
+                const waitMs = Date.now() - startedAt;
                 this.notify({
                     kind: 'recovery_failed',
                     candidateName,
+                    requestId,
                     peers: [...this.peers],
-                    reason: formatError(error),
+                    reason: `pull request send failed; requestId=${requestId}; candidate=${candidateName}; peers=${this.peers.join(', ') || 'none'}; waitMs=${waitMs}; error=${formatError(error)}`,
+                    waitMs,
+                    peerReachability: this.describePeerReachability(peers, startedAt),
                 });
                 resolve(false);
             });
@@ -340,6 +365,7 @@ export class CrossNodeAuthSync {
         this.seenNonces.set(nonceKey, Date.now());
         this.state.lastReceivedAt = new Date().toISOString();
         await this.writeState();
+        this.notePeerActivity(normalizePeerIdentity(peer));
         await this.handleMessage(opened.message, opened.sender, peer);
         return true;
     }
@@ -616,6 +642,7 @@ export class CrossNodeAuthSync {
         if (!result.ok) {
             return this.rejectImport(bundle, sourceNodeId, source, fromPeer, mode, `remote candidate import failed for ${bundle.candidateName}: ${result.reason ?? 'unknown'}`);
         }
+        const clearedFailure = this.clearCandidateFailure(bundle.candidateName);
         if (result.imported) {
             this.state.lastImportedAt = new Date().toISOString();
             this.state.lastImportCandidate = bundle.candidateName;
@@ -641,6 +668,9 @@ export class CrossNodeAuthSync {
                 mode,
                 reason: result.reason ?? 'local candidate did not need an update',
             });
+            if (clearedFailure) {
+                await this.writeState();
+            }
         }
         return { ok: true, imported: result.imported, reason: result.reason ?? null };
     }
@@ -767,8 +797,8 @@ export class CrossNodeAuthSync {
             this.notifyError(message);
         }
     }
-    rejectImport(bundle, sourceNodeId, sourceLabel, fromPeer, mode, reason) {
-        this.recordError(reason, false);
+    async rejectImport(bundle, sourceNodeId, sourceLabel, fromPeer, mode, reason) {
+        await this.recordCandidateFailure(bundle, sourceNodeId, sourceLabel, fromPeer, mode, reason);
         this.notify({
             kind: 'remote_import_failed',
             candidateName: bundle.candidateName,
@@ -780,6 +810,51 @@ export class CrossNodeAuthSync {
         });
         return { ok: false, imported: false, reason };
     }
+    async recordCandidateFailure(bundle, sourceNodeId, sourceLabel, fromPeer, mode, reason) {
+        const candidateName = typeof bundle.candidateName === 'string' && bundle.candidateName.trim()
+            ? bundle.candidateName
+            : 'invalid-bundle';
+        this.state.lastCandidateFailures[candidateName] = {
+            candidateName,
+            reason,
+            sourceNodeId,
+            sourceLabel,
+            peer: fromPeer,
+            mode,
+            updatedAt: new Date().toISOString(),
+        };
+        this.state.lastCandidateFailures = pruneCandidateFailures(this.state.lastCandidateFailures);
+        this.logger.warn('auth.sync.candidate_failed', {
+            candidateName,
+            sourceNodeId,
+            sourceLabel,
+            peer: fromPeer,
+            mode,
+            reason,
+        });
+        await this.writeState();
+    }
+    clearCandidateFailure(candidateName) {
+        if (!this.state.lastCandidateFailures[candidateName]) {
+            return false;
+        }
+        delete this.state.lastCandidateFailures[candidateName];
+        return true;
+    }
+    notePeerActivity(peer) {
+        const matchedPeer = this.matchConfiguredPeer(peer) ?? peer;
+        this.lastPeerActivityAt.set(matchedPeer, Date.now());
+    }
+    describePeerReachability(peers, sinceMs) {
+        return peers.map((peer) => {
+            const lastActivityAt = this.lastPeerActivityAt.get(peer) ?? null;
+            return {
+                peer,
+                reachableDuringRequest: lastActivityAt !== null && lastActivityAt >= sinceMs,
+                lastReceivedAt: lastActivityAt === null ? null : new Date(lastActivityAt).toISOString(),
+            };
+        });
+    }
     notify(event) {
         if (!this.callbacks.notify)
             return;
@@ -886,6 +961,46 @@ function hashAccountId(accountId) {
 function sha256(value) {
     return crypto.createHash('sha256').update(value).digest('hex');
 }
+function normalizeCandidateFailures(raw) {
+    const failures = {};
+    for (const [key, value] of Object.entries(raw)) {
+        const candidateName = typeof value.candidateName === 'string' && value.candidateName.trim()
+            ? value.candidateName
+            : key;
+        const reason = typeof value.reason === 'string' ? value.reason : '';
+        const mode = value.mode === 'pull' ? 'pull' : 'push';
+        const updatedAt = typeof value.updatedAt === 'string' && Number.isFinite(Date.parse(value.updatedAt))
+            ? value.updatedAt
+            : new Date().toISOString();
+        if (!candidateName || !reason) {
+            continue;
+        }
+        failures[candidateName] = {
+            candidateName,
+            reason,
+            sourceNodeId: typeof value.sourceNodeId === 'string' ? value.sourceNodeId : null,
+            sourceLabel: typeof value.sourceLabel === 'string' ? value.sourceLabel : null,
+            peer: typeof value.peer === 'string' ? value.peer : null,
+            mode,
+            updatedAt,
+        };
+    }
+    return pruneCandidateFailures(failures);
+}
+function pruneCandidateFailures(failures) {
+    return Object.fromEntries(Object.entries(failures)
+        .sort(([, left], [, right]) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt))
+        .slice(0, 20));
+}
+function formatPullTimeoutReason(pending, waitMs, peerReachability) {
+    const reachable = peerReachability
+        .filter((entry) => entry.reachableDuringRequest)
+        .map((entry) => entry.peer);
+    const reachableSuffix = reachable.length > 0
+        ? `; peer reachable but this request timed out: ${reachable.join(', ')}`
+        : '';
+    return `timed out waiting for ${pending.peers.length} auth sync peer response(s); requestId=${pending.requestId}; candidate=${pending.candidateName}; peers=${pending.peers.join(', ') || 'none'}; waitMs=${waitMs}${reachableSuffix}`;
+}
 function normalizeConfiguredPeer(peer) {
     const value = peer.trim();
     if (!value)

package/dist/auth/mirror.d.ts

@@ -93,6 +93,8 @@ export declare class AuthCandidateMirror {
     private resolveCanonicalCurrentCandidate;
     private findNewestRecord;
     private runtimeLabel;
+    private recoverInterruptedValidationSymlink;
+    private selectValidationRecoveryCandidate;
 }
 export declare function isAuthCandidateName(name: string): boolean;
 export declare function readChatGptAuthRecord(filePath: string): Promise<ChatGptAuthRecord | null>;

package/dist/auth/mirror.js

@@ -23,7 +23,12 @@ export class AuthCandidateMirror {
     async initialize() {
         this.lastStatus = await readMirrorStatus(this.statusPath);
         await fs.mkdir(this.canonicalDir, { recursive: true, mode: 0o700 });
+        await this.recoverInterruptedValidationSymlink(this.canonicalDir);
         await this.ensureCanonicalDefaultCandidate();
+        for (const runtime of this.runtimes) {
+            await fs.mkdir(runtime.authDir, { recursive: true, mode: 0o700 });
+            await this.recoverInterruptedValidationSymlink(runtime.authDir);
+        }
         const candidateNames = await this.collectCandidateNames();
         for (const name of candidateNames) {
             await this.reconcileCandidateAtStartup(name);
@@ -40,6 +45,7 @@ export class AuthCandidateMirror {
                     await atomicCopy(path.join(this.canonicalDir, name), destination);
                 }
             }
+            await this.recoverInterruptedValidationSymlink(runtime.authDir);
             if (defaultCandidate && !(await exists(path.join(runtime.authDir, 'auth.json')))) {
                 await pointAuthSymlink(runtime.authDir, defaultCandidate);
             }
@@ -402,6 +408,54 @@ export class AuthCandidateMirror {
         const runtime = this.runtimes.find((entry) => entry.id === runtimeId);
         return runtime?.label ?? runtimeId;
     }
+    async recoverInterruptedValidationSymlink(authDir) {
+        const authPath = path.join(authDir, 'auth.json');
+        const oldTarget = await fs.readlink(authPath).catch(() => null);
+        if (!oldTarget)
+            return;
+        const oldTargetPath = path.resolve(authDir, oldTarget);
+        if (!path.basename(oldTargetPath).startsWith('.auth-sync-validate-'))
+            return;
+        const candidateName = await this.selectValidationRecoveryCandidate(authDir);
+        if (!candidateName) {
+            this.logger.warn('codex.auth_temp_symlink_recovery_failed', {
+                authDir,
+                oldTarget: oldTargetPath,
+                reason: 'no parseable auth candidate found',
+            });
+            return;
+        }
+        await pointAuthSymlink(authDir, candidateName);
+        await removeValidationTempFiles(authDir);
+        const newTarget = path.join(authDir, candidateName);
+        this.logger.warn('codex.auth_temp_symlink_recovered', {
+            authDir,
+            oldTarget: oldTargetPath,
+            newTarget,
+        });
+    }
+    async selectValidationRecoveryCandidate(authDir) {
+        const statusCandidate = this.lastStatus?.candidateName ?? null;
+        if (statusCandidate && isAuthCandidateName(statusCandidate)) {
+            const record = await readChatGptAuthRecord(path.join(authDir, statusCandidate));
+            if (record) {
+                return statusCandidate;
+            }
+        }
+        const candidates = [];
+        for (const name of await listAuthCandidateNames(authDir)) {
+            const candidatePath = path.join(authDir, name);
+            const [record, stat] = await Promise.all([
+                readChatGptAuthRecord(candidatePath),
+                fs.stat(candidatePath).catch(() => null),
+            ]);
+            if (record && stat?.isFile()) {
+                candidates.push({ name, mtimeMs: stat.mtimeMs });
+            }
+        }
+        candidates.sort((left, right) => right.mtimeMs - left.mtimeMs || left.name.localeCompare(right.name));
+        return candidates[0]?.name ?? null;
+    }
 }
 export function isAuthCandidateName(name) {
     return name !== 'auth.json'
@@ -461,6 +515,12 @@ async function pointAuthSymlink(dir, candidateName) {
     await fs.symlink(path.join(dir, candidateName), temporary);
     await fs.rename(temporary, path.join(dir, 'auth.json'));
 }
+async function removeValidationTempFiles(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    await Promise.all(entries
+        .filter((entry) => entry.isFile() && entry.name.startsWith('.auth-sync-validate-'))
+        .map((entry) => fs.rm(path.join(dir, entry.name), { force: true }).catch(() => undefined)));
+}
 async function resolveFinalPath(sourcePath) {
     try {
         return await fs.realpath(sourcePath);

package/dist/controller/controller.d.ts

@@ -9,7 +9,9 @@ import type { SelfUpdateRuntime, SelfUpdateStatus } from '../update.js';
 export interface CoreCoordinator {
     canSelfUpdate?: () => boolean;
     authCandidateUpdated?: (runtimeId: string, candidateName: string) => Promise<void>;
-    recoverAuthCandidate?: (runtimeId: string, candidateName: string) => Promise<boolean>;
+    recoverAuthCandidate?: (runtimeId: string, candidateName: string, options?: {
+        crossNode?: boolean;
+    }) => Promise<boolean>;
     acquireAuthRefreshLease?: (reason: string) => Promise<{
         ok: boolean;
         leaseId: string | null;

package/dist/controller/controller.js

@@ -437,6 +437,14 @@ export class BridgeSessionCore {
                         if (serviceStatus.authSync.lastError) {
                             lines.push(t(locale, 'status_auth_sync_error', { value: serviceStatus.authSync.lastError }));
                         }
+                        if (serviceStatus.authSync.candidateFailures?.length) {
+                            lines.push(t(locale, 'status_auth_sync_candidate_failures', {
+                                value: serviceStatus.authSync.candidateFailures
+                                    .slice(0, 3)
+                                    .map((failure) => `${failure.candidateName}: ${failure.reason}`)
+                                    .join('; '),
+                            }));
+                        }
                     }
                     if (serviceStatus.lastUpdate) {
                         lines.push(t(locale, 'status_last_update', {
@@ -3846,7 +3854,7 @@ export class BridgeSessionCore {
         await this.sendMessage(scopeId, t(locale, 'auth_reload_restarting'));
         const currentCandidate = (await this.listCodexAuthState()).candidates.find(candidate => candidate.isCurrent) ?? null;
         const recovered = currentCandidate
-            ? await this.recoverCodexAuthCandidate(currentCandidate.name)
+            ? await this.recoverCodexAuthCandidate(currentCandidate.name, { crossNode: false })
             : false;
         this.pendingTurnErrors.clear();
         this.attachedThreads.clear();
@@ -4846,7 +4854,7 @@ export class BridgeSessionCore {
         };
     }
     async switchCodexAuthAndRestart(scopeId, locale, candidate, automatic, sendResult = true) {
-        const recovered = await this.recoverCodexAuthCandidate(candidate.name);
+        const recovered = await this.recoverCodexAuthCandidate(candidate.name, { crossNode: automatic });
         const result = await switchCodexAuth(candidate.path, this.resolveAuthDir());
         this.authRotationFailedTargets.delete(candidate.path);
         this.pendingTurnErrors.clear();
@@ -4863,12 +4871,12 @@ export class BridgeSessionCore {
         lines.push(...await this.buildCodexUsageStatusLines(locale));
         await this.sendMessage(scopeId, lines.join('\n'));
     }
-    async recoverCodexAuthCandidate(candidateName) {
+    async recoverCodexAuthCandidate(candidateName, options = { crossNode: true }) {
         if (!this.coordinator?.recoverAuthCandidate) {
             return false;
         }
         try {
-            return await this.coordinator.recoverAuthCandidate(this.authRuntimeId(), candidateName);
+            return await this.coordinator.recoverAuthCandidate(this.authRuntimeId(), candidateName, options);
         }
         catch (error) {
             this.logger.warn('codex.auth_candidate_recovery_failed', {
@@ -8144,6 +8152,18 @@ function formatAuthSyncStatus(locale, status) {
     if (status.lastError) {
         lines.push(t(locale, 'auth_sync_status_error', { value: status.lastError }));
     }
+    if (status.candidateFailures?.length) {
+        lines.push(t(locale, 'auth_sync_status_candidate_failures'));
+        for (const failure of status.candidateFailures.slice(0, 5)) {
+            lines.push(t(locale, 'auth_sync_status_candidate_failure', {
+                candidate: failure.candidateName,
+                reason: failure.reason,
+                source: failure.sourceLabel ?? failure.sourceNodeId ?? t(locale, 'unknown'),
+                peer: failure.peer ?? t(locale, 'unknown'),
+                time: failure.updatedAt,
+            }));
+        }
+    }
     return lines.join('\n');
 }
 function normalizeHelpUsageKey(name) {

package/dist/i18n.d.ts

@@ -127,6 +127,7 @@ declare const MESSAGES: {
         readonly status_auth_mirror_synced: "Last auth mirror: {candidate} from {source} at {time}";
         readonly status_auth_sync: "Cross-node auth sync: node {node}, contact {contact}, peers {peers}, pending imports {pending}";
         readonly status_auth_sync_error: "Cross-node auth sync error: {value}";
+        readonly status_auth_sync_candidate_failures: "Auth sync candidate failures: {value}";
         readonly status_last_update_none: "Last service update: none recorded";
         readonly status_last_update: "Last service update: {from} -> {to} at {time}";
         readonly status_last_codex_update: "Last Codex update: {value}";
@@ -218,6 +219,8 @@ declare const MESSAGES: {
         readonly auth_sync_status_pull: "Last pull: {value}";
         readonly auth_sync_status_lease: "Active refresh lease: {value}";
         readonly auth_sync_status_error: "Last error: {value}";
+        readonly auth_sync_status_candidate_failures: "Candidate failures:";
+        readonly auth_sync_status_candidate_failure: "- {candidate}: {reason} (source {source}, peer {peer}, at {time})";
         readonly button_login_device: "🔑 Login";
         readonly button_auth_reload: "🔄 Reload auth";
         readonly button_auth_refresh_all_confirm: "⚠️ Accept risk & refresh";
@@ -754,6 +757,7 @@ declare const MESSAGES: {
         readonly status_auth_mirror_synced: "最近 auth 镜像：{candidate} 由 {source} 于 {time} 同步";
         readonly status_auth_sync: "跨节点 auth 同步：节点 {node}，联系人 {contact}，peer {peers}，待导入 {pending}";
         readonly status_auth_sync_error: "跨节点 auth 同步错误：{value}";
+        readonly status_auth_sync_candidate_failures: "auth 同步候选失败：{value}";
         readonly status_last_update_none: "最近服务升级：暂无记录";
         readonly status_last_update: "最近服务升级：{from} -> {to}（{time}）";
         readonly status_last_codex_update: "最近 Codex 升级：{value}";
@@ -845,6 +849,8 @@ declare const MESSAGES: {
         readonly auth_sync_status_pull: "最近拉取：{value}";
         readonly auth_sync_status_lease: "当前刷新锁：{value}";
         readonly auth_sync_status_error: "最近错误：{value}";
+        readonly auth_sync_status_candidate_failures: "候选失败：";
+        readonly auth_sync_status_candidate_failure: "- {candidate}：{reason}（来源 {source}，peer {peer}，时间 {time}）";
         readonly button_login_device: "🔑 设备登录";
         readonly button_auth_reload: "🔄 重载 auth";
         readonly button_auth_refresh_all_confirm: "⚠️ 接受风险并刷新";

package/dist/i18n.js

@@ -125,6 +125,7 @@ const MESSAGES = {
         status_auth_mirror_synced: 'Last auth mirror: {candidate} from {source} at {time}',
         status_auth_sync: 'Cross-node auth sync: node {node}, contact {contact}, peers {peers}, pending imports {pending}',
         status_auth_sync_error: 'Cross-node auth sync error: {value}',
+        status_auth_sync_candidate_failures: 'Auth sync candidate failures: {value}',
         status_last_update_none: 'Last service update: none recorded',
         status_last_update: 'Last service update: {from} -> {to} at {time}',
         status_last_codex_update: 'Last Codex update: {value}',
@@ -216,6 +217,8 @@ const MESSAGES = {
         auth_sync_status_pull: 'Last pull: {value}',
         auth_sync_status_lease: 'Active refresh lease: {value}',
         auth_sync_status_error: 'Last error: {value}',
+        auth_sync_status_candidate_failures: 'Candidate failures:',
+        auth_sync_status_candidate_failure: '- {candidate}: {reason} (source {source}, peer {peer}, at {time})',
         button_login_device: '🔑 Login',
         button_auth_reload: '🔄 Reload auth',
         button_auth_refresh_all_confirm: '⚠️ Accept risk & refresh',
@@ -752,6 +755,7 @@ const MESSAGES = {
         status_auth_mirror_synced: '最近 auth 镜像：{candidate} 由 {source} 于 {time} 同步',
         status_auth_sync: '跨节点 auth 同步：节点 {node}，联系人 {contact}，peer {peers}，待导入 {pending}',
         status_auth_sync_error: '跨节点 auth 同步错误：{value}',
+        status_auth_sync_candidate_failures: 'auth 同步候选失败：{value}',
         status_last_update_none: '最近服务升级：暂无记录',
         status_last_update: '最近服务升级：{from} -> {to}（{time}）',
         status_last_codex_update: '最近 Codex 升级：{value}',
@@ -843,6 +847,8 @@ const MESSAGES = {
         auth_sync_status_pull: '最近拉取：{value}',
         auth_sync_status_lease: '当前刷新锁：{value}',
         auth_sync_status_error: '最近错误：{value}',
+        auth_sync_status_candidate_failures: '候选失败：',
+        auth_sync_status_candidate_failure: '- {candidate}：{reason}（来源 {source}，peer {peer}，时间 {time}）',
         button_login_device: '🔑 设备登录',
         button_auth_reload: '🔄 重载 auth',
         button_auth_refresh_all_confirm: '⚠️ 接受风险并刷新',

package/dist/main.js

@@ -9,7 +9,7 @@ import { fileURLToPath } from 'node:url';
 import { APP_HOME, DEFAULT_CODEX_TELEGRAM_HOME, DEFAULT_ENV_PATH, DEFAULT_LOG_PATH, DEFAULT_STATUS_PATH, getLoadedEnvPath, loadConfig, loadEnv, } from './config.js';
 import { acquireProcessLock, LockHeldError } from './lock.js';
 import { readRuntimeStatus, writeRuntimeStatus } from './runtime.js';
-import { refreshFoxclawExecStartDropIns, removeFoxclawExecStartDropIns } from './systemd.js';
+import { buildFoxclawSystemdUnitText, refreshFoxclawExecStartDropIns, removeFoxclawExecStartDropIns } from './systemd.js';
 import { createSelfUpdateRuntime, inferPnpmHomeFromEntryPoint, performSelfUpdate, readSelfUpdateStatus, writeSelfUpdateStatus, } from './update.js';
 const rawCommand = process.argv[2];
 const command = rawCommand || 'serve';
@@ -288,10 +288,12 @@ async function runServeCli() {
                 canSelfUpdate: () => authSyncLocalIdle()
                     && (!authSync || authSync.isIdle()),
                 authCandidateUpdated: (runtimeId, candidateName) => mirror.syncRuntimeCandidate(runtimeId, candidateName).then(() => undefined),
-                recoverAuthCandidate: async (runtimeId, candidateName) => {
+                recoverAuthCandidate: async (runtimeId, candidateName, options = {}) => {
                     const local = await mirror.recoverRuntimeCandidate(runtimeId, candidateName);
                     if (local)
                         return true;
+                    if (options.crossNode === false)
+                        return false;
                     const current = await mirror.readRuntimeCandidate(runtimeId, candidateName)
                         ?? await mirror.readNewestCandidate(candidateName);
                     return await authSync?.requestRecovery(candidateName, {
@@ -442,10 +444,12 @@ async function runServeCli() {
             canSelfUpdate: () => singleAuthSyncLocalIdle()
                 && (!singleAuthSync || singleAuthSync.isIdle()),
             authCandidateUpdated: (runtimeId, candidateName) => singleMirror?.syncRuntimeCandidate(runtimeId, candidateName).then(() => undefined) ?? Promise.resolve(),
-            recoverAuthCandidate: async (runtimeId, candidateName) => {
+            recoverAuthCandidate: async (runtimeId, candidateName, options = {}) => {
                 const local = await singleMirror?.recoverRuntimeCandidate(runtimeId, candidateName) ?? null;
                 if (local)
                     return true;
+                if (options.crossNode === false)
+                    return false;
                 const current = await singleMirror?.readRuntimeCandidate(runtimeId, candidateName)
                     ?? await singleMirror?.readNewestCandidate(candidateName)
                     ?? null;
@@ -612,13 +616,21 @@ function formatAuthSyncNotification(locale, event) {
             case 'remote_import_failed':
                 return `${event.mode === 'pull' ? '跨节点拉取导入失败' : '跨节点 auth 导入失败'}：${event.candidateName}\n来源：${formatSource(event.sourceLabel, event.sourceNodeId)}\n原因：${event.reason}\n需要注意：如果其他候选也无法恢复，请人工介入重新登录或刷新这个 auth。`;
             case 'recovery_started':
-                return `auth 恢复开始：${event.candidateName}\n处理：同节点没有可用较新副本，正在向跨节点 peer 查询：${peers}`;
+                return `auth 恢复开始：${event.candidateName}\nRequest：${event.requestId}\n处理：同节点没有可用较新副本，正在向跨节点 peer 查询：${peers}，最长等待 ${event.timeoutMs}ms`;
             case 'recovery_peer_empty':
                 return `auth 恢复收到 peer 回应但没有可用副本：${event.candidateName}\nPeer：${event.peer}\n原因：${event.reason}`;
             case 'recovery_peer_bundle_received':
                 return `auth 恢复收到 peer 候选：${event.candidateName}\nPeer：${event.peer}，来源节点：${event.sourceNodeId}\n处理：正在验证 usage 后导入。`;
             case 'recovery_failed':
-                return `auth 恢复已穷尽：${event.candidateName}\n已查询 peer：${peers}\n原因：${event.reason}\n请人工介入：使用 /auth add <name> 或设备登录重新生成可用 auth。`;
+                return [
+                    `auth 恢复已穷尽：${event.candidateName}`,
+                    event.requestId ? `Request：${event.requestId}` : null,
+                    `已查询 peer：${peers}`,
+                    event.waitMs !== undefined ? `等待：${event.waitMs}ms` : null,
+                    formatPeerReachability(event.peerReachability, 'zh'),
+                    `原因：${event.reason}`,
+                    '请人工介入：使用 /auth add <name> 或设备登录重新生成可用 auth。',
+                ].filter(Boolean).join('\n');
             case 'pull_request_received':
                 return `收到 peer 的 auth 查询：${event.candidateName}\nPeer：${event.peer}，请求节点：${event.requesterNodeId}`;
             case 'pull_response_sent':
@@ -653,13 +665,21 @@ function formatAuthSyncNotification(locale, event) {
         case 'remote_import_failed':
             return `${event.mode === 'pull' ? 'Cross-node pull import failed' : 'Cross-node auth import failed'}: ${event.candidateName}\nSource: ${formatSource(event.sourceLabel, event.sourceNodeId)}\nReason: ${event.reason}\nAttention: if no other candidate can recover this account, run device login or refresh this auth manually.`;
         case 'recovery_started':
-            return `Auth recovery started: ${event.candidateName}\nAction: no newer same-node copy was available; querying cross-node peers: ${peers}`;
+            return `Auth recovery started: ${event.candidateName}\nRequest: ${event.requestId}\nAction: no newer same-node copy was available; querying cross-node peers: ${peers}; timeout ${event.timeoutMs}ms`;
         case 'recovery_peer_empty':
             return `Auth recovery peer replied without usable auth: ${event.candidateName}\nPeer: ${event.peer}\nReason: ${event.reason}`;
         case 'recovery_peer_bundle_received':
             return `Auth recovery peer returned a candidate: ${event.candidateName}\nPeer: ${event.peer}, source node: ${event.sourceNodeId}\nAction: validating usage before import.`;
         case 'recovery_failed':
-            return `Auth recovery exhausted: ${event.candidateName}\nPeers checked: ${peers}\nReason: ${event.reason}\nManual action: use /auth add <name> or device login to create a usable auth.`;
+            return [
+                `Auth recovery exhausted: ${event.candidateName}`,
+                event.requestId ? `Request: ${event.requestId}` : null,
+                `Peers checked: ${peers}`,
+                event.waitMs !== undefined ? `Wait: ${event.waitMs}ms` : null,
+                formatPeerReachability(event.peerReachability, 'en'),
+                `Reason: ${event.reason}`,
+                'Manual action: use /auth add <name> or device login to create a usable auth.',
+            ].filter(Boolean).join('\n');
         case 'pull_request_received':
             return `Received peer auth recovery request: ${event.candidateName}\nPeer: ${event.peer}, requester node: ${event.requesterNodeId}`;
         case 'pull_response_sent':
@@ -671,6 +691,17 @@ function formatAuthSyncNotification(locale, event) {
 function formatPeerList(peers, locale) {
     return peers.length > 0 ? peers.join(', ') : (locale === 'zh' ? '无' : 'none');
 }
+function formatPeerReachability(reachability, locale) {
+    const reachable = (reachability ?? []).filter((entry) => entry.reachableDuringRequest);
+    if (reachable.length === 0)
+        return null;
+    const details = reachable
+        .map((entry) => `${entry.peer}${entry.lastReceivedAt ? ` @ ${entry.lastReceivedAt}` : ''}`)
+        .join(', ');
+    return locale === 'zh'
+        ? `注意：这些 peer 在本次等待期间有其他 auth sync 消息，说明 peer 可达但这个请求超时：${details}`
+        : `Note: these peers sent other auth sync messages during this wait, so the peer was reachable but this request timed out: ${details}`;
+}
 function formatSource(sourceLabel, sourceNodeId) {
     return sourceLabel === sourceNodeId ? sourceNodeId : `${sourceLabel} / ${sourceNodeId}`;
 }
@@ -1168,32 +1199,15 @@ function installSystemd() {
     fs.mkdirSync(configDir, { recursive: true });
     fs.mkdirSync(path.join(APP_HOME, 'logs'), { recursive: true });
     const escapedEntryPoint = systemdEscape(entryPoint);
-    fs.writeFileSync(unitPath, `[Unit]
-Description=FoxClaw local Codex execution bridge
-Documentation=https://github.com/foxden-app/foxclaw
-After=network-online.target
-Wants=network-online.target
-StartLimitIntervalSec=300
-StartLimitBurst=5
-
-[Service]
-Type=simple
-WorkingDirectory=${systemdEscape(configDir)}
-EnvironmentFile=-${systemdEscape(envPath)}
-Environment=HOME=${systemdEscape(process.env.HOME || '')}
-Environment=USER=${systemdEscape(process.env.USER || '')}
-Environment=LOGNAME=${systemdEscape(process.env.LOGNAME || process.env.USER || '')}
-Environment=PATH=${systemdEscape(pathValue)}
-Environment=FOXCLAW_ENV=${systemdEscape(envPath)}
-ExecStart=${execStart}
-Restart=always
-RestartSec=10
-TimeoutStopSec=45
-KillMode=process
-
-[Install]
-WantedBy=default.target
-`);
+    fs.writeFileSync(unitPath, buildFoxclawSystemdUnitText({
+        workingDirectory: systemdEscape(configDir),
+        envPath: systemdEscape(envPath),
+        home: systemdEscape(process.env.HOME || ''),
+        user: systemdEscape(process.env.USER || ''),
+        logname: systemdEscape(process.env.LOGNAME || process.env.USER || ''),
+        pathValue: systemdEscape(pathValue),
+        execStart,
+    }));
     if (proxychainsConf) {
         console.log(`[OK] systemd proxychains enabled: ${proxychainsConf}`);
     }

package/dist/systemd.d.ts

@@ -2,6 +2,16 @@ export interface SystemdDropInUpdate {
     path: string;
     replacements: number;
 }
+export interface FoxclawSystemdUnitTextOptions {
+    workingDirectory: string;
+    envPath: string;
+    home: string;
+    user: string;
+    logname: string;
+    pathValue: string;
+    execStart: string;
+}
+export declare function buildFoxclawSystemdUnitText(options: FoxclawSystemdUnitTextOptions): string;
 export declare function refreshFoxclawExecStartDropIns(userSystemdDir: string, unitName: string, escapedEntryPoint: string): SystemdDropInUpdate[];
 export declare function removeFoxclawExecStartDropIns(userSystemdDir: string, unitName: string): SystemdDropInUpdate[];
 export declare function refreshFoxclawExecStartText(text: string, escapedEntryPoint: string): {

package/dist/systemd.js

@@ -1,6 +1,34 @@
 import fs from 'node:fs';
 import path from 'node:path';
 const FOXCLAW_MAIN_PATH_RE = /\S*(?:\.pnpm\/@foxden-app\+foxclaw@[^/\s]+\/node_modules\/@foxden-app\/foxclaw|node_modules\/@foxden-app\/foxclaw)\/dist\/main\.js/g;
+export function buildFoxclawSystemdUnitText(options) {
+    return `[Unit]
+Description=FoxClaw local Codex execution bridge
+Documentation=https://github.com/foxden-app/foxclaw
+After=network-online.target
+Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
+
+[Service]
+Type=simple
+WorkingDirectory=${options.workingDirectory}
+EnvironmentFile=-${options.envPath}
+Environment=HOME=${options.home}
+Environment=USER=${options.user}
+Environment=LOGNAME=${options.logname}
+Environment=PATH=${options.pathValue}
+Environment=FOXCLAW_ENV=${options.envPath}
+ExecStart=${options.execStart}
+Restart=always
+RestartSec=10
+TimeoutStopSec=45
+KillMode=control-group
+
+[Install]
+WantedBy=default.target
+`;
+}
 export function refreshFoxclawExecStartDropIns(userSystemdDir, unitName, escapedEntryPoint) {
     const dropInDir = path.join(userSystemdDir, `${unitName}.d`);
     let names;

package/dist/types.d.ts

@@ -373,6 +373,15 @@ export interface RuntimeStatus {
         lastPullAt: string | null;
         lastPullCandidate: string | null;
         lastError: string | null;
+        candidateFailures?: Array<{
+            candidateName: string;
+            reason: string;
+            sourceNodeId: string | null;
+            sourceLabel: string | null;
+            peer: string | null;
+            mode: 'push' | 'pull';
+            updatedAt: string;
+        }>;
         activeLeaseId: string | null;
     } | null;
     lastUpdate?: {

package/dist/update.d.ts

@@ -40,6 +40,12 @@ interface PerformSelfUpdateOptions {
     codexCliBin?: string;
     env?: NodeJS.ProcessEnv;
 }
+export interface SelfUpdateLaunchCommand {
+    command: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    viaSystemdRun: boolean;
+}
 export interface SelfUpdateOutcome {
     ok: boolean;
     fromVersion: string;
@@ -53,5 +59,16 @@ export declare function resolveCodexUpdateInstaller(codexCliBin: string, nodePat
 export declare function readSelfUpdateStatus(statusFile: string): SelfUpdateStatus | null;
 export declare function writeSelfUpdateStatus(statusFile: string, status: SelfUpdateStatus): void;
 export declare function createSelfUpdateRuntime(options: CreateSelfUpdateRuntimeOptions): SelfUpdateRuntime;
+export declare function buildSelfUpdateLaunchCommand(options: {
+    entryPoint: string;
+    nodePath: string;
+    statusFile: string;
+    logPath: string;
+    codexCliBin?: string;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    systemdRunPath?: string | null;
+    unitName?: string;
+}): SelfUpdateLaunchCommand;
 export declare function performSelfUpdate(options: PerformSelfUpdateOptions): SelfUpdateOutcome;
 export {};

package/dist/update.js

@@ -171,12 +171,33 @@ export function createSelfUpdateRuntime(options) {
             fs.mkdirSync(path.dirname(options.logPath), { recursive: true });
             const logFd = fs.openSync(options.logPath, 'a', 0o600);
             try {
-                const child = spawn(options.nodePath, [options.entryPoint, 'update', '--notification-file', statusFile], {
-                    detached: true,
-                    stdio: ['ignore', logFd, logFd],
-                    env: options.codexCliBin ? { ...process.env, CODEX_CLI_BIN: options.codexCliBin } : process.env,
+                const launch = buildSelfUpdateLaunchCommand({
+                    entryPoint: options.entryPoint,
+                    nodePath: options.nodePath,
+                    statusFile,
+                    logPath: options.logPath,
+                    ...(options.codexCliBin ? { codexCliBin: options.codexCliBin } : {}),
                 });
-                child.unref();
+                if (launch.viaSystemdRun) {
+                    const result = spawnSync(launch.command, launch.args, {
+                        stdio: ['ignore', logFd, logFd],
+                        env: launch.env,
+                    });
+                    if (result.error) {
+                        throw result.error;
+                    }
+                    if (result.status !== 0) {
+                        throw new Error(`${launch.command} ${launch.args.join(' ')} exited with status ${result.status ?? 'unknown'}.`);
+                    }
+                }
+                else {
+                    const child = spawn(launch.command, launch.args, {
+                        detached: true,
+                        stdio: ['ignore', logFd, logFd],
+                        env: launch.env,
+                    });
+                    child.unref();
+                }
             }
             catch (error) {
                 writeSelfUpdateStatus(statusFile, {
@@ -205,6 +226,40 @@ export function createSelfUpdateRuntime(options) {
         },
     };
 }
+export function buildSelfUpdateLaunchCommand(options) {
+    const env = options.codexCliBin
+        ? { ...(options.env ?? process.env), CODEX_CLI_BIN: options.codexCliBin }
+        : { ...(options.env ?? process.env) };
+    const updateArgs = [options.entryPoint, 'update', '--notification-file', options.statusFile];
+    const platform = options.platform ?? process.platform;
+    const systemdRunPath = options.systemdRunPath === undefined
+        ? resolveCommand('systemd-run', env)
+        : options.systemdRunPath;
+    if (platform === 'linux' && systemdRunPath) {
+        const unitName = options.unitName ?? `foxclaw-update-${process.pid}-${Date.now()}`;
+        return {
+            command: systemdRunPath,
+            args: [
+                '--user',
+                '--collect',
+                `--unit=${unitName}`,
+                `--property=StandardOutput=append:${options.logPath}`,
+                `--property=StandardError=append:${options.logPath}`,
+                ...systemdSetEnvArgs(env),
+                options.nodePath,
+                ...updateArgs,
+            ],
+            env,
+            viaSystemdRun: true,
+        };
+    }
+    return {
+        command: options.nodePath,
+        args: updateArgs,
+        env,
+        viaSystemdRun: false,
+    };
+}
 export function performSelfUpdate(options) {
     const env = options.env ?? process.env;
     let toVersion = null;
@@ -295,6 +350,31 @@ function executableCandidates(commandName, nodePath, env, preferred = []) {
         ...(env.PATH || '').split(path.delimiter).filter(Boolean).map((dir) => path.join(dir, commandName)),
     ].filter((candidate, index, all) => candidate && all.indexOf(candidate) === index);
 }
+function resolveCommand(commandName, env) {
+    for (const directory of (env.PATH || '').split(path.delimiter).filter(Boolean)) {
+        const candidate = path.join(directory, commandName);
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    for (const fallback of ['/usr/bin', '/bin', '/usr/local/bin']) {
+        const candidate = path.join(fallback, commandName);
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function systemdSetEnvArgs(env) {
+    return Object.entries(env)
+        .filter((entry) => {
+        const [key, value] = entry;
+        return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key)
+            && typeof value === 'string'
+            && !value.includes('\0');
+    })
+        .map(([key, value]) => `--setenv=${key}=${value}`);
+}
 function buildInstallerEnv(entryPoint, installer, env) {
     const pnpmHome = installer.manager === 'pnpm'
         ? installer.pnpmHome ?? inferPnpmHomeFromEntryPoint(entryPoint)

package/docs/cross-node-auth-sync.md

@@ -168,6 +168,12 @@ Note: `/auth sync push all` saying “sent” only means this node successfully
 
 When cross-node sync is enabled, the contact bot private chat receives node-level notifications: local auth updates and the peers being contacted, received remote bundles and whether they were queued or immediately validated, import success/skip/failure reasons, recovery peer queries and peer replies, and a manual-intervention notice when every peer lacks an importable copy. Notifications never include auth contents, tokens, or encrypted bundle payloads.
 
+Starting in 0.5.2, `/auth sync status` separates sync-system `Last error` from per-auth `Candidate failures`. For example, a remote candidate that returns `token_invalidated` or has an expired access token is recorded under that candidate name only; current `auth.json` health is still determined by validating the current auth usage. `local candidate is already newer or equal` is a normal skip, not an error.
+
+Manual `/auth` switches and `/auth reload` recover from same-node local mirrors only and do not send cross-node pull requests. FoxClaw queries peers only during automatic recovery after it detects a real auth problem. Recovery timeout notifications include the request id, candidate name, peer list, and wait duration; if another auth sync message arrived from the same peer during that wait, the notification says the peer was reachable but this request timed out.
+
+If an upgrade or restart interrupts remote candidate usage validation, older versions could leave `auth.json -> .auth-sync-validate-*` behind. Starting in 0.5.2, FoxClaw checks for this at startup, restores `auth.json` to the mirror-status candidate or the newest parseable real `auth.json_*` candidate in the same directory, and removes stale validation temp files.
+
 5. Only test refresh-token rotation after you understand the risk:
 
 ```text

package/docs/user-manual.md

@@ -419,7 +419,7 @@ OpenAI does not publish a fixed ChatGPT refresh-token lifetime or an old-token r
 
 ### 6.4 Cross-Node Auth Sync
 
-Cross-node auth sync is disabled by default. It is for multiple machines you control that share the same legally owned ChatGPT auth candidate pool, so a token refreshed by Codex on one node can be copied to the others. v1 uses Telegram Bot-to-Bot private messages to carry encrypted files, so it does not require public IPs or FRP. The recommended default is one contact bot per node; other bots on the same node keep using local auth mirroring. In multi-bot mode, the default contact is the first token in `TG_BOT_TOKENS`. The contact bot private chat reports send, receive, queue, import, failure, recovery-query, and manual-intervention states.
+Cross-node auth sync is disabled by default. It is for multiple machines you control that share the same legally owned ChatGPT auth candidate pool, so a token refreshed by Codex on one node can be copied to the others. v1 uses Telegram Bot-to-Bot private messages to carry encrypted files, so it does not require public IPs or FRP. The recommended default is one contact bot per node; other bots on the same node keep using local auth mirroring. In multi-bot mode, the default contact is the first token in `TG_BOT_TOKENS`. The contact bot private chat reports send, receive, queue, import, failure, recovery-query, and manual-intervention states; per-candidate validation failures are shown as candidate failures instead of overwriting the sync-system last error.
 
 For the full design, safety boundaries, `.env` examples, and troubleshooting, read the [Cross-Node Auth Sync Setup Guide](./cross-node-auth-sync.md).
 
@@ -460,7 +460,7 @@ Dual-active behavior:
 
 Commands:
 
-- `/auth sync status`: show node id, peers, recent sends/receives/imports, pending imports, and the latest error.
+- `/auth sync status`: show node id, peers, recent sends/receives/imports, pending imports, the sync-system latest error, and per-candidate failures.
 - `/auth sync test`: send an encrypted ping and wait for peer pong replies to verify peer config, shared key, and Bot-to-Bot private messages.
 - `/auth sync push all`: manually broadcast all locally verified candidates without refreshing tokens. “Sent” does not mean the peer imported files; check `/auth sync status` and `/auth` on the peer.
 

package/docs/zh/cross-node-auth-sync.md

@@ -168,6 +168,12 @@ auth sync 测试完成：已发送 1，收到回应 1。
 
 启用跨节点同步后，联系人 bot 的私聊会收到节点级通知：本机 auth 更新并开始发往哪些 peer、收到远端包后是排队还是立即验证、导入成功/跳过/失败原因、auth 恢复时正在查询哪些 peer、peer 回应了什么，以及所有 peer 都无法提供可用副本时的人工介入提示。通知不会包含 auth 内容、token 或同步密文。
 
+从 0.5.2 起，`/auth sync status` 会把同步系统级 `最近错误` 和单个 auth 的 `候选失败` 分开显示。比如某个远端候选返回 `token_invalidated` 或 access token 过期时，只会记录到该候选名下面；当前 `auth.json` 是否健康仍以当前 auth 的 usage 验证为准。`local candidate is already newer or equal` 属于正常跳过，不会记为错误。
+
+手动 `/auth` 切换和 `/auth reload` 只会尝试同节点本地 mirror 恢复，不会主动向跨节点 peer 发起 pull。只有 FoxClaw 检测到当前 auth 真的出现认证问题并进入自动恢复时，才会向 peer 查询可用副本。恢复超时通知会包含 request id、候选名、peer 列表和等待时长；如果等待期间收到过同 peer 的其他 auth sync 消息，通知会标明 peer 可达但该请求超时。
+
+如果升级或重启正好打断远端候选 usage 验证，旧版本可能留下 `auth.json -> .auth-sync-validate-*` 临时 symlink。0.5.2 起 FoxClaw 启动时会自动检测并恢复到 mirror 状态记录的候选，或同目录最近修改且可解析的真实 `auth.json_*` 候选，然后清理临时文件。
+
 5. 只有在完全理解 refresh token 轮换风险时，才测试：
 
 ```text

package/docs/zh/user-manual.md

@@ -419,7 +419,7 @@ OpenAI 没有公开 ChatGPT refresh token 的固定有效期或旧 token 重放
 
 ### 6.4 跨节点 auth 同步
 
-跨节点 auth 同步默认关闭。它适合你在多台自己控制的机器上使用同一组合法 ChatGPT 账号候选，并希望某台机器上 Codex 自动刷新出的新 token 能同步到其他机器。v1 使用 Telegram Bot-to-Bot 私聊传输加密文件，不需要公网 IP 或 FRP。推荐每台机器选择一个联系人 bot；同一节点内其他 bot 继续使用本机 auth 镜像。多 bot 模式下，默认联系人是 `TG_BOT_TOKENS` 的第一个 token。联系人 bot 的私聊会报告发送、接收、排队、导入、失败、恢复查询和人工介入提示。
+跨节点 auth 同步默认关闭。它适合你在多台自己控制的机器上使用同一组合法 ChatGPT 账号候选，并希望某台机器上 Codex 自动刷新出的新 token 能同步到其他机器。v1 使用 Telegram Bot-to-Bot 私聊传输加密文件，不需要公网 IP 或 FRP。推荐每台机器选择一个联系人 bot；同一节点内其他 bot 继续使用本机 auth 镜像。多 bot 模式下，默认联系人是 `TG_BOT_TOKENS` 的第一个 token。联系人 bot 的私聊会报告发送、接收、排队、导入、失败、恢复查询和人工介入提示；单个候选验证失败会作为“候选失败”显示，不会覆盖同步系统级最近错误。
 
 完整设计、安全边界、`.env` 示例和排查步骤见 [跨节点 auth 同步配置指南](./cross-node-auth-sync.md)。
 
@@ -460,7 +460,7 @@ AUTH_SYNC_NODE_ID=workstation-a
 
 命令：
 
-- `/auth sync status`：查看 node id、peer、最近收发、最近导入、待导入和最近错误。
+- `/auth sync status`：查看 node id、peer、最近收发、最近导入、待导入、系统级最近错误和单候选失败。
 - `/auth sync test`：发送加密 ping 并等待 peer 返回 pong，确认 peer、共享密钥和 Bot-to-Bot 私聊可用。
 - `/auth sync push all`：手动广播当前节点已验证的全部候选，不刷新 token；“已发送”不等于对端已经导入，需要在 peer 上看 `/auth sync status` 和 `/auth`。
 

package/package.json

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