0.31.0 - Smithers

Smithers 0.31.0 makes time travel side-effect-safe. Rewind, fork, and replay have always restored run state and worktree files, but they knew nothing about what a run did to the outside world: rewinding past a task that posted a message left the message up, and replaying posted it again. Now you mark those actions, Smithers journals them durably, and every time-travel operation compensates for them, blocks, or reports exactly what it crossed. Claude Opus 5 also takes the default implementer, smart, and orchestrator seats in the model registry.

The Smithers Monitor following a live run from running to completed — A release-canary run streaming through the Monitor: the health banner, execution tree, and event feed update live until the run lands on Completed with 4/4 tasks done.

Upgrading

bunx smithers-orchestrator update        # upgrade the CLI
bunx smithers-orchestrator upgrade       # agent-assisted: reads the changelogs and applies what your project needs
bunx smithers-orchestrator packs update  # refresh installed workflow packs

Behavior changes are collected in the upgrade notes.

Time travel that respects side effects

The danger was never the state Smithers owns; it was the state you touched along the way: the Slack message, the deploy, the charge. Mark a task whose callback changes the outside world, and register compensation:

<Task
  id="announce"
  output={outputs.announcement}
  sideEffect={{
    idempotent: false,
    revert: async (ctx) => {
      const message = await findMessageByRun(ctx.runId);
      if (message) await slack.chat.delete(message);
    },
  }}
>
  {async () => {
    const message = await slack.chat.postMessage({ text: "Release complete" });
    return { messageId: message.ts };
  }}
</Task>

When an agent decides for itself when to act, mark the exact tool call instead:

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

const createTicket = defineTool({
  name: "create_ticket",
  schema: z.object({ title: z.string() }),
  sideEffect: true,
  execute: async ({ title }, ctx) => {
    const ticket = await tracker.createIssue({ title }, { idempotencyKey: ctx.idempotencyKey });
    return { id: ticket.id };
  },
  revert: async (_args, ctx) => {
    if (ctx.output) await tracker.archiveIssue(ctx.output.id);
  },
});

Every marked call is journaled durably before it runs, with an effect status of intended, then succeeded or unknown. Time travel consults that journal:

bunx smithers-orchestrator rewind RUN_ID <frame>              # prints an effect-boundary report
bunx smithers-orchestrator rewind RUN_ID <frame> --force      # cross anyway; the run is marked needs-attention
bunx smithers-orchestrator rewind RUN_ID <frame> --no-revert  # keep the effects; skip compensation

Rewind, fork, replay, and jumpToFrame run an effect-boundary guard. Crossing a marked effect triggers its revert handler; an effect with no way to compensate blocks the operation with a new error code, TIME_TRAVEL_SIDE_EFFECT_BLOCKED, instead of quietly re-firing it.
The diagnosis follows you everywhere. rewind and timetravel print the effect-boundary report; why, status, and the MCP tools expose the same diagnosis; and the Gateway RPC surface accepts force and noRevert and returns an effectBoundary report so custom run UIs can render the guard.
The journal is observable. The SmithersEvent union gains side-effect journal event types, so dashboards and OTLP exporters see effect transitions as they happen.

Touring a finished run in the Monitor, opening the node inspector, the XML debug view, and the frame scrubber — Inspecting a finished run in the Monitor: the execution tree, the node inspector with transcript and output, Debug power tools with the engine XML view, and frame-by-frame scrubbing with the Frames control.

Marking is checkable: a new authoring-side-effects eval suite (70 fixture workflows plus handwritten cases and a harness) and a gradeSideEffectCompliance scorer statically grade whether a workflow marks and reverts its side effects. See the external side effects section of the Task docs and the time-travel quickstart.

Claude Opus 5 becomes the default implementer

If you use the shipped registry defaults rather than a custom agents.ts, the model doing most of your work changed. SOTA registry v7 routes the implement and smart seats in CLI-generated agent pools to Claude Opus 5; registry v6, also in this release, had already handed it the orchestrator seat that Claude Opus 4.8 held. GPT-5.6 Sol and Terra move to the review, validation, and checking seats.

bunx smithers-orchestrator oneshot "make the flaky auth test deterministic"

Cost scoring prices claude-opus-5 at $5 per million input tokens and$ 25 per million output tokens, the same as Opus 4.8.
smithers oneshot falls back in a new order: Claude Opus 5, then Codex Sol, then Kimi K3, then Claude Fable 5.

See the model selection guide for overriding any seat.

Point Opus 5 at your open issues

The new opus5-bug-sweep pack workflow applies the routing change: Claude Opus 5 triages your open GitHub issues, fixes the straightforward bugs in parallel jj worktrees, lands each fix through a serialized compare-and-swap merge queue, gates the result with install, typecheck, and lint in a scratch worktree, then pushes main and closes the issues. It ships with a live UI.

bunx smithers-orchestrator packs update
bunx smithers-orchestrator up opus5-bug-sweep

Docs for humans, docs for agents

The docs site now separates its two audiences. The Product API tab is for you: a Platform Capabilities catalog of what you can ask for in plain English, setup pages for each harness (Claude Code, Codex, Cursor, Copilot, Pi, Hermes, OpenClaw), and a Set Up Semantic Memory page covering Hindsight and HINDSIGHT_URL. The Technical API tab is the agent-facing reference, and its entry pages now say so.

Other improvements

Every @smithers-orchestrator/ui component has a browsable catalog: 47 stories at storybook.smithers.sh.
Launching Smithers from the Claude Code native Workflow tool no longer crashes. That tool’s script sandbox defines no Node globals, so the mirror script stopped referencing the bare process global.

Upgrade notes

DB migrations 0031 (the side-effect journal) and 0032 (tool-call tokens) run automatically through the existing schema-migrations runner the first time an upgraded CLI touches a workspace. No manual steps.
sideEffect is opt-in. A workflow that never sets it has no effect boundaries, so rewind, fork, and replay behave exactly as before.
Shipped registry defaults now route the implement, smart, and orchestrator seats to Claude Opus 5, and oneshot prefers Opus 5 before Codex Sol, Kimi K3, and Claude Fable 5. A custom agents.ts is unaffected.

The full changelog

The complete commit-level history for this release is in CHANGELOG.md. Found a bug? Run bunx smithers-orchestrator bug to file it.

​Upgrading

​Time travel that respects side effects

​Claude Opus 5 becomes the default implementer

​Point Opus 5 at your open issues

​Docs for humans, docs for agents

​Other improvements

​Upgrade notes

​The full changelog