pari-cli 0.1.0__py3-none-any.whl

pari/providers/ollama.py

@@ -0,0 +1,25 @@
+"""PARI Providers: Local Ollama Adapter.
+
+Supports local models (Llama 3, Qwen 2.5 Coder, DeepSeek R1 distilled) via local HTTP endpoint.
+Allows 100% offline, private coding agent execution without external cloud tokens.
+"""
+
+from typing import Any, Dict, List, Optional
+from pari.providers.base import LLMProvider, ModelResponse, ProviderMessage
+
+
+class OllamaProvider(LLMProvider):
+    """Adapter for locally hosted Ollama instances."""
+
+    def __init__(self, model_name: str = "qwen2.5-coder:7b", base_url: str = "http://localhost:11434/v1"):
+        super().__init__(model_name, api_key="ollama")
+        self.base_url = base_url
+
+    async def complete(
+        self,
+        messages: List[ProviderMessage],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        temperature: float = 0.0,
+    ) -> ModelResponse:
+        """Call local Ollama endpoint."""
+        raise NotImplementedError

pari/providers/openai.py

@@ -0,0 +1,23 @@
+"""PARI Providers: OpenAI Adapter.
+
+Supports GPT-4o, o3-mini, and GPT-4.5 with function calling.
+"""
+
+from typing import Any, Dict, List, Optional
+from pari.providers.base import LLMProvider, ModelResponse, ProviderMessage
+
+
+class OpenAIProvider(LLMProvider):
+    """Adapter for OpenAI Chat Completions API."""
+
+    def __init__(self, model_name: str = "gpt-4o", api_key: Optional[str] = None):
+        super().__init__(model_name, api_key)
+
+    async def complete(
+        self,
+        messages: List[ProviderMessage],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        temperature: float = 0.0,
+    ) -> ModelResponse:
+        """Call OpenAI Chat Completions API."""
+        raise NotImplementedError

pari/routing/__init__.py

@@ -0,0 +1,16 @@
+"""PARI Layer 8: Dual-Model Routing Engine.
+
+Architectural Purpose:
+    Harvested from Aider's architect_coder.py and closes Antigravity F1 (planning token burn).
+    Reduces per-turn output costs by ~85%:
+    - Architect Model (Claude 3.7 Sonnet / o3-mini): Ingests context and emits a dense,
+      high-signal 300-token plan.
+    - Editor Model (Claude 3.5 Haiku / DeepSeek V3): Ingests the plan and emits mechanical diffs.
+
+Subsystems:
+    - router: Orchestrates the Architect-to-Editor pipeline
+    - classifier: Identifies simple/localized edits to bypass Architect overhead
+    - anti_verbosity: Enforces strict 4,096-token ceiling on reasoning to arrest planning loops
+"""
+
+# Placeholder imports will be exported once implementations are added

pari/routing/anti_verbosity.py

@@ -0,0 +1,13 @@
+"""PARI Layer 8: Anti-Verbosity Guard.
+
+Architectural Purpose:
+    Closes Google Antigravity F1 (200k-400k token burn on meta-planning).
+    Places a strict hard token ceiling (default 4,096 tokens) on the Architect model.
+    If the Architect fails to conclude its plan within 4k tokens, the output is cut
+    and dispatched immediately to the Editor model with instructions to execute
+    the partial plan, arresting recursive planning loops.
+"""
+
+def enforce_planning_ceiling(plan_text: str, max_tokens: int = 4096) -> str:
+    """Enforce token ceiling on architect reasoning output."""
+    raise NotImplementedError

pari/routing/classifier.py

@@ -0,0 +1,24 @@
+"""PARI Layer 8: Task Classifier.
+
+Architectural Purpose:
+    Evaluates incoming user prompts and active file scope.
+    If the task is simple (single file typo, localized test fix, doc update),
+    bypasses the Architect model entirely, saving both latency and token cost.
+"""
+
+from enum import Enum
+from typing import List
+
+
+class TaskComplexity(str, Enum):
+    SIMPLE_EDIT = "simple_edit"      # Bypass architect -> route directly to editor
+    ARCHITECTURAL = "architectural"  # Dual-model: Architect plan -> Editor diff
+
+
+class TaskClassifier:
+    """Classifies task complexity to select optimal routing pipeline."""
+
+    @staticmethod
+    def classify(prompt: str, active_files: List[str]) -> TaskComplexity:
+        """Classify task complexity based on intent keywords and scope."""
+        raise NotImplementedError

pari/routing/router.py

@@ -0,0 +1,23 @@
+"""PARI Layer 8: Dual-Model Router Pipeline.
+
+Coordinates prompt classification, architect plan generation, and editor execution.
+"""
+
+from typing import Any, Callable, Coroutine, List, Optional
+from pari.routing.classifier import TaskClassifier, TaskComplexity
+
+
+class DualModelRouter:
+    """Dispatches tasks across Architect and Editor model tiers."""
+
+    def __init__(
+        self,
+        architect_call: Optional[Callable[[str], Coroutine[Any, Any, str]]] = None,
+        editor_call: Optional[Callable[[str, Optional[str]], Coroutine[Any, Any, str]]] = None,
+    ):
+        self.architect_call = architect_call
+        self.editor_call = editor_call
+
+    async def route_and_execute(self, prompt: str, active_files: List[str]) -> str:
+        """Route prompt based on task complexity classification."""
+        raise NotImplementedError

pari/sandbox/__init__.py

@@ -0,0 +1,16 @@
+"""PARI Layer 0: Multi-Platform Kernel Sandboxing Engine.
+
+Architectural Purpose:
+    Closes Claude Code F2, Pi F1, Aider F1, and OpenCode F1.
+    Prevents hallucinated or prompt-injected destructive commands (e.g., rm -rf /)
+    from executing with host-user privileges.
+
+Subsystems:
+    - dispatcher: Automatically selects the most secure sandbox backend based on OS
+    - bwrap: Linux & Windows WSL2 bubblewrap container isolation (<5ms startup)
+    - seatbelt: macOS Apple Seatbelt (sandbox-exec + Scheme profile)
+    - e2b: Cloud microVM execution using Firecracker KVM
+    - process: Process-group supervision, die-with-parent lifecycle, and zombie reaping
+"""
+
+# Placeholder imports will be exported once implementations are added

pari/sandbox/base.py

@@ -0,0 +1,74 @@
+"""PARI Layer 0: Base Sandbox Interface.
+
+Defines the contract for all platform sandbox implementations (Bubblewrap, Seatbelt, E2B, ProcessGroup).
+All commands executed by PARI must run through an implementation of SandboxRunner.
+
+Guarantees:
+    1. Working directory isolation: Writes restricted to authorized workspace tree.
+    2. Die-with-parent lifecycle: Child processes killed when agent process terminates.
+    3. Resource bounding: Execution constrained by timeout, max output bytes, and memory.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Optional
+
+
+@dataclass
+class SandboxLimits:
+    """Resource constraints for sandboxed command execution.
+    
+    Fields:
+        timeout_seconds: Maximum allowed wall-clock run duration.
+        max_output_bytes: Ceiling for stdout/stderr spooling.
+        memory_limit_mb: cgroup ceiling on Linux.
+        allow_network: Policy toggle for network interface access.
+    """
+    timeout_seconds: float = 30.0
+    max_output_bytes: int = 50 * 1024
+    memory_limit_mb: int = 2048
+    allow_network: bool = True
+
+
+@dataclass
+class SandboxResult:
+    """Structured result from sandboxed command execution.
+    
+    Fields:
+        exit_code: Process return code.
+        stdout: Standard output string (truncated if exceeding limits).
+        stderr: Standard error string.
+        duration_seconds: Elapsed execution time.
+        timed_out: True if terminated by timeout.
+        truncated: True if output exceeded max_output_bytes.
+    """
+    exit_code: int
+    stdout: str
+    stderr: str
+    duration_seconds: float
+    timed_out: bool = False
+    truncated: bool = False
+
+
+class SandboxRunner(ABC):
+    """Abstract base class for all PARI kernel and cloud sandboxes."""
+
+    def __init__(self, workspace: Path, limits: Optional[SandboxLimits] = None):
+        # TODO: Initialize workspace path and enforce resource limits
+        pass
+
+    @abstractmethod
+    def run_command(
+        self,
+        command: str,
+        env: Optional[Dict[str, str]] = None,
+        timeout: Optional[float] = None,
+    ) -> SandboxResult:
+        """Execute a shell command inside the sandbox."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def cleanup(self) -> None:
+        """Terminate any lingering child processes, virtual mounts, or microVM instances."""
+        raise NotImplementedError

pari/sandbox/bwrap.py

@@ -0,0 +1,39 @@
+"""PARI Layer 0: Linux / WSL2 Bubblewrap Sandbox Runner.
+
+Architectural Purpose:
+    Harvested from Codex codex-bwrap.
+    Provides sub-5ms unprivileged user namespace isolation (zero root required).
+    Mounts root / as read-only, workspace as read-write, masks ~/.ssh, ~/.gnupg, and
+    drops network namespaces when network isolation is requested.
+
+Kernel Namespaces:
+    - CLONE_NEWUSER, CLONE_NEWNS, CLONE_NEWPID, CLONE_NEWIPC, CLONE_NEWUTS.
+    - Die-with-parent via bwrap --die-with-parent flag.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+from pari.sandbox.base import SandboxLimits, SandboxResult, SandboxRunner
+
+
+class BwrapSandboxRunner(SandboxRunner):
+    """Runs commands in an unprivileged Linux Bubblewrap (bwrap) sandbox."""
+
+    def __init__(self, workspace: Path, limits: Optional[SandboxLimits] = None):
+        super().__init__(workspace, limits)
+        # TODO: Verify 'bwrap' executable exists in PATH
+
+    def run_command(
+        self,
+        command: str,
+        env: Optional[Dict[str, str]] = None,
+        timeout: Optional[float] = None,
+    ) -> SandboxResult:
+        # TODO: Assemble bwrap CLI arguments:
+        # --die-with-parent, --ro-bind / /, --bind workspace workspace,
+        # mask sensitive directories (~/.ssh, ~/.gnupg), and spawn child process
+        raise NotImplementedError("Bwrap sandbox runner placeholder.")
+
+    def cleanup(self) -> None:
+        # TODO: Clean up any ephemeral mounts
+        pass

pari/sandbox/dispatcher.py

@@ -0,0 +1,31 @@
+"""PARI Layer 0: Sandbox Selection Dispatcher.
+
+Architectural Purpose:
+    Intelligently inspects the host platform and environment configuration
+    to select the most secure available sandbox engine:
+    1. Cloud mode -> E2B Firecracker MicroVM
+    2. Linux / WSL2 with bwrap -> Bubblewrap runner
+    3. macOS -> Apple Seatbelt runner
+    4. Fallback / Native Windows -> Supervised Process Group runner
+"""
+
+from pathlib import Path
+from typing import Optional
+from pari.sandbox.base import SandboxLimits, SandboxRunner
+
+
+def get_sandbox_runner(
+    workspace: Path,
+    limits: Optional[SandboxLimits] = None,
+    force_mode: Optional[str] = None,
+) -> SandboxRunner:
+    """Select and instantiate the appropriate sandbox runner for the current platform.
+    
+    TODO:
+    - Check force_mode or PARI_SANDBOX_MODE env var.
+    - If cloud -> E2BCloudSandboxRunner
+    - If Linux and bwrap in PATH -> BwrapSandboxRunner
+    - If macOS and sandbox-exec in PATH -> MacOSSeatbeltSandboxRunner
+    - Otherwise -> SupervisedProcessRunner fallback
+    """
+    raise NotImplementedError("Sandbox selection dispatcher placeholder.")

pari/sandbox/e2b.py

@@ -0,0 +1,32 @@
+"""PARI Layer 0: Cloud E2B Firecracker Sandbox Runner.
+
+Architectural Purpose:
+    Satisfies cloud microVM sandboxing using E2B Firecracker hardware KVM microVMs.
+    Bypasses weeks of custom hypervisor / vsock plumbing while guaranteeing full
+    kernel-level hardware virtualization for remote evaluation and cloud runs.
+"""
+
+from pathlib import Path
+from typing import Dict, Optional
+from pari.sandbox.base import SandboxLimits, SandboxResult, SandboxRunner
+
+
+class E2BCloudSandboxRunner(SandboxRunner):
+    """Executes commands inside an ephemeral E2B Firecracker Cloud microVM."""
+
+    def __init__(self, workspace: Path, limits: Optional[SandboxLimits] = None, api_key: Optional[str] = None):
+        super().__init__(workspace, limits)
+        # TODO: Initialize E2B Sandbox client with api_key
+
+    def run_command(
+        self,
+        command: str,
+        env: Optional[Dict[str, str]] = None,
+        timeout: Optional[float] = None,
+    ) -> SandboxResult:
+        # TODO: Execute command remotely inside Firecracker microVM
+        raise NotImplementedError("E2B cloud sandbox runner placeholder.")
+
+    def cleanup(self) -> None:
+        # TODO: Close remote microVM instance
+        pass

pari/sandbox/process.py

@@ -0,0 +1,38 @@
+"""PARI Layer 0: Process Group Supervisor & Fallback Runner.
+
+Architectural Purpose:
+    Closes Codex F5 (Orphaned exec-server processes) and provides the supervised
+    fallback runner when kernel sandbox utilities (bwrap/seatbelt) are absent.
+
+Features:
+    - Creates independent process groups using os.setsid() so child process trees
+      can be terminated cleanly as a unit (killpg).
+    - Sets PR_SET_PDEATHSIG on Linux so child processes terminate if the parent crashes.
+    - Prevents zombie process accumulation via signal handling and reaping.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+from pari.sandbox.base import SandboxLimits, SandboxResult, SandboxRunner
+
+
+class SupervisedProcessRunner(SandboxRunner):
+    """Supervised process runner using process-group tracking and path-guard boundaries."""
+
+    def __init__(self, workspace: Path, limits: Optional[SandboxLimits] = None):
+        super().__init__(workspace, limits)
+        # TODO: Initialize active PID tracking list
+
+    def run_command(
+        self,
+        command: str,
+        env: Optional[Dict[str, str]] = None,
+        timeout: Optional[float] = None,
+    ) -> SandboxResult:
+        # TODO: Execute command using subprocess.Popen with preexec_fn=os.setsid
+        # and enforce die-with-parent lifecycle + timeout handling
+        raise NotImplementedError("Supervised process runner placeholder.")
+
+    def cleanup(self) -> None:
+        # TODO: Terminate all recorded active process groups
+        pass

pari/sandbox/seatbelt.py

@@ -0,0 +1,32 @@
+"""PARI Layer 0: macOS Apple Seatbelt Sandbox Runner.
+
+Architectural Purpose:
+    Uses macOS sandbox-exec with an explicit TinyScheme profile.
+    Confines filesystem write operations strictly to the workspace directory.
+    Note: Expands explicit user home path since Seatbelt TinyScheme does not expand tilde (~).
+"""
+
+from pathlib import Path
+from typing import Dict, Optional
+from pari.sandbox.base import SandboxLimits, SandboxResult, SandboxRunner
+
+
+class MacOSSeatbeltSandboxRunner(SandboxRunner):
+    """Runs commands in an Apple Seatbelt sandbox via sandbox-exec."""
+
+    def __init__(self, workspace: Path, limits: Optional[SandboxLimits] = None):
+        super().__init__(workspace, limits)
+        # TODO: Verify 'sandbox-exec' exists in PATH
+
+    def run_command(
+        self,
+        command: str,
+        env: Optional[Dict[str, str]] = None,
+        timeout: Optional[float] = None,
+    ) -> SandboxResult:
+        # TODO: Generate TinyScheme profile restricting writes to workspace and /tmp,
+        # denying ~/.ssh, ~/.aws, ~/.gnupg access, and execute via sandbox-exec -f
+        raise NotImplementedError("macOS Seatbelt sandbox runner placeholder.")
+
+    def cleanup(self) -> None:
+        pass

pari/session/__init__.py

@@ -0,0 +1,15 @@
+"""PARI Layer 1: Durable Session Engine (Merkle DAG).
+
+Architectural Purpose:
+    Closes Claude Code F1 (No ACID state durability; 0-byte corrupt session file on SIGINT)
+    and Pi F4 / F5 (O(N) JSONL replay and mid-append torn-write truncation).
+
+Subsystems:
+    - events: Structured session event records (SESSION_START, USER_PROMPT, TOOL_CALL, etc.)
+    - logger: Append-only JSONL writer with CRC32 integrity check & torn-write recovery
+    - dag: Merkle DAG node tracking, parentId linking, and branch reconstruction
+    - checkpoint: Periodic index snapshots (every 50 turns) for O(1) state recovery
+    - undo: Bounded, guarded file rollback + child process termination + side effect report
+"""
+
+# Placeholder imports will be exported once implementations are added

pari/session/checkpoint.py

@@ -0,0 +1,24 @@
+"""PARI Layer 1: Checkpoint Index Manager.
+
+Architectural Purpose:
+    Closes Pi F4 (O(N) JSONL replay latency on deep 500+ turn sessions).
+    Periodically writes a CHECKPOINT index event (every 50 turns) containing the
+    active context state, file snapshot manifests, and token metrics.
+    Allows resuming a session by reading backward to the most recent checkpoint.
+"""
+
+from typing import Any, Dict, Optional
+from pari.session.logger import SessionLogger
+
+
+class CheckpointManager:
+    """Manages periodic checkpoint intervals for fast session resumption."""
+
+    def __init__(self, logger: SessionLogger, interval_turns: int = 50):
+        self.logger = logger
+        self.interval_turns = interval_turns
+        # TODO: Track turn count
+
+    def record_turn(self, state_snapshot: Dict[str, Any]) -> Optional[str]:
+        """Increment turn counter and trigger checkpoint write if interval is met."""
+        raise NotImplementedError

pari/session/dag.py

@@ -0,0 +1,34 @@
+"""PARI Layer 1: Merkle DAG Session Graph.
+
+Architectural Purpose:
+    Harvested from Pi's session-manager.ts.
+    Maintains session history as a Directed Acyclic Graph (DAG) using parentId references.
+    Enables non-linear branching, checkpoints, and causal traversal without in-memory state loss.
+"""
+
+from typing import Dict, List, Optional
+from pari.session.events import SessionEvent
+
+
+class DAGNode:
+    """Represents a node in the causal event Merkle DAG."""
+    def __init__(self, event: SessionEvent):
+        self.event = event
+        self.parent: Optional["DAGNode"] = None
+        self.children: List["DAGNode"] = []
+
+
+class SessionDAG:
+    """In-memory DAG index over the immutable session event stream."""
+
+    def __init__(self):
+        # TODO: Initialize node map and head/root pointers
+        pass
+
+    def add_event(self, event: SessionEvent) -> DAGNode:
+        """Insert event into DAG and link parent/child pointers."""
+        raise NotImplementedError
+
+    def get_lineage(self, leaf_id: Optional[str] = None) -> List[SessionEvent]:
+        """Traverse backwards from leaf to root to reconstruct the linear event thread."""
+        raise NotImplementedError

pari/session/events.py

@@ -0,0 +1,50 @@
+"""PARI Layer 1: Structured Session Event Types.
+
+Defines all immutable event records logged into the append-only Merkle DAG.
+Each event possesses a unique record ID, timestamp, and an optional parent_id
+forming an unbroken causal Merkle chain.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, Optional
+
+
+class SessionEventType(str, Enum):
+    SESSION_START = "session_start"
+    USER_PROMPT = "user_prompt"
+    ASSISTANT_RESPONSE = "assistant_response"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    FILE_SNAPSHOT = "file_snapshot"
+    CHECKPOINT = "checkpoint"
+    SESSION_END = "session_end"
+
+
+@dataclass
+class SessionEvent:
+    """An individual event entry in the session Merkle DAG.
+    
+    Fields:
+        type: Event category
+        payload: Event data dictionary
+        id: Unique UUID identifier
+        parent_id: ID of preceding causal event
+        timestamp: Epoch timestamp
+        crc32: Integrity checksum
+    """
+    type: SessionEventType
+    payload: Dict[str, Any]
+    id: Optional[str] = None
+    parent_id: Optional[str] = None
+    timestamp: float = 0.0
+    crc32: Optional[int] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert event to serializable dictionary."""
+        raise NotImplementedError
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "SessionEvent":
+        """Reconstruct event from serialized dictionary."""
+        raise NotImplementedError

pari/session/logger.py

@@ -0,0 +1,41 @@
+"""PARI Layer 1: Append-Only JSONL Session Logger.
+
+Architectural Purpose:
+    Closes Claude Code F1 & Pi F5.
+    Writes every session event with an explicit CRC32 checksum, flushes to OS buffer,
+    and calls os.fsync() on critical milestones.
+    On startup, scans backward from EOF to automatically detect and truncate torn writes
+    caused by power loss or sudden SIGKILL.
+"""
+
+from pathlib import Path
+from typing import Any, Dict, Iterator, List, Optional
+from pari.session.events import SessionEvent, SessionEventType
+
+
+class SessionLogger:
+    """Manages an append-only JSONL session log with CRC32 integrity verification."""
+
+    def __init__(self, session_file: Path):
+        self.session_file = session_file
+        # TODO: Initialize file path and perform backward recovery scan for torn writes
+
+    def _recover_and_index(self) -> None:
+        """Scan session file, recover from torn writes at EOF, and locate the last record ID."""
+        raise NotImplementedError("Torn write recovery placeholder.")
+
+    def log(self, event_type: SessionEventType, payload: Dict[str, Any]) -> SessionEvent:
+        """Append a new verified session event to disk with CRC32 checksum."""
+        raise NotImplementedError("Session logging placeholder.")
+
+    def append_event(self, event_type: str, data: Dict[str, Any]) -> str:
+        """Legacy append API."""
+        raise NotImplementedError
+
+    def read_events(self) -> List[Dict[str, Any]]:
+        """Read all verified records from the session file."""
+        raise NotImplementedError
+
+    def iter_events(self) -> Iterator[SessionEvent]:
+        """Iterate over all valid events in chronological order."""
+        raise NotImplementedError

pari/session/undo.py

@@ -0,0 +1,99 @@
+"""PARI Layer 1: Guarded Undo Manager.
+
+Architectural Purpose:
+    Implements a safe, bounded /undo mechanism:
+    1. Restores files modified by the most recent turn.
+    2. Guarded check: If the developer manually edited the file after PARI touched it,
+       aborts or prompts to prevent accidental overwrite of user work.
+    3. Terminates background processes started during the turn.
+    4. Explicit disclosure: Informs user that external side effects (API calls, remote DBs,
+       pip install) are logged but not automatically reversible.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List
+
+
+@dataclass
+class FileSnapshot:
+    """Pre- and post-edit file hash snapshot."""
+    rel_path: str
+    pre_edit_content: str
+    pre_edit_hash: str
+    post_edit_hash: str
+
+
+@dataclass
+class UndoResult:
+    """Outcome of guarded undo execution."""
+    reverted_files: List[str]
+    conflicted_files: List[str]
+    terminated_processes: int
+    disclosed_side_effects: List[str]
+
+
+import hashlib
+from typing import Dict, List
+from pari.fs.atomic import atomic_write, read_file
+from pari.fs.path import resolve_safe_path
+
+
+class GuardedUndoManager:
+    """Provides guarded rollback for physical file changes and process termination."""
+
+    def __init__(self, workspace: Path):
+        self.workspace = workspace.resolve()
+        self.snapshots: Dict[str, FileSnapshot] = {}
+        self.side_effects: List[str] = []
+
+    def _hash(self, content: str) -> str:
+        return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+    def record_snapshot(self, rel_path: str, pre_content: str, post_content: str):
+        """Record file state prior to write mutation."""
+        self.snapshots[rel_path] = FileSnapshot(
+            rel_path=rel_path,
+            pre_edit_content=pre_content,
+            pre_edit_hash=self._hash(pre_content),
+            post_edit_hash=self._hash(post_content),
+        )
+
+    def record_side_effect(self, description: str):
+        """Log external irreversible side effect (e.g. package install, DB migration)."""
+        self.side_effects.append(description)
+
+    def undo(self, force: bool = False) -> UndoResult:
+        """Execute guarded rollback verifying files haven't drifted."""
+        reverted: List[str] = []
+        conflicts: List[str] = []
+
+        for rel_path, snapshot in list(self.snapshots.items()):
+            file_path = resolve_safe_path(self.workspace, rel_path)
+            if not file_path.exists():
+                atomic_write(file_path, snapshot.pre_edit_content)
+                reverted.append(rel_path)
+                continue
+
+            current_content = read_file(file_path)
+            current_hash = self._hash(current_content)
+
+            if current_hash == snapshot.post_edit_hash or force:
+                atomic_write(file_path, snapshot.pre_edit_content)
+                reverted.append(rel_path)
+            else:
+                conflicts.append(rel_path)
+
+        # Clear reverted snapshots
+        for rel in reverted:
+            self.snapshots.pop(rel, None)
+
+        result = UndoResult(
+            reverted_files=reverted,
+            conflicted_files=conflicts,
+            terminated_processes=0,
+            disclosed_side_effects=list(self.side_effects),
+        )
+        self.side_effects.clear()
+        return result
+