Module dispatch 

Dispatch and review: a worktree per task, agent runs within the batch budget, verification by pma itself, and the review actions.

Structs

Chosen

What a dispatch settled on: a worker, a model, the arguments that configure it, and the preset those came from.

Overrides

An agent and a model named on the command line. Both override the configuration and an applied route: a flag is the most recent statement of intent there is, and it covers the whole invocation.

Pick

A task chosen for dispatch.

Preflight

What pma verify found for one project.

UnitRef

Which workflow unit a dispatch serves.

Enums

Prepared

Target

What a target names after the colon.

Constants

ATTEMPT_LIMIT

Consumed attempts after which a task revision is not dispatched again. Two independent negative signals: an agent that cannot pass the check, or one that passed it and produced work a reviewer refused.

INNER_GRACE

How much sooner a worker that bounds itself is told to stop. A worker given the same deadline as this process is killed by it first, and one that runs a container then leaves the container for its own sweep to find.

NOT_STARTED

What prepare made of a pick. How a run refused before it started says so, in Run::error. A run that never reached the agent is not a run that failed: the caller leaves its work where it was rather than recording a result for it.

Functions

approve

attempt_key

What a run’s attempts count against. A workflow unit counts against its lineage, workflow:<instance>:<root>, so a retry and a lap draw from one budget (W23); anything else counts against its task text.

changelog_draft

Where a run’s drafted changelog entries are kept, outside its tree.

choose_worker

Which worker runs, at which model, with which configuration. Highest first: the -a and -m flags, a preset named on the command line, an applied route, then the default preset. A model named nowhere is a model this dispatch does not state: the worker is run without one and uses its own, which runs.model then records as null.

clone_held

clone_unchanged over runs already read, for a caller checking many repositories.

clone_unchanged

Refuses to run git in repo while a run there that is not settled found its snapshot changed, until the clone matches that snapshot again. A setting an agent added stays in the clone after its run fails; the next fetch or worktree add would run it, and the next snapshot would take it as its baseline.

diff

git diff of the worktree against the run’s base.

discard

Removes a run’s worktree and marks it rejected, consuming no attempt: what reject does before a reviewer’s judgement is counted. A local edit that failed verify was counted by verify; one that did not apply was judged by no one.

execute

Runs queued runs, at most max_parallel at once, starting a run only while the batch stays within batch_budget. done sees each run as it finishes.

git

Runs git -C dir args, returning trimmed stdout or an error naming the command and its stderr. With no filesystem monitor: one names a program, and these calls carry the user’s credentials.

git_snapshot

What makes git run a program in the worktree, or push somewhere else, that the diff does not show: each hook by content and executable bit, and each repository setting that names a command or rewrites a URL, by a hash of its value, since a URL may carry a token. Publishing compares it with the one taken at dispatch. Hooks that run tracked files, such as husky’s scripts or a .pre-commit-config.yaml, run what the reviewer approved in the diff. Global and system settings are the user’s, so they are left out.

is_signal

Whether a task key names a signal rather than a TODO.md item.

own_gitdir

Refuses a worktree whose .git is not a file naming this worktree’s entry under the clone’s worktrees/.

path_arg

preflight

Runs the project’s verify at the head of its remote default branch, in a fresh worktree and under the agent’s environment, as a dispatch’s base check does, and records the result in the base cache. A check that fails for a reason of its own then shows before an agent is paid to find it. Unlike dispatch, it measures again rather than reading the cache.

prepare

Checks pick against the remote default branch, then creates its worktree and branch and records a queued run. An error concerns the whole project, such as a failed fetch.

reject

keep accepts hooks or settings the run found changed as the user’s own. Without it, such a run is rejected only once the clone matches its snapshot again, so rejecting does not quietly lift what clone_unchanged holds.

remove_worktree

Removes the worktree and its branch. Either may already be gone.

revision

A task’s identity for the attempt counter. The normalised text, so a reworded specification starts fresh and a ci incident is identified by the workflows it names rather than by the word ci, which recurs.

rework

Runs the agent again in the same worktree with the reviewer’s feedback.

slug

Lowercase words of the task text joined by -, at most 40 bytes.

target

Splits project:what, or reads a bare project name.

tree

The worktree’s content as one object id: git add --all, which stages without committing, then git write-tree. The same call when publishing says whether anything changed since.

unchanged_git

Refuses a run whose repository gained or changed a hook, or a setting that runs a program or redirects a push, since dispatch. pma’s git calls carry the user’s credentials and environment, and none of that is in the diff the reviewer read. Also refuses a replaced .git, which is all a run from before the snapshot existed can be checked for.

verify_command

The project’s verify setting, else a command detected in the worktree. none disables verification.

verify_once

Runs command in worktree under the agent’s stripped environment, the same way the head check runs it. Ok(None) means it was killed at the timeout.

wants_changelog

Whether a run’s agent is asked for changelog entries: its project keeps a CHANGELOG.md.

without_item

A task with no line in any TODO.md: a signal, or a campaign applying one definition across repositories. There is nothing to check on origin before dispatch and nothing to tick when it is published.

wt_git

git in the run’s worktree, once its .git is still the one git worktree add wrote and its hooks and settings are the ones taken at dispatch. An agent that replaced either would hand these calls, which carry the user’s credentials, a program of its own to run.