urgent work first priorities, the queue, preempting
On a busy day every slot is taken and new work waits. Priorities decide
what starts next when a slot frees, and the queue shows the order and why
each task still waits. When something is on fire, a critical task can
pause low work to start at once.
what you need #
A flock that is full. Here desk and server-1 run 2 and 3 agents, and
every agent counts against max_agents: no job slots and no burst.
# ~/.config/pastor/flock.toml
[[machine]]
name = "desk"
local = true
max_agents = 2
job_slots = 0
burst = 0
[[machine]]
name = "server-1"
ssh = "user@server-1"
max_agents = 3
job_slots = 0
burst = 0Both default to 1. With burst = 1, a critical task first takes one slot
past max_agents, and pauses nothing until that is gone too.
jump the line #
Levels are low, normal, high and critical. A task that names none
takes its flock’s priority, else [defaults], else normal. Dispatch takes higher levels first, then the order tasks came in.
$ pastor task run "Fix the checkout crash on Safari" --repo '~/src/app' --worktree --priority high
$ pastor queuePOS TASK LEVEL WHERE FROM WAITED WHY NOT YET
1 t-21 high flock default task run 1m flock default is full
2 t-18 normal flock default job kanban 6m flock default is full
3 t-19 normal flock default task run 5m flock default is full
4 t-16 low flock default task run 14m flock default is fullPOS is the order the tasks will start in. FROM says who asked: task run
or a job. WAITED shows how long each has waited. After age_after (30
minutes by default) a queued task goes up a level, never past high, so
t-16 runs in the end behind normal and high work; a steady stream of
critical tasks would still go first.
reorder #
Put a task first. It takes the level of where it lands, so t-19 becomes
high:
$ pastor queue move t-19 --topt-19 is 1 of 4 in the queue; lifted from normal to high--before t-21, --after t-21 and --to 2 place it elsewhere. To change
a task’s level without moving it by hand, set it:
$ pastor task priority t-16 normalID STATE PRIORITY MACHINE FLOCK AGENT MODEL JOB AGE NOTE
t-16 queued normal - default claude - run 14m Tidy up the READMEpause low work #
Production is down. A critical task goes first, and with --preempt it
need not wait for a slot:
$ pastor task run "Prod login is down: find out why" --repo '~/src/app' --worktree --priority critical --preemptWith every slot full, it pauses the newest running low Claude task on a
machine and takes its slot. The paused agent is interrupted and its pane
closed; its worktree stays. With no such task to pause, the critical task
waits at the head of the queue.
$ pastor task list --machine server-1ID STATE PRIORITY MACHINE FLOCK AGENT MODEL JOB AGE NOTE
t-22 running critical server-1 default claude - run 1m Prod login is down: find out why
t-17 running normal server-1 default claude - run 25m Update the Node version in CI
t-15 running high server-1 default claude - run 40m Upgrade the payment SDK
t-14 paused low server-1 default claude - run 1h Rename the old config keysThe paused task goes back in the queue, first among the low ones, and
waits for its own machine:
POS TASK LEVEL WHERE FROM WAITED WHY NOT YET
1 t-19 high flock default task run 7m flock default is full
2 t-21 high flock default task run 3m flock default is full
3 t-16 normal flock default task run 16m flock default is full
4 t-18 normal flock default job kanban 8m flock default is full
5 t-14 low machine server-1 task run 1h paused for t-22; machine server-1 is full (3/3)When a slot on server-1 frees and nothing higher waits, t-14 resumes its
own Claude session there. Only a critical task may preempt, and only a
low Claude task is ever paused. A paused task keeps its place: queue move
does not move it.
start it now #
Sometimes you know exactly where the fix must run, and it cannot wait for
anything. --now with --machine starts the task there in the same
command, past the machine’s limits, and pauses nothing:
$ pastor task run "Roll back the bad migration" --repo '~/src/app' --machine server-1 --now
$ pastor machine listNAME HOST FLOCKS PROFILE CHANNEL HERDR PASTOR AGENTS ORPHANS TAGS ERROR
desk local default - connected 0.9.1 0.8.0 2/2 - -
server-1 user@server-1 default - connected 0.9.1 0.8.0 4/3 now:t-23 - -t-23 counts on server-1, so the queue starts nothing more there until
its count is under 3 again. --now needs --machine, and a connected one;
a job cannot set it, and an agent or orchestrator is refused, a guard
against mistakes rather than a boundary.