Reference · Interactive

See the handoff protocol

Step through a single git_handoff from coder → cleaner. Watch directories, headers, and the agent loop light up together.

Lesson 2 Lifecycle cheat sheet Glossary System map Mission
How to use this page

Use Next / Prev (or ← → keys) on the stepper below. Then scroll for the static maps (topology, lossy vs durable). Everything here matches handoff-protocol.md and the helper scripts.

1. Topology at a glance

Two roles, two worktrees, one daemon that owns delivery and wake-ups. Agents never send work over tmux themselves.

Role A · sender

Coder worktree

Own git branch under .worktrees/… (or master). Writes draft → outbox/. Later sees file in sent/.

Protocol · middle

handoffd

Polls every outbox. Copies into recipient inbox/new/. Lossy tmux wake-up. Archives to sent/ or failed/.

Role B · receiver

Cleaner worktree

Claims with ready_for_next (new → in_process. Finishes with done_with_current → completed.

2. Step-through: one handoff

Scenario: coder finished a slice, committed, hands off to cleaner (two-pack style). Black chip = the .handoff file.

Coder worktree

.swarmforge/handoffs/ · SWARMFORGE_ROLE=coder

./tmp/ draft (agent writes)
outbox/
sent/
failed/
handoffd
poll ~1s
tmux wake-up
(lossy)

Cleaner worktree

.swarmforge/handoffs/ · SWARMFORGE_ROLE=cleaner

inbox/new/
inbox/in_process/
inbox/completed/

Highlighted = this step’s action Green border = file present Token = .handoff

Headers that exist so far

Chips light up as writers add them. Agents only draft the first row’s fields for a git_handoff.

Agent draft
type to priority task commit
swarm_handoff
id from role created_at
handoffd
recipient enqueued_at
ready_for_next
dequeued_at
done_with_current
completed_at

Recipient agent loop (highlight)

A · Ready

ready_for_next → TASK or NO_TASK

B · Work

Use PAYLOAD only; ignore extra wake-ups

C · Send

Commit + swarm_handoff (sender side)

D · Done

done_with_current then ready again

Sequence (cumulative)

Coder
1

Write draft headers; run swarm_handoff.sh

2

File appears in outbox/ (body generated)

handoffd
3

Copy → cleaner inbox/new/ + headers

4

Wake-up text via tmux; move original → sent/

Cleaner
5

ready_for_next → in_process

6

Do owned work (merge / clean / tests…)

7

done_with_current → completed + ready

3. Lossy notify vs durable queue

This is the design trick that makes a TUI rewrite easy: swap the left column; keep the right column’s semantics.

Lossy · wake-up only

  • tmux send-keys (today)
  • Does not name a file
  • Busy agent may ignore
  • Can be dropped — system still correct
  • Rewrite: TUI flash, bell, status line…

Durable · source of truth

  • Files under .swarmforge/handoffs/
  • Directory = queue state
  • Headers = audit timestamps
  • Restart → ready_for_next
  • Rewrite: same state machine in Rust/TS

4. State machine (inbox side)

For task mode, each handoff is one token moving through three inbox folders. Ambiguous shapes (two in_process files) are errors — helpers refuse to “fix” them. 

                    ready_for_next
   inbox/new  ──────────────────────►  inbox/in_process
       │                                     │
       │  (sorted by filename)               │  done_with_current
       │                                     ▼
       │                              inbox/completed
       │
       └── if empty after ready → print NO_TASK

   restart rule: always ready_for_next
   · one file already in in_process → re-print it (resume)
   · else take first from new/

Batch mode (later lesson): equal-priority files move together into a batch_* directory under in_process/.

Ask the teacher If a step still feels fuzzy, describe what you expected the file to do vs what the viz shows. Next content can be batch mode, pack pipelines, or the launcher — your call.