Stateful Workflows: Sessions, Undo, Saving, and Reusable Context

CLI-Anything's state model answers a practical problem: an agent rarely completes meaningful work in one command. This chapter focuses on what must survive between operations, how a REPL and a one-shot process use the same underlying session differently, and why saving, undo/redo, status, and file locking are part of the agent contract. The goal is to distinguish a CLI that merely accepts repeated commands from a harness that lets an agent maintain and correct a real project.

A project is more than the current command

A multi-step workflow has at least two kinds of state. Project state is the thing the target software will eventually open, render, or process: a timeline, scene, document, or other structured artifact. Session state is the working context around it: which project is open, what has changed since the last save, what history is available for undo and redo, and what the CLI should do when the next command arrives. The two may be stored together in a simple harness, but they are not conceptually identical.

The distinction matters because an agent's next decision depends on both. If an agent asks for a project status, it may need to know not only what objects or tracks exist but whether there are unsaved changes. If a mutation fails, the agent needs to know whether the project remained unchanged, became partially modified, or can be reopened from the last saved version. If the process exits, the project may still exist on disk while session context disappears. A harness that does not make these transitions visible forces the agent to guess.

CLI-Anything's stateful pattern begins with a project that can be created or opened. Commands then read or mutate the current session, and status commands expose enough context for the next operation. A REPL can retain the open project in memory and show a modified marker in its prompt. A one-shot command must identify the project, load the relevant state, perform the operation, and decide what to save before it ends. Both modes can share the same core operations, but the lifetime of their in-memory context is different.

stateDiagram-v2 [*] --> NoProject state "No project" as NoProject state "Open and saved" as OpenSaved state "Modified in session" as Modified state "Undo/redo branch" as HistoryBranch state "Dry-run change" as DryRun state "Error requiring recovery" as Error NoProject --> OpenSaved: create or open OpenSaved --> Modified: mutation Modified --> OpenSaved: save or auto-save Modified --> HistoryBranch: undo HistoryBranch --> Modified: redo or new mutation OpenSaved --> DryRun: one-shot --dry-run DryRun --> OpenSaved: discard non-persisted change Modified --> Error: command failure Error --> Modified: inspect and recover Error --> OpenSaved: reopen saved state OpenSaved --> NoProject: close or process ends

The diagram is not a claim that every harness exposes exactly these named states. It is a way to see the transitions the methodology requires a session-based design to handle. A command can move a project from saved to modified, a save can make the change durable, an undo can create a branch in the agent's reasoning, and a failure can require inspection before work continues.