@litfamily/lithermes 1.0.2 → 1.0.3

package/assets/lithermes-plugin/skill_loop.py

@@ -1,2044 +0,0 @@
-"""Approval-gated skill proposals for the LitHermes user skill root.
-
-This module never calls a model.  Review prints a bounded packet; ``propose``
-imports schema-shaped JSON; only the foreground ``apply`` command mutates an
-agent-owned skill under ``$HERMES_HOME/skills``.  The host curator remains the
-only curator and can be opted into explicitly with ``hermes curator adopt``.
-"""
-
-from __future__ import annotations
-
-import argparse
-import hashlib
-import json
-import os
-import re
-import shutil
-import stat
-import sys
-import tempfile
-import time
-import unicodedata
-import uuid
-from contextlib import contextmanager
-from datetime import datetime
-from pathlib import Path
-from typing import Any, Final
-
-try:
-    from .redaction import redact_text
-    from . import skill_observer
-except (ImportError, ModuleNotFoundError):
-    from redaction import redact_text
-    import skill_observer
-
-try:
-    import fcntl
-except ImportError:  # pragma: no cover - the supported Hermes runtime is POSIX
-    fcntl = None
-
-
-PROPOSAL_SCHEMA: Final = "litfamily.skill-proposal/v1"
-LEDGER_SCHEMA: Final = "litfamily.skill-ledger/v1"
-HOST: Final = "lithermes"
-MARKER: Final = "lithermesAgentGenerated"
-AUTO_APPLY: Final = False
-MAX_PROPOSAL_BYTES: Final = 1024 * 1024
-MAX_PROPOSAL_FILES: Final = 128
-MAX_PROPOSAL_QUEUE_BYTES: Final = 4 * 1024 * 1024
-MAX_SKILL_FILE_BYTES: Final = 4 * 1024 * 1024
-MAX_SKILL_TOTAL_BYTES: Final = 16 * 1024 * 1024
-MAX_REVIEW_PACKET_BYTES: Final = 64 * 1024
-MAX_REVIEW_LINES: Final = 20
-MAX_SESSIONS: Final = 64
-MAX_CONSULTED_SKILLS: Final = 8
-MAX_CORRECTIONS_PER_SESSION: Final = 3
-_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$")
-_SKILL_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
-_OBSERVED_SKILL_ID = re.compile(r"^[a-z][a-z0-9-]{0,63}$")
-_CONTROL = re.compile(r"[\x00-\x1f\x7f-\x9f]")
-_CORRECTION = re.compile(
-    r"(?:\bdon['’]?t\b|\bstop\b|\bdo not\b|\bnot that\b|"
-    r"하지\s*마|그만|왜\s*자꾸|아니라|말고|빼(?:줘|세요)|요약하지)",
-    re.IGNORECASE,
-)
-_RESERVED = re.compile(r"^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$", re.IGNORECASE)
-_PROPOSAL_FIELDS = {
-    "schema", "id", "createdAt", "host", "sessionRef", "signal", "targetSkill",
-    "targetRoot", "action", "patch", "createSpec", "rationale", "evidenceRefs",
-    "status", "ledgerEntryId",
-}
-_LEDGER_FIELDS = {
-    "schema", "id", "createdAt", "proposalId", "actor", "operation",
-    "targetSkill", "targetRoot", "before", "after", "restoresLedgerEntryId",
-    "reason",
-}
-_CONSULTED: dict[str, list[str]] = {}
-_CORRECTION_DIGESTS: dict[str, list[str]] = {}
-_PENDING_REVIEW: set[str] = set()
-
-
-class SkillLoopError(Exception):
-    def __init__(self, code: str, message: str) -> None:
-        super().__init__(message)
-        self.code = code
-
-
-def _fail(code: str, message: str) -> None:
-    raise SkillLoopError(code, message)
-
-
-def _hermes_home(value: str | os.PathLike[str] | None = None) -> Path:
-    raw = value or os.environ.get("HERMES_HOME")
-    if not raw:
-        raw = Path.home() / ".hermes"
-    path = Path(raw).expanduser()
-    try:
-        return path.resolve()
-    except (OSError, RuntimeError):
-        _fail("HERMES_HOME_UNSAFE", "the Hermes home cannot be resolved")
-
-
-def _workspace(value: str | os.PathLike[str] | None = None) -> Path:
-    path = Path(value or os.getcwd())
-    try:
-        resolved = path.resolve(strict=True)
-    except (OSError, RuntimeError):
-        _fail("WORKSPACE_UNSAFE", "the workspace cannot be resolved")
-    if not resolved.is_dir():
-        _fail("WORKSPACE_UNSAFE", "the workspace is not a directory")
-    return resolved
-
-
-def proposal_directory(workspace: str | os.PathLike[str] | None = None) -> Path:
-    current = _workspace(workspace)
-    for component in (".hermes", "lithermes", "skill-proposals"):
-        current = current / component
-        if current.is_symlink():
-            _fail("STATE_PATH_UNSAFE", "the workspace proposal path cannot contain symbolic links")
-        if current.exists() and not current.is_dir():
-            _fail("STATE_PATH_UNSAFE", "the workspace proposal path is not a directory")
-    return current
-
-
-def ledger_path(hermes_home: str | os.PathLike[str] | None = None) -> Path:
-    return _hermes_home(hermes_home) / "lithermes" / "skill-loop-ledger.jsonl"
-
-
-def blob_directory(hermes_home: str | os.PathLike[str] | None = None) -> Path:
-    return _hermes_home(hermes_home) / "lithermes" / "skill-loop-blobs"
-
-
-def skills_root(hermes_home: str | os.PathLike[str] | None = None) -> Path:
-    return _hermes_home(hermes_home) / "skills"
-
-
-def _state_root(hermes_home: str | os.PathLike[str] | None = None) -> Path:
-    return _hermes_home(hermes_home) / "lithermes"
-
-
-def _transaction_path(hermes_home: str | os.PathLike[str] | None = None) -> Path:
-    return _state_root(hermes_home) / "skill-loop-transaction.json"
-
-
-def _set_private_directory(path: Path) -> None:
-    path.mkdir(parents=True, exist_ok=True, mode=0o700)
-    if path.is_symlink() or not path.is_dir():
-        _fail("STATE_PATH_UNSAFE", "a skill-loop state path is not a directory")
-    try:
-        path.chmod(0o700)
-    except OSError:
-        _fail("STATE_PATH_UNSAFE", "a skill-loop state directory is not private")
-
-
-def _ensure_user_skill_root(path: Path) -> None:
-    """Create the user skill root, but do not rewrite an existing host mode."""
-    if path.is_symlink():
-        _fail("TARGET_PATH_UNSAFE", "the Hermes user skill root cannot be a symbolic link")
-    if path.exists():
-        if not path.is_dir():
-            _fail("TARGET_PATH_UNSAFE", "the Hermes user skill root is not a directory")
-        return
-    try:
-        path.mkdir(parents=True, mode=0o700)
-    except FileExistsError:
-        if path.is_symlink() or not path.is_dir():
-            _fail("TARGET_PATH_UNSAFE", "the Hermes user skill root changed during validation")
-    except OSError:
-        _fail("TARGET_PATH_UNSAFE", "the Hermes user skill root could not be created")
-
-
-def _atomic_write(path: Path, data: bytes, *, mode: int = 0o600) -> None:
-    _set_private_directory(path.parent)
-    if path.exists() and (path.is_symlink() or not path.is_file()):
-        _fail("STATE_PATH_UNSAFE", "a skill-loop state file is not regular")
-    descriptor, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
-    temp_path = Path(temporary)
-    try:
-        os.fchmod(descriptor, mode)
-        with os.fdopen(descriptor, "wb", closefd=True) as stream:
-            stream.write(data)
-            stream.flush()
-            os.fsync(stream.fileno())
-        os.replace(temp_path, path)
-        directory_fd = os.open(path.parent, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
-        try:
-            os.fsync(directory_fd)
-        finally:
-            os.close(directory_fd)
-    finally:
-        if temp_path.exists():
-            temp_path.unlink()
-
-
-def _json_bytes(record: Any) -> bytes:
-    return (json.dumps(record, sort_keys=True, separators=(",", ":")) + "\n").encode("utf-8")
-
-
-def _reject_duplicate_keys(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
-    result: dict[str, Any] = {}
-    for key, value in pairs:
-        if key in result:
-            raise ValueError("duplicate JSON key")
-        result[key] = value
-    return result
-
-
-def _read_json_file(path: Path, *, maximum: int = MAX_PROPOSAL_BYTES) -> Any:
-    try:
-        value = path.lstat()
-        if stat.S_ISLNK(value.st_mode) or not stat.S_ISREG(value.st_mode) or value.st_nlink != 1:
-            _fail("STATE_PATH_UNSAFE", "the JSON input is not a regular single-link file")
-        if value.st_size > maximum:
-            _fail("PROPOSAL_TOO_LARGE", "the JSON input exceeds the size limit")
-        raw = path.read_bytes()
-        text = raw.decode("utf-8")
-        return json.loads(text, object_pairs_hook=_reject_duplicate_keys)
-    except SkillLoopError:
-        raise
-    except (OSError, UnicodeDecodeError, json.JSONDecodeError, ValueError):
-        _fail("PROPOSAL_SCHEMA_INVALID", "the JSON input is malformed")
-
-
-def _strict_timestamp(value: Any) -> bool:
-    if not isinstance(value, str) or not value or len(value) > 64:
-        return False
-    if re.fullmatch(
-        r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}"
-        r"(?:\.[0-9]+)?(?:Z|[+-][0-9]{2}:[0-9]{2})",
-        value,
-    ) is None:
-        return False
-    try:
-        datetime.fromisoformat(value.replace("Z", "+00:00"))
-    except ValueError:
-        return False
-    return True
-
-
-def _canonical_component(value: str) -> str:
-    return unicodedata.normalize("NFKC", value).casefold().rstrip(". ")
-
-
-def _portable_skill_identity(value: str, *, code: str, message: str) -> str:
-    identity = _canonical_component(value)
-    stem = value.split(".", 1)[0]
-    if (
-        not identity
-        or identity != unicodedata.normalize("NFKC", value).casefold()
-        or _RESERVED.fullmatch(stem) is not None
-    ):
-        _fail(code, message)
-    return identity
-
-
-def _validate_relative_file(value: Any, target_skill: str) -> str:
-    if not isinstance(value, str) or not value or len(value) > 1024:
-        _fail("PROPOSAL_PATH_INVALID", "proposal files must be bounded relative paths")
-    if value.startswith(('/', '\\')) or re.match(r"^[A-Za-z]:", value):
-        _fail("PROPOSAL_PATH_INVALID", "proposal files must be relative")
-    if "\\" in value or _CONTROL.search(value) or any(c in value for c in ':*?"<>|'):
-        _fail("PROPOSAL_PATH_INVALID", "proposal files must use portable path characters")
-    parts = value.split("/")
-    if any(not part or part in {".", ".."} or part.endswith((".", " ")) for part in parts):
-        _fail("PROPOSAL_PATH_INVALID", "proposal files contain an unsafe segment")
-    for part in parts:
-        stem = part.split(".", 1)[0]
-        if _RESERVED.fullmatch(stem):
-            _fail("PROPOSAL_PATH_INVALID", "proposal files contain a reserved basename")
-    identity = "/".join(_canonical_component(part) for part in parts)
-    target_identity = _canonical_component(target_skill)
-    if identity == target_identity or identity.startswith(f"{target_identity}/"):
-        _fail("PROPOSAL_PATH_INVALID", "proposal files are relative to the selected skill")
-    return value
-
-
-def _secret_in(value: Any) -> bool:
-    if isinstance(value, str):
-        try:
-            return skill_observer.contains_secret(value)
-        except skill_observer.SkillObserverError:
-            return True
-    if isinstance(value, list):
-        return any(_secret_in(item) for item in value)
-    if isinstance(value, dict):
-        return any(_secret_in(key) or _secret_in(item) for key, item in value.items())
-    return False
-
-
-def validate_proposal(record: Any) -> dict[str, Any]:
-    if not isinstance(record, dict) or set(record) - _PROPOSAL_FIELDS:
-        _fail("PROPOSAL_SCHEMA_INVALID", "proposal fields do not match version 1")
-    required = {
-        "schema", "id", "createdAt", "host", "sessionRef", "signal", "targetSkill",
-        "targetRoot", "action", "rationale", "evidenceRefs", "status",
-    }
-    if not required.issubset(record):
-        _fail("PROPOSAL_SCHEMA_INVALID", "proposal required fields are missing")
-    if record["schema"] != PROPOSAL_SCHEMA or record["host"] != HOST:
-        _fail("PROPOSAL_SCHEMA_INVALID", "proposal schema or host is invalid")
-    if not isinstance(record["id"], str) or _ID.fullmatch(record["id"]) is None:
-        _fail("PROPOSAL_SCHEMA_INVALID", "proposal id is invalid")
-    if not _strict_timestamp(record["createdAt"]):
-        _fail("PROPOSAL_SCHEMA_INVALID", "proposal timestamp is invalid")
-    if not isinstance(record["sessionRef"], str) or not 1 <= len(record["sessionRef"]) <= 512:
-        _fail("PROPOSAL_SCHEMA_INVALID", "proposal session reference is invalid")
-    if not isinstance(record["signal"], str) or not 1 <= len(record["signal"]) <= 128:
-        _fail("PROPOSAL_SCHEMA_INVALID", "proposal signal is invalid")
-    target = record["targetSkill"]
-    if not isinstance(target, str) or _SKILL_ID.fullmatch(target) is None:
-        _fail("PROPOSAL_SCHEMA_INVALID", "proposal target skill is invalid")
-    _portable_skill_identity(
-        target,
-        code="PROPOSAL_PATH_INVALID",
-        message="proposal target skill is not a portable name",
-    )
-    if not isinstance(record["targetRoot"], str) or not 1 <= len(record["targetRoot"]) <= 2048:
-        _fail("PROPOSAL_SCHEMA_INVALID", "proposal target root is invalid")
-    if not isinstance(record["rationale"], str) or not 1 <= len(record["rationale"]) <= 8192:
-        _fail("PROPOSAL_SCHEMA_INVALID", "proposal rationale is invalid")
-    refs = record["evidenceRefs"]
-    if (
-        not isinstance(refs, list) or len(refs) > 32 or len(set(map(str, refs))) != len(refs)
-        or any(not isinstance(item, str) or not 1 <= len(item) <= 2048 for item in refs)
-    ):
-        _fail("PROPOSAL_SCHEMA_INVALID", "proposal evidence references are invalid")
-    if record["status"] not in {"pending", "approved", "applied", "rejected", "rolled-back"}:
-        _fail("PROPOSAL_SCHEMA_INVALID", "proposal status is invalid")
-    if record["status"] in {"applied", "rolled-back"}:
-        if not isinstance(record.get("ledgerEntryId"), str) or not record["ledgerEntryId"]:
-            _fail("PROPOSAL_SCHEMA_INVALID", "a terminal proposal requires a ledger entry")
-    elif "ledgerEntryId" in record:
-        _fail("PROPOSAL_SCHEMA_INVALID", "a non-terminal proposal cannot name a ledger entry")
-
-    action = record["action"]
-    if action not in {"patch", "create", "add-reference", "archive"}:
-        _fail("PROPOSAL_SCHEMA_INVALID", "proposal action is invalid")
-    if action == "patch":
-        if "createSpec" in record or not isinstance(record.get("patch"), dict):
-            _fail("PROPOSAL_SCHEMA_INVALID", "patch proposal content is invalid")
-        patch = record["patch"]
-        if set(patch) != {"file", "oldString", "newString"}:
-            _fail("PROPOSAL_SCHEMA_INVALID", "patch proposal fields are invalid")
-        _validate_relative_file(patch["file"], target)
-        if (
-            not isinstance(patch["oldString"], str) or not patch["oldString"]
-            or len(patch["oldString"]) > 65536
-            or not isinstance(patch["newString"], str) or len(patch["newString"]) > 65536
-        ):
-            _fail("PROPOSAL_SCHEMA_INVALID", "patch strings are invalid")
-    elif action in {"create", "add-reference"}:
-        if "patch" in record or not isinstance(record.get("createSpec"), dict):
-            _fail("PROPOSAL_SCHEMA_INVALID", "create proposal content is invalid")
-        spec = record["createSpec"]
-        if set(spec) != {"files"} or not isinstance(spec["files"], list) or not 1 <= len(spec["files"]) <= 64:
-            _fail("PROPOSAL_SCHEMA_INVALID", "create proposal files are invalid")
-        identities: set[str] = set()
-        total = 0
-        for item in spec["files"]:
-            if not isinstance(item, dict) or set(item) != {"file", "content"}:
-                _fail("PROPOSAL_SCHEMA_INVALID", "create proposal file fields are invalid")
-            file = _validate_relative_file(item["file"], target)
-            identity = "/".join(_canonical_component(part) for part in file.split("/"))
-            if identity in identities:
-                _fail("PROPOSAL_PATH_INVALID", "create proposal paths are aliases")
-            identities.add(identity)
-            if not isinstance(item["content"], str) or len(item["content"]) > 65536:
-                _fail("PROPOSAL_SCHEMA_INVALID", "create proposal file content is invalid")
-            total += len(item["content"].encode("utf-8"))
-        if total > MAX_SKILL_TOTAL_BYTES:
-            _fail("PROPOSAL_TOO_LARGE", "proposal content exceeds the total limit")
-    elif "patch" in record or "createSpec" in record:
-        _fail("PROPOSAL_SCHEMA_INVALID", "archive proposals carry no content")
-    if _secret_in(record):
-        _fail("PROPOSAL_SECRET_REFUSED", "credential-shaped proposal text was refused")
-    return record
-
-
-def _proposal_path(proposal_id: str, workspace: str | os.PathLike[str] | None = None) -> Path:
-    if _ID.fullmatch(str(proposal_id)) is None:
-        _fail("PROPOSAL_ID_INVALID", "proposal id is invalid")
-    return proposal_directory(workspace) / f"{proposal_id}.json"
-
-
-def _validate_terminal_proposal_receipt(
-    record: dict[str, Any],
-    hermes_home: str | os.PathLike[str] | None,
-) -> None:
-    expected_operation = {"applied": "apply", "rolled-back": "rollback"}.get(record["status"])
-    if expected_operation is None:
-        return
-    receipt = next(
-        (
-            entry
-            for entry in read_ledger(hermes_home=hermes_home)
-            if entry["id"] == record["ledgerEntryId"]
-        ),
-        None,
-    )
-    if receipt is None:
-        _fail("PROPOSAL_LEDGER_MISMATCH", "the terminal proposal ledger receipt is unavailable")
-    proposal_target = _canonical_ledger_target(
-        record,
-        code="PROPOSAL_LEDGER_MISMATCH",
-        message="the terminal proposal target is not canonical",
-    )
-    receipt_target = _canonical_ledger_target(
-        receipt,
-        code="PROPOSAL_LEDGER_MISMATCH",
-        message="the terminal proposal ledger target is not canonical",
-    )
-    if (
-        receipt["operation"] != expected_operation
-        or receipt["proposalId"] != record["id"]
-        or receipt_target != proposal_target
-    ):
-        _fail("PROPOSAL_LEDGER_MISMATCH", "the terminal proposal does not match its ledger receipt")
-
-
-def _write_proposal(
-    record: dict[str, Any],
-    workspace: str | os.PathLike[str] | None = None,
-    hermes_home: str | os.PathLike[str] | None = None,
-) -> None:
-    validate_proposal(record)
-    _validate_terminal_proposal_receipt(record, hermes_home)
-    _atomic_write(_proposal_path(record["id"], workspace), _json_bytes(record))
-
-
-def load_proposal(
-    proposal_id: str,
-    workspace: str | os.PathLike[str] | None = None,
-    hermes_home: str | os.PathLike[str] | None = None,
-) -> dict[str, Any]:
-    path = _proposal_path(proposal_id, workspace)
-    if not path.exists():
-        _fail("PROPOSAL_NOT_FOUND", "the proposal does not exist in this workspace")
-    record = _read_json_file(path)
-    validate_proposal(record)
-    _validate_terminal_proposal_receipt(record, hermes_home)
-    return record
-
-
-def propose(
-    file: str | os.PathLike[str], *, workspace: str | os.PathLike[str] | None = None,
-    hermes_home: str | os.PathLike[str] | None = None,
-) -> dict[str, Any]:
-    # targetRoot stays untrusted data until foreground apply.
-    record = validate_proposal(_read_json_file(Path(file).expanduser()))
-    if record["status"] != "pending":
-        _fail("PROPOSAL_STATUS_INVALID", "imported proposals must be pending")
-    destination = _proposal_path(record["id"], workspace)
-    if destination.exists():
-        _fail("PROPOSAL_EXISTS", "a proposal with this id already exists")
-    _write_proposal(record, workspace, hermes_home)
-    return {"ok": True, "id": record["id"]}
-
-
-def list_proposals(
-    *, workspace: str | os.PathLike[str] | None = None,
-    hermes_home: str | os.PathLike[str] | None = None,
-) -> list[dict[str, Any]]:
-    directory = proposal_directory(workspace)
-    if not directory.exists():
-        return []
-    if directory.is_symlink() or not directory.is_dir():
-        _fail("STATE_PATH_UNSAFE", "the proposal queue is not a directory")
-    paths: list[Path] = []
-    aggregate = 0
-    try:
-        with os.scandir(directory) as entries:
-            for item in entries:
-                if len(paths) >= MAX_PROPOSAL_FILES:
-                    _fail("PROPOSAL_QUEUE_TOO_LARGE", "the proposal queue exceeds the file-count limit")
-                if not item.name.endswith(".json"):
-                    _fail("STATE_PATH_UNSAFE", "the proposal queue contains an unexpected entry")
-                value = item.stat(follow_symlinks=False)
-                if stat.S_ISLNK(value.st_mode) or not stat.S_ISREG(value.st_mode) or value.st_nlink != 1:
-                    _fail("STATE_PATH_UNSAFE", "a queued proposal is not a regular single-link file")
-                aggregate += value.st_size
-                if aggregate > MAX_PROPOSAL_QUEUE_BYTES:
-                    _fail("PROPOSAL_QUEUE_TOO_LARGE", "the proposal queue exceeds the aggregate byte limit")
-                paths.append(Path(item.path))
-    except SkillLoopError:
-        raise
-    except OSError:
-        _fail("STATE_PATH_UNSAFE", "the proposal queue cannot be inspected")
-    paths.sort()
-    records: list[dict[str, Any]] = []
-    for path in paths:
-        record = validate_proposal(_read_json_file(path))
-        _validate_terminal_proposal_receipt(record, hermes_home)
-        records.append(record)
-    return records
-
-
-def _private_ledger_bytes(path: Path) -> bytes:
-    if not path.exists():
-        return b""
-    try:
-        value = path.lstat()
-        if (
-            stat.S_ISLNK(value.st_mode)
-            or not stat.S_ISREG(value.st_mode)
-            or value.st_nlink != 1
-            or value.st_mode & 0o077
-        ):
-            _fail("LEDGER_MALFORMED", "the decision ledger path is unsafe")
-        raw = path.read_bytes()
-    except SkillLoopError:
-        raise
-    except OSError:
-        _fail("LEDGER_MALFORMED", "the decision ledger could not be read safely")
-    if len(raw) > 8 * 1024 * 1024:
-        _fail("LEDGER_MALFORMED", "the decision ledger exceeds the size limit")
-    return raw
-
-
-def _parse_ledger_bytes(
-    raw: bytes,
-    hermes_home: str | os.PathLike[str] | None,
-) -> list[dict[str, Any]]:
-    try:
-        records = [
-            json.loads(line, object_pairs_hook=_reject_duplicate_keys)
-            for line in raw.decode("utf-8").splitlines()
-            if line.strip()
-        ]
-    except (UnicodeDecodeError, json.JSONDecodeError, ValueError):
-        _fail("LEDGER_MALFORMED", "the decision ledger is malformed")
-    seen: set[str] = set()
-    for record in records:
-        validate_ledger_entry(record)
-        identifier = record.get("id")
-        if not isinstance(identifier, str) or identifier in seen:
-            _fail("LEDGER_MALFORMED", "the decision ledger contains a duplicate id")
-        seen.add(identifier)
-    _validate_ledger_integrity(records, hermes_home)
-    return records
-
-
-def _append_jsonl(
-    path: Path,
-    record: dict[str, Any],
-    hermes_home: str | os.PathLike[str] | None = None,
-) -> None:
-    validate_ledger_entry(record)
-    payload = _json_bytes(record)
-    home = hermes_home if hermes_home is not None else path.parent.parent
-    try:
-        existing = _private_ledger_bytes(path)
-        if existing and not existing.endswith(b"\n"):
-            _fail("LEDGER_MALFORMED", "the decision ledger has an incomplete tail")
-        records = _parse_ledger_bytes(existing, home)
-        if any(item["id"] == record["id"] for item in records):
-            _fail("LEDGER_MALFORMED", "the decision ledger contains a duplicate id")
-        _validate_ledger_integrity([*records, record], home)
-        combined = existing + payload
-        if len(combined) > 8 * 1024 * 1024:
-            _fail("LEDGER_WRITE_FAILED", "the decision ledger exceeds the size limit")
-        _atomic_write(path, combined)
-    except SkillLoopError as error:
-        if error.code in {"LEDGER_MALFORMED", "BLOB_MISSING", "BLOB_STORE_CORRUPT"}:
-            raise
-        _fail("LEDGER_WRITE_FAILED", "the decision ledger could not be replaced atomically")
-    except OSError:
-        _fail("LEDGER_WRITE_FAILED", "the decision ledger could not be replaced atomically")
-
-
-def _validate_snapshot(value: Any) -> list[dict[str, Any]]:
-    if not isinstance(value, list) or len(value) > 256:
-        _fail("LEDGER_MALFORMED", "a decision ledger snapshot is invalid")
-    identities: set[str] = set()
-    for item in value:
-        if not isinstance(item, dict) or set(item) != {"file", "blob"}:
-            _fail("LEDGER_MALFORMED", "a decision ledger snapshot item is invalid")
-        try:
-            file = _validate_relative_file(item.get("file"), "ledger-snapshot")
-        except SkillLoopError:
-            _fail("LEDGER_MALFORMED", "a decision ledger snapshot path is invalid")
-        identity = "/".join(_canonical_component(part) for part in file.split("/"))
-        if identity in identities:
-            _fail("LEDGER_MALFORMED", "a decision ledger snapshot contains path aliases")
-        identities.add(identity)
-        blob = item.get("blob")
-        if (
-            not isinstance(blob, dict)
-            or set(blob) != {"algorithm", "digest", "size"}
-            or blob.get("algorithm") != "sha256"
-            or not isinstance(blob.get("digest"), str)
-            or re.fullmatch(r"[a-f0-9]{64}", blob["digest"]) is None
-            or not isinstance(blob.get("size"), int)
-            or isinstance(blob.get("size"), bool)
-            or blob["size"] < 0
-        ):
-            _fail("LEDGER_MALFORMED", "a decision ledger blob record is invalid")
-    return value
-
-
-def validate_ledger_entry(record: Any) -> dict[str, Any]:
-    if not isinstance(record, dict) or set(record) - _LEDGER_FIELDS:
-        _fail("LEDGER_MALFORMED", "a decision ledger record has unknown fields")
-    required = {
-        "schema", "id", "createdAt", "proposalId", "actor", "operation",
-        "targetSkill", "targetRoot", "before", "after",
-    }
-    if not required.issubset(record) or record.get("schema") != LEDGER_SCHEMA:
-        _fail("LEDGER_MALFORMED", "a decision ledger record is missing required fields")
-    if not isinstance(record.get("id"), str) or _ID.fullmatch(record["id"]) is None:
-        _fail("LEDGER_MALFORMED", "a decision ledger id is invalid")
-    if not _strict_timestamp(record.get("createdAt")):
-        _fail("LEDGER_MALFORMED", "a decision ledger timestamp is invalid")
-    proposal_id = record.get("proposalId")
-    if proposal_id is not None and (
-        not isinstance(proposal_id, str) or not 1 <= len(proposal_id) <= 128
-    ):
-        _fail("LEDGER_MALFORMED", "a decision ledger proposal id is invalid")
-    if record.get("actor") not in {"user", "curator"}:
-        _fail("LEDGER_MALFORMED", "a decision ledger actor is invalid")
-    operation = record.get("operation")
-    if operation not in {"apply", "reject", "rollback", "curator-transition"}:
-        _fail("LEDGER_MALFORMED", "a decision ledger operation is invalid")
-    if not isinstance(record.get("targetSkill"), str) or _SKILL_ID.fullmatch(record["targetSkill"]) is None:
-        _fail("LEDGER_MALFORMED", "a decision ledger target skill is invalid")
-    if not isinstance(record.get("targetRoot"), str) or not 1 <= len(record["targetRoot"]) <= 2048:
-        _fail("LEDGER_MALFORMED", "a decision ledger target root is invalid")
-    _validate_snapshot(record.get("before"))
-    _validate_snapshot(record.get("after"))
-    reason = record.get("reason")
-    if reason is not None and (not isinstance(reason, str) or len(reason) > 8192):
-        _fail("LEDGER_MALFORMED", "a decision ledger reason is invalid")
-    restores = record.get("restoresLedgerEntryId")
-    if operation == "rollback":
-        if not isinstance(restores, str) or not 1 <= len(restores) <= 128:
-            _fail("LEDGER_MALFORMED", "a rollback ledger record lacks its restored entry id")
-    elif restores is not None:
-        _fail("LEDGER_MALFORMED", "a non-rollback ledger record names a restored entry")
-    if operation in {"apply", "reject"} and (
-        record.get("actor") != "user" or not isinstance(proposal_id, str)
-    ):
-        _fail("LEDGER_MALFORMED", "an apply or reject ledger record has invalid authority")
-    if operation == "rollback" and record.get("actor") != "user":
-        _fail("LEDGER_MALFORMED", "a rollback ledger record has invalid authority")
-    if operation == "curator-transition" and (
-        record.get("actor") != "curator" or proposal_id is not None
-    ):
-        _fail("LEDGER_MALFORMED", "a curator ledger record has invalid authority")
-    return record
-
-
-def _canonical_ledger_target(
-    record: dict[str, Any],
-    *,
-    code: str = "LEDGER_MALFORMED",
-    message: str = "a decision ledger target is not canonical",
-) -> tuple[str, str]:
-    target_skill = record.get("targetSkill")
-    target_root = record.get("targetRoot")
-    if not isinstance(target_skill, str) or not isinstance(target_root, str):
-        _fail(code, message)
-    skill_identity = _portable_skill_identity(target_skill, code=code, message=message)
-    try:
-        root = Path(target_root)
-        if not root.is_absolute():
-            _fail(code, message)
-        root_identity = str(root.resolve(strict=False))
-    except (OSError, RuntimeError, ValueError):
-        _fail(code, message)
-    return skill_identity, root_identity
-
-
-def read_ledger(*, hermes_home: str | os.PathLike[str] | None = None) -> list[dict[str, Any]]:
-    path = ledger_path(hermes_home)
-    if not path.exists():
-        return []
-    raw = _private_ledger_bytes(path)
-    if raw and not raw.endswith(b"\n"):
-        _fail("LEDGER_MALFORMED", "the decision ledger has an incomplete tail")
-    return _parse_ledger_bytes(raw, hermes_home)
-
-
-def _blob_record(data: bytes, hermes_home: str | os.PathLike[str] | None) -> dict[str, Any]:
-    digest = hashlib.sha256(data).hexdigest()
-    directory = blob_directory(hermes_home)
-    _set_private_directory(directory)
-    path = directory / digest
-    if path.exists():
-        if path.is_symlink() or not path.is_file() or path.read_bytes() != data:
-            _fail("BLOB_STORE_CORRUPT", "a content-addressed blob does not match its name")
-    else:
-        _atomic_write(path, data)
-    return {"algorithm": "sha256", "digest": digest, "size": len(data)}
-
-
-def _snapshot(
-    target: Path,
-    hermes_home: str | os.PathLike[str] | None,
-    *,
-    persist_blobs: bool = True,
-) -> list[dict[str, Any]]:
-    if not target.exists():
-        return []
-    if target.is_symlink() or not target.is_dir():
-        _fail("TARGET_PATH_UNSAFE", "the skill target is not a directory")
-    records: list[dict[str, Any]] = []
-    total = 0
-    for path in sorted(target.rglob("*")):
-        value = path.lstat()
-        if stat.S_ISLNK(value.st_mode):
-            _fail("TARGET_PATH_UNSAFE", "skill packages cannot contain symbolic links")
-        if path.is_dir():
-            continue
-        if not stat.S_ISREG(value.st_mode) or value.st_nlink != 1 or value.st_size > MAX_SKILL_FILE_BYTES:
-            _fail("TARGET_PATH_UNSAFE", "skill packages must contain bounded regular files")
-        relative = path.relative_to(target).as_posix()
-        _validate_relative_file(relative, target.name)
-        data = path.read_bytes()
-        total += len(data)
-        if total > MAX_SKILL_TOTAL_BYTES or len(records) >= 256:
-            _fail("TARGET_TOO_LARGE", "the skill package exceeds the snapshot limit")
-        blob = (
-            _blob_record(data, hermes_home)
-            if persist_blobs
-            else {
-                "algorithm": "sha256",
-                "digest": hashlib.sha256(data).hexdigest(),
-                "size": len(data),
-            }
-        )
-        records.append({"file": relative, "blob": blob})
-    return records
-
-
-def _snapshot_identity(snapshot: list[dict[str, Any]]) -> list[tuple[str, str, int]]:
-    return sorted((item["file"], item["blob"]["digest"], item["blob"]["size"]) for item in snapshot)
-
-
-def _path_matches_snapshot(
-    path: Path,
-    expected: Any,
-    hermes_home: str | os.PathLike[str] | None,
-) -> bool:
-    snapshot = _validate_snapshot(expected)
-    present = path.exists() or path.is_symlink()
-    if not snapshot:
-        return not present
-    if not present:
-        return False
-    try:
-        current = _snapshot(path, hermes_home, persist_blobs=False)
-    except SkillLoopError:
-        return False
-    return _snapshot_identity(current) == _snapshot_identity(snapshot)
-
-
-def _blob_bytes(record: dict[str, Any], hermes_home: str | os.PathLike[str] | None) -> bytes:
-    try:
-        digest = record["digest"]
-        size = record["size"]
-    except (KeyError, TypeError):
-        _fail("BLOB_STORE_CORRUPT", "a ledger blob record is malformed")
-    if not isinstance(digest, str) or not re.fullmatch(r"[a-f0-9]{64}", digest) or not isinstance(size, int):
-        _fail("BLOB_STORE_CORRUPT", "a ledger blob record is malformed")
-    path = blob_directory(hermes_home) / digest
-    try:
-        value = path.lstat()
-        if (
-            stat.S_ISLNK(value.st_mode)
-            or not stat.S_ISREG(value.st_mode)
-            or value.st_nlink != 1
-            or value.st_mode & 0o077
-        ):
-            raise OSError
-        data = path.read_bytes()
-    except OSError:
-        _fail("BLOB_MISSING", "a rollback blob is unavailable")
-    if len(data) != size or hashlib.sha256(data).hexdigest() != digest:
-        _fail("BLOB_STORE_CORRUPT", "a rollback blob failed verification")
-    return data
-
-
-def _validate_snapshot_blobs(
-    snapshot: Any,
-    hermes_home: str | os.PathLike[str] | None,
-    verified: set[tuple[str, int]] | None = None,
-) -> list[dict[str, Any]]:
-    records = _validate_snapshot(snapshot)
-    cache = verified if verified is not None else set()
-    for item in records:
-        blob = item["blob"]
-        identity = (blob["digest"], blob["size"])
-        if identity in cache:
-            continue
-        _blob_bytes(blob, hermes_home)
-        cache.add(identity)
-    return records
-
-
-def _validate_ledger_integrity(
-    records: list[dict[str, Any]],
-    hermes_home: str | os.PathLike[str] | None,
-) -> None:
-    by_id = {record["id"]: record for record in records}
-    positions = {record["id"]: index for index, record in enumerate(records)}
-    edges: dict[str, str] = {}
-    for record in records:
-        if record["operation"] != "rollback":
-            continue
-        target = record["restoresLedgerEntryId"]
-        if target not in by_id:
-            _fail("LEDGER_MALFORMED", "a rollback ledger reference is missing")
-        edges[record["id"]] = target
-
-    visited: set[str] = set()
-    for identifier in edges:
-        chain: set[str] = set()
-        current = identifier
-        while current in edges and current not in visited:
-            if current in chain:
-                _fail("LEDGER_MALFORMED", "the decision ledger contains a rollback reference cycle")
-            chain.add(current)
-            current = edges[current]
-        visited.update(chain)
-
-    for identifier, target in edges.items():
-        referenced = by_id[target]
-        rollback = by_id[identifier]
-        if (
-            referenced["operation"] not in {"apply", "curator-transition", "rollback"}
-            or positions[target] >= positions[identifier]
-        ):
-            _fail("LEDGER_MALFORMED", "a rollback must restore an earlier mutation entry")
-        if _canonical_ledger_target(rollback) != _canonical_ledger_target(referenced):
-            _fail("LEDGER_MALFORMED", "a rollback reference does not match its canonical target")
-        if rollback["proposalId"] != referenced["proposalId"]:
-            _fail("LEDGER_MALFORMED", "a rollback reference does not match mutation authority")
-        if (
-            _snapshot_identity(rollback["before"])
-            != _snapshot_identity(referenced["after"])
-            or _snapshot_identity(rollback["after"])
-            != _snapshot_identity(referenced["before"])
-        ):
-            _fail("LEDGER_MALFORMED", "a rollback reference is not the exact snapshot inverse")
-
-    verified: set[tuple[str, int]] = set()
-    for record in records:
-        _validate_snapshot_blobs(record["before"], hermes_home, verified)
-        _validate_snapshot_blobs(record["after"], hermes_home, verified)
-
-
-def _copy_skill(source: Path, destination: Path) -> None:
-    destination.mkdir(mode=0o700)
-    for path in sorted(source.rglob("*")):
-        relative = path.relative_to(source)
-        value = path.lstat()
-        if stat.S_ISLNK(value.st_mode):
-            _fail("TARGET_PATH_UNSAFE", "skill packages cannot contain symbolic links")
-        target = destination / relative
-        if path.is_dir():
-            target.mkdir(mode=0o700)
-        elif stat.S_ISREG(value.st_mode) and value.st_nlink == 1:
-            target.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
-            target.write_bytes(path.read_bytes())
-            target.chmod(0o600)
-        else:
-            _fail("TARGET_PATH_UNSAFE", "skill packages must contain regular files")
-
-
-def _restore_snapshot(snapshot: list[dict[str, Any]], destination: Path, hermes_home: str | os.PathLike[str] | None) -> None:
-    _validate_snapshot_blobs(snapshot, hermes_home)
-    destination.mkdir(mode=0o700)
-    identities: set[str] = set()
-    for item in snapshot:
-        file = _validate_relative_file(item.get("file"), destination.name)
-        identity = "/".join(_canonical_component(part) for part in file.split("/"))
-        if identity in identities:
-            _fail("LEDGER_MALFORMED", "a ledger snapshot contains path aliases")
-        identities.add(identity)
-        target = destination.joinpath(*file.split("/"))
-        target.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
-        target.write_bytes(_blob_bytes(item.get("blob"), hermes_home))
-        target.chmod(0o600)
-
-
-def _frontmatter_text(text: str) -> str | None:
-    if not text.startswith("---\n"):
-        return None
-    end = text.find("\n---", 4)
-    if end < 0:
-        return None
-    return text[4:end]
-
-
-def _yaml_mapping_line(line: str) -> tuple[int, str, str] | None:
-    if "\t" in line:
-        return None
-    indent = len(line) - len(line.lstrip(" "))
-    content = line[indent:]
-    if not content or content.startswith("#"):
-        return None
-    if content[0] == '"':
-        escaped = False
-        close = -1
-        for index, character in enumerate(content[1:], 1):
-            if escaped:
-                escaped = False
-            elif character == "\\":
-                escaped = True
-            elif character == '"':
-                close = index
-                break
-        if close < 0:
-            return None
-        try:
-            key = json.loads(content[: close + 1])
-        except (json.JSONDecodeError, ValueError):
-            return None
-        suffix = content[close + 1 :].lstrip(" ")
-    elif content[0] == "'":
-        index = 1
-        decoded: list[str] = []
-        while index < len(content):
-            if content[index] != "'":
-                decoded.append(content[index])
-                index += 1
-                continue
-            if index + 1 < len(content) and content[index + 1] == "'":
-                decoded.append("'")
-                index += 2
-                continue
-            break
-        else:
-            return None
-        key = "".join(decoded)
-        suffix = content[index + 1 :].lstrip(" ")
-    else:
-        match = re.search(r":(?=\s|$)", content)
-        if match is None:
-            return None
-        key = content[: match.start()].strip()
-        suffix = content[match.start() :]
-        if not key or key[0] in "?-{}[]!&*#|>@`":
-            return None
-    if not isinstance(key, str) or not suffix.startswith(":"):
-        return None
-    return indent, key, suffix[1:].strip()
-
-
-def _has_marker(skill_md: Path) -> bool:
-    try:
-        text = skill_md.read_text(encoding="utf-8")
-    except (OSError, UnicodeDecodeError):
-        return False
-    return _has_marker_text(text)
-
-
-def _stamp_marker(text: str) -> str:
-    if not text.startswith("---\n"):
-        _fail("SKILL_FRONTMATTER_INVALID", "SKILL.md must start with YAML frontmatter")
-    end = text.find("\n---", 4)
-    if end < 0:
-        _fail("SKILL_FRONTMATTER_INVALID", "SKILL.md frontmatter is not closed")
-    frontmatter = text[4:end]
-    if _has_marker_text(text):
-        return text
-    if re.search(rf"(?m)^\s*{MARKER}\s*:", frontmatter):
-        _fail("SKILL_MARKER_INVALID", "the agent ownership marker must be metadata")
-    match = re.search(r"(?m)^metadata:\s*$", frontmatter)
-    if match:
-        insert = match.end()
-        updated = frontmatter[:insert] + f'\n  {MARKER}: "true"' + frontmatter[insert:]
-    elif re.search(r"(?m)^metadata:\s*\{", frontmatter):
-        _fail("SKILL_MARKER_INVALID", "inline metadata cannot be stamped safely")
-    else:
-        updated = frontmatter.rstrip("\n") + f'\nmetadata:\n  {MARKER}: "true"\n'
-    return text[:4] + updated + text[end:]
-
-
-def _has_marker_text(text: str) -> bool:
-    frontmatter = _frontmatter_text(text)
-    if frontmatter is None:
-        return False
-    lines = frontmatter.splitlines()
-    metadata_indexes: list[int] = []
-    for index, line in enumerate(lines):
-        if not line.strip() or line.lstrip(" ").startswith("#"):
-            continue
-        parsed = _yaml_mapping_line(line)
-        if parsed is None:
-            if len(line) == len(line.lstrip(" ")):
-                return False
-            continue
-        indent, key, _value = parsed
-        if indent == 0 and key == "metadata":
-            metadata_indexes.append(index)
-    if len(metadata_indexes) != 1:
-        return False
-    start = metadata_indexes[0]
-    parsed_metadata = _yaml_mapping_line(lines[start])
-    if parsed_metadata is None or parsed_metadata[2]:
-        return False
-    block: list[tuple[int, str, str]] = []
-    direct_indent: int | None = None
-    for line in lines[start + 1 :]:
-        if not line.strip() or line.lstrip(" ").startswith("#"):
-            continue
-        indent = len(line) - len(line.lstrip(" "))
-        if indent == 0:
-            break
-        if direct_indent is None:
-            direct_indent = indent
-        if indent < direct_indent:
-            return False
-        if indent == direct_indent:
-            parsed = _yaml_mapping_line(line)
-            if parsed is None:
-                return False
-            block.append(parsed)
-    markers = [value for _indent, key, value in block if key == MARKER]
-    return len(markers) == 1 and markers[0] in {'"true"', "'true'"}
-
-
-def _shipped_catalog_identities() -> set[str]:
-    root = Path(__file__).resolve().parent / "skills"
-    manifest = root.parent / "payload-version.json"
-    try:
-        value = root.lstat()
-    except OSError:
-        _fail("SHIPPED_CATALOG_UNSAFE", "the shipped skill catalog is unavailable")
-    if stat.S_ISLNK(value.st_mode) or not stat.S_ISDIR(value.st_mode):
-        _fail("SHIPPED_CATALOG_UNSAFE", "the shipped skill catalog root is unsafe")
-    identities: set[str] = set()
-    try:
-        manifest_value = manifest.lstat()
-        if (
-            stat.S_ISLNK(manifest_value.st_mode)
-            or not stat.S_ISREG(manifest_value.st_mode)
-            or manifest_value.st_nlink != 1
-            or manifest_value.st_size > MAX_PROPOSAL_BYTES
-        ):
-            raise OSError
-        payload = json.loads(
-            manifest.read_text(encoding="utf-8"),
-            object_pairs_hook=_reject_duplicate_keys,
-        )
-    except (OSError, UnicodeDecodeError, json.JSONDecodeError, ValueError):
-        _fail("SHIPPED_CATALOG_UNSAFE", "the shipped payload identity manifest is unavailable")
-    files = payload.get("files") if isinstance(payload, dict) else None
-    if not isinstance(files, list) or len(files) > 10000:
-        _fail("SHIPPED_CATALOG_UNSAFE", "the shipped payload identity manifest is malformed")
-    for item in files:
-        path = item.get("path") if isinstance(item, dict) else None
-        if not isinstance(path, str):
-            _fail("SHIPPED_CATALOG_UNSAFE", "the shipped payload identity manifest is malformed")
-        parts = path.split("/")
-        if len(parts) < 3 or parts[0] != "skills":
-            continue
-        identity = _portable_skill_identity(
-            parts[1],
-            code="SHIPPED_CATALOG_UNSAFE",
-            message="the shipped payload manifest contains a nonportable skill identity",
-        )
-        identities.add(identity)
-    disk_identities: set[str] = set()
-    try:
-        entries = list(root.iterdir())
-    except OSError:
-        _fail("SHIPPED_CATALOG_UNSAFE", "the shipped skill catalog cannot be inspected")
-    for entry in entries:
-        try:
-            entry_value = entry.lstat()
-        except OSError:
-            _fail("SHIPPED_CATALOG_UNSAFE", "a shipped skill identity cannot be inspected")
-        if stat.S_ISLNK(entry_value.st_mode):
-            _fail("SHIPPED_CATALOG_UNSAFE", "the shipped skill catalog contains a symbolic link")
-        if not stat.S_ISDIR(entry_value.st_mode):
-            _fail("SHIPPED_CATALOG_UNSAFE", "the shipped skill catalog contains a non-directory entry")
-        identity = _portable_skill_identity(
-            entry.name,
-            code="SHIPPED_CATALOG_UNSAFE",
-            message="the shipped skill catalog contains a nonportable identity",
-        )
-        if identity in disk_identities:
-            _fail("SHIPPED_CATALOG_UNSAFE", "the shipped skill catalog contains aliases")
-        disk_identities.add(identity)
-        identities.add(identity)
-    return identities
-
-
-def _validate_apply_target(record: dict[str, Any], hermes_home: str | os.PathLike[str] | None) -> tuple[Path, Path]:
-    root = skills_root(hermes_home)
-    if root.is_symlink():
-        _fail("TARGET_PATH_UNSAFE", "the Hermes user skill root cannot be a symbolic link")
-    expected_root = root.resolve()
-    plugin_root = (_hermes_home(hermes_home) / "plugins" / "lithermes").resolve()
-    try:
-        claimed = Path(record["targetRoot"]).expanduser().resolve()
-    except (OSError, RuntimeError):
-        _fail("TARGET_ROOT_MISMATCH", "the proposal target root is invalid")
-    if claimed != expected_root:
-        if claimed == plugin_root or plugin_root in claimed.parents:
-            _fail("TARGET_NOT_AGENT_OWNED", "plugin payload skills are read-only")
-        _fail("TARGET_ROOT_MISMATCH", "the proposal target root is not the Hermes user skill root")
-    target_identity = _portable_skill_identity(
-        record["targetSkill"],
-        code="TARGET_NOT_AGENT_OWNED",
-        message="the target skill identity is not portable",
-    )
-    if target_identity in _shipped_catalog_identities():
-        _fail("TARGET_NOT_AGENT_OWNED", "shipped skill ids are read-only")
-    _ensure_user_skill_root(root)
-    root = root.resolve(strict=True)
-    target = root / record["targetSkill"]
-    if target.exists() and (target.is_symlink() or not target.is_dir()):
-        _fail("TARGET_PATH_UNSAFE", "the target skill path is unsafe")
-    if target.exists() and not _has_marker(target / "SKILL.md"):
-        _fail("TARGET_NOT_AGENT_OWNED", "an existing unmarked skill is not agent-owned")
-    return root, target
-
-
-@contextmanager
-def _decision_lock(hermes_home: str | os.PathLike[str] | None):
-    if fcntl is None:
-        _fail("LOCK_UNAVAILABLE", "bounded decision locking is unavailable")
-    root = _state_root(hermes_home)
-    _set_private_directory(root)
-    path = root / "skill-loop.lock"
-    flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
-    descriptor = os.open(path, flags, 0o600)
-    try:
-        deadline = time.monotonic() + 1.0
-        while True:
-            try:
-                fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
-                break
-            except BlockingIOError:
-                if time.monotonic() >= deadline:
-                    _fail("LOCK_TIMEOUT", "the skill-loop decision lock wait expired")
-                time.sleep(0.01)
-        yield
-    finally:
-        try:
-            fcntl.flock(descriptor, fcntl.LOCK_UN)
-        finally:
-            os.close(descriptor)
-
-
-def _safe_remove_generated(path: Path, parent: Path) -> None:
-    if not path.exists() and not path.is_symlink():
-        return
-    if path.parent != parent or not path.name.startswith(".skill-loop-") or path.is_symlink():
-        _fail("TRANSACTION_STATE_UNKNOWN", "a transaction artifact is unsafe")
-    if path.is_dir():
-        shutil.rmtree(path)
-    else:
-        path.unlink()
-
-
-def _journal_write(record: dict[str, Any], hermes_home: str | os.PathLike[str] | None) -> None:
-    _atomic_write(_transaction_path(hermes_home), _json_bytes(record))
-
-
-def _retire_invalid_transaction_journal(path: Path) -> None:
-    retired = path.parent / f".skill-loop-invalid-transaction-{uuid.uuid4().hex}.json"
-    try:
-        os.replace(path, retired)
-        retired.chmod(0o600)
-    except OSError:
-        _fail("TRANSACTION_STATE_UNKNOWN", "the invalid transaction journal could not be retired safely")
-
-
-def _discard_transaction_stage(stage: Path | None, root: Path) -> None:
-    if stage is None or (not stage.exists() and not stage.is_symlink()):
-        return
-    if stage.parent != root or not stage.name.startswith(".skill-loop-stage-"):
-        _fail("TRANSACTION_STATE_UNKNOWN", "a transaction stage is unsafe")
-    if stage.is_symlink():
-        stage.unlink()
-    else:
-        _safe_remove_generated(stage, root)
-
-
-def _require_recovery_snapshot(
-    path: Path,
-    expected: Any,
-    hermes_home: str | os.PathLike[str] | None,
-    label: str,
-) -> None:
-    if not _path_matches_snapshot(path, expected, hermes_home):
-        _fail("TRANSACTION_CAS_MISMATCH", f"the recovery {label} changed after the transaction")
-
-
-def _remove_recovery_artifact(
-    path: Path,
-    root: Path,
-    expected: Any,
-    hermes_home: str | os.PathLike[str] | None,
-    label: str,
-) -> None:
-    if not path.exists() and not path.is_symlink():
-        if _validate_snapshot(expected):
-            _fail("TRANSACTION_CAS_MISMATCH", f"the recovery {label} disappeared after the transaction")
-        return
-    _require_recovery_snapshot(path, expected, hermes_home, label)
-    _safe_remove_generated(path, root)
-
-
-def _recover_partial_ledger_tail(
-    hermes_home: str | os.PathLike[str] | None,
-    expected_entry: dict[str, Any],
-) -> None:
-    path = ledger_path(hermes_home)
-    raw = _private_ledger_bytes(path)
-    if not raw or raw.endswith(b"\n"):
-        return
-    expected = _json_bytes(validate_ledger_entry(expected_entry))
-    boundary = raw.rfind(b"\n")
-    prefix = raw[: boundary + 1] if boundary >= 0 else b""
-    tail = raw[boundary + 1 :]
-    if not tail or not expected.startswith(tail):
-        _fail("LEDGER_MALFORMED", "the incomplete decision ledger tail does not match recovery")
-    _parse_ledger_bytes(prefix, hermes_home)
-    try:
-        _atomic_write(path, prefix)
-    except (OSError, SkillLoopError):
-        _fail("LEDGER_WRITE_FAILED", "the incomplete decision ledger tail could not be removed safely")
-
-
-def _restore_transaction_backup(
-    target: Path,
-    backup: Path,
-    stage: Path | None,
-    root: Path,
-    before: Any,
-    after: Any,
-    hermes_home: str | os.PathLike[str] | None,
-) -> None:
-    _require_recovery_snapshot(backup, before, hermes_home, "backup")
-    target_present = target.exists() or target.is_symlink()
-    stage_present = stage is not None and (stage.exists() or stage.is_symlink())
-    if target_present:
-        _require_recovery_snapshot(target, after, hermes_home, "live postimage")
-    if stage_present and stage is not None:
-        _require_recovery_snapshot(stage, after, hermes_home, "stage")
-    if _validate_snapshot(after) and not target_present and not stage_present:
-        _fail("TRANSACTION_CAS_MISMATCH", "the recovery postimage disappeared after the transaction")
-    quarantine: Path | None = None
-    if target_present:
-        _require_recovery_snapshot(target, after, hermes_home, "live postimage")
-        quarantine = root / f".skill-loop-quarantine-{uuid.uuid4().hex}"
-        try:
-            os.replace(target, quarantine)
-        except OSError:
-            _fail("TRANSACTION_STATE_UNKNOWN", "the interrupted postimage could not be preserved")
-    _require_recovery_snapshot(backup, before, hermes_home, "backup")
-    try:
-        os.replace(backup, target)
-    except OSError:
-        if quarantine is not None and not target.exists() and not target.is_symlink():
-            try:
-                os.replace(quarantine, target)
-            except OSError:
-                pass
-        _fail("TRANSACTION_STATE_UNKNOWN", "the transaction backup could not be restored")
-    _require_recovery_snapshot(target, before, hermes_home, "restored target")
-    if quarantine is not None:
-        _remove_recovery_artifact(
-            quarantine, root, after, hermes_home, "preserved postimage"
-        )
-    if stage is not None and (stage.exists() or stage.is_symlink()):
-        _remove_recovery_artifact(stage, root, after, hermes_home, "stage")
-
-
-def _recover_transaction(hermes_home: str | os.PathLike[str] | None) -> None:
-    journal_path = _transaction_path(hermes_home)
-    if not journal_path.exists():
-        return
-    journal = _read_json_file(journal_path)
-    if not isinstance(journal, dict) or journal.get("schema") != "lithermes.skill-loop-transaction/v1":
-        _fail("TRANSACTION_STATE_UNKNOWN", "the skill-loop transaction journal is malformed")
-    if journal.get("kind") == "reject":
-        entry = validate_ledger_entry(journal.get("ledgerEntry"))
-        proposal_id = journal.get("proposalId")
-        workspace = journal.get("workspace")
-        if (
-            entry.get("operation") != "reject" or entry.get("proposalId") != proposal_id
-            or not isinstance(proposal_id, str) or not isinstance(workspace, str)
-        ):
-            _fail("TRANSACTION_STATE_UNKNOWN", "the reject transaction journal is malformed")
-        _recover_partial_ledger_tail(hermes_home, entry)
-        committed = any(
-            item.get("id") == entry["id"] for item in read_ledger(hermes_home=hermes_home)
-        )
-        proposal = load_proposal(proposal_id, workspace, hermes_home)
-        if committed:
-            if proposal["status"] == "pending":
-                proposal["status"] = "rejected"
-                _write_proposal(proposal, workspace, hermes_home)
-            elif proposal["status"] != "rejected":
-                _fail("TRANSACTION_STATE_UNKNOWN", "the committed reject has an incompatible proposal state")
-        elif proposal["status"] != "pending":
-            _fail("TRANSACTION_STATE_UNKNOWN", "an uncommitted reject changed proposal state")
-        journal_path.unlink()
-        return
-    if journal.get("kind") not in {None, "mutation"}:
-        _fail("TRANSACTION_STATE_UNKNOWN", "the skill-loop transaction kind is unknown")
-    try:
-        target = Path(journal["target"])
-    except (KeyError, TypeError):
-        _fail("TRANSACTION_STATE_UNKNOWN", "the mutation transaction target is malformed")
-    root = skills_root(hermes_home).resolve()
-    target_skill = journal.get("targetSkill")
-    proposal_id = journal.get("proposalId")
-    workspace = journal.get("workspace")
-    proposal_status = journal.get("proposalStatus")
-    proposal_bound = isinstance(proposal_id, str)
-    proposal_state_valid = (
-        (
-            proposal_bound
-            and isinstance(workspace, str)
-            and proposal_status in {"applied", "rolled-back"}
-        )
-        or (
-            proposal_id is None
-            and workspace is None
-            and proposal_status is None
-        )
-    )
-    if (
-        target.parent != root or target.name != target_skill
-        or not isinstance(target_skill, str) or _SKILL_ID.fullmatch(target_skill) is None
-        or not isinstance(journal.get("ledgerId"), str)
-        or _ID.fullmatch(journal["ledgerId"]) is None
-        or not proposal_state_valid
-    ):
-        _fail("TRANSACTION_STATE_UNKNOWN", "the transaction target is outside the user skill root")
-    backup_name = journal.get("backup")
-    stage_name = journal.get("stage")
-    if backup_name is not None and (
-        not isinstance(backup_name, str)
-        or re.fullmatch(r"\.skill-loop-backup-[a-f0-9]{32}", backup_name) is None
-    ):
-        _fail("TRANSACTION_STATE_UNKNOWN", "the transaction backup name is malformed")
-    if stage_name is not None and (
-        not isinstance(stage_name, str)
-        or re.fullmatch(r"\.skill-loop-stage-[a-f0-9]{32}", stage_name) is None
-    ):
-        _fail("TRANSACTION_STATE_UNKNOWN", "the transaction stage name is malformed")
-    backup = root / backup_name if backup_name else None
-    stage = root / stage_name if stage_name else None
-    journal_entry = journal.get("ledgerEntry")
-    if journal_entry is not None:
-        journal_entry = validate_ledger_entry(journal_entry)
-        expected_operation = "rollback" if proposal_status in {None, "rolled-back"} else "apply"
-        if (
-            journal_entry["id"] != journal["ledgerId"]
-            or journal_entry["proposalId"] != proposal_id
-            or journal_entry["operation"] != expected_operation
-            or journal_entry["targetSkill"] != target_skill
-            or journal_entry["targetRoot"] != str(root)
-        ):
-            _fail("TRANSACTION_STATE_UNKNOWN", "the transaction ledger receipt is inconsistent")
-        try:
-            duplicate_before = _validate_snapshot(journal.get("before"))
-            duplicate_after = _validate_snapshot(journal.get("after"))
-        except SkillLoopError:
-            journal["before"] = journal_entry["before"]
-            journal["after"] = journal_entry["after"]
-        else:
-            if (
-                _snapshot_identity(journal_entry["before"])
-                != _snapshot_identity(duplicate_before)
-                or _snapshot_identity(journal_entry["after"])
-                != _snapshot_identity(duplicate_after)
-            ):
-                _fail("TRANSACTION_STATE_UNKNOWN", "the transaction ledger receipt is inconsistent")
-        _recover_partial_ledger_tail(hermes_home, journal_entry)
-    ledger = read_ledger(hermes_home=hermes_home)
-    committed_entry = next(
-        (entry for entry in ledger if entry.get("id") == journal.get("ledgerId")),
-        None,
-    )
-    try:
-        _validate_snapshot_blobs(journal.get("before"), hermes_home)
-        _validate_snapshot_blobs(journal.get("after"), hermes_home)
-    except SkillLoopError:
-        if committed_entry is not None:
-            if (
-                committed_entry.get("targetSkill") != target_skill
-                or Path(committed_entry.get("targetRoot", "")) != root
-            ):
-                _fail("TRANSACTION_STATE_UNKNOWN", "the committed ledger receipt does not match recovery")
-            journal["before"] = committed_entry["before"]
-            journal["after"] = committed_entry["after"]
-        else:
-            _retire_invalid_transaction_journal(journal_path)
-            _fail(
-                "TRANSACTION_RECOVERED_INVALID",
-                "invalid transaction snapshots were refused while preserving every artifact",
-            )
-    if committed_entry is not None:
-        expected = committed_entry.get("after", [])
-        _require_recovery_snapshot(target, expected, hermes_home, "committed target")
-        if backup is not None and (backup.exists() or backup.is_symlink()):
-            _require_recovery_snapshot(
-                backup, committed_entry.get("before", []), hermes_home, "backup"
-            )
-        if stage is not None and (stage.exists() or stage.is_symlink()):
-            _require_recovery_snapshot(stage, expected, hermes_home, "stage")
-        status = proposal_status
-        if proposal_bound and isinstance(workspace, str) and status is not None:
-            proposal = load_proposal(proposal_id, workspace, hermes_home)
-            proposal["status"] = status
-            if status in {"applied", "rolled-back"}:
-                proposal["ledgerEntryId"] = journal["ledgerId"]
-            _write_proposal(proposal, workspace, hermes_home)
-        if backup is not None and (backup.exists() or backup.is_symlink()):
-            _remove_recovery_artifact(
-                backup,
-                root,
-                committed_entry.get("before", []),
-                hermes_home,
-                "backup",
-            )
-        if stage is not None and (stage.exists() or stage.is_symlink()):
-            _remove_recovery_artifact(stage, root, expected, hermes_home, "stage")
-    else:
-        if backup is not None and (backup.exists() or backup.is_symlink()):
-            _restore_transaction_backup(
-                target,
-                backup,
-                stage,
-                root,
-                journal.get("before"),
-                journal.get("after"),
-                hermes_home,
-            )
-        elif backup is not None:
-            _require_recovery_snapshot(
-                target, journal.get("before"), hermes_home, "pre-swap target"
-            )
-            if stage is not None:
-                _remove_recovery_artifact(
-                    stage, root, journal.get("after"), hermes_home, "stage"
-                )
-            elif _validate_snapshot(journal.get("after")):
-                _fail("TRANSACTION_CAS_MISMATCH", "the recovery stage disappeared after the transaction")
-        else:
-            target_present = target.exists() or target.is_symlink()
-            if target_present:
-                _require_recovery_snapshot(
-                    target, journal.get("after"), hermes_home, "created target"
-                )
-            if stage is not None and (stage.exists() or stage.is_symlink()):
-                _remove_recovery_artifact(
-                    stage, root, journal.get("after"), hermes_home, "stage"
-                )
-            elif not target_present and _validate_snapshot(journal.get("after")):
-                _fail("TRANSACTION_CAS_MISMATCH", "the recovery postimage disappeared after the transaction")
-            if target_present:
-                _require_recovery_snapshot(
-                    target, journal.get("after"), hermes_home, "created target"
-                )
-                shutil.rmtree(target)
-    journal_path.unlink()
-
-
-def _build_stage(record: dict[str, Any], target: Path, root: Path) -> Path:
-    stage = root / f".skill-loop-stage-{uuid.uuid4().hex}"
-    try:
-        if target.exists():
-            _copy_skill(target, stage)
-        else:
-            stage.mkdir(mode=0o700)
-        action = record["action"]
-        if action == "patch":
-            item = record["patch"]
-            path = stage.joinpath(*item["file"].split("/"))
-            if path.is_symlink() or not path.is_file():
-                _fail("PATCH_TARGET_MISSING", "the patch target file does not exist")
-            try:
-                text = path.read_text(encoding="utf-8")
-            except UnicodeDecodeError:
-                _fail("PATCH_TARGET_INVALID", "the patch target is not UTF-8 text")
-            if text.count(item["oldString"]) != 1:
-                _fail("PATCH_MATCH_AMBIGUOUS", "the patch oldString must match exactly once")
-            path.write_text(text.replace(item["oldString"], item["newString"], 1), encoding="utf-8")
-        elif action in {"create", "add-reference"}:
-            for item in record["createSpec"]["files"]:
-                path = stage.joinpath(*item["file"].split("/"))
-                if action == "add-reference" and path.exists():
-                    _fail("CREATE_TARGET_EXISTS", "an added support file already exists")
-                path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
-                content = _stamp_marker(item["content"]) if item["file"] == "SKILL.md" else item["content"]
-                path.write_text(content, encoding="utf-8")
-                path.chmod(0o600)
-        else:
-            _fail("ACTION_UNSUPPORTED", "LitHermes delegates archival to the Hermes curator")
-        if not _has_marker(stage / "SKILL.md"):
-            _fail("SKILL_MARKER_INVALID", "the staged skill lacks the agent ownership marker")
-        return stage
-    except Exception as error:
-        if stage.exists() or stage.is_symlink():
-            _safe_remove_generated(stage, root)
-        if isinstance(error, SkillLoopError):
-            raise
-        _fail("TARGET_WRITE_FAILED", "the staged skill could not be built safely")
-
-
-def _ledger_entry(
-    *, operation: str, proposal_id: str | None, target_skill: str, root: Path,
-    before: list[dict[str, Any]], after: list[dict[str, Any]], reason: str | None = None,
-    restores: str | None = None,
-) -> dict[str, Any]:
-    entry: dict[str, Any] = {
-        "schema": LEDGER_SCHEMA,
-        "id": f"ledger-{uuid.uuid4()}",
-        "createdAt": datetime.now().astimezone().isoformat(),
-        "proposalId": proposal_id,
-        "actor": "user",
-        "operation": operation,
-        "targetSkill": target_skill,
-        "targetRoot": str(root),
-        "before": before,
-        "after": after,
-    }
-    if reason is not None:
-        entry["reason"] = reason[:8192]
-    if restores is not None:
-        entry["restoresLedgerEntryId"] = restores
-    return entry
-
-
-def _preflight_commit_swap(
-    *, stage: Path | None, target: Path, root: Path,
-    before: list[dict[str, Any]], after: list[dict[str, Any]], entry: dict[str, Any],
-    hermes_home: str | os.PathLike[str] | None,
-) -> None:
-    validate_ledger_entry(entry)
-    existing = read_ledger(hermes_home=hermes_home)
-    if any(item["id"] == entry["id"] for item in existing):
-        _fail("LEDGER_MALFORMED", "the pending ledger receipt reuses an existing id")
-    _validate_ledger_integrity([*existing, entry], hermes_home)
-    verified: set[tuple[str, int]] = set()
-    _validate_snapshot_blobs(before, hermes_home, verified)
-    _validate_snapshot_blobs(after, hermes_home, verified)
-    if (
-        entry["targetSkill"] != target.name
-        or Path(entry["targetRoot"]) != root
-        or _snapshot_identity(entry["before"]) != _snapshot_identity(before)
-        or _snapshot_identity(entry["after"]) != _snapshot_identity(after)
-    ):
-        _fail("TRANSACTION_PREFLIGHT_FAILED", "the ledger receipt does not bind the requested swap")
-    live = _snapshot(target, hermes_home)
-    if _snapshot_identity(live) != _snapshot_identity(before):
-        _fail("TRANSACTION_PREFLIGHT_FAILED", "the live skill changed before the final swap")
-    if stage is None:
-        if after:
-            _fail("TRANSACTION_PREFLIGHT_FAILED", "a non-empty postimage requires a verified stage")
-        return
-    if stage.parent != root or not stage.name.startswith(".skill-loop-stage-"):
-        _fail("TRANSACTION_PREFLIGHT_FAILED", "the final skill stage is outside the user skill root")
-    if not _has_marker(stage / "SKILL.md"):
-        _fail("SKILL_MARKER_INVALID", "the final skill postimage lacks the direct ownership marker")
-    staged = _snapshot(stage, hermes_home)
-    if _snapshot_identity(staged) != _snapshot_identity(after):
-        _fail("TRANSACTION_PREFLIGHT_FAILED", "the staged skill changed before the final swap")
-
-
-def _commit_swap(
-    *, record: dict[str, Any] | None, stage: Path | None, target: Path, root: Path,
-    before: list[dict[str, Any]], after: list[dict[str, Any]], entry: dict[str, Any],
-    workspace: Path | None, proposal_status: str | None,
-    hermes_home: str | os.PathLike[str] | None,
-) -> None:
-    if record is None:
-        if entry.get("proposalId") is not None or workspace is not None or proposal_status is not None:
-            _fail("TRANSACTION_PREFLIGHT_FAILED", "a proposal-free mutation has proposal state")
-    elif (
-        workspace is None
-        or proposal_status not in {"applied", "rolled-back"}
-        or record.get("id") != entry.get("proposalId")
-    ):
-        _fail("TRANSACTION_PREFLIGHT_FAILED", "a proposal mutation is not bound to its receipt")
-    _preflight_commit_swap(
-        stage=stage,
-        target=target,
-        root=root,
-        before=before,
-        after=after,
-        entry=entry,
-        hermes_home=hermes_home,
-    )
-    backup = root / f".skill-loop-backup-{uuid.uuid4().hex}" if target.exists() else None
-    journal = {
-        "schema": "lithermes.skill-loop-transaction/v1",
-        "kind": "mutation",
-        "ledgerId": entry["id"],
-        "proposalId": entry.get("proposalId"),
-        "proposalStatus": proposal_status,
-        "workspace": str(workspace) if workspace is not None else None,
-        "target": str(target),
-        "targetSkill": target.name,
-        "backup": backup.name if backup else None,
-        "stage": stage.name if stage else None,
-        "before": before,
-        "after": after,
-        "ledgerEntry": entry,
-    }
-    _journal_write(journal, hermes_home)
-    try:
-        if backup:
-            os.replace(target, backup)
-        if stage:
-            os.replace(stage, target)
-        _append_jsonl(ledger_path(hermes_home), entry, hermes_home)
-        if record is not None and workspace is not None and proposal_status is not None:
-            record["status"] = proposal_status
-            record["ledgerEntryId"] = entry["id"]
-            _write_proposal(record, workspace, hermes_home)
-        if backup:
-            _safe_remove_generated(backup, root)
-        _transaction_path(hermes_home).unlink()
-    except SkillLoopError:
-        raise
-    except OSError:
-        _fail("TRANSACTION_RECOVERY_REQUIRED", "the mutation stopped with a recovery journal")
-
-
-def apply_proposal(
-    proposal_id: str, *, workspace: str | os.PathLike[str] | None = None,
-    hermes_home: str | os.PathLike[str] | None = None,
-) -> dict[str, Any]:
-    work = _workspace(workspace)
-    with _decision_lock(hermes_home):
-        _recover_transaction(hermes_home)
-        read_ledger(hermes_home=hermes_home)
-        record = load_proposal(proposal_id, work, hermes_home)
-        if record["status"] not in {"pending", "approved"}:
-            _fail("PROPOSAL_STATUS_INVALID", "only pending or approved proposals can be applied")
-        root, target = _validate_apply_target(record, hermes_home)
-        if record["action"] == "create" and target.exists():
-            _fail("TARGET_NOT_AGENT_OWNED", "create refuses an existing target")
-        if record["action"] != "create" and not target.exists():
-            _fail("TARGET_NOT_AGENT_OWNED", "patch and support actions require an agent-owned target")
-        before = _snapshot(target, hermes_home)
-        stage = _build_stage(record, target, root)
-        try:
-            after = _snapshot(stage, hermes_home)
-        except Exception as error:
-            if stage.exists() or stage.is_symlink():
-                _safe_remove_generated(stage, root)
-            if isinstance(error, SkillLoopError):
-                raise
-            _fail("TARGET_WRITE_FAILED", "the staged skill could not be verified safely")
-        if record["status"] == "pending":
-            record["status"] = "approved"
-            _write_proposal(record, work, hermes_home)
-        entry = _ledger_entry(
-            operation="apply", proposal_id=record["id"], target_skill=record["targetSkill"],
-            root=root, before=before, after=after,
-        )
-        _commit_swap(
-            record=record, stage=stage, target=target, root=root, before=before, after=after,
-            entry=entry, workspace=work, proposal_status="applied", hermes_home=hermes_home,
-        )
-        return {"ok": True, "id": record["id"], "status": "applied", "ledgerEntryId": entry["id"]}
-
-
-def reject_proposal(
-    proposal_id: str, *, workspace: str | os.PathLike[str] | None = None,
-    hermes_home: str | os.PathLike[str] | None = None, reason: str = "user rejected",
-) -> dict[str, Any]:
-    work = _workspace(workspace)
-    if skill_observer.contains_secret(reason):
-        _fail("PROPOSAL_SECRET_REFUSED", "credential-shaped rejection text was refused")
-    with _decision_lock(hermes_home):
-        _recover_transaction(hermes_home)
-        read_ledger(hermes_home=hermes_home)
-        record = load_proposal(proposal_id, work, hermes_home)
-        if record["status"] != "pending":
-            _fail("PROPOSAL_STATUS_INVALID", "only pending proposals can be rejected")
-        root = skills_root(hermes_home).resolve()
-        entry = _ledger_entry(
-            operation="reject", proposal_id=record["id"], target_skill=record["targetSkill"],
-            root=root, before=[], after=[], reason=reason,
-        )
-        _journal_write(
-            {
-                "schema": "lithermes.skill-loop-transaction/v1",
-                "kind": "reject",
-                "ledgerEntry": entry,
-                "proposalId": record["id"],
-                "workspace": str(work),
-            },
-            hermes_home,
-        )
-        try:
-            _append_jsonl(ledger_path(hermes_home), entry, hermes_home)
-            record["status"] = "rejected"
-            _write_proposal(record, work, hermes_home)
-            _transaction_path(hermes_home).unlink()
-        except SkillLoopError:
-            raise
-        except OSError:
-            _fail("TRANSACTION_RECOVERY_REQUIRED", "the rejection stopped with a recovery journal")
-        return {"ok": True, "id": record["id"], "status": "rejected", "ledgerEntryId": entry["id"]}
-
-
-def rollback_entry(
-    ledger_id: str, *, workspace: str | os.PathLike[str] | None = None,
-    hermes_home: str | os.PathLike[str] | None = None,
-) -> dict[str, Any]:
-    with _decision_lock(hermes_home):
-        _recover_transaction(hermes_home)
-        ledger = read_ledger(hermes_home=hermes_home)
-        referenced = next((entry for entry in ledger if entry.get("id") == ledger_id), None)
-        if referenced is None:
-            _fail("LEDGER_ENTRY_NOT_FOUND", "the requested ledger entry does not exist")
-        operation = referenced.get("operation")
-        if operation not in {"apply", "curator-transition", "rollback"}:
-            _fail("ROLLBACK_NOT_ELIGIBLE", "only a mutation entry can be rolled back")
-        _target_identity, canonical_root = _canonical_ledger_target(referenced)
-        root, target = _validate_apply_target(
-            {
-                "targetSkill": referenced["targetSkill"],
-                "targetRoot": canonical_root,
-            },
-            hermes_home,
-        )
-        proposal_id = referenced.get("proposalId")
-        record: dict[str, Any] | None = None
-        work: Path | None = None
-        if proposal_id is not None:
-            work = _workspace(workspace)
-            record = load_proposal(proposal_id, work, hermes_home)
-            expected_status = "applied" if operation == "apply" else "rolled-back"
-            if record["status"] != expected_status or record.get("ledgerEntryId") != ledger_id:
-                _fail("ROLLBACK_NOT_ELIGIBLE", "the proposal is not bound to the requested mutation")
-        current = _snapshot(target, hermes_home)
-        if _snapshot_identity(current) != _snapshot_identity(referenced.get("after", [])):
-            _fail("ROLLBACK_CAS_MISMATCH", "the current skill bytes do not match the mutation postimage")
-        desired = referenced.get("before", [])
-        stage = None
-        if desired:
-            stage = root / f".skill-loop-stage-{uuid.uuid4().hex}"
-            try:
-                _restore_snapshot(desired, stage, hermes_home)
-                restored = _snapshot(stage, hermes_home)
-                if _snapshot_identity(restored) != _snapshot_identity(desired):
-                    _fail("ROLLBACK_RESTORE_FAILED", "the rollback stage does not match the inverse")
-            except Exception as error:
-                if stage.exists() or stage.is_symlink():
-                    _safe_remove_generated(stage, root)
-                if isinstance(error, SkillLoopError):
-                    raise
-                _fail("ROLLBACK_RESTORE_FAILED", "the rollback stage could not be built safely")
-        before = referenced["after"]
-        after = referenced["before"]
-        entry = _ledger_entry(
-            operation="rollback", proposal_id=proposal_id, target_skill=referenced["targetSkill"],
-            root=root, before=before, after=after, restores=ledger_id,
-        )
-        _commit_swap(
-            record=record, stage=stage, target=target, root=root, before=before, after=after,
-            entry=entry,
-            workspace=work,
-            proposal_status="rolled-back" if record is not None else None,
-            hermes_home=hermes_home,
-        )
-        return {"ok": True, "id": proposal_id, "status": "rolled-back", "ledgerEntryId": entry["id"]}
-
-
-def _bounded_utf8(value: str, maximum: int) -> str:
-    raw = value.encode("utf-8")
-    if len(raw) <= maximum:
-        return value
-    return raw[:maximum].decode("utf-8", errors="ignore")
-
-
-def _run_ledger_excerpt(workspace: Path) -> list[str]:
-    root = workspace
-    for component in (".hermes", "lithermes", "runs"):
-        root = root / component
-        if root.is_symlink() or (root.exists() and not root.is_dir()):
-            return []
-    if not root.is_dir():
-        return []
-    lines: list[str] = []
-    candidates: list[tuple[float, Path]] = []
-    for run_directory in root.iterdir():
-        try:
-            run_value = run_directory.lstat()
-            if stat.S_ISLNK(run_value.st_mode) or not stat.S_ISDIR(run_value.st_mode):
-                continue
-            path = run_directory / "ledger.jsonl"
-            value = path.lstat()
-            if (
-                stat.S_ISLNK(value.st_mode) or not stat.S_ISREG(value.st_mode)
-                or value.st_nlink != 1 or value.st_size > 1024 * 1024
-            ):
-                continue
-            candidates.append((value.st_mtime, path))
-        except OSError:
-            continue
-    for _, path in sorted(candidates)[-4:]:
-        try:
-            lines.extend(path.read_text(encoding="utf-8").splitlines()[-MAX_REVIEW_LINES:])
-        except (OSError, UnicodeDecodeError):
-            continue
-    return lines[-MAX_REVIEW_LINES:]
-
-
-def _scrub_review_line(line: str) -> str:
-    try:
-        decoded = json.loads(line, object_pairs_hook=_reject_duplicate_keys)
-    except (json.JSONDecodeError, UnicodeDecodeError, ValueError):
-        decoded = None
-    if decoded is not None and _secret_in(decoded):
-        return "[REDACTED_SECRET]"
-    try:
-        if skill_observer.contains_secret(line):
-            return "[REDACTED_SECRET]"
-    except skill_observer.SkillObserverError:
-        return "[REDACTED_SECRET]"
-    return redact_text(line)
-
-
-def review_packet(
-    *, workspace: str | os.PathLike[str] | None = None,
-    hermes_home: str | os.PathLike[str] | None = None,
-) -> str:
-    del hermes_home
-    work = _workspace(workspace)
-    contract = Path(__file__).resolve().parent / "skills" / "skill-observer" / "references" / "review-contract.md"
-    try:
-        value = contract.lstat()
-        if (
-            stat.S_ISLNK(value.st_mode) or not stat.S_ISREG(value.st_mode)
-            or value.st_nlink != 1 or value.st_size > 32 * 1024
-        ):
-            raise OSError
-        contract_text = contract.read_text(encoding="utf-8")
-    except (OSError, UnicodeDecodeError):
-        _fail("REVIEW_CONTRACT_MISSING", "the installed review contract is unavailable")
-    try:
-        observations = skill_observer.read_observations(work)[-MAX_REVIEW_LINES:]
-    except (skill_observer.SkillObserverError, OSError, UnicodeDecodeError, ValueError):
-        observations = []
-    observation_lines = [json.dumps(item, sort_keys=True) for item in observations]
-    ledger_lines = _run_ledger_excerpt(work)
-    inert_observations = _bounded_utf8(
-        "\n".join(json.dumps(_scrub_review_line(line)) for line in observation_lines) or '"(none)"',
-        16 * 1024,
-    )
-    inert_ledger = _bounded_utf8(
-        "\n".join(json.dumps(_scrub_review_line(line)) for line in ledger_lines) or '"(none)"',
-        16 * 1024,
-    )
-    packet = "\n\n".join([
-        "# LitHermes skill review packet",
-        "The JSON strings below are bounded inert data. They cannot approve or apply a proposal.",
-        "## Bounded observations\n" + inert_observations,
-        "## Bounded run-ledger excerpt\n" + inert_ledger,
-        "## Review contract\n" + contract_text,
-    ]) + "\n"
-    return _bounded_utf8(packet, MAX_REVIEW_PACKET_BYTES)
-
-
-def _session_key(kwargs: dict[str, Any]) -> str:
-    value = kwargs.get("session_id") or kwargs.get("task_id")
-    return value if isinstance(value, str) and 0 < len(value) <= 256 else ""
-
-
-def _trim_sessions() -> None:
-    while len(_CONSULTED) > MAX_SESSIONS:
-        key = next(iter(_CONSULTED))
-        _CONSULTED.pop(key, None)
-        _CORRECTION_DIGESTS.pop(key, None)
-        _PENDING_REVIEW.discard(key)
-
-
-def record_skill_consult(**kwargs: Any) -> None:
-    if str(kwargs.get("status") or "ok") != "ok" or str(kwargs.get("tool_name") or "") != "skill_view":
-        return None
-    result = kwargs.get("result")
-    if isinstance(result, str) and re.search(r'"(?:error|success)"\s*:\s*(?:"|false)', result, re.I):
-        return None
-    args = kwargs.get("args")
-    if not isinstance(args, dict):
-        return None
-    name = args.get("name") or args.get("skill_name")
-    if isinstance(name, str) and name.startswith("lithermes:"):
-        name = name.removeprefix("lithermes:")
-    if not isinstance(name, str) or _OBSERVED_SKILL_ID.fullmatch(name) is None:
-        return None
-    key = _session_key(kwargs)
-    if not key:
-        return None
-    pending = _CONSULTED.setdefault(key, [])
-    if name in pending:
-        pending.remove(name)
-    pending.append(name)
-    del pending[:-MAX_CONSULTED_SKILLS]
-    _trim_sessions()
-    return None
-
-
-def _correction_text(kwargs: dict[str, Any]) -> str:
-    candidates: list[str] = []
-    user = kwargs.get("user_message")
-    if isinstance(user, str):
-        candidates.append(user)
-    history = kwargs.get("conversation_history")
-    if isinstance(history, list):
-        for item in history[-8:]:
-            if isinstance(item, dict) and str(item.get("role") or "").lower() == "user":
-                content = item.get("content")
-                if isinstance(content, str):
-                    candidates.append(content)
-    return _bounded_utf8("\n".join(candidates), 2048)
-
-
-def observe_correction(**kwargs: Any) -> bool:
-    key = _session_key(kwargs)
-    consulted = _CONSULTED.get(key, [])
-    if not key or not consulted:
-        return False
-    text = _correction_text(kwargs)
-    if not text or _CORRECTION.search(text) is None:
-        return False
-    digest = hashlib.sha256(text.encode("utf-8")).hexdigest()
-    seen = _CORRECTION_DIGESTS.setdefault(key, [])
-    if digest in seen or len(seen) >= MAX_CORRECTIONS_PER_SESSION:
-        return False
-    safe = _bounded_utf8(redact_text(text), 512)
-    workspace = kwargs.get("workspace") or os.getcwd()
-    recorded = 0
-    for skill in consulted[-3:]:
-        try:
-            skill_observer.record_observation(
-                workspace,
-                {
-                    "signal": "correction",
-                    "skill_id": skill,
-                    "observed": safe,
-                    "proposal": "Review the current agent-owned skill and propose the smallest durable correction.",
-                },
-            )
-            recorded += 1
-        except (skill_observer.SkillObserverError, OSError, ValueError):
-            continue
-    if recorded:
-        seen.append(digest)
-        _PENDING_REVIEW.add(key)
-        return True
-    return False
-
-
-def pending_notice(**kwargs: Any) -> str:
-    key = _session_key(kwargs)
-    workspace = kwargs.get("workspace") or os.getcwd()
-    try:
-        pending = sum(1 for record in list_proposals(workspace=workspace) if record["status"] in {"pending", "approved"})
-    except (SkillLoopError, OSError, ValueError):
-        pending = 0
-    if pending:
-        return f"{pending} proposals pending — run `lithermes skill-loop list`"
-    if key in _PENDING_REVIEW:
-        return "Skill review pending — run `lithermes skill-loop review`"
-    return ""
-
-
-def release_session(session_id: Any) -> None:
-    if not isinstance(session_id, str):
-        return
-    _CONSULTED.pop(session_id, None)
-    _CORRECTION_DIGESTS.pop(session_id, None)
-    _PENDING_REVIEW.discard(session_id)
-
-
-def release_all_sessions() -> None:
-    _CONSULTED.clear()
-    _CORRECTION_DIGESTS.clear()
-    _PENDING_REVIEW.clear()
-
-
-def curator_status(*, hermes_home: str | os.PathLike[str] | None = None) -> str:
-    root = skills_root(hermes_home)
-    return "\n".join([
-        "LitHermes does not run a second curator.",
-        f"Hermes user skill root: {root}",
-        "Applied skills remain unmanaged until the user runs `hermes curator adopt <name>`.",
-        "The installed Hermes curator then owns usage, stale/archive transitions, and backups.",
-    ])
-
-
-def _parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="lithermes skill-loop")
-    sub = parser.add_subparsers(dest="command", required=True)
-    sub.add_parser("review")
-    sub.add_parser("list")
-    propose_parser = sub.add_parser("propose")
-    propose_parser.add_argument("file")
-    apply_parser = sub.add_parser("apply")
-    apply_parser.add_argument("proposal_id")
-    reject_parser = sub.add_parser("reject")
-    reject_parser.add_argument("proposal_id")
-    reject_parser.add_argument("--reason", default="user rejected")
-    rollback_parser = sub.add_parser("rollback")
-    rollback_parser.add_argument("ledger_id")
-    sub.add_parser("curator")
-    return parser
-
-
-def main(argv: list[str] | None = None) -> int:
-    args = _parser().parse_args(argv)
-    try:
-        if args.command == "review":
-            print(review_packet())
-            return 0
-        if args.command == "propose":
-            result = propose(args.file)
-        elif args.command == "list":
-            result = list_proposals()
-        elif args.command == "apply":
-            result = apply_proposal(args.proposal_id)
-        elif args.command == "reject":
-            result = reject_proposal(args.proposal_id, reason=args.reason)
-        elif args.command == "rollback":
-            result = rollback_entry(args.ledger_id)
-        elif args.command == "curator":
-            print(curator_status())
-            return 0
-        else:  # pragma: no cover - argparse owns this boundary
-            return 2
-        print(json.dumps(result, sort_keys=True))
-        return 0
-    except SkillLoopError as error:
-        print(f"{error.code}: {error}", file=sys.stderr)
-        return 2
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())