expluro 0.2.0__tar.gz → 0.3.0__tar.gz

{expluro-0.2.0 → expluro-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: expluro
-Version: 0.2.0
+Version: 0.3.0
 Summary: Expluro CLI — graph layer on top of your AI agent
 Requires-Python: >=3.10
 Requires-Dist: claude-agent-sdk>=0.0.1

{expluro-0.2.0 → expluro-0.3.0}/expluro.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: expluro
-Version: 0.2.0
+Version: 0.3.0
 Summary: Expluro CLI — graph layer on top of your AI agent
 Requires-Python: >=3.10
 Requires-Dist: claude-agent-sdk>=0.0.1

{expluro-0.2.0 → expluro-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "expluro"
-version = "0.2.0"
+version = "0.3.0"
 description = "Expluro CLI — graph layer on top of your AI agent"
 requires-python = ">=3.10"
 dependencies = [

{expluro-0.2.0 → expluro-0.3.0}/topo/capture.py

@@ -27,6 +27,7 @@ from .constants import APP_DIR
 if TYPE_CHECKING:
     from .backend import BackendClient
     from .drivers.base import BaseDriver, DriverEvent, ToolHookPayload
+    from .snapshot import SnapshotManager
 
 logger = logging.getLogger(__name__)
 
@@ -56,10 +57,16 @@ class EventCapture:
         backend: "BackendClient",
         graph_id: str,
         node_id: str,
+        snapshot_manager: "SnapshotManager | None" = None,
     ) -> None:
         self._backend = backend
         self._graph_id = graph_id
         self._node_id = node_id
+        # Optional — when present, every side-effecting tool call gets a
+        # filesystem snapshot committed to a shadow git repo and the resulting
+        # commit hash + diff summary attached to the post_tool_use event.
+        # Powers `/branch` and `/checkout` filesystem rewind.
+        self._snapshot_manager: "SnapshotManager | None" = snapshot_manager
         self._last_event_id: str | None = None
         # Accumulated streaming text for the current turn.
         # Flushed as message_ai on turn_result if text_complete never fires
@@ -297,16 +304,44 @@ class EventCapture:
 
     async def _on_post_tool(self, payload: "ToolHookPayload") -> None:
         is_side_effecting = payload.tool_name in SIDE_EFFECTING_TOOLS
+
+        # Snapshot the filesystem after a side-effecting tool. Even tools we
+        # think are read-only sometimes touch state (e.g. Bash that runs a
+        # build, Grep with --rewrite), so we let the SnapshotManager dedupe:
+        # if nothing changed, the commit is a no-op and returns the existing
+        # HEAD hash. Diff summary is attached to the event for browser display.
+        snapshot_hash: str | None = None
+        diff_summary: dict | None = None
+        if is_side_effecting and self._snapshot_manager is not None:
+            try:
+                snapshot_hash, diff_summary = await self._snapshot_manager.commit(
+                    label=f"{payload.tool_name} {payload.tool_use_id[:8]}",
+                )
+            except Exception:
+                logger.exception("snapshot commit failed for %s", payload.tool_name)
+
+        event_data: dict[str, Any] = {
+            "tool_output": _truncate(payload.tool_output),
+            "is_error": payload.is_error,
+            "is_side_effecting": is_side_effecting,
+        }
+        if snapshot_hash:
+            event_data["snapshot_hash"] = snapshot_hash
+        if diff_summary:
+            event_data["diff_summary"] = diff_summary
+
         event = self._build_event(
             event_type="post_tool_use",
             tool_name=payload.tool_name,
             tool_use_id=payload.tool_use_id,
-            data={
-                "tool_output": _truncate(payload.tool_output),
-                "is_error": payload.is_error,
-                "is_side_effecting": is_side_effecting,
-            },
+            data=event_data,
         )
+        # The Event model has a snapshot_hash field — the backend pulls it
+        # from the top level of the request payload, not from `data`. Set it
+        # here so it lands in the indexed column, not just the JSON blob.
+        if snapshot_hash:
+            event["snapshot_hash"] = snapshot_hash
+
         if self._pending_user_message_text is not None:
             self._buffered_hook_events.append(event)
             return

{expluro-0.2.0 → expluro-0.3.0}/topo/drivers/_branch_detection.py

@@ -83,8 +83,17 @@ def parse_branch_flag(buffered_head: str) -> tuple[float | None, str]:
     Returns (confidence, remaining_text). When the head doesn't start with
     a valid tag, confidence is None and the entire buffered_head is
     returned as remaining_text — caller should treat it as regular content.
+
+    If the tag matches structurally but the digits are malformed (e.g.
+    `<!--BRANCH:.-->`), we still consume the tag bytes from the remaining
+    text but return None for confidence. That way a weird model emission
+    can't leak the tag to the user OR crash the dispatcher.
     """
     m = BRANCH_FLAG_START_RE.match(buffered_head)
-    if m:
-        return float(m.group(1)), buffered_head[m.end():]
-    return None, buffered_head
+    if not m:
+        return None, buffered_head
+    try:
+        confidence = float(m.group(1))
+    except ValueError:
+        return None, buffered_head[m.end():]
+    return confidence, buffered_head[m.end():]

{expluro-0.2.0 → expluro-0.3.0}/topo/drivers/_permissions.py

@@ -18,6 +18,7 @@ from __future__ import annotations
 import logging
 from dataclasses import dataclass, field
 from enum import Enum
+from html import escape as _html_escape
 from typing import Any
 
 logger = logging.getLogger(__name__)
@@ -72,24 +73,44 @@ async def ask_user_for_permission(
     """
     # Late imports to avoid cycles with picker / renderer at module-load time.
     from ..picker import pick_option
-    from ..renderer import pause_active_spinner, resume_active_spinner
+    from ..renderer import (
+        pause_active_md_stream,
+        pause_active_spinner,
+        resume_active_spinner,
+    )
+
+    # prompt_toolkit's HTML(...) is strict XML; any literal `&`, `<`, `>`
+    # or quote in agent-provided text (Kiro tool titles like
+    # "Run command: cat /etc/hosts 2>&1" — note the bare `&`) crashes the
+    # picker with an ExpatError, the wrapper deny-fails closed, and the
+    # user sees no prompt at all. Escape user/agent-provided substrings
+    # before embedding them inside our HTML-formatted picker text.
+    safe_tool_name = _html_escape(tool_name)
+    safe_summary = _html_escape(summary) if summary else ""
 
     summary_line = (
-        f"\n  <ansibrightblack>  {summary}</ansibrightblack>" if summary else ""
+        f"\n  <ansibrightblack>  {safe_summary}</ansibrightblack>" if safe_summary else ""
     )
     header = (
-        f"  <ansicyan>⚙ {tool_name}</ansicyan>  "
+        f"  <ansicyan>⚙ {safe_tool_name}</ansicyan>  "
         f"<ansibrightblack>wants to run:</ansibrightblack>{summary_line}"
     )
 
     options: list[tuple[str, str]] = [
         ("Allow", "allow"),
-        (f"Always allow {tool_name}", "always"),
+        (f"Always allow {safe_tool_name}", "always"),
         ("Deny", "deny"),
         ("Bypass all checks", "bypass"),
     ]
 
+    # Hand the terminal off to prompt_toolkit cleanly: stop the spinner and
+    # flush+stop any active rich.Live markdown stream. If we skip the
+    # md-stream flush, an in-progress streaming response will keep
+    # repainting the cursor area on every refresh tick and the picker is
+    # invisible — the user thinks the agent went silent, but the agent is
+    # actually waiting on an approval that never gets a chance to render.
     pause_active_spinner()
+    pause_active_md_stream()
     try:
         result = await pick_option(header, options)
     except KeyboardInterrupt:

{expluro-0.2.0 → expluro-0.3.0}/topo/drivers/acp.py

@@ -45,6 +45,7 @@ from acp.schema import AllowedOutcome, DeniedOutcome
 
 from ._branch_detection import (
     BRANCH_DETECTION_INSTRUCTION,
+    BRANCH_FLAG_START_RE,
     HEAD_BUFFER_MAX,
     parse_branch_flag,
 )
@@ -103,15 +104,19 @@ class ACPDriver(BaseDriver):
         # Permission tracking. always_allowed survives across branches;
         # bypass_all is reset on branch switch (see reset_context).
         self._permission_state: PermissionState = PermissionState()
-        # Auto-branch head buffering. Per-turn state: accumulate the start of
-        # the streamed text response until we either see a newline or hit
-        # HEAD_BUFFER_MAX, then parse for the BRANCH:X.XX tag and emit a
-        # branch_signal event. Reset at the top of each _run_prompt.
-        # If a tool call arrives before any text, we treat the head as
-        # already resolved (no tag, no branch fire) so subsequent text
-        # streams through normally.
+        # Auto-branch head buffering. Per-segment state: accumulate the
+        # start of each streamed text segment until we either see a newline
+        # or hit HEAD_BUFFER_MAX, then parse for the BRANCH:X.XX tag.
+        # A "segment" begins at turn start AND after every tool call, because
+        # Kiro re-emits the tag at the head of post-tool text. Resetting the
+        # head buffer per segment is what catches chunked tags
+        # (`<!--BRANCH:0.10` + `-->...`) that a single regex sub on one chunk
+        # would miss.
+        # branch_signal only fires once per turn even if Kiro repeats the
+        # tag — we use the very first parse as authoritative.
         self._head_buf: str = ""
         self._head_parsed: bool = False
+        self._branch_signal_fired_this_turn: bool = False
 
     # ------------------------------------------------------------------
     # Lifecycle
@@ -371,10 +376,10 @@ class ACPDriver(BaseDriver):
             except asyncio.QueueEmpty:
                 break
 
-        # Reset auto-branch head state at the start of every turn — the
-        # response we're about to receive should begin with the BRANCH tag.
+        # Reset auto-branch head state at the start of every turn.
         self._head_buf = ""
         self._head_parsed = False
+        self._branch_signal_fired_this_turn = False
 
         # Fire-and-forget the prompt as a background task. The connection's
         # `prompt()` returns a PromptResponse when the agent finishes. We
@@ -400,6 +405,12 @@ class ACPDriver(BaseDriver):
                 session_id=self._session_id,
                 prompt=[text_block(framed_prompt)],
             )
+            # Flush any text still pending in the head buffer. Short post-
+            # tool responses (e.g. "Your username is yab", 21 chars, no
+            # newline) never trip the size/newline thresholds during
+            # streaming and would otherwise be lost when the turn ends.
+            assert self._session_id is not None
+            await self._flush_head_buffer(self._session_id)
             # Emit a result event capturing usage if present, then end-of-turn.
             data: dict[str, Any] = {}
             if response is not None:
@@ -435,12 +446,11 @@ class ACPDriver(BaseDriver):
         """
         Text-streaming entry point with auto-branch head buffering.
 
-        Buffers the very first chunk(s) of each turn until we see a newline
-        or hit HEAD_BUFFER_MAX, then parses for the BRANCH tag. If found,
-        emits a `branch_signal` event before any visible text — session.py
-        can then decide whether to fork at this exact moment, before the
-        renderer prints anything. After the head is resolved (with or
-        without a tag), text streams through normally.
+        Buffers the start of each text segment (turn-start, or post-tool
+        re-entry) until we see a newline or hit HEAD_BUFFER_MAX, then
+        delegates to _flush_head_buffer for tag parsing + emission. That
+        helper centralises the multi-tag, partial-tag, and malformed-tag
+        defenses so this handler stays a thin entry point.
         """
         if self._head_parsed:
             await self._emit(
@@ -454,45 +464,89 @@ class ACPDriver(BaseDriver):
             return
 
         self._head_parsed = True
-        confidence, remaining = parse_branch_flag(self._head_buf)
+        await self._flush_head_buffer(session_id)
+
+    async def _flush_head_buffer(self, session_id: str) -> None:
+        """
+        Drain the current head buffer (if any), emitting at most one
+        branch_signal event (only on the first parsed tag of the turn) and
+        a text event for whatever non-tag content remains.
+
+        Called from two sites:
+          1. _resolve_head_for_non_text — when a tool call arrives.
+          2. End of _run_prompt — when the turn finishes, to ensure any
+             short post-tool text response (e.g. "Your username is yab"
+             with no newline) doesn't get stuck in the buffer and lost.
+
+        Defensive against three model misbehaviours:
+          - Multiple stacked tags (`<!--BRANCH:0.0--><!--BRANCH:0.5-->Hi`):
+            strip ALL leading tags, not just the first, so none leak.
+          - Partial tag at flush time (`<!--BRANCH:0.5` with no `-->`):
+            happens if a tool call interrupts mid-tag-stream. Drop the
+            partial-tag bytes rather than emitting them as visible text.
+          - Malformed digits (`<!--BRANCH:.-->`): handled inside
+            parse_branch_flag — the tag is consumed, no confidence
+            recorded.
+
+        Caller is responsible for resetting `_head_parsed` after this if
+        appropriate. We deliberately do not reset state here so the
+        function is reusable.
+        """
+        if not self._head_buf:
+            return
+        buf = self._head_buf
         self._head_buf = ""
-        if confidence is not None:
-            logger.debug("ACPDriver: branch tag parsed (confidence=%.2f)", confidence)
+
+        first_confidence: float | None = None
+        # Strip every leading tag. Defensive against double-emission.
+        while True:
+            confidence, rest = parse_branch_flag(buf)
+            if confidence is None and rest == buf:
+                # No tag matched at all — buf is plain content.
+                break
+            # A tag was consumed (confidence may still be None if the
+            # tag's digits were malformed). Capture the first valid
+            # confidence we see.
+            if first_confidence is None and confidence is not None:
+                first_confidence = confidence
+            buf = rest
+            if not buf:
+                break
+
+        # If the buffer is now a partial tag prefix (no closing `-->`),
+        # the model started a tag we never saw the end of. Drop it
+        # rather than leak `<!--BRANCH:0.5` to the renderer.
+        if buf.startswith("<!--BRANCH:") and "-->" not in buf:
+            buf = ""
+
+        if first_confidence is not None and not self._branch_signal_fired_this_turn:
+            self._branch_signal_fired_this_turn = True
             await self._emit(
                 DriverEvent(
                     type="branch_signal",
-                    data={"confidence": confidence, "session_id": session_id},
-                    raw=raw,
+                    data={"confidence": first_confidence, "session_id": session_id},
+                    raw=None,
                 )
             )
-            if remaining:
-                await self._emit(
-                    DriverEvent(type="text", data={"text": remaining, "session_id": session_id}, raw=raw)
-                )
-        else:
-            # No tag — flush whatever buffered as regular text so nothing is
-            # silently dropped even if the model ignored the instruction.
-            if remaining:
-                await self._emit(
-                    DriverEvent(type="text", data={"text": remaining, "session_id": session_id}, raw=raw)
-                )
+        if buf:
+            await self._emit(
+                DriverEvent(type="text", data={"text": buf, "session_id": session_id}, raw=None)
+            )
 
     async def _resolve_head_for_non_text(self, session_id: str) -> None:
         """
-        Mark the head as resolved when a non-text event (tool call) arrives
-        before any AgentMessageChunk. Flushes any buffered partial text as
-        regular text so it isn't silently lost. No branch_signal can fire
-        at this point because we never saw a tag.
+        Called when a non-text event (tool call) arrives. Flushes any
+        buffered head text and resets so the next text segment re-enters
+        tag parsing.
+
+        That re-entry is what catches Kiro's habit of repeating the
+        BRANCH tag at the head of each post-tool text segment, including
+        when the tag is split across multiple stream chunks (a single
+        regex sub on one chunk would miss the second half).
         """
-        if self._head_parsed:
-            return
-        self._head_parsed = True
-        if self._head_buf:
-            buffered = self._head_buf
-            self._head_buf = ""
-            await self._emit(
-                DriverEvent(type="text", data={"text": buffered, "session_id": session_id}, raw=None)
-            )
+        await self._flush_head_buffer(session_id)
+        # Reset for the next text segment so it re-enters head parsing.
+        self._head_parsed = False
 
     async def _fire_pre_tool_hook(self, payload: ToolHookPayload) -> None:
         for cb in self._pre_tool_hooks:
@@ -666,6 +720,33 @@ class _ACPClient(Client):
             await self._driver._emit(
                 DriverEvent(type="tool_use", data=event_data, raw=update)
             )
+            # Fast tools (Kiro's `read` for small files, for example) emit a
+            # single ToolCallStart with status already "completed" or
+            # "failed" and never send a follow-up ToolCallProgress. If we
+            # only emit tool_use the browser shows the call as "running…"
+            # forever. Emit tool_result inline when the start update is
+            # already terminal.
+            start_status = getattr(update, "status", None)
+            if start_status is not None and str(start_status).lower() in ("completed", "failed"):
+                tool_output = _extract_tool_output(update)
+                is_error = str(start_status).lower() == "failed"
+                payload_out = self._driver._active_tool_calls.pop(tool_use_id, None)
+                if payload_out is not None:
+                    payload_out.tool_output = tool_output
+                    payload_out.is_error = is_error
+                    await self._driver._fire_post_tool_hook(payload_out)
+                await self._driver._emit(
+                    DriverEvent(
+                        type="tool_result",
+                        data={
+                            "tool_use_id": tool_use_id,
+                            "tool_output": tool_output,
+                            "is_error": is_error,
+                            "session_id": session_id,
+                        },
+                        raw=update,
+                    )
+                )
             return
 
         if isinstance(update, ToolCallProgress):

{expluro-0.2.0 → expluro-0.3.0}/topo/picker.py

@@ -1,9 +1,16 @@
 """
 picker.py — Arrow-key pickers for session selection and permission prompts.
+
+prompt_toolkit's HTML(...) is strict XML, so any literal `&`, `<`, `>`, or
+quote in user/agent-provided text (graph names, node labels, message bodies,
+tool titles) crashes the picker with an ExpatError. We escape every such
+substring before embedding it into the HTML format strings below. Static
+markup (tags like <ansicyan>...</ansicyan>) is hand-written and stays raw.
 """
 from __future__ import annotations
 
 import datetime
+from html import escape as _html_escape
 from typing import Any
 
 from prompt_toolkit import Application
@@ -87,13 +94,16 @@ async def pick_node(nodes: list[dict[str, Any]], has_more: bool, current_node_id
                 is_current = choice.get("id") == current_node_id
                 label = choice.get("label") or "(untitled)"
                 truncated = label[:52] + ("…" if len(label) > 52 else "")
+                # Node labels can contain `&`, `<`, `>` (assistant-generated
+                # summaries often do). Escape before embedding in HTML.
+                safe_truncated = _html_escape(truncated)
                 node_id_short = str(choice.get("id", ""))[:8]
                 status = choice.get("status", "active")
                 sc = STATUS_COLOR.get(status, "ansibrightblack")
                 msg_count = len(choice.get("materialized_context", []))
                 time_str = _relative_time(choice.get("updated_at", ""))
                 current_tag = "  <ansibrightblack>(current)</ansibrightblack>" if is_current else ""
-                label_fmt = f"<ansiwhite><b>{truncated}</b></ansiwhite>" if selected else f"<ansiwhite>{truncated}</ansiwhite>"
+                label_fmt = f"<ansiwhite><b>{safe_truncated}</b></ansiwhite>" if selected else f"<ansiwhite>{safe_truncated}</ansiwhite>"
                 lines.append(f"  {cursor}{label_fmt}{current_tag}\n")
                 time_part = f"  ·  {time_str}" if time_str else ""
                 lines.append(f"       <ansibrightblack>{node_id_short}  ·  <{sc}>{status}</{sc}>  ·  {msg_count} msg{'s' if msg_count != 1 else ''}{time_part}</ansibrightblack>\n\n")
@@ -155,15 +165,19 @@ async def pick_message(context: list[dict[str, Any]]) -> int | None:
         for i, msg in enumerate(reversed_ctx):
             role = msg.get("role", "user")
             content = (msg.get("content") or "").replace("\n", " ").strip()
+            # Message bodies routinely contain `<`, `>`, `&` (code snippets,
+            # diffs, shell commands). Escape before HTML interpolation.
+            preview = content[:64] + ("…" if len(content) > 64 else "")
+            safe_preview = _html_escape(preview)
             is_active = i == active_display_idx
             if role == "assistant":
                 cursor = "<ansiwhite>▶ </ansiwhite>" if is_active else "  "
                 role_fmt = "<ansigreen>[assistant]</ansigreen>"
-                text_fmt = f"<ansiwhite><b>{content[:64]}{'…' if len(content) > 64 else ''}</b></ansiwhite>" if is_active else f"<ansiwhite>{content[:64]}{'…' if len(content) > 64 else ''}</ansiwhite>"
+                text_fmt = f"<ansiwhite><b>{safe_preview}</b></ansiwhite>" if is_active else f"<ansiwhite>{safe_preview}</ansiwhite>"
                 lines.append(f"  {cursor}{role_fmt}  {text_fmt}\n\n")
             else:
                 # User message — display only, dimmed, no cursor
-                lines.append(f"     <ansibrightblack>[user]  {content[:64]}{'…' if len(content) > 64 else ''}</ansibrightblack>\n\n")
+                lines.append(f"     <ansibrightblack>[user]  {safe_preview}</ansibrightblack>\n\n")
         lines.append("  <ansibrightblack>↑/↓ to navigate · Enter to branch here · Ctrl+C to cancel</ansibrightblack>\n")
         return HTML("".join(lines))
 
@@ -248,9 +262,11 @@ async def pick_session(graphs: list[dict[str, Any]]) -> dict[str, Any] | None:
                 lines.append(f"  {cursor}{label}\n")
             else:
                 name = choice.get("name", "Untitled")
+                # Graph names are user-controlled; escape before embedding.
+                safe_name = _html_escape(name)
                 updated = _relative_time(choice.get("updated_at", ""))
                 active_node = choice.get("active_node")
-                name_fmt = f"<ansiwhite><b>{name}</b></ansiwhite>" if selected else f"<ansiwhite>{name}</ansiwhite>"
+                name_fmt = f"<ansiwhite><b>{safe_name}</b></ansiwhite>" if selected else f"<ansiwhite>{safe_name}</ansiwhite>"
                 time_fmt = f"<ansibrightblack>{updated}</ansibrightblack>" if updated else ""
                 # Line 1: graph name + last active time
                 lines.append(f"  {cursor}{name_fmt}    {time_fmt}\n")
@@ -258,8 +274,11 @@ async def pick_session(graphs: list[dict[str, Any]]) -> dict[str, Any] | None:
                 if active_node and active_node.get("label"):
                     node_lbl = active_node["label"]
                     truncated = node_lbl[:60] + ("…" if len(node_lbl) > 60 else "")
+                    # Node labels are assistant-generated and routinely
+                    # contain HTML-unsafe characters; escape.
+                    safe_truncated = _html_escape(truncated)
                     node_id_short = active_node["id"][:8]
-                    lines.append(f"       <ansibrightblack>↳ resume node {node_id_short}  ·  \"{truncated}\"</ansibrightblack>\n")
+                    lines.append(f"       <ansibrightblack>↳ resume node {node_id_short}  ·  \"{safe_truncated}\"</ansibrightblack>\n")
                 elif active_node:
                     node_id_short = active_node["id"][:8]
                     lines.append(f"       <ansibrightblack>↳ resume node {node_id_short}  ·  (untitled)</ansibrightblack>\n")

{expluro-0.2.0 → expluro-0.3.0}/topo/renderer.py

@@ -168,11 +168,26 @@ class _MarkdownStreamState:
 
 
 # ---------------------------------------------------------------------------
-# Module-level spinner control — lets the driver pause the spinner before
-# showing a permission prompt so the two don't race on stdout.
+# Module-level pause/resume hooks for interactive UI overlays (permission
+# pickers, in-line confirmations) that need to take over the terminal.
+#
+# Two pieces of in-flight terminal state can collide with a prompt_toolkit
+# Application:
+#   1. The turn-level spinner thread (rewrites the same line).
+#   2. The streaming-markdown rich.Live context, which owns the cursor for
+#      partial re-renders. If a picker tries to render while rich.Live is
+#      mid-refresh, prompt_toolkit's draw is overwritten on the next Live
+#      tick and the picker is invisible to the user — the visible symptom
+#      is "the agent went silent" because the user never sees a prompt to
+#      approve and the agent is sitting on a permission request.
+#
+# pause_* committs/stops both pieces; resume_* restarts only the spinner
+# (the markdown stream restarts itself the next time a chunk arrives, so
+# there's nothing to resume there).
 # ---------------------------------------------------------------------------
 
 _active_spinner: _Spinner | None = None
+_active_md_stream: _MarkdownStreamState | None = None
 
 
 def pause_active_spinner() -> None:
@@ -185,6 +200,15 @@ def resume_active_spinner() -> None:
         _active_spinner.resume()
 
 
+def pause_active_md_stream() -> None:
+    """Flush and stop the streaming markdown rich.Live so a prompt_toolkit
+    picker can take over the terminal cleanly. Already-rendered text stays
+    committed above; the next text chunk after the picker exits will start
+    a fresh Live below it."""
+    if _active_md_stream is not None:
+        _active_md_stream.flush()
+
+
 # ---------------------------------------------------------------------------
 # TerminalRenderer — main public class
 # ---------------------------------------------------------------------------
@@ -199,8 +223,14 @@ class TerminalRenderer:
     """
 
     def __init__(self) -> None:
+        global _active_md_stream
         self._spinner: _Spinner | None = None
         self._md = _MarkdownStreamState()
+        # Register the markdown stream so pause_active_md_stream() can
+        # flush it ahead of any interactive picker. The renderer is a
+        # singleton per session, so this assignment is safe to leave in
+        # place for the lifetime of the process.
+        _active_md_stream = self._md
         self._spinner_active = False
 
     # ------------------------------------------------------------------

{expluro-0.2.0 → expluro-0.3.0}/topo/session.py

@@ -37,6 +37,7 @@ from .drivers.acp import ACPDriver, AgentLaunchError
 from .drivers.claude import ClaudeDriver
 from .picker import pick_session, pick_node, pick_message
 from .renderer import TerminalRenderer, pause_active_spinner, resume_active_spinner
+from .snapshot import SnapshotManager
 
 logger = logging.getLogger(__name__)
 console = Console()
@@ -128,6 +129,24 @@ async def _run(driver_name: str, cwd: str, no_browser: bool = False) -> None:
         await backend.aclose()
         return
 
+    # ----------------------------------------------------------------
+    # World-state snapshots — shadow git repo for filesystem state per graph.
+    # One shadow repo per graph_id (not per project path) so explicit "+ Start
+    # new session" gives a clean filesystem slate too. Resuming the same graph
+    # reuses the same shadow.
+    # ----------------------------------------------------------------
+    snapshot_manager: SnapshotManager | None = None
+    try:
+        snapshot_manager = SnapshotManager(cwd, graph_id)
+        await snapshot_manager.init()
+    except Exception:
+        # Snapshot subsystem is best-effort — never block the session on it.
+        # Common reasons it fails: git not on PATH, cwd not writable, broken
+        # shadow repo. Log loudly but continue without snapshots; /branch
+        # and /checkout will fall back to conversation-only forking.
+        logger.exception("SnapshotManager: init failed — snapshots disabled this session")
+        snapshot_manager = None
+
     # ----------------------------------------------------------------
     # Wire up event capture
     # ----------------------------------------------------------------
@@ -135,6 +154,7 @@ async def _run(driver_name: str, cwd: str, no_browser: bool = False) -> None:
         backend=backend,
         graph_id=graph_id,
         node_id=node_id,
+        snapshot_manager=snapshot_manager,
     )
 
     # Shared state for branch switching — written by WS listener, read by REPL
@@ -238,10 +258,20 @@ async def _run(driver_name: str, cwd: str, no_browser: bool = False) -> None:
     _toolbar_style = Style.from_dict({'bottom-toolbar': 'bg:default fg:ansibrightblack noreverse'})
 
     def _toolbar() -> HTML:
+        # Node labels are user prompts and assistant-generated summaries —
+        # both routinely contain `&`, `<`, `>` that would crash prompt_toolkit's
+        # HTML parser. Escape before embedding. Otherwise the toolbar redraws
+        # on every keystroke, hits the ExpatError, and prompts the user with
+        # "Press ENTER to continue…" indefinitely.
+        from html import escape as _html_escape
         label = current_node_label['value']
         status = current_node_status['value']
         node_short = capture.node_id[:8] if capture.node_id else '--------'
-        label_part = f" · {label[:40]}{'…' if label and len(label) > 40 else ''}" if label else ""
+        if label:
+            preview = label[:40] + ('…' if len(label) > 40 else '')
+            label_part = f" · {_html_escape(preview)}"
+        else:
+            label_part = ""
         status_badge = " [branched]" if status == 'branched' else ""
         border = '─' * 200  # prompt_toolkit clips to terminal width
         return HTML(
@@ -263,6 +293,52 @@ async def _run(driver_name: str, cwd: str, no_browser: bool = False) -> None:
         else:
             await driver.connect(cwd=cwd)
 
+        async def _restore_fs_snapshot(node_data: dict) -> None:
+            """
+            Best-effort restore of the work-tree to a node's filesystem snapshot.
+
+            Surfaces dirty-tree status to the user before the rewind: if the
+            current work-tree has uncommitted edits that will be auto-
+            preserved, we tell them inline so they understand the rewind
+            isn't silently destroying anything. After the restore we echo
+            the rescue commit hash so the user has a handle to recover
+            from if they ever want those edits back.
+
+            Logs and continues on any failure — we never want a snapshot
+            issue to block conversation-side branching/checkout, which is
+            still partially useful even with FS divergence.
+            """
+            if snapshot_manager is None:
+                return
+            git_hash = (node_data.get("git_hash") or "").strip()
+            if not git_hash:
+                # Node was created before snapshots existed, or the source
+                # node had no FS changes captured. Nothing to restore.
+                return
+
+            # Pre-restore: tell the user if pending edits will be auto-
+            # preserved. Best-effort — never block the restore on this.
+            try:
+                if await snapshot_manager.has_uncommitted_changes():
+                    console.print(
+                        "[dim yellow]  ⚠ Saving uncommitted edits as a rescue snapshot before rewinding…[/dim yellow]"
+                    )
+            except Exception:
+                logger.debug("snapshot: dirty-tree check failed", exc_info=True)
+
+            try:
+                rescue_hash = await snapshot_manager.restore(git_hash)
+                logger.debug("snapshot: restored FS to %s", git_hash[:8])
+                if rescue_hash:
+                    console.print(
+                        f"[dim]    edits preserved as snapshot [bold]{rescue_hash[:8]}[/bold] in shadow git[/dim]"
+                    )
+            except Exception:
+                logger.exception(
+                    "snapshot: failed to restore FS to %s — continuing without rewind",
+                    git_hash[:8],
+                )
+
         async def _handle_pending_switch(*, print_notification: bool = False) -> None:
             """
             Handle a pending branch switch if one is queued.
@@ -288,6 +364,9 @@ async def _run(driver_name: str, cwd: str, no_browser: bool = False) -> None:
                 if fetched_label:
                     current_node_label['value'] = fetched_label
                     node_label_cache[new_node_id] = fetched_label
+                # Rewind the work-tree to this node's snapshot before the
+                # agent restart — agent and FS need to agree on state.
+                await _restore_fs_snapshot(result)
                 new_cc_session_id = await driver.reset_context(
                     result.get("materialized_context", []),
                     cc_session_id=result.get("cc_session_id") or None,
@@ -332,6 +411,11 @@ async def _run(driver_name: str, cwd: str, no_browser: bool = False) -> None:
                 child_checkout = await backend.checkout_node(child_id)
                 current_node_status['value'] = child_checkout.get("status", "active")
                 current_node_label['value'] = child_checkout.get("label") or None
+                # Rewind work-tree to the snapshot at the chosen branch
+                # point. Backend's branch_node populated child.git_hash by
+                # walking parent's events to the right index — see
+                # backend/nodes/views.py branch_node().
+                await _restore_fs_snapshot(child_checkout)
                 new_cc_session_id = await driver.reset_context(
                     child_checkout.get("materialized_context", []),
                     cc_session_id=child_checkout.get("cc_session_id") or None,
@@ -402,6 +486,8 @@ async def _run(driver_name: str, cwd: str, no_browser: bool = False) -> None:
                 if fetched_label:
                     node_label_cache[target_id] = fetched_label
 
+                # Rewind work-tree to target node's snapshot before agent restart.
+                await _restore_fs_snapshot(node_data)
                 new_cc_session_id = await driver.reset_context(
                     node_data.get("materialized_context", []),
                     cc_session_id=node_data.get("cc_session_id") or None,
@@ -456,6 +542,8 @@ async def _run(driver_name: str, cwd: str, no_browser: bool = False) -> None:
                         # Force active — user explicitly reverted, bypass the branched-node guard
                         current_node_status['value'] = 'active'
                         current_node_label['value'] = parent_data.get("label") or None
+                        # Rewind FS to parent's snapshot before agent restart.
+                        await _restore_fs_snapshot(parent_data)
                         new_cc_session_id = await driver.reset_context(
                             parent_data.get("materialized_context", []),
                             cc_session_id=parent_data.get("cc_session_id") or None,
@@ -510,6 +598,8 @@ async def _run(driver_name: str, cwd: str, no_browser: bool = False) -> None:
                         child_checkout = await backend.checkout_node(child_id)
                         current_node_status['value'] = child_checkout.get("status", "active")
                         current_node_label['value'] = child_checkout.get("label") or None
+                        # Rewind FS to the new child's inherited snapshot before agent restart.
+                        await _restore_fs_snapshot(child_checkout)
                         new_cc_session_id = await driver.reset_context(
                             child_checkout.get("materialized_context", []),
                             cc_session_id=child_checkout.get("cc_session_id") or None,
@@ -705,6 +795,24 @@ async def _run(driver_name: str, cwd: str, no_browser: bool = False) -> None:
                             await backend.patch_node(capture.node_id, {"cc_session_id": cc_session_id})
                         except Exception:
                             logger.warning("Failed to store cc_session_id for node %s", capture.node_id)
+
+                    # Take a final snapshot at turn end and pin it as the
+                    # node's git_hash. Catches any user-side or final-tool
+                    # FS changes that happened after the last hook fired
+                    # so /branch and /checkout always have a concrete state
+                    # to rewind to. No-op if nothing changed.
+                    if snapshot_manager is not None:
+                        try:
+                            snap_hash, _ = await snapshot_manager.commit(
+                                f"node {capture.node_id[:8]} turn end"
+                            )
+                            if snap_hash:
+                                try:
+                                    await backend.patch_node(capture.node_id, {"git_hash": snap_hash})
+                                except Exception:
+                                    logger.warning("Failed to persist git_hash for node %s", capture.node_id)
+                        except Exception:
+                            logger.exception("turn-end snapshot commit failed")
                     # If auto-branch happened mid-stream, reset driver context to child node now
                     # that the stream is fully done (can't disconnect/reconnect mid-stream).
                     # The pivot user message already lives on the child via the in-stream

expluro-0.3.0/topo/snapshot.py

@@ -0,0 +1,482 @@
+"""
+World-state snapshots — shadow git repo capturing filesystem state per tool call.
+
+The product promise is "graph layer on top of agentic AI tools." If `/branch`
+doesn't actually rewind the filesystem when forking the conversation, that
+promise is incomplete. SnapshotManager closes that gap by tagging every
+side-effecting tool call with a git commit and rewinding the work-tree on
+`/branch` and `/checkout`.
+
+Architecture
+------------
+We use git's `--git-dir` / `--work-tree` separation. The shadow repo's `.git`
+lives at `~/.expluro/snapshots/<graph-id>/.git`, where `graph-id` is the
+backend's UUID for the graph (one per "topology graph session" in the
+user's mental model). Multiple graphs in the same project directory each
+get their own isolated shadow — explicit "+ Start new session" means a
+fresh slate at the filesystem level too.
+
+The work-tree is the user's actual project directory. Two consequences:
+
+  1. The user's own `.git` is never touched. Their repo state, their staged
+     index, their stash — all untouched. Their normal git workflow is
+     unaffected.
+  2. Non-git projects work transparently. A project that's just loose files
+     gets snapshots without the user even initializing git.
+
+We respect the user's `.gitignore` (shadow git reads it from the work-tree),
+so build artifacts, `node_modules`, and friends stay out of snapshot history.
+
+Edge cases handled
+------------------
+  - Binary files: git handles natively (hashed, no text diff).
+  - Large files: respected via `.gitignore` if user excludes them; otherwise
+    we cap diff text reported in events at SNAPSHOT_DIFF_MAX_BYTES.
+  - User edits between tool calls: commit captures all current work-tree
+    state, so manual edits get rolled into the next snapshot.
+  - `/branch` with uncommitted vs-last-snapshot work: we auto-commit those as
+    a "user-edits" snapshot before the restore so nothing is lost.
+  - User's git hooks: shadow commits use `--no-verify` to skip them — the
+    shadow repo is a tool-internal concern, not a code-review concern.
+  - Concurrent operations: each call awaits its subprocess to completion,
+    no parallel git operations on the same dir.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import shutil
+from pathlib import Path
+from typing import Optional
+
+from .constants import APP_DIR
+
+logger = logging.getLogger(__name__)
+
+# Cap diff text reported in events. Full diffs for large changes blow up
+# the event log and don't render meaningfully in the browser anyway —
+# truncate and let users fetch the full snapshot via the CLI later.
+SNAPSHOT_DIFF_MAX_BYTES = 50_000
+
+SNAPSHOTS_ROOT = Path.home() / APP_DIR / "snapshots"
+
+
+class SnapshotError(RuntimeError):
+    """Raised when a snapshot operation fails in a way the caller should know about."""
+
+
+class SnapshotManager:
+    """Shadow-git snapshot manager scoped to a single graph (topology session).
+
+    Each graph gets its own shadow repo — explicit "+ Start new session"
+    means a clean slate at the filesystem level too. Cleanup is natural:
+    deleting a graph maps 1:1 to deleting its shadow directory.
+
+    Lifecycle:
+        sm = SnapshotManager(cwd, graph_id)
+        await sm.init()                      # ensure shadow repo exists
+        hash, diff = await sm.commit(label)  # snapshot current state
+        await sm.restore(hash)               # rewind work-tree to that snapshot
+        # no explicit close needed — shadow repo persists across sessions
+        # for the SAME graph (resume preserves history); deleted with the graph
+    """
+
+    def __init__(self, cwd: str, graph_id: str) -> None:
+        if not os.path.isdir(cwd):
+            raise SnapshotError(f"cwd is not a directory: {cwd}")
+        if not graph_id:
+            raise SnapshotError("graph_id is required for SnapshotManager")
+        self._cwd = os.path.realpath(cwd)
+        self._graph_id = str(graph_id)
+        self._git_dir = SNAPSHOTS_ROOT / self._graph_id / ".git"
+        self._initialized = False
+
+    @property
+    def graph_id(self) -> str:
+        return self._graph_id
+
+    @property
+    def git_dir(self) -> Path:
+        return self._git_dir
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def init(self) -> None:
+        """Ensure the shadow repo exists and has at least an initial commit.
+
+        Idempotent — safe to call on every session start.
+        """
+        if self._initialized:
+            return
+
+        SNAPSHOTS_ROOT.mkdir(parents=True, exist_ok=True)
+
+        # Already initialized?
+        if (self._git_dir / "HEAD").exists():
+            self._initialized = True
+            logger.debug("SnapshotManager: shadow repo already exists at %s", self._git_dir)
+            return
+
+        # Create the shadow repo. We do NOT init the work-tree here —
+        # `git --git-dir=X --work-tree=Y init` would point HEAD into Y
+        # which is fine, but we want to be explicit about which dir the
+        # repo metadata lives in.
+        self._git_dir.parent.mkdir(parents=True, exist_ok=True)
+        await self._git("init", "--quiet", "--bare=false", create_anyway=True)
+
+        # Configure shadow repo identity — needed for commits to succeed
+        # without leaning on whatever the user has globally configured.
+        await self._git("config", "user.name", "Expluro Snapshot")
+        await self._git("config", "user.email", "snapshots@expluro.local")
+        # Don't sign shadow commits even if user has commit.gpgsign=true
+        # globally — we don't want to spam the user with gpg prompts.
+        await self._git("config", "commit.gpgsign", "false")
+
+        # Initial baseline commit. May be empty if cwd is empty — git
+        # accepts empty-tree commits with --allow-empty.
+        await self._git("add", "--all", "--", ".")
+        await self._git(
+            "commit",
+            "--allow-empty",
+            "--no-verify",
+            "--quiet",
+            "-m",
+            "expluro: initial snapshot",
+        )
+
+        self._initialized = True
+        logger.info("SnapshotManager: initialized shadow repo at %s", self._git_dir)
+
+    # ------------------------------------------------------------------
+    # Capture
+    # ------------------------------------------------------------------
+
+    async def commit(self, label: str) -> tuple[Optional[str], Optional[dict]]:
+        """Commit the current work-tree state to the shadow repo.
+
+        Returns (commit_hash, diff_summary). If there are no changes since
+        the last commit, returns (existing_HEAD, None) so the caller still
+        has a hash to attach to the event.
+
+        diff_summary is a dict suitable for embedding in an event payload:
+            {
+                "files_changed": [{"path": str, "status": str}, ...],
+                "insertions": int,
+                "deletions": int,
+                "diff_text": str,  # truncated to SNAPSHOT_DIFF_MAX_BYTES
+                "truncated": bool,
+            }
+        """
+        if not self._initialized:
+            await self.init()
+
+        # Stage everything new/modified/deleted that isn't gitignored.
+        await self._git("add", "--all", "--", ".")
+
+        # Has anything actually changed since HEAD?
+        has_changes = await self._has_staged_changes()
+        if not has_changes:
+            head = await self._git_head()
+            return head, None
+
+        # Capture diff BEFORE committing so we can describe what changed.
+        diff_summary = await self._diff_summary_staged()
+
+        sanitized = label.replace("\n", " ").strip()[:200] or "snapshot"
+        await self._git(
+            "commit",
+            "--no-verify",
+            "--quiet",
+            "-m",
+            f"expluro: {sanitized}",
+        )
+
+        commit_hash = await self._git_head()
+        logger.debug(
+            "SnapshotManager: committed %s (%d files, +%d/-%d)",
+            commit_hash[:8] if commit_hash else "?",
+            len(diff_summary.get("files_changed", [])),
+            diff_summary.get("insertions", 0),
+            diff_summary.get("deletions", 0),
+        )
+        return commit_hash, diff_summary
+
+    # ------------------------------------------------------------------
+    # Restore
+    # ------------------------------------------------------------------
+
+    async def has_uncommitted_changes(self) -> bool:
+        """Return True if the work-tree differs from the shadow repo's HEAD.
+
+        Used to inform the user before a destructive `restore()` that their
+        in-flight edits will be auto-preserved as a rescue snapshot. Never
+        raises — a git failure is treated as "clean" so this can't block
+        the restore path on transient issues.
+        """
+        if not self._initialized:
+            return False
+        try:
+            out = await self._git("status", "--porcelain")
+        except SnapshotError:
+            return False
+        return bool(out.strip())
+
+    async def restore(self, commit_hash: str) -> Optional[str]:
+        """Rewind the work-tree to the given snapshot.
+
+        Auto-commits any pending uncommitted-vs-last-snapshot work first so
+        nothing is lost. The auto-commit is reachable from the shadow repo's
+        reflog and we return its hash so the caller can surface it to the
+        user as a recovery handle.
+
+        Returns the rescue commit hash when the auto-preserve actually
+        happened (i.e. the work-tree was dirty), or None when there was
+        nothing to preserve.
+
+        Raises SnapshotError if the target commit doesn't exist or the
+        reset fails.
+        """
+        if not self._initialized:
+            await self.init()
+
+        if not commit_hash:
+            raise SnapshotError("restore() called with empty commit hash")
+
+        # Verify the hash exists in our shadow repo.
+        try:
+            await self._git("cat-file", "-e", f"{commit_hash}^{{commit}}")
+        except SnapshotError as exc:
+            raise SnapshotError(
+                f"snapshot {commit_hash[:8]} not found in shadow repo"
+            ) from exc
+
+        # Auto-commit any pending work to preserve it before we rewind.
+        # Most of the time this is a no-op (the last tool call already
+        # committed). It matters when the user has manually edited files
+        # between turns, or when a turn's snapshot didn't catch the very
+        # last write.
+        rescue_hash: Optional[str] = None
+        await self._git("add", "--all", "--", ".")
+        if await self._has_staged_changes():
+            await self._git(
+                "commit",
+                "--no-verify",
+                "--quiet",
+                "-m",
+                "expluro: auto-preserve before restore",
+            )
+            rescue_hash = await self._git_head()
+            logger.info(
+                "SnapshotManager: preserved pre-restore changes as %s",
+                (rescue_hash or "?")[:8],
+            )
+
+        # Hard-reset the work-tree to the target commit. We use reset
+        # rather than checkout because we want the index AND the work-tree
+        # to match the target — checkout in detached-HEAD mode plays
+        # weirdly with the user's normal git workflow.
+        await self._git("reset", "--hard", "--quiet", commit_hash)
+        logger.info("SnapshotManager: restored to %s", commit_hash[:8])
+        return rescue_hash
+
+    # ------------------------------------------------------------------
+    # Diff helpers
+    # ------------------------------------------------------------------
+
+    async def diff_against_head(self, commit_hash: str) -> Optional[dict]:
+        """Return a diff summary comparing the given commit against current HEAD.
+
+        Used by the browser node detail panel to render "what changed at this
+        node" without us having to ship a separate diff API.
+        """
+        if not self._initialized:
+            await self.init()
+        if not commit_hash:
+            return None
+
+        try:
+            return await self._diff_summary_between(f"{commit_hash}~1", commit_hash)
+        except SnapshotError as exc:
+            logger.warning("diff_against_head failed: %s", exc)
+            return None
+
+    # ------------------------------------------------------------------
+    # Internal: git plumbing
+    # ------------------------------------------------------------------
+
+    async def _git(
+        self,
+        *args: str,
+        create_anyway: bool = False,
+    ) -> str:
+        """
+        Run a git command in the shadow repo. Returns stdout.
+
+        `create_anyway` is for `init` itself — git init doesn't need
+        --git-dir/--work-tree the same way.
+        """
+        # GIT_DIR + GIT_WORK_TREE env separates the shadow repo from the
+        # user's. Setting via env (not flags) lets `git init` and friends
+        # behave correctly.
+        env = os.environ.copy()
+        env["GIT_DIR"] = str(self._git_dir)
+        env["GIT_WORK_TREE"] = self._cwd
+        # Avoid leaning on user's per-repo or global config that might
+        # interfere (e.g. signing, commit templates, hooks paths).
+        env.pop("GIT_CONFIG_GLOBAL", None)
+        env.pop("GIT_CONFIG_SYSTEM", None)
+
+        # `git init` needs the parent dir to exist; its own positional arg
+        # is the GIT_DIR location.
+        if args and args[0] == "init":
+            cmd = ["git", "init", "--quiet", str(self._git_dir)]
+        else:
+            cmd = ["git", *args]
+
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env=env,
+                cwd=self._cwd,
+            )
+        except FileNotFoundError as exc:
+            raise SnapshotError(
+                "git is not installed or not on PATH — snapshots disabled"
+            ) from exc
+
+        stdout_b, stderr_b = await proc.communicate()
+        if proc.returncode != 0:
+            raise SnapshotError(
+                f"git {' '.join(args)} failed (rc={proc.returncode}): "
+                f"{stderr_b.decode(errors='replace').strip()}"
+            )
+        return stdout_b.decode(errors="replace")
+
+    async def _git_head(self) -> Optional[str]:
+        try:
+            out = await self._git("rev-parse", "HEAD")
+            return out.strip() or None
+        except SnapshotError:
+            return None
+
+    async def _has_staged_changes(self) -> bool:
+        # `git diff --cached --quiet` exits 0 if nothing staged, 1 if changes.
+        # Run it manually since our _git wrapper raises on non-zero.
+        env = os.environ.copy()
+        env["GIT_DIR"] = str(self._git_dir)
+        env["GIT_WORK_TREE"] = self._cwd
+        proc = await asyncio.create_subprocess_exec(
+            "git", "diff", "--cached", "--quiet",
+            stdin=asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+            env=env,
+            cwd=self._cwd,
+        )
+        rc = await proc.wait()
+        return rc != 0
+
+    async def _diff_summary_staged(self) -> dict:
+        """Build a diff summary for currently-staged changes."""
+        files_changed = await self._diff_files_status("--cached")
+        numstat = await self._git("diff", "--cached", "--numstat")
+        insertions, deletions = _parse_numstat(numstat)
+        diff_text = await self._git("diff", "--cached")
+        return _build_summary(files_changed, insertions, deletions, diff_text)
+
+    async def _diff_summary_between(self, a: str, b: str) -> dict:
+        files_changed = await self._diff_files_status(a, b)
+        numstat = await self._git("diff", "--numstat", a, b)
+        insertions, deletions = _parse_numstat(numstat)
+        diff_text = await self._git("diff", a, b)
+        return _build_summary(files_changed, insertions, deletions, diff_text)
+
+    async def _diff_files_status(self, *git_args: str) -> list[dict]:
+        """Run `git diff --name-status` and parse to list of {path, status}."""
+        out = await self._git("diff", "--name-status", *git_args)
+        files: list[dict] = []
+        for line in out.splitlines():
+            parts = line.split("\t")
+            if len(parts) < 2:
+                continue
+            status = parts[0].strip()
+            # Renames produce: R100\told\tnew — collapse to just the new path.
+            path = parts[-1]
+            files.append({"path": path, "status": status[:1]})
+        return files
+
+    # ------------------------------------------------------------------
+    # Maintenance
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def shadow_dir_for(graph_id: str) -> Path:
+        """Where the shadow repo for this graph lives. Useful for UI display."""
+        return SNAPSHOTS_ROOT / str(graph_id)
+
+    @staticmethod
+    def delete_shadow(graph_id: str) -> None:
+        """
+        Remove the shadow repo for this graph. Used when a graph is deleted
+        or on explicit user request. Once deleted, all snapshot hashes for
+        that graph's nodes become orphan references with no restore path —
+        which is correct behavior when the graph itself is gone.
+        """
+        shadow = SnapshotManager.shadow_dir_for(graph_id)
+        if shadow.exists():
+            shutil.rmtree(shadow)
+            logger.info("SnapshotManager: deleted shadow for graph %s", graph_id)
+
+
+# ----------------------------------------------------------------------
+# Module-level helpers
+# ----------------------------------------------------------------------
+
+
+def _parse_numstat(numstat: str) -> tuple[int, int]:
+    """Parse `git diff --numstat` output to total (insertions, deletions).
+
+    Numstat format: `<insertions>\t<deletions>\t<path>` per line. Binary
+    files show `-\t-\t<path>` and don't contribute to the count.
+    """
+    ins = dele = 0
+    for line in numstat.splitlines():
+        parts = line.split("\t", 2)
+        if len(parts) < 3:
+            continue
+        a, b = parts[0], parts[1]
+        if a == "-" or b == "-":
+            continue
+        try:
+            ins += int(a)
+            dele += int(b)
+        except ValueError:
+            pass
+    return ins, dele
+
+
+def _build_summary(
+    files_changed: list[dict],
+    insertions: int,
+    deletions: int,
+    diff_text: str,
+) -> dict:
+    truncated = False
+    encoded = diff_text.encode("utf-8", errors="replace")
+    if len(encoded) > SNAPSHOT_DIFF_MAX_BYTES:
+        truncated = True
+        diff_text = encoded[:SNAPSHOT_DIFF_MAX_BYTES].decode("utf-8", errors="replace")
+        diff_text += f"\n…[{len(encoded) - SNAPSHOT_DIFF_MAX_BYTES} bytes truncated]\n"
+    return {
+        "files_changed": files_changed,
+        "insertions": insertions,
+        "deletions": deletions,
+        "diff_text": diff_text,
+        "truncated": truncated,
+    }

expluro-0.2.0/topo/snapshot.py

@@ -1,3 +0,0 @@
-class SnapshotManager:
-    # Implemented in task #9
-    pass