Revert to Attempt

Each successful task attempt captures the current JJ commit ID into _smithers_attempts.jj_pointer. The commit ID pins the exact workspace state even when later attempts amend the same JJ change. revert restores the workspace to that state and discards any graph snapshots recorded after the attempt began, rolling the run’s timeline back to that point in time.

API reference: Time Travel lists every revert and time-travel export, its options, and links to source and tests.

bunx smthrs revert workflow.tsx \
  --run-id RUN_ID --node-id NODE_ID [--attempt N=1] [--iteration N=0] \
  [--force] [--no-revert]

Revert restores files only, without altering JJ history; the restoration creates a new change on top of the current working copy. Before restoring files, revert checks every marked external effect that would be crossed. It runs registered handlers in reverse order, then prints an effect-boundary report. The report is printed for blocked, compensated, forced, and clean operations. --no-revert skips handlers. --force crosses any effects that remain, records SideEffectBoundaryCrossed, and marks the run for attention. Without --force, unresolved succeeded, unknown, revert-failed, or revert-stale effects stop the command with TIME_TRAVEL_SIDE_EFFECT_BLOCKED. Git commits, branch changes, worktree writes, and git push are exempt. GitHub issues, comments, releases, and PR merge state are external effects.

Requirements

JJ in PATH (brew install jj or cargo install jj-cli)
Workspace is a JJ repository (jj git init or jj init)
The target attempt was completed when JJ was available (otherwise no pointer was captured)

Programmatic

import { revertToAttempt, timeTravel } from "smthrs";

const result = await revertToAttempt(adapter, {
  runId: "abc123",
  nodeId: "implement",
  attempt: 2,
  iteration: 0,
});

where adapter is the SmithersDb instance for the run’s database. revertToAttempt never throws for a missing attempt or missing JJ pointer: it returns { success: false, error: string }, so inspect result.success to detect failures. On success it returns { success: true, jjPointer: string }.

type RevertOptions = {
  runId: string;
  nodeId: string;
  iteration: number;
  attempt: number;
  force?: boolean;
  noRevert?: boolean;
  onProgress?: (event: SmithersEvent) => void;
};

type RevertResult = {
  success: boolean;
  error?: string;
  jjPointer?: string;
  effectBoundary: EffectBoundaryReport;
};

function revertToAttempt(adapter: SmithersDb, opts: RevertOptions): Promise<RevertResult>;

Use timeTravel when you want the higher-level reset flow: it can restore VCS, reset the target node, and reset dependent nodes after the selected attempt.

const reset = await timeTravel(adapter, {
  runId: "abc123",
  nodeId: "implement",
  attempt: 2,
  iteration: 0,
  resetDependents: true,
  restoreVcs: true,
});

type TimeTravelOptions = {
  runId: string;
  nodeId: string;
  iteration?: number;
  attempt?: number;
  resetDependents?: boolean;
  restoreVcs?: boolean;
  force?: boolean;
  noRevert?: boolean;
  onProgress?: (event: SmithersEvent) => void;
};

type TimeTravelResult = {
  success: boolean;
  jjPointer?: string;
  vcsRestored: boolean;
  resetNodes: string[];
  error?: string;
  effectBoundary: EffectBoundaryReport;
};

function timeTravel(adapter: SmithersDb, opts: TimeTravelOptions): Promise<TimeTravelResult>;

Overview

Core API

Runtime

Types & errors

Gateway RPC

Revert to Attempt

Requirements

Programmatic

​Requirements

​Programmatic

Requirements

Programmatic