Shepherd: Reversible Execution Traces for Agents

Shepherd is not simply “Git for agents.” It is an early-alpha runtime that tries to make an agent’s execution—a typed event history coupled to process, filesystem, bindings, and environment—branchable, replayable, inspectable, and reviewable. The current public workflow is useful even before the deeper research model: run work as a retained proposal, inspect the changeset, then explicitly apply or discard it.

The Git-like execution model

The project’s central object is a reversible, typed execution trace. A model action, tool call, and environment change become structured events rather than only messages in a transcript. The paper maps the core operations to familiar version-control ideas:

The Git analogy is a mental model, not a claim that an ordinary Git repository contains the whole runtime. Shepherd’s paper describes scope.fork() as coupling the worker’s filesystem, processes, and bindings into a copy-on-write child. That is the part a transcript or Docker commit normally lacks: the branch is meant to include the continuation of the agent, not only a disk image.

The formal model divides effects into three tiers:

• Reversible: filesystem writes and sandbox state can be restored by the runtime.
• Compensable: services or database writes require application-provided compensation handlers.
• Irreversible: model calls, payments, and outbound email are recorded for audit but cannot be undone by discarding a branch.

That last category is a hard boundary. “Reversible execution” does not mean time travel for everything an agent can do.

The current retained-run workflow

The current public docs emphasize a retained run that keeps proposed work beside the user’s files until it is explicitly settled. The conceptual flow is:

That review boundary complements AgentPedia’s Agent Plugins 1.0 guide, which focuses on portable tool packaging, and its Hermes Kanban guide, which focuses on durable multi-agent task state rather than reversible execution state.

import shepherd as sp

run = sp.run(task, workspace=workspace)
output = run.output()

print(output.changeset())
print(output.trace())

# Choose deliberately after review:
output.select()   # or apply(), release(), or discard()

The exact API is version-sensitive; the official documentation currently applies to Shepherd v0.3.0. The important operational pattern is stable:

1. Define a typed task and named bindings.
2. Run it in a retained workspace.
3. Inspect the trace, proposed changeset, and files.
4. Select, apply, release, or discard the result.
5. Keep the source workspace unchanged until the review decision.

The quickstart’s review step is more valuable than the Git slogan. It creates a proposal boundary between an agent’s work and the user’s workspace. For a code task, that means a reviewer can inspect the candidate diff before applying it. For a long-running workflow, it creates a point from which a supervisor can branch or reject a continuation.

Permissions and environment state

Shepherd expresses permissions in the task contract. The project documentation uses repository handles such as a writable sp.GitRepo and a read-only May[GitRepo, ReadOnly] binding. That makes authority visible in a function signature instead of leaving the entire policy inside a prompt.

The runtime also targets OS-level enforcement through macOS Seatbelt and Linux Landlock in a privileged container. Windows is unsupported; the README directs Windows users toward WSL. The practical rule is to inspect the selected placement rather than assume every placement enforces grants equally.

A typed permission is not a complete threat model. You still need to verify:

• which process receives the binding;
• whether network access is enabled;
• how credentials enter the sandbox;
• what happens when a tool call fails;
• whether external side effects have compensation handlers;
• and whether the retained output can be inspected before settlement.

The current shipped API is narrower than the paper’s conceptual model. Ambient task-to-task delegation and returned handles are described as future or roadmap capabilities in the public documentation. Do not write a tutorial that assumes every paper primitive is available in the released package.

Traces versus snapshots and transcripts

The paper frames Shepherd against several neighboring approaches. The following is a conceptual comparison based on the paper’s capability table, not an independent benchmark of every system.

A transcript tells you what an agent said and which tools it called, but restoring it requires rebuilding the environment and deciding how to replay the messages. A snapshot restores an environment image but does not make typed execution history a first-class branchable object. Docker commit captures filesystem state; it does not preserve the worker’s prompt-cache continuity or task semantics.

Shepherd’s advantage, if its implementation and backend provide the promised coupling, is that the branch point can include state that matters to the next model decision. That is also why its guarantees are more complicated than a file diff.

For a separate example of keeping model claims tied to validation boundaries, see the scientific software validation guide.

Supervision, replay, and training

The paper reports three useful applications.

Live supervision

In a CooperBench experiment, two Claude Haiku 4.5 workers ran parallel feature tasks while a Sonnet 4.6 or Opus 4.7 supervisor used inject, handoff, and discard. The reported joint-pair pass rate rose from 28.8% to 54.7% across 479 pairs.

This is not a general agent-quality guarantee. The result depends on the benchmark, worker and supervisor models, coordination tools, and the definition of a passing pair. The paper also reports 1–5 minutes of supervisor overhead. The useful design lesson is narrower: a supervisor can inspect a live branch and intervene without treating the whole workflow as an opaque conversation.

Counterfactual replay optimization

Counterfactual Replay Optimization, or CRO, forks at the first affected point and replays only the divergent suffix. In the paper’s experiments, CRO outperformed MetaHarness on four of five listed datasets and reduced optimization wall-clock by 27–58% relative to MetaHarness. The detailed table covers HoVer, MATH, IFBench, LiveCodeBench, and TerminalBench 2.0, using GPT-5.4-mini as executor and a 20-candidate budget for most datasets.

The paper reports that CRO was not uniformly best: MetaHarness led IFBench by about one point within the reported variance. Read this as an execution-efficiency experiment, not proof that every prompt optimizer or agent workload will improve.

Tree-GRPO

Tree-GRPO uses sibling branches for finer-grained credit assignment in training. On held-out Terminal-Bench 2.0, the paper reports Qwen3.5-35B-A3B improving from 34.2% Flat GRPO to 39.4% Tree-GRPO, and Nemotron-3-Super-120B-A12B improving from 33.8% to 37.2%. The experiment used 89 tasks and five seeds.

Those are reported training results using a filtered Endless Terminals corpus and a Tinker-based setup. They do not show that every reinforcement-learning workload benefits equally.

Performance and formal limits

Shepherd’s fork measurements are more useful when shown with their conditions:

The authors measured these on a Vultr instance with 2 vCPU, 16 GB RAM, SSD storage, Ubuntu 22.04, Docker 29.3.1, and overlay2. A full root filesystem copy took 53,462 ms to fork and 25,943 ms to revert for the 5.8 GB image. Modal used separate hosted hardware and included network round-trip, so it should not be treated as the same setup.

The paper also reports roughly 95% prompt-cache hit rate after replay reaches a certain fork depth in an eight-task Claude Haiku 4.5 Terminal-Bench test. That is cache reuse for a specified provider, model, task set, and replay pattern—not a promise that all compute or cost disappears.

The formal work is similarly bounded. The paper describes a Lean-mechanized semantic core and proof envelope for typed effect traces. It explicitly does not verify arbitrary Python control flow, provider SDK behavior, model outputs, prompt-cache state, shell commands, filesystem correctness, Docker/sandbox implementations, storage, scheduling, cancellation, retries, recovery, or multi-branch replay.

Maturity and adoption

Shepherd’s repository is MIT-licensed, supports Python 3.11+, and documents macOS Seatbelt plus Linux Landlock paths. It labels the project alpha, and the docs call it an early development preview that should not be used for production or business-critical workflows. The current release is v0.3.0.

That makes Shepherd a good fit for:

• agent-runtime research;
• reversible coding experiments;
• supervised multi-agent prototypes;
• prompt or workflow optimization experiments;
• and teams willing to pin a version and inspect the experiment substrate.

It is a poor fit for business-critical automation that assumes every side effect can be rolled back, every backend has identical enforcement, or the pre-1.0 API will remain stable.

FAQ

Is Shepherd production-ready?

No. The project labels itself alpha and warns against business-critical production use.

Can Shepherd undo a payment or email?

No. Those are irreversible external effects. Shepherd can record them for audit, but discarding a branch does not reverse them.

Is Shepherd ordinary Git for agents?

No. Git is the analogy. Shepherd aims to couple typed execution effects with worker, filesystem, process, and binding state.

What does formal verification cover?

The paper describes a verified semantic core, not a proof that arbitrary Python, model output, shell commands, storage, scheduling, retries, or every sandbox backend behave correctly.

Sources and links

Primary project sources

• Shepherd project site
• Shepherd documentation
• Shepherd runtime repository
• Shepherd experiments repository

Paper

• arXiv abstract: 2605.10913
• HTML paper

Related implementation references

• Shepherd quickstart source
• Shepherd v0.3.0 release