Dispatch and land from the terminal

In the desktop, the Superintendent proposes a dispatch or a land and you approve it (see ask the Superintendent and follow work on the board). This page is the same sequence run by hand. For why dispatch and landing are separate, gated steps, read dispatch and the Gatehouse.

The examples use m-example for a manifest and m-example-t1 for a ready ticket on it. Add --works with your Works path to any of them, or set HM_WORKS.

Assign the ticket to a seat

A ticket is dispatched to the seat that holds it, so assign it first:

hm latch assign m-example-t1 --seat <seat>

The ticket must be ready. A seat holds one ticket at a time, and --steal moves a busy seat onto this ticket by releasing its current one. hm latch release m-example-t1 puts the ticket back in the open pool.

Preview, then dispatch

hm run dispatch m-example-t1 --dry-run
hm run dispatch m-example-t1

--dry-run changes nothing. It prints the workspace, the branch and the landing branch the dispatch would use, and any dependency it would inherit. Without it, hm prepares the ticket's workspace and starts the seat's agent with a brief.

Flags you may need:

• --model overrides the seat's model for this dispatch only.
• --redispatch starts a ticket again after a run that ended and left it assigned. hm otherwise refuses it as a duplicate.
• --require names a tool the seat must have credentials for, so a missing one fails before the agent starts.

Watch and steer the run

hm run status
hm run status --ticket m-example-t1
hm run log m-example-t1

status works out each run's state from the evidence, so a run whose process has died shows as dead. --ticket adds that ticket's full attempt history. log prints the end of the run's own output, with values that look like secrets removed.

To step in while it runs:

hm run pause m-example-t1
hm run terminate m-example-t1

pause freezes the process without losing its state. terminate ends it. Both are recorded. After a terminate the ticket stays assigned, so hm run dispatch m-example-t1 sends it again.

When the hand finishes

The agent commits its work to the manifest's branch and then runs hm ticket complete m-example-t1. Complete is the agent's claim that it is done; it integrates nothing. Check the manifest before landing:

hm manifest status m-example
hm gatehouse land m-example --dry-run

status gives a land-readiness verdict. land --dry-run prints what a land would do to each ticket, changing neither git nor the ledger.

Land

hm gatehouse land m-example --git --approve-push

--git merges the manifest's branch, and --approve-push is your approval to do so. What the merge does depends on the land mode set in the Works:

• direct merges and pushes to the remote landing branch;
• local merges into the local landing branch and never pushes;
• pr only verifies. Use --verify-only once the pull request has merged, to confirm the work is on the landing branch and close the record.

If the Works lands each ticket as it finishes, add --ticket m-example-t1. Without --git, a land is recorded in the ledger only, and doctor warns if that work never reaches the landing branch.

When a land is refused for a conflict

hm gatehouse resolve --manifest m-example --theirs <path>

resolve merges the landing branch into the manifest's branch, so the fix happens on the work branch. Name each conflicted path with --ours, --theirs or --file; a path with no decision stops the merge and leaves the workspace as it was. It pushes nothing. Run hm gatehouse land again afterwards.