@foxden-app/foxclaw 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 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.7.1 - 2026-08-30
+
+### 中文
+- 修复 Codex app-server WebSocket 短暂断开时错误废弃活动轮次和实时预览、导致后续 Telegram 消息永久卡在队列中的问题。FoxClaw 现在会保留活动状态，等待 app-server 重新初始化后恢复线程订阅，并通过线程快照补齐断线期间遗漏的输出或完成事件，再继续处理队列。
+- WebSocket 关闭信息现在保留真实关闭码和原因；重连恢复已在 Codex CLI 0.151.0 上通过同一 app-server 进程断线的现场验证。
+
+### English
+- Fixed transient Codex app-server WebSocket disconnects abandoning active turns and live previews, which could leave later Telegram messages permanently queued. FoxClaw now preserves active state, restores the thread subscription after app-server initialization, reconciles output or completion events missed during the disconnect from the thread snapshot, and then continues the queue.
+- WebSocket close metadata now preserves the actual close code and reason. Reconnect recovery was live-verified against Codex CLI 0.151.0 with the same app-server process disconnecting and reattaching.
+
 ## 0.7.0 - 2026-08-26
 
 ### 中文

package/dist/codex_app/client.js

@@ -540,6 +540,7 @@ export class CodexAppClient extends EventEmitter {
         });
         await Promise.race([this.connectWebSocket(), spawnFailed]);
         await this.initialize();
+        this.emit('ready');
     }
     async attachPersistedServer() {
         const state = this.readServerState();
@@ -554,6 +555,7 @@ export class CodexAppClient extends EventEmitter {
         try {
             await this.connectWebSocket();
             await this.initialize();
+            this.emit('ready');
             this.logger.info('codex.app-server.attached', { pid: state.pid, port: state.port });
             return true;
         }
@@ -586,12 +588,16 @@ export class CodexAppClient extends EventEmitter {
                         this.socket = ws;
                         this.connected = true;
                         ws.addEventListener('message', message => this.handleMessage(String(message.data)));
-                        ws.addEventListener('close', () => {
+                        ws.addEventListener('close', (event) => {
                             if (this.socket !== ws) {
                                 return;
                             }
                             this.socket = null;
-                            this.handleDisconnect({ code: 'ws-close', source: 'websocket-close' });
+                            this.handleDisconnect({
+                                code: event.code,
+                                reason: event.reason || null,
+                                source: 'websocket-close',
+                            });
                         });
                         ws.addEventListener('error', err => {
                             this.logger.warn('codex.ws.error', String(err.message ?? 'unknown'));

package/dist/controller/controller.d.ts

@@ -100,6 +100,9 @@ export declare class BridgeSessionCore {
     private proactiveAuthRefreshStatus;
     private stalePanelDeleteTimers;
     private attachedThreads;
+    private codexReconnectPending;
+    private codexReconnectRecovery;
+    private stopping;
     private botUsername;
     private lastError;
     /** Last threads-panel pagination state per scope (Telegram inline nav + /open index alignment). */
@@ -268,6 +271,10 @@ export declare class BridgeSessionCore {
     private localeForChat;
     private findActiveTurn;
     private clearObservedThreadWatchers;
+    private pauseAppSnapshotWatchers;
+    private scheduleCodexReconnectRecovery;
+    private recoverAfterCodexReconnect;
+    private recoverActiveTurnAfterCodexReconnect;
     private clearObservedTurnWatcher;
     private stopWatchingScopeThread;
     private forgetStaleActiveTurn;
@@ -456,7 +463,6 @@ export declare class BridgeSessionCore {
     private cleanupFinishedPreview;
     private cleanupStaleInterruptButton;
     private cleanupTransientPreview;
-    private abandonActiveTurns;
     private releaseActiveTurnsForBridgeShutdown;
     private retirePreviewMessage;
     private forgetPreviewRecord;

package/dist/controller/controller.js

@@ -156,6 +156,9 @@ export class BridgeSessionCore {
     proactiveAuthRefreshStatus = null;
     stalePanelDeleteTimers = new Map();
     attachedThreads = new Set();
+    codexReconnectPending = false;
+    codexReconnectRecovery = null;
+    stopping = false;
     botUsername = null;
     lastError = null;
     /** Last threads-panel pagination state per scope (Telegram inline nav + /open index alignment). */
@@ -200,6 +203,7 @@ export class BridgeSessionCore {
     }
     /** Start Codex app-server transport and attach RPC listeners. */
     async startCodexApp() {
+        this.stopping = false;
         this.app.on('notification', (msg) => {
             void this.handleNotification(msg).catch((error) => {
                 void this.handleAsyncError('codex.notification', error);
@@ -215,13 +219,20 @@ export class BridgeSessionCore {
             this.lastError = null;
             this.updateStatus();
         });
+        this.app.on('ready', () => {
+            if (!this.codexReconnectPending || this.stopping) {
+                return;
+            }
+            this.codexReconnectPending = false;
+            this.scheduleCodexReconnectRecovery();
+        });
         this.app.on('disconnected', () => {
             this.attachedThreads.clear();
             this.threadTokenUsageAlerts.clear();
-            this.clearObservedThreadWatchers();
-            void this.abandonActiveTurns().catch((error) => {
-                this.logger.error('codex.disconnect_cleanup_failed', { error: toErrorMeta(error) });
-            });
+            if (!this.stopping) {
+                this.codexReconnectPending = true;
+                this.pauseAppSnapshotWatchers();
+            }
             this.updateStatus();
         });
         await this.app.start();
@@ -252,6 +263,8 @@ export class BridgeSessionCore {
         await this.startTelegramPolling();
     }
     async stop() {
+        this.stopping = true;
+        this.codexReconnectPending = false;
         this.pendingTurnErrors.clear();
         this.pendingUserInputs.clear();
         this.pendingMcpElicitations.clear();
@@ -3802,6 +3815,120 @@ export class BridgeSessionCore {
         }
         this.observedThreadWatchers.clear();
     }
+    pauseAppSnapshotWatchers() {
+        for (const watcher of this.observedThreadWatchers.values()) {
+            if (watcher.mode !== 'app_snapshot') {
+                continue;
+            }
+            watcher.stopped = true;
+            if (watcher.timer) {
+                clearTimeout(watcher.timer);
+                watcher.timer = null;
+            }
+        }
+    }
+    scheduleCodexReconnectRecovery() {
+        const previous = this.codexReconnectRecovery ?? Promise.resolve();
+        const recovery = previous
+            .catch(() => undefined)
+            .then(async () => this.recoverAfterCodexReconnect());
+        const trackedRecovery = recovery.finally(() => {
+            if (this.codexReconnectRecovery === trackedRecovery) {
+                this.codexReconnectRecovery = null;
+            }
+        });
+        this.codexReconnectRecovery = trackedRecovery;
+        void this.codexReconnectRecovery.catch((error) => {
+            this.logger.error('codex.reconnect_recovery_failed', { error: toErrorMeta(error) });
+        });
+    }
+    async recoverAfterCodexReconnect() {
+        const recoveredScopes = new Set();
+        for (const watcher of [...this.observedThreadWatchers.values()]) {
+            if (watcher.mode !== 'app_snapshot') {
+                continue;
+            }
+            try {
+                const binding = this.store.getBinding(watcher.scopeId);
+                const session = await this.resumeThreadForScope(watcher.scopeId, {
+                    threadId: watcher.threadId,
+                    cwd: binding?.threadId === watcher.threadId ? binding.cwd : null,
+                });
+                this.storeThreadSession(watcher.scopeId, session, 'seed');
+                watcher.stopped = false;
+                const active = watcher.activeTurnId
+                    ? this.getActiveTurn(watcher.scopeId, watcher.activeTurnId)
+                    : null;
+                if (active) {
+                    watcher.cursor = observerCursorFromActiveTurn(active);
+                }
+                await this.pollObservedThread(watcher);
+                if (!watcher.stopped && this.observedThreadWatchers.get(watcher.scopeId) === watcher) {
+                    this.scheduleObservedThreadPoll(watcher);
+                }
+                recoveredScopes.add(watcher.scopeId);
+            }
+            catch (error) {
+                watcher.stopped = false;
+                if (this.observedThreadWatchers.get(watcher.scopeId) === watcher) {
+                    this.scheduleObservedThreadPoll(watcher);
+                }
+                this.logger.warn('codex.reconnect_watcher_recovery_failed', {
+                    scopeId: watcher.scopeId,
+                    threadId: watcher.threadId,
+                    error: toErrorMeta(error),
+                });
+            }
+        }
+        for (const active of [...this.activeTurns.values()]) {
+            if (recoveredScopes.has(active.scopeId) || !this.getActiveTurn(active.scopeId, active.turnId)) {
+                continue;
+            }
+            try {
+                await this.recoverActiveTurnAfterCodexReconnect(active);
+            }
+            catch (error) {
+                this.logger.warn('codex.reconnect_turn_recovery_failed', {
+                    scopeId: active.scopeId,
+                    threadId: active.threadId,
+                    turnId: active.turnId,
+                    error: toErrorMeta(error),
+                });
+            }
+        }
+        await this.recoverQueuedTurns();
+        this.updateStatus();
+    }
+    async recoverActiveTurnAfterCodexReconnect(active) {
+        const binding = this.store.getBinding(active.scopeId);
+        const session = await this.resumeThreadForScope(active.scopeId, {
+            threadId: active.threadId,
+            cwd: binding?.threadId === active.threadId ? binding.cwd : null,
+        });
+        this.storeThreadSession(active.scopeId, session, 'seed');
+        const snapshot = await this.app.readThreadSnapshot(active.threadId);
+        const turn = snapshot?.turns.find(candidate => candidate.turnId === active.turnId) ?? null;
+        if (!snapshot || !turn) {
+            throw new Error(`Active turn ${active.turnId} was not found after reconnect`);
+        }
+        const diff = diffObservedTurn(observerCursorFromActiveTurn(active), turn, snapshot.activeFlags.includes('waitingOnApproval'));
+        for (const event of diff.events) {
+            await this.handleTurnActivityEvent(event, active.scopeId);
+        }
+        if (diff.completed && this.getActiveTurn(active.scopeId, active.turnId)) {
+            await this.handleTurnActivityEvent({
+                kind: 'turn_completed',
+                turnId: active.turnId,
+                state: turn.status === 'interrupted' ? 'interrupted' : 'completed',
+            }, active.scopeId);
+        }
+        this.logger.info('codex.reconnect_turn_recovered', {
+            scopeId: active.scopeId,
+            threadId: active.threadId,
+            turnId: active.turnId,
+            status: turn.status,
+        });
+    }
     clearObservedTurnWatcher(turnId, scopeId) {
         for (const watcher of this.observedThreadWatchers.values()) {
             if (scopeId && watcher.scopeId !== scopeId) {
@@ -3943,6 +4070,9 @@ export class BridgeSessionCore {
         }
         const snapshot = await this.app.readThreadSnapshot(watcher.threadId);
         if (!snapshot) {
+            if (watcher.activeTurnId && this.getActiveTurn(watcher.scopeId, watcher.activeTurnId)) {
+                return 'active';
+            }
             await this.stopWatchingScopeThread(watcher.scopeId);
             return 'idle';
         }
@@ -8144,24 +8274,6 @@ export class BridgeSessionCore {
             }
         }
     }
-    async abandonActiveTurns() {
-        const activeTurns = [...this.activeTurns.values()];
-        for (const active of activeTurns) {
-            this.clearToolBatchTimer(active.toolBatch);
-            this.clearRenderRetry(active);
-            if (active.previewActive) {
-                await this.retirePreviewMessage(active.scopeId, active.previewMessageId, t(this.localeForChat(active.scopeId), 'stale_preview_expired'), active.turnId);
-            }
-            if (active.queuedInputId) {
-                this.store.updateQueuedTurnInputStatus(active.queuedInputId, 'queued');
-            }
-            active.resolver();
-            this.deleteActiveTurnRecord(active);
-        }
-        if (activeTurns.length > 0) {
-            this.updateStatus();
-        }
-    }
     releaseActiveTurnsForBridgeShutdown() {
         const activeTurns = [...this.activeTurns.values()];
         for (const active of activeTurns) {
@@ -10039,6 +10151,21 @@ function seedObservedTurnCursor(turn) {
         completedItemIds: agentItems.map((item) => item.itemId),
     };
 }
+function observerCursorFromActiveTurn(active) {
+    const itemTexts = {};
+    const completedItemIds = [];
+    for (const segment of active.segments) {
+        itemTexts[segment.itemId] = segment.text;
+        if (segment.completed) {
+            completedItemIds.push(segment.itemId);
+        }
+    }
+    return {
+        turnId: active.turnId,
+        itemTexts,
+        completedItemIds,
+    };
+}
 function approvalKeyboard(locale, localId) {
     return [[
             { text: t(locale, 'button_allow'), callback_data: `approval:${localId}:accept` },

package/package.json

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