Autonomous Dev Team Dispatcher

Scan GitHub issues and dispatch dev/review tasks locally.

Security Note: This dispatcher processes GitHub issue content as input. In public repositories, issue content is untrusted — anyone can create issues. Ensure the autonomous label can only be applied by trusted maintainers (use GitHub branch rulesets or organizational policies). The dispatcher itself only reads labels/comments and spawns local processes — it does NOT modify source code or push to branches.

GitHub Authentication — USE APP TOKEN, NOT USER TOKEN

CRITICAL: All gh CLI calls MUST use a GitHub App token, NOT the default user token.

Before running any gh command, generate and export the App token using the shared script at scripts/gh-app-token.sh:

# Source the shared token generator
source "${PROJECT_DIR}/scripts/gh-app-token.sh"

# Generate token for the dispatcher's GitHub App
GH_TOKEN=$(get_gh_app_token "$DISPATCHER_APP_ID" "$DISPATCHER_APP_PEM" "$REPO_OWNER" "$REPO_NAME") || {
  echo "FATAL: Failed to generate GitHub App token" >&2
  exit 1
}
if [[ -z "$GH_TOKEN" ]]; then
  echo "FATAL: GitHub App token is empty" >&2
  exit 1
fi
export GH_TOKEN

The DISPATCHER_APP_PEM env var must point to the App's private key PEM file. If not set, provide the path explicitly.

This ensures all issue comments, label changes, and API calls appear as the configured GitHub App bot instead of a personal user account. The token is valid for 1 hour and scoped to the target repo only.

DO NOT skip this step. If GH_TOKEN is not set, gh will fall back to the user's personal token, which is incorrect.

Environment Variables

• REPO: GitHub repo in owner/repo format (e.g., myorg/myproject)
• PROJECT_DIR: Absolute path to the project root on the local machine
• MAX_CONCURRENT: Max parallel tasks (default: 5)
• MAX_RETRIES: Max dev retry attempts before marking issue as stalled (default: 3)
• PROJECT_ID: Project identifier for log/PID files (default: project)
• DISPATCHER_APP_ID: GitHub App ID for the dispatcher bot
• DISPATCHER_APP_PEM: Path to the GitHub App private key PEM file

Local Dispatch Helper Script

CRITICAL: All task dispatches (dev-new, dev-resume, review) MUST use the helper script scripts/dispatch-local.sh in the project root's scripts/ directory. The script handles:

• Background process spawning via nohup
• Input validation (numeric issue numbers, safe session IDs)
• Config loading from scripts/autonomous.conf

Usage:

# PROJECT_DIR is the absolute path to the project root

# For new dev task:
bash "$PROJECT_DIR/scripts/dispatch-local.sh" dev-new ISSUE_NUM

# For review task:
bash "$PROJECT_DIR/scripts/dispatch-local.sh" review ISSUE_NUM

# For resume dev task:
bash "$PROJECT_DIR/scripts/dispatch-local.sh" dev-resume ISSUE_NUM SESSION_ID

DO NOT construct dispatch commands manually. Always use the dispatch-local.sh script.

DO NOT commit or push code to the target repository. The dispatcher's role is strictly:

1. Read issue labels and comments via GitHub API
2. Update labels and post comments via GitHub API
3. Dispatch local processes using the helper script

All code changes happen via the autonomous-dev/review scripts. The dispatcher MUST NOT modify source files or push to any branch (especially main).

Dispatch Logic

When triggered (cron every 5 minutes), execute the following steps IN ORDER.

Important: Maintain a JUST_DISPATCHED array to track issue numbers dispatched in the current cycle. This prevents Step 5 from false-positive stale detection on freshly dispatched processes whose PID files haven't been written yet.

# Initialize at the start of each dispatch cycle
JUST_DISPATCHED=()

Step 1: Check Concurrency

Count issues with labels in-progress OR reviewing:

ACTIVE=$(gh issue list --repo "$REPO" --state open --limit 100 \
  --label "autonomous" --json labels \
  -q '[.[] | select(.labels[].name | IN("in-progress","reviewing"))] | length')

If ACTIVE >= MAX_CONCURRENT (default 5), STOP. Log "Concurrency limit reached (ACTIVE/MAX_CONCURRENT)" and exit.

Step 2: Scan for New Tasks

Find issues with autonomous label but NO state labels:

gh issue list --repo "$REPO" --state open --limit 100 \
  --label "autonomous" --json number,labels,title \
  -q '[.[] | select(
    [.labels[].name] | (
      contains(["in-progress"]) or
      contains(["pending-review"]) or
      contains(["reviewing"]) or
      contains(["pending-dev"]) or
      contains(["stalled"]) or
      contains(["approved"])
    ) | not
  )]'

For each found issue (respecting concurrency limit):

1. Check Dependencies — before dispatching, read the issue body and look for a ## Dependencies section. Parse issue references (#N) from that section. For each referenced issue, check if it is closed:

# Extract dependency issue numbers from the issue body
DEPS=$(gh issue view ISSUE_NUM --repo "$REPO" --json body -q '.body' \
  | sed -n '/^## Dependencies/,/^## /p' \
  | grep -oP '#\K[0-9]+')

# Check if all dependencies are closed
BLOCKED=false
for DEP in $DEPS; do
  STATE=$(gh issue view "$DEP" --repo "$REPO" --json state -q '.state')
  if [ "$STATE" != "CLOSED" ]; then
    BLOCKED=true
    break
  fi
done

if [ "$BLOCKED" = true ]; then
  # Skip this issue — dependency not yet resolved
  continue
fi

If any dependency issue is still open, skip this issue silently (do not add labels or comment). It will be picked up in the next dispatch cycle after its dependencies are resolved.

2. Add in-progress label 3. Comment: Dispatching autonomous development... 4. Dispatch via helper script:

bash "$PROJECT_DIR/scripts/dispatch-local.sh" dev-new ISSUE_NUM

5. Track dispatched issue: JUST_DISPATCHED+=(ISSUE_NUM) 6. Re-check concurrency after each dispatch

Step 3: Scan for Review Tasks

Find issues with autonomous + pending-review (no reviewing):

gh issue list --repo "$REPO" --state open --limit 100 \
  --label "autonomous,pending-review" --json number,labels \
  -q '[.[] | select([.labels[].name] | contains(["reviewing"]) | not)]'

For each found issue (respecting concurrency limit): 1. Remove pending-review, add reviewing 2. Comment: Dispatching autonomous review... 3. Dispatch via helper script:

bash "$PROJECT_DIR/scripts/dispatch-local.sh" review ISSUE_NUM

4. Track dispatched issue: JUST_DISPATCHED+=(ISSUE_NUM)

Step 4: Scan for Pending-Dev (Resume)

Find issues with autonomous + pending-dev:

gh issue list --repo "$REPO" --state open --limit 100 \
  --label "autonomous,pending-dev" --json number,labels,comments

For each found issue (respecting concurrency limit):

1. Check retry count — before dispatching, count BOTH failed Agent Session Report (Dev) comments (exit code ≠ 0) AND dispatcher-detected crash comments. Only count failures that occurred after the last stalled→unstalled transition (i.e., after the most recent "Marking as stalled" comment). This ensures that removing the stalled label resets the retry counter. Successful dev completions (exit code 0) that were sent back by review do NOT count as retries:

# Find the timestamp of the last "Marking as stalled" comment (retry counter cutoff).
# If the issue was never stalled, use epoch (1970-01-01T00:00:00Z) to count all comments.
LAST_STALLED_AT=$(gh issue view ISSUE_NUM --repo "$REPO" --json comments \
  -q '[.comments[] | select(.body | test("Marking as stalled"))] | last | .createdAt // "1970-01-01T00:00:00Z"')

# Count failed agent session reports (only after last stalled cutoff)
AGENT_FAILURES=$(gh issue view ISSUE_NUM --repo "$REPO" --json comments \
  -q "[.comments[] | select((.createdAt > \"${LAST_STALLED_AT}\") and (.body | test(\"Agent Session Report \\\\(Dev\\\\)\")) and (.body | test(\"Exit code: 0\") | not))] | length")

# Count dispatcher-detected crashes (only after last stalled cutoff)
DISPATCHER_CRASHES=$(gh issue view ISSUE_NUM --repo "$REPO" --json comments \
  -q "[.comments[] | select((.createdAt > \"${LAST_STALLED_AT}\") and (.body | test(\"Task appears to have crashed|process not found|crashed \\\\(no PR found\\\\)|crashed\\\\. PR found\")))] | length")

RETRY_COUNT=$((AGENT_FAILURES + DISPATCHER_CRASHES))
MAX_RETRIES="${MAX_RETRIES:-3}"

if [ "$RETRY_COUNT" -ge "$MAX_RETRIES" ]; then
  # Issue has exceeded retry limit — mark as stalled
  gh issue edit ISSUE_NUM --repo "$REPO" \
    --remove-label "pending-dev" \
    --add-label "stalled"
  gh issue comment ISSUE_NUM --repo "$REPO" \
    --body "Issue has exceeded the maximum retry limit ($MAX_RETRIES failed attempts: $AGENT_FAILURES agent failures + $DISPATCHER_CRASHES dispatcher-detected crashes). Marking as stalled. @${REPO_OWNER} please investigate manually."
  continue
fi

If combined retry count exceeds MAX_RETRIES (default 3), add stalled label, remove pending-dev, post a comment, and skip this issue. When a user removes the stalled label to re-dispatch, the retry counter automatically resets because only crashes after the latest "Marking as stalled" comment are counted.

2. Extract latest dev session ID from issue comments (search for Dev Session ID: — do NOT match Review Session ID:):

SESSION_ID=$(gh issue view ISSUE_NUM --repo "$REPO" --json comments \
  -q '[.comments[].body | capture("Dev Session ID: `(?P<id>[a-zA-Z0-9_-]+)`"; "g") | .id] | last // empty')

3. Remove pending-dev, add in-progress 4. Comment: Resuming development (session: SESSION_ID)... 5. Dispatch via helper script:

bash "$PROJECT_DIR/scripts/dispatch-local.sh" dev-resume ISSUE_NUM SESSION_ID

6. Track dispatched issue: JUST_DISPATCHED+=(ISSUE_NUM)

Step 5: Stale Detection

Find issues with in-progress or reviewing that may be stuck.

Skip freshly dispatched issues: Before checking any issue, verify it was NOT dispatched in the current cycle. Issues in JUST_DISPATCHED must be skipped — their PID files may not exist yet.

# Skip issues dispatched in this cycle
if [[ " ${JUST_DISPATCHED[*]} " == *" ISSUE_NUM "* ]]; then
  # Skip — just dispatched this cycle, PID file may not exist yet
  continue
fi

For each remaining issue, check if the agent process is still alive locally. Use the correct PID file prefix based on the issue's current label:

• in-progress issues use PID file: /tmp/agent-${PROJECT_ID}-issue-ISSUE_NUM.pid
• reviewing issues use PID file: /tmp/agent-${PROJECT_ID}-review-ISSUE_NUM.pid

# For in-progress issues:
kill -0 $(cat /tmp/agent-${PROJECT_ID}-issue-ISSUE_NUM.pid 2>/dev/null) 2>/dev/null && echo ALIVE || echo DEAD

# For reviewing issues:
kill -0 $(cat /tmp/agent-${PROJECT_ID}-review-ISSUE_NUM.pid 2>/dev/null) 2>/dev/null && echo ALIVE || echo DEAD

If DEAD and issue still has in-progress, check whether a PR exists before deciding the transition:

PR_EXISTS=$(gh pr list --repo "$REPO" --state open --json number,body \
  -q "[.[] | select(.body | test(\"#ISSUE_NUM[^0-9]\") or test(\"#ISSUE_NUM$\"))] | length")

if [ "$PR_EXISTS" -gt 0 ]; then
  # PR exists — review agent can assess the work
  # Comment: "Task appears to have crashed. PR found — moving to pending-review for assessment."
  # Remove `in-progress`, add `pending-review`
else
  # No PR — dev agent didn't finish, retry development
  # Comment: "Task appears to have crashed (no PR found). Moving to pending-dev for retry."
  # Remove `in-progress`, add `pending-dev`
fi

If DEAD and issue still has reviewing:

1. Comment: Review process appears to have crashed. Moving to pending-dev for retry.
2. Remove reviewing, add pending-dev

Cron Configuration (OpenClaw)

openclaw cron add \
  --name "Autonomous Dispatcher" \
  --cron "*/5 * * * *" \
  --session isolated \
  --message "Run the autonomous-dispatcher skill. Check GitHub issues and dispatch tasks." \
  --announce

Label Definitions

Label	Color	Description
autonomous	#0E8A16	Issue should be processed by autonomous pipeline
in-progress	#FBCA04	Agent is actively developing
pending-review	#1D76DB	Development complete, awaiting review
reviewing	#5319E7	Agent is actively reviewing
pending-dev	#E99695	Review failed, needs more development
approved	#0E8A16	Review passed. PR merged (or awaiting manual merge if no-auto-close present)
no-auto-close	#d4c5f9	Used with autonomous — skip auto-merge after review passes, requires manual approval
stalled	#B60205	Issue exceeded max retry attempts; requires manual investigation

Model Strategy

Task	Model	Rationale
Development (autonomous-dev.sh)	Opus (default)	Complex coding, architecture decisions
Review (autonomous-review.sh)	Sonnet (--model sonnet)	Checklist verification, avoids Opus quota contention