@litfamily/lithermes 1.0.0

package/assets/lithermes-plugin/skill_observer.py

@@ -0,0 +1,1778 @@
+"""Durable store for skill-improvement observations.
+
+The capability's whole value rests on one restraint: it proposes, and something
+with judgement decides. A tool that edited skills from its own inferences would
+compound its mistakes silently, and the skill corpus would drift away from
+anything a reviewer approved. So every record here carries ``applied: False``,
+and nothing in this module opens a skill file for writing.
+
+Observations are text the session did not author -- a user's correction quoted
+back, a pattern noticed in a transcript. That text is stored as data: bounded,
+single-line, credential-free, and never interpreted. An observation asking to
+rewrite every skill is a curiosity to record, not an instruction to follow.
+"""
+
+from __future__ import annotations
+
+import errno
+import json
+import os
+import re
+import stat
+import sys
+import threading
+import time
+import unicodedata
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Final
+
+if __package__:
+    from .redaction import redact_text
+else:  # Standalone diagnostic/test imports retain their existing module entry.
+    from redaction import redact_text
+
+try:
+    import fcntl
+except (ImportError, ModuleNotFoundError):  # pragma: no cover - Hermes targets POSIX hosts
+    fcntl = None
+
+_SETUP_FLOCK = fcntl.flock if fcntl is not None else None
+
+#: The three signals worth capturing. A fourth needs a contract revision, not a
+#: free-text value.
+OBSERVER_SIGNALS: Final = ("correction", "repetition", "coverage-gap")
+
+_ALLOWED_FIELDS: Final = ("signal", "skill_id", "observed", "proposal")
+_PERSISTED_FIELDS: Final = _ALLOWED_FIELDS + ("applied",)
+_TEXT_CEILING: Final = 1000
+MAX_LOG_BYTES: Final = 1024 * 1024
+_LOCK_WAIT_SECONDS: Final = 0.5
+_LOCK_POLL_SECONDS: Final = 0.01
+_LOG_NAME: Final = "observations.jsonl"
+_LOCK_NAME: Final = "observations.jsonl.lock"
+_LOCK_STALE_SECONDS: Final = 5.0
+_LOCK_METADATA_BYTES: Final = 4096
+_STATE_COMPONENTS: Final = (".hermes", "lithermes", "skill-observer")
+_PATH_SETUP_LOCK = threading.Lock()
+_UNKNOWN_FIELD_MESSAGE: Final = "unknown observation field"
+_SECRET_SCAN_BYTE_CEILING: Final = 64 * 1024
+_COMMITTED_CLEANUP_CODE: Final = "OBSERVER_RECORD_COMMITTED_CLEANUP_FAILED"
+_COMMITTED_CLEANUP_MESSAGE: Final = "the observation record was committed; read the log before retrying"
+_UNKNOWN_STATE_CODE: Final = "OBSERVER_RECORD_STATE_UNKNOWN"
+_UNKNOWN_STATE_MESSAGE: Final = (
+    "the observation record rollback failed; the record state is unknown; read the log before retrying"
+)
+_SKILL_ID: Final = re.compile(r"[a-z][a-z0-9-]{0,63}")
+_CONTROL: Final = re.compile(r"[\x00-\x1f\x7f-\x9f]")
+
+
+def _is_windows_runtime() -> bool:
+    return sys.platform == "win32"
+
+
+def _uses_path_lock() -> bool:
+    return fcntl is None or _is_windows_runtime()
+
+
+class SkillObserverError(Exception):
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def _committed_cleanup_error() -> SkillObserverError:
+    return SkillObserverError(_COMMITTED_CLEANUP_CODE, _COMMITTED_CLEANUP_MESSAGE)
+
+
+def _unknown_state_error() -> SkillObserverError:
+    return SkillObserverError(_UNKNOWN_STATE_CODE, _UNKNOWN_STATE_MESSAGE)
+
+
+def _is_unknown_state(error: BaseException | None) -> bool:
+    return isinstance(error, SkillObserverError) and error.code == _UNKNOWN_STATE_CODE
+
+
+def _unsafe_text_error() -> SkillObserverError:
+    return SkillObserverError(
+        "OBSERVER_TEXT_UNSAFE",
+        "observation text contains incomplete or unsupported terminal escape data",
+    )
+
+
+def _text_too_large_error() -> SkillObserverError:
+    return SkillObserverError(
+        "OBSERVER_TEXT_TOO_LARGE",
+        "observation text exceeds the secret-scan input limit",
+    )
+
+
+def _consume_csi(value: str, index: int) -> int:
+    intermediate = False
+    while index < len(value):
+        code = ord(value[index])
+        if not intermediate and 0x30 <= code <= 0x3F:
+            index += 1
+            continue
+        if 0x20 <= code <= 0x2F:
+            intermediate = True
+            index += 1
+            continue
+        if 0x40 <= code <= 0x7E:
+            return index + 1
+        raise _unsafe_text_error()
+    raise _unsafe_text_error()
+
+
+def _consume_osc(value: str, index: int) -> int:
+    while index < len(value):
+        character = value[index]
+        if character in ("\x07", "\x9c"):
+            return index + 1
+        if character == "\x1b":
+            if index + 1 < len(value) and value[index + 1] == "\\":
+                return index + 2
+            raise _unsafe_text_error()
+        index += 1
+    raise _unsafe_text_error()
+
+
+def _normalization_surfaces(value: str) -> tuple[str, str, str]:
+    if len(value.encode("utf-8", "surrogatepass")) > _SECRET_SCAN_BYTE_CEILING:
+        raise _text_too_large_error()
+
+    stripped: list[str] = []
+    spaced: list[str] = []
+    index = 0
+    while index < len(value):
+        character = value[index]
+        if character == "\x1b":
+            if index + 1 >= len(value):
+                raise _unsafe_text_error()
+            introducer = value[index + 1]
+            if introducer == "[":
+                index = _consume_csi(value, index + 2)
+            elif introducer == "]":
+                index = _consume_osc(value, index + 2)
+            else:
+                raise _unsafe_text_error()
+            spaced.append(" ")
+            continue
+        if character == "\x9b":
+            index = _consume_csi(value, index + 1)
+            spaced.append(" ")
+            continue
+        if character == "\x9d":
+            index = _consume_osc(value, index + 1)
+            spaced.append(" ")
+            continue
+        code = ord(character)
+        if 0x80 <= code <= 0x9F:
+            raise _unsafe_text_error()
+        stripped.append(character)
+        if code <= 0x1F or 0x7F <= code <= 0x9F or unicodedata.category(character) == "Cf":
+            spaced.append(" ")
+        else:
+            spaced.append(character)
+        index += 1
+
+    normalized_stripped = unicodedata.normalize("NFKC", "".join(stripped))
+    normalized_spaced = unicodedata.normalize("NFKC", "".join(spaced))
+    stripped_surface = "".join(
+        character
+        for character in normalized_stripped
+        if not _CONTROL.fullmatch(character) and unicodedata.category(character) != "Cf"
+    )
+    spaced_surface = "".join(
+        " "
+        if _CONTROL.fullmatch(character) or unicodedata.category(character) == "Cf"
+        else character
+        for character in normalized_spaced
+    )
+    return value, stripped_surface, spaced_surface
+
+
+def contains_secret(value: Any) -> bool:
+    """True when the value looks like it carries a credential.
+
+    This asks the harness's own redactor rather than carrying a second pattern
+    list: if redaction changes the text, a credential shape was present. Two
+    copies drift, and a stale copy fails open -- it persists the secret it was
+    written to catch.
+
+    The redactor also sees stripped and spaced text surfaces. ANSI escapes or
+    zero-width characters interleaved through a credential would otherwise
+    splice it apart so no detector pattern matches, and the fragments would
+    persist.
+    """
+    if not isinstance(value, str) or not value:
+        return False
+    return any(redact_text(surface) != surface for surface in _normalization_surfaces(value))
+
+
+def observation_log_path(root: str | os.PathLike[str]) -> Path:
+    return Path(root).resolve() / ".hermes" / "lithermes" / "skill-observer" / "observations.jsonl"
+
+
+def observation_lock_path(root: str | os.PathLike[str]) -> Path:
+    return observation_log_path(root).with_name(_LOCK_NAME)
+
+
+def _reject_symlink_ancestors(root: str | os.PathLike[str]) -> None:
+    try:
+        absolute = Path(os.path.abspath(os.fspath(root)))
+    except (OSError, TypeError):
+        raise SkillObserverError("OBSERVER_LOG_UNSAFE", "the observation workspace path is invalid") from None
+    current = Path(absolute.anchor)
+    for part in absolute.parts:
+        if part == absolute.anchor:
+            continue
+        current /= part
+        try:
+            value = os.lstat(current)
+        except FileNotFoundError:
+            break
+        except OSError:
+            raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation workspace parent cannot be inspected") from None
+        if stat.S_ISLNK(value.st_mode) and not _is_platform_path_alias(current):
+            raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation workspace parent is a symbolic link")
+
+
+def _is_platform_path_alias(path: Path) -> bool:
+    if path.parent != Path("/"):
+        return False
+    try:
+        target = Path(os.path.realpath(path))
+    except OSError:
+        return False
+    return target.parent == Path("/private") and target.name == path.name
+
+
+def _canonical_workspace(root: str | os.PathLike[str], *, missing_ok: bool = False) -> Path:
+    _reject_symlink_ancestors(root)
+    base = Path(root)
+    if base.is_symlink() and not _is_platform_path_alias(base):
+        raise SkillObserverError("OBSERVER_LOG_UNSAFE", "the observation workspace is a symbolic link")
+    try:
+        resolved = base.resolve(strict=True)
+    except FileNotFoundError:
+        if missing_ok:
+            raise
+        raise SkillObserverError("OBSERVER_LOG_UNSAFE", "the observation workspace is unavailable") from None
+    except (OSError, RuntimeError):
+        raise SkillObserverError("OBSERVER_LOG_UNSAFE", "the observation workspace is unavailable") from None
+    try:
+        value = os.stat(resolved, follow_symlinks=False)
+    except OSError:
+        raise SkillObserverError("OBSERVER_LOG_UNSAFE", "the observation workspace cannot be inspected") from None
+    if stat.S_ISLNK(value.st_mode) or not stat.S_ISDIR(value.st_mode):
+        raise SkillObserverError("OBSERVER_LOG_UNSAFE", "the observation workspace is not a directory")
+    return resolved
+
+
+def _directory_flags() -> int:
+    required = ("O_DIRECTORY", "O_NOFOLLOW")
+    if any(not hasattr(os, name) for name in required):
+        raise SkillObserverError("OBSERVER_PATH_UNSUPPORTED", "safe directory operations are unavailable")
+    return os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0)
+
+
+def _same_identity(first: os.stat_result, second: os.stat_result) -> bool:
+    return (
+        first.st_dev == second.st_dev
+        and first.st_ino == second.st_ino
+        and first.st_mode == second.st_mode
+    )
+
+
+def _birthtime(value: os.stat_result) -> int | float | None:
+    birthtime_ns = getattr(value, "st_birthtime_ns", None)
+    if birthtime_ns is not None:
+        return birthtime_ns
+    return getattr(value, "st_birthtime", None)
+
+
+def _same_immutable_identity(first: os.stat_result, second: os.stat_result) -> bool:
+    """Bind a path-to-open/rollback check to creation metadata as well as dev+ino."""
+    if not (
+        first.st_dev == second.st_dev
+        and first.st_ino == second.st_ino
+        and first.st_mode == second.st_mode
+    ):
+        return False
+    first_ctime = getattr(first, "st_ctime_ns", None)
+    second_ctime = getattr(second, "st_ctime_ns", None)
+    if first_ctime is not None or second_ctime is not None:
+        if first_ctime is None or second_ctime is None or first_ctime != second_ctime:
+            return False
+    first_birthtime = _birthtime(first)
+    second_birthtime = _birthtime(second)
+    if first_birthtime is not None or second_birthtime is not None:
+        return first_birthtime is not None and first_birthtime == second_birthtime
+    return first_ctime is not None and first_ctime == second_ctime
+
+
+def _same_creation_identity(first: os.stat_result, second: os.stat_result) -> bool:
+    if not (
+        first.st_dev == second.st_dev
+        and first.st_ino == second.st_ino
+        and first.st_mode == second.st_mode
+    ):
+        return False
+    first_birthtime = _birthtime(first)
+    second_birthtime = _birthtime(second)
+    if first_birthtime is not None or second_birthtime is not None:
+        return first_birthtime is not None and first_birthtime == second_birthtime
+    first_ctime = getattr(first, "st_ctime_ns", None)
+    second_ctime = getattr(second, "st_ctime_ns", None)
+    return first_ctime is not None and first_ctime == second_ctime
+
+
+def _validate_directory(value: os.stat_result) -> None:
+    if stat.S_ISLNK(value.st_mode) or not stat.S_ISDIR(value.st_mode):
+        raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent is not a regular directory")
+
+
+def _validate_regular(value: os.stat_result, *, lock: bool = False) -> None:
+    if stat.S_ISLNK(value.st_mode) or not stat.S_ISREG(value.st_mode):
+        code = "OBSERVER_LOCK_UNSAFE" if lock else "OBSERVER_LOG_UNSAFE"
+        raise SkillObserverError(code, "the observation path is not a regular file")
+    if value.st_nlink != 1:
+        code = "OBSERVER_LOCK_HARDLINK" if lock else "OBSERVER_LOG_HARDLINK"
+        raise SkillObserverError(code, "the observation path has multiple hard links")
+    if not _is_windows_runtime() and value.st_mode & 0o077:
+        code = "OBSERVER_LOCK_UNSAFE" if lock else "OBSERVER_LOG_UNSAFE"
+        raise SkillObserverError(code, "the observation path must not be group or world accessible")
+
+
+def _stat_regular_at(directory_fd: int, name: str, *, lock: bool, missing_ok: bool) -> os.stat_result | None:
+    try:
+        value = os.stat(name, dir_fd=directory_fd, follow_symlinks=False)
+    except FileNotFoundError:
+        if missing_ok:
+            return None
+        raise
+    except OSError:
+        code = "OBSERVER_LOCK_UNSAFE" if lock else "OBSERVER_LOG_UNSAFE"
+        raise SkillObserverError(code, "the observation path cannot be inspected") from None
+    _validate_regular(value, lock=lock)
+    return value
+
+
+def _remove_created_directory(
+    parent_fd: int,
+    name: str,
+    expected: os.stat_result | None,
+    *,
+    pinned_fd: int | None = None,
+) -> None:
+    if expected is None:
+        return
+    try:
+        current = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+    except FileNotFoundError:
+        return
+    except OSError:
+        raise SkillObserverError(
+            "OBSERVER_LOG_ROLLBACK_FAILED", "a new observation parent cannot be inspected for removal"
+        ) from None
+    _validate_directory(current)
+    try:
+        identity_matches = (
+            _same_immutable_identity(os.fstat(pinned_fd), current)
+            if pinned_fd is not None
+            else _same_creation_identity(expected, current)
+        )
+    except OSError:
+        raise SkillObserverError(
+            "OBSERVER_LOG_ROLLBACK_FAILED", "a new observation parent cannot be verified for removal"
+        ) from None
+    if not identity_matches:
+        raise SkillObserverError(
+            "OBSERVER_LOG_ROLLBACK_FAILED", "a new observation parent changed before removal"
+        )
+    try:
+        os.rmdir(name, dir_fd=parent_fd)
+    except OSError:
+        raise SkillObserverError(
+            "OBSERVER_LOG_ROLLBACK_FAILED", "a new observation parent could not be removed"
+        ) from None
+    try:
+        os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+    except FileNotFoundError:
+        return
+    except OSError:
+        raise SkillObserverError(
+            "OBSERVER_LOG_ROLLBACK_FAILED", "a new observation parent could not be verified after removal"
+        ) from None
+    raise SkillObserverError(
+        "OBSERVER_LOG_ROLLBACK_FAILED", "a new observation parent remained after removal"
+    )
+
+
+def _open_child_directory(
+    parent_fd: int,
+    name: str,
+    *,
+    create: bool,
+) -> tuple[int, os.stat_result, bool]:
+    created = False
+    try:
+        expected = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+    except FileNotFoundError:
+        if not create:
+            raise
+        try:
+            os.mkdir(name, 0o700, dir_fd=parent_fd)
+        except FileExistsError:
+            pass
+        else:
+            created = True
+        expected = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+    except OSError:
+        raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent cannot be inspected") from None
+    _validate_directory(expected)
+    try:
+        parent_before = os.fstat(parent_fd)
+    except OSError:
+        raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent cannot be verified safely") from None
+    _validate_directory(parent_before)
+    try:
+        descriptor = os.open(name, _directory_flags(), dir_fd=parent_fd)
+    except OSError:
+        if created:
+            _remove_created_directory(parent_fd, name, expected)
+        raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent cannot be opened safely") from None
+    try:
+        actual = os.fstat(descriptor)
+        _validate_directory(actual)
+        parent_after = os.fstat(parent_fd)
+        _validate_directory(parent_after)
+        # A directory's ctime legitimately changes when entries below it are
+        # created or removed.  The parent descriptor is the independent pin:
+        # if the child pathname was replaced, the parent's directory metadata
+        # changes even when Linux reuses the child's inode.  Permit only the
+        # child-local ctime drift that leaves that parent pin unchanged.
+        if not _same_immutable_identity(parent_before, parent_after) or (
+            not _same_creation_identity(expected, actual) and not _same_identity(expected, actual)
+        ):
+            raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent changed during open")
+        return descriptor, expected, created
+    except Exception:
+        os.close(descriptor)
+        if created:
+            _remove_created_directory(parent_fd, name, expected)
+        raise
+
+
+def _cleanup_created_directories(
+    created_components: list[tuple[int, str, os.stat_result]],
+) -> None:
+    for parent_fd, name, expected in reversed(created_components):
+        _remove_created_directory(parent_fd, name, expected)
+
+
+def _verify_pinned_ancestry(
+    base: Path,
+    expected_components: tuple[os.stat_result, ...],
+    pinned_fds: tuple[int, ...] | None = None,
+) -> os.stat_result:
+    if pinned_fds is not None:
+        if len(pinned_fds) != len(expected_components):
+            raise SkillObserverError("OBSERVER_LOG_UNSAFE", "the observation parent ancestry is incomplete")
+        for index, descriptor in enumerate(pinned_fds):
+            path = base.joinpath(*_STATE_COMPONENTS[:index])
+            # A competing writer can create the log between these metadata reads.
+            # Retry once against the same descriptor; persistent drift fails closed.
+            for _ in range(2):
+                try:
+                    current = os.stat(path, follow_symlinks=False)
+                    actual = os.fstat(descriptor)
+                except FileNotFoundError:
+                    raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent changed during setup") from None
+                except OSError:
+                    raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent cannot be verified safely") from None
+                _validate_directory(current)
+                _validate_directory(actual)
+                if _same_immutable_identity(current, actual):
+                    break
+            else:
+                raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent changed during setup")
+        return os.fstat(pinned_fds[-1])
+
+    parent_fd: int | None = None
+    try:
+        parent_fd = os.open(base, _directory_flags())
+        actual_base = os.fstat(parent_fd)
+        _validate_directory(actual_base)
+        if not _same_creation_identity(expected_components[0], actual_base):
+            raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent changed during setup")
+        for index, name in enumerate(_STATE_COMPONENTS[: len(expected_components) - 1], start=1):
+            child_fd, observed, _ = _open_child_directory(parent_fd, name, create=False)
+            try:
+                actual = os.fstat(child_fd)
+                _validate_directory(actual)
+                if (
+                    not _same_creation_identity(expected_components[index], observed)
+                    or not _same_creation_identity(expected_components[index], actual)
+                ):
+                    raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent changed during setup")
+            except Exception:
+                os.close(child_fd)
+                raise
+            os.close(parent_fd)
+            parent_fd = child_fd
+        return os.fstat(parent_fd)
+    except FileNotFoundError:
+        raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent changed during setup") from None
+    except OSError:
+        raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent cannot be verified safely") from None
+    finally:
+        if parent_fd is not None:
+            os.close(parent_fd)
+
+
+@contextmanager
+def _state_directory(root: str | os.PathLike[str], *, create: bool, committed=None):
+    base = _canonical_workspace(root, missing_ok=not create)
+    expected_base = os.stat(base, follow_symlinks=False)
+    _validate_directory(expected_base)
+    try:
+        current_fd = os.open(base, _directory_flags())
+    except OSError:
+        raise SkillObserverError("OBSERVER_LOG_UNSAFE", "the observation workspace cannot be opened safely") from None
+    workspace_fd: int | None = None
+    open_fds = [current_fd]
+    created_components: list[tuple[int, str, os.stat_result]] = []
+    setup_lock_held = False
+    setup_complete = False
+    pending_error: BaseException | None = None
+    try:
+        actual_base = os.fstat(current_fd)
+        if not _same_creation_identity(expected_base, actual_base):
+            raise SkillObserverError("OBSERVER_LOG_UNSAFE", "the observation workspace changed during open")
+        try:
+            workspace_fd = os.dup(current_fd)
+        except OSError:
+            raise SkillObserverError("OBSERVER_LOG_UNSAFE", "the observation workspace cannot be pinned safely") from None
+
+        def state_tree_exists() -> bool:
+            for index in range(1, len(_STATE_COMPONENTS) + 1):
+                try:
+                    state_stat = os.stat(base.joinpath(*_STATE_COMPONENTS[:index]), follow_symlinks=False)
+                except OSError:
+                    return False
+                if not stat.S_ISDIR(state_stat.st_mode):
+                    return False
+            return True
+
+        needs_setup_lock = create and not state_tree_exists()
+        if needs_setup_lock and fcntl is not None and _SETUP_FLOCK is not None:
+            deadline = time.monotonic() + _LOCK_WAIT_SECONDS
+            while True:
+                try:
+                    _SETUP_FLOCK(workspace_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                    setup_lock_held = True
+                    break
+                except OSError as error:
+                    if error.errno not in (errno.EACCES, errno.EAGAIN):
+                        raise SkillObserverError(
+                            "OBSERVER_LOG_UNSAFE", "the observation workspace cannot be serialized safely"
+                        ) from None
+                    if state_tree_exists():
+                        break
+                    remaining = deadline - time.monotonic()
+                    if remaining <= 0:
+                        break
+                    time.sleep(min(_LOCK_POLL_SECONDS, remaining))
+        expected_state = expected_base
+        expected_components = [expected_base]
+        for name in _STATE_COMPONENTS:
+            parent_fd = current_fd
+            child_fd, expected_state, created = _open_child_directory(parent_fd, name, create=create)
+            open_fds.append(child_fd)
+            expected_components[-1] = os.fstat(parent_fd)
+            current_fd = child_fd
+            expected_components.append(expected_state)
+            if created:
+                created_components.append((parent_fd, name, expected_state))
+            _verify_pinned_ancestry(base, tuple(expected_components), tuple(open_fds))
+        pinned_components = tuple(expected_components)
+        pinned_fds = tuple(open_fds)
+
+        def verify_state() -> None:
+            _verify_pinned_state(base, current_fd, pinned_components, pinned_fds)
+
+        verify_state()
+        setup_complete = True
+        if setup_lock_held:
+            try:
+                _SETUP_FLOCK(workspace_fd, fcntl.LOCK_UN)
+            except OSError:
+                raise SkillObserverError("OBSERVER_LOG_UNSAFE", "the observation workspace lock could not be released") from None
+            setup_lock_held = False
+        try:
+            yield current_fd, verify_state, workspace_fd
+        except BaseException as error:
+            pending_error = error
+            try:
+                verify_state()
+            except Exception:
+                pass
+            raise
+    finally:
+        try:
+            if not setup_complete:
+                _cleanup_created_directories(created_components)
+        finally:
+            if setup_lock_held and workspace_fd is not None:
+                try:
+                    _SETUP_FLOCK(workspace_fd, fcntl.LOCK_UN)
+                except OSError:
+                    pass
+            close_error: OSError | None = None
+            for descriptor in reversed(open_fds):
+                try:
+                    os.close(descriptor)
+                except OSError as error:
+                    close_error = close_error or error
+            if workspace_fd is not None:
+                try:
+                    os.close(workspace_fd)
+                except OSError as error:
+                    close_error = close_error or error
+            if close_error is not None:
+                if committed is not None and committed():
+                    raise _committed_cleanup_error() from None
+                if _is_unknown_state(pending_error):
+                    raise pending_error
+                raise close_error
+
+
+def _verify_pinned_state(
+    base: Path,
+    directory_fd: int,
+    expected_components: tuple[os.stat_result, ...],
+    pinned_fds: tuple[int, ...] | None = None,
+) -> None:
+    reopened = _verify_pinned_ancestry(base, expected_components, pinned_fds)
+    try:
+        pinned = os.fstat(directory_fd)
+        _validate_directory(pinned)
+    except OSError:
+        raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent changed during write") from None
+    if pinned_fds is None:
+        if not _same_creation_identity(expected_components[-1], reopened) or not _same_creation_identity(
+            reopened, pinned
+        ):
+            raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent changed during write")
+    elif directory_fd != pinned_fds[-1]:
+        raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent changed during write")
+
+
+def _remove_created_path_directory(path: Path, expected: os.stat_result) -> None:
+    try:
+        current = os.stat(path, follow_symlinks=False)
+    except FileNotFoundError:
+        return
+    except OSError:
+        raise SkillObserverError(
+            "OBSERVER_LOG_ROLLBACK_FAILED", "a new observation parent cannot be inspected for removal"
+        ) from None
+    _validate_directory(current)
+    if not _same_creation_identity(expected, current):
+        raise SkillObserverError(
+            "OBSERVER_LOG_ROLLBACK_FAILED", "a new observation parent changed before removal"
+        )
+    try:
+        os.rmdir(path)
+    except OSError:
+        raise SkillObserverError(
+            "OBSERVER_LOG_ROLLBACK_FAILED", "a new observation parent could not be removed"
+        ) from None
+    try:
+        os.stat(path, follow_symlinks=False)
+    except FileNotFoundError:
+        return
+    except OSError:
+        raise SkillObserverError(
+            "OBSERVER_LOG_ROLLBACK_FAILED", "a new observation parent could not be verified after removal"
+        ) from None
+    raise SkillObserverError(
+        "OBSERVER_LOG_ROLLBACK_FAILED", "a new observation parent remained after removal"
+    )
+
+
+@contextmanager
+def _path_state_directory(root: str | os.PathLike[str], *, create: bool):
+    pin_directories = not _is_windows_runtime() and all(
+        hasattr(os, name) for name in ("O_DIRECTORY", "O_NOFOLLOW")
+    )
+    setup_lock_held = False
+    if pin_directories:
+        _PATH_SETUP_LOCK.acquire()
+        setup_lock_held = True
+
+    def release_setup_lock() -> None:
+        nonlocal setup_lock_held
+        if setup_lock_held:
+            _PATH_SETUP_LOCK.release()
+            setup_lock_held = False
+
+    try:
+        base = _canonical_workspace(root, missing_ok=not create)
+        try:
+            expected_base = os.stat(base, follow_symlinks=False)
+        except OSError:
+            raise SkillObserverError(
+                "OBSERVER_LOG_UNSAFE", "the observation workspace cannot be inspected"
+            ) from None
+        _validate_directory(expected_base)
+    except BaseException:
+        release_setup_lock()
+        raise
+    current = base
+    expected_paths: list[tuple[Path, os.stat_result]] = [(base, expected_base)]
+    created_components: list[tuple[Path, os.stat_result]] = []
+    created_pinned_components: list[tuple[int, str, os.stat_result, int]] = []
+    pinned_fds: list[int] = []
+    pinned_baselines: tuple[os.stat_result, ...] = ()
+    setup_complete = False
+
+    # POSIX hosts without advisory-lock support still have directory descriptors.
+    # Keep those descriptors pinned so directory ctime changes caused by creating
+    # the lock/log are compared against the live object, not a stale pre-write
+    # stat. Windows uses the path fallback because its directory-open flags and
+    # dir_fd APIs are not available.
+    if pin_directories:
+        try:
+            base_fd = os.open(base, _directory_flags())
+            actual_base = os.fstat(base_fd)
+            _validate_directory(actual_base)
+            if not _same_immutable_identity(expected_base, actual_base):
+                raise SkillObserverError("OBSERVER_LOG_UNSAFE", "the observation workspace changed during open")
+        except SkillObserverError:
+            try:
+                os.close(base_fd)
+            except (NameError, OSError):
+                pass
+            release_setup_lock()
+            raise
+        except OSError:
+            try:
+                os.close(base_fd)
+            except (NameError, OSError):
+                pass
+            release_setup_lock()
+            raise SkillObserverError(
+                "OBSERVER_LOG_UNSAFE", "the observation workspace cannot be opened safely"
+            ) from None
+        pinned_fds.append(base_fd)
+
+    def verify_state() -> None:
+        if pinned_fds:
+            if len(pinned_fds) != len(expected_paths) or len(pinned_baselines) != len(expected_paths):
+                raise SkillObserverError("OBSERVER_LOG_UNSAFE", "the observation parent ancestry is incomplete")
+            for index, (path, expected) in enumerate(expected_paths):
+                try:
+                    actual = os.stat(path, follow_symlinks=False)
+                except OSError:
+                    raise SkillObserverError(
+                        "OBSERVER_LOG_UNSAFE", "an observation parent changed during write"
+                    ) from None
+                _validate_directory(actual)
+                baseline = pinned_baselines[index]
+                _validate_directory(baseline)
+                if index < len(expected_paths) - 1:
+                    # Ancestor ctime is stable after setup; a replacement of
+                    # its child changes that parent entry and is rejected.
+                    identity_matches = _same_immutable_identity(baseline, actual)
+                else:
+                    # The leaf directory owns the lock/log, so its ctime is
+                    # expected to move during a legitimate write.
+                    expected_birthtime = _birthtime(expected)
+                    actual_birthtime = _birthtime(actual)
+                    birthtime_matches = (
+                        (expected_birthtime is None and actual_birthtime is None)
+                        or (expected_birthtime is not None and expected_birthtime == actual_birthtime)
+                    )
+                    identity_matches = _same_identity(expected, actual) and birthtime_matches
+                if not identity_matches:
+                    raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent changed during write")
+            return
+        for path, expected in expected_paths:
+            try:
+                actual = os.stat(path, follow_symlinks=False)
+            except OSError:
+                raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent changed during write") from None
+            _validate_directory(actual)
+            if not _same_creation_identity(expected, actual):
+                raise SkillObserverError("OBSERVER_LOG_UNSAFE", "an observation parent changed during write")
+
+    try:
+        for name in _STATE_COMPONENTS:
+            child = current / name
+            if pinned_fds:
+                parent_fd = pinned_fds[-1]
+                child_fd, expected, created = _open_child_directory(parent_fd, name, create=create)
+                pinned_fds.append(child_fd)
+                if created:
+                    created_pinned_components.append((parent_fd, name, expected, child_fd))
+            else:
+                created = False
+                try:
+                    expected = os.stat(child, follow_symlinks=False)
+                except FileNotFoundError:
+                    if not create:
+                        raise
+                    try:
+                        os.mkdir(child, 0o700)
+                    except FileExistsError:
+                        pass
+                    else:
+                        created = True
+                    expected = os.stat(child, follow_symlinks=False)
+                except OSError:
+                    raise SkillObserverError(
+                        "OBSERVER_LOG_UNSAFE", "an observation parent cannot be inspected"
+                    ) from None
+                _validate_directory(expected)
+            if created:
+                if not pinned_fds:
+                    created_components.append((child, expected))
+            current = child
+            expected_paths.append((current, expected))
+        pinned_baselines = tuple(os.fstat(descriptor) for descriptor in pinned_fds)
+        for baseline in pinned_baselines:
+            _validate_directory(baseline)
+        verify_state()
+        setup_complete = True
+        release_setup_lock()
+        yield current, verify_state
+    finally:
+        try:
+            if not setup_complete:
+                if pinned_fds:
+                    for parent_fd, name, expected, child_fd in reversed(created_pinned_components):
+                        _remove_created_directory(parent_fd, name, expected, pinned_fd=child_fd)
+                else:
+                    for path, expected in reversed(created_components):
+                        _remove_created_path_directory(path, expected)
+        finally:
+            for descriptor in reversed(pinned_fds):
+                try:
+                    os.close(descriptor)
+                except OSError:
+                    pass
+            release_setup_lock()
+
+
+def _path_regular_stat(path: Path, *, lock: bool, missing_ok: bool) -> os.stat_result | None:
+    try:
+        value = os.stat(path, follow_symlinks=False)
+    except FileNotFoundError:
+        if missing_ok:
+            return None
+        raise
+    except OSError:
+        code = "OBSERVER_LOCK_UNSAFE" if lock else "OBSERVER_LOG_UNSAFE"
+        raise SkillObserverError(code, "the observation path cannot be inspected") from None
+    _validate_regular(value, lock=lock)
+    return value
+
+
+def _open_path_regular(
+    directory: Path,
+    name: str,
+    *,
+    lock: bool,
+    append: bool,
+    create: bool,
+) -> tuple[int, bool, os.stat_result]:
+    path = directory / name
+    expected = _path_regular_stat(path, lock=lock, missing_ok=True)
+    flags = os.O_RDWR | getattr(os, "O_BINARY", 0) | getattr(os, "O_CLOEXEC", 0)
+    if append:
+        flags |= os.O_APPEND
+    if expected is None:
+        if not create:
+            raise FileNotFoundError(name)
+        flags |= os.O_CREAT | os.O_EXCL
+    try:
+        descriptor = os.open(path, flags, 0o600)
+    except FileExistsError:
+        if expected is None and create:
+            return _open_path_regular(directory, name, lock=lock, append=append, create=False)
+        raise SkillObserverError("OBSERVER_LOG_CHANGED", "the observation path changed during creation") from None
+    except OSError:
+        code = "OBSERVER_LOCK_UNSAFE" if lock else "OBSERVER_LOG_UNSAFE"
+        raise SkillObserverError(code, "the observation path cannot be opened safely") from None
+    try:
+        actual = os.fstat(descriptor)
+        _validate_regular(actual, lock=lock)
+        current = _path_regular_stat(path, lock=lock, missing_ok=False)
+        if current is None or not _same_immutable_identity(actual, current):
+            code = "OBSERVER_LOCK_UNSAFE" if lock else "OBSERVER_LOG_CHANGED"
+            raise SkillObserverError(code, "the observation path changed during open")
+        if expected is not None and not _same_immutable_identity(expected, actual):
+            code = "OBSERVER_LOCK_UNSAFE" if lock else "OBSERVER_LOG_CHANGED"
+            raise SkillObserverError(code, "the observation path changed during open")
+        return descriptor, expected is None, actual
+    except BaseException:
+        os.close(descriptor)
+        raise
+
+
+def _verify_path_log(directory: Path, descriptor: int, expected: os.stat_result) -> None:
+    try:
+        current = _path_regular_stat(directory / _LOG_NAME, lock=False, missing_ok=False)
+        actual = os.fstat(descriptor)
+    except FileNotFoundError:
+        raise SkillObserverError("OBSERVER_LOG_CHANGED", "the observation log changed during write") from None
+    _validate_regular(actual)
+    if current is None or not _same_identity(expected, actual) or not _same_identity(expected, current):
+        raise SkillObserverError("OBSERVER_LOG_CHANGED", "the observation log changed during write")
+
+
+def _unlink_created_path_log(directory: Path, descriptor: int, expected: os.stat_result) -> None:
+    path = directory / _LOG_NAME
+    try:
+        current = _path_regular_stat(path, lock=False, missing_ok=False)
+        actual = os.fstat(descriptor)
+        _validate_regular(actual)
+        if current is None or not _same_identity(expected, actual) or not _same_identity(expected, current):
+            raise SkillObserverError("OBSERVER_LOG_ROLLBACK_FAILED", "the new observation log changed before removal")
+        os.unlink(path)
+        if _path_regular_stat(path, lock=False, missing_ok=True) is not None:
+            raise SkillObserverError("OBSERVER_LOG_ROLLBACK_FAILED", "the new observation log could not be removed")
+    except (OSError, SkillObserverError):
+        raise SkillObserverError("OBSERVER_LOG_ROLLBACK_FAILED", "the new observation log could not be removed") from None
+
+
+def _read_path_lock(path: Path) -> tuple[os.stat_result, dict[str, Any]]:
+    before = _path_regular_stat(path, lock=True, missing_ok=False)
+    if before is None:
+        raise FileNotFoundError(path)
+    descriptor: int | None = None
+    try:
+        flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_CLOEXEC", 0)
+        descriptor = os.open(path, flags)
+        actual = os.fstat(descriptor)
+        if actual.st_nlink == 0:
+            raise SkillObserverError("OBSERVER_LOCK_CHANGED", "the observation lock disappeared during read")
+        _validate_regular(actual, lock=True)
+        if not _same_immutable_identity(before, actual):
+            raise SkillObserverError("OBSERVER_LOCK_CHANGED", "the observation lock changed during read")
+        if actual.st_size > _LOCK_METADATA_BYTES:
+            raise SkillObserverError("OBSERVER_LOCK_MALFORMED", "the observation lock metadata is malformed")
+        os.lseek(descriptor, 0, os.SEEK_SET)
+        raw = os.read(descriptor, _LOCK_METADATA_BYTES + 1)
+        if len(raw) > _LOCK_METADATA_BYTES:
+            raise SkillObserverError("OBSERVER_LOCK_MALFORMED", "the observation lock metadata is malformed")
+        after = os.fstat(descriptor)
+        if after.st_nlink == 0:
+            raise SkillObserverError("OBSERVER_LOCK_CHANGED", "the observation lock disappeared during read")
+        _validate_regular(after, lock=True)
+        if not _same_immutable_identity(before, after) or after.st_size != actual.st_size:
+            raise SkillObserverError("OBSERVER_LOCK_CHANGED", "the observation lock changed during read")
+    except FileNotFoundError:
+        raise
+    except SkillObserverError:
+        raise
+    except (OSError, UnicodeDecodeError, ValueError, TypeError):
+        raise SkillObserverError("OBSERVER_LOCK_MALFORMED", "the observation lock metadata is malformed") from None
+    finally:
+        if descriptor is not None:
+            os.close(descriptor)
+    try:
+        owner = json.loads(raw.decode("utf-8"), object_pairs_hook=_reject_duplicate_keys)
+    except (UnicodeDecodeError, ValueError, TypeError):
+        raise SkillObserverError("OBSERVER_LOCK_MALFORMED", "the observation lock metadata is malformed") from None
+    if (
+        not isinstance(owner, dict)
+        or set(owner) != {"pid", "token"}
+        or isinstance(owner.get("pid"), bool)
+        or not isinstance(owner.get("pid"), int)
+        or owner["pid"] <= 0
+        or not isinstance(owner.get("token"), str)
+        or not re.fullmatch(r"[0-9a-f]{32}", owner["token"])
+    ):
+        raise SkillObserverError("OBSERVER_LOCK_MALFORMED", "the observation lock metadata is malformed")
+    return before, owner
+
+
+def _lock_owner_is_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError as error:
+        if error.errno == errno.ESRCH or getattr(error, "winerror", None) in (87, 128):
+            return False
+        return True
+    return True
+
+
+def _remove_path_lock(path: Path, expected: os.stat_result, token: str | None = None) -> bool:
+    current = _path_regular_stat(path, lock=True, missing_ok=True)
+    if current is None:
+        return True
+    if not _same_immutable_identity(expected, current):
+        return False
+    if token is not None:
+        _, owner = _read_path_lock(path)
+        if owner["token"] != token:
+            return False
+    try:
+        os.unlink(path)
+    except FileNotFoundError:
+        return True
+    except OSError:
+        raise SkillObserverError("OBSERVER_LOCK_CLEANUP_FAILED", "the observation lock could not be removed") from None
+    replacement = _path_regular_stat(path, lock=True, missing_ok=True)
+    if replacement is None:
+        return True
+    if not _same_identity(expected, replacement):
+        return True
+    # Some filesystems can reuse an inode immediately after unlink. The token
+    # disambiguates a valid replacement without ever removing that replacement;
+    # an equal or unreadable token remains an unverifiable cleanup and fails closed.
+    if token is None:
+        return False
+    try:
+        _, owner = _read_path_lock(path)
+    except FileNotFoundError:
+        return True
+    except SkillObserverError:
+        return False
+    return owner["token"] != token
+
+
+def _path_lock_is_stale(value: os.stat_result) -> bool:
+    return time.time() - value.st_mtime >= _LOCK_STALE_SECONDS
+
+
+def _read_path_lock_after_creation_race(path: Path) -> tuple[os.stat_result, dict[str, Any]]:
+    try:
+        return _read_path_lock(path)
+    except SkillObserverError as error:
+        if error.code != "OBSERVER_LOCK_MALFORMED":
+            raise
+        time.sleep(_LOCK_POLL_SECONDS)
+        try:
+            return _read_path_lock(path)
+        except SkillObserverError as retry_error:
+            if retry_error.code == "OBSERVER_LOCK_MALFORMED":
+                raise error
+            raise
+
+
+def _write_path_lock(path: Path, token: str) -> tuple[int, os.stat_result]:
+    metadata = json.dumps({"pid": os.getpid(), "token": token}, sort_keys=True).encode("utf-8")
+    try:
+        descriptor = os.open(
+            path,
+            os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0) | getattr(os, "O_CLOEXEC", 0),
+            0o600,
+        )
+    except FileExistsError:
+        raise
+    except OSError:
+        raise SkillObserverError("OBSERVER_LOCK_FAILED", "the observation lock could not be created") from None
+    try:
+        written = os.write(descriptor, metadata)
+        if written != len(metadata):
+            raise SkillObserverError("OBSERVER_LOCK_FAILED", "the observation lock metadata was incomplete")
+        os.fsync(descriptor)
+        return descriptor, os.fstat(descriptor)
+    except BaseException:
+        try:
+            os.close(descriptor)
+        finally:
+            try:
+                os.unlink(path)
+            except FileNotFoundError:
+                pass
+        raise
+
+
+@contextmanager
+def _path_writer_lock(directory: Path, *, verify=None, committed=None):
+    path = directory / _LOCK_NAME
+    token = os.urandom(16).hex()
+    descriptor: int | None = None
+    acquired = False
+    pending_error: BaseException | None = None
+    deadline = time.monotonic() + _LOCK_WAIT_SECONDS
+    try:
+        while True:
+            if verify is not None:
+                verify()
+            try:
+                descriptor, created = _write_path_lock(path, token)
+                acquired = True
+                _validate_regular(created, lock=True)
+                if verify is not None:
+                    verify()
+                break
+            except FileExistsError:
+                try:
+                    lock_stat, owner = _read_path_lock_after_creation_race(path)
+                except FileNotFoundError:
+                    continue
+                except SkillObserverError as error:
+                    if error.code == "OBSERVER_LOCK_CHANGED":
+                        continue
+                    raise
+                if _path_lock_is_stale(lock_stat) and not _lock_owner_is_alive(owner["pid"]):
+                    if _remove_path_lock(path, lock_stat, owner["token"]):
+                        continue
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise SkillObserverError("OBSERVER_LOCK_TIMEOUT", "the observation lock wait expired") from None
+                time.sleep(min(_LOCK_POLL_SECONDS, remaining))
+        try:
+            yield
+        except BaseException as error:
+            pending_error = error
+            raise
+    finally:
+        close_error: OSError | None = None
+        if descriptor is not None:
+            try:
+                os.close(descriptor)
+            except OSError as error:
+                close_error = error
+        if acquired:
+            try:
+                current = _path_regular_stat(path, lock=True, missing_ok=False)
+                if current is None or not _remove_path_lock(path, current, token):
+                    raise SkillObserverError("OBSERVER_LOCK_CLEANUP_FAILED", "the observation lock changed before removal")
+            except FileNotFoundError:
+                raise SkillObserverError("OBSERVER_LOCK_CLEANUP_FAILED", "the observation lock disappeared before removal") from None
+            except SkillObserverError:
+                if committed is not None and committed():
+                    raise _committed_cleanup_error() from None
+                if _is_unknown_state(pending_error):
+                    raise pending_error
+                raise
+            except OSError:
+                if committed is not None and committed():
+                    raise _committed_cleanup_error() from None
+                if _is_unknown_state(pending_error):
+                    raise pending_error
+                raise SkillObserverError("OBSERVER_LOCK_CLEANUP_FAILED", "the observation lock could not be removed") from None
+        if close_error is not None:
+            if committed is not None and committed():
+                raise _committed_cleanup_error() from None
+            if _is_unknown_state(pending_error):
+                raise pending_error
+            raise close_error
+
+
+def _open_regular_at(
+    directory_fd: int,
+    name: str,
+    *,
+    lock: bool,
+    append: bool,
+    create: bool,
+) -> tuple[int, bool]:
+    expected = _stat_regular_at(directory_fd, name, lock=lock, missing_ok=True)
+    flags = os.O_RDWR | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_CLOEXEC", 0)
+    if append:
+        flags |= os.O_APPEND
+    if expected is None:
+        if not create:
+            raise FileNotFoundError(name)
+        flags |= os.O_CREAT | os.O_EXCL
+    try:
+        descriptor = os.open(name, flags, 0o600, dir_fd=directory_fd)
+    except FileExistsError:
+        if expected is None and create:
+            return _open_regular_at(directory_fd, name, lock=lock, append=append, create=False)
+        raise SkillObserverError("OBSERVER_LOG_UNSAFE", "the observation path changed during creation") from None
+    except OSError:
+        code = "OBSERVER_LOCK_UNSAFE" if lock else "OBSERVER_LOG_UNSAFE"
+        raise SkillObserverError(code, "the observation path cannot be opened safely") from None
+    try:
+        actual = os.fstat(descriptor)
+        _validate_regular(actual, lock=lock)
+        current = _stat_regular_at(directory_fd, name, lock=lock, missing_ok=False)
+        if current is None or not _same_immutable_identity(actual, current):
+            code = "OBSERVER_LOCK_UNSAFE" if lock else "OBSERVER_LOG_CHANGED"
+            raise SkillObserverError(code, "the observation path changed during open")
+        if expected is not None and not _same_immutable_identity(expected, actual):
+            code = "OBSERVER_LOCK_UNSAFE" if lock else "OBSERVER_LOG_CHANGED"
+            raise SkillObserverError(code, "the observation path changed during open")
+        return descriptor, expected is None
+    except Exception:
+        os.close(descriptor)
+        raise
+
+
+def _read_descriptor(descriptor: int) -> bytes:
+    before = os.fstat(descriptor)
+    _validate_regular(before)
+    if before.st_size > MAX_LOG_BYTES:
+        raise SkillObserverError("OBSERVER_LOG_SIZE_EXCEEDED", "the observation log exceeds its size limit")
+    os.lseek(descriptor, 0, os.SEEK_SET)
+    remaining = before.st_size
+    chunks: list[bytes] = []
+    while remaining:
+        chunk = os.read(descriptor, min(65536, remaining))
+        if not chunk:
+            raise SkillObserverError("OBSERVER_LOG_CHANGED", "the observation log changed during read")
+        chunks.append(chunk)
+        remaining -= len(chunk)
+    if os.read(descriptor, 1):
+        raise SkillObserverError("OBSERVER_LOG_CHANGED", "the observation log changed during read")
+    after = os.fstat(descriptor)
+    _validate_regular(after)
+    if not _same_identity(before, after) or after.st_size != before.st_size:
+        raise SkillObserverError("OBSERVER_LOG_CHANGED", "the observation log changed during read")
+    return b"".join(chunks)
+
+
+def _verify_log_path(directory_fd: int, descriptor: int, expected: os.stat_result) -> None:
+    try:
+        current = _stat_regular_at(directory_fd, _LOG_NAME, lock=False, missing_ok=False)
+        actual = os.fstat(descriptor)
+    except FileNotFoundError:
+        raise SkillObserverError("OBSERVER_LOG_CHANGED", "the observation log changed during write") from None
+    _validate_regular(actual)
+    if current is None or not _same_identity(expected, actual) or not _same_identity(expected, current):
+        raise SkillObserverError("OBSERVER_LOG_CHANGED", "the observation log changed during write")
+
+
+def _unlink_created_log(directory_fd: int, descriptor: int, expected: os.stat_result) -> None:
+    try:
+        current = _stat_regular_at(directory_fd, _LOG_NAME, lock=False, missing_ok=False)
+        actual = os.fstat(descriptor)
+        _validate_regular(actual)
+        if current is None or not _same_identity(expected, actual) or not _same_identity(expected, current):
+            raise SkillObserverError("OBSERVER_LOG_ROLLBACK_FAILED", "the new observation log changed before removal")
+        os.unlink(_LOG_NAME, dir_fd=directory_fd)
+        if _stat_regular_at(directory_fd, _LOG_NAME, lock=False, missing_ok=True) is not None:
+            raise SkillObserverError("OBSERVER_LOG_ROLLBACK_FAILED", "the new observation log could not be removed")
+    except (OSError, SkillObserverError):
+        raise SkillObserverError("OBSERVER_LOG_ROLLBACK_FAILED", "the new observation log could not be removed") from None
+
+
+def _sync_log(descriptor: int) -> None:
+    try:
+        os.fsync(descriptor)
+    except (AttributeError, OSError):
+        raise SkillObserverError("OBSERVER_LOG_FSYNC_FAILED", "the observation log could not be synchronized") from None
+
+
+def _rollback_log(directory_fd: int, descriptor: int, expected: os.stat_result, prior_length: int) -> None:
+    try:
+        os.ftruncate(descriptor, prior_length)
+        _sync_log(descriptor)
+        _verify_log_path(directory_fd, descriptor, expected)
+    except (AttributeError, OSError, SkillObserverError):
+        raise SkillObserverError("OBSERVER_LOG_ROLLBACK_FAILED", "the observation log could not be rolled back") from None
+
+
+def _cleanup_log_failure(
+    directory_fd: int,
+    descriptor: int,
+    expected: os.stat_result,
+    prior_length: int,
+    *,
+    created: bool,
+    write_attempted: bool,
+) -> None:
+    rollback_error: SkillObserverError | None = None
+    if write_attempted:
+        try:
+            _rollback_log(directory_fd, descriptor, expected, prior_length)
+        except SkillObserverError as error:
+            rollback_error = error
+    if rollback_error is not None:
+        raise _unknown_state_error() from None
+    if created:
+        _unlink_created_log(directory_fd, descriptor, expected)
+
+
+def _rollback_path_log(directory: Path, descriptor: int, expected: os.stat_result, prior_length: int) -> None:
+    try:
+        os.ftruncate(descriptor, prior_length)
+        _sync_log(descriptor)
+        _verify_path_log(directory, descriptor, expected)
+    except (AttributeError, OSError, SkillObserverError):
+        raise SkillObserverError("OBSERVER_LOG_ROLLBACK_FAILED", "the observation log could not be rolled back") from None
+
+
+def _cleanup_path_log_failure(
+    directory: Path,
+    descriptor: int,
+    expected: os.stat_result,
+    prior_length: int,
+    *,
+    created: bool,
+    write_attempted: bool,
+) -> None:
+    rollback_error: BaseException | None = None
+    if write_attempted:
+        try:
+            _rollback_path_log(directory, descriptor, expected, prior_length)
+        except BaseException as error:
+            rollback_error = error
+    if rollback_error is not None:
+        raise _unknown_state_error() from None
+    if created:
+        _unlink_created_path_log(directory, descriptor, expected)
+
+
+def _validate_existing_jsonl(raw: bytes) -> None:
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        raise SkillObserverError("OBSERVER_LOG_MALFORMED", "the existing observation log is not valid UTF-8") from None
+    if not text:
+        return
+    lines = text.split("\n")
+    if text.endswith("\n"):
+        lines.pop()
+    for line in lines:
+        try:
+            if not line.strip():
+                raise ValueError("blank JSONL record")
+            record = json.loads(line, object_pairs_hook=_reject_duplicate_keys)
+            _validate_observation(record, persisted=True)
+        except (ValueError, SkillObserverError):
+            raise SkillObserverError("OBSERVER_LOG_MALFORMED", "the existing observation log is malformed") from None
+
+
+@contextmanager
+def _writer_lock(workspace_fd: int, *, verify=None, committed=None):
+    if fcntl is None:
+        raise SkillObserverError("OBSERVER_LOCK_UNAVAILABLE", "bounded writer locking is unavailable")
+    pending_error: BaseException | None = None
+    try:
+        descriptor = os.open(".", _directory_flags(), dir_fd=workspace_fd)
+    except OSError:
+        raise SkillObserverError("OBSERVER_LOCK_UNAVAILABLE", "workspace directory locking is unavailable") from None
+    try:
+        deadline = time.monotonic() + _LOCK_WAIT_SECONDS
+        while True:
+            try:
+                fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                acquired = True
+                break
+            except OSError as error:
+                if error.errno not in (errno.EACCES, errno.EAGAIN):
+                    raise SkillObserverError("OBSERVER_LOCK_FAILED", "the observation lock failed") from None
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise SkillObserverError("OBSERVER_LOCK_TIMEOUT", "the observation lock wait expired") from None
+                time.sleep(min(_LOCK_POLL_SECONDS, remaining))
+        if verify is not None:
+            verify()
+        try:
+            yield
+        except BaseException as error:
+            pending_error = error
+            raise
+    finally:
+        try:
+            os.close(descriptor)
+        except OSError:
+            if committed is not None and committed():
+                raise _committed_cleanup_error() from None
+            if _is_unknown_state(pending_error):
+                raise pending_error
+            raise
+
+
+def _record_observation_path(root: str | os.PathLike[str], record: dict, payload: bytes) -> dict:
+    committed = False
+    with _path_state_directory(root, create=True) as (directory, verify_state):
+        descriptor: int | None = None
+        opened: os.stat_result | None = None
+        created = False
+        prior_length = 0
+        write_attempted = False
+        primary_error: BaseException | None = None
+        try:
+            verify_state()
+            with _path_writer_lock(directory, verify=verify_state, committed=lambda: committed):
+                try:
+                    descriptor, created, opened = _open_path_regular(
+                        directory, _LOG_NAME, lock=False, append=True, create=True
+                    )
+                    existing = _read_descriptor(descriptor)
+                    prior_length = len(existing)
+                    _verify_path_log(directory, descriptor, opened)
+                    _validate_existing_jsonl(existing)
+                    separator = b"" if not existing or existing.endswith(b"\n") else b"\n"
+                    addition = separator + payload
+                    if len(existing) + len(addition) > MAX_LOG_BYTES:
+                        raise SkillObserverError(
+                            "OBSERVER_LOG_SIZE_EXCEEDED", "the new observation would exceed the log size limit"
+                        )
+                    verify_state()
+                    os.lseek(descriptor, 0, os.SEEK_END)
+                    write_attempted = True
+                    try:
+                        written = os.write(descriptor, addition)
+                    except OSError:
+                        raise SkillObserverError(
+                            "OBSERVER_LOG_WRITE_FAILED", "the observation record could not be written"
+                        ) from None
+                    if written != len(addition):
+                        raise SkillObserverError(
+                            "OBSERVER_LOG_WRITE_FAILED", "the observation record was not complete"
+                        )
+                    after = os.fstat(descriptor)
+                    _validate_regular(after)
+                    if after.st_size != len(existing) + len(addition):
+                        raise SkillObserverError("OBSERVER_LOG_CHANGED", "the observation log changed during write")
+                    _verify_path_log(directory, descriptor, after)
+                    _sync_log(descriptor)
+                    synced = os.fstat(descriptor)
+                    _validate_regular(synced)
+                    if synced.st_size != len(existing) + len(addition):
+                        raise SkillObserverError("OBSERVER_LOG_CHANGED", "the observation log changed during write")
+                    _verify_path_log(directory, descriptor, synced)
+                    verify_state()
+                    committed = True
+                except SkillObserverError as error:
+                    primary_error = error
+                    if descriptor is not None and opened is not None:
+                        try:
+                            _cleanup_path_log_failure(
+                                directory,
+                                descriptor,
+                                opened,
+                                prior_length,
+                                created=created,
+                                write_attempted=write_attempted,
+                            )
+                        except SkillObserverError as cleanup_error:
+                            primary_error = cleanup_error
+                            raise
+                    raise
+                except KeyboardInterrupt as error:
+                    primary_error = error
+                    if descriptor is not None and opened is not None:
+                        try:
+                            _cleanup_path_log_failure(
+                                directory,
+                                descriptor,
+                                opened,
+                                prior_length,
+                                created=created,
+                                write_attempted=write_attempted,
+                            )
+                        except SkillObserverError as cleanup_error:
+                            primary_error = cleanup_error
+                            raise
+                    raise
+                except OSError as error:
+                    primary_error = error
+                    if descriptor is not None and opened is not None:
+                        try:
+                            _cleanup_path_log_failure(
+                                directory,
+                                descriptor,
+                                opened,
+                                prior_length,
+                                created=created,
+                                write_attempted=write_attempted,
+                            )
+                        except SkillObserverError as cleanup_error:
+                            primary_error = cleanup_error
+                            raise
+                    raise SkillObserverError(
+                        "OBSERVER_LOG_WRITE_FAILED", "the observation log could not be written"
+                    ) from None
+                except BaseException as error:
+                    primary_error = error
+                    if descriptor is not None and opened is not None:
+                        try:
+                            _cleanup_path_log_failure(
+                                directory,
+                                descriptor,
+                                opened,
+                                prior_length,
+                                created=created,
+                                write_attempted=write_attempted,
+                            )
+                        except SkillObserverError as cleanup_error:
+                            primary_error = cleanup_error
+                            raise
+                    raise
+        finally:
+            if descriptor is not None:
+                try:
+                    os.close(descriptor)
+                except OSError:
+                    if committed:
+                        raise _committed_cleanup_error() from None
+                    if _is_unknown_state(primary_error):
+                        raise primary_error
+                    raise
+    return record
+
+
+def _read_observations_path(root: str | os.PathLike[str]) -> list[dict]:
+    try:
+        with _path_state_directory(root, create=False) as (directory, verify_state):
+            descriptor: int | None = None
+            try:
+                verify_state()
+                with _path_writer_lock(directory, verify=verify_state):
+                    descriptor, _, opened = _open_path_regular(
+                        directory, _LOG_NAME, lock=False, append=False, create=False
+                    )
+                    raw = _read_descriptor(descriptor)
+                    _verify_path_log(directory, descriptor, opened)
+                    _validate_existing_jsonl(raw)
+            finally:
+                if descriptor is not None:
+                    os.close(descriptor)
+    except FileNotFoundError:
+        return []
+    text = raw.decode("utf-8")
+    records: list[dict] = []
+    for line in text.split("\n"):
+        if not line.strip():
+            continue
+        record = json.loads(line, object_pairs_hook=_reject_duplicate_keys)
+        _validate_observation(record, persisted=True)
+        records.append(record)
+    return records
+
+
+def _flatten(value: str) -> str:
+    """One bounded line. A newline would break the record format and is the
+    simplest way to forge a second entry, so whitespace is collapsed."""
+    return re.sub(r"\s+", " ", _CONTROL.sub(" ", value)).strip()[:_TEXT_CEILING]
+
+
+def _reject_duplicate_keys(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    record = dict(pairs)
+    if len(record) != len(pairs):
+        raise ValueError("duplicate JSON object key")
+    return record
+
+
+def _validate_observation(observation: Any, *, persisted: bool = False) -> None:
+    if not isinstance(observation, dict):
+        raise SkillObserverError("OBSERVER_SHAPE_INVALID", "an observation must be an object")
+    allowed_fields = _PERSISTED_FIELDS if persisted else _ALLOWED_FIELDS
+    unknown = sorted((field for field in observation if field not in allowed_fields), key=str)
+    if unknown:
+        raise SkillObserverError("OBSERVER_FIELD_UNKNOWN", _UNKNOWN_FIELD_MESSAGE)
+    if persisted:
+        missing = [field for field in _PERSISTED_FIELDS if field not in observation]
+        if missing:
+            raise SkillObserverError(
+                "OBSERVER_FIELD_MISSING", "missing observation field: {0}".format(", ".join(missing))
+            )
+    if observation.get("signal") not in OBSERVER_SIGNALS:
+        raise SkillObserverError(
+            "OBSERVER_SIGNAL_UNKNOWN", "signal must be one of {0}".format(", ".join(OBSERVER_SIGNALS))
+        )
+    skill_id = observation.get("skill_id")
+    if not isinstance(skill_id, str) or _SKILL_ID.fullmatch(skill_id) is None:
+        raise SkillObserverError(
+            "OBSERVER_SKILL_ID_INVALID", "skill_id must be a lowercase skill identifier"
+        )
+    for field in ("observed", "proposal"):
+        value = observation.get(field)
+        if not isinstance(value, str) or not value.strip():
+            raise SkillObserverError("OBSERVER_TEXT_MISSING", f"{field} must be non-empty text")
+        # The ingress filter must not invalidate records after its pattern set widens.
+        if persisted:
+            _normalization_surfaces(value)
+        elif contains_secret(value):
+            # The offending value is never echoed: an error message is one more place
+            # a secret can land.
+            raise SkillObserverError(
+                "OBSERVER_SECRET_REFUSED",
+                f"{field} looks like it carries a credential and was refused before any write",
+            )
+        flattened = _flatten(value)
+        if not flattened:
+            raise SkillObserverError("OBSERVER_TEXT_MISSING", f"{field} must contain usable text")
+        if persisted and flattened != value:
+            raise SkillObserverError("OBSERVER_TEXT_NONCANONICAL", f"{field} is not canonical text")
+    if persisted and observation["applied"] is not False:
+        raise SkillObserverError("OBSERVER_APPLIED_INVALID", "applied must be the boolean false")
+
+
+def record_observation(root: str | os.PathLike[str], observation: Any) -> dict:
+    _validate_observation(observation)
+
+    record = {
+        "signal": observation["signal"],
+        "skill_id": observation["skill_id"],
+        "observed": _flatten(observation["observed"]),
+        "proposal": _flatten(observation["proposal"]),
+        "applied": False,
+    }
+    payload = (json.dumps(record, sort_keys=True) + "\n").encode("utf-8")
+    if len(payload) > MAX_LOG_BYTES:
+        raise SkillObserverError("OBSERVER_LOG_SIZE_EXCEEDED", "the new observation exceeds the log size limit")
+    if _uses_path_lock():
+        return _record_observation_path(root, record, payload)
+    committed = False
+    with _state_directory(root, create=True, committed=lambda: committed) as (
+        directory_fd,
+        verify_state,
+        workspace_fd,
+    ):
+        descriptor: int | None = None
+        opened: os.stat_result | None = None
+        created = False
+        prior_length = 0
+        write_attempted = False
+        primary_error: BaseException | None = None
+        try:
+            verify_state()
+            with _writer_lock(workspace_fd, verify=verify_state, committed=lambda: committed):
+                try:
+                    descriptor, created = _open_regular_at(
+                        directory_fd, _LOG_NAME, lock=False, append=True, create=True
+                    )
+                    opened_candidate = os.fstat(descriptor)
+                    _validate_regular(opened_candidate)
+                    opened = opened_candidate
+                    existing = _read_descriptor(descriptor)
+                    prior_length = len(existing)
+                    _verify_log_path(directory_fd, descriptor, opened)
+                    _validate_existing_jsonl(existing)
+                    separator = b"" if not existing or existing.endswith(b"\n") else b"\n"
+                    addition = separator + payload
+                    if len(existing) + len(addition) > MAX_LOG_BYTES:
+                        raise SkillObserverError(
+                            "OBSERVER_LOG_SIZE_EXCEEDED", "the new observation would exceed the log size limit"
+                        )
+                    verify_state()
+                    os.lseek(descriptor, 0, os.SEEK_END)
+                    write_attempted = True
+                    try:
+                        written = os.write(descriptor, addition)
+                    except OSError:
+                        raise SkillObserverError(
+                            "OBSERVER_LOG_WRITE_FAILED", "the observation record could not be written"
+                        ) from None
+                    if written != len(addition):
+                        raise SkillObserverError(
+                            "OBSERVER_LOG_WRITE_FAILED", "the observation record was not complete"
+                        )
+                    after = os.fstat(descriptor)
+                    _validate_regular(after)
+                    if after.st_size != len(existing) + len(addition):
+                        raise SkillObserverError("OBSERVER_LOG_CHANGED", "the observation log changed during write")
+                    _verify_log_path(directory_fd, descriptor, after)
+                    _sync_log(descriptor)
+                    synced = os.fstat(descriptor)
+                    _validate_regular(synced)
+                    if synced.st_size != len(existing) + len(addition):
+                        raise SkillObserverError("OBSERVER_LOG_CHANGED", "the observation log changed during write")
+                    _verify_log_path(directory_fd, descriptor, synced)
+                    verify_state()
+                    committed = True
+                except SkillObserverError as error:
+                    primary_error = error
+                    if not committed and descriptor is not None and opened is not None:
+                        try:
+                            _cleanup_log_failure(
+                                directory_fd,
+                                descriptor,
+                                opened,
+                                prior_length,
+                                created=created,
+                                write_attempted=write_attempted,
+                            )
+                        except SkillObserverError as cleanup_error:
+                            primary_error = cleanup_error
+                            raise
+                    raise
+                except KeyboardInterrupt as error:
+                    primary_error = error
+                    if descriptor is not None and opened is not None:
+                        try:
+                            _cleanup_log_failure(
+                                directory_fd,
+                                descriptor,
+                                opened,
+                                prior_length,
+                                created=created,
+                                write_attempted=write_attempted,
+                            )
+                        except SkillObserverError as cleanup_error:
+                            primary_error = cleanup_error
+                            raise
+                    raise
+                except OSError as error:
+                    primary_error = error
+                    if committed:
+                        raise _committed_cleanup_error() from None
+                    if not committed and descriptor is not None and opened is not None:
+                        try:
+                            _cleanup_log_failure(
+                                directory_fd,
+                                descriptor,
+                                opened,
+                                prior_length,
+                                created=created,
+                                write_attempted=write_attempted,
+                            )
+                        except SkillObserverError as cleanup_error:
+                            primary_error = cleanup_error
+                            raise
+                    raise SkillObserverError(
+                        "OBSERVER_LOG_WRITE_FAILED", "the observation log could not be written"
+                    ) from None
+        finally:
+            if descriptor is not None:
+                try:
+                    os.close(descriptor)
+                except OSError:
+                    if committed:
+                        raise _committed_cleanup_error() from None
+                    if _is_unknown_state(primary_error):
+                        raise primary_error
+                    raise
+    return record
+
+
+def read_observations(root: str | os.PathLike[str]) -> list[dict]:
+    if _uses_path_lock():
+        return _read_observations_path(root)
+    try:
+        with _state_directory(root, create=False) as (directory_fd, verify_state, workspace_fd):
+            descriptor: int | None = None
+            try:
+                verify_state()
+                with _writer_lock(workspace_fd, verify=verify_state):
+                    descriptor, _ = _open_regular_at(
+                        directory_fd, _LOG_NAME, lock=False, append=False, create=False
+                    )
+                    opened = os.fstat(descriptor)
+                    _validate_regular(opened)
+                    raw = _read_descriptor(descriptor)
+                    _verify_log_path(directory_fd, descriptor, opened)
+                    _validate_existing_jsonl(raw)
+            finally:
+                if descriptor is not None:
+                    os.close(descriptor)
+    except FileNotFoundError:
+        return []
+    text = raw.decode("utf-8")
+    records: list[dict] = []
+    for line in text.split("\n"):
+        if not line.strip():
+            continue
+        record = json.loads(line, object_pairs_hook=_reject_duplicate_keys)
+        _validate_observation(record, persisted=True)
+        records.append(record)
+    return records