Entomologist Task Runner — Cron Job Architecture

Overview

The entomologist task runner is an autonomous cron-based system that polls an entomologist issue tracker for new tasks assigned to "agent" and spawns background workers to handle them.

The entire system runs on a single machine under the Hermes gateway, which provides a cron scheduler, background process management, and LLM-based agents.

Components

1. Hermes Gateway Cron Scheduler

The Hermes gateway includes a built-in cron ticker that executes scheduled jobs at configurable intervals. Cron jobs are defined in:

$HERMES_HOME/cron/jobs.json

Each job has:

• id — unique job identifier
• name — human-readable name
• prompt — the system prompt given to the agent for each run
• schedule — interval configuration (e.g. every 1 minute)
• enabled_toolsets — tools available to the agent (e.g. ["terminal"])
• deliver — where output goes (local saves to $HERMES_HOME/cron/output/<JOB_ID>/)
• workdir — working directory for the agent session

2. The Cron Job (Dispatcher)

Job name: entomologist-task-runner Schedule: every 1 minute Working directory: /opt/data/agent-tasks

The dispatcher runs the following workflow on each tick:

1. Sync — ent sync to fetch latest changes from remote
2. List — ent list assignee=agent state=new,inprogress,blocked,backlog to find all issues assigned to agent that are not in terminal states (Done or WontDo)
3. Silent — If no new issues, respond with [SILENT] (suppresses delivery)
4. For each new issue:
   • Get full details: ent show <ISSUE_ID>
   • Mark as InProgress: ent state <ISSUE_ID> InProgress
   • Spawn a background worker via hermes chat -q with the issue details
5. Sync — ent sync after spawning workers

3. Background Workers

For each new issue, the dispatcher spawns an independent Hermes agent process:

export HERMES_HOME=/opt/data && cd /opt/data/agent-tasks && hermes chat -q "WORK ON THIS ENTOMOLOGIST ISSUE..."

Each worker:

• Receives the issue ID, description, and AGENTS.md rules
• Works on the issue autonomously
• Comments progress using ent comment <ID> "update"
• On completion: comments final status and reassigns to "handler" via ent assign <ID> handler
• On stuck: comments why, sets state to Blocked, reassigns to "handler"
• Never sets state to Done — only the handler can do that

4. Entomologist CLI (ent)

The ent CLI is installed at /usr/bin/ent and manages the entomologist issue tracker. Issues are stored on the entomologist-data git branch as directories named by issue ID.

Key commands:

Command	Description
ent sync	Fetch/push changes with remote, merge entomologist-data branch
ent list assignee=X state=Y	Filter and list issues
ent show <ID>	Show full issue details
ent state <ID> <STATE>	Change issue state (New, InProgress, Blocked, Done)
ent comment <ID> "msg"	Add a comment to an issue
ent assign <ID> <USER>	Reassign issue to a user

5. Issue Lifecycle

New → InProgress (cron picks up, spawns worker)
      → [work done]
        → Blocked + assignee=handler (worker stuck, needs info)
        → assignee=handler (worker complete, handler marks Done)

The cron processes issues in New, InProgress, Blocked, and Backlog states. Issues in Done and WontDo states are skipped.

Directory Layout

$HERMES_HOME/
├── cron/
│   ├── jobs.json              # Cron job definitions
│   ├── .tick.lock             # Lock file for concurrent tick prevention
│   └── output/<JOB_ID>/       # Output from each cron run
├── skills/
│   └── devops/
│       └── entomologist-task-dispatcher/
│           ├── SKILL.md       # Skill documentation
│           └── references/
│               ├── cron-prompt.md      # Prompt template
│               └── ent-cli-reference.md
└── agent-tasks/               # The task repository (git)
    ├── AGENTS.md              # Workflow rules for agents
    └── docs/                  # This documentation

Configuration

Cron Job Configuration

The cron job is defined in $HERMES_HOME/cron/jobs.json. See cron-job.prompt in this directory for the actual prompt used by the dispatcher.

Environment Variables

Variable	Value	Purpose
HERMES_HOME	/opt/data	Root directory for Hermes data

Troubleshooting

• No issues being picked up: Check ent list assignee=agent state=new,inprogress,blocked,backlog manually
• Workers not spawning: Check $HERMES_HOME/cron/output/<JOB_ID>/ for errors
• Issues stuck in InProgress: Worker may have crashed; reset with ent state <ID> New
• Cron not running: Verify gateway is running and cron ticker is enabled
• Push fails: Run ent sync to resolve any git conflicts on entomologist-data branch