Time Travel

Hour four of an overnight run: the plan node produced a subtly wrong plan, six downstream agents faithfully built on it, and the review node finally caught it. Without time travel your options are bad — start the whole run over and re-pay every token, or hand-edit the workspace and hope the orchestrator’s idea of state still matches the filesystem’s. Neither works, because agent runs have two kinds of state that drift apart the moment you touch one: the orchestrator’s database (which tasks ran, what they output) and the worktree (what the agents actually wrote to disk). Rolling back one without the other produces a run that is lying to itself. Time travel in Smithers means rolling both back together, to a point that was actually recorded — and, when you’d rather not destroy history, branching a new run from that point instead. Every task attempt records a jj commit pointer for its worktree; every render frame gets a snapshot of graph state. Those two ledgers are what make “go back to before the plan node and try again with a different prompt” a one-line command instead of an archaeology project. One distinction up front, because the industry uses “replay” for two different things. Deterministic replay (Temporal, rr) re-executes code against a recorded log and guarantees you reconstruct exactly the same state — which requires the code to be deterministic. State restoration + re-execution (Smithers, LangGraph) restores a persisted checkpoint and runs forward from it, fresh — no determinism contract, so LLM calls are legal, but the re-executed portion may (often deliberately) diverge from what happened before. Smithers is squarely in the second family: you go back to a real recorded state, and everything after it is a new future, not a reconstruction of the old one.

How the industry does it

System	Mechanism	What “going back” means	Tradeoff
Temporal reset	Copy the event history up to a `WorkflowTaskCompleted` reset point into a new execution; deterministic replay reconstructs state, then execution continues on current code — optionally re-applying later signals	Exact state reconstruction; used to carry bug fixes past a failure	Workflow code must be deterministic; resets nothing outside Temporal (no filesystem, no external side effects)
Azure Durable Functions rewind	`RewindAsync` puts a failed orchestration back into a running state by replaying from history	Failure recovery only — you cannot rewind a healthy run to explore	Preview-status API; same determinism contract as normal replay
Event sourcing / CQRS	State is a fold over an append-only event log; rebuild any past state by replaying a prefix	Temporal queries and full rebuilds for free	You must design every state change as an event; external side effects during replay need gateways/stubs
LangGraph time travel	`get_state_history` lists per-super-step checkpoints; invoking with a past `checkpoint_id` replays to it, `update_state` forks a new branch with edited state	Checkpoint restoration; forks are new branches, the original thread is untouched	Graph channel state only — no filesystem capture, so a coding agent’s actual edits aren’t part of the checkpoint
git worktrees + jj op log	Every repo mutation is itself versioned; `jj op restore` / `jj undo` rolls the whole repo — working copy included — to any prior operation	A true filesystem time machine	Knows nothing about why states existed; no link to task/attempt semantics
rr / Replay.io	Record nondeterministic inputs (syscalls, signals, shared-memory reads) once; re-execute deterministically any number of times	Perfect instruction-level replay of one process	Single-process debugging scope; heavy recording machinery, not an orchestration primitive
Redux DevTools	Actions are serializable and reducers pure, so the log can be sliced, reordered, and re-folded live	UI state scrubbing during development	Only works because reducers are pure — the property agent workloads lack
OpenAI Agents SDK sessions	Sessions persist conversation history per `session_id` across runs	Resume and continue; no rewind, fork, or branch operations	Memory persistence, not time travel
Antithesis	Run the whole system inside a deterministic simulation hypervisor; any moment can be revisited and branched to explore multiple futures	The strongest version of forking that exists	Requires your entire system to run inside their hypervisor; a testing platform, not a runtime

The jj operation log is the closest spiritual relative to what Smithers does for the filesystem — and not coincidentally, jj is the machinery Smithers uses under the hood. What no system above provides out of the box is the join: orchestration state and filesystem state rolled back as one unit, keyed by task attempt. That join is the whole point.

How Smithers does it

Two ledgers get written during every run, without workflow-author effort:

Graph snapshots per frame. Each render frame captures nodes, outputs, loop state, and input, content-hashed (sha256) and stored deduplicated across _smithers_snapshots, _smithers_snapshot_contents, and _smithers_snapshot_payload_refs (packages/time-travel/src/snapshot/captureSnapshotEffect.js). This is the source of truth for fork, replay, and timeline.
VCS pointers per attempt. Every task attempt records the worktree’s jj commit ID in _smithers_attempts.jj_pointer (plus jj_cwd), and the durability layer captures intermediate Tier 1/Tier 2 checkpoints in _smithers_workspace_checkpoints while the agent works.

Five operations act on those ledgers. They differ on two axes — destructive vs. branching and DB vs. filesystem — and picking the wrong one is the most common mistake, so here is the whole map:

Operation	Destroys history?	Resets DB state	Restores filesystem	Use when
`fork`	No — new child run	Copies snapshot into child; `--reset-node` marks nodes pending	No (child gets metadata only)	Branch an experiment without touching the parent
`replay`	No — new child run	Same as fork, then resumes execution	Optional (`--restore-vcs` restores the source frame’s revision)	“Run it again from frame 5 with different input”
`rewind`	Yes — deletes frames after target	Deletes frames, snapshots, and vcs-tags past the frame	Restores the frame’s recorded jj pointer	Roll one run back to an earlier frame, in place
`timetravel`	Yes — cancels later attempts	Resets target node and dependents to `pending`, deletes their output rows, truncates frames/snapshots past the attempt, flips the run back to `running`	Yes — `revertToJjPointer` on the attempt’s recorded commit	”Redo from this task” on the same run
`revert`	No DB reset at all	Nothing	Yes — worktree back to the attempt’s `jj_pointer`	Inspect or salvage filesystem state without touching the run

Separately, smithers restore <runId> --node <id> [--seq N] restores a worktree to a durability checkpoint — the finer-grained per-tool-call ledger — rather than a per-attempt pointer. Attempt pointers tell you where each task ended; durability checkpoints tell you every step of how it got there.

Forks are real child runs

forkRunEffect copies the parent’s snapshot at the chosen frame into a new run (fresh UUID, frame 0) and records the edge in _smithers_branches, all in one transaction. The child carries the parent’s outputs as already-satisfied state; only the nodes you --reset-node (plus, via expandResetSet, what depends on them) re-execute. Input overrides overlay the snapshot’s input, so a fork can ask “what if the input had been different.” Replay is fork + auto-resume — and if you pass an edited workflow file, replay re-blesses the child’s workflow hash so the resume guard accepts the very edit you’re carrying forward (replayFromCheckpointEffect.js). smithers timeline <runId> --tree renders the whole family: parent frames, fork points, and every child branch, derived purely from snapshot + branch rows.

# What happened, and where can I go back to?
smithers timeline RUN_ID --tree
smithers snapshots RUN_ID                      # per-tool-call worktree checkpoints

# Branch two experiments off frame 5; parent untouched
smithers fork workflow.tsx -r RUN_ID -f 5 -n analyze -i '{"model":"opus"}' -l exp-a
smithers replay workflow.tsx -r RUN_ID -f 5 --restore-vcs        # fork + resume

# Redo the same run from a bad task (filesystem + DB together), then resume
smithers timetravel workflow.tsx -r RUN_ID -n plan --resume

# Filesystem only — put the worktree back, decide later
smithers revert workflow.tsx -r RUN_ID -n implement --attempt 1

The side-effect boundary

Rolling back a database does not un-send an email. Every destructive operation (rewind, timetravel, revert) runs guardEffectBoundary before touching anything: it finds external effects recorded after the target point, executes registered revert compensation handlers for them, and blocks (TIME_TRAVEL_SIDE_EFFECT_BLOCKED) on any succeeded/unknown effect it cannot compensate — unless you pass --force, which records SideEffectBoundaryCrossed and marks the run needs-attention. Compensation is something you opt tools into:

import { defineTool } from "smithers-orchestrator/tools";
import { z } from "zod";

const createTicket = defineTool({
  name: "jira.create",
  schema: z.object({ title: z.string() }),
  sideEffect: true,
  async execute(args, ctx) {
    return jira.createIssue({ ...args, idempotencyKey: ctx.idempotencyKey });
  },
  // Time travel across this effect deletes the ticket instead of blocking.
  async revert(_args, ctx) {
    const ticket = await jira.findIssueByKey(ctx.idempotencyKey);
    if (ticket) await jira.deleteIssue(ticket.id);
  },
});

Branch operations (fork, replay) never compensate the parent’s effects — the parent’s history still happened. They stop before an effect-bearing boundary only when they would re-execute across it (replay, fork --run); a plain fork just warns. Git commits, branch moves, worktree writes, and git push are exempt from the boundary; external API mutations (issues, comments, PR merges) are not.

Safety machinery

Destructive operations are serialized and audited: a per-run rewind lock (lease-renewed at every step, checked again inside the DB transaction) prevents two concurrent time-travel operations; a rate limiter caps rewinds per window; every operation writes a row to a rewind audit table, with in-progress rows recovered at startup. A run that is running with a live owner or fresh heartbeat refuses time travel without force: true. All mutations run through the dialect-agnostic storage seam, so the same code path works on bun:sqlite, PGlite, and Postgres.

Guarantees and limits

Guaranteed: filesystem and DB state roll back atomically to a recorded point — the jj pointer restore happens before the DB transaction, and the transaction truncates frames, snapshots, and vcs-tags together so no derived view (fork, replay, timeline) can read discarded state. Forks never mutate the parent. Uncompensated external effects block by default rather than being silently crossed. Not guaranteed:

No deterministic re-execution. Re-run nodes call real agents with real nondeterminism. If you need “the replayed run provably does what the original did,” that is Temporal’s contract, not ours — see Smithers vs Temporal.
You can only travel to recorded points — attempts with a jj_pointer, frames with a snapshot. An attempt without a recorded pointer returns success: false.
--force means you own the consequences. Crossed effects are archived and the run is flagged, but the email is still sent.
Filesystem restore targets the worktree where the attempt ran (jj_cwd). If you deleted that worktree, there is nothing to restore into.
revert alone desynchronizes deliberately — worktree moves, DB does not. It exists for inspection; follow with timetravel if you want the run to agree.

Operating it

Day-to-day, from the CLI: timeline, snapshots, fork, replay, rewind RUN_ID FRAME_NO, timetravel, revert, restore, plus retry-task for the common “just redo this one task and resume” case. Every one has an MCP twin so an agent operating a run has the same surface: get_timeline, list_snapshots, fork_run, replay_run, rewind_run, time_travel, revert_attempt, restore_checkpoint — the destructive ones require confirm: true, and rewind/timetravel/revert accept --no-revert to skip compensation handlers (skipped effects become blockers).

Start

Articles

Learn

Capabilities

Build Workflows

Run and Operate

Workflow Pack

Components

Integrations

Agent Support

Examples

Contributing

How the industry does it

How Smithers does it

Forks are real child runs

The side-effect boundary

Safety machinery

Guarantees and limits

Operating it

See also

​How the industry does it

​How Smithers does it

​Forks are real child runs

​The side-effect boundary

​Safety machinery

​Guarantees and limits

​Operating it

​See also

How the industry does it

How Smithers does it

Forks are real child runs

The side-effect boundary

Safety machinery

Guarantees and limits

Operating it

See also