Offers, catches and drops

To pass work on, the carrier offers it. The next carrier catches the offer with handsoff continue. Work that nobody passes on drops, and any handle in the workspace can catch it.

Before you start

The examples use the workspace billing, the handles build-agent and review-agent, and the file baton.md from your first relay. Any baton file will do. Each section opens its own piece of work.

Offer to a handle

A handle is a name that carries work, for a person or an agent. The carrier is the handle that holds the work now. Here build-agent opens BILL-46, so it is the carrier:

$ handsoff open BILL-46 --title "Refund the double charges" --as build-agent --baton baton.md
Opened BILL-46 at r1 (work 114)
Leg 203; lease expires 2026-10-05T05:19:17.184339+00:00

You cannot offer work to your own handle:

$ handsoff offer BILL-46 --as build-agent --to build-agent
This offer is addressed to your own handle build-agent, which cannot catch it. Offer it to another handle or to any, or end your leg clean and catch the drop.
invalid: to: own handle cannot catch its offer; fix: offer to another handle or to any, or end your leg clean and catch the drop

The first line is for you. The second line is for the agent that ran the command.

To pass the work to one handle, offer it with --to:

$ handsoff offer BILL-46 --as build-agent --to review-agent
Offered BILL-46 at r1 to review-agent until 2026-10-06T04:49:17.999358+00:00

The offer carries the current baton, here r1. To save a new baton and offer it in one step, add --baton and a file. The example under "End your leg" does this.

An offer refuses a baton whose True now or Next action is empty or still holds a <placeholder>. The baton shows that refusal.

Offer to anyone

To let any handle in the workspace catch the work, write --any in place of --to <handle>. Here build-agent opens BILL-47 and offers it to anyone:

$ handsoff open BILL-47 --title "Archive the February invoices" --as build-agent --baton baton.md
Opened BILL-47 at r1 (work 115)
Leg 204; lease expires 2026-10-05T05:19:18.372886+00:00
$ handsoff offer BILL-47 --as build-agent --any
Offered BILL-47 at r1 to any until 2026-10-06T04:49:18.675694+00:00

Every handle in the workspace can catch it, except the handle that offered it. Handsoff does not choose who should carry the work. You choose, by naming a handle or by offering to any.

The offer deadline

An offer waits until its deadline. The workspace sets the default, which starts at one day. To set another deadline, add --deadline and a duration from 1 minute to 7 days. Here build-agent opens BILL-49 and offers it for two hours:

$ handsoff open BILL-49 --title "Send the refund emails" --as build-agent --baton baton.md
Opened BILL-49 at r1 (work 116)
Leg 205; lease expires 2026-10-05T05:19:18.936578+00:00
$ handsoff offer BILL-49 --as build-agent --to review-agent --deadline 2h
Offered BILL-49 at r1 to review-agent until 2026-10-05T06:49:19.699728+00:00

A piece of work has at most one offer waiting. While the offer on BILL-49 waits, its carrier cannot save:

$ handsoff save BILL-49 --as build-agent --baton baton.md
An offer is waiting; retract it or let it be caught before saving.
offer_waiting: waiting offer; fix: retract the offer or let it be caught

To change the baton, take the offer back first, as shown below. When the deadline passes and nobody caught the offer, the work drops. Workspaces shows how the owner changes the default deadline.

End your leg

After you offer, end your leg with a reason. A leg is one carrier's stretch on the work. The reason says how you stopped. BILL-46 still has its offer to review-agent waiting, so build-agent ends its leg there:

$ handsoff end BILL-46 --as build-agent --reason clean
Ended BILL-46: clean

The reasons are clean, limit, crash, killed and other. Use clean when you stopped on purpose with nothing half done. The offer keeps waiting after you end, until it is caught or its deadline passes.

Any reason other than clean marks the offer. Listings show it, and the next carrier gets a warning when it catches the work. Here build-agent opens BILL-51, saves a new baton and offers it in one step with --baton, and then stops on a usage limit:

$ handsoff open BILL-51 --title "Refund the April double charges" --as build-agent --baton baton.md
Opened BILL-51 at r1 (work 117)
Leg 206; lease expires 2026-10-05T05:19:28.935707+00:00
$ handsoff offer BILL-51 --as build-agent --to review-agent --baton baton.md
accepted as r2
Offered BILL-51 to review-agent until 2026-10-06T04:49:29.440818+00:00
$ handsoff end BILL-51 --as build-agent --reason limit
Ended BILL-51: limit
$ handsoff list
…
   WAITING  BILL-51: Refund the April double charges — waiting
            Last carrier build-agent; ended with reason limit
            Last accepted r2 at 2026-10-05T04:49:29.437767+00:00
            waiting for review-agent until 2026-10-06T04:49:29.440818+00:00
            waiting; passer ended: limit
            Next: wait for the deadline
…

Leave BILL-51 waiting. After an interruption catches it.

If you end your leg with no offer waiting, the work drops at once.

Catch it

The next carrier catches an offer with handsoff continue. The offer on BILL-46 waits for review-agent, so it catches it:

$ handsoff continue BILL-46 --as review-agent
Caught BILL-46 at r1 from build-agent via offer

Attention
2026-10-05T04:49:17.801211+00:00 refusal: {"act":"offer","detail":"to: own handle cannot catch its offer","rule":null}
Warning: References: no work reference
This machine has no pending writes.

## True now
Invoices 1 to 4800 are copied. The v2 table holds 4,800 rows and so does the old table.
…

The first line says what you caught, from whom, and whether it came from an offer or a drop. Then come the points that need your attention, here the refused offer to its own handle. Then comes the baton. After the baton, the tool prints what to do now and your new lease. The new carrier holds the work from here.

Only the handle the offer names can catch it. The offer on BILL-49 still waits for review-agent. Any other handle is refused, such as your own handle, dana:

$ handsoff continue BILL-49
This offer waits for review-agent; ask that handle to catch it, or wait for its deadline.
offered_to_other: receiver review-agent; fix: ask the named receiver to catch it or wait for the offer deadline

If two handles catch at the same moment, one wins. The other is refused, and the history records the refusal.

Take an offer back

The carrier can take its offer back with handsoff retract. The leg of build-agent on BILL-49 is still live, so it holds the work again:

$ handsoff retract BILL-49 --as build-agent
Retracted offer for BILL-49; now held

The handle that offered can also retract after it has ended its leg. The work then drops, and any handle can catch it, that handle too. Here build-agent offers BILL-49 to anyone, ends its leg, and then takes the offer back:

$ handsoff offer BILL-49 --as build-agent --any
Offered BILL-49 at r1 to any until 2026-10-06T04:49:36.953509+00:00
$ handsoff end BILL-49 --as build-agent --reason clean
Ended BILL-49: clean
$ handsoff retract BILL-49 --as build-agent
Retracted offer for BILL-49; now dropped; catchable: run handsoff continue

The workspace's owner can retract any offer.

Drops

Work drops when nobody passes it on. That happens when one of these is true:

The carrier's lease ran out, and no offer was waiting.
An offer's deadline passed, and nobody caught it.
The carrier offered the work but let its lease run out without ending its leg.
The carrier ended its leg with no offer waiting.

handsoff list and handsoff status show who held dropped work, why it dropped, and the last revision the service accepted. BILL-49 dropped when build-agent took back its offer:

$ handsoff list
…
   DROPPED  BILL-49: Send the refund emails — dropped
            Last carrier build-agent; ended: ended without a hand-over at 2026-10-05T04:49:37.296732+00:00
            Last accepted r1 at 2026-10-05T04:49:18.937354+00:00
            dropped: ended without a hand-over at 2026-10-05T04:49:37.296732+00:00; held by build-agent; last accepted r1 at 2026-10-05T04:49:18.937354+00:00
            Next: catch it
…

Any handle in the workspace can catch dropped work with handsoff continue, the last carrier too. The tool says via drop.

What the next carrier sees depends on how the last leg ended:

If it ended clean, there is no warning. If its offer ran out first, the tool says so, for example: the offer from build-agent expired at 2026-10-05T04:13:30.5048+00:00; the passer had ended its leg clean.
If its lease ran out, it ended with any other reason, or it was taken over, the tool warns that contact was lost. After an interruption shows that warning and what to do.

Next, read after an interruption to catch dropped work safely.