Theme
Aa
← man.tcos.us gopher root · man.tcos.us
lu: · ·
HEE-PVE-DISPATCH(8)                HEE Tools                HEE-PVE-DISPATCH(8)

NAME
       hee-pve-dispatch  -  hand  one  bounded  job  to one agent container and
       collect the result

SYNOPSIS
              hee-pve-dispatch [-h] [--cred ACCOUNT] [--cred-dir DIR] [--key-env VAR]
                hee-pve-dispatch AGENT JOBDIR --cred ACCOUNT [--cred-dir DIR] [--ticket ID]
                hee-pve-dispatch AGENT JOBDIR --wif --cred ISSUER-KEY-ACCOUNT [--ticket ID]
                hee-pve-dispatch AGENT JOBDIR --collect JID [--ticket ID]     # a job whose dispatcher died: outputs, evidence, record
                hee-pve-dispatch AGENT JOBDIR --resume JID --budget USD --why TEXT   # a job that stopped at its ceiling: same session, same files

DESCRIPTION
                                      [--wif] [--ticket ID] [--offline] [--collect JID]
                                      [--resume JID] [--budget USD] [--why TEXT] [--dry-run]
                                      [--host HOST] [--allocations ALLOCATIONS]
                                      agent jobdir

              hee-pve-dispatch -- hand one bounded job to one agent container and collect the result.

              The first dispatch mechanism for the pve agent containers (fleet-ops#387):
              until the GitHub App, the factory's per-job token and tick-task exist, this
              is how work reaches an agent. Operator, 2026-09-10: "this jobs go to the new
              agents", "do not run these on kiosk", "let's see if we can utilize hee cred
              to provide the anthropic auth needed", "hee ticket and tick-task will be
              merging soon".

              What a dispatch is:
                1. AGENT names a role in the fleet allocation registry (ci-triage,
                   docs-keeper, ...). The registry gives its hostname and says it is an
                   agent; the live node gives its vmid. A non-agent container is refused.
                2. JOBDIR holds job.yaml, a prompt file, the inputs the job may read, and
                   (after the run) results/. Everything the agent sees is in that
                   directory, so a job is reviewable before it runs and reproducible after.
                3. The job's files are shipped INTO the container over pct exec (no repo
                   credential in the container), claude runs there as the `agent` user in
                   -p mode with a dollar budget and a wall-clock timeout, and the outputs
                   come back the same way into JOBDIR/results/<job id>/.
                4. The Anthropic key never touches the container's disk or any command
                   line. With --cred, this tool re-runs itself under `hee cred -pass`, so
                   the key exists only in this process's environment and is written to the
                   job's stdin, where the generated run.sh reads it into the environment of
                   the one claude process. `hee cred -seal` is the only way a key gets into
                   the store, and it accepts input only from a real terminal.
                5. A record of every dispatch is written to <repo>/.hee/dispatch/<job id>.yaml
                   (the repo JOBDIR lives in): agent, vmid, ticket, cost, turns, exit.

              job.yaml:
                name: convert-legacy-page           # short, becomes part of the job id
                prompt: prompt.md                   # file in JOBDIR; its text is the -p prompt
                inputs: [in/, rules.md]             # shipped; default: everything but results/
                outputs: [out/]                     # collected; default: out/
                agent: docs-keeper                  # optional: a dispatch that resolves to any other role is refused
                ticket: fleet-ops/0100              # optional: recorded when --ticket is not given
                blocked_by: [fleet-ops/0080]        # optional: while any is open a real dispatch refuses, a dry run warns
                budget_usd: 2.00                    # required -- claude --max-budget-usd; above 1.00 needs budget_reason
                budget_reason: "five doc pages to read and cite"   # required when budget_usd > 1.00
                timeout_s: 1800                     # default 1800 -- `timeout` around claude
                permission_mode: acceptEdits        # default; claude --permission-mode
                allowed_tools: [Read, Write, Edit, Glob, Grep]   # default; no Bash unless listed
                json_schema: schema.json            # optional; claude --json-schema
                system_prompt: system.md            # optional; claude --append-system-prompt-file

EXAMPLES
                $ hee pve dispatch ci-triage tests/fixtures/dispatch/job --dry-run --offline --allocations tests/fixtures/dispatch/allocations.yaml   # ci
                $ hee pve dispatch ci-triage tests/fixtures/dispatch/job --wif --dry-run --offline --allocations tests/fixtures/dispatch/allocations.yaml   # ci
                $ hee pve dispatch ci-triage pve/agents/jobs/wif-prep-readonly --wif --cred wif-issuer-lab --ticket 0090     # the real thing; needs the lab

                --wif: workload identity federation instead of a static key. --cred names
                   the hee cred account holding the lab issuer's ES256 private key (made by
                   `hee cred -seal ... -genkey es256`). This tool mints ONE JWT for the job
                   (iss/sub/aud from the allocation registry's console: block, unique jti,
                   exp = the job timeout + 2 min), ships it on stdin exactly as a key would
                   be, and the generated run.sh exchanges it once at the Claude Console
                   (POST /v1/oauth/token, jwt-bearer) for a short-lived token bound to the
                   role's service account, then runs claude with ANTHROPIC_AUTH_TOKEN. No
                   static API key exists anywhere for the agent. The registry entry needs
                   console.organization_id, workspace_id, service_account_id,
                   federation_rule_id, issuer and subject.
                hee-pve-dispatch AGENT JOBDIR --dry-run

              positional arguments:
                agent                 a role (ci-triage) or hostname from the allocation
                                      registry; must be kind: agent
                jobdir                directory holding job.yaml, the prompt and the inputs

              options:
                -h, --help            show this help message and exit
                --cred ACCOUNT        hee cred account holding the agent's Anthropic API
                                      key; this tool re-runs itself under `hee cred -pass
                                      ACCOUNT` so the key is never printed or on argv
                --cred-dir DIR        passed to hee cred -dir (default: its own default)
                --key-env VAR         read the key from this environment variable instead of
                                      --cred (what the --cred re-exec uses: HEE_CRED_PASS).
                                      Never pass a key on the command line.
                --wif                 federate instead of a static key: --cred is the lab
                                      issuer's signing key; the registry's console: block
                                      for the role supplies rule, org, service account,
                                      workspace, issuer, subject
                --ticket ID           the hee ticket this dispatch works on; recorded, not
                                      enforced
                --offline             with --dry-run: do not ask the pve node for the
                                      container; take the registry's vmid (fixtures, CI)
                --collect JID         collect a job that already ran (or is still running)
                                      in the container -- outputs, evidence, record --
                                      without shipping or running anything. For a dispatcher
                                      that died mid-job (kiosk killed one on low memory,
                                      2026-09-11).
                --resume JID          continue a job that stopped (its budget ceiling,
                                      usually) in the same container directory and the same
                                      Claude session, instead of starting over; needs
                                      --budget and --why. Recorded as a new record that
                                      resumes JID.
                --budget USD          with --resume: the new ceiling for this continuation
                --why TEXT            with --resume: what the extra money buys (recorded as
                                      resume_reason)
                --dry-run             resolve the agent, validate the job, print run.sh and
                                      the file list; ship and run nothing
                --host HOST
                --allocations ALLOCATIONS

                                                            HEE-PVE-DISPATCH(8)