@opengsd/gsd-path 1.3.1 → 1.5.0

package/skills/gsd-path-define/scripts/detect_project.py

@@ -12,12 +12,14 @@ Verdicts:
 - owned — `.project/` is a real directory with a regular `STATE.md` and no
   unsafe project paths; route by that file, not detection
 - orphan — `.project/` is unsafe, or it contains an entry without a safe
-  regular `STATE.md`; the initializer's regular temporary state file is
-  recoverable and does not make the project orphaned
-- brownfield — no owned state, `.project/` empty or absent, and at least one
-  in-scope signal (package/build manifest, source file, tracked signal in
-  git, or substantive system documentation)
-- greenfield — no owned state, `.project/` empty or absent, and no signal
+  regular `STATE.md`; the initializer's regular temporary state file and an
+  ignored, untracked regular `.DS_Store` are exceptions
+- brownfield — no owned state, `.project/` empty, absent, or containing only
+  an ignored `.DS_Store`, and at least one in-scope signal (package/build
+  manifest, source file, tracked signal in git, or substantive system
+  documentation)
+- greenfield — no owned state, `.project/` empty, absent, or containing only
+  an ignored `.DS_Store`, and no signal
 
 Ignored path components: `.git`, `node_modules`, vendored/generated trees,
 build output, and managed GSD Path installation artifacts. `.project/` is
@@ -41,6 +43,11 @@ from datetime import date
 from pathlib import Path, PurePosixPath, PureWindowsPath
 from typing import Iterable, NamedTuple, Optional, Sequence
 
+try:
+    from . import _common
+except ImportError:
+    import _common
+
 try:
     import fcntl
 
@@ -48,10 +55,22 @@ try:
         fcntl.flock(fd, fcntl.LOCK_EX)
 
 except ImportError:  # Windows does not provide POSIX file locks.
+    import errno
     import msvcrt
+    import time
 
     def lock_exclusive(fd: int) -> None:
-        msvcrt.locking(fd, msvcrt.LK_LOCK, 1)
+        delay = 0.01
+        while True:
+            try:
+                os.lseek(fd, 0, os.SEEK_SET)
+                msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+                return
+            except OSError as error:
+                if error.errno not in (errno.EACCES, errno.EAGAIN, errno.EDEADLK):
+                    raise
+                time.sleep(delay)
+                delay = min(delay * 2, 0.25)
 
 
 IGNORE_DIRS = {
@@ -210,16 +229,20 @@ HTML_BLOCK_START = re.compile(
     re.IGNORECASE,
 )
 REPARSE_NAME_SURROGATE = 0x20000000
-ANCHORED_EVIDENCE_SUPPORTED = (
+_POSIX_ANCHORED_EVIDENCE_SUPPORTED = (
     hasattr(os, "O_DIRECTORY")
     and hasattr(os, "O_NOFOLLOW")
     and os.open in os.supports_dir_fd
     and os.stat in os.supports_dir_fd
     and os.stat in os.supports_follow_symlinks
 )
+WINDOWS_ANCHORED_EVIDENCE_SUPPORTED = os.name == "nt"
+ANCHORED_EVIDENCE_SUPPORTED = (
+    _POSIX_ANCHORED_EVIDENCE_SUPPORTED or WINDOWS_ANCHORED_EVIDENCE_SUPPORTED
+)
 LISTDIR_DIR_FD_SUPPORTED = os.listdir in getattr(os, "supports_fd", ())
 ANCHORED_STATE_CREATE_SUPPORTED = (
-    ANCHORED_EVIDENCE_SUPPORTED
+    _POSIX_ANCHORED_EVIDENCE_SUPPORTED
     and LISTDIR_DIR_FD_SUPPORTED
     and os.mkdir in getattr(os, "supports_dir_fd", ())
     and os.unlink in getattr(os, "supports_dir_fd", ())
@@ -262,11 +285,12 @@ def is_link_like_status(status: os.stat_result) -> bool:
 def is_link_like(path: Path, status: os.stat_result) -> bool:
     if is_link_like_status(status):
         return True
-    isjunction = getattr(os.path, "isjunction", None)
-    if os.name != "nt" or isjunction is None:
+    if os.name != "nt":
         return False
     try:
-        return bool(isjunction(path))
+        return is_link_like_status(os.lstat(path))
+    except FileNotFoundError:
+        return False
     except OSError as error:
         raise DetectError(f"cannot inspect link-like evidence: {path}: {error}") from error
 
@@ -325,7 +349,7 @@ def is_managed_pipeline_directory(relative: str, root: Path) -> bool:
     return is_verified_skill_bundle(relative, root)
 
 
-def is_verified_skill_bundle_at(relative: str, directory_fd: int) -> bool:
+def is_verified_skill_bundle_at(relative: str, directory_fd: int, root: Path) -> bool:
     parts = PurePosixPath(relative).parts
     if not parts:
         return False
@@ -335,19 +359,45 @@ def is_verified_skill_bundle_at(relative: str, directory_fd: int) -> bool:
         return False
     if is_verified_installer_bundle(parts):
         return True
+    if _POSIX_ANCHORED_EVIDENCE_SUPPORTED:
+        try:
+            status = os.stat(
+                "SKILL.md",
+                dir_fd=directory_fd,
+                follow_symlinks=False,
+            )
+        except FileNotFoundError:
+            return False
+        except OSError as error:
+            raise DetectError(
+                f"cannot inspect managed skill bundle: {relative}: {error}"
+            ) from error
+        return not is_link_like_status(status) and stat.S_ISREG(status.st_mode)
+    skill_fd = None
     try:
-        status = os.stat(
+        win = get_windows_handles()
+        skill_fd = win.open_relative(
+            directory_fd,
             "SKILL.md",
-            dir_fd=directory_fd,
-            follow_symlinks=False,
+            _FILE_READ_ATTRIBUTES,
+            _PIN_SHARE,
+            _FILE_OPEN,
+            0,
         )
+        status = os.fstat(skill_fd)
     except FileNotFoundError:
         return False
     except OSError as error:
+        if getattr(error, "winerror", None) == 2:
+            return False
         raise DetectError(
             f"cannot inspect managed skill bundle: {relative}: {error}"
         ) from error
-    return not is_link_like_status(status) and stat.S_ISREG(status.st_mode)
+    finally:
+        if skill_fd is not None:
+            os.close(skill_fd)
+    skill = root.joinpath(*parts) / "SKILL.md"
+    return not is_link_like(skill, status) and stat.S_ISREG(status.st_mode)
 
 
 def is_fixed_managed_pipeline_artifact(relative: str) -> bool:
@@ -416,13 +466,20 @@ def read_regular_evidence(
         ) from error
     if not relative.parts:
         raise DetectError(f"{evidence_name} evidence path is empty: {path}")
-    if ANCHORED_EVIDENCE_SUPPORTED:
+    if _POSIX_ANCHORED_EVIDENCE_SUPPORTED:
         return read_anchored_evidence(
             relative,
             root,
             missing_ok=missing_ok,
             evidence_name=evidence_name,
         )
+    if WINDOWS_ANCHORED_EVIDENCE_SUPPORTED:
+        return read_windows_anchored_evidence(
+            relative,
+            root,
+            missing_ok=missing_ok,
+            evidence_name=evidence_name,
+        )
     return read_lstat_open_evidence(
         relative,
         root,
@@ -440,6 +497,17 @@ def directory_flags() -> int:
     )
 
 
+def listdir_anchored(dir_fd: int) -> list[str]:
+    """List names through a fresh directory descriptor under dir_fd."""
+    fresh = os.open(".", directory_flags(), dir_fd=dir_fd)
+    try:
+        if not os.path.samestat(os.fstat(fresh), os.fstat(dir_fd)):
+            raise DetectError("anchored directory listing lost its identity")
+        return os.listdir(fresh)
+    finally:
+        os.close(fresh)
+
+
 def file_flags() -> int:
     return (
         os.O_RDONLY
@@ -759,9 +827,12 @@ def raise_walk_error(error: OSError) -> None:
 
 
 def iter_worktree_files(root: Path) -> Iterable[str]:
-    if ANCHORED_EVIDENCE_SUPPORTED and LISTDIR_DIR_FD_SUPPORTED:
+    if _POSIX_ANCHORED_EVIDENCE_SUPPORTED and LISTDIR_DIR_FD_SUPPORTED:
         yield from iter_worktree_files_anchored(root)
         return
+    if WINDOWS_ANCHORED_EVIDENCE_SUPPORTED:
+        yield from iter_worktree_files_windows_anchored(root)
+        return
     for dirpath, dirnames, filenames in os.walk(
         root,
         followlinks=False,
@@ -819,7 +890,7 @@ def iter_from_dir_fd(
     dir_fd: int, relative_dir: str, root: Path
 ) -> Iterable[str]:
     try:
-        names = os.listdir(dir_fd)
+        names = listdir_anchored(dir_fd)
     except OSError as error:
         raise DetectError(f"cannot traverse filesystem evidence: {error}") from error
     for name in names:
@@ -855,7 +926,7 @@ def iter_from_dir_fd(
                     raise DetectError(
                         f"filesystem evidence changed while traversing: {relative}"
                     )
-                if is_verified_skill_bundle_at(relative, child):
+                if is_verified_skill_bundle_at(relative, child, root):
                     continue
                 yield from iter_from_dir_fd(child, relative, root)
             finally:
@@ -961,6 +1032,26 @@ def is_staged_skill_bundle_artifact(
     )
 
 
+def ignored_junk(directory: Path, name: str, status: os.stat_result) -> bool:
+    """Ignored, untracked OS junk. The caller's no-follow status decides the file type."""
+    if (
+        name not in _common.OS_JUNK_NAMES
+        or is_link_like_status(status)
+        or not stat.S_ISREG(status.st_mode)
+    ):
+        return False
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(directory), "check-ignore", "-q", "--", name],
+            capture_output=True,
+            check=False,
+            env=git_environment(),
+        )
+    except OSError:
+        return False
+    return result.returncode == 0
+
+
 def project_path_inventory(
     project: Path, root: Path
 ) -> tuple[tuple[str, ...], tuple[str, ...]]:
@@ -1001,14 +1092,18 @@ def project_path_inventory(
             posix_relative(current / name, root) for name in linked_directories
         )
         dirnames[:] = [name for name in dirnames if name not in linked_directories]
+        kept = []
         for name in filenames:
             path = current / name
-            relative = posix_relative(path, root)
             status = lstat_evidence(path, missing_ok=False)
+            if ignored_junk(current, name, status):
+                continue
+            kept.append(name)
+            relative = posix_relative(path, root)
             paths.append(relative)
             if is_link_like(path, status) or not stat.S_ISREG(status.st_mode):
                 unsafe_paths.append(relative)
-        if not filenames and not dirnames and current != project:
+        if not kept and not dirnames and current != project:
             paths.append(posix_relative(current, root))
     if not paths:
         try:
@@ -1017,7 +1112,11 @@ def project_path_inventory(
             raise DetectError(
                 f"cannot list project evidence: {project}: {error}"
             ) from error
-        paths = [posix_relative(project / name, root) for name in names]
+        paths = [
+            posix_relative(project / name, root)
+            for name in names
+            if not ignored_junk(project, name, lstat_evidence(project / name, missing_ok=False))
+        ]
     return tuple(sorted(paths)), tuple(sorted(unsafe_paths))
 
 
@@ -1093,7 +1192,7 @@ def classify(repo: Path) -> dict:
         missing_ok=True,
     )
     if (
-        ANCHORED_STATE_CREATE_SUPPORTED
+        STATE_CREATE_SUPPORTED
         and orphan_paths == (f".project/{STATE_TEMP_NAME}",)
         and not unsafe_paths
         and temporary_state_status is not None
@@ -1265,12 +1364,28 @@ def close_file_descriptors(
             pass
 
 
+def project_entries(project_fd: int, project: Path) -> set:
+    """Names in .project without ignored OS junk (Finder may add .DS_Store at any time)."""
+    entries = set(listdir_anchored(project_fd))
+    for name in entries & _common.OS_JUNK_NAMES:
+        try:
+            status = os.stat(name, dir_fd=project_fd, follow_symlinks=False)
+        except FileNotFoundError:
+            continue  # Keep the name: the caller's comparison then fails closed.
+        if ignored_junk(project, name, status):
+            entries.discard(name)
+    return entries
+
+
 def write_state_anchored(
     root: Path,
     content: str,
     expected_root: os.stat_result,
     expected_project: Optional[os.stat_result],
 ) -> None:
+    if WINDOWS_STATE_CREATE_SUPPORTED:
+        write_state_windows(root, content, expected_root, expected_project)
+        return
     if not ANCHORED_STATE_CREATE_SUPPORTED:
         raise DetectError("anchored no-follow STATE.md creation is unavailable")
     payload = content.encode("utf-8")
@@ -1333,7 +1448,7 @@ def write_state_anchored(
         ):
             raise DetectError(".project changed after classification")
         lock_exclusive(project_fd)
-        entries = set(os.listdir(project_fd))
+        entries = project_entries(project_fd, root / ".project")
         if entries not in (set(), {STATE_TEMP_NAME}):
             raise DetectError(".project changed after classification")
         create = (
@@ -1362,12 +1477,12 @@ def write_state_anchored(
                 follow_symlinks=False,
             )
         except FileNotFoundError as error:
-            if "STATE.md" in os.listdir(project_fd):
+            if "STATE.md" in listdir_anchored(project_fd):
                 raise DetectError("STATE.md already exists") from error
             raise DetectError("temporary STATE.md disappeared") from error
         if not os.path.samestat(created_status, named_temporary):
             raise DetectError("temporary STATE.md changed before writing")
-        if "STATE.md" in os.listdir(project_fd):
+        if "STATE.md" in listdir_anchored(project_fd):
             raise DetectError("STATE.md already exists")
         os.ftruncate(state_fd, 0)
         write_all(state_fd, payload)
@@ -1400,7 +1515,7 @@ def write_state_anchored(
             or not os.path.samestat(created_status, current_state)
         ):
             raise DetectError("temporary STATE.md changed while writing")
-        if set(os.listdir(project_fd)) != {STATE_TEMP_NAME}:
+        if project_entries(project_fd, root / ".project") != {STATE_TEMP_NAME}:
             raise DetectError(".project contents changed while creating STATE.md")
         try:
             os.link(
@@ -1420,7 +1535,7 @@ def write_state_anchored(
         published = os.stat("STATE.md", dir_fd=project_fd, follow_symlinks=False)
         if published.st_nlink != 1 or not os.path.samestat(created_status, published):
             raise DetectError("STATE.md changed while publishing")
-        if set(os.listdir(project_fd)) != {"STATE.md"}:
+        if project_entries(project_fd, root / ".project") != {"STATE.md"}:
             raise DetectError(".project contents changed while publishing STATE.md")
         os.fsync(project_fd)
         closing_state_fd = state_fd
@@ -1448,6 +1563,446 @@ def write_state_anchored(
         close_file_descriptors(state_fd, project_fd, root_fd)
 
 
+# --- Windows anchored creation ------------------------------------------------
+# Windows has no dir_fd, O_NOFOLLOW, or O_DIRECTORY. Handles give the same
+# guarantee (docs/adr/0004-windows-anchored-state.md):
+# - each directory is opened without following a reparse point and held
+#   without FILE_SHARE_DELETE, so it cannot be renamed or replaced while held;
+# - children are opened relative to the held parent handle (NtCreateFile with
+#   a RootDirectory), so no path is resolved again after it was checked;
+# - STATE.md is published by renaming the temporary file's own handle without
+#   replacing an existing name, and rollback deletes through that handle.
+
+_FILE_LIST_DIRECTORY = 0x0001
+_FILE_TRAVERSE = 0x0020
+_FILE_READ_ATTRIBUTES = 0x0080
+_DELETE = 0x00010000
+_SYNCHRONIZE = 0x00100000
+_GENERIC_WRITE = 0x40000000
+_GENERIC_READ = 0x80000000
+_FILE_SHARE_READ = 0x1
+_FILE_SHARE_WRITE = 0x2
+_OPEN_EXISTING = 3
+_FILE_FLAG_OPEN_REPARSE_POINT = 0x00200000
+_FILE_FLAG_BACKUP_SEMANTICS = 0x02000000
+_FILE_OPEN = 1
+_FILE_CREATE = 2
+_FILE_OPEN_IF = 3
+_FILE_DIRECTORY_FILE = 0x00000001
+_FILE_SYNCHRONOUS_IO_NONALERT = 0x00000020
+_FILE_NON_DIRECTORY_FILE = 0x00000040
+_FILE_OPEN_REPARSE_POINT = 0x00200000
+_OBJ_CASE_INSENSITIVE = 0x00000040
+_FILE_RENAME_INFORMATION = 10
+_FILE_DISPOSITION_INFO = 4
+_DIRECTORY_ACCESS = _FILE_LIST_DIRECTORY | _FILE_TRAVERSE | _FILE_READ_ATTRIBUTES | _SYNCHRONIZE
+# Readers and writers may share a held directory; nobody may delete or rename it.
+_PIN_SHARE = _FILE_SHARE_READ | _FILE_SHARE_WRITE
+
+WINDOWS_STATE_CREATE_SUPPORTED = os.name == "nt"
+STATE_CREATE_SUPPORTED = ANCHORED_STATE_CREATE_SUPPORTED or WINDOWS_STATE_CREATE_SUPPORTED
+
+
+class _WindowsHandles:
+    """kernel32/ntdll calls for the Windows anchored create, bound on first use."""
+
+    def __init__(self) -> None:
+        import ctypes
+        import msvcrt
+        from ctypes import wintypes
+
+        class UnicodeString(ctypes.Structure):
+            _fields_ = [("Length", wintypes.USHORT), ("MaximumLength", wintypes.USHORT),
+                        ("Buffer", wintypes.LPWSTR)]
+
+        class ObjectAttributes(ctypes.Structure):
+            _fields_ = [("Length", wintypes.ULONG), ("RootDirectory", wintypes.HANDLE),
+                        ("ObjectName", ctypes.POINTER(UnicodeString)),
+                        ("Attributes", wintypes.ULONG), ("SecurityDescriptor", ctypes.c_void_p),
+                        ("SecurityQualityOfService", ctypes.c_void_p)]
+
+        class IoStatusBlock(ctypes.Structure):
+            _fields_ = [("Status", ctypes.c_void_p), ("Information", ctypes.c_size_t)]
+
+        self.ctypes, self.wintypes, self.msvcrt = ctypes, wintypes, msvcrt
+        self.UnicodeString, self.ObjectAttributes, self.IoStatusBlock = (
+            UnicodeString, ObjectAttributes, IoStatusBlock)
+        self.kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+        self.ntdll = ctypes.WinDLL("ntdll")
+        self.kernel32.CreateFileW.restype = wintypes.HANDLE
+        self.kernel32.CreateFileW.argtypes = (
+            wintypes.LPCWSTR, wintypes.DWORD, wintypes.DWORD, ctypes.c_void_p,
+            wintypes.DWORD, wintypes.DWORD, wintypes.HANDLE)
+        self.kernel32.SetFileInformationByHandle.argtypes = (
+            wintypes.HANDLE, ctypes.c_int, ctypes.c_void_p, wintypes.DWORD)
+        self.ntdll.NtCreateFile.restype = ctypes.c_long
+        self.ntdll.NtCreateFile.argtypes = (
+            ctypes.POINTER(wintypes.HANDLE), wintypes.DWORD, ctypes.POINTER(ObjectAttributes),
+            ctypes.POINTER(IoStatusBlock), ctypes.c_void_p, wintypes.ULONG, wintypes.ULONG,
+            wintypes.ULONG, wintypes.ULONG, ctypes.c_void_p, wintypes.ULONG)
+        self.ntdll.RtlNtStatusToDosError.restype = wintypes.ULONG
+        self.ntdll.RtlNtStatusToDosError.argtypes = (ctypes.c_long,)
+        self.ntdll.NtSetInformationFile.restype = ctypes.c_long
+        self.ntdll.NtSetInformationFile.argtypes = (
+            wintypes.HANDLE, ctypes.POINTER(IoStatusBlock), ctypes.c_void_p, wintypes.ULONG,
+            ctypes.c_int)
+
+    def adopt(self, handle: int) -> int:
+        """A CRT descriptor that owns handle, so os.fstat, os.write, and os.close apply."""
+        try:
+            descriptor = self.msvcrt.open_osfhandle(handle, 0)
+        except OSError:
+            self.kernel32.CloseHandle(self.wintypes.HANDLE(handle))
+            raise
+        # The CRT adopts handles in text mode, where os.write turns "\n" into "\r\n".
+        self.msvcrt.setmode(descriptor, os.O_BINARY)
+        return descriptor
+
+    def open_root(self, path: Path) -> int:
+        handle = self.kernel32.CreateFileW(
+            str(path), _DIRECTORY_ACCESS, _PIN_SHARE, None, _OPEN_EXISTING,
+            _FILE_FLAG_BACKUP_SEMANTICS | _FILE_FLAG_OPEN_REPARSE_POINT, None)
+        if handle is None or handle == self.wintypes.HANDLE(-1).value:
+            raise self.ctypes.WinError(self.ctypes.get_last_error())
+        return self.adopt(handle)
+
+    def open_relative(
+        self, parent_fd: int, name: str, access: int, share: int, disposition: int, options: int
+    ) -> int:
+        """Open name inside the directory held by parent_fd, never following a reparse point."""
+        ctypes = self.ctypes
+        buffer = ctypes.create_unicode_buffer(name)
+        length = len(name) * ctypes.sizeof(ctypes.c_wchar)
+        object_name = self.UnicodeString(length, length + ctypes.sizeof(ctypes.c_wchar),
+                                         ctypes.cast(buffer, self.wintypes.LPWSTR))
+        attributes = self.ObjectAttributes(
+            ctypes.sizeof(self.ObjectAttributes), self.msvcrt.get_osfhandle(parent_fd),
+            ctypes.pointer(object_name), _OBJ_CASE_INSENSITIVE, None, None)
+        handle = self.wintypes.HANDLE()
+        status = self.ntdll.NtCreateFile(
+            ctypes.byref(handle), access | _SYNCHRONIZE, ctypes.byref(attributes),
+            ctypes.byref(self.IoStatusBlock()), None, 0, share, disposition,
+            options | _FILE_SYNCHRONOUS_IO_NONALERT | _FILE_OPEN_REPARSE_POINT, None, 0)
+        if status < 0:
+            raise ctypes.WinError(self.ntdll.RtlNtStatusToDosError(status))
+        return self.adopt(handle.value)
+
+    def rename_no_replace(self, fd: int, directory_fd: int, name: str) -> None:
+        """Rename the file held by fd to name inside the directory held by directory_fd.
+
+        The renameat equivalent; fails when name already exists.
+        """
+        ctypes, wintypes = self.ctypes, self.wintypes
+
+        class RenameInformation(ctypes.Structure):
+            _fields_ = [("ReplaceIfExists", wintypes.BOOLEAN), ("RootDirectory", wintypes.HANDLE),
+                        ("FileNameLength", wintypes.ULONG),
+                        ("FileName", wintypes.WCHAR * (len(name) + 1))]
+
+        info = RenameInformation(False, self.msvcrt.get_osfhandle(directory_fd),
+                                 len(name) * ctypes.sizeof(ctypes.c_wchar), name)
+        status = self.ntdll.NtSetInformationFile(
+            self.msvcrt.get_osfhandle(fd), ctypes.byref(self.IoStatusBlock()),
+            ctypes.byref(info), ctypes.sizeof(info), _FILE_RENAME_INFORMATION)
+        if status < 0:
+            raise ctypes.WinError(self.ntdll.RtlNtStatusToDosError(status))
+
+    def delete_on_close(self, fd: int) -> None:
+        """Delete exactly the file held by fd when it closes, whatever its name is now."""
+        ctypes = self.ctypes
+        flag = ctypes.c_ubyte(1)
+        if not self.kernel32.SetFileInformationByHandle(
+                self.msvcrt.get_osfhandle(fd), _FILE_DISPOSITION_INFO,
+                ctypes.byref(flag), ctypes.sizeof(flag)):
+            raise ctypes.WinError(ctypes.get_last_error())
+
+
+_WINDOWS_HANDLES: Optional[_WindowsHandles] = None
+
+
+def get_windows_handles() -> _WindowsHandles:
+    global _WINDOWS_HANDLES
+    if _WINDOWS_HANDLES is None:
+        _WINDOWS_HANDLES = _WindowsHandles()
+    return _WINDOWS_HANDLES
+
+
+def _windows_missing_ok(error: OSError) -> bool:
+    return getattr(error, "winerror", None) in {2, 3}
+
+
+def read_windows_anchored_evidence(
+    relative: Path,
+    root: Path,
+    *,
+    missing_ok: bool,
+    evidence_name: str,
+) -> Optional[str]:
+    win = get_windows_handles()
+    descriptors: list[int] = []
+    try:
+        descriptors.append(win.open_root(root))
+        opened_root = os.fstat(descriptors[-1])
+        if not stat.S_ISDIR(opened_root.st_mode):
+            raise DetectError(f"repo evidence is not a directory: {root}")
+        for index, part in enumerate(relative.parts):
+            current = root.joinpath(*relative.parts[: index + 1])
+            final = index == len(relative.parts) - 1
+            access = _GENERIC_READ if final else _DIRECTORY_ACCESS
+            options = _FILE_NON_DIRECTORY_FILE if final else _FILE_DIRECTORY_FILE
+            try:
+                descriptor = win.open_relative(
+                    descriptors[-1],
+                    part,
+                    access,
+                    _PIN_SHARE,
+                    _FILE_OPEN,
+                    options,
+                )
+            except OSError as error:
+                if missing_ok and _windows_missing_ok(error):
+                    return None
+                raise DetectError(
+                    f"filesystem evidence disappeared: {root / relative}"
+                ) from error
+            descriptors.append(descriptor)
+            actual = os.fstat(descriptor)
+            if is_link_like(current, actual):
+                raise DetectError(
+                    f"link-like {evidence_name} evidence is not allowed: {current}"
+                )
+            if final and not stat.S_ISREG(actual.st_mode):
+                raise DetectError(
+                    f"{evidence_name} evidence is not a regular file: {current}"
+                )
+            if not final and not stat.S_ISDIR(actual.st_mode):
+                raise DetectError(
+                    f"{evidence_name} evidence parent is not a directory: {current}"
+                )
+        with os.fdopen(descriptors.pop(), "rb") as stream:
+            data = stream.read()
+    except DetectError:
+        raise
+    except OSError as error:
+        raise DetectError(
+            f"cannot read {evidence_name} evidence: {root / relative}"
+        ) from error
+    finally:
+        for descriptor in reversed(descriptors):
+            os.close(descriptor)
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError as error:
+        raise DetectError(
+            f"cannot read {evidence_name} evidence: {root / relative}"
+        ) from error
+
+
+def iter_worktree_files_windows_anchored(root: Path) -> Iterable[str]:
+    win = get_windows_handles()
+    try:
+        root_fd = win.open_root(root)
+    except OSError as error:
+        raise DetectError(f"cannot traverse filesystem evidence: {error}") from error
+    try:
+        root_status = os.fstat(root_fd)
+        if not stat.S_ISDIR(root_status.st_mode):
+            raise DetectError(f"repo evidence is not a directory: {root}")
+        yield from iter_from_windows_dir_fd(root_fd, "", root, win)
+    finally:
+        os.close(root_fd)
+
+
+def iter_from_windows_dir_fd(
+    dir_fd: int, relative_dir: str, root: Path, win: _WindowsHandles
+) -> Iterable[str]:
+    scan_dir = root if not relative_dir else root.joinpath(*PurePosixPath(relative_dir).parts)
+    try:
+        # Windows CPython cannot listdir(dir_fd); paths come from the pinned walk.
+        names = os.listdir(scan_dir)
+    except OSError as error:
+        raise DetectError(f"cannot traverse filesystem evidence: {error}") from error
+    for name in names:
+        relative = f"{relative_dir}/{name}" if relative_dir else name
+        if is_ignored(relative) or name == ".project":
+            continue
+        path = root.joinpath(*PurePosixPath(relative).parts)
+        try:
+            child_fd = win.open_relative(
+                dir_fd,
+                name,
+                _DIRECTORY_ACCESS,
+                _PIN_SHARE,
+                _FILE_OPEN,
+                _FILE_DIRECTORY_FILE,
+            )
+        except OSError:
+            child_fd = None
+        else:
+            status = os.fstat(child_fd)
+            if is_link_like(path, status):
+                os.close(child_fd)
+                continue
+            if stat.S_ISDIR(status.st_mode):
+                try:
+                    if is_verified_skill_bundle_at(relative, child_fd, root):
+                        continue
+                    yield from iter_from_windows_dir_fd(
+                        child_fd, relative, root, win
+                    )
+                finally:
+                    os.close(child_fd)
+                continue
+            os.close(child_fd)
+        try:
+            file_fd = win.open_relative(
+                dir_fd,
+                name,
+                _FILE_READ_ATTRIBUTES,
+                _PIN_SHARE,
+                _FILE_OPEN,
+                _FILE_NON_DIRECTORY_FILE,
+            )
+        except OSError as error:
+            raise DetectError(
+                f"cannot inspect filesystem evidence: {relative}: {error}"
+            ) from error
+        try:
+            status = os.fstat(file_fd)
+            if is_link_like(path, status) or not stat.S_ISREG(status.st_mode):
+                continue
+            if is_fixed_managed_pipeline_artifact(relative):
+                continue
+            yield relative
+        finally:
+            os.close(file_fd)
+
+
+def windows_project_entries(project: Path) -> set:
+    """project_entries for a .project held open without delete sharing."""
+    entries = set(os.listdir(project))
+    for name in entries & _common.OS_JUNK_NAMES:
+        try:
+            status = os.stat(project / name, follow_symlinks=False)
+        except FileNotFoundError:
+            continue
+        if ignored_junk(project, name, status):
+            entries.discard(name)
+    return entries
+
+
+def write_state_windows(
+    root: Path,
+    content: str,
+    expected_root: os.stat_result,
+    expected_project: Optional[os.stat_result],
+) -> None:
+    win = _WindowsHandles()
+    payload = content.encode("utf-8")
+    project = root / ".project"
+    root_fd = project_fd = state_fd = None
+    delete_on_failure = False
+    # The same lock pipeline_state takes for this track.
+    with _common.directory_mutex(project):
+        try:
+            try:
+                root_fd = win.open_root(root)
+            except OSError as error:
+                raise DetectError(f"cannot open repo for STATE.md creation: {error}") from error
+            opened_root = os.fstat(root_fd)
+            if (
+                is_link_like(root, opened_root)
+                or not stat.S_ISDIR(opened_root.st_mode)
+                or not os.path.samestat(expected_root, opened_root)
+            ):
+                raise DetectError("repo changed after classification")
+            try:
+                project_fd = win.open_relative(
+                    root_fd, ".project", _DIRECTORY_ACCESS, _PIN_SHARE,
+                    _FILE_CREATE if expected_project is None else _FILE_OPEN,
+                    _FILE_DIRECTORY_FILE)
+            except FileExistsError as error:
+                raise DetectError(".project changed after classification") from error
+            except OSError as error:
+                raise DetectError(f"cannot open .project for STATE.md creation: {error}") from error
+            opened_project = os.fstat(project_fd)
+            if is_link_like(project, opened_project) or not stat.S_ISDIR(opened_project.st_mode):
+                raise DetectError("cannot create state through a non-directory .project")
+            if expected_project is not None and not os.path.samestat(expected_project, opened_project):
+                raise DetectError(".project changed after classification")
+            if windows_project_entries(project) not in (set(), {STATE_TEMP_NAME}):
+                raise DetectError(".project changed after classification")
+            try:
+                # Share mode 0: nothing else may open the temporary file while it is held.
+                state_fd = win.open_relative(
+                    project_fd, STATE_TEMP_NAME, _GENERIC_READ | _GENERIC_WRITE | _DELETE,
+                    0, _FILE_OPEN_IF, _FILE_NON_DIRECTORY_FILE)
+            except OSError as error:
+                raise DetectError(f"cannot reserve temporary STATE.md: {error}") from error
+            created_status = os.fstat(state_fd)
+            if is_link_like(project / STATE_TEMP_NAME, created_status) or not stat.S_ISREG(
+                created_status.st_mode
+            ):
+                raise DetectError("temporary STATE.md is not a regular file")
+            if created_status.st_nlink != 1:
+                raise DetectError("temporary STATE.md has an unexpected link count")
+            delete_on_failure = True
+            if "STATE.md" in os.listdir(project):
+                raise DetectError("STATE.md already exists")
+            os.ftruncate(state_fd, 0)
+            write_all(state_fd, payload)
+            os.fsync(state_fd)
+            current_root = lstat_evidence(root, missing_ok=False)
+            current_project = lstat_evidence(project, missing_ok=False)
+            if (
+                is_link_like(root, current_root)
+                or not os.path.samestat(opened_root, current_root)
+                or is_link_like(project, current_project)
+                or not os.path.samestat(opened_project, current_project)
+            ):
+                raise DetectError("project identity changed while creating STATE.md")
+            current_state = os.fstat(state_fd)
+            if current_state.st_nlink != 1 or not os.path.samestat(created_status, current_state):
+                raise DetectError("temporary STATE.md changed while writing")
+            if windows_project_entries(project) != {STATE_TEMP_NAME}:
+                raise DetectError(".project contents changed while creating STATE.md")
+            try:
+                win.rename_no_replace(state_fd, project_fd, "STATE.md")
+            except OSError as error:
+                if "STATE.md" in os.listdir(project):
+                    raise DetectError("STATE.md already exists") from error
+                raise DetectError(f"cannot publish STATE.md: {error}") from error
+            published = lstat_evidence(project / "STATE.md", missing_ok=False)
+            if (
+                is_link_like(project / "STATE.md", published)
+                or published.st_nlink != 1
+                or not os.path.samestat(created_status, published)
+            ):
+                raise DetectError("STATE.md changed while publishing")
+            if windows_project_entries(project) != {"STATE.md"}:
+                raise DetectError(".project contents changed while publishing STATE.md")
+            delete_on_failure = False
+            closing_state_fd, state_fd = state_fd, None
+            try:
+                os.close(closing_state_fd)
+            except OSError as error:
+                raise DetectError(f"cannot close STATE.md: {error}") from error
+        except BaseException as error:
+            if delete_on_failure and state_fd is not None:
+                try:
+                    win.delete_on_close(state_fd)
+                except OSError as rollback_error:
+                    raise DetectError(
+                        f"cannot roll back STATE.md: {rollback_error}") from error
+            if isinstance(error, DetectError):
+                raise
+            if isinstance(error, OSError):
+                raise DetectError(f"cannot create STATE.md: {error}") from error
+            raise
+        finally:
+            close_file_descriptors(state_fd, project_fd, root_fd)
+
+
 def initialize(
     repo: Path, template: Path, phase: Optional[str] = None, *, require_git: bool = False
 ) -> dict:
@@ -1471,7 +2026,7 @@ def initialize(
     if require_git:
         git = subprocess.run(
             ["git", "-C", str(root), "rev-parse", "--is-inside-work-tree"],
-            env=git_environment(), capture_output=True, text=True, check=False,
+            env=git_environment(), capture_output=True, encoding="utf-8", errors="replace", check=False,
         )
         if git.returncode != 0 or git.stdout.strip() != "true":
             return {**payload, "route": "setup-repository", "wrote_state": False}
@@ -1482,7 +2037,7 @@ def initialize(
         raise DetectError(
             f"initialize phase {phase} does not match verdict {payload['verdict']}"
         )
-    if not ANCHORED_STATE_CREATE_SUPPORTED:
+    if not STATE_CREATE_SUPPORTED:
         payload["wrote_state"] = False
         payload["error"] = "anchored no-follow STATE.md creation is unavailable"
         return payload