@foxden-app/foxclaw 0.7.1 → 0.7.3

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()