Reference

Handoff lifecycle

File locations and helpers that own each step. Normative source: handoff-protocol.md + the *.bb helpers.

Lesson 2 Interactive viz Glossary System map Mission

Pictures

Prefer a step-through of the same facts? Open the handoff visualization.

Agent-facing commands

Command	Job
`swarm_handoff.sh <draft>`	Validate draft → write outbox → delete draft
`ready_for_next.sh`	Dispatch task or batch receive mode; claim or resume work
`done_with_current.sh`	Complete current task/batch; then auto-ready for next

Agents do not send tmux messages for work transfer. Only handoffd uses the tmux socket for generic wake-ups.

Per-worktree layout

.swarmforge/handoffs/
  outbox/tmp/     # incomplete writes (daemon ignores)
  outbox/         # ready .handoff files
  sent/           # after successful delivery
  failed/         # undeliverable (+ .error sidecar)
  inbox/new/      # delivered, not yet claimed
  inbox/in_process/
  inbox/completed/

Happy path (task mode)

Agent writes draft headers only → swarm_handoff.sh.
Helper writes outbox/tmp/…tmp then renames into outbox/*.handoff.
handoffd (poll ~1s) copies to each recipient inbox/new/, adds recipient + enqueued_at, wake-up via tmux, moves original to sent/.
Recipient runs ready_for_next.sh → moves first sorted file to in_process/, sets dequeued_at, prints TASK: / PAYLOAD:.
On finish: done_with_current.sh → completed_at, move to completed/, then runs ready again (TASK: or NO_TASK).

Draft formats (agent-written only)

type: git_handoff
to: cleaner
priority: 50
task: task-1-cave-setup
commit: a1b2c3d9e8

type: note
to: architect
priority: 70
message: Waiting on QA result before merging.

Reserved headers agents must not set: id, from, role, recipient, created_at, enqueued_at, dequeued_at, completed_at.

Generated git_handoff body

Re-read your role and constitution.

merge_and_process coder a1b2c3d9e8

Commit must be exactly 10 hex chars, resolve to one commit object; helper canonicalizes before queueing.

Header ownership

Writer	Headers
`swarm_handoff`	`id` `from` `to` `priority` `type` `role`/`task`/`commit` or `message` `created_at`
`handoffd`	`recipient` `enqueued_at` (on each inbox copy)
`ready_for_next_*`	`dequeued_at`
`done_with_current_*`	`completed_at`

Wake-up text (lossy)

You have new handoff mail. If idle, run ready_for_next.sh.

Does not name a file. Busy agents ignore. Queue is durable; completion always re-checks.

Filename sort key

<priority>_<timestamp>_<sequence>_from_<sender>_to_<recipients>.handoff

Lower priority number first. Scripts parse metadata from headers, not the filename.

Ambiguous states

Helpers refuse recovery for multiple in-process files, mixed task/batch shapes, etc. Fix outside the helper — by design for a rewrite core.