Workspace Upgrades & Absorb

OpenAlice 0.81 adds two explicit maintenance workflows for durable Workspaces:

Template Upgrade brings newer launcher-managed assets into the same desk.
Workspace Absorb copies selected work from one desk into another, then archives the source.

Both are preview-first and preserve Workspace history. They solve different problems and never collapse two identities by accident.

Choose the right action

Goal	Action
Refresh managed instructions, skills, or template files	Template Upgrade
Combine useful files from two overlapping desks	Workspace Absorb
Stop a desk but keep it inspectable	Offboard
Remove an already departed checkout	Purge

Template Upgrade

A Workspace starts with a snapshot of its template. Over time, both sides may change: OpenAlice ships newer managed assets, while the Workspace edits its own instructions and skills. Upgrade performs a three-way comparison instead of overwriting the desk.

Base       files installed when the Workspace was created or last upgraded
Local      files in the Workspace now
Incoming   files from the current template

Each managed path is classified before anything changes:

Classification	Meaning	Default action
Ready	Incoming changed; Local still matches Base	Apply Incoming
Preserved	Local changed; Incoming still matches Base	Keep Local
Conflict	Local and Incoming both changed	Require an explicit choice
Unchanged	Local already equals Incoming	Do nothing

Conflicts are decided per file. You can keep the Workspace copy, use the new template copy, or leave the upgrade unapplied while you investigate.

Preview and apply

Open the Workspace settings and select Template upgrade, or ask the Workspace Manager to preview upgrades across the floor. The review shows:

current and incoming template versions;
every managed path and classification;
content diffs for conflicts;
blockers such as live Sessions or headless runs;
the exact reviewed plan digest.

Apply rechecks the plan so a stale preview cannot mutate newer files. It takes a backup, writes the reviewed results, updates the baseline, and creates an audit commit. A failed transaction restores the previous files; startup recovery handles an interrupted transaction before allowing another upgrade.

Template Upgrade only owns assets declared by the template. It does not absorb arbitrary research, copy credentials, rewrite Session identity, or move the Workspace.

CLI preview

Agents and the manager can inspect an upgrade through the Workspace CLI:

alice-workspace template upgrade --id <workspaceId>

Applying remains an explicit reviewed action. Old Workspaces continue to work with their existing guidance snapshot until you choose to upgrade.

Workspace Absorb

Absorb is directional. You choose one Workspace to keep and one to retire:

source Workspace ── selected files ──> target Workspace
       │                                  stays active
       └── complete checkout ─────────> departed-workspaces/

The target keeps its id, directory, template, git history, Sessions, Issues, and schedules. The source keeps its historical identity but leaves the active floor after the reviewed files are copied.

What moves

The plan reads tracked files plus untracked, non-ignored files from the source:

a path missing from the target can be copied directly;
identical files are recognized and skipped;
a different file at the same path requires Keep target, Use source, or Keep both;
Keep both stores the source version under an imports/ directory tied to the source Workspace.

What does not move

Absorb does not copy runtime or identity-bearing assets:

.git and .alice internals;
managed prompt and skill trees;
provider credentials and .env* files;
runtime homes, dependency caches, or build output;
the source's Issues, schedules, Sessions, or template identity.

Source Issues remain readable in the departed checkout but stop scheduling. Source resumeId records retire with the source. Existing Inbox, report, run, and trade provenance continues to name the original Workspace and Session.

Safe transaction

Both Workspaces must have no live interactive or headless work. The target must also have no staged git changes because Absorb creates one isolated audit commit.

Apply then:

recomputes and validates the reviewed plan;
snapshots target paths and writes a recovery journal;
offboards the source, closing its scheduling and runtime door;
copies the chosen files;
creates one target git commit with source and plan evidence;
records which active Workspace absorbed the departed source.

If the operation fails, target paths and the source location are restored. The complete departed source checkout is the lossless backstop; Absorb never deletes it.

Product flow

Start from the target Workspace settings:

Confirm Keep this Workspace.
Choose an active source under Absorb another Workspace.
Review copied files, duplicates, collisions, and stopped work.
Resolve every collision.
Confirm Absorb and archive source.
Inspect the audit commit and departed source record.

Do not use Absorb merely to share a file. A normal explicit copy or commit is simpler when both desks should remain active.

Next Steps

Workspace Manager — Audit the floor and preview maintenance.
Templates — Understand template-owned assets and guidance snapshots.
Lifecycle & Offboarding — See how the source becomes a departed desk.
Structure — Review the active/departed on-disk layout.

Search Documentation