Review and merge a worker's branch safely

Updated August 10, 2026

Goal: a worker says it’s done. Check the work, then get the branch into your main line without surprises.

What you need

  • An isolated shard (or a parked crystl/* branch) with commits.
  • Merging from the desktop is not gated. crystl merge from the CLI is a Guild control command.

Steps

  1. Confirm it’s actually finished. A quiet worker is not necessarily a done one: it may be parked on its agent’s own in-terminal approval prompt, which crystl shards and crystl status flag as ⏸ awaiting input.

  2. Read the work before you take it. Open the gem’s branches button in the shard bar for the worktrees panel. ACTIVE rows show what each shard was asked to do, its branch, agent and model, idle time, and commit count. Or read the session itself with history.

  3. Merge from the shard tab. An isolated shard with unmerged commits shows a ↑N badge below its tab. Click it and pick the merge action. Every action names what it will touch, like merge crystl/opal into main (3 commits), so there’s no guessing which branch moves where. crystl rebases onto the target, fast-forward merges, cleans up the worktree, and closes the shard.

  4. Or merge from the CLI, which is what an orchestrator uses:

    crystl merge --gem myapp --shard opal

    It returns a structured result: success, nothingToMerge, dirty, conflicts, failed, or notIsolated.

  5. Merge a parked branch from the PARKED section of the same panel. Each row shows commit count, whether the worktree is dirty, and last-commit age, with reattach, merge, and discard actions. Reattach reopens the worktree as a shell and does not auto-start an agent, so you land at a prompt on the branch.

What you’ll see when it works

The merge badge disappears and the shard closes, or the CLI returns success. Results from the panel arrive as a notification with a green check on the button, so nothing gets typed into an unrelated shard’s terminal.

Nothing here ever forces. The three refusals you’ll actually meet:

  • nothing to merge: the branch has no commits ahead of the target.
  • dirty: uncommitted changes in the worktree. Commit or stash them in the shard, then merge.
  • conflicts: the rebase hit conflicts and was aborted automatically. Resolve them in the shard with git rebase {target}, then merge from the badge. On a remote isolated shard, do it in the remote shard: you’re already SSH’d into the right directory.

If several shards touched database schema or migration files at the same time, crystl warns you before merging. Merge one, regenerate migrations, then merge the next.

Closing a shard instead of merging doesn’t lose anything. Keep Branch parks it in git as crystl/{name}, where the branches button can reattach, merge, or discard it later. The only path that deletes commits is choosing Discard on purpose.

Go deeper