Skip to content

Workspace upgrades

This page records the compatibility and migration guidance for workspace storage.

Adjacent Compatibility And Migration

The default workspace.root is xdg-state for unconfigured installations and projects. Existing adjacent <primary>_<num>/ directories are not moved during ordinary resolution; SASE only creates new managed checkouts under the configured root. To carry old adjacent checkouts into the managed root, run:

sase workspace migrate --to xdg-state [--symlink-transition] [--dry-run]
sase workspace migrate --finalize [--dry-run]

The first form moves every existing <primary>_<num> checkout under the managed root and records it in the registry. With --symlink-transition, the original <primary>_<num> path becomes a symlink to the canonical managed checkout so legacy tooling that walks .. for siblings keeps working. Migration refuses to overwrite a real directory at the managed destination; pre-existing managed content is reported and skipped. --dry-run reports the planned actions without touching the filesystem or registry.

Once workflows have adapted to the managed paths, sase workspace migrate --finalize removes the leftover transition symlinks without touching the canonical checkouts.

Post-Default Migration Guidance

Users and environments that still rely on sibling checkouts should set workspace.root: adjacent explicitly, either in the project-local sase/sase.yml or globally in ~/.config/sase/sase.yml. The managed-root default is intentionally non-migrating: it prevents silent moves, but a project with old adjacent clones and no explicit config will create new non-primary checkouts under the state root after the default change.

Before switching shared CI images, containers, or network-mounted homes to the default, confirm the state root is mounted, backed up, and on storage fast enough for agent work. Use an absolute workspace.root when the platform state directory is not the right operational location.

_[project]: A sase project is a named unit of work registered with SASE. _[workspace]: A sase workspace is a numbered clone of a project's primary repo, managed by the workspace store and tracked in that project's registry.json. _[agent]: A sase agent is an agent session or a single agent that does not belong to a session. _[prompt]: A prompt is the text SASE hands to a provider to start an agent turn. _[macro]: A macro is a reusable prompt triggered with #name in agent prompts. _[Patch]: A Patch is SASE's local unit of change. _[bead]: A bead is one tracked work item in SASE's git-native issue tracker. _[plan]: A plan is a persisted, approved artifact recording the intent behind agent work. _[TUI]: The TUI is SASE's terminal interface for running agents and reviewing results. _[epic]: An epic is an executable multi-phase plan run with sase bead work. _[gate]: A sase gate is a durable, command-backed request for one user decision, created when work must pause for the user. _[monitor]: A sase monitor is a monitor turn that runs one long command under a detached supervisor, so the command outlives the agent that started it. *[stitch]: A stitch is the lightweight ordered change record inside a Patch's STITCHES: section.