Jobs

A Job represents a single execution of an agent. Each time an agent runs—whether triggered by a schedule, manual invocation, or trigger event—herdctl creates a job to track that execution from start to finish.

Job Properties

Property	Type	Description
`id`	string	Unique job identifier (UUID)
`agent`	string	Name of the agent executing this job
`schedule`	string	Schedule that triggered this job (if scheduled)
`status`	enum	Current job status
`exitReason`	enum	Why the job ended (set on completion)
`sessionId`	string	Claude session ID for resume capability
`startedAt`	timestamp	When the job started execution
`completedAt`	timestamp	When the job finished (success or failure)
`output`	string	Path to job output file (JSONL format)
`error`	string	Error message if job failed

Job Lifecycle

Jobs progress through a defined lifecycle:

PENDING → RUNNING → COMPLETED
                  → FAILED
                  → CANCELLED

Status Definitions

Status	Description
`running`	Job is currently executing
`completed`	Job finished successfully
`failed`	Job terminated due to an error
`cancelled`	Job was manually stopped

Exit Reasons

When a job completes, it records an exit reason explaining why it ended:

Exit Reason	Description
`success`	Job completed all tasks successfully
`error`	Job failed due to an error
`timeout`	Job exceeded its configured time limit
`manual_cancel`	Job was cancelled by user intervention

Example Job Record

{
  "id": "job-550e8400-e29b",
  "agent": "bragdoc-coder",
  "schedule": "daily-standup",
  "status": "completed",
  "exitReason": "success",
  "sessionId": "sess-a1b2c3d4",
  "startedAt": "2024-01-15T09:00:00Z",
  "completedAt": "2024-01-15T09:15:32Z",
  "output": "~/.herdctl/jobs/job-550e8400-e29b/output.jsonl"
}

Job Output Format

Job output is stored in JSONL (JSON Lines) format, where each line is a separate JSON object representing an event during execution:

{"type":"start","timestamp":"2024-01-15T09:00:00Z","message":"Job started"}
{"type":"tool_use","timestamp":"2024-01-15T09:00:05Z","tool":"Read","file":"src/index.ts"}
{"type":"output","timestamp":"2024-01-15T09:00:10Z","content":"Reading file contents..."}
{"type":"tool_use","timestamp":"2024-01-15T09:00:15Z","tool":"Edit","file":"src/index.ts"}
{"type":"complete","timestamp":"2024-01-15T09:15:32Z","exitReason":"success"}

Output Event Types

Type	Description
`start`	Job execution began
`output`	Text output from Claude
`tool_use`	Tool invocation
`tool_result`	Tool execution result
`error`	Error occurred
`complete`	Job finished

Viewing Job Output

# Stream job output
herdctl jobs logs <job-id>

# Follow output in real-time
herdctl jobs logs <job-id> --follow

# Show only errors
herdctl jobs logs <job-id> --level error

# Export to file
herdctl jobs logs <job-id> > job-output.log

Working with Jobs

Listing Jobs

# List all jobs
herdctl jobs list

# Filter by status
herdctl jobs list --status running
herdctl jobs list --status completed
herdctl jobs list --status failed
herdctl jobs list --status cancelled

# Filter by agent
herdctl jobs list --agent bragdoc-coder

# Filter by time range
herdctl jobs list --since 24h
herdctl jobs list --since "2024-01-15"

Viewing Job Details

# Show full job details
herdctl jobs show <job-id>

# Show job in JSON format
herdctl jobs show <job-id> --json

Cancelling Jobs

# Cancel a running job
herdctl jobs cancel <job-id>

# Cancel all jobs for an agent
herdctl jobs cancel --agent bragdoc-coder

Job Resume

Jobs store their Claude session ID, enabling resume after interruption. This is useful when:

Network connectivity was lost
The job was manually paused
The system was restarted during execution

# Resume a specific job
herdctl jobs resume <job-id>

# Resume with additional context
herdctl jobs resume <job-id> --prompt "Continue from where you left off"

Job Storage

Jobs are persisted to disk for history and recovery. See State Management for details on storage backends and configuration.

~/.herdctl/
├── jobs/
│   └── <job-id>/
│       ├── job.json      # Job metadata
│       └── output.jsonl  # Execution output
└── logs/
    └── <agent>/
        └── <job-id>.log  # Agent-specific logs

Agents - What executes jobs
Schedules - What triggers scheduled jobs
Triggers - What triggers event-based jobs
Sessions - Job execution context
State Management - Job storage and persistence