How moves work

Pack, workspace and agent

A pack is a saved tar snapshot of a workspace, supported native settings and project-scoped sessions. Its manifest records the source agent and selected conversation. Packs are immutable through Desk’s commands.

A working workspace is a separate directory restored from a pack. A move gives its target agent a new HOME and leaves the source files in place.

A managed-agent record tracks a packed source or a moved target. It records the pack, workspace, agent, lifecycle status, and process ID when a target has launched. desk ps retains these records after processes exit.

What packing captures

• The whole workspace, including hidden files, Git metadata and untracked files.
• Native settings supported by the source adapter.
• Project-scoped sessions, with one selected conversation for the handoff.

The default selection is the newest parent conversation. --session=ID pins a specific session. A source with no conversations can still be packed with its workspace and settings.

For Bob, Desk creates a project-only SQLite snapshot. It excludes unrelated tasks and global key/value state, and refuses active tasks or pending approvals.

What the target receives

For all harnesses, moving from the packed project directory (or selecting it with --project) keeps the existing working directory and its current files. The handoff still uses the saved pack, and the target session uses your normal HOME and existing login. An explicit pack moved from another directory uses an extracted workspace.

A move prepares the workspace, archives source settings and sessions in the Desk store, and resumes a native target session. A readable transcript contains selected user and assistant text when extraction succeeds.

Tool calls, reasoning, media and other native state remain archived rather than being replayed. The readable transcript follows log order; it does not reconstruct branch selection or compaction. report.json records extraction limitations.

All four targets receive extracted user and assistant text in native session storage when readable history is available. Vendor permissions, hooks, MCP, models and authentication are not translated or activated. The target can review source instruction files and archived settings as context.

For Bob 2.0.2, Desk prepares a new native task containing a handoff message and the extracted conversation text, then opens that task using bob chat --resume. It does not invent source tool history.

Lifecycle

Status	Meaning
packed	A source snapshot has been saved.
prepared	A target workspace and HOME exist; launch has not begun.
starting	Desk has reserved a launch attempt.
running	Desk started the target and recorded its PID.
exited	Desk observed a successful exit.
failed	Launch failed or the process returned an error.

A normal move proceeds through preparation and launch automatically. It does not stop at prepared. A retained prepared entry can occur if the move was interrupted before launch. See move recovery.

A launch is attempted once per target. To retry after an attempted launch, move the saved pack again. To carry forward new work, stop writers and run desk pack from the printed working workspace, then move its new pack. Prior handoff context is retained in chained moves.