hindsight-embed crashes on Windows: ModuleNotFoundError: no module named fcntl

[lquk]

Bug Description

hindsight-embed fails to start on Windows 11 due to a hard dependency on the Unix-only fcntl module. The crash occurs immediately at import time, before any command can execute.

The official installation docs at https://hindsight.vectorize.io/developer/installation state:

Platform: Windows (x86_64) -- Docker: yes, Bare Metal: yes, Embedded DB (pg0): yes -- Fully supported

However, the hindsight-embed CLI package is not functional on Windows due to this issue.

Steps to Reproduce

1. On Windows 11, with Python 3.13 installed and uv package manager available
2. Run: uvx hindsight-embed@latest --help
3. Observe immediate crash

Expected Behavior

The CLI should start and display help text, or gracefully fall back to Windows-compatible file locking.

Actual Behavior

Immediate ModuleNotFoundError at import time.

Full Error Stack

Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "...\hindsight-embed.exe\__main__.py", line 4, in <module>
    from hindsight_embed.cli import main
  File "...\hindsight_embed\__init__.py", line 3, in <module>
    from .daemon_embed_manager import DaemonEmbedManager
  File "...\hindsight_embed\daemon_embed_manager.py", line 23, in <module>
    from .profile_manager import UI_PORT_OFFSET, ProfileManager, resolve_active_profile
  File "...\hindsight_embed\profile_manager.py", line 7, in <module>
    import fcntl
ModuleNotFoundError: No module named 'fcntl'

Root Cause

hindsight_embed/profile_manager.py line 7 contains import fcntl. The fcntl module is a Unix-only standard library module and does not exist on Windows. Similar patterns exist in many Python packages and the standard fix is to use try/except with msvcrt.locking as the Windows fallback.

Environment

• OS: Windows 11 (NT 10.0.26220.0), x86_64
• Python: 3.13.3
• uv: 0.11.2
• hindsight-embed: 0.4.6 (latest as of 2026-04-04)

Impact

This blocks all OpenClaw users on Windows from using the official @vectorize-io/hindsight-openclaw plugin, since the plugin relies on hindsight-embed to start the local daemon.

Suggested Fix

In hindsight_embed/profile_manager.py, replace the unconditional import with a cross-platform fallback. The pattern below adds a minimal compatibility shim:

import sys

if sys.platform == "win32":
    import msvcrt
    # Minimal shim: msvcrt.locking is not a full drop-in for fcntl.flock
    # but is sufficient for the simple file-locking use cases in profile_manager
else:
    import fcntl

Or more robustly, wrap fcntl.flock() calls with a platform-aware helper function:

import sys

if sys.platform != "win32":
    import fcntl
    def _file_lock(fd, exclusive=True):
        fcntl.flock(fd, fcntl.LOCK_EX if exclusive else fcntl.LOCK_SH)
    def _file_unlock(fd):
        fcntl.flock(fd, fcntl.LOCK_UN)
else:
    import msvcrt
    def _file_lock(fd, exclusive=True):
        msvcrt.locking(fd.fileno(), msvcrt.LK_NBLCK, 1)
    def _file_unlock(fd):
        msvcrt.locking(fd.fileno(), msvcrt.LK_UNLCK, 1)

The equivalent pattern has been applied successfully in these projects:

• Hermes Agent issue 3992
• GPUStack issue 4684
• bpython issue 509

---

Note: hindsight-api (the pip package) appears to work on Windows as documented, but hindsight-embed (the CLI used by the OpenClaw integration plugin) is the one that crashes. The installation docs should clarify which package is actually tested on Windows.

[nicoloboschi]

fixed by #867 - will be in the next version