webbee 0.2.3__tar.gz → 0.3.1__tar.gz

{webbee-0.2.3 → webbee-0.3.1}/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.3.1
+
+- Auto-checkpointing no longer disables itself after a single transient
+  shadow-git error — it only pauses after repeated failures, and
+  `/checkpoints` shows when it's paused.
+
+## 0.3.0
+
+- **The agent plans in the open.** A live todo checklist (📋) rendered from the
+  kernel's todo facts — you see what Webbee intends and how far it's got.
+- **Precise editing.** `edit_file` requires a unique match (or an explicit
+  `replace_all`), and a new atomic `multi_edit` applies coordinated changes
+  across files all-or-nothing.
+- **The time machine.** Every change auto-checkpoints into a shadow git — your
+  own `.git` is never touched; `/checkpoints` lists them and `/rollback`
+  restores, and the agent can checkpoint/diff/rollback too. A wrong step is
+  now undoable.
+
 ## 0.2.3
 
 - **Readable big numbers.** Token and credit counts in the toolbar now scale

{webbee-0.2.3 → webbee-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webbee
-Version: 0.2.3
+Version: 0.3.1
 Summary: Webbee 🐝 — the Imperal Cloud coding agent in your terminal
 Project-URL: Homepage, https://imperal.io
 Project-URL: Documentation, https://docs.imperal.io

{webbee-0.2.3 → webbee-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "webbee"
-version = "0.2.3"
+version = "0.3.1"
 description = "Webbee 🐝 — the Imperal Cloud coding agent in your terminal"
 readme = "README.md"
 license = "MIT"

webbee-0.3.1/src/webbee/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.1"

webbee-0.3.1/src/webbee/checkpoints.py

@@ -0,0 +1,234 @@
+"""The session's TIME MACHINE (whole-mind Phase 4, I-WEBBEE-CODE-REVERSIBLE).
+
+A shadow git repository whose GIT_DIR lives in the webbee cache and whose
+worktree is the user's workspace (the classic detached-git-dir pattern).
+The user's own VCS -- .git, index, refs, hooks -- is NEVER touched:
+reversibility is ours, not theirs. Every write tool auto-checkpoints before
+it runs (tools.py); `rollback` snapshots the pre-rollback state first, so a
+rollback is itself undoable. Fail-soft everywhere: no git binary / init
+failure => available=False and every operation degrades to an honest
+message -- the time machine must never block the work."""
+import os
+import subprocess
+
+# Identity + safety for shadow commits only (never the user's config/hooks).
+_GIT_CFG = ["-c", "user.name=webbee", "-c", "user.email=webbee@imperal.io",
+            "-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null"]
+
+
+def shadow_key(workspace_root: str) -> str:
+    """Shadow identity is the WORKTREE, never the remote: clones and linked
+    git-worktrees of one origin must each get their OWN time machine
+    (final-review F3 -- a shared shadow rolls checkout B onto checkout A's
+    snapshot). sha256 of the realpath, 12 hex chars (intel keeps its own
+    content-addressed repo_key; this one is deliberately different)."""
+    import hashlib
+    real = os.path.realpath(workspace_root)
+    return hashlib.sha256(real.encode("utf-8")).hexdigest()[:12]
+
+
+def _scrubbed_env() -> dict:
+    """A GIT_*-free copy of the environment (final-review F2): git exports
+    GIT_INDEX_FILE / GIT_DIR / GIT_OBJECT_DIRECTORY / GIT_COMMON_DIR into hook
+    and rebase contexts -- inherited, they silently redirect SHADOW operations
+    into the USER's repository. Explicit --git-dir/--work-tree flags override
+    only two of them; scrub them all."""
+    return {k: v for k, v in os.environ.items() if not k.startswith("GIT_")}
+
+
+class ShadowGit:
+    _DIFF_CAP = 20000
+
+    def __init__(self, workspace_root: str, repo_key: str, cache_dir: str = "") -> None:
+        self.root = os.path.realpath(workspace_root)
+        base = cache_dir or os.path.expanduser("~/.cache/webbee")
+        self.git_dir = os.path.join(base, "shadow", repo_key)
+        self.available = False
+        self.auto_ok = True        # auto-checkpointing enabled (F8 latch below)
+        self._auto_fail_streak = 0  # consecutive failed AUTO snapshots
+
+    def _git(self, *args: str) -> "subprocess.CompletedProcess":
+        cmd = (["git", "--git-dir", self.git_dir, "--work-tree", self.root]
+               + _GIT_CFG + list(args))
+        return subprocess.run(cmd, capture_output=True, text=True, timeout=120,
+                              env=_scrubbed_env())
+
+    def ensure(self) -> bool:
+        """Create/open the shadow. Returns availability; never raises.
+        Refuses a workspace that IS a bare git repository (final-review F9:
+        tracking its refs/objects and resetting them would rewind the USER's
+        VCS -- the one thing the shadow must never do)."""
+        try:
+            if (os.path.exists(os.path.join(self.root, "HEAD"))
+                    and os.path.isdir(os.path.join(self.root, "objects"))
+                    and os.path.isdir(os.path.join(self.root, "refs"))):
+                self.available = False
+                return False
+            os.makedirs(self.git_dir, mode=0o700, exist_ok=True)
+            os.chmod(self.git_dir, 0o700)
+            if not os.path.exists(os.path.join(self.git_dir, "HEAD")):
+                r = subprocess.run(["git"] + _GIT_CFG + ["init", "--bare", self.git_dir],
+                                   capture_output=True, text=True, timeout=60,
+                                   env=_scrubbed_env())
+                if r.returncode != 0:
+                    self.available = False
+                    return False
+                # Detached-git-dir mode: bare layout + explicit --work-tree.
+                self._git("config", "core.bare", "false")
+                excl = os.path.join(self.git_dir, "info", "exclude")
+                os.makedirs(os.path.dirname(excl), exist_ok=True)
+                with open(excl, "a", encoding="utf-8") as f:
+                    f.write("\n.git/\n")
+            self.available = self._git("rev-parse", "--git-dir").returncode == 0
+        except Exception:
+            self.available = False
+        return self.available
+
+    # -- internals ---------------------------------------------------------
+
+    def _count(self) -> int:
+        r = self._git("for-each-ref", "--format=%(refname)", "refs/webbee/")
+        return len([ln for ln in r.stdout.splitlines() if ln.strip()])
+
+    def _resolve(self, ref: str) -> "str | None":
+        ref = (ref or "").strip()
+        if not ref:
+            return None
+        if ref.isdigit():
+            cand = f"refs/webbee/cp-{ref}"
+        elif ref.startswith("cp-"):
+            cand = f"refs/webbee/{ref}"
+        else:
+            cand = ref
+        r = self._git("rev-parse", "--verify", "--quiet", cand + "^{commit}")
+        return r.stdout.strip() if r.returncode == 0 else None
+
+    # -- operations ---------------------------------------------------------
+
+    def checkpoint(self, label: str = "", force: bool = False) -> "dict | None":
+        """Commit the workspace state to the shadow history.
+        {"id","n","label","changed"} or None when unavailable/failed.
+        `force=True` always records a new checkpoint even with nothing dirty
+        -- used by rollback() for its mandatory pre-rollback safety snapshot,
+        which must exist even when the workspace already matches HEAD."""
+        if not self.available:
+            return None
+        try:
+            if self._git("add", "-A").returncode != 0:
+                return None          # a partial add must never masquerade as a snapshot
+            dirty = self._git("status", "--porcelain").stdout.strip()
+            head = self._git("rev-parse", "--short", "HEAD")
+            if not dirty and head.returncode == 0 and not force:
+                return {"id": head.stdout.strip(), "n": self._count(),
+                        "label": "(no changes)", "changed": False}
+            msg = (label or "checkpoint").strip()[:200] or "checkpoint"
+            args = ["commit", "-m", msg, "--no-verify"]
+            if head.returncode != 0 or not dirty:
+                args.append("--allow-empty")      # first-ever baseline / forced snapshot
+            c = self._git(*args)
+            if c.returncode != 0:
+                return None
+            sha = self._git("rev-parse", "--short", "HEAD").stdout.strip()
+            n = self._count() + 1
+            self._git("update-ref", f"refs/webbee/cp-{n}", "HEAD")
+            return {"id": sha, "n": n, "label": msg, "changed": True}
+        except Exception:
+            return None
+
+    def list_checkpoints(self, limit: int = 10) -> list:
+        """Newest-first [{'n','id','label','when'}] from the refs/webbee ledger."""
+        if not self.available:
+            return []
+        try:
+            r = self._git(
+                "for-each-ref",
+                "--format=%(refname:short)|%(objectname:short)|%(contents:subject)|%(creatordate:relative)",
+                "refs/webbee/")
+            rows = []
+            for line in r.stdout.splitlines():
+                parts = line.split("|", 3)
+                if len(parts) == 4 and parts[0].startswith("webbee/cp-"):
+                    rows.append({"n": int(parts[0].rsplit("-", 1)[1]),
+                                 "id": parts[1], "label": parts[2], "when": parts[3]})
+            rows.sort(key=lambda x: x["n"], reverse=True)
+            return rows[:max(1, int(limit))]
+        except Exception:
+            return []
+
+    def diff(self, since: str = "") -> str:
+        """Workspace changes since a checkpoint (default: the last one).
+        Bounded with an HONEST truncation note -- never a silent cut."""
+        if not self.available:
+            return "reversibility is off (git unavailable)"
+        try:
+            self._git("add", "-A")   # stage into the SHADOW index so new files show
+            target = self._resolve(since) or "HEAD"
+            stat = self._git("diff", "--cached", "--stat", target).stdout
+            body = self._git("diff", "--cached", target).stdout
+            out = (stat + "\n" + body).strip() or "(no changes)"
+            if len(out) > self._DIFF_CAP:
+                out = (out[:self._DIFF_CAP]
+                       + f"\n… (diff truncated at {self._DIFF_CAP} chars -- pass a "
+                         f"narrower `since` or inspect files directly)")
+            return out
+        except Exception as e:
+            return f"diff failed: {type(e).__name__}: {e}"
+
+    def rollback(self, to: str) -> dict:
+        """Restore every checkpointed file to checkpoint `to`. The current
+        state is checkpointed FIRST ("pre-rollback"), so a rollback is itself
+        undoable. Files never checkpointed are not removed."""
+        if not self.available:
+            return {"ok": False, "content": "reversibility is off (git unavailable)"}
+        target = self._resolve(to)
+        if not target:
+            return {"ok": False, "content":
+                    f"unknown checkpoint '{to}' -- use an id, cp-N or N "
+                    f"(see the checkpoint list)"}
+        undo = self.checkpoint("pre-rollback", force=True)
+        if not undo:
+            # The safety snapshot is MANDATORY: without it a reset would
+            # destroy the current state unrecoverably (final-review F1).
+            return {"ok": False, "content":
+                    "rollback refused: the pre-rollback safety snapshot could not "
+                    "be created (shadow git error), so rolling back would destroy "
+                    "the current state unrecoverably. Fix the shadow (disk space / "
+                    "permissions) or copy your changes out first."}
+        r = self._git("reset", "--hard", target)
+        if r.returncode != 0:
+            return {"ok": False, "content": f"rollback failed: {r.stderr.strip()[:500]}"}
+        return {"ok": True, "content":
+                (f"restored the workspace to checkpoint {to} ({target[:9]}). "
+                 f"The previous state -- including any files this rollback removed -- "
+                 f"was saved first as checkpoint cp-{(undo or {}).get('n', '?')} "
+                 f"({(undo or {}).get('id', '?')}), so this rollback is itself undoable.")}
+
+    _AUTO_FAIL_LATCH = 3   # consecutive AUTO failures before pausing auto-checkpointing
+
+    def note_auto_result(self, ok: bool) -> None:
+        """Record an AUTO (pre-write) snapshot outcome. A single transient
+        failure must NOT disable the session's time machine (final-review F8):
+        latch auto-checkpointing OFF only after _AUTO_FAIL_LATCH CONSECUTIVE
+        failures; any success resets the streak and re-enables it."""
+        if ok:
+            self._auto_fail_streak = 0
+            self.auto_ok = True
+        else:
+            self._auto_fail_streak += 1
+            if self._auto_fail_streak >= self._AUTO_FAIL_LATCH:
+                self.auto_ok = False
+
+    def describe(self) -> str:
+        """One printable block for the /checkpoints command."""
+        if not self.available:
+            return "Reversibility is off (git unavailable)."
+        rows = self.list_checkpoints(limit=10)
+        if not rows:
+            body = "No checkpoints yet."
+        else:
+            lines = [f"cp-{r['n']}  {r['id']}  {r['when']:>16}  {r['label']}" for r in rows]
+            body = "Checkpoints (newest first) — /rollback <id|cp-N|N>:\n" + "\n".join(lines)
+        if not self.auto_ok:
+            body = ("⚠ Auto-checkpointing is paused after repeated shadow errors — "
+                     "manual /checkpoint + /rollback still work.\n") + body
+        return body

{webbee-0.2.3 → webbee-0.3.1}/src/webbee/commands.py

@@ -11,6 +11,8 @@ _HELP = """Commands:
   /cost  (=/usage)   tokens + credits this session
   /status            cwd · git · surface · tokens · version
   /steps [N]         last turn's steps; N expands one (also: Up/Down + Enter)
+  /checkpoints       the reversibility time machine — list workspace checkpoints
+  /rollback <ref>    restore the workspace to a checkpoint (id, cp-N or N)
   /sessions          list active sessions (this + other devices)
   /sessions revoke <#>   revoke a session by its number
   /logout-others     sign out every session except this one
@@ -79,6 +81,10 @@ def dispatch(line: str, ctx: CommandContext) -> SlashResult:
         if args:
             return SlashResult(handled=True, action="step_detail", arg=args[0])
         return SlashResult(handled=True, action="steps")
+    if cmd == "/checkpoints":
+        return SlashResult(handled=True, action="checkpoints")
+    if cmd == "/rollback":
+        return SlashResult(handled=True, action="rollback", arg=" ".join(args))
     if cmd == "/mode":
         if not args:
             return SlashResult(handled=True, action="mode", new_mode=None,

{webbee-0.2.3 → webbee-0.3.1}/src/webbee/frames.py

@@ -129,7 +129,7 @@ def handle_action_frame(frame: dict, sink, started: set, finished: set, steps: l
 # composes ONE human-readable line per fact (I-FRAMES-FACTS-ONLY). Defensive:
 # unknown / missing fields degrade to a bare label, never crash.
 
-_MARATHON_FACT_TYPES = ("marathon_plan", "milestone", "marathon_paused")
+_MARATHON_FACT_TYPES = ("marathon_plan", "milestone", "marathon_paused", "todo")
 
 
 def marathon_note(frame: dict) -> str:
@@ -154,4 +154,12 @@ def marathon_note(frame: dict) -> str:
     if ftype == "marathon_paused":
         reason = str(frame.get("reason") or frame.get("summary") or "").strip()
         return f"⏸ Marathon paused: {reason}" if reason else "⏸ Marathon paused"
+    if ftype == "todo":
+        todos = frame.get("todos") if isinstance(frame.get("todos"), list) else []
+        total = frame.get("total", len(todos))
+        done = frame.get("completed", 0)
+        current = next((str(t.get("content", "")) for t in todos
+                        if isinstance(t, dict) and t.get("status") == "in_progress"), "")
+        head = f"📋 Todos {done}/{total}"
+        return f"{head} — now: {current}" if current else head
     return str(frame.get("type", ""))

{webbee-0.2.3 → webbee-0.3.1}/src/webbee/repl.py

@@ -80,6 +80,17 @@ async def run_marathon(cfg, mode: str, goal: str, *, sink=None, auth=None,
     return text
 
 
+def _default_shadow_factory(cfg, workspace: str):
+    """The reversibility shadow git. Guarded like intel: any failure (no git
+    binary, cache not writable) degrades to None -- coding still works, just
+    without the time machine."""
+    from webbee.checkpoints import ShadowGit, shadow_key
+    from webbee.repo import find_repo_root
+    root = find_repo_root(workspace)
+    sg = ShadowGit(root, shadow_key(root), cache_dir=cfg.cache_dir)
+    return sg if sg.ensure() else None
+
+
 def _default_intel_factory(cfg, workspace: str):
     """Lazy/guarded -- a base install (no tree-sitter/watchfiles extra) must
     never fail to import here; `_boot` wraps the whole intel boot in
@@ -93,7 +104,7 @@ def _default_intel_factory(cfg, workspace: str):
 
 async def run_repl(cfg, mode: str = "default", *, once: bool = False, sink=None, read_line=input,
                    agent_factory=None, auth=None, account_fetcher=None,
-                   sessions_client=None, intel_factory=None) -> None:
+                   sessions_client=None, intel_factory=None, shadow_factory=None) -> None:
     """Interactive coding REPL. Production (a real tty, no injected sink) runs
     the persistent prompt_toolkit dock (`tui.run_session`): the bordered input
     box is pinned at the bottom, turn output scrolls above it (patch_stdout →
@@ -103,7 +114,7 @@ async def run_repl(cfg, mode: str = "default", *, once: bool = False, sink=None,
         from imperal_mcp import auth as _auth
         auth = _auth
     if agent_factory is None:
-        agent_factory = lambda c, tp, ws, m: AgentSession(c, tp, ws, m, intel=intel)  # noqa: E731
+        agent_factory = lambda c, tp, ws, m: AgentSession(c, tp, ws, m, intel=intel, shadow=shadow)  # noqa: E731
     if account_fetcher is None:
         from webbee.account import fetch_account as account_fetcher
     if sessions_client is None:
@@ -121,6 +132,7 @@ async def run_repl(cfg, mode: str = "default", *, once: bool = False, sink=None,
     _sink = None         # assigned by _boot
     agent = None         # assigned by _boot
     intel = None         # assigned by _boot -- IntelService, or None (off/base-install/boot failure)
+    shadow = None        # assigned by _boot -- ShadowGit, or None (git unavailable / boot failure)
     watcher_task = None  # assigned by _boot -- background watchfiles task, cancelled on exit
 
     def _cycle() -> None:
@@ -211,6 +223,21 @@ async def run_repl(cfg, mode: str = "default", *, once: bool = False, sink=None,
                 else:
                     _sink.note("Detail unavailable (expired or not recorded).")
                 return "continue"
+            if res.action == "checkpoints":
+                if shadow is None:
+                    _sink.note("Reversibility is off (git unavailable).")
+                else:
+                    _sink.note(await asyncio.to_thread(shadow.describe))
+                return "continue"
+            if res.action == "rollback":
+                if shadow is None:
+                    _sink.note("Reversibility is off (git unavailable).")
+                elif not res.arg:
+                    _sink.note("Usage: /rollback <id|cp-N|N>  (see /checkpoints)")
+                else:
+                    _r = await asyncio.to_thread(shadow.rollback, res.arg)
+                    _sink.note(str(_r.get("content", "")))
+                return "continue"
             if res.action == "clear":
                 _sink.clear()
                 _sink.note(res.message)
@@ -238,7 +265,7 @@ async def run_repl(cfg, mode: str = "default", *, once: bool = False, sink=None,
         return "continue"
 
     async def _boot(s) -> None:
-        nonlocal _sink, agent, intel, watcher_task
+        nonlocal _sink, agent, intel, watcher_task, shadow
         _sink = s
         # Cache git branch OFF the event loop (subprocess.run blocks it). Only
         # /status reads it; recomputing it per input line froze the dock.
@@ -260,6 +287,12 @@ async def run_repl(cfg, mode: str = "default", *, once: bool = False, sink=None,
             except Exception:
                 intel = None
                 watcher_task = None
+        # Whole-mind P4: the reversibility shadow (never the user's VCS);
+        # guarded -- boot must not fail over the time machine.
+        try:
+            shadow = await asyncio.to_thread(shadow_factory or _default_shadow_factory, cfg, workspace)
+        except Exception:
+            shadow = None
         agent = agent_factory(cfg, token_provider, workspace, state["mode"])
 
     if use_dock:

{webbee-0.2.3 → webbee-0.3.1}/src/webbee/session.py

@@ -142,7 +142,8 @@ class AgentSession:
     P1: one POST per turn (server reloads the shared webbee-terminal thread,
     so context carries across turns). Persistent signal-based sessions are P3."""
 
-    def __init__(self, cfg, token_provider, workspace_root: str, mode: str = "default", intel=None) -> None:
+    def __init__(self, cfg, token_provider, workspace_root: str, mode: str = "default", intel=None,
+                 shadow=None) -> None:
         self.cfg = cfg
         self.token_provider = token_provider
         self.workspace_root = workspace_root
@@ -151,6 +152,7 @@ class AgentSession:
         self.steps: list = []
         self._task_id: str = ""
         self._intel = intel  # IntelService, or None (base install / boot failure)
+        self._shadow = shadow  # ShadowGit, or None (git unavailable / boot failure)
 
     async def _headers(self) -> dict:
         token = await self.token_provider()
@@ -173,7 +175,8 @@ class AgentSession:
             verify_cmd = await asyncio.to_thread(detect_verify_cmd, root)
             coding_context = {**coding_context, "verify_cmd": verify_cmd}
         imperal_id = await ImperalClient(self.cfg, self.token_provider).whoami()
-        executor = LocalToolExecutor(self.workspace_root, indexer=self._intel)
+        executor = LocalToolExecutor(self.workspace_root, indexer=self._intel,
+                                     shadow=self._shadow)
 
         body = {"user_id": imperal_id, "task": task, "coding_context": coding_context}
         if marathon:

{webbee-0.2.3 → webbee-0.3.1}/src/webbee/tools.py

@@ -3,14 +3,20 @@ import re
 import subprocess
 
 
+# Tools that MUTATE the workspace -> auto-checkpoint before each run
+# (mirrors the kernel write tier; rollback snapshots itself, so not listed).
+_WRITE_TIER = {"write_file", "edit_file", "multi_edit", "bash"}
+
+
 class OutsideWorkspaceError(Exception):
     pass
 
 
 class LocalToolExecutor:
-    def __init__(self, workspace_root: str, indexer=None) -> None:
+    def __init__(self, workspace_root: str, indexer=None, shadow=None) -> None:
         self.root = os.path.realpath(workspace_root)
         self.indexer = indexer  # IntelService (or None on a base install) -- Task 5's _t_<verb> shims read this
+        self.shadow = shadow    # ShadowGit (or None) -- the reversibility time machine
 
     def resolve_in_workspace(self, path: str) -> str:
         full = os.path.realpath(os.path.join(self.root, path))
@@ -28,6 +34,22 @@ class LocalToolExecutor:
                 args = {}
         if not isinstance(args, dict):
             args = {}
+        if (tool in _WRITE_TIER and self.shadow is not None
+                and getattr(self.shadow, "auto_ok", True)):
+            # The time machine snapshots BEFORE every mutation -- and must never
+            # block or fail the actual work. A SINGLE transient failure must not
+            # disable the session (final-review F8): note_auto_result latches
+            # auto-checkpointing OFF only after several CONSECUTIVE failures; a
+            # success re-enables it. Manual checkpoint/rollback always try.
+            try:
+                _cp = self.shadow.checkpoint(f"pre:{tool}")
+                _note = getattr(self.shadow, "note_auto_result", None)
+                if _note is not None:
+                    _note(_cp is not None)
+            except Exception:
+                _note = getattr(self.shadow, "note_auto_result", None)
+                if _note is not None:
+                    _note(False)
         try:
             fn = getattr(self, f"_t_{tool}", None)
             if fn is None:
@@ -82,11 +104,99 @@ class LocalToolExecutor:
             return {"ok": False, "content": "edit_file requires 'old' (the text to replace)"}
         with open(p, "r", encoding="utf-8") as f:
             text = f.read()
-        if old not in text:
+        n = text.count(old)
+        if n == 0:
             return {"ok": False, "content": "old string not found"}
+        _ra = a.get("replace_all")
+        replace_all = (_ra.strip().lower() in ("true", "1", "yes")
+                       if isinstance(_ra, str) else bool(_ra))
+        if n > 1 and not replace_all:
+            return {"ok": False, "content":
+                    f"old string occurs {n} times; add surrounding context to make it "
+                    f"unique, or pass replace_all=true to replace every occurrence"}
         with open(p, "w", encoding="utf-8") as f:
-            f.write(text.replace(old, new, 1))
-        return {"ok": True, "content": f"edited {rel}"}
+            f.write(text.replace(old, new) if replace_all else text.replace(old, new, 1))
+        note = f" ({n} occurrences)" if replace_all and n > 1 else ""
+        return {"ok": True, "content": f"edited {rel}{note}"}
+
+    def _t_multi_edit(self, a: dict) -> dict:
+        edits = a.get("edits")
+        if not isinstance(edits, list) or not edits:
+            return {"ok": False, "content": "multi_edit requires a non-empty 'edits' list"}
+        # Validate EVERYTHING first -- all-or-nothing (a half-applied batch is
+        # worse than a failed one).
+        staged = []
+        problems = []
+        for i, e in enumerate(edits):
+            if not isinstance(e, dict):
+                problems.append(f"edit {i}: not an object")
+                continue
+            try:
+                rel = self._rel(e)
+                p = self.resolve_in_workspace(rel)
+            except (ValueError, OutsideWorkspaceError) as err:
+                problems.append(f"edit {i}: {err}")
+                continue
+            old = e.get("old", e.get("old_string", ""))
+            new = e.get("new", e.get("new_string", ""))
+            if not old:
+                problems.append(f"edit {i} ({rel}): 'old' is required")
+                continue
+            try:
+                with open(p, "r", encoding="utf-8") as f:
+                    text = f.read()
+            except OSError as err:
+                problems.append(f"edit {i} ({rel}): {type(err).__name__}: {err}")
+                continue
+            n = text.count(old)
+            if n != 1:
+                problems.append(f"edit {i} ({rel}): 'old' occurs {n} times (must be exactly 1)")
+                continue
+            if not os.access(p, os.W_OK):
+                problems.append(f"edit {i} ({rel}): file is not writable")
+                continue
+            staged.append((p, rel, old, new))
+        if problems:
+            return {"ok": False, "content":
+                    "multi_edit applied NOTHING -- fix these and retry:\n" + "\n".join(problems)}
+        # Apply sequentially, re-reading so multiple edits to the SAME file
+        # compose; if an earlier edit invalidated a later one, stop honestly.
+        applied = []
+        for p, rel, old, new in staged:
+            with open(p, "r", encoding="utf-8") as f:
+                text = f.read()
+            if text.count(old) != 1:
+                return {"ok": False, "content":
+                        f"multi_edit stopped at {rel}: an earlier edit in this batch changed "
+                        f"the text around 'old' (applied so far: {', '.join(applied) or 'none'}); "
+                        f"re-read the file and retry the remaining edits"}
+            with open(p, "w", encoding="utf-8") as f:
+                f.write(text.replace(old, new, 1))
+            applied.append(rel)
+        return {"ok": True, "content": f"applied {len(applied)} edits: " + ", ".join(applied)}
+
+    def _t_checkpoint(self, a: dict) -> dict:
+        if self.shadow is None:
+            return {"ok": False, "content": "reversibility is unavailable (no shadow git)"}
+        cp = self.shadow.checkpoint(str(a.get("label", "") or "manual"))
+        if cp is None:
+            return {"ok": False, "content": "checkpoint failed (shadow git error)"}
+        note = "created" if cp.get("changed") else "no changes since the last checkpoint"
+        return {"ok": True, "content": f"checkpoint cp-{cp.get('n')} ({cp.get('id')}): {note}"}
+
+    def _t_diff(self, a: dict) -> dict:
+        if self.shadow is None:
+            return {"ok": False, "content": "reversibility is unavailable (no shadow git)"}
+        return {"ok": True, "content": self.shadow.diff(str(a.get("since", "") or ""))}
+
+    def _t_rollback(self, a: dict) -> dict:
+        if self.shadow is None:
+            return {"ok": False, "content": "reversibility is unavailable (no shadow git)"}
+        to = str(a.get("checkpoint", "") or a.get("to", "") or "")
+        if not to:
+            return {"ok": False, "content":
+                    "rollback requires 'checkpoint' (an id, cp-N or N -- see diff/checkpoint output)"}
+        return self.shadow.rollback(to)
 
     def _t_bash(self, a: dict) -> dict:
         timeout = min(int(a.get("timeout", 120) or 120), 3600)