@foxden-app/foxclaw 0.7.2 → 0.7.3

package/docs/zh/user-manual.md

@@ -357,6 +357,14 @@ FoxClaw 的聊天是“绑定线程”的。你在手机上打开某个 Codex
 
 旧版 Codex 没有这个队列接口，FoxClaw 会明确提示升级，不会退回到抢占 writer 或改写 session 文件。要让 Telegram 自己另行启动 turn，仍需先 `/unwatch`。
 
+### `/takeover --force <消息>`：从本机 CLI 强制交接
+
+遇到 `already has an active writer` 时，可发送 `/takeover --force 继续处理`，核对 thread、PID 和工作目录，再点击“确认强制接管”；也可点“取消”。确认仅 60 秒有效，并绑定发起用户和聊天。普通 `/watch`、`/queue` 和 `/takeover` 不会自动停止外部 CLI。
+
+仅支持 Linux/WSL，需 `python3` 3.9+ 和内核 pidfd 支持。只接受当前 bot 的 Codex home 中、同一系统用户的交互式 Codex CLI。拒绝 app-server、远程客户端、桥的祖先进程，以及同时持有其他 thread 锁的进程。确认后重新核实进程启动时间及锁身份，通过 pidfd 先发 SIGTERM，5 秒不退出再发 SIGKILL；检查锁释放后，才恢复原 thread 并提交指定消息。不会删除锁或修改 session 文件，不会自动重试提交。
+
+强停可能打断未完成任务，已启动的子命令可能继续运行，文件修改不会回滚。身份变化、锁未释放或恢复失败都会明确报错，不投递新任务。桥自己的旧待执行队列只在成功取得写入权后取消；原 CLI 的跨客户端队列不会被此功能清空。多线程 CLI 请在终端手动交接。
+
 ## 6. Codex 登录和 auth 轮转
 
 这是 FoxClaw 的特色功能。Codex 的登录状态通常保存在 `~/.codex/auth.json`。FoxClaw 把多个账号保存成候选文件，并通过切换 `auth.json` 指向哪个候选来换号。启用 `TG_BOT_TOKENS` 多 bot 模式后，默认每个 bot 使用独立 Codex home、独立 app-server 和独立当前候选，因此可以并行运行、单独切号；隔离 Telegram runtime 会强制使用文件凭据存储。已验证的登录/刷新凭据会安全镜像到其他 bot home，但不会共享 session。
@@ -365,7 +373,11 @@ FoxClaw 的聊天是“绑定线程”的。你在手机上打开某个 Codex
 
 ### 6.1 文件格式
 
-单 bot 兼容模式的候选文件放在 Codex auth 目录，默认是 `~/.codex/`。如果你设置了 `CODEX_AUTH_DIR`，则使用那个目录。多 bot 模式以这个目录作为候选源，并在 `~/.foxclaw/codex/telegram/bot<id>/home/` 下为隔离 bot 保存副本。默认/终端共享 bot 不创建隔离副本，而是直接使用这个默认 auth 目录。
+单 bot 兼容模式的候选文件放在 Codex auth 目录，默认是 `~/.codex/`。如果你设置了 `CODEX_AUTH_DIR`，则使用那个目录。多 bot 模式以这个目录作为候选源，并在 `~/.foxclaw/codex/telegram/@Telegram用户名/home/` 下为隔离 bot 保存副本，例如 `@WuguiAI_Bot/home/`。默认/终端共享 bot 的名称目录通过链接指向原来的 Codex home，保留终端互通能力。
+
+启动时并行读取 Telegram 的真实用户名。已有 `bot<id>` 目录会迁移到名称目录，旧路径保留兼容链接；更改用户名后，下次启动会更新目录名称并保留旧名称链接。首次启动无法联网时临时使用 `bot<id>`，之后启动取到用户名再迁移；已有名称在断网重启时继续使用。迁移前请让相关会话空闲。遇到同名冲突会明确停止，不合并或覆盖目录。
+
+名称目录中的 `.foxclaw-bot.json` 只保存稳定的数字 bot ID，不保存 token，供媒体发送判断目标账号。不要删除该文件或旧路径链接。数据库绑定、运行日志及服务状态仍用稳定 bot ID 标识；项目工作目录仍由 `DEFAULT_CWD` 或 `/new <目录>` 决定。
 
 推荐命名：
 

package/package.json

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

package/scripts/force-takeover.py

@@ -0,0 +1,118 @@
+"""Linux-only, fail-closed handoff of one local interactive Codex writer.
+
+No lock files are removed. pidfd keeps signals bound to the inspected process,
+even if its numeric PID is reused. stdout is a small JSON protocol.
+"""
+import fcntl
+import json
+import os
+from pathlib import Path
+import re
+import select
+import signal
+import sys
+
+
+def lock_owners(lock_path):
+    st = lock_path.stat()
+    key = (os.major(st.st_dev), os.minor(st.st_dev), st.st_ino)
+    owners = []
+    for line in Path('/proc/locks').read_text().splitlines():
+        fields = line.split()
+        if len(fields) != 8 or fields[1:4] != ['FLOCK', 'ADVISORY', 'WRITE']:
+            continue
+        major, minor, inode = fields[5].split(':')
+        if (int(major, 16), int(minor, 16), int(inode)) == key:
+            owners.append(int(fields[4]))
+    return owners
+
+
+def process_stat(pid):
+    # comm can contain spaces and parentheses; fields after the final ')' are stable.
+    return Path(f'/proc/{pid}/stat').read_text().rsplit(')', 1)[1].split()
+
+
+def inspect_writer(home, thread_id):
+    if sys.platform != 'linux' or not hasattr(os, 'pidfd_open') or not hasattr(signal, 'pidfd_send_signal'):
+        raise RuntimeError('Requires Linux/WSL with Python 3.9+ and pidfd support')
+    if not re.fullmatch(r'[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}', thread_id):
+        raise RuntimeError('Invalid thread ID')
+    lock_path = Path(home).resolve() / 'thread-writer-locks' / f'{thread_id}.lock'
+    owners = lock_owners(lock_path)
+    if len(owners) != 1 or owners[0] <= 1:
+        raise RuntimeError('No unique local writer; nothing was stopped')
+    pid = owners[0]
+    proc = Path(f'/proc/{pid}')
+    stat = process_stat(pid)
+    if proc.stat().st_uid != os.getuid():
+        raise RuntimeError('Writer belongs to a different OS user')
+    exe = os.readlink(proc / 'exe')
+    argv = (proc / 'cmdline').read_bytes().split(b'\0')
+    if Path(exe).name != 'codex' or int(stat[4]) == 0:
+        raise RuntimeError('Writer is not an interactive Codex CLI')
+    if any(arg in (b'app-server', b'exec', b'e', b'review', b'mcp-server', b'--remote') or arg.startswith(b'--remote=') for arg in argv[1:]):
+        raise RuntimeError('Refusing to stop a server, noninteractive CLI, or remote client')
+    ancestor = os.getpid()
+    while ancestor > 1:
+        if ancestor == pid:
+            raise RuntimeError('Refusing to stop an ancestor of this bridge')
+        ancestor = int(process_stat(ancestor)[1])
+    # A single CLI may own subagent threads: stopping it would affect them too.
+    held_threads = set()
+    for fd in (proc / 'fd').iterdir():
+        try:
+            target = os.readlink(fd)
+            if '/thread-writer-locks/' in target and not target.endswith('/.coordination.lock'):
+                held_threads.add(target)
+        except FileNotFoundError:
+            continue
+    if held_threads != {str(lock_path)}:
+        raise RuntimeError('Writer has additional or unidentifiable thread locks; manual handoff required')
+    st = lock_path.stat()
+    identity = {
+        'pid': pid, 'startTime': stat[19], 'exe': exe,
+        'lockDevice': str(st.st_dev), 'lockInode': str(st.st_ino),
+        'cwd': os.readlink(proc / 'cwd'),
+    }
+    if lock_owners(lock_path) != [pid] or process_stat(pid)[19] != identity['startTime']:
+        raise RuntimeError('Writer changed during inspection; request confirmation again')
+    return identity
+
+
+def stop_writer(home, thread_id, expected):
+    # Open first, then revalidate. A recycled PID can never receive our signal.
+    fd = os.pidfd_open(expected['pid'])
+    try:
+        if inspect_writer(home, thread_id) != expected:
+            raise RuntimeError('Writer changed since confirmation; nothing was stopped')
+        poller = select.poll()
+        poller.register(fd, select.POLLIN)
+        signal.pidfd_send_signal(fd, signal.SIGTERM)
+        if not poller.poll(5000):
+            # Recheck scope before escalation, retaining the original pidfd.
+            if inspect_writer(home, thread_id) != expected:
+                raise RuntimeError('Writer changed after SIGTERM; refused SIGKILL')
+            signal.pidfd_send_signal(fd, signal.SIGKILL)
+            if not poller.poll(3000):
+                raise RuntimeError('CLI exit timed out; handoff not completed')
+    finally:
+        os.close(fd)
+    lock_path = Path(home).resolve() / 'thread-writer-locks' / f'{thread_id}.lock'
+    # Actual flock check, not just PID disappearance. Never unlink the lock.
+    try:
+        with lock_path.open('rb') as lock:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except FileNotFoundError:
+        pass  # A clean CLI exit removed its own lock.
+    except BlockingIOError:
+        raise RuntimeError('CLI exited but thread is still locked; handoff not completed') from None
+    return {'stopped': True}
+
+
+if __name__ == '__main__':
+    try:
+        home, thread_id = sys.argv[1:3]
+        result = stop_writer(home, thread_id, json.loads(sys.argv[3])) if len(sys.argv) == 4 else inspect_writer(home, thread_id)
+        print(json.dumps({'ok': True, 'result': result}))
+    except Exception as error:
+        print(json.dumps({'ok': False, 'error': str(error)}))

package/scripts/force-takeover.test.py

@@ -0,0 +1,122 @@
+import fcntl
+import importlib.util
+import os
+from pathlib import Path
+import pty
+import shutil
+import signal
+import tempfile
+import time
+import unittest
+from unittest.mock import patch
+
+spec = importlib.util.spec_from_file_location('takeover', Path(__file__).with_name('force-takeover.py'))
+takeover = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(takeover)
+THREAD = '00000000-0000-0000-0000-000000000001'
+
+
+class WriterTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory(prefix='foxclaw-force-test-')
+        self.home = Path(self.temp.name)
+        (self.home / 'thread-writer-locks').mkdir()
+        self.lock = self.home / 'thread-writer-locks' / f'{THREAD}.lock'
+        self.pid = None
+        self.terminal = None
+
+    def tearDown(self):
+        if self.pid:
+            try:
+                os.kill(self.pid, signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+            os.waitpid(self.pid, 0)
+        if self.terminal is not None:
+            os.close(self.terminal)
+        self.temp.cleanup()
+
+    def writer(self, extra_lock=False, ignore_term=False, name='codex'):
+        # Harmless sleep binary: real PTY, PID, flock and pidfd, never a user CLI.
+        executable = self.home / name
+        shutil.copyfile('/bin/sleep', executable)
+        executable.chmod(0o700)
+        pid, terminal = pty.fork()
+        if pid == 0:
+            if ignore_term:
+                signal.signal(signal.SIGTERM, signal.SIG_IGN)
+            locks = [self.lock]
+            if extra_lock:
+                locks.append(self.lock.with_name('00000000-0000-0000-0000-000000000002.lock'))
+            for lock in locks:
+                fd = os.open(lock, os.O_CREAT | os.O_RDWR, 0o600)
+                os.set_inheritable(fd, True)
+                fcntl.flock(fd, fcntl.LOCK_EX)
+            os.execl(str(executable), name, '60')
+        self.pid, self.terminal = pid, terminal
+        for _ in range(200):
+            if os.readlink(f'/proc/{pid}/exe') == str(executable):
+                return
+            time.sleep(0.01)
+        self.fail('Fixture did not start')
+
+    def test_inspect_does_not_signal_and_stop_releases_real_lock(self):
+        self.writer()
+        identity = takeover.inspect_writer(self.home, THREAD)
+        self.assertEqual(identity['pid'], self.pid)
+        os.kill(self.pid, 0)
+        self.assertEqual(takeover.stop_writer(self.home, THREAD, identity), {'stopped': True})
+        self.assertTrue(self.lock.exists(), 'helper must not unlink lock files')
+        with self.lock.open('rb') as lock:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+
+    def test_escalates_only_confirmed_process_after_term_timeout(self):
+        self.writer(ignore_term=True)
+        identity = takeover.inspect_writer(self.home, THREAD)
+        takeover.stop_writer(self.home, THREAD, identity)
+        self.assertEqual(takeover.process_stat(self.pid)[0], 'Z')
+
+    def test_stale_identity_never_signals(self):
+        self.writer()
+        identity = takeover.inspect_writer(self.home, THREAD)
+        identity['startTime'] = 'wrong-start-time'
+        with self.assertRaisesRegex(RuntimeError, 'changed since confirmation'):
+            takeover.stop_writer(self.home, THREAD, identity)
+        self.assertEqual(takeover.lock_owners(self.lock), [self.pid])
+
+    def test_additional_thread_refused(self):
+        self.writer(extra_lock=True)
+        with self.assertRaisesRegex(RuntimeError, 'additional'):
+            takeover.inspect_writer(self.home, THREAD)
+
+    def test_non_codex_refused(self):
+        self.writer(name='sleep')
+        with self.assertRaisesRegex(RuntimeError, 'not an interactive'):
+            takeover.inspect_writer(self.home, THREAD)
+
+    def test_server_remote_and_other_user_refused(self):
+        self.writer()
+        for arg in (b'app-server', b'exec', b'--remote', b'--remote=ws://localhost:9000'):
+            with patch.object(Path, 'read_bytes', return_value=b'codex\0' + arg + b'\0'):
+                with self.assertRaisesRegex(RuntimeError, 'Refusing to stop'):
+                    takeover.inspect_writer(self.home, THREAD)
+        with patch.object(os, 'getuid', return_value=os.getuid() + 1):
+            with self.assertRaisesRegex(RuntimeError, 'different OS user'):
+                takeover.inspect_writer(self.home, THREAD)
+
+    def test_ancestor_refused(self):
+        self.writer()
+        with patch.object(os, 'getpid', return_value=self.pid):
+            with self.assertRaisesRegex(RuntimeError, 'ancestor'):
+                takeover.inspect_writer(self.home, THREAD)
+
+    def test_unlocked_file_and_invalid_id_refused(self):
+        self.lock.touch()
+        with self.assertRaisesRegex(RuntimeError, 'No unique'):
+            takeover.inspect_writer(self.home, THREAD)
+        with self.assertRaisesRegex(RuntimeError, 'Invalid thread'):
+            takeover.inspect_writer(self.home, '../../outside')
+
+
+if __name__ == '__main__':
+    unittest.main()