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 the directory where the target agent works. A local move from the packed project keeps that directory and its current files; moving an explicit pack from another directory restores a separate workspace. Native launches use your normal HOME and existing login.

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 retains these records after processes exit. Use desk ps for verified running managed agents, or desk ps -A for saved history and discovered unmanaged processes. Add --no-trunc to show full IDs and directory paths.

What packing captures

• The workspace. Desk 0.2.6 and later use a Git URL, exact commit and local changes by default. Explicit full snapshots include the entire project tree. See workspace formats.
• 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	Target workspace and session preparation completed; 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.