/agent-clean — Infrastructure-Failure Purge

Don't conflate "the agent didn't try because we ran out of credits" with "the agent tried and the code is broken."

The signal

Failed tasks in an autonomous agent fall into two completely different categories:

1. Infra failures — agent never got a chance: rate limit, credit exhausted, network timeout, auth expired
2. Real failures — agent tried, code is broken, prompt was wrong, env was missing

Bulk-requeuing all failures conflates these. Bulk-dead-lettering all failures throws away real work. /agent-clean separates them: it purges (or requeues) only the infra failures and leaves the real failures for /agent-triage.

Prerequisites

Usage

/agent-clean                    — sweep last 24h
/agent-clean 7d                 — sweep last 7 days
/agent-clean --requeue          — requeue infra failures instead of dead-lettering
/agent-clean --dry-run          — show what would be done, don't act

Workflow

Phase 1: Pull failures

curl -s -H "Authorization: Bearer $AGENT_API_TOKEN" \
  "$AGENT_API_URL/api/tasks?status=failed&since=24h"

Phase 2: Match each failure against infra patterns

For each failed task, fetch a tail of its log and match against these patterns:

Anything that doesn't match — leave alone. That's a real failure that needs /agent-triage.

Phase 3: Group + present

INFRA SWEEP — <window>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total failures:           <N>
Infra failures:           <N>  ←  this skill cleans these
Real failures:            <N>  ←  use /agent-triage

INFRA BREAKDOWN
  rate-limit:        <N>
  credit-exhausted:  <N>
  auth-expired:      <N>
  network:           <N>
  upstream-5xx:      <N>
  worker-crash:      <N>

PROPOSED ACTION
  default:           dead-letter all infra failures (with reason logged)
  --requeue mode:    requeue all infra failures

Real failures NOT touched:  <N>  (run /agent-triage to handle these)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Confirm? [y/N]

Phase 4: Execute

After explicit user confirmation:

# Default: dead-letter (cleaner — these were never the agent's fault, no need to retry)
for tid in $INFRA_TASK_IDS; do
  curl -s -X POST -H "Authorization: Bearer $AGENT_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"reason\": \"infra: $CLASS\"}" \
    "$AGENT_API_URL/api/tasks/$tid/dead-letter"
done

Or with --requeue:

for tid in $INFRA_TASK_IDS; do
  curl -s -X POST -H "Authorization: Bearer $AGENT_API_TOKEN" \
    "$AGENT_API_URL/api/tasks/$tid/requeue"
done

When to requeue vs dead-letter

When in doubt: dead-letter is safer (reversible — you can re-create the task). --requeue only when you've fixed the root cause.

Pairs with

• /agent-triage — handles the real failures (code, prompt, env). Run /agent-clean first to remove noise, then /agent-triage on what remains.
• /agent-status — verify the queue is clean afterward.

Notes

• Don't auto-requeue rate-limit failures while still rate-limited. You'll create another wave of failures. Verify the underlying constraint is fixed first.
• Log the reason on dead-letter. A future audit looking at "why was this dead-lettered" needs to see "infra: credit-exhausted" not just "dead-lettered."
• This skill is intentionally scoped narrowly. Don't try to clean code/prompt/env failures here — that's /agent-triage's job. Keep the scope clean.