rtfm CLI is completely broken on native Windows: unconditional 'import fcntl' in core.supervisor

[AVeryTastyRaspberry]

Summary

rtfm-ai 0.35.7 (latest on PyPI) is entirely unusable via the rtfm CLI on native Windows Python (tested: Python 3.12.10, Windows 11, pip 26.2.1). Every command crashes at import time before argument parsing even happens.

Root cause

rtfm/core/supervisor.py does an unconditional, top-level import fcntl:

from __future__ import annotations

import fcntl
import json
import os
import signal
import socket
...

fcntl is POSIX-only and does not exist on Windows. There is no msvcrt-based fallback anywhere in the package — I checked every file under rtfm/core/ and none of them branch on platform for locking.

Since the 0.16.x rearchitecture (per the module docstring: "every mutating command is a thin producer: it enqueues P0 jobs, ensures the worker daemon is running, and watches queue stats"), every mutating CLI command — init, sync, scan, and therefore all indexing — routes through rtfm/cli_worker.py, which imports rtfm.core.supervisor at module level. rtfm/cli.py's main() imports cli_worker unconditionally too, so the crash happens for any CLI invocation, not just worker/daemon subcommands.

Repro

> pip install rtfm-ai
> rtfm --version
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "...\Scripts\rtfm.exe\__main__.py", line 5, in <module>
  File "...\site-packages\rtfm\cli.py", line 2738, in main
    from rtfm.cli_worker import cmd_worker, cmd_worker_daemon, cmd_queue
  File "...\site-packages\rtfm\cli_worker.py", line 31, in <module>
    from rtfm.core.supervisor import (
  File "...\site-packages\rtfm\core\supervisor.py", line 33, in <module>
    import fcntl
ModuleNotFoundError: No module named 'fcntl'

This reproduces even for --version/--help, since the crash is at import time before argparse runs.

What still works

rtfm-serve (the MCP stdio server, rtfm/_mcp/server.py) is a separate, pure-stdlib entry point that does not import cli_worker/supervisor, and it runs cleanly on Windows (rtfm-serve --help exits 0). So the MCP server itself is fine — the problem is entirely confined to the worker/supervisor code path that the CLI depends on for indexing.

Impact

There is currently no way to run rtfm init/sync/scan — i.e. to populate .rtfm/library.db at all — on native Windows Python. The only workaround is running the CLI inside WSL/Linux against a Windows-mounted path, which works (fcntl exists there) but isn't a fix, and isn't discoverable from the README's "runs on ... Windows" claim.

Suggested fix

Guard the lock acquisition in supervisor.py (and anywhere else fcntl is used) behind a platform check, falling back to msvcrt.locking() on Windows, or to a portable cross-platform lock library. Happy to help test a patch if useful — flagging as filed by an AI coding agent (Claude Code) on behalf of a user evaluating rtfm for two Windows-based repos.

[roomi-fields]

Fixed in 0.37.0, on PyPI now. Your diagnosis was right, and the blast radius was wider than the import.

Behind import fcntl sat four more calls that are Unix-only, or mean something else on Windows:

• os.pread, used to read the supervisor's PID — absent on Windows.
• os.kill(pid, 0), the liveness probe: on Windows that call is TerminateProcess. Asking "is the supervisor alive?" would have killed it — and killed whatever process had recycled that PID.
• signal.SIGKILL — undefined, so the last-resort kill in restart-all raised AttributeError instead of killing anything.
• start_new_session=True — accepted and silently ignored, so the supervisor would have died with the console that spawned it.

All of them now live in one module (rtfm/core/portable.py) with a test that fails if any is reached for anywhere else — five unguarded calls behind one guarded import is exactly how this shipped. The lock keeps its flock behaviour and file format byte-for-byte on Unix; on Windows it uses msvcrt.locking on a reserved byte 0, with the PID stamped from byte 1, because a byte-range lock there is mandatory and would refuse a reader the bytes it holds.

Graceful stop, which 0.36.0 could not do on Windows, is in 0.37.0. Each in-flight job holds the only write connection to its project's database, so "stop" has to mean finish what you are holding, then exit — and no signal can mean that on Windows. rtfm worker stop and restart-all now leave a request in ~/.rtfm/supervisor.stop naming the supervisor it is for; the supervisor looks for it twice a second, consumes it, drains, and exits without respawning. Nothing sends a named signal any more. The hard kill stays as the last resort after eight seconds, for a supervisor wedged in a syscall that reads nothing.

One caveat I'd rather state than have you discover: I have no Windows machine. The crash itself is covered by a test that hides fcntl from the import system — it reproduces on 0.35.7 and passes on 0.37.0 — but the msvcrt.locking and OpenProcess calls are written against documented behaviour and are unverified on Windows. Your offer to test is very welcome. pip install -U rtfm-ai, then in a small repo:

rtfm --help            # used to die here
rtfm init --no-embeddings
rtfm status
rtfm worker status
rtfm worker stop        # should drain, not kill

Leaving this open until you confirm. If the lock is the part that misbehaves, rtfm worker start will fail rather than misbehave quietly — that path refuses loudly by design.

A note on the repro: --version isn't a flag. After the fix it reaches argparse and exits 2 with a usage message, which is correct behaviour and not the old crash — rtfm --help and rtfm status are the quick checks.

[AVeryTastyRaspberry]

Confirmed on Windows 11, Python 3.12.10, rtfm-ai 0.37.0. Ran your suggested sequence in a real repo (D:\Kieal.scratch — ~10k tracked files):

Fixed and verified working

• rtfm --help — no more fcntl crash, reaches argparse cleanly. ✅
• rtfm worker status — clean, correct output when no supervisor running. ✅
• rtfm sync — genuinely enqueues and runs a real scan job via the supervisor, live progress line updates (pending=… running=… done=… embed=… scan=…), returns after --timeout with the worker still draining in the background as documented. This is the core fix and it works. ✅
• rtfm worker start — spawns a real supervisor (confirmed via Windows tasklist, not just the tool's own claim), starts a fresh lock correctly even with a stale lock file from a previous dead supervisor sitting there — so msvcrt.locking isn't wedging on stale state. ✅
• rtfm worker stop — graceful drain genuinely works: log shows stop requested — finishing 1 job(s) in flight then supervisor stopping pid=… done=2 failed=0, and the PID was actually gone from tasklist afterward (not just claimed) — so it drained and exited cleanly rather than being force-killed mid-job. ✅

Two small things worth knowing about

1. rtfm status still crashes on Windows — but on a different, unrelated bug, not fcntl:

   File "...\rtfm\cli.py", line 1594, in cmd_status
       print(f"  {mark} {name:<12}missing … pip install {pkg}   ({purpose})")
     File "...\encodings\cp1252.py", line 19, in encode
   UnicodeEncodeError: 'charmap' codec can't encode character '\u2717' in position 2
   

   Windows consoles default to cp1252, which can't encode ✗ (U+2717) or similar Unicode marks used in the optional-extras table. Interestingly the rest of status's output (books/chunks/corpora/embeddings/parsers) printed fine before hitting that line — so it's specifically the "Optional extras" section's status-mark characters. A sys.stdout.reconfigure(encoding='utf-8') or an ASCII fallback (x/- instead of ✗/✓) when the stream can't encode UTF-8 would fix it.

2. Brief post-stop liveness staleness — immediately after worker stop finished draining and the process had genuinely exited (confirmed via tasklist showing no such PID), worker status still reported "supervisor running (PID …)" for a few seconds before flipping to "not running." Not a functional problem (nothing was actually stuck, and a second worker status a moment later correctly reported it as dead + queued jobs), but worth knowing the liveness check has a lag window on Windows immediately after exit — might be a stale-lock-read-before-cleanup race rather than anything in portable.py per se.

One repro-adjacent note, not a bug in 0.37.0 itself

Not something you need to fix, just flagging in case it trips someone else: I'd originally worked around 0.35.7's Windows breakage by running rtfm init inside a Linux Docker container with the repo bind-mounted at /repo. That baked an absolute /repo path into .rtfm/config.json's sources[].path. After upgrading to 0.37.0 and running natively, rtfm sync silently no-op'd (path missing — skipped / nothing to do) until I manually fixed the config back to a relative .. Anyone else who did the same container-workaround dance will hit this on upgrade — might be worth a one-line troubleshooting note, or having sync/status warn loudly when a configured source path doesn't exist rather than silently skipping to "nothing to do."

Overall: this is a real, solid fix — the core Windows blocker is gone and the graceful-stop design works as designed. Thank you for the fast turnaround. Happy to keep testing if useful.

[roomi-fields]

That's the confirmation I couldn't produce here — thank you, especially for checking against tasklist rather than taking RTFM's word for it. msvcrt.locking on a reserved byte, a stale lock file, and the drain are now verified on the platform they were written for and not just reasoned about.

All three follow-ups are fixed in 0.37.1, on PyPI now.

1. rtfm status dying on its own output. Fixed, and your diagnosis was exact — the marks in the optional-extras table. The CLI now asks for UTF-8 when the stream it was handed can't carry what every command prints, with errors="replace" underneath so no output can ever end a run. I went with UTF-8 rather than an ASCII fallback for one reason: a replacement character would print the same glyph for installed and missing, which turns that table into a lie. There are ~3500 non-ASCII characters across the CLI's output (box rules, dashes, arrows), so fixing it at the stream was the only fix that covers all of them rather than the one line you happened to hit.

2. The post-stop liveness lag. Not a stale-lock-read race — the lock genuinely was still held. Windows releases a byte-range lock at process exit, but not synchronously: the documented wording is that how long it takes "depends upon available system resources". So _lock_holder_pid() was telling the truth and the truth was stale. A held lock whose stamped PID is not alive now reads as free, which is a cheap cross-check that never fires on Unix (there the kernel drops a flock the instant its holder dies). Your instinct that it wasn't portable.py per se was right — it was the assumption above it, that a held lock implies a live holder.

3. The container-baked absolute paths. Not a troubleshooting note — a real defect, and worse than you framed it. sync skipped every source and exited 0, so any automation reading the exit code saw success while nothing was indexed. Now: each configured directory that isn't on disk gets its own line, and if none of them exists sync says so and exits non-zero, naming the config file to fix. rtfm sources marks them too. Anyone else who did the container dance will now be told rather than left to work it out.

That does the whole list, so I'm closing this. If anything else turns up — on Windows or not — please open one; this report was unusually good to work from, and the three follow-ups were worth more than the original fix.