@litfamily/lithermes 1.0.0

package/assets/lithermes-plugin/skill_loop.py

@@ -0,0 +1,2044 @@
+"""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())