usage: publish_event.py [-h] (--job JOB | --pick-pending)
                        [--agent-session AGENT_SESSION]
                        [--event {started,permission_required,progress,completed,error,cancelled}]
                        [--detail DETAIL] [--data DATA] [--retained]
                        [--registry-dir REGISTRY_DIR] [--attempts ATTEMPTS]
                        [--finalize-report PATH]
                        [--side-effect KIND=REFERENCE]
                        [--attempt-id ATTEMPT_ID]
                        [--expect-dispatch-token EXPECT_DISPATCH_TOKEN]
                        [--heartbeat N] [--no-state] [--watch-pid WATCH_PID]
                        [-v]

Publish a Job event to MQTT

optional arguments:
  -h, --help            show this help message and exit
  --job JOB             job id to publish for
  --pick-pending        auto-select a pending job for --agent-session
  --agent-session AGENT_SESSION
                        session label used with --pick-pending
  --event {started,permission_required,progress,completed,error,cancelled}
  --detail DETAIL
  --data DATA           optional JSON object string
  --retained            force retain=True (auto for completed/error)
  --registry-dir REGISTRY_DIR
  --attempts ATTEMPTS
  --finalize-report PATH
                        atomically finalize this report and declare its
                        completion manifest before publishing
  --side-effect KIND=REFERENCE
                        evidence for an external side effect this job
                        performed
  --attempt-id ATTEMPT_ID
                        attempt this finalization belongs to (default: the
                        job's current iteration)
  --expect-dispatch-token EXPECT_DISPATCH_TOKEN
                        expected dispatch token for CAS verification
  --heartbeat N         after publishing, start a detached timer that
                        publishes a `progress` heartbeat every N seconds until
                        the job ends (Issue #18; not with a terminal event)
  --no-state            do not publish the retained <topic_prefix>/state
                        message
  --watch-pid WATCH_PID
                        bind the heartbeat timer to this process (default: the
                        nearest agent-CLI ancestor; 0 = no watch)
  -v, --verbose