Reading work

See where work stands: one piece, a whole workspace, everything that waits for you, the full history, or a baton.

These commands only read. Every line comes from what the service holds now. The tool never guesses a state from what this machine remembers. If this machine holds writes that it could not send earlier, a command first tries to send them. Read Offline commands to see how.

Each command also takes the global options, such as --workspace, --as and --json. The CLI reference explains them. In each command, <WORK> is the work's reference, such as BILL-42, or its id.

Work is in one of five states:

held: a carrier holds it.
stalled: a carrier holds it, but has saved nothing for longer than the workspace's stall threshold.
waiting: an offer waits for a catch.
dropped: its carrier stopped without passing it on. Any handle can catch it.
closed: the carrier or the owner closed it, and nobody can change it now.

Blocked work also carries a BLOCKED mark, whatever its state.

Before the examples

The examples show the billing workspace at one moment. It is after the Carrying work examples unblocked BILL-42, and before they closed it. Just before the examples, build-agent opened two more pieces of work:

$ handsoff open BILL-43 --title "Invoice totals report" --as build-agent --baton baton.md
Opened BILL-43 at r1 (work 57)
Leg 111; lease expires 2026-10-05T04:58:33.309233+00:00
$ handsoff end BILL-43 --as build-agent --reason crash
Ended BILL-43: crash
$ handsoff open BILL-44 --title "Export the 2025 invoices" --as build-agent --baton baton.md
Opened BILL-44 at r1 (work 58)
Leg 112; lease expires 2026-10-05T04:58:34.124519+00:00
$ handsoff offer BILL-44 --as build-agent --any
Offered BILL-44 at r1 to any until 2026-10-06T04:13:34.534437+00:00

BILL-43 dropped, because its carrier ended without passing it on. BILL-44 waits for any handle to catch it.

handsoff show

Shows one piece of work. Its state comes first, then the notes and late writes, then the current baton.

Usage: handsoff show [OPTIONS] <WORK>

Arguments:
  <WORK>  

Options:
      --server <SERVER>        
      --workspace <WORKSPACE>  
      --as <HANDLE>            
      --session <SESSION>      
      --runtime <RUNTIME>      
      --model <MODEL>          
      --leg <LEG>              
      --account <ACCOUNT>      
      --json                   
  -h, --help                   Print help

Option	What it does
`<WORK>`	The work to show.

$ handsoff show BILL-42
   HELD     BILL-42: Billing v2 migration — held
            Workspace billing (22)
            Carrier review-agent; held since 2026-10-05T04:13:16.696389+00:00; lease expires 2026-10-05T04:58:25.905568+00:00
            Last accepted r2 at 2026-10-05T04:13:03.349233+00:00
            Next: ask the carrier

2026-10-05T04:13:24.454892+00:00 note: {"kind":"question","note":"Should credit notes move with the invoices?"}

## True now
The v2 invoice tables exist in staging. Invoices 1 to 1200 of 4800 are copied.

## Next action
Copy invoices 1201 to 4800, then compare the row counts.

Done when: The row counts match between the old and new tables.
## Traps
The old table stores amounts in cents. The new one stores whole currency units. Divide by 100 when you copy.

## Evidence
The copy script ran for invoices 1 to 1200. It reported 1,200 rows written.

## References
- [required] source: migrations/0042_invoices_v2.sql -- creates the v2 tables (check: bun test billing)
- work: BILL-41 -- the schema change this copy follows

A save from a former carrier shows as late, not accepted. It never becomes the baton.

handsoff list

Lists every piece of work in the selected workspace, one block for each. Blocked work comes first, then dropped, waiting, stalled, held and closed work.

Usage: handsoff list [OPTIONS]

Options:
      --server <SERVER>        
      --workspace <WORKSPACE>  
      --as <HANDLE>            
      --session <SESSION>      
      --runtime <RUNTIME>      
      --model <MODEL>          
      --leg <LEG>              
      --account <ACCOUNT>      
      --json                   
  -h, --help                   Print help

This command has no options of its own.

$ handsoff list
   DROPPED  BILL-43: Invoice totals report — dropped
            Last carrier build-agent; ended: ended without a hand-over at 2026-10-05T04:13:33.821924+00:00
            Last accepted r1 at 2026-10-05T04:13:33.310555+00:00
            dropped: ended without a hand-over at 2026-10-05T04:13:33.821924+00:00; held by build-agent; last accepted r1 at 2026-10-05T04:13:33.310555+00:00
            Next: catch it

   WAITING  BILL-44: Export the 2025 invoices — waiting
            Carrier build-agent; held since 2026-10-05T04:13:34.124519+00:00; lease expires 2026-10-05T04:58:34.535351+00:00
            Last accepted r1 at 2026-10-05T04:13:34.125646+00:00
            waiting for any until 2026-10-06T04:13:34.534437+00:00
            Next: catch it

   HELD     BILL-42: Billing v2 migration — held
            Carrier review-agent; held since 2026-10-05T04:13:16.696389+00:00; lease expires 2026-10-05T04:58:25.905568+00:00
            Last accepted r2 at 2026-10-05T04:13:03.349233+00:00
            Next: ask the carrier

Each block names the work, its state, its carrier, its last accepted revision and what to do next. Times are the service's times, in UTC.

handsoff status

Shows what waits for you, across every workspace and all your handles. It lists the batons you hold, the offers that wait for you, and dropped work you may catch. Last, it says whether this machine has writes that the service has not accepted yet.

Usage: handsoff status [OPTIONS]

Options:
      --server <SERVER>        
      --workspace <WORKSPACE>  
      --as <HANDLE>            
      --session <SESSION>      
      --runtime <RUNTIME>      
      --model <MODEL>          
      --leg <LEG>              
      --account <ACCOUNT>      
      --json                   
  -h, --help                   Print help

This command has no options of its own.

$ handsoff status
Batons held
   WAITING  BILL-44: Export the 2025 invoices — waiting
            Workspace billing (22)
            Carrier build-agent; held since 2026-10-05T04:13:34.124519+00:00; lease expires 2026-10-05T04:58:34.535351+00:00
            Last accepted r1 at 2026-10-05T04:13:34.125646+00:00
            waiting for any until 2026-10-06T04:13:34.534437+00:00
            Next: wait for the deadline

   HELD     BILL-42: Billing v2 migration — held
            Workspace billing (22)
            Carrier review-agent; held since 2026-10-05T04:13:16.696389+00:00; lease expires 2026-10-05T04:58:25.905568+00:00
            Last accepted r2 at 2026-10-05T04:13:03.349233+00:00
            Next: ask the carrier

Offers waiting
…
   WAITING  BILL-44: Export the 2025 invoices — waiting
            Workspace billing (22)
            Carrier build-agent; held since 2026-10-05T04:13:34.124519+00:00; lease expires 2026-10-05T04:58:34.535351+00:00
            Last accepted r1 at 2026-10-05T04:13:34.125646+00:00
            waiting for any until 2026-10-06T04:13:34.534437+00:00
            Next: catch it
            for handles: dana, review-agent

Dropped work you may catch
…
   DROPPED  BILL-43: Invoice totals report — dropped
            Workspace billing (22)
            Last carrier build-agent; ended: ended without a hand-over at 2026-10-05T04:13:33.821924+00:00
            Last accepted r1 at 2026-10-05T04:13:33.310555+00:00
            dropped: ended without a hand-over at 2026-10-05T04:13:33.821924+00:00; held by build-agent; last accepted r1 at 2026-10-05T04:13:33.310555+00:00
            Next: catch it
            for handles: build-agent, dana, review-agent

This machine has no pending writes.

The … lines stand for work in another workspace this test person belongs to. When several of your handles could act on one piece of work, a for handles: line names them. Read Offline commands for the last line.

handsoff history

Shows every leg of one piece of work, in order, with what happened in each. That covers opens, saves, offers, catches, drops, blocks, notes, refusals and ends, each with its time.

Usage: handsoff history [OPTIONS] <WORK>

Arguments:
  <WORK>  

Options:
      --server <SERVER>        
      --workspace <WORKSPACE>  
      --as <HANDLE>            
      --session <SESSION>      
      --runtime <RUNTIME>      
      --model <MODEL>          
      --leg <LEG>              
      --account <ACCOUNT>      
      --json                   
  -h, --help                   Print help

Option	What it does
`<WORK>`	The work whose history to show.

$ handsoff history BILL-42
   HELD     BILL-42: Billing v2 migration — held
            Carrier review-agent; held since 2026-10-05T04:13:16.696389+00:00; lease expires 2026-10-05T04:58:25.905568+00:00
            Last accepted r2 at 2026-10-05T04:13:03.349233+00:00
            Next: ask the carrier

History of 56; state held
Leg 1: build-agent (agent, unknown)
  opened at r1; saved r1 to r2
  runtime unknown and model unknown (as reported); session unknown
  ended with reason clean at 2026-10-05T04:13:12.793043+00:00; handed over to review-agent
  2026-10-05T04:12:58.063645+00:00 opened: {"reference":"BILL-42"}
  2026-10-05T04:13:03.351846+00:00 saved: {"revision":2}
  2026-10-05T04:13:10.30047+00:00 offered: {"offer":"41","revision":2,"to":"review-agent"}
  2026-10-05T04:13:11.36141+00:00 retracted: {"offer":"41"}
  2026-10-05T04:13:12.08891+00:00 offered: {"offer":"42","revision":2,"to":"review-agent"}
  2026-10-05T04:13:12.794803+00:00 ended: {"note":null,"reason":"clean"}

Leg 2: review-agent (agent, unknown)
  caught the offer at r2; saved none
  runtime unknown and model unknown (as reported); session unknown
  live; lease expires 2026-10-05T04:58:25.905568+00:00
  2026-10-05T04:13:16.698728+00:00 caught: {"drop":null,"from":"build-agent","handle":"51","offer":"42","principal":"1","revision":2,"session":null}
  2026-10-05T04:13:23.757424+00:00 renewed: {}
  2026-10-05T04:13:24.454892+00:00 note: {"kind":"question","note":"Should credit notes move with the invoices?"}
  2026-10-05T04:13:25.226447+00:00 blocked: {"evidence":null,"reason":"Waiting for read access to the old invoice table"}
  2026-10-05T04:13:25.90619+00:00 unblocked: {"evidence":null,"reason":"Waiting for read access to the old invoice table"}

The brackets after a handle hold its kind and the name of the person it belongs to. The name reads unknown when that person's sign-in page sends none. The runtime, model and session are what the carrier reported. A person handle also sees where each leg's transcript lives, when the carrier gave it. An agent handle never sees that. For more, read History.

handsoff baton

Prints a baton as Markdown, in the form you can edit and save back. Without --rev, it prints the current baton.

Usage: handsoff baton [OPTIONS] <WORK>

Arguments:
  <WORK>  

Options:
      --rev <REV>              
      --server <SERVER>        
      --workspace <WORKSPACE>  
      --as <HANDLE>            
      --session <SESSION>      
      --runtime <RUNTIME>      
      --model <MODEL>          
      --leg <LEG>              
      --account <ACCOUNT>      
      --json                   
  -h, --help                   Print help

Option	What it does
`<WORK>`	The work whose baton to print.
`--rev <REV>`	The revision to print, by number, such as `1` for the first baton.

$ handsoff baton BILL-42 --rev 1
## True now
The v2 invoice tables exist in staging. Nothing is copied into them yet.

## Next action
Copy the 2025 invoices into the v2 tables.

Done when: The row counts match between the old and new tables.
## Traps
The old table stores amounts in cents. The new one stores whole currency units.

## Evidence
Migration 0042 ran in staging and the billing tests passed.

## References
- [required] source: migrations/0042_invoices_v2.sql -- creates the v2 tables (check: bun test billing)

To change the baton, print it into a file, edit the file, and save it with handsoff save BILL-42 --baton <file>.