Skip to main content

Session patterns

This page is about design, not just routes.

The public session API is flexible enough to support several product models, but a small number of patterns work much better than the rest.

Pattern: one session per task​

Use one session for one clearly bounded unit of work.

Best for:

  • A single issue or change request.
  • One analysis job.
  • One reviewable proposal.
  • One exportable result.

Why it works:

  • Ownership is clear.
  • Review state is easy to explain.
  • Cleanup is straightforward.
  • Persistence decisions stay local to one workspace.

Pattern: baseline plus forked proposals​

Start from a stable session, then fork once per proposal.

Best for:

  • Human review.
  • Agent competitions.
  • A/B approaches.
  • Approval-heavy workflows.

Why it works:

  • The baseline remains stable.
  • Reviewers can inspect each proposal independently.
  • Losing proposals can be deleted without disturbing the winner.

Pattern: checkpoint before risk​

Create checkpoints before:

  • Large automated mutations.
  • Imports or mass renames.
  • Content transformations that are hard to reverse manually.
  • Handoffs between tools or teams.

Why it works:

  • Recovery becomes cheap.
  • The workflow is easier to support.
  • Users gain confidence to try aggressive actions.

Pattern: explicit review gate​

Use annotations, approval requests, and commit summaries before persistence.

Best for:

  • Agent-assisted changes.
  • High-impact edits.
  • Compliance-sensitive workflows.
  • Multi-actor review.

Recommended flow:

  1. Work happens in a session or fork.
  2. Context is attached through annotations or cache entries.
  3. Approval is requested.
  4. A reviewer grants or denies.
  5. Only then does the system commit, merge, or promote.

Pattern: short-lived working sessions, durable sources​

Let sessions be temporary and let sources or commits carry the durable meaning.

Best for:

  • SaaS products.
  • Repeatable templates.
  • Clean lifecycle management.
  • Systems that create many task workspaces.

This separation keeps users from treating every live workspace as something that must be kept forever.

Pattern: long-running session with operational checkpoints​

Use a long-lived session only when:

  • The user expects continuity across many work periods.
  • The workspace behaves like an ongoing project rather than a single request.
  • The cost of repeated setup is high.

If you choose this pattern:

  • checkpoint aggressively
  • tag lifecycle state clearly
  • keep retention rules explicit
  • avoid letting unrelated work accumulate in the same session

Anti-pattern: shared mutable session for many independent actors​

Avoid putting several unrelated actors into one mutable session unless you also have a strong locking and review story.

Why it breaks down:

  • stale assumptions become common
  • review state gets muddy
  • rollback becomes expensive
  • persistence decisions become ambiguous

Use forks, locks, or separate sessions instead.

Anti-pattern: commit as a save button​

Do not use commit for every minor progress update.

Use:

  • checkpoints for recoverability
  • annotations for workflow notes
  • cache entries for derived state
  • commits for meaningful durable outcomes

Pattern selection guide​

If you need:

  • isolation: use one session per task
  • alternatives: use forks
  • rollback: use checkpoints
  • formal review: use approvals plus annotations
  • reusable baselines: use source promotion

See also: