Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs: Windows-CI study + measured Phase 0/1 results on marvin

AkitaOnRailsa2b195d47ce9
diff --git a/docs/design-windows-ci.md b/docs/design-windows-ci.md
new file mode 100644
index 00000000..93a8277c
--- /dev/null
+++ b/docs/design-windows-ci.md
@@ -0,0 +1,467 @@
+# Design: a fast local Windows test/build loop (dockur on marvin) alongside `windows-latest`
+
+**Status: Phase 0 shipped; Phase 1 measured on marvin (see the results section at the
+end).** This began as a feasibility + design study evaluating options for a fast, reliable,
+mostly-local Windows test/build loop to supplement (not blindly replace) the current GitHub
+`windows-latest` CI. Phase 0 (the cross-compile build gate) has since been implemented and
+Phase 1 (the dockur VM) has been stood up and benchmarked; the "Phase 1 results" section at
+the end records the measured numbers and the host-specific accommodations, and revises the
+recommendation accordingly. The body below is the original study, preserved as the rationale.
+
+This is a *written study*. Every recommendation is grounded in the repo's actual setup
+(`.github/workflows/windows.yml`, the enumerated `#[cfg(windows)]` surface, and the
+recent flake history) and in cited external sources. Fetched web content was treated as
+untrusted; only facts were extracted.
+
+## Problem
+
+Windows is a real, shipped target — "Experimental" in the support matrix
+(`docs/support-matrix.md`), but tagged releases publish `ai-memory-windows-x86_64.zip`
+with `ai-memory.exe`, and the PowerShell hook/wrapper surface exists *only* for Windows.
+The `#[cfg(windows)]` regression tests are the one place several Windows-only code paths
+ever execute: the Linux/macOS matrix in `ci.yml` never compiles them. So the coverage is
+not optional — but the way we get it hurts.
+
+**Quantified cost (from the `windows.yml` header comment).**
+
+- A Windows run takes **~1000s** against **~250s** for the same tests on Linux — slower
+ linking, and a cache restore that is **~10x slower** over many small files.
+- Every gating job in `ci.yml` finishes in **~8 minutes**. Leaving Windows *in* that
+ workflow made every pull request wait **~17 minutes**, with the last ~8 spent on a job
+ that was `continue-on-error` and therefore blocked nothing.
+- The response was to pull Windows out into its own workflow, gated three ways:
+ nightly cron (`23 4 * * *`), `workflow_dispatch`, and the `windows` **label** on a PR
+ that touches platform-sensitive code. The job dropped `continue-on-error`, so those
+ runs are now red-or-green rather than advisory.
+
+**Observed pain beyond raw slowness (from git history + CHANGELOG).**
+
+- **Cold-start flake.** `powershell_utf8`'s connect deadline had to be widened from 10s
+ to **60s** because a cold PowerShell start on a loaded `windows-latest` runner (process
+ spawn + JIT + dot-sourcing the hook lib) "can take well over ten seconds before the
+ hook opens its connection" (commit `94057581`, PR #842). The 10s deadline was marginal
+ and flaked.
+- **Eval-gate timeout relaxations.** Windows needed relaxed eval-gate test timeouts and
+ aligned dependency pins (`032ec2fc`), and a further `fix/windows-eval-gate-test-timeout`
+ (PR #827). Timing assumptions that hold on Linux do not hold on a shared Windows runner.
+- **Hook-shell friction on the runner** (#758 family): quote the PowerShell interpreter
+ path (`2cd18840`), convert MSYS paths before handing them to `powershell.exe`
+ (`d5afdcbf`), and give the hook bundle its own job then gate it behind the `windows`
+ label (`a8405568`, `deb64063`).
+- **Fork-PR gating friction.** GitHub requires manual approval ("action_required") before
+ a workflow runs on a fork PR from an outside contributor. Combined with the label gate,
+ a contributor's Windows-relevant change often needs a maintainer to *both* approve the
+ run *and* add the `windows` label — and only then wait ~1000s. Feedback on a
+ Windows-sensitive fork PR is therefore slow and manual.
+
+The through-line: `windows-latest` is **shared, slow, and timing-noisy**, so we pay for it
+with label-gating friction, hand-relaxed timeouts, and per-flake patches. The maintainer
+develops on Linux and runs a homelab box, **marvin** (Linux, 32 cores, ~2.6 TB free,
+KVM available), which is idle capacity that could give a Windows loop measured in *tens of
+seconds of iteration* instead of a ~17-minute round trip through GitHub.
+
+The goal of this study: a fast, reliable, mostly-local way to run the real-Windows surface
+on demand (and before every release), **without** taking on the security or licensing
+liabilities that the obvious "just self-host a runner" answer carries.
+
+## The Windows-specific surface (what actually needs real Windows)
+
+The study has to be concrete about *what* must run on native Windows versus what Linux
+already covers, or the cost/benefit of every option is guesswork. Enumerated from the code:
+
+### Only faithfully validated on real Windows
+
+- **Drain-lock `ERROR_LOCK_VIOLATION`** — `crates/ai-memory-cli/src/commands/hook_spool.rs`
+ defines `ERROR_LOCK_VIOLATION = 33` and `is_drain_lock_busy_error` treats it as
+ "busy, retry." The *unit* test injects the code via `Error::from_raw_os_error(33)` and so
+ runs on any platform, but whether the OS actually *returns* code 33 for a contended
+ drain lock is a real-Windows fact.
+- **NTFS file-index "inode" + sharing-violation retry** —
+ `crates/ai-memory-wiki/src/atomic.rs` reads the NTFS file index via
+ `GetFileInformationByHandle` (`winapi_util::file::information`) so the watcher can skip
+ its own writes, and `persist_with_retry` absorbs a transient
+ `ERROR_SHARING_VIOLATION (32)` — "the Windows-CI antivirus scenario." The retry test
+ injects error 32 everywhere; the *real* NTFS file-index value and a *real* scanner-held
+ sharing violation only occur on Windows.
+- **libgit2 path-resolution fallback** — `crates/ai-memory-wiki/src/git.rs` carries a
+ whole `#[cfg(windows)]` fallback family (`commit_all_fallback`,
+ `should_try_commit_cli_fallback`, `commit_count_fallback`,
+ `recent_checkpoints_fallback`, `file_at_rev_fallback`) that shells out to the `git` CLI
+ when "libgit2 can fail to reopen a freshly initialised wiki repo under dot-prefixed temp
+ dirs with an OS path-resolution error" (`ErrorClass::Os` + `"failed to resolve path"`).
+ This branch is dead on Linux — it never compiles there — so its behavior is *only* ever
+ exercised on native Windows.
+- **Verbatim / UNC / drive-letter path handling** — Windows drive-letter and UNC paths are
+ treated case-insensitively in scope matching (CHANGELOG: `C:\Users\…\repo` vs a
+ lower-cased form), plus verbatim-path (`\\?\`) concerns in git/atomic writes and the
+ `%USERPROFILE%`-then-`dirs::home_dir` HOME fallback (`Config::load`). Path *casing* and
+ verbatim semantics are OS behaviors, not code we can prove correct on Linux.
+- **PowerShell hook transport** — `crates/ai-memory-hooks/tests/suite/powershell_utf8.rs`
+ and `powershell_home.rs` are `#![cfg(windows)]` and drive the real
+ `hooks/lib/ai-memory-hook.ps1` under a native PowerShell interpreter (UTF-8 body framing,
+ marker-boundary handling). This is the cold-start flake's home.
+- **PowerShell wrapper `bin/ai-memory.ps1`** — the Docker-Desktop wrapper; has had
+ PowerShell 5.1-specific crashes (redirected native stderr becoming a terminating error,
+ fixed with a localized probe). PS 5.1 behavior is Windows-only.
+- **Detached hook-drain process launch** — `hook_drain_process.rs` detaches the background
+ drainer differently on Windows vs the Unix `setsid` path.
+- **Assorted `#[cfg(windows)]` in** `install_hooks`, `install_mcp`, `render_shared`, `run`
+ (exec-form quoting, single-command hook strings), and `packaging::slow` tests.
+
+### Already covered on Linux (do not pay Windows time for these)
+
+- Every **injected-error** unit test (`from_raw_os_error(32|33)`, the sharing-violation
+ retry) compiles and runs on Linux and macOS today.
+- The **POSIX hook bundle** (`tests/hooks/test_lib.sh`) runs across four awks on Linux in
+ `ci.yml`'s `hooks-shell` job. Only the suite's *PowerShell branch* needs a native
+ interpreter.
+- All **path-normalization logic that is lexical** (not OS-dependent) — the code
+ deliberately normalizes lexically rather than via `fs::canonicalize` (a documented
+ Windows/macOS divergence), so that logic is testable on Linux.
+
+The practical size of the real-Windows-only surface: **two Rust concerns** (file-locking /
+NTFS-index / sharing-violation, and the libgit2 path-resolution fallback + verbatim/UNC
+path casing) plus **the PowerShell layer** (hook transport + `bin/ai-memory.ps1` + the
+PowerShell half of the shell suite). Everything else is either injected-and-Linux-covered
+or lexical. That is a small, well-bounded target — which is what makes a local VM loop
+worthwhile rather than over-engineered.
+
+## Options
+
+Setup complexity, one-time and per-run cost, resources, **Windows licensing**, **security
+posture (esp. public-repo / fork-PR exposure)**, maintenance, the coverage each gives
+against the surface above, and how each integrates with `windows.yml`.
+
+### Option A — `dockur/windows` VM on marvin, for **local on-demand** runs
+
+Run a Windows guest as a KVM/QEMU VM inside a Docker container on marvin
+(`dockur/windows`), driven from the Linux host by a `bin/`-style helper: bring the VM up,
+sync the repo in (bind-mounted `/shared` → drive `Z:` in the guest, or RDP/SSH), run
+`cargo test --workspace --all-targets` + the PowerShell hook suite, report, tear down.
+`windows-latest` stays exactly as it is (nightly + label + pre-release), catching drift.
+
+- **Setup complexity:** Medium one-time. `dockur/windows` boots a full Windows via an
+ automated unattended install; access via web viewer (port **8006**), **RDP** (3389), and
+ a **`/shared`** host bind-mount that appears as **`Z:`** inside Windows. One-time
+ provisioning: install the Rust 1.95 toolchain, Git, and (native) PowerShell in the guest,
+ then snapshot the disk image so subsequent boots reuse it.
+- **Resources on marvin:** Needs `/dev/kvm` (marvin has it). dockur defaults to 2 cores /
+ 4 GB / 64 GB; Win11 realistically wants ≥4 GB and several cores for a tolerable `cargo`
+ build. marvin's 32 cores / ~2.6 TB free absorb this trivially, and the VM can be given
+ 8–16 cores to beat a shared GitHub runner on link time.
+- **Cost/time:** One-time first boot is *minutes* (image pull + retail ISO download +
+ unattended install). Per-run after provisioning: a warm VM plus an incremental
+ `cargo test` should land far under the ~1000s `windows-latest` figure, because (a) the
+ cache lives on a local disk (no ~10x slow cache *restore* over the network) and (b) we
+ can throw more cores at linking. Exact numbers must be measured on marvin (see Open
+ questions) — the dockur README publishes no benchmark.
+- **Licensing (address honestly):** dockur downloads **retail** consumer ISOs (Win 10/11
+ Pro) and installs them **unactivated**. That is **not** covered by any evaluation-license
+ grant — it is the same posture as any unactivated retail install, best described as
+ **gray-area / unlicensed**. The cleanly-licensed path is to point dockur at a **Windows
+ Server** or **Windows Enterprise evaluation** ISO (Server eval = full-featured **180
+ days**, re-armable up to 6×; client Enterprise eval = **90 days**) via `VERSION=<ISO URL>`
+ or a bind-mounted `/custom.iso`, and re-provision when the window lapses. **Recommendation
+ for this project: use a Windows Server (or Enterprise) evaluation ISO, not the default
+ retail Win11 download**, so the local loop is licensed for testing. (Sources below.)
+- **Security posture:** **Best of the VM options.** Nothing here is a CI runner reachable
+ by fork PRs. It runs only when the maintainer or the agent invokes it, on a trusted
+ branch, on the maintainer's own box. The public-repo / fork-PR arbitrary-code risk that
+ sinks Option B **does not apply**.
+- **Maintenance:** Re-provision on eval-window expiry and on toolchain bumps; keep a
+ snapshot. Modest.
+- **Coverage vs the surface:** **Full.** Real NTFS file-index + sharing violations, real
+ libgit2 path-resolution fallback, real verbatim/UNC + drive-letter casing, real
+ PowerShell transport and `bin/ai-memory.ps1` under a native interpreter. Everything the
+ enumerated surface needs.
+- **Integration with `windows.yml`:** **Supplement / local-only.** Keep `windows.yml`
+ as-is for drift detection; the VM becomes the *fast* pre-merge and mandatory pre-release
+ path (dispatch `windows.yml` on the RC SHA still happens — belt and suspenders).
+
+### Option B — Self-hosted GitHub Actions Windows runner on marvin (dockur or dedicated VM)
+
+Register a self-hosted `windows` runner (inside a dockur VM or a dedicated Windows VM on
+marvin) and point `windows.yml`'s `runs-on` at it.
+
+- **The disqualifying caveat:** ai-memory is a **public** repo. GitHub's own guidance is
+ explicit: *"We recommend that you only use self-hosted runners with private repositories.
+ This is because forks of your public repository can potentially run dangerous code on
+ your self-hosted runner machine by creating a pull request that executes the code in a
+ workflow."* The secure-use reference goes further: self-hosted runners "should almost
+ never be used for public repositories." A fork PR is exactly the case we *want* Windows
+ feedback on, and it is exactly the attack vector.
+- **Mitigations exist but are load-bearing and easy to get wrong:** never run fork
+ `pull_request` on the self-hosted runner (reserve it for `push`/`schedule`/
+ `workflow_dispatch` on trusted refs); require approval for outside contributors; use
+ **ephemeral / just-in-time runners** (at most one job, then destroyed) so one PR cannot
+ poison the next; isolate via runner groups; keep no secrets on the host; treat the VM as
+ disposable. Even with all of that, a single misconfiguration (or a future
+ `pull_request_target`/`workflow_run` mistake) exposes marvin to arbitrary code from the
+ internet.
+- **Setup/maintenance:** Highest — runner registration + auto-reset ephemeral tooling +
+ keeping the isolation invariants true forever, on top of the same VM provisioning as
+ Option A. Licensing: same retail-vs-eval issue as Option A.
+- **Coverage:** Same *full* Windows coverage as Option A (it's the same VM), but reached
+ through a CI runner instead of a local invocation — which only *adds* the fork-PR risk
+ without adding coverage over Option A.
+- **Verdict:** **Not acceptable for this public repo.** The one thing it buys over Option A
+ — "Windows results appear automatically on a fork PR" — is precisely the thing GitHub
+ warns against, and Option A already gives the maintainer the fast local loop safely. The
+ fork-PR *feedback* need is better served by keeping GitHub-hosted `windows-latest` (which
+ GitHub licenses and isolates) for that case.
+
+### Option C — Cross-compile from Linux (`gnu` / `msvc` via `cargo-xwin`), plus Wine for a subset
+
+- **`cargo build --target x86_64-pc-windows-gnu`** (MinGW-w64) and
+ **`x86_64-pc-windows-msvc` via `cargo-xwin`** produce Windows binaries from Linux and
+ prove the code **compiles and links** for the target — this catches `#[cfg(windows)]`
+ build breaks, missing imports, and ABI/link errors *cheaply, per merge, on Linux*.
+- **What it does NOT do:** cross-compiling proves nothing about whether tests *pass* on
+ real Windows. Running the cross-built test binaries under **Wine** is possible but
+ **cannot be trusted** for this project's surface. Wine is a compatibility layer, not an
+ emulator, and specifically:
+ - **PowerShell** does not run reliably on Wine (64-bit PowerShell stack-overflows;
+ community wrappers shim to PowerShell *Core*, not real Windows PowerShell) — so the
+ entire PowerShell hook/transport surface is untestable under Wine.
+ - **NTFS case-folding** — Wine uses the host FS (case-sensitive on Linux); it does not
+ reproduce NTFS case-insensitive-but-preserving semantics. Our drive-letter/UNC casing
+ tests would be invalid.
+ - **Win32 file-locking / sharing-violation** semantics (`ERROR_LOCK_VIOLATION`,
+ `ERROR_SHARING_VIOLATION`) are incomplete/best-effort in Wine — our drain-lock and
+ atomic-write retry behavior cannot be validated.
+ - **libgit2 verbatim/`\\?\` path handling** is a Win32 kernel path-parsing feature Wine
+ does not faithfully reproduce.
+- **Verdict:** Genuinely useful as a **cheap per-merge build gate** (add a Linux job that
+ cross-builds the Windows target so a `#[cfg(windows)]` compile break is caught in ~8-min
+ CI instead of at release). **Wine is not a runtime replacement** for any part of the
+ enumerated surface — it is at best a thin, unreliable extra that must never gate
+ correctness. Treat cross-compile as a supplement to Option A, and treat Wine as
+ out-of-scope.
+
+### Option D — Keep `windows-latest`, just harden (the do-less baseline)
+
+Status quo plus more flake-hardening: keep the label gate + nightly + pre-release
+dispatch, keep widening the timing tolerances (the 60s connect deadline, relaxed eval-gate
+timeouts) as flakes surface.
+
+- **Cost/complexity/security/licensing:** Zero new infrastructure; GitHub licenses and
+ isolates Windows for us; no `/dev/kvm`, no VM, no fork-PR exposure.
+- **Coverage:** Full real-Windows coverage (it *is* real Windows) — this is the correctness
+ floor every other option is measured against.
+- **What it does not fix:** the ~1000s round trip, the ~10x-slow cache restore, the
+ label-gating + fork-approval friction, and the reactive per-flake patching. The
+ iteration loop stays slow, and Windows-sensitive work stays painful to develop.
+- **Verdict:** the honest baseline. It must **stay** (for drift + licensed fork-PR
+ coverage), but on its own it does not deliver the "fast local loop" the problem asks for.
+
+### Options summary
+
+| Option | Setup | Per-run vs ~1000s | Resources | Licensing | Security (public repo / fork PR) | Coverage vs surface | Role vs `windows.yml` |
+|---|---|---|---|---|---|---|---|
+| A — dockur VM, local on-demand | Medium (1× provision + snapshot) | Much faster (local cache, more cores) — measure | `/dev/kvm`, ~8–16 cores / ≥8 GB on marvin | Gray-area if retail; **licensed if Server/Enterprise eval ISO** | **Low** — not a runner; runs only when invoked on trusted branch | **Full** | **Supplement / local-only** |
+| B — self-hosted runner | Highest (runner + ephemeral + isolation) | Fast | Same as A | Same as A | **Unacceptable** — GitHub warns against on public repos; fork PRs = arbitrary code | Full (same VM) | Would replace `runs-on` — **do not** |
+| C — cross-compile (+Wine) | Low (add Linux job) | N/A (build only) | Linux CI | Fine (no Windows guest) | Fine | **Build-only**; Wine runtime **untrustworthy** for this surface | **Supplement** (per-merge build gate) |
+| D — harden `windows-latest` | None | ~1000s (unchanged) | GitHub-hosted | GitHub-licensed | Fine | Full | **Keep** (baseline / drift / fork-PR) |
+
+## Recommendation
+
+**Adopt Option A + Option C's build gate; keep Option D; reject Option B.**
+
+1. **Primary fast loop — `dockur/windows` on marvin, local on-demand (Option A).** A
+ `bin/`-style helper brings up a provisioned Windows VM, syncs the working tree in
+ (bind-mount → `Z:`), runs `cargo test --workspace --all-targets` + the PowerShell hook
+ suite, and reports. This is the fast pre-merge and mandatory pre-release verification
+ path, run by the maintainer/agent on a trusted box. **Provision it from a Windows Server
+ (or Enterprise) evaluation ISO**, not the default retail Win11 download, to keep the loop
+ cleanly licensed for testing.
+2. **Cheap per-merge build gate — cross-compile (Option C).** Add a Linux CI job that
+ cross-builds the Windows target (`x86_64-pc-windows-gnu`, and/or `-msvc` via
+ `cargo-xwin`) so a `#[cfg(windows)]` *compile* break is caught in the ~8-minute Linux
+ gate instead of at release time. This does **not** replace runtime Windows testing and
+ Wine is explicitly **not** used to fake it.
+3. **Keep `windows-latest` label-gated + nightly + pre-release (Option D).** It remains the
+ drift catcher (toolchain/dependency changes no code touches), the licensed-and-isolated
+ path for **fork-PR** Windows feedback, and the mandatory green-before-tag gate on the RC
+ SHA (per AGENTS.md). The local loop is *belt*; `windows.yml` stays as *suspenders*.
+4. **Do NOT put a self-hosted runner on the public repo (reject Option B).** GitHub
+ explicitly warns against it; fork PRs could run arbitrary code on marvin. The only thing
+ it adds over Option A is automatic Windows results on fork PRs — a need already met,
+ safely, by keeping `windows-latest`.
+
+Why this shape: the real-Windows-only surface is small and bounded (file-locking / NTFS /
+sharing-violation, libgit2 path fallback + verbatim/UNC casing, and the PowerShell layer),
+so a **local** VM that the maintainer already has the hardware for gives full, faithful
+coverage at iteration speeds `windows-latest` can't match — *without* importing the
+fork-PR attack surface or making a Windows license the thing standing between a
+contributor and a merge.
+
+## Phased adoption plan
+
+Each phase is independently shippable and reversible; nothing removes `windows.yml`.
+
+- **Phase 0 — Cheap win, no VM.** Add a Linux CI job that cross-compiles the Windows target
+ to gate `#[cfg(windows)]` compile breaks per merge (Option C build-only). Document that
+ Wine is *not* used for correctness. Low risk, immediate value.
+- **Phase 1 — Provision the VM manually.** Stand up `dockur/windows` on marvin from a
+ **Server/Enterprise evaluation ISO**; install Rust 1.95 + Git + native PowerShell;
+ snapshot. **Measure** warm `cargo test --workspace --all-targets` + PowerShell suite time
+ and compare to the ~1000s `windows-latest` figure. This measurement decides whether
+ Phase 2 is worth automating (it almost certainly is, given local cache + more cores).
+- **Phase 2 — The `bin/` helper.** Script "up → sync tree (`/shared`→`Z:`) → `cargo test` +
+ hook suite → report → down" as a `bin/`-style command, mirroring existing helpers
+ (`bin/ai-memory`, `bin/deploy`, `bin/release`). Keep it read/report only; never let it
+ mutate the host tree. Document it in `docs/windows.md` and reference it from AGENTS.md's
+ pre-release Windows step as the *fast* pre-check that precedes the mandatory
+ `windows.yml` dispatch on the RC SHA.
+- **Phase 3 — Optional convenience.** A one-command "run the Windows surface before I push
+ a platform-sensitive change" wrapper, and (if desired) a scheduled *local* run on marvin
+ that emails/logs drift — still **not** a GitHub runner, still trigger-only, no fork
+ exposure.
+
+At every phase, `windows.yml` stays: nightly, `windows` label, `workflow_dispatch`, and
+green-before-tag on the RC SHA.
+
+## Open questions and risks
+
+- **Measured per-run time on marvin (blocking for the value case).** The dockur README
+ publishes no install-time or per-run benchmark. Phase 1's measurement is what proves the
+ loop is actually faster than ~1000s. Risk: if a cold VM boot dominates, keep a warm/
+ snapshotted VM so only the incremental `cargo test` is on the critical path.
+- **Eval-window churn.** Server eval = 180 days (re-armable ~6×), Enterprise client eval =
+ 90 days. Re-provisioning is a recurring chore; a documented snapshot + rebuild runbook
+ keeps it cheap. Risk if forgotten: the guest starts hourly-shutting-down mid-run.
+- **Retail-ISO temptation.** dockur's *default* is a retail Win11 download (unactivated =
+ gray-area). The plan must explicitly pin an eval ISO; a future contributor copying a
+ dockur quickstart could silently reintroduce the retail default. Call this out in
+ `docs/windows.md`.
+- **PowerShell parity.** The guest must run the *Windows PowerShell 5.1* (and/or the pinned
+ PowerShell the hook lib targets) that `bin/ai-memory.ps1` and the hook suite exercise —
+ the 5.1-specific redirected-stderr crash we already fixed shows version matters. Ensure
+ the eval edition ships the right PowerShell, or install it during provisioning.
+- **Nested-virt / GPU / `/dev/kvm` availability.** Confirmed available on marvin per the
+ brief, but the helper should fail loudly with a clear message if `/dev/kvm` is absent
+ (e.g., run from a container without the device passed through).
+- **Drift the local loop can't see.** A local snapshot pins toolchain/dependency versions;
+ `windows-latest`'s nightly is what catches *upstream* drift the snapshot would hide. This
+ is the reason `windows.yml` must stay, not be replaced — the two are complementary, not
+ redundant.
+- **Cross-compile ABI gap.** `-gnu` cross-builds catch most compile breaks, but the shipped
+ release is MSVC (`ai-memory.exe`); a `-gnu`-only gate could miss an MSVC-specific break.
+ If Phase 0 uses `-gnu` for simplicity, note the gap and consider `cargo-xwin` (`-msvc`)
+ for fidelity.
+
+## Sources
+
+External sources (fetched as untrusted data; facts only):
+
+- **dockur/windows** — image, access ports (8006 web / 3389 RDP / `/shared`→`Z:`),
+ `VERSION` editions, defaults (2 cores / 4 GB / 64 GB), `/dev/kvm` requirement:
+ https://github.com/dockur/windows
+- **Windows licensing for VMs / testing** — Server evaluation (180 days, re-armable):
+ https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2022 ·
+ https://learn.microsoft.com/en-us/answers/questions/2128668/vm-licensing-under-windows-server-evaluation ;
+ Windows 11 Enterprise dev VMs (90-day eval, cannot activate):
+ https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/ ·
+ https://www.neowin.net/news/microsoft-updates-its-free-windows-11-virtual-machines/
+- **GitHub self-hosted runners on public repos (security warning + mitigations)**:
+ https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/add-runners ·
+ https://docs.github.com/en/actions/reference/security/secure-use
+- **Wine limitations** (compatibility layer, not an emulator; PowerShell/NTFS/file-locking/
+ UNC caveats):
+ https://www.winehq.org/ · https://wiki.winehq.org/FAQ ·
+ https://forum.winehq.org/viewtopic.php?t=37047 ·
+ https://github.com/PietJankbal/powershell-wrapper-for-wine ·
+ https://forum.winehq.org/viewtopic.php?t=21619
+- **Cross-compiling Rust to Windows from Linux** (`gnu`, `cargo-xwin`/`-msvc`; build-only,
+ Wine-runner caveats):
+ https://jake-shadle.github.io/xwin/ · https://blog.logrocket.com/guide-cross-compilation-rust/ ·
+ https://github.com/cross-rs/cross/issues/550
+
+Repo grounding (this repository): `.github/workflows/windows.yml`;
+`crates/ai-memory-cli/src/commands/hook_spool.rs` (`ERROR_LOCK_VIOLATION`);
+`crates/ai-memory-wiki/src/atomic.rs` (NTFS file-index, sharing-violation retry);
+`crates/ai-memory-wiki/src/git.rs` (`#[cfg(windows)]` libgit2 path-resolution fallbacks);
+`crates/ai-memory-hooks/tests/suite/powershell_utf8.rs`, `powershell_home.rs`;
+`hooks/lib/ai-memory-hook.ps1`, `bin/ai-memory.ps1`; `docs/support-matrix.md`,
+`docs/windows.md`; CHANGELOG + commits `94057581` (#842), `032ec2fc`, `2cd18840`/`d5afdcbf`
+(#758), and PR #827.
+
+## Phase 1 results — measured on marvin (2026-09-22)
+
+The study above proposed Phase 1 as "provision the VM manually and **measure**, because
+the dockur README publishes no benchmark and that number decides whether Phase 2 is worth
+automating." That measurement has now been done on marvin (AMD Ryzen AI Max 395, 32
+cores, 62 GB, `/var` on btrfs, SELinux enforcing). It also proved Phase 0 on a real
+runner. Findings, kept honest because they change the recommendation:
+
+### Phase 0 (cross-compile gate): shipped, works
+
+`cargo xwin build --workspace --all-targets --target x86_64-pc-windows-msvc` is green both
+locally (57s warm) and on `ubuntu-latest` (9m1s cold / **3m19s warm** — under the ~8-min
+gate, and parallel to the existing slowest job). It compiles and links the whole workspace
+for Windows — bundled SQLite and vendored libgit2 under clang-cl, `windows-sys`/`winapi-util`,
+and every `#[cfg(windows)]` **test** binary — so a Windows-only compile/link break is caught
+per-merge on Linux. Landed as the `windows cross-build (msvc)` job in `ci.yml`. Gotcha for
+future maintainers: the target's `rust-std` must be added to the **1.95** toolchain that
+`rust-toolchain.toml` pins, not `stable`, or the build fails with "can't find crate for
+`core`"; the job pins `toolchain: "1.95"` for that reason.
+
+### Phase 1 (dockur VM): it runs the real suite green, but it is NOT a full-suite speed win
+
+Windows Server 2025 (Evaluation, licence-clean 180-day) installs and boots to an autologon
+desktop under `dockurr/windows` on marvin, and the **full suite passes green**, including
+the `#[cfg(windows)]` tests executing on native Windows (PowerShell transport, NTFS atomic
+writes, libgit2 path fallback). Measured, GNU toolchain (rustc 1.95 + MinGW gcc 16.1),
+8 vCPU / 8 GB:
+
+| Run | Time | Notes |
+|---|---|---|
+| Cold full (`test --workspace --all-targets`, first compile) | **2408s (~40m)** | 400 crates, all tests ok |
+| Warm full (nothing changed, test execution only) | **1600s (~27m)** | 0 recompiled — this is *test-execution* time |
+| Warm single crate (`test -p ai-memory-hooks`) | **73s** | the realistic focused-iteration cost |
+| GitHub `windows-latest` full run (from the study) | **~1000s** | warm cache |
+
+The decisive, unwelcome result: **the warm full suite (1600s) is slower than
+`windows-latest` (~1000s)**, and it is dominated by *test execution*, not compilation
+(0 crates recompiled). The suite is I/O-bound — SQLite, `git2`/libgit2, and fsync-heavy
+atomic-write tests — and marvin's `/var` is **btrfs**, so the QEMU raw disk image pays
+copy-on-write fragmentation on every fsync. So the "iteration measured in tens of seconds"
+premise does **not** hold for a full-suite run on this box; the local VM's honest value is
+(a) **on-demand focused iteration** (one crate in ~1 min, no ~17-min GitHub round trip and
+no fork-approval friction) and (b) full local Windows coverage before a push. It is not a
+faster full gate.
+
+Untried optimisation that could change this verdict: disable btrfs CoW on the storage dir
+(`chattr +C` before the image is created) and re-measure the I/O-bound execution; that is
+the single most likely lever and should be tried before either committing to Phase 2
+automation or concluding the VM is too slow.
+
+### Host-specific accommodations dockur needs on marvin (none anticipated by the study)
+
+1. **SELinux `:Z`/`:z` on every bind mount** — otherwise `/storage` is not writable.
+2. **`security_opt: [label:disable]`** — SELinux blocks `/dev/net/tun`, so dockur silently
+ falls back to user-mode (passt) networking, which breaks the `\\host.lan\Data` shared
+ folder and custom port-forwarding. With the label disabled it gets real NAT.
+3. **The `/oem` `RunOnce` auto-provision did not fire** — the VM reached an autologon
+ desktop but the first-logon provisioning never ran. Driving it via the **QEMU monitor**
+ (`sendkey` to type a launch command, `screendump` to read the screen — the monitor lives
+ at `/dev/shm/monitor.sock` inside the container) worked reliably and is the mechanism a
+ `bin/` helper should use, not `RunOnce`.
+4. **Microsoft Defender must be disabled/excluded** — real-time scanning *quarantined build
+ artifacts mid-build* and killed cargo (silent early exit). `Set-MpPreference
+ -DisableRealtimeMonitoring $true` + exclusions for `.cargo`/`.rustup`/the build dir fixed
+ it. This is the same Defender-exclusion guidance AGENTS.md already gives for Windows dev,
+ here promoted from "slow" to "correctness-breaking".
+5. **Isolation flakiness**: `test -p ai-memory-wiki` hung/crawled when run alone (file-watcher
+ / libgit2 tests) although the same tests passed inside the `--all-targets` run — a
+ reliability caveat to investigate before relying on per-crate runs for that crate.
+
+### Revised recommendation
+
+- **Phase 0 — ship** (done). Unambiguous win, no Windows infra.
+- **Phase 1/2 — feasible, but re-measure with CoW disabled before automating.** The VM gives
+ faithful full Windows coverage on demand, but is not a faster full gate on btrfs. If Phase 2
+ proceeds, the `bin/` helper must: apply fixes 1–2 in compose, disable Defender (4), drive
+ provisioning + runs via the QEMU monitor (3), and prefer focused per-crate invocations.
+- **Option D (`windows.yml`) stays** the authoritative, licence-clean, fork-safe pre-tag gate
+ regardless — the VM is *belt*, `windows.yml` remains *suspenders*.