feat(windows): unblock the import path and cover it in CI

[gloryfromca]

Summary

Makes EverOS run on native Windows as far as the unit suite can see, and puts
a CI job behind that claim.

import fcntl at module scope in core/persistence/locking.py was the
single import-time blocker. It sits on core.persistence.__init__, which
every persistence path imports, so even everos --help died with ImportError
before printing anything:

cli/main.py:16 -> commands/cascade.py:43 -> component/embedding/__init__.py:33
  -> component/utils/config_hints.py:11 -> core/persistence/__init__.py:36
  -> core/persistence/locking.py:24  ->  ImportError: No module named 'fcntl'

portalocker is already a dependency (the OME single-engine guard uses it) and
dispatches to fcntl.flock on POSIX / LockFileEx on Windows, so no new
dependency and no change in POSIX semantics.

With the import path open, the first Windows CI run surfaced what was behind
it: 12 failed / 2538 passed. Three were real defects, the rest were POSIX
assumptions in tests. All fixed here; the third run is 2550 passed / 4
skipped, identical to Linux.

Defect	Where	Fix
file:// uris never worked on Windows — unquote leaves the leading-slash drive form /C:/x	memory/extract/parser/mapping.py	urllib.request.url2pathname, the stdlib converter; a no-op beyond percent-decoding on POSIX
Text IO without encoding= follows the locale (cp1252 on Windows); TUI demo frames raised UnicodeEncodeError on box-drawing glyphs	7 sites in tui/demo/readme_media.py and infra/persistence/lancedb/__init__.py	explicit utf-8. The markdown layer already passed it everywhere, so memory data was never at risk
SO_REUSEADDR means the opposite on Windows — a second socket may bind a port the probe holds, so the benchmark fleet's hold-until-spawn excluded nobody	benchmarks/run.py	SO_EXCLUSIVEADDRUSE where it exists

Things that looked like blockers and were not: lancedb ships a win_amd64
wheel; portalocker already branches on os.name; watchdog's Observer
dispatches to WindowsApiObserver; uvloop is excluded on win32 by uvicorn's
markers; raise_signal(SIGTERM) in the cascade worker is only reachable under
the API lifespan, where uvicorn's handler is installed on Windows too.

Plus a Windows / WSL2 install guide, with a Chinese mirror, and
scan_interval_seconds becomes a real [cascade] setting (reviewer note 5).

Coverage for the two subsystems most exposed to a different OS — the
cascade watcher and the LanceDB store — 20 new unit tests that run on all
three CI platforms and assert on outcomes, never event order (reviewer note
6). Writing them surfaced one real watcher defect, fixed in fd3c9da: a late
modified for a path already unlinked overwrote the deleted row and
resurrected a gone file until the scanner's next sweep. FSEvents reorders;
the guard now records disk truth.

Then the branch was run on a stock Windows 11 Enterprise machine — no VC++
redistributable, corporate image, nothing preinstalled — and it did not start:
import greenlet → DLL load failed while importing _greenlet. greenlet sits
under SQLAlchemy's async engine, so every SQLite call was dead. Of 27 compiled
packages it was the only one to fail; its wheel links msvcp140.dll and does
not ship it. windows-latest has the redistributable preinstalled, so CI is
structurally unable to catch this. Fixed in d91702a with no manual step
(reviewer note 7): a Windows-only msvc-runtime dependency puts the DLLs in
sys.prefix, and everos/__init__.py registers that directory with the DLL
loader before anything else imports. On the same machine afterwards:
everos init and everos cascade status (opens SQLite) exit 0, and all 23
new tests pass — including the six real ReadDirectoryChangesW observer tests.

Area

• Architecture method
• Benchmark
• Use case
• Documentation
• Developer experience
• CI, build, or release

Verification

CI on this branch (latest run):
  unit tests (Windows)         2573 passed, 4 skipped     <- all 23 new tests ran there, msvc-runtime
                               installed by marker; same skips as Linux/macOS (benchmark datasets absent)
  unit tests / (3.13)          pass
  integration tests / (3.13)   pass
  lint, package, links, commit messages, PR title   pass
  integration tests (Milvus)   FAIL -- upstream: `pull access denied for minio/minio`.
                               Also failing on PR #453; last green on main was 2026-09-08.
                               Not touched by this branch.

Local (macOS):
  make ci                      exit 0 (lint -> test -> integration -> package)
  unit                         2576 passed, 4 skipped  (2550 before the 26 new tests)
  integration                  183 passed, 5 skipped, 7 deselected

Windows branches that macOS cannot reach, proven another way:
  url2pathname  -- called nturl2path.url2pathname directly (what url2pathname
                   resolves to on Windows): three drive-letter cases round-trip;
                   the old unquote gave `/C:/...` for each.
  import path   -- meta_path finder blocking POSIX-only stdlib: all 11 EverOS
                   layers import clean (9 of 11 failed before the lock change).

Mutation pass on the new tests: 13 source mutations (guards removed, branches
inverted, fallback constants moved, Observer.schedule() dropped) each turned
their target tests red on the claimed symptom; sources restored byte-identical.
The three Lance probes (handle release after close(), prune with an open
reader, MAX_PATH) cannot be reddened on POSIX -- they exist to be run on
windows-latest and a red there is a finding, not a test bug.

The one timing test touched (test_rebuild_runs_periodically) had its window
widened from 0.2s to 0.6s; the >= 3 assertion is unchanged. One TUI scroll
test got an extra pilot.pause() on each side of scroll_home; assertions
unchanged. Neither is reproducible on macOS.

Stock Windows 11 Enterprise box (no VC++ redistributable), branch at 9c0fe18:
uv python install 3.12 + uv sync --frozen ok (msvc-runtime pulled in by marker)
import everos, greenlet 3.5.3 <- via the hook
import greenlet (control, no everos first) DLL load failed <- the pre-fix state
everos init --root exit 0
everos cascade status --root exit 0 <- opens SQLite via the console script
the 23 new tests 23 passed
full unit suite 2573 passed, 4 skipped
full integration suite (stubs, no key) 183 passed, 5 skipped (Milvus, no URI), 7 deselected (slow/live)
incl. test_cascade_fsevents_repro (os.replace bursts vs the real watcher) and
test_memorize_concurrent_session_lock (cross-process lock under LockFileEx)

Then the loop the Windows guide is really about, on that same machine:
everos server start --root (detached, dummy LLM key -> Tier 1) /health 200 in 2s
write users/admin/episodes/episode-2026-09-23.md with a marker token
6s later: cascade_worker_processed kind=episode upserted=1 <- ReadDirectoryChangesW, for real
everos cascade status: done 1 / pending 0 / failed 0
POST /api/v2/memory/search method=keyword query= 200, the episode, score 0.86
So on a stock Windows machine: install -> start -> edit a file -> search it,
with no installer, no administrator step, no manual prerequisite.

Then the slow/live selection, on the same machine, with real OpenRouter +
DeepInfra keys (never persisted there):
-m "slow or live_llm" 28 passed, 1 skipped, 0 failed, exit 0, 9m05s
the skip is test_real_sigint_during_phase_await (os.kill(pid, SIGINT) is
TerminateProcess on Windows -- it killed the pytest process on the first try)
Getting there fixed three things in the suite itself (commits 167473d, 89ac544):
tests/e2e/test_reflection_e2e.py could not be collected since #425 on main
(bare import adapters), which aborted every live run everywhere; the
multimodal e2e hand-built file://{path}; the rename watcher test asserted
the source leg on the watcher alone where ReadDirectoryChangesW can split the
RENAMED pair across reads (now asserted after one sweep).

And a soak (the LanceDB soak harness, ported to Windows: psutil instead of
/proc, Win32_Process.Create instead of systemd, in-process RSS/disk caps
instead of cgroup) is running on that machine as this is written: 10 h at
the ceiling preset, two concurrent cascade sync storms, disk capped at
80 GB. Its dry run surfaced the writer defect fixed in 47b96eb (reviewer
note 8). Results land in a follow-up.

Still not verified: the editor-saved edit above was written by a script
(VS Code writes CRLF; the watcher tests cover in-place and atomic saves, the
live loop has not yet seen one). One machine so far. The guide still says
native Windows is not yet supported; that sentence gets revisited with the
soak result.
The WSL2 guide's networking claims (localhost forwarding, \\wsl$\ inotify)
are from documented WSL mechanics, not measured.

Checklist

• I kept the change scoped to the relevant area.
• I am opening this from a separate branch, not pushing directly to main.
• I updated docs, examples, or setup notes when behavior changed.
• I added or updated tests when the change affects behavior.
• I did not commit secrets, .env files, dependency folders, or generated output.
• Active relative links in Markdown files resolve.

Notes for Reviewers

1. AlreadyLocked is not an OSError subclass, so the contention branch
   stopped catching BlockingIOError. Getting that wrong turns a normal wait
   into an unhandled exception.
2. portalocker's POSIX branch is fcntl.flock, not lockf — record-lock
   semantics ("closing any fd for the file drops all locks") would have been a
   real regression.
3. The Windows CI job calls uv directly, not make — the image has no
   usable make. uv sync --frozen works because the lockfile is universal
   (sys_platform == 'win32' markers, pywin32 present).
4. SO_EXCLUSIVEADDRUSE is selected by hasattr, not a platform string —
   src/ has zero sys.platform checks and this keeps it that way.
5. scan_interval_seconds is now a [cascade] setting (last commit). It
   was a CascadeConfig dataclass default that from_settings() never read,
   while docs/cascade_runbook.md told operators to "drop the scan interval to
   ~2.5 s" — advice that needed a code change to follow. It matters most on the
   mounts this PR documents: a Windows directory bound into WSL2 or a container
   delivers no filesystem events, so the scanner is the only path an md edit
   takes to the index and its interval is the edit-to-searchable latency.
   The exact-set test on CascadeSettings.model_fields grows by one; its own
   rule (deadlines stay constants, cadences may move) classifies this as a
   cadence. The forwarding test asserts on the scanner's _interval, not on
   CascadeConfig, for the same reason the existing four assert on the worker.
6. The watcher tests read md_change_state, not events. inotify, FSEvents
   and ReadDirectoryChangesW disagree about what an editor's save looks like
   (Windows reports os.replace over an existing file as REMOVED + RENAMED, so
   on_deleted fires for a path that still exists). Asserting on the final row
   is what lets one test hold on all three. The six real-Observer tests wait
   up to 15 s for delivery; a passing run takes ~1 s, the deadline only bites
   when nothing arrives -- which is exactly the /mnt/c failure the guide
   warns about. If test_deep_memory_root_still_stores_and_counts reds on
   Windows, the fix is documentation (LongPathsEnabled) or a startup check,
   not the test.
7. msvc-runtime is a supply-chain decision, stated plainly. Its PyPI
   metadata has no author or homepage and the license field reads
   "Proprietary" (Microsoft's redistributable terms, repackaged). It ships
   per-CPython win32/amd64/arm64 wheels and tracks MSVC versions (14 releases,
   14.29 → 14.44); uv.lock pins it by hash and the marker keeps it off POSIX
   entirely. The alternative is telling every Windows user to install the
   redistributable by hand, which is the manual step this PR exists to remove.
   Two things the hook does not cover: (a) a host application that imports
   sqlalchemy before everos — sqlalchemy imports greenlet eagerly, so the
   registration comes too late; the test suite hit exactly this and
   tests/conftest.py now imports everos first. Covering arbitrary import
   order needs a startup .pth shipped in the wheel — a packaging change,
   left as a separate decision. (b) Nothing; the feature-detected
   getattr(os, "add_dll_directory", None) keeps src/ at zero
   sys.platform checks and makes the hook a no-op on POSIX and on Windows
   machines that already have the redistributable.
8. writer.py now retries the staging swap through a Windows sharing
   violation (47b96eb). The soak dry run's load feeder died 62 s in with
   PermissionError: [WinError 5] from os.replace(tmp, target) -- the
   target was open in another process at that instant (cascade worker
   reading it, Defender scanning it). The server's own markdown writer is the
   same primitive at the same call, so /add would have failed the same way
   under load. _replace_with_retry retries only PermissionError with
   exponential backoff (8 attempts, ~2.5 s), re-raises unchanged after the
   budget, never retries other errors; each attempt is one atomic
   os.replace. POSIX never raises here, so behaviour there is unchanged and
   no platform check was needed. Three tests fake os.replace and pin the
   behaviour on every platform; each was mutation-checked. The retry fired
   within the first minute of the real soak (REPLACE_RETRY_OK after 1 retries), so the condition is real and frequent on Windows.

🤖 Generated with Claude Code

Native Windows verification (2026-09-23/24, stock Windows 11 Enterprise laptop)

Machine: Intel Core Ultra 7 155H (22 threads), 32 GB, no Visual C++ Redistributable, Python 3.12 via uv. Everything below ran on that box, not in CI.

What	Result
pip install everos → everos init → everos server start	works, no manual step (msvc-runtime supplies the C++ runtime greenlet needs; everos/__init__.py registers sys.prefix with the DLL loader)
unit / integration / live-LLM suites	2576 passed / 4 skipped · 183 passed / 5 skipped · 28 passed / 1 skipped
Four memory kinds on a Tier 3 server (real LLM + embedding + rerank)	episode 5 · profile 1 · agent case 1 · agent skill 1 produced and read back via /get and /search
Python range	3.12 / 3.13 / 3.14 regular: unit + integration green unchanged; ≤3.11 refused (requires-python, PEP 695 in src/); 3.14t: no lancedb wheel
10 h soak (feeder ~1 md rewrite/s + 0.5 search/s + 12 % /add, two concurrent everos cascade sync processes, md fuzz)	78 264 entries · 16 328 searches · 2 264 /add · storms 1 754 + 1 769 runs, 0 errors · integrity CLEAN (all tables open, schemas verify, no entry lost) · RSS 224 MB → plateau ~2.3 GB from hour 3 (max 2.9 GB) · LanceDB dir peak 6.7 GB, floor 2.7 GB, live 437 MB · disk net +6.6 GB at peak, returned · os.replace sharing violations: 49 retried, 0 gave up

Fixed along the way (all in this PR): POST /add with an orphan role: "tool" row → 422 instead of 500 (06509b2); a bare ManualTick at a business-event strategy → not_dispatched instead of a dead-lettered AttributeError (5692baf), and the follow-up so a manual trigger still reaches a Cron strategy like reflect_episodes (c99db49).

Found by the soak, not Windows-specific, tracked outside this PR:

• Two processes running the cascade on the same tree (server worker + CLI cascade sync) can each insert the same row: after 10 h, 1 158 / 1 219 / 1 241 duplicate global ids in episode / atomic_fact / foresight (~4.5 % extra rows, same md_path, same content, updated_at 14 s apart). No corruption; counts and disk inflate.
• Request latency under sustained write load: search p50 0.5 s in hour 0 → 3.2 s in hour 9 (p95 up to 7 s), five /health 5 s timeouts, while the same query on the idle server takes 12–15 ms and raw Lance FTS < 100 ms. py-spy: the event-loop thread spends ~85 % of its busy time in lancedb to_list(), half of it in import pytz failing on every timestamp value (pyarrow tries pytz first, the failed import is not cached, each attempt walks sys.path; Defender makes every stat expensive on Windows).
• atomic_fact version cleanup lost the commit race against the CLI processes for ~45 min (health reported it as designed; it recovered).

Related PRs: #455 (API doc clarifications found by driving the server the way the Claude Code plugin does), #456 (knowledge document deleted before it was indexed came back).

CI note: integration tests (Milvus 2.6) is red on every branch since the minio/minio Docker Hub image went away; unrelated to this PR.

Adversarial review round (2026-09-24)

Two read-only reviewers attacked this branch (product code; tests / CI / docs). No blocker. Fixed in b75e755 + ab33efe:

• DLL hook only probed sys.prefix; a pip install that falls back to a per-user install puts the wheel's data files under site.getuserbase(), where the hook was a no-op. Both bases are probed now, with a test.
• Comments that were not true: the locking module said LockFileEx (portalocker's default Windows locker is msvcrt.locking, same semantics); the replace-retry budget is ~2.5 s, not ~5 s (also wrong in 47b96eb's body); POSIX can raise PermissionError on an immutable target.
• Each os.replace retry now logs at debug level — the soak's 49 retries were the harness writer's; the product path was unobservable.
• scan_interval_seconds gains gt=0; docs/api.md's not_dispatched sentence names the fifth gate.
• The two watcher save tests asserted only "not deleted / still pending", which the first write already satisfied — with the handler stubbed out they passed. They now assert the row's mtime advanced.
• Guide: the unit number was a macOS figure (now the CI windows-latest count, 2583 / 4); "pip install" was not the path run (a uv checkout was — the wheel path is being verified on the box now and the sentence will be restored with that evidence); "no entry lost" excludes the deliberately malformed fuzz files; 3.13 / 3.14 are attributed to CI / macOS; the intro no longer contradicts the native section; LongPathsEnabled and the wheel-only msvc-runtime risk are stated.

Left for the maintainers: make unit tests (Windows) a required check after merge (command in .work_context/windows_support/status.md); decide whether msvc-runtime shipping wheels only, per CPython minor, is acceptable (a newer Python cannot install EverOS on Windows until upstream publishes a wheel).