@foxden-app/foxclaw 0.7.1 → 0.7.3

package/.env.example

@@ -1,5 +1,6 @@
 # Required for new installs: one or more bot tokens for this host.
 # Comma-separated bot tokens. By default, each bot gets an independent Codex runtime/auth selection.
+# Homes use ~/.foxclaw/codex/telegram/@TelegramUsername/home (old numeric paths remain as links).
 TG_BOT_TOKENS=<telegram_bot_token>
 # Backward-compatible single-runtime setup.
 # In TG_BOT_TOKENS mode, if this exact token is also present in TG_BOT_TOKENS,

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 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.3 - 2026-09-05
+
+### 中文
+- 修复代理或网络不稳时 Telegram、Codex RPC 和 WebSocket 可能长期无响应的问题：请求有明确截止时间，活动会话断连、恢复失败和 writer 冲突都会给出可继续操作的错误，不重放结果未知的请求。
+- 登录、auth add 和 auth repair 流程增加取消按钮；取消失败也释放本地流程，旧按钮和其他聊天不能误取消当前登录。
+- 新增 `/cli` 与 `foxclaw resume`，可让终端连接桥的同一 Codex app-server；`/watch` 继续只读，外部 CLI 的消息可用原生线程队列安全排队。
+- 新增 `/takeover --force <消息>`：可信 Telegram 用户二次确认后，可精确停止占用目标 thread 的本机交互式 CLI，验证锁释放并恢复原 thread 后再提交消息。进程、锁或 thread 身份变化时明确拒绝，不删除锁、不改写 session 文件。
+- 多 bot Codex 数据目录默认使用真实 `@Telegram用户名`。迁移既有数字目录并保留兼容链接，共享终端的 bot 使用同名目录入口指向原 home。
+- 并行读取用户名，断网重启沿用已有名称；媒体发送通过稳定身份记录保持正确路由，目录冲突明确报错。
+- auth 问号、修复和删除操作会重新读取最新状态；安全同步文案区分“已发送”和“远端已导入”，状态更新未生效时不再报告虚假成功。
+
+### English
+- Bound Telegram, Codex RPC, and WebSocket waits so unstable proxy or network links fail explicitly instead of hanging. Active-session disconnects, recovery failures, and writer conflicts now include actionable recovery guidance without replaying ambiguous requests.
+- Added cancel buttons to login, auth-add, and auth-repair flows. Local state is released even when cancellation fails, while stale or foreign-chat buttons cannot cancel the current login.
+- Added `/cli` and `foxclaw resume` to connect a terminal to the bridge's Codex app-server. `/watch` remains read-only and external CLI prompts use Codex's native thread queue.
+- Added `/takeover --force <message>` for a trusted Telegram user to confirm a precise local interactive-CLI handoff. FoxClaw revalidates process, lock, and thread identity, verifies lock release, resumes the original thread, and only then submits the prompt; it never deletes locks or edits session files.
+- Name multi-bot Codex homes after verified Telegram usernames, migrating numeric directories with compatibility links and preserving shared terminal homes.
+- Resolve usernames in parallel, reuse stored paths offline, preserve media routing through stable identity metadata, and reject directory conflicts.
+- Auth repair/question-mark/delete actions now refresh current state first. Safe-sync wording distinguishes dispatch from confirmed remote import, and unapplied state changes no longer report false success.
+
+## 0.7.2 - 2026-08-30
+
+### 中文
+- 为 Codex CLI 0.151.0 及以上版本接入原生跨客户端线程队列。在 Telegram `/watch` 观察电脑端 CLI 会话时，直接发送文字或使用 `/queue <消息>` 会把下一轮任务排入同一线程，由桌面 CLI 在当前轮结束后继续执行。
+- 保持观察模式的 writer 安全边界：FoxClaw 不会 `resume`、中断或接管外部 CLI，`/steer` 仍明确拒绝；旧版 Codex 缺少队列接口时会提示升级，不会改写 session 文件或报告虚假成功。
+
+### English
+- Added the native cross-client thread queue available in Codex CLI 0.151.0 and later. While Telegram `/watch` observes a desktop CLI session, plain text or `/queue <message>` now queues the next task on the same thread for the desktop CLI to continue after its current turn.
+- Preserved the writer-safety boundary of watch mode: FoxClaw does not resume, interrupt, or take over the external CLI, and `/steer` remains explicitly unavailable. Older Codex versions receive an upgrade notice instead of session-file mutation or false success.
+
 ## 0.7.1 - 2026-08-30
 
 ### 中文

package/README.md

@@ -30,7 +30,7 @@ FoxClaw（狸爪）的目标很直接：让你用手机控制本机的 Codex 或
 
 ![FoxClaw Telegram 功能预览](./docs/assets/telegram-preview-zh.svg)
 
-手机端不是简单转发消息，而是给 Codex 的常用工作流做了 Telegram 面板：`/setup` 调模型、推理强度、Fast tier、权限和 Agent/Plan 模式；`/auth` 管理多个 Codex 登录候选，触发限制时自动轮转；`/threads`、`/watch` 和审批按钮用于切线程、观察进度和处理权限请求。
+手机端不是简单转发消息，而是给 Codex 的常用工作流做了 Telegram 面板：`/setup` 调模型、推理强度、Fast tier、权限和 Agent/Plan 模式；`/auth` 管理多个 Codex 登录候选，触发限制时自动轮转；`/threads`、`/watch` 和审批按钮用于切线程、观察进度和处理权限请求。终端 CLI 卡住且持有 thread 时，可信用户还可用 `/takeover --force <消息>` 核对 PID、目录并二次确认，将同一 thread 安全交给桥继续执行。
 
 ## 从这里开始
 

package/README_EN.md

@@ -30,7 +30,7 @@ No public server required. FoxClaw runs on your own computer, talks to `codex ap
 
 ![FoxClaw Telegram feature preview](./docs/assets/telegram-preview-en.svg)
 
-FoxClaw is more than message forwarding. It provides Telegram panels for Codex workflows: `/setup` adjusts model, reasoning, Fast tier, access, and Agent/Plan mode; `/auth` manages multiple Codex auth candidates and rotates them on usage limits; `/threads`, `/watch`, and approval buttons handle thread switching, progress monitoring, and permission requests.
+FoxClaw is more than message forwarding. It provides Telegram panels for Codex workflows: `/setup` adjusts model, reasoning, Fast tier, access, and Agent/Plan mode; `/auth` manages multiple Codex auth candidates and rotates them on usage limits; `/threads`, `/watch`, and approval buttons handle thread switching, progress monitoring, and permission requests. If a local interactive Codex CLI is stuck while holding a thread, the trusted Telegram user can use `/takeover --force <message>`, verify its PID and working directory, and explicitly confirm a safe handoff to the bridge.
 
 ## Start Here
 

package/dist/auth/cross_node_sync.js

@@ -776,11 +776,11 @@ export class CrossNodeAuthSync {
         this.recordEvent({
             direction: 'local',
             kind: 'audit.state',
-            stage: message.state,
+            stage: applied ? message.state : 'skipped',
             peer: null,
             requestId: message.requestId,
             candidateName: message.candidateName,
-            detail: null,
+            detail: applied ? null : 'local candidate did not match the audited identity or refresh timestamp',
         });
     }
     async buildAuditReport() {

package/dist/codex_app/client.d.ts

@@ -78,6 +78,7 @@ export declare class CodexAppClient extends EventEmitter {
     private port;
     private connected;
     private userAgent;
+    private readonly requestTimeoutMs;
     constructor(codexCliBin: string, launchCommand: string, autolaunch: boolean, serverStatePath: string, serverLogPath: string, logger: Logger, childEnv?: NodeJS.ProcessEnv | null, appServerConfigOverrides?: readonly string[]);
     isConnected(): boolean;
     getUserAgent(): string | null;
@@ -98,6 +99,9 @@ export declare class CodexAppClient extends EventEmitter {
     steerTurn(threadId: string, expectedTurnId: string, input: TurnInput[]): Promise<{
         turnId: string;
     }>;
+    queueThreadInput(threadId: string, clientUserMessageId: string, input: TurnInput[]): Promise<{
+        queuedSubmissionId: string;
+    }>;
     forkThread(options: {
         threadId: string;
         cwd: string | null;

package/dist/codex_app/client.js

@@ -33,6 +33,7 @@ export class CodexAppClient extends EventEmitter {
     port = null;
     connected = false;
     userAgent = null;
+    requestTimeoutMs = 30_000;
     constructor(codexCliBin, launchCommand, autolaunch, serverStatePath, serverLogPath, logger, childEnv = null, appServerConfigOverrides = []) {
         super();
         this.codexCliBin = codexCliBin;
@@ -186,6 +187,14 @@ export class CodexAppClient extends EventEmitter {
         const result = await this.request('turn/steer', { threadId, expectedTurnId, input });
         return { turnId: String(result?.turnId ?? expectedTurnId) };
     }
+    async queueThreadInput(threadId, clientUserMessageId, input) {
+        const result = await this.request('thread/queue/add', { threadId, clientUserMessageId, input });
+        const queuedSubmissionId = result?.queuedSubmission?.id;
+        if (typeof queuedSubmissionId !== 'string' || !queuedSubmissionId) {
+            throw new Error('thread/queue/add returned no queued submission id');
+        }
+        return { queuedSubmissionId };
+    }
     async forkThread(options) {
         const params = {
             threadId: options.threadId,
@@ -569,6 +578,9 @@ export class CodexAppClient extends EventEmitter {
                 port: state.port,
                 error: error instanceof Error ? error.message : String(error),
             });
+            if (isProcessAlive(state.pid)) {
+                throw new Error(`Managed Codex app-server pid ${state.pid} is alive but unreachable; retry the connection or explicitly restart it.`, { cause: error });
+            }
             this.clearServerStateForPid(state.pid);
             return false;
         }
@@ -580,11 +592,18 @@ export class CodexAppClient extends EventEmitter {
             try {
                 await new Promise((resolve, reject) => {
                     const ws = new WebSocket(url);
+                    const timer = setTimeout(() => {
+                        ws.close();
+                        reject(new Error('WebSocket handshake timed out'));
+                    }, 2000);
                     const onError = (event) => {
+                        clearTimeout(timer);
                         ws.close();
                         reject(new Error(`WebSocket connect failed: ${String(event.type)}`));
                     };
                     ws.addEventListener('open', () => {
+                        clearTimeout(timer);
+                        ws.removeEventListener('error', onError);
                         this.socket = ws;
                         this.connected = true;
                         ws.addEventListener('message', message => this.handleMessage(String(message.data)));
@@ -600,7 +619,12 @@ export class CodexAppClient extends EventEmitter {
                             });
                         });
                         ws.addEventListener('error', err => {
-                            this.logger.warn('codex.ws.error', String(err.message ?? 'unknown'));
+                            this.logger.warn('codex.ws.error', { message: err.message || 'WebSocket transport error', port: this.port });
+                            if (this.socket === ws) {
+                                this.socket = null;
+                                ws.close();
+                                this.handleDisconnect({ source: 'websocket-error', port: this.port });
+                            }
                         });
                         resolve();
                     }, { once: true });
@@ -641,8 +665,22 @@ export class CodexAppClient extends EventEmitter {
         }
         const id = String(++this.requestId);
         return new Promise((resolve, reject) => {
-            this.pending.set(id, { resolve, reject });
-            this.send({ jsonrpc: '2.0', id, method, params });
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                this.logger.warn('codex.request_timeout', { method, timeoutMs: this.requestTimeoutMs });
+                reject(new Error(`Codex request timed out: ${method}. The result is unknown; check /status or use foxclaw resume before retrying.`));
+            }, this.requestTimeoutMs);
+            this.pending.set(id, {
+                resolve: (value) => { clearTimeout(timer); resolve(value); },
+                reject: (error) => { clearTimeout(timer); reject(error); },
+            });
+            try {
+                this.send({ jsonrpc: '2.0', id, method, params });
+            }
+            catch (error) {
+                this.pending.get(id)?.reject(error);
+                this.pending.delete(id);
+            }
         });
     }
     send(payload) {
@@ -682,6 +720,7 @@ export class CodexAppClient extends EventEmitter {
         }
     }
     handleDisconnect(meta) {
+        this.logger.warn('codex.disconnected', meta);
         if (this.connected) {
             this.connected = false;
         }
@@ -703,7 +742,7 @@ export class CodexAppClient extends EventEmitter {
         this.reconnectTimer = setTimeout(async () => {
             this.reconnectTimer = null;
             try {
-                await this.startServer();
+                await this.start();
             }
             catch (error) {
                 this.logger.error('codex.reconnect_failed', { error: String(error) });

package/dist/codex_app/force_takeover.d.ts

@@ -0,0 +1,12 @@
+export interface ExternalWriterIdentity {
+    pid: number;
+    startTime: string;
+    exe: string;
+    lockDevice: string;
+    lockInode: string;
+    cwd: string;
+}
+export declare const externalWriterControl: {
+    inspect(home: string, threadId: string): Promise<ExternalWriterIdentity>;
+    stop(home: string, threadId: string, expected: ExternalWriterIdentity): Promise<void>;
+};

package/dist/codex_app/force_takeover.js

@@ -0,0 +1,27 @@
+import { execFile } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const helper = fileURLToPath(new URL('../../scripts/force-takeover.py', import.meta.url));
+async function runHelper(home, threadId, expected) {
+    if (process.platform !== 'linux')
+        throw new Error('Force takeover requires Linux/WSL with pidfd support');
+    const args = [helper, home, threadId];
+    if (expected)
+        args.push(JSON.stringify(expected));
+    const { stdout } = await execFileAsync('python3', args, { timeout: 12_000, maxBuffer: 16_384 });
+    const response = JSON.parse(stdout);
+    if (!response.ok)
+        throw new Error(response.error ?? 'External writer inspection failed');
+    return response.result;
+}
+export const externalWriterControl = {
+    async inspect(home, threadId) {
+        return await runHelper(home, threadId);
+    },
+    async stop(home, threadId, expected) {
+        const result = await runHelper(home, threadId, expected);
+        if (result.stopped !== true)
+            throw new Error('CLI stop was not confirmed');
+    },
+};

package/dist/controller/controller.d.ts

@@ -66,6 +66,9 @@ export declare class BridgeSessionCore {
     private pendingUserInputs;
     private pendingMcpElicitations;
     private pendingLoginsByScope;
+    private externalWriterControl;
+    private forceTakeoversInProgress;
+    private pendingForceTakeovers;
     private pendingLoginScopesById;
     private pendingAuthAddsByLoginId;
     private latestTurnDiffs;
@@ -287,8 +290,11 @@ export declare class BridgeSessionCore {
     private applyObservedSessionEvents;
     private applyObservedTurnSnapshot;
     private handleTakeoverCommand;
+    private prepareForceTakeover;
+    private handleForceTakeoverCallback;
     private handleQueueCommand;
     private handleActiveTurnInboundMessage;
+    private queueObservedThreadMessage;
     private queuePromptAfterActiveTurn;
     private steerActiveTurn;
     private enqueuePreparedTurnInput;
@@ -340,6 +346,7 @@ export declare class BridgeSessionCore {
     private handleVoiceCallback;
     private sendVoiceForText;
     private handleLoginDeviceCommand;
+    private loginCancelKeyboard;
     private handleLoginCancelCommand;
     private handleLogoutCommand;
     private handleSteerCommand;
@@ -376,6 +383,7 @@ export declare class BridgeSessionCore {
     private requireReadyBinding;
     private handleAuthPanelActionCallback;
     private handleAuthListViewCallback;
+    private refreshRepairedAuthChoice;
     private handleAuthRepairMenuCallback;
     private handleAuthRepairActionCallback;
     private handleAuthToggleCallback;