fix: native Windows crash (os.O_DIRECTORY) — working dry-runs, fail-closed writes, Windows CI (#150)

fix: native Windows crash (os.O_DIRECTORY) — working dry-runs, fail-closed writes, Windows CI

Author: AgriciDaniel

.gitattributes

@@ -0,0 +1,4 @@
+# Never translate line endings at checkout: frontmatter parsing requires exact
+# "---\n" and content hashes (templates, release manifests, approval plans)
+# must be byte-identical on every platform, including Windows checkouts.
+* -text

.github/workflows/test.yml

@@ -49,6 +49,62 @@ jobs:
           git diff --exit-code
           test -z "$(git status --porcelain=v1 --untracked-files=all)"
 
+  windows-smoke:
+    # The full suite exercises dirfd confinement, symlinks, fcntl, and bash —
+    # deliberately unsupported on native Windows.  This job runs the portable
+    # surface (schema/package/contract validation plus the Windows
+    # compatibility suite) as an explicit allowlist so a skip can never be
+    # mistaken for a pass.
+    name: windows-latest / Python 3.12 (portable surface)
+    runs-on: windows-latest
+    timeout-minutes: 10
+    env:
+      PYTHONDONTWRITEBYTECODE: '1'
+    defaults:
+      run:
+        shell: bash
+
+    steps:
+      - name: Disable line-ending translation before checkout
+        # The runner image ships autocrlf=true globally; frontmatter parsing
+        # and content hashing require byte-exact LF checkouts.  Must run
+        # before actions/checkout writes any file.
+        run: git config --global core.autocrlf false
+
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: '3.12'
+
+      - name: Show runtime versions
+        run: python --version
+
+      - name: Run portable-surface tests
+        run: |
+          set -eu
+          for test_file in \
+            tests/test_package_validation.py \
+            tests/test_knowledge_contracts.py \
+            tests/test_contracts.py \
+            tests/test_benchmark_tools.py \
+            tests/test_windows_compat.py; do
+            echo "=== $test_file ==="
+            python "$test_file"
+          done
+
+      - name: Run portable validators
+        run: |
+          python scripts/claude-obsidian.py package validate
+          python scripts/claude-obsidian.py contracts --check-only
+
+      - name: Prove tests did not mutate or create product files
+        run: |
+          git diff --exit-code
+          test -z "$(git status --porcelain=v1 --untracked-files=all)"
+
   release-safety:
     name: Reproducible release artifact
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -7,8 +7,50 @@ implementation record for older releases.
 
 ## [Unreleased]
 
+### Fixed
+
+- Native Windows no longer crashes with `AttributeError: os.O_DIRECTORY` on
+  every vault command. Read-only inspection and dry-runs (`transaction
+  inspect`, `migrate`/`init`/`adopt`/`capture` previews) now work natively
+  with real equivalent safety checks: path-based casefold-alias auditing,
+  lstat-based vault identity, and symlink/junction rejection.
+- File reads in the transaction core now force binary mode (`O_BINARY`), so
+  CRLF content is hashed byte-exactly on Windows instead of producing false
+  `CONTENT_HASH_MISMATCH`/`EXPECTED_HASH_MISMATCH` failures.
+- CLI output is always UTF-8, fixing `UnicodeEncodeError` crashes when
+  redirecting output containing non-ASCII titles on Windows (cp1252 consoles).
+- Retrieval no longer returns zero results for vaults with CRLF line endings:
+  the chunker, index, and retriever now hash page bodies byte-identically
+  (previously `read_text` newline normalization made every chunk look stale).
+- Under a held mutation lock, a vault whose on-disk name differs only by case
+  from the spelling used on the command line is no longer misreported as its
+  own portable alias on case-insensitive filesystems (APFS; the lock layer
+  never runs on native Windows); the descriptor-pinned vault object is
+  recognized as itself. Inspect-time auditing keeps the stricter shipped
+  behavior, since an absent init root on a case-insensitive volume cannot
+  distinguish itself from an alien sibling.
+
 ### Changed
 
+- Vault mutation on hosts without directory-descriptor confinement (native
+  Windows) is refused before any side effect with a new
+  `UNSUPPORTED_PLATFORM` validation error (exit 2, previously a generic
+  `LOCK_FAILED` exit 1 or a traceback), and `init --apply` no longer creates
+  an abandoned empty vault directory on refused platforms.
+- New transaction write destinations are validated against
+  portable-filesystem rules on every platform: Windows-reserved device names
+  (`CON`, `NUL`, ...), `:<>|?*"` characters, and trailing dots/spaces are
+  rejected with `UNPORTABLE_WRITE_PATH` so an approved plan means the same
+  thing everywhere. Reads, retrieval indexing, and journal recovery of
+  pre-existing files with such names are intentionally unaffected.
+- Degraded-mode path walks now reject Windows directory junctions and mount
+  points in addition to symlinks.
+- File permission bits feeding plan hashes are normalized to `0o644` on
+  Windows, keeping inspect output deterministic.
+- Added a `.gitattributes` that disables line-ending translation so checkouts
+  hash identically on every platform.
+- CI gained a `windows-smoke` job exercising the portable Python surface and
+  the new Windows compatibility suite on `windows-latest`.
 - Replaced the animated README hero with the selected static PNG cover while
   preserving the warm orbital style.
 

README.md

@@ -345,10 +345,15 @@ remain yours.
 - Bash for setup, optional extensions, and shell test suites
 - Git only for development, releases, or an explicit knowledge checkpoint
 
-CI exercises Linux and macOS. On Windows, use WSL; native Windows and Git Bash
-are not current compatibility guarantees. Optional tools such as Obsidian CLI,
-Ollama, and defuddle are capability-detected and affect only their dependent
-workflow.
+CI exercises Linux and macOS, plus a native-Windows smoke job for the portable
+surface. On native Windows (including Git Bash), read-only inspection and
+dry-run commands work; vault writes require WSL and fail closed with an
+`UNSUPPORTED_PLATFORM` error otherwise. Approval hashes bind to the reviewing
+environment's filesystem identity, so run the dry-run review inside WSL when
+the apply will happen there — a natively produced `approved_plan_sha256`
+cannot be replayed from WSL. The bash setup scripts and shell test suites
+remain POSIX-only. Optional tools such as Obsidian CLI, Ollama, and defuddle
+are capability-detected and affect only their dependent workflow.
 
 ## Development and release
 

claude_obsidian/capture.py

@@ -36,6 +36,8 @@
     BUNDLE_SCHEMA,
     TransactionValidationError,
     _LockIdentityChanged,
+    _PlatformConfinementUnavailable,
+    _UNSUPPORTED_PLATFORM_MESSAGE,
     _lock_entry_matches,
     _open_lock_directory_at,
     _open_lock_parent_from_root_fd,
@@ -205,6 +207,10 @@ def _safe_runtime_dir(vault_root: Path) -> Path:
             create=True,
         )
     except OSError as exc:
+        if isinstance(exc, _PlatformConfinementUnavailable):
+            raise CaptureValidationError(
+                "UNSUPPORTED_PLATFORM", _UNSUPPORTED_PLATFORM_MESSAGE
+            ) from exc
         if exc.errno in {errno.ELOOP, errno.ENOTDIR}:
             raise CaptureValidationError(
                 "RUNTIME_SYMLINK",
@@ -1494,6 +1500,10 @@ def acquire(self) -> None:
         try:
             root_fd = _open_lock_root_fd(self.vault_root)
         except OSError as exc:
+            if isinstance(exc, _PlatformConfinementUnavailable):
+                raise CaptureValidationError(
+                    "UNSUPPORTED_PLATFORM", _UNSUPPORTED_PLATFORM_MESSAGE
+                ) from exc
             raise CaptureError(
                 "QUEUE_LOCK_FAILED", f"cannot pin capture vault root: {exc}"
             ) from exc

claude_obsidian/checkpoint.py

@@ -18,7 +18,7 @@
 
 from .json_utils import parse_finite_json_float
 from .lint_engine import lint_vault
-from .paths import canonical
+from .paths import canonical, directory_open_flags, read_open_flags
 from .transaction import (
     RESULT_SCHEMA,
     MutationLock,
@@ -425,11 +425,7 @@ def read(self, name: str, *, label: str, code: str) -> dict[str, Any]:
                 or before.st_size > MAX_CHECKPOINT_STATE_BYTES
             ):
                 raise CheckpointError(code, f"{label} is not a bounded regular file")
-            descriptor = os.open(
-                name,
-                os.O_RDONLY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0),
-                dir_fd=self.operation_fd,
-            )
+            descriptor = os.open(name, read_open_flags(), dir_fd=self.operation_fd)
             opened = os.fstat(descriptor)
             if (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino):
                 raise CheckpointError(code, f"{label} changed before it could be read")
@@ -530,9 +526,7 @@ def other_pending(self) -> str | None:
             raise CheckpointError(
                 "CORRUPT_CHECKPOINT", f"cannot list transaction state: {exc}"
             ) from exc
-        flags = (
-            os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0)
-        )
+        flags = directory_open_flags()
         for name in names:
             if name == self.operation_id:
                 continue

claude_obsidian/cli.py

@@ -45,6 +45,7 @@
     MutationLock,
     TransactionError,
     TransactionValidationError,
+    _require_write_platform,
     apply_bundle,
     inspect_bundle,
     read_vault_regular,
@@ -810,6 +811,10 @@ def command_init(args: argparse.Namespace) -> int:
             }
         )
         return 0
+    # Refuse unsupported write platforms before creating the destination
+    # directory: a failed Init root is never path-deleted (see below), so the
+    # check must precede the mkdir rather than surface later in apply_bundle.
+    _require_write_platform()
     reviewed_plan = _require_approved_plan(args, destination, operation)
     approval = str(reviewed_plan["approval_sha256"])
     created = False
@@ -1218,7 +1223,27 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
+def _force_utf8_stdio() -> None:
+    """Emit UTF-8 regardless of the console code page.
+
+    On Windows, redirected stdout/stderr default to the locale encoding
+    (cp1252), so any non-ASCII page title crashes ``_emit``'s
+    ``ensure_ascii=False`` output.  ``newline=""`` keeps JSON output
+    byte-identical across platforms.
+    """
+
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8", newline="")
+        except (OSError, ValueError):
+            pass
+
+
 def main(argv: Sequence[str] | None = None) -> int:
+    _force_utf8_stdio()
     parser = build_parser()
     args = parser.parse_args(argv)
     try:

claude_obsidian/hook_adapter.py

@@ -16,6 +16,7 @@
     VaultSelectionError,
     assert_within,
     canonical,
+    is_name_surrogate,
     is_relative_to,
     resolve_vault_root,
 )
@@ -47,8 +48,13 @@ def _bounded_regular_bytes(root: Path, path: Path, limit: int) -> bytes | None:
         | getattr(os, "O_CLOEXEC", 0)
         | getattr(os, "O_NOFOLLOW", 0)
     )
+    # O_BINARY keeps the Windows CRT from CRLF-translating reads at the
+    # descriptor layer, which would corrupt content passed to hashing callers.
     file_flags = (
-        os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
+        os.O_RDONLY
+        | getattr(os, "O_CLOEXEC", 0)
+        | getattr(os, "O_NOFOLLOW", 0)
+        | getattr(os, "O_BINARY", 0)
     )
     if os.name != "nt" and os.open in os.supports_dir_fd and hasattr(os, "O_DIRECTORY"):
         try:
@@ -83,7 +89,7 @@ def _bounded_regular_bytes(root: Path, path: Path, limit: int) -> bytes | None:
                 metadata = cursor.lstat()
             except OSError:
                 return None
-            if stat.S_ISLNK(metadata.st_mode):
+            if is_name_surrogate(metadata):
                 return None
         try:
             descriptor = os.open(path, file_flags)