expluro 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: expluro
-Version: 0.3.0
+Version: 0.4.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.3.0 → expluro-0.4.0}/expluro.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: expluro
-Version: 0.3.0
+Version: 0.4.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.3.0 → expluro-0.4.0}/expluro.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ expluro.egg-info/entry_points.txt
 expluro.egg-info/requires.txt
 expluro.egg-info/top_level.txt
 topo/__init__.py
+topo/attribution.py
 topo/auth.py
 topo/backend.py
 topo/capture.py
@@ -24,4 +25,5 @@ topo/drivers/_permissions.py
 topo/drivers/acp.py
 topo/drivers/base.py
 topo/drivers/claude.py
+topo/drivers/codex.py
 topo/drivers/kiro_session_files.py

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

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

expluro-0.4.0/topo/attribution.py

@@ -0,0 +1,329 @@
+"""Hunk-level reason attribution for the Files-changed tab.
+
+Maps git commit hashes (from `git blame` in the shadow repo) to expluro
+event ids, so each hunk in a node's net diff can be traced back to the
+tool call that produced it. Output feeds the reason-linked diff UI:
+clicking a hunk's attribution chip opens a side rail with the responsible
+prompt + tool call + assistant message.
+
+Kept separate from snapshot.py (which stays git-mechanical) — this
+module knows about expluro's event semantics.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Iterable
+
+logger = logging.getLogger(__name__)
+
+
+# Flat tool_input keys that carry a file path. Different agents use
+# different conventions:
+#   - Claude Code:    `file_path` (Write/Edit/MultiEdit), `notebook_path` (NotebookEdit)
+#   - ACP (Kiro):     `path`
+#   - Codex:          path is NOT at the top level for fileChange items;
+#                     it lives at `changes[*].path`. _extract_tool_paths
+#                     below handles that nested shape. `savedPath` is
+#                     the flat key on Codex `imageGeneration` items.
+_PATH_KEYS = ('file_path', 'path', 'notebook_path', 'savedPath')
+
+
+# Best-effort recognition of "this event is a file-mutating tool call
+# by named path." Three drivers' naming conventions need to match:
+#   - Claude Code:   'Write', 'Edit', 'MultiEdit', 'NotebookEdit'
+#   - ACP (Kiro):    kind='edit', titles like 'Edit File: foo.py', 'Create File: bar.py'
+#   - Codex:         item type='fileChange' (the main one), 'imageGeneration'
+#                    (writes a generated image to disk).
+#
+# Case-insensitive substring match keeps us robust to capitalization
+# AND to verbose titles ("Edit File") AND to single-word codex item
+# types ("fileChange" → matches via 'filechange'). The explicit
+# read-tool exclusion below prevents `Read`/`Grep` from spuriously
+# naming files.
+#
+# Bash / commandExecution are intentionally NOT mutation tokens —
+# they execute shell commands that may or may not mutate files, and
+# topo has no structured path to attribute. Future: a per-turn
+# snapshot boundary would let us attribute Bash effects too.
+#
+# mcpToolCall / dynamicToolCall are also excluded — arbitrary tools
+# whose file effects are unpredictable; conservatively classify any
+# files they touch as Unattributed rather than misclaiming attribution.
+_MUTATION_TOOL_TOKENS = (
+    # Claude Code names
+    'write', 'edit', 'multiedit', 'notebookedit',
+    # ACP / Kiro verbose titles
+    'create file', 'write file', 'edit file',
+    # Codex item types (lowercase form because we case-fold)
+    'filechange', 'imagegeneration',
+    # Patch operations across agents
+    'patch', 'apply patch',
+)
+_READ_TOOL_TOKENS = ('read', 'grep', 'glob', 'search', 'ls', 'list')
+
+
+def _extract_tool_paths(tool_input: dict) -> list[str]:
+    """Pull every file path the agent named out of a tool's input dict.
+
+    Three shapes to handle:
+      - Claude / ACP: flat string at `tool_input.file_path` /
+        `tool_input.path` / `tool_input.notebook_path`.
+      - Codex `imageGeneration`: flat string at `tool_input.savedPath`.
+      - Codex `fileChange`: nested under `tool_input.changes[*].path`,
+        where each entry also has `diff` and `kind`. A single
+        fileChange item can touch multiple files in one call.
+
+    Returns the deduplicated path strings, preserving input order so
+    the most-specific path appears first when callers iterate.
+    """
+    paths: list[str] = []
+    seen: set[str] = set()
+
+    def _add(value: object) -> None:
+        if isinstance(value, str) and value and value not in seen:
+            seen.add(value)
+            paths.append(value)
+
+    if not isinstance(tool_input, dict):
+        return paths
+    # Flat string keys first — covers Claude, ACP, and Codex's
+    # imageGeneration savedPath.
+    for key in _PATH_KEYS:
+        _add(tool_input.get(key))
+    # Codex fileChange items nest paths under `changes[*].path`.
+    changes = tool_input.get('changes')
+    if isinstance(changes, list):
+        for entry in changes:
+            if isinstance(entry, dict):
+                _add(entry.get('path'))
+    return paths
+
+
+def _is_file_mutation_tool(tool_name: str | None) -> bool:
+    """Does this tool_name look like an agent file-mutation operation?
+
+    Case-insensitive. Mutation tokens take precedence over read tokens
+    so an unlikely "edit_read_metadata"-style name still classifies as
+    mutation if any mutation token matches. Returns False for empty
+    names and for tools whose name is purely a read/list operation.
+    """
+    if not tool_name:
+        return False
+    n = tool_name.strip().lower()
+    for token in _MUTATION_TOOL_TOKENS:
+        if token in n:
+            return True
+    # No mutation match — check if it's a clear read-only tool.
+    for token in _READ_TOOL_TOKENS:
+        if n == token or n.startswith(token + ' ') or n.startswith(token + '_'):
+            return False
+    return False
+
+
+def build_hunk_attributions(
+    file_changes: list[dict],
+    events: Iterable[dict],
+) -> None:
+    """Splice `hunk_attributions` and `attribution_class` into each
+    file_change row in place.
+
+    Args:
+        file_changes: rows from `SnapshotManager.net_diff_summary`. Each
+            row may carry a `hunk_blame` field (added by snapshot.py)
+            holding per-hunk commit-hash counts. After this call, each
+            row also carries `hunk_attributions` (and `hunk_blame` is
+            removed — it's an intermediate the backend doesn't need)
+            and a per-file `attribution_class` of either
+            `'attributed'` (some tool event in this node explicitly
+            named this file's path) or `'unattributed'` (file changed
+            but no captured tool action referenced it — e.g., a
+            background process, an external editor, /tmp cleanup, etc.).
+        events: chronologically-ordered list of the node's events. Each
+            event is expected to be a dict with at minimum `id` and
+            `snapshot_hash`; events touching files have
+            `payload.diff_summary.files_changed`.
+
+    Side effect: each file_change row gains `hunk_attributions` and
+    `attribution_class`. The class is used by the UI to render
+    unattributed files in a separate section without a misleading
+    reason block.
+    """
+    events_list = list(events)
+    # Map shadow-git commit hash → first event_id with that snapshot_hash.
+    # FIRST because subsequent events sharing a hash mean the tool ran
+    # but committed nothing — they didn't contribute changes. Earliest
+    # event is the one that introduced the snapshot.
+    commit_to_event: dict[str, str] = {}
+    # Per-path: list of event_ids in chronological order that touched
+    # the path. Used for the deletion fallback (last tool call to touch
+    # a path) and for diagnostics.
+    path_to_events: dict[str, list[str]] = {}
+    # Set of file paths that any mutation-capable tool event explicitly
+    # named in its tool_input — the agent's stated target, NOT the
+    # post-call diff. A file is "Attributed" iff its path matches one
+    # of these. Stored as raw (typically absolute) paths; matched
+    # against the relative file_change paths via suffix comparison
+    # because git diff yields paths relative to the work-tree root
+    # while tool inputs use absolute paths.
+    tool_named_paths: set[str] = set()
+    for ev in events_list:
+        ev_id = str(ev.get('id') or '')
+        if not ev_id:
+            continue
+        snap = (ev.get('snapshot_hash') or '').strip()
+        if snap and snap not in commit_to_event:
+            commit_to_event[snap] = ev_id
+        payload = ev.get('payload') or {}
+        diff_summary = payload.get('diff_summary') or {}
+        files = diff_summary.get('files_changed') or []
+        for fc in files:
+            if isinstance(fc, dict):
+                path = fc.get('path')
+                if path:
+                    path_to_events.setdefault(path, []).append(ev_id)
+        # Collect paths the agent explicitly named, regardless of
+        # event_type. pre_tool_use carries the intended input;
+        # post_tool_use repeats it. Either is fine for set membership.
+        # _is_file_mutation_tool() recognizes Claude Code's tool names,
+        # ACP kind='edit', and common verbose forms ("Edit File", etc.)
+        # so the classifier works across drivers.
+        if _is_file_mutation_tool(ev.get('tool_name')):
+            tool_input = payload.get('tool_input') or {}
+            for named in _extract_tool_paths(tool_input):
+                tool_named_paths.add(named)
+
+    for row in file_changes:
+        hunk_blame = row.pop('hunk_blame', None) or []
+        path = row.get('path', '')
+        attributions: list[dict] = []
+        for h_idx, hb in enumerate(hunk_blame):
+            attributions.append(_attribute_hunk(
+                hunk_index=h_idx,
+                hunk_blame=hb,
+                path=path,
+                commit_to_event=commit_to_event,
+                path_to_events=path_to_events,
+            ))
+        row['hunk_attributions'] = attributions
+        row['attribution_class'] = (
+            'attributed' if _path_matches_tool_named(path, tool_named_paths)
+            else 'unattributed'
+        )
+
+
+def _path_matches_tool_named(rel_path: str, tool_named_paths: set[str]) -> bool:
+    """Does `rel_path` (from git diff, relative to project root) refer
+    to the same file as any path in `tool_named_paths` (from tool_input,
+    typically absolute)?
+
+    Suffix match with a path-separator boundary so `dir/a.py` doesn't
+    spuriously match `otherdir/a.py`. Exact match also accepted for the
+    rare case where both sides happen to be relative.
+    """
+    if not rel_path or not tool_named_paths:
+        return False
+    if rel_path in tool_named_paths:
+        return True
+    suffix = '/' + rel_path
+    for named in tool_named_paths:
+        if named.endswith(suffix):
+            return True
+    return False
+
+
+def _attribute_hunk(
+    hunk_index: int,
+    hunk_blame: dict,
+    path: str,
+    commit_to_event: dict[str, str],
+    path_to_events: dict[str, list[str]],
+) -> dict:
+    """Build the hunk_attributions entry for a single hunk."""
+    contributors_map: dict[str, int] = {}
+    unresolved = 0
+    for sha, count in (hunk_blame.get('commit_counts') or {}).items():
+        ev_id = commit_to_event.get(sha)
+        if ev_id:
+            contributors_map[ev_id] = contributors_map.get(ev_id, 0) + count
+        else:
+            # Lines blamed to a commit that doesn't map to any event in
+            # this node — typically lines that came from the parent
+            # branch's history (i.e. lines this node inherited and
+            # didn't touch). Skipped from contributors; counted for
+            # confidence calculation.
+            unresolved += count
+
+    contributors = [
+        {'event_id': ev_id, 'line_count': count}
+        for ev_id, count in sorted(
+            contributors_map.items(), key=lambda kv: kv[1], reverse=True,
+        )
+    ]
+
+    added_count = hunk_blame.get('added_count', 0)
+    deleted_count = hunk_blame.get('deleted_count', 0)
+
+    # Method + confidence decision tree:
+    #   - If we have any contributors AND most blamed lines resolved →
+    #     blame, high (single contributor) or medium (multiple).
+    #   - If we have contributors but lots of unresolved → blame, medium.
+    #   - No added lines at all (pure deletion) → deletion_fallback,
+    #     primary = last event to touch the path.
+    #   - Added lines but no contributors mapped → file_fallback,
+    #     primary = last event to touch the path. Low confidence; the
+    #     blame went somewhere we couldn't resolve.
+    #   - No fallback candidate either → unknown, null primary.
+    if contributors:
+        if unresolved == 0 and len(contributors) == 1:
+            method = 'blame'
+            confidence = 'high'
+        elif unresolved > added_count // 2 and added_count > 0:
+            method = 'blame'
+            confidence = 'medium'
+        else:
+            method = 'blame'
+            confidence = 'medium' if len(contributors) > 1 else 'high'
+        primary = contributors[0]['event_id']
+    elif added_count == 0 and deleted_count > 0:
+        last_ev = _last_event_for_path(path, path_to_events)
+        method = 'deletion_fallback'
+        confidence = 'low'
+        primary = last_ev
+        if last_ev:
+            contributors = [{'event_id': last_ev, 'line_count': deleted_count}]
+    else:
+        last_ev = _last_event_for_path(path, path_to_events)
+        if last_ev:
+            method = 'file_fallback'
+            confidence = 'low'
+            primary = last_ev
+            contributors = [{'event_id': last_ev, 'line_count': added_count + deleted_count}]
+        else:
+            method = 'unknown'
+            confidence = 'low'
+            primary = None
+
+    return {
+        'hunk_index': hunk_index,
+        'new_start': hunk_blame.get('new_start', 0),
+        'new_lines': hunk_blame.get('new_lines', 0),
+        'old_start': hunk_blame.get('old_start', 0),
+        'old_lines': hunk_blame.get('old_lines', 0),
+        'primary_event_id': primary,
+        'method': method,
+        'confidence': confidence,
+        'contributors': contributors,
+    }
+
+
+def _last_event_for_path(path: str, path_to_events: dict[str, list[str]]) -> str | None:
+    """Return the most recent event_id that touched `path`, or None.
+
+    Used by the deletion and file fallbacks when blame can't attribute
+    the hunk to a specific commit (deletion-only hunks, blame pointing
+    at an unmappable commit).
+    """
+    ids = path_to_events.get(path)
+    if not ids:
+        return None
+    return ids[-1]

{expluro-0.3.0 → expluro-0.4.0}/topo/backend.py

@@ -64,6 +64,32 @@ class BackendClient:
     async def patch_graph(self, graph_id: str, data: dict[str, Any]) -> dict[str, Any]:
         return await self._patch(f"/api/graphs/{graph_id}/", data)
 
+    async def delete_graph(self, graph_id: str) -> None:
+        """Delete a graph and all of its nodes/edges/events/marks via Django cascade.
+
+        Used by scripts/cleanup_playground.py, not by the running CLI.
+        DELETE responds 204 No Content, so we can't reuse the JSON-parsing
+        _request helper — call _client directly with the same auth+refresh
+        pattern in miniature.
+        """
+        token = get_access_token()
+        headers = {"Authorization": f"Bearer {token}"} if token else {}
+        url = f"{self.base_url}/api/graphs/{graph_id}/"
+        try:
+            resp = await self._client.request("DELETE", url, headers=headers)
+        except httpx.ConnectError as exc:
+            raise BackendError(0, f"Cannot reach backend at {self.base_url}") from exc
+        except httpx.TimeoutException as exc:
+            raise BackendError(0, "Request timed out.") from exc
+        if resp.status_code == 401:
+            try:
+                new_token = await self._refresh_access_token()
+                headers["Authorization"] = f"Bearer {new_token}"
+                resp = await self._client.request("DELETE", url, headers=headers)
+            except BackendError:
+                raise BackendError(401, f"Session expired. Please run `{APP_NAME} login` again.")
+        _raise_for_status(resp)
+
     async def list_graphs_for_path(self, project_path: str) -> list[dict[str, Any]]:
         result = await self._get(f"/api/graphs/?project_path={project_path}")
         return result if isinstance(result, list) else result.get("results", [])
@@ -77,12 +103,21 @@ class BackendClient:
         graph_id: str,
         parent_id: str | None = None,
         tool: str | None = None,
+        base_git_hash: str | None = None,
     ) -> dict[str, Any]:
+        """Create a node. For root nodes, pass `base_git_hash` (the shadow
+        repo's HEAD after init) so the Files-changed tab can compute net
+        diff against the project's starting state instead of the empty
+        tree. Branch children get their base_git_hash from the backend's
+        branch endpoint and don't pass it here.
+        """
         payload: dict[str, Any] = {"graph": graph_id}
         if parent_id:
             payload["parent"] = parent_id
         if tool:
             payload["tool"] = tool
+        if base_git_hash:
+            payload["base_git_hash"] = base_git_hash
         return await self._post("/api/nodes/", payload)
 
     async def patch_node(self, node_id: str, data: dict[str, Any]) -> dict[str, Any]:
@@ -91,8 +126,34 @@ class BackendClient:
     async def checkout_node(self, node_id: str) -> dict[str, Any]:
         return await self._post(f"/api/nodes/{node_id}/checkout/", {})
 
-    async def branch_node(self, node_id: str, branch_from_index: int) -> dict[str, Any]:
-        return await self._post(f"/api/nodes/{node_id}/branch/", {"branch_from_index": branch_from_index})
+    async def get_node(self, node_id: str) -> dict[str, Any]:
+        """Fetch the full NodeSerializer payload — kind, generation_count,
+        materialized_context, inherited_context_length, branch_reason,
+        outcome, etc. Used by the CLI's LLM pipeline because checkout_node
+        only returns the checkout response (a slim shape)."""
+        return await self._get(f"/api/nodes/{node_id}/")
+
+    async def branch_node(
+        self,
+        node_id: str,
+        branch_from_index: int,
+        edge_kind: str = "manual_branch",
+        branch_reason: str = "",
+    ) -> dict[str, Any]:
+        """Create a child node from `node_id` at the chosen branch point.
+
+        edge_kind and branch_reason are set atomically during creation so
+        the panel banner renders the right label even if a follow-up PATCH
+        would have failed. edge_kind is immutable after creation; this is
+        the only place a caller gets to set it.
+        """
+        payload: dict[str, Any] = {
+            "branch_from_index": branch_from_index,
+            "edge_kind": edge_kind,
+        }
+        if branch_reason:
+            payload["branch_reason"] = branch_reason[:500]
+        return await self._post(f"/api/nodes/{node_id}/branch/", payload)
 
     async def list_nodes(self, graph_id: str, limit: int = 10, offset: int = 0) -> dict[str, Any]:
         result = await self._get(f"/api/nodes/?graph={graph_id}&limit={limit}&offset={offset}")
@@ -109,6 +170,47 @@ class BackendClient:
     async def move_event(self, event_id: str, target_node_id: str) -> dict[str, Any]:
         return await self._post(f"/api/nodes/events/{event_id}/move/", {"target_node_id": target_node_id})
 
+    async def list_events(self, node_id: str) -> Any:
+        """Fetch the durable event list for a node. Used by the LLM
+        review-artifact pipeline to read the transcript that produced
+        the current node state."""
+        return await self._get(f"/api/nodes/{node_id}/events/")
+
+    async def generate_now(self, node_id: str) -> tuple[int, dict[str, Any] | None]:
+        """Ask the backend to generate the review artifact for `node_id`.
+
+        Returns (status_code, body). Body is None for 202/204. Callers
+        in the CLI fire this as a fire-and-forget background task on
+        lifecycle transitions (/branch, /checkpoint, /exit). Backend
+        owns the lock, the LLM call, validation, persistence, and the
+        node_updated broadcast — the CLI is just a requester.
+
+        Status semantics (matches endpoint):
+          202 — accepted; generation running in a daemon thread on the
+                backend. Listen for `node_updated` over Channels to
+                know when the artifact lands. This is the happy path.
+          204 — skipped (empty node, no new events since last gen, or
+                kind != work).
+          409 — locked elsewhere, or cap reached. Body has `detail`.
+        """
+        token = get_access_token()
+        headers = {"Authorization": f"Bearer {token}"} if token else {}
+        url = f"{self.base_url}/api/nodes/{node_id}/generate_now/"
+        # Backend returns 202 sub-second (it spawns the LLM call in a
+        # daemon thread), so the class-default 15s timeout is plenty.
+        resp = await self._client.post(url, headers=headers, json={})
+        if resp.status_code == 401:
+            new_token = await self._refresh_access_token()
+            headers["Authorization"] = f"Bearer {new_token}"
+            resp = await self._client.post(url, headers=headers, json={})
+        body: dict[str, Any] | None = None
+        if resp.status_code not in (202, 204):
+            try:
+                body = resp.json()
+            except Exception:
+                body = None
+        return resp.status_code, body
+
     # ------------------------------------------------------------------
     # Internal helpers
     # ------------------------------------------------------------------

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

@@ -20,8 +20,9 @@ import logging
 import uuid
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Callable, Optional
 
+from .backend import BackendError
 from .constants import APP_DIR
 
 if TYPE_CHECKING:
@@ -58,10 +59,22 @@ class EventCapture:
         graph_id: str,
         node_id: str,
         snapshot_manager: "SnapshotManager | None" = None,
+        on_node_locked: Optional[Callable[[str], None]] = None,
     ) -> None:
         self._backend = backend
         self._graph_id = graph_id
         self._node_id = node_id
+        # Invoked when the backend rejects an event with 409 because
+        # the target node is branched. Receives the node_id that was
+        # rejected. The session loop uses this to mark the node as
+        # branched in CLI state so the next user input triggers the
+        # auto-checkpoint guard. Set on construction so the loop and
+        # capture don't need a shared mutable state object.
+        self._on_node_locked = on_node_locked
+        # Guard so the callback fires at most once per node_id (an
+        # in-flight stream may attempt several event posts after the
+        # node flips to branched; we only need to recover once).
+        self._locked_node_notified: set[str] = set()
         # 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.
@@ -92,6 +105,15 @@ class EventCapture:
     def node_id(self) -> str:
         return self._node_id
 
+    def set_on_node_locked(self, callback: Optional[Callable[[str], None]]) -> None:
+        """Set/replace the branched-node-rejection callback.
+
+        Lets the session loop wire the callback after EventCapture is
+        constructed (the session's state dict lives lower in the
+        function and can't be closed over at construction time).
+        """
+        self._on_node_locked = callback
+
     def register(self, driver: "BaseDriver") -> None:
         """Wire pre/post tool hooks onto the driver."""
         driver.register_pre_tool_hook(self._on_pre_tool)
@@ -384,9 +406,39 @@ class EventCapture:
         self._log_file.flush()
 
         # 2. Send to backend — best effort, never crash the session on failure
+        target_node_id = self._node_id
         try:
-            resp = await self._backend.append_delta_event(self._node_id, event)
+            resp = await self._backend.append_delta_event(target_node_id, event)
             return resp.get("id") if isinstance(resp, dict) else None
+        except BackendError as exc:
+            # 409 from append_event means the backend now considers this
+            # node branched/frozen. The session-loop guard at
+            # session.py:876 is supposed to prevent us ever reaching
+            # here — if we do, it's a CLI bug, race, or a third-party
+            # actor branched the node while a stream was mid-flight.
+            #
+            # Surface it loudly and trigger session-level recovery via
+            # the on_node_locked callback so the next user input runs
+            # the auto-checkpoint guard. The 409'd event itself is
+            # lost (still in the local JSONL log), which is acceptable
+            # for a defense-in-depth path.
+            if exc.status_code == 409:
+                if target_node_id not in self._locked_node_notified:
+                    self._locked_node_notified.add(target_node_id)
+                    logger.error(
+                        "Backend refused event on branched node %s — durable event "
+                        "log will be out of sync until the next user input triggers "
+                        "the auto-checkpoint guard. Failed event: %s",
+                        target_node_id, event.get("event_type"),
+                    )
+                    if self._on_node_locked is not None:
+                        try:
+                            self._on_node_locked(target_node_id)
+                        except Exception:
+                            logger.exception("on_node_locked callback raised")
+                return None
+            logger.warning("Failed to send event to backend: %s", exc)
+            return None
         except Exception as exc:
             logger.warning("Failed to send event to backend: %s", exc)
             return None

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

@@ -97,3 +97,50 @@ def parse_branch_flag(buffered_head: str) -> tuple[float | None, str]:
     except ValueError:
         return None, buffered_head[m.end():]
     return confidence, buffered_head[m.end():]
+
+
+def strip_all_branch_tags(text: str) -> tuple[float | None, str]:
+    """Strip every leading BRANCH tag from `text` and return (confidence, rest).
+
+    Defensive against three model misbehaviours, in one place so every
+    driver inherits the same protection:
+
+      - **Multiple stacked tags** — e.g. `<!--BRANCH:0.0--><!--BRANCH:0.5-->Hi`.
+        We loop `parse_branch_flag` and strip them all; the *first*
+        confidence wins (subsequent tags are usually a model emitting
+        the marker more than once, not actually multiple decisions).
+
+      - **Partial tag at end** — e.g. `<!--BRANCH:0.5` with no closing
+        `-->`. Happens when a tool call interrupts a tag stream. We drop
+        the partial-tag bytes so they don't leak into rendered text.
+
+      - **Malformed digits** — handled inside `parse_branch_flag`
+        (the tag is consumed silently, no confidence reported).
+
+    Returns the first valid confidence found (or None if no parseable
+    tag was at the head), and the remaining text after all leading tags
+    are stripped (or empty string if the remaining content was a
+    partial-tag prefix).
+    """
+    first_confidence: float | None = None
+    buf = text
+    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.
+        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 = ""
+
+    return first_confidence, buf