superlocalmemory 3.8.14 → 4.0.1

package/src/superlocalmemory/evolution/evolution_store.py

@@ -12,9 +12,11 @@ Part of Qualixar | Author: Varun Pratap Bhardwaj
 
 from __future__ import annotations
 
+import hashlib
 import json
 import logging
 import sqlite3
+import warnings
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
@@ -61,6 +63,44 @@ CREATE TABLE IF NOT EXISTS evolution_cycle_state (
     updated_at TEXT,
     PRIMARY KEY (profile_id, key)
 );
+
+-- Phase 2: append-only status-transition log (LLD Decision B2).
+-- Each state change for a record produces one new row here.
+-- The BEFORE UPDATE trigger enforces immutability at the DB layer.
+CREATE TABLE IF NOT EXISTS skill_evolution_transitions (
+    seq             INTEGER PRIMARY KEY AUTOINCREMENT,
+    record_id       TEXT NOT NULL,
+    profile_id      TEXT NOT NULL DEFAULT 'default',
+    from_status     TEXT NOT NULL,
+    to_status       TEXT NOT NULL,
+    transitioned_at TEXT NOT NULL,
+    actor_id        TEXT DEFAULT '',
+    reason          TEXT DEFAULT '',
+    prev_hash       TEXT DEFAULT '',
+    transition_hash TEXT NOT NULL,
+    metadata        TEXT DEFAULT '{}'
+);
+
+CREATE INDEX IF NOT EXISTS idx_evo_trans_record
+    ON skill_evolution_transitions(record_id, seq);
+
+CREATE INDEX IF NOT EXISTS idx_evo_trans_profile
+    ON skill_evolution_transitions(profile_id, transitioned_at);
+
+-- DB-enforced append-only: any UPDATE on this table is a bug (LLD Decision B2).
+CREATE TRIGGER IF NOT EXISTS no_update_evo_transitions
+BEFORE UPDATE ON skill_evolution_transitions
+BEGIN
+    SELECT RAISE(ABORT, 'skill_evolution_transitions is append-only');
+END;
+
+-- Audit P1-3: DELETE must also be forbidden — otherwise the hash chain can be
+-- silently truncated/erased without a DB abort, breaking the immutable-log claim.
+CREATE TRIGGER IF NOT EXISTS no_delete_evo_transitions
+BEFORE DELETE ON skill_evolution_transitions
+BEGIN
+    SELECT RAISE(ABORT, 'skill_evolution_transitions is append-only');
+END;
 """
 
 # Anti-loop budget
@@ -223,11 +263,194 @@ class EvolutionStore:
         for k in recovered:
             del self._addressed_degradations[k]
 
+    # ------------------------------------------------------------------
+    # Phase 2: append-only transition log
+    # ------------------------------------------------------------------
+
+    def insert_record(self, record: EvolutionRecord, profile_id: str) -> None:
+        """INSERT a new evolution record (CANDIDATE status).
+
+        Unlike save_record, this uses plain INSERT — NOT INSERT OR REPLACE.
+        Raises sqlite3.IntegrityError if a row with the same id already exists.
+        Call this exactly once per candidate (CRIT-1: never reuse record_id).
+        """
+        conn = sqlite3.connect(self._db_path, timeout=10)
+        try:
+            conn.execute(
+                "INSERT INTO skill_evolution_log "
+                "(id, profile_id, skill_name, parent_skill_id, evolution_type, "
+                " trigger_type, generation, status, mutation_summary, evidence, "
+                " original_content, evolved_content, content_diff, "
+                " blind_verified, rejection_reason, created_at, completed_at) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    record.id,
+                    profile_id,
+                    record.skill_name,
+                    record.parent_skill_id,
+                    record.evolution_type.value,
+                    record.trigger.value,
+                    record.generation,
+                    record.status.value,
+                    record.mutation_summary,
+                    json.dumps(list(record.evidence)),
+                    record.original_content,
+                    record.evolved_content,
+                    record.content_diff,
+                    1 if record.blind_verified else 0,
+                    record.rejection_reason,
+                    record.created_at,
+                    record.completed_at,
+                ),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def append_transition(
+        self,
+        record_id: str,
+        profile_id: str,
+        from_status: EvolutionStatus,
+        to_status: EvolutionStatus,
+        *,
+        actor_id: str = "",
+        reason: str = "",
+        metadata: dict | None = None,
+    ) -> str:
+        """Append an immutable status-transition row. Returns transition_hash.
+
+        Hash linkage (audit P2-3): transition_hash = SHA-256 over a canonical,
+        pipe-delimited payload covering EVERY persisted field —
+        ``prev_hash | record_id | from_status | to_status | ts | actor_id |
+        reason | metadata_str``. Delimiters remove concatenation ambiguity and
+        including reason+metadata makes those columns tamper-evident too.
+
+        prev_hash is the transition_hash of the most recent row for this
+        record_id, or 'genesis' for the first transition.
+
+        Concurrency (audit P1-5): the read-prev-then-insert is wrapped in a
+        single ``BEGIN IMMEDIATE`` transaction so two concurrent writers cannot
+        both read the same prev_hash and fork the chain.
+
+        Never calls UPDATE or DELETE. Raises ValueError if from_status == to_status.
+        """
+        if from_status == to_status:
+            raise ValueError(
+                f"append_transition: from_status == to_status == {from_status!r}; "
+                "no-op transitions are not allowed in the append-only log."
+            )
+        ts = datetime.now(timezone.utc).isoformat()
+        metadata_str = json.dumps(metadata or {}, sort_keys=True)
+
+        # isolation_level=None + explicit BEGIN IMMEDIATE = one atomic
+        # select-prev-then-insert critical section per call (P1-5).
+        conn = sqlite3.connect(self._db_path, timeout=10, isolation_level=None)
+        try:
+            conn.execute("BEGIN IMMEDIATE")
+            # Find prev_hash for this record_id (genesis if first)
+            row = conn.execute(
+                "SELECT transition_hash FROM skill_evolution_transitions "
+                "WHERE record_id = ? AND profile_id = ? "
+                "ORDER BY seq DESC LIMIT 1",
+                (record_id, profile_id),
+            ).fetchone()
+            prev_hash = row[0] if row else "genesis"
+
+            # Canonical, delimited payload over ALL persisted fields (P2-3).
+            payload = "|".join((
+                prev_hash, record_id,
+                from_status.value, to_status.value,
+                ts, actor_id, reason, metadata_str,
+            ))
+            transition_hash = hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+            conn.execute(
+                "INSERT INTO skill_evolution_transitions "
+                "(record_id, profile_id, from_status, to_status, "
+                " transitioned_at, actor_id, reason, prev_hash, "
+                " transition_hash, metadata) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    record_id,
+                    profile_id,
+                    from_status.value,
+                    to_status.value,
+                    ts,
+                    actor_id,
+                    reason,
+                    prev_hash,
+                    transition_hash,
+                    metadata_str,
+                ),
+            )
+            conn.execute("COMMIT")
+            return transition_hash
+        except Exception:
+            try:
+                conn.execute("ROLLBACK")
+            except Exception:
+                pass
+            raise
+        finally:
+            conn.close()
+
+    def get_latest_status(
+        self, record_id: str, profile_id: str,
+    ) -> EvolutionStatus | None:
+        """Return the to_status of the highest-seq transition for record_id.
+
+        Returns None if no transitions exist for this record_id / profile_id.
+        """
+        conn = sqlite3.connect(self._db_path, timeout=10)
+        try:
+            row = conn.execute(
+                "SELECT to_status FROM skill_evolution_transitions "
+                "WHERE record_id = ? AND profile_id = ? "
+                "ORDER BY seq DESC LIMIT 1",
+                (record_id, profile_id),
+            ).fetchone()
+            if row is None:
+                return None
+            return EvolutionStatus(row[0])
+        finally:
+            conn.close()
+
+    def get_transitions(self, record_id: str, profile_id: str) -> list[dict]:
+        """Return all transition rows for record_id ordered by seq ASC."""
+        conn = sqlite3.connect(self._db_path, timeout=10)
+        conn.row_factory = sqlite3.Row
+        try:
+            rows = conn.execute(
+                "SELECT seq, record_id, profile_id, from_status, to_status, "
+                "transitioned_at, actor_id, reason, prev_hash, transition_hash, "
+                "metadata "
+                "FROM skill_evolution_transitions "
+                "WHERE record_id = ? AND profile_id = ? "
+                "ORDER BY seq ASC",
+                (record_id, profile_id),
+            ).fetchall()
+            return [dict(r) for r in rows]
+        finally:
+            conn.close()
+
     # ------------------------------------------------------------------
     # CRUD
     # ------------------------------------------------------------------
 
     def save_record(self, record: EvolutionRecord, profile_id: str) -> None:
+        """DEPRECATED: use insert_record() for new records and append_transition() for state changes.
+
+        Retained for backward-compatibility with existing tests and callers.
+        Uses INSERT OR REPLACE — mutable semantics, not append-only.
+        Will be removed in a future cleanup pass (not Phase 2 scope).
+        """
+        warnings.warn(
+            "EvolutionStore.save_record() is deprecated; "
+            "use insert_record() + append_transition() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         conn = sqlite3.connect(self._db_path, timeout=10)
         try:
             conn.execute(
@@ -306,13 +529,30 @@ class EvolutionStore:
             conn.close()
 
     def count_attempts(self, skill_name: str, profile_id: str) -> int:
+        """Count non-successful evolution attempts for a skill.
+
+        Audit P0-2: with the Phase-2 append-only model, ``skill_evolution_log``
+        rows are frozen at 'candidate' by ``insert_record`` and never updated, so
+        the legacy ``status NOT IN ('promoted')`` filter counted successes too —
+        permanently disabling a skill after MAX_ATTEMPTS_PER_SKILL improvements.
+        The current status is now read from the append-only transitions log
+        (latest ``to_status`` per record), and success states are excluded,
+        mirroring the pre-Phase-2 exclusion of 'promoted'. Legacy rows with no
+        transitions fall back to their frozen log status via COALESCE.
+        """
+        success = ("promoted", "verified_quarantined", "approved", "active")
+        marks = ",".join("?" for _ in success)
         conn = sqlite3.connect(self._db_path, timeout=10)
         try:
             row = conn.execute(
-                "SELECT COUNT(*) FROM skill_evolution_log "
-                "WHERE skill_name = ? AND profile_id = ? "
-                "AND status NOT IN ('promoted')",
-                (skill_name, profile_id),
+                "SELECT COUNT(*) FROM skill_evolution_log l "
+                "WHERE l.skill_name = ? AND l.profile_id = ? "
+                "AND COALESCE("
+                "  (SELECT t.to_status FROM skill_evolution_transitions t "
+                "   WHERE t.record_id = l.id AND t.profile_id = l.profile_id "
+                "   ORDER BY t.seq DESC LIMIT 1), l.status"
+                f") NOT IN ({marks})",
+                (skill_name, profile_id, *success),
             ).fetchone()
             return row[0] if row else 0
         finally:

package/src/superlocalmemory/evolution/llm_dispatch.py

@@ -158,6 +158,7 @@ ALLOWED_LLM_MODELS: frozenset[str] = frozenset({
     "claude-sonnet-4-6",
     "ollama:llama3",
     "ollama:qwen2.5",
+    "openai:gpt-4o-mini",
 })
 
 FORBIDDEN_MODEL_SUBSTRINGS: tuple[str, ...] = ("opus", "gpt-4-turbo")
@@ -301,6 +302,43 @@ def _call_claude_api_backend(
         return ""
 
 
+def _call_openai_api_backend(
+    prompt: str, *, model: str, max_tokens: int,
+) -> str:
+    """Call the OpenAI Chat Completions API directly.
+
+    The API model id is derived from the allow-listed name by stripping
+    the ``"openai:"`` prefix — e.g. ``"openai:gpt-4o-mini"`` → ``"gpt-4o-mini"``.
+    Requires ``OPENAI_API_KEY`` in the environment. Returns empty string on
+    any transport or SDK failure (fail-closed).
+    """
+    openai_model = model.split(":", 1)[1] if model.startswith("openai:") else model
+    try:
+        import openai as _openai  # type: ignore[import-not-found]
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("openai sdk unavailable: %s", exc)
+        return ""
+
+    try:
+        client = _openai.OpenAI()
+        completion = client.chat.completions.create(
+            model=openai_model,
+            max_tokens=max_tokens,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        choices = getattr(completion, "choices", None)
+        if choices and len(choices) > 0:
+            msg = getattr(choices[0], "message", None)
+            if msg:
+                content = getattr(msg, "content", None)
+                if isinstance(content, str):
+                    return content
+        return ""
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("OpenAI API backend failed: %s", exc)
+        return ""
+
+
 # ---------------------------------------------------------------------------
 # Backend registry — dispatches by (allow-listed) model id
 # ---------------------------------------------------------------------------
@@ -337,6 +375,8 @@ def _pick_backend(model: str) -> Callable[..., str]:
     """
     if model.startswith("ollama:"):
         return _call_ollama_backend
+    if model.startswith("openai:"):
+        return _call_openai_api_backend
     if model.startswith("claude-"):
         # Claude CLI path is an alternative — selected when an explicit
         # env flag is set. Default path is the Anthropic API backend.

package/src/superlocalmemory/evolution/model_selection.py

@@ -39,6 +39,7 @@ CHEAPEST_CLAUDE = "claude-haiku-4-5"
 QUALITY_CLAUDE = "claude-sonnet-4-6"
 CHEAPEST_OLLAMA = "ollama:llama3"
 ALT_OLLAMA = "ollama:qwen2.5"
+CHEAPEST_OPENAI = "openai:gpt-4o-mini"
 
 # Short-name → allow-listed model id. Single source of truth for aliasing;
 # ``skill_evolver`` re-exports these for backward compatibility.
@@ -48,6 +49,8 @@ _MODEL_ALIASES: dict[str, str] = {
     "ollama": CHEAPEST_OLLAMA,
     "ollama:llama3": CHEAPEST_OLLAMA,
     "ollama:qwen2.5": ALT_OLLAMA,
+    "openai": CHEAPEST_OPENAI,
+    "openai:gpt-4o-mini": CHEAPEST_OPENAI,
     CHEAPEST_CLAUDE: CHEAPEST_CLAUDE,
     QUALITY_CLAUDE: QUALITY_CLAUDE,
 }
@@ -78,11 +81,18 @@ class ResolvedModels:
 
 
 def _cheapest_for_backend(backend: str) -> str:
-    """Lowest-cost allow-listed model for a detected backend."""
+    """Lowest-cost allow-listed model for a detected backend.
+
+    The configured backend is authoritative: when the caller explicitly
+    names a provider, models are drawn from that provider only —
+    never silently downgraded to a different vendor's offering.
+    """
     if backend == "ollama":
         return CHEAPEST_OLLAMA
-    # claude CLI, anthropic API, and any non-Ollama backend evolution can
-    # actually dispatch route through the cheapest Claude model.
+    if backend == "openai":
+        return CHEAPEST_OPENAI
+    # claude CLI, anthropic API, and any non-Ollama/non-OpenAI backend
+    # route through the cheapest Claude model.
     return CHEAPEST_CLAUDE
 
 
@@ -106,6 +116,8 @@ def _independent_verifier(
     """Pick a cheap verifier that differs from the generator when possible.
 
     - Ollama generator → the *other* local model (both free, distinct).
+    - OpenAI generator → same OpenAI model (single-provider constraint;
+      independence flag will be False — caller logs the condition).
     - Claude generator + local Ollama up → free local verifier.
     - Claude generator, no Ollama → the cheapest *different* Claude tier if
       the generator was a premium model; otherwise reuse the cheapest model
@@ -114,6 +126,9 @@ def _independent_verifier(
     """
     if mutation.startswith("ollama:"):
         return ALT_OLLAMA if mutation != ALT_OLLAMA else CHEAPEST_OLLAMA
+    if mutation.startswith("openai:"):
+        # Honor the configured provider: stay within OpenAI models.
+        return CHEAPEST_OPENAI
     if ollama_available:
         return CHEAPEST_OLLAMA
     if mutation != CHEAPEST_CLAUDE:

package/src/superlocalmemory/evolution/mutation_generator.py

@@ -97,6 +97,9 @@ _SKILL_DENY_PATTERNS: tuple[str, ...] = (
     "os.environ", "subprocess", "exec(", "eval(", "__import__", "import os",
     "import subprocess", "pickle.loads", "curl ", "wget ", "rm -rf",
     "ANTHROPIC_API_KEY", "OPENAI_API_KEY", "AWS_SECRET", "/.ssh/", ".install_token",
+    # Semantic exfiltration patterns — skills must not instruct unauthorized
+    # data transfer or bypass of user consent.
+    "without consent", "exfiltrat",
 )
 
 

package/src/superlocalmemory/evolution/skill_activator.py

@@ -0,0 +1,270 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later — see LICENSE file
+# Part of SuperLocalMemory V4 | https://qualixar.com | https://varunpratap.com
+
+"""SkillActivator — atomic activation of quarantined evolved skills.
+
+Copies a VERIFIED_QUARANTINED skill artifact into the live skill directory
+(~/.claude/skills/{skill_name}/SKILL.md), retains the prior artifact as a
+.bak file, and provides a tested rollback path.
+
+Invariants:
+  1. The destination directory is a child of live_root — path traversal raises ValueError.
+  2. The backup is written BEFORE the live copy is overwritten.
+  3. Activation is atomic via a .tmp file → os.replace (POSIX atomic on same fs).
+  4. Rollback restores from the .bak file and leaves the live copy unchanged.
+  5. Only the quarantined artifact identified by quarantine_dir_name is copied;
+     no arbitrary file can be activated.
+
+CRIT-2 note: skill_name and quarantine_dir_name are ALWAYS different strings:
+  - skill_name: the original skill identifier (e.g. "brainstorming")
+  - quarantine_dir_name: the sanitized quarantine subdir (e.g. "brainstorming-vabc12")
+Both are required; neither defaults from the other.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import re
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+
+from superlocalmemory.infra.data_root import canonical_data_root
+
+logger = logging.getLogger(__name__)
+
+LIVE_SKILLS_ROOT: Path = Path.home() / ".claude" / "skills"
+BACKUP_ROOT: Path = canonical_data_root() / "skill_backups"
+QUARANTINE_ROOT: Path = canonical_data_root() / "quarantine" / "skills"
+
+_SAFE_NAME_RE = re.compile(r"[^a-zA-Z0-9_-]")
+
+
+class SkillActivationError(Exception):
+    """Raised when activation fails after writing the backup.
+
+    The caller must invoke rollback() after receiving this error to restore
+    the previous live artifact.
+    """
+
+
+class SkillActivator:
+    """Activates a quarantined evolved skill into the live skill directory."""
+
+    def __init__(
+        self,
+        *,
+        live_root: Path | None = None,
+        backup_root: Path | None = None,
+        quarantine_root: Path | None = None,
+    ) -> None:
+        self._live_root = live_root or LIVE_SKILLS_ROOT
+        self._backup_root = backup_root or BACKUP_ROOT
+        self._quarantine_root = quarantine_root or QUARANTINE_ROOT
+
+    # ------------------------------------------------------------------
+    # Path helpers
+    # ------------------------------------------------------------------
+
+    def _safe_skill_dir(self, skill_name: str, base: Path) -> Path:
+        """Return base / sanitized_name, raising ValueError on traversal.
+
+        Two-layer check (fail-fast + belt-and-suspenders):
+          1. Reject the raw skill_name if it contains '..' or is absolute.
+          2. After sanitization, resolve the target path and verify it remains
+             inside base.  This catches any edge case the regex misses.
+        """
+        # Fail-fast: detect traversal in raw name before sanitization.
+        raw = Path(skill_name)
+        if raw.is_absolute() or ".." in raw.parts:
+            raise ValueError(
+                f"skill_name {skill_name!r} contains path traversal sequences"
+            )
+        safe = _SAFE_NAME_RE.sub("-", skill_name).lower()[:50] or "skill"
+        target = (base / safe).resolve()
+        base_resolved = base.resolve()
+        # Audit P2-5: is_relative_to is not prefix-fragile (a sibling like
+        # ".../skills-evil" cannot masquerade as being under ".../skills").
+        if not target.is_relative_to(base_resolved):
+            raise ValueError(
+                f"skill_name {skill_name!r} escapes sandbox: {target}"
+            )
+        return target
+
+    def _quarantine_path(self, quarantine_dir_name: str) -> Path:
+        """Return the SKILL.md path inside quarantine for a given dir name.
+
+        quarantine_dir_name is the sanitized directory name (CRIT-2), e.g.
+        'brainstorming-vabc12'.  It is NOT the skill_name.
+
+        Hardened (audit P0-1 / P1-4): reject absolute paths and '..' traversal,
+        then resolve() and require containment inside the quarantine root. The
+        resolve() step also defeats a symlinked quarantine dir that would
+        otherwise redirect the read outside the sandbox and inject arbitrary
+        content into a live skill.
+        """
+        raw = Path(quarantine_dir_name)
+        if raw.is_absolute() or ".." in raw.parts:
+            raise ValueError(
+                f"quarantine_dir_name {quarantine_dir_name!r} contains path traversal"
+            )
+        root = self._quarantine_root.resolve()
+        q_dir = (self._quarantine_root / quarantine_dir_name).resolve()
+        if not q_dir.is_relative_to(root):
+            raise ValueError(
+                f"quarantine_dir_name {quarantine_dir_name!r} escapes sandbox: {q_dir}"
+            )
+        q_path = (q_dir / "SKILL.md").resolve()
+        if not q_path.is_relative_to(root):
+            raise ValueError(
+                f"quarantine artifact escapes sandbox: {q_path}"
+            )
+        return q_path
+
+    def _live_path(self, skill_name: str) -> Path:
+        return self._safe_skill_dir(skill_name, self._live_root) / "SKILL.md"
+
+    def _backup_path(self, skill_name: str) -> Path:
+        return self._safe_skill_dir(skill_name, self._backup_root) / "SKILL.md.bak"
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def activate(
+        self,
+        skill_name: str,
+        quarantine_dir_name: str,
+        *,
+        actor_id: str = "",
+    ) -> dict:
+        """Atomically activate a quarantined skill.
+
+        Steps:
+          1. Resolve quarantine_path using quarantine_dir_name and verify it exists.
+          2. Read quarantine content and compute SHA-256.
+          3. Write backup of existing live SKILL.md (if any) to backup_root.
+          4. Write quarantine content to live path via .tmp → os.replace.
+          5. Return activation metadata.
+
+        Args:
+            skill_name: The original skill identifier (CRIT-2), e.g. "brainstorming".
+            quarantine_dir_name: The sanitized quarantine subdir, e.g. "brainstorming-vabc12".
+            actor_id: Who triggered activation (e.g. "auto" or a user id).
+
+        Raises:
+            FileNotFoundError: Quarantine artifact does not exist.
+            ValueError: Path traversal detected in skill_name.
+            SkillActivationError: Any OS error after the backup was already written.
+        """
+        q_path = self._quarantine_path(quarantine_dir_name)
+        live_path = self._live_path(skill_name)  # raises ValueError on traversal
+        backup_path = self._backup_path(skill_name)
+
+        if not q_path.exists():
+            raise FileNotFoundError(
+                f"Quarantine artifact not found: {q_path}"
+            )
+
+        content = q_path.read_bytes()
+        content_hash = hashlib.sha256(content).hexdigest()
+        ts = datetime.now(timezone.utc).isoformat()
+
+        # Step 3: backup existing live artifact BEFORE any overwrite
+        backup_path.parent.mkdir(parents=True, exist_ok=True)
+        backup_written = False
+        if live_path.exists():
+            shutil.copy2(live_path, backup_path)
+            backup_written = True
+            logger.info(
+                "skill_activator: backed up %s → %s",
+                live_path, backup_path,
+            )
+
+        # Step 4: atomic write via .tmp → rename (same directory = same fs)
+        live_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp_path = live_path.with_suffix(".tmp")
+        try:
+            tmp_path.write_bytes(content)
+            os.replace(tmp_path, live_path)
+        except OSError as exc:
+            try:
+                tmp_path.unlink(missing_ok=True)
+            except OSError:
+                pass
+            raise SkillActivationError(
+                f"atomic write failed for {live_path}: {exc}"
+            ) from exc
+
+        logger.info(
+            "skill_activator: activated %s @ %s (sha256=%s, actor=%s)",
+            skill_name, live_path, content_hash[:12], actor_id,
+        )
+        return {
+            "skill_name": skill_name,
+            "live_path": str(live_path),
+            "backup_path": str(backup_path) if backup_written else None,
+            "content_hash": content_hash,
+            "activated_at": ts,
+            "actor_id": actor_id,
+        }
+
+    def rollback(self, skill_name: str) -> dict:
+        """Restore the live SKILL.md from the backup written by activate().
+
+        If no backup exists, removes the live file (the skill was new).
+        Never raises on missing backup — logs a warning instead.
+
+        Args:
+            skill_name: The original skill identifier, same value used in activate().
+        """
+        live_path = self._live_path(skill_name)
+        backup_path = self._backup_path(skill_name)
+        ts = datetime.now(timezone.utc).isoformat()
+
+        if backup_path.exists():
+            # Audit P2-4: restore atomically (tmp → os.replace) so a crash
+            # mid-rollback cannot leave a torn live SKILL.md.
+            live_path.parent.mkdir(parents=True, exist_ok=True)
+            tmp_path = live_path.with_suffix(".tmp")
+            tmp_path.write_bytes(backup_path.read_bytes())
+            os.replace(tmp_path, live_path)
+            logger.info(
+                "skill_activator: rolled back %s ← %s",
+                live_path, backup_path,
+            )
+            return {
+                "skill_name": skill_name,
+                "rolled_back": True,
+                "restored_from": str(backup_path),
+                "rolled_back_at": ts,
+            }
+        elif live_path.exists():
+            live_path.unlink()
+            logger.warning(
+                "skill_activator: no backup for %s; removed live file",
+                skill_name,
+            )
+            return {
+                "skill_name": skill_name,
+                "rolled_back": True,
+                "restored_from": None,
+                "note": "no backup; live file removed",
+                "rolled_back_at": ts,
+            }
+        else:
+            logger.warning(
+                "skill_activator: rollback called but no live file for %s",
+                skill_name,
+            )
+            return {
+                "skill_name": skill_name,
+                "rolled_back": False,
+                "note": "nothing to rollback",
+                "rolled_back_at": ts,
+            }