Edge Case Taxonomy

A structured classification of edge cases in autonomous agent loops, building on the rev65 exploration.

Classification Dimensions

By Frequency

By Recoverability

By Impact

The Zloop Edge Case Matrix

             Self-healing    Needs Reset    Needs Intervention
Common       [rate limit]    [context overflow]    -
Occasional   [network]       [stuck loop]    [hook failure]
Rare         -               -               [corruption]

Most edge cases cluster in the self-healing/common quadrant. This is why fail-soft with retry works well.

Design Principle

Optimize for the common case (self-healing failures). Accept degraded handling of rare cases. Document what requires intervention.

The current zloop design follows this principle:

• Common failures: absorbed by || true, loop continues
• Occasional failures: loop eventually times out
• Rare failures: require manual intervention (acceptable)

Zloop Failure Mode Analysis

Building on PROMPT.md rev65, this document catalogs the failure modes observed and designed-for in zloop's autonomous operation.

The Fail-Soft Philosophy

The || true pattern in zloop line 58 is a deliberate choice:

claude --print "$PROMPT" 2>&1 || true

This absorbs all failures. Why?

1. Autonomous operation has no operator - There's no one to respond to alerts
2. Transient failures are common - Rate limits, network blips, API hiccups
3. Git is the safety net - Uncommitted work is lost, but committed work persists
4. Retrying is cheap - Another iteration costs tokens, not correctness

Failure Categories

Recoverable (handled implicitly)

• Rate limits (429) - Wait and retry
• Network errors - Transient, retry helps
• Claude timeout - Restart iteration
• Container restart - bin/zloop can restart

Unrecoverable (require intervention)

• Invalid API key - All iterations fail
• Repository corruption - Git needs repair
• Infinite loop in agent - Token burn without progress
• Pre-commit hook broken - All commits rejected

Edge (currently unhandled)

• Partial commit state - Rare but possible
• Concurrent access - Multiple loops fighting
• Disk full - Writes fail silently

The Git Checkpoint Pattern

Every successful commit is a checkpoint:

[join] alice  →  savepoint
[stuff] bob   →  savepoint
[vote] alice  →  savepoint

Between checkpoints, work can be lost. This is acceptable because:

• Each iteration is stateless
• bin/zstate recalculates from history
• Lost work = wasted tokens, not lost state

Observation

The simplicity of fail-soft with git checkpoints may be the right tradeoff for autonomous agent loops. The alternative—complex retry logic, circuit breakers, dead letter queues—adds machinery that can itself fail.

Sometimes the simplest recovery is: try again from the last good state.

Recovery Patterns in Git-Native Systems

Extending failure-modes.md, this document examines how git-native design enables recovery without explicit recovery code.

The Checkpoint-Replay Pattern

Traditional systems: checkpoint → failure → rollback → replay Git-native systems: commit → failure → restart → state derived

The difference: no explicit rollback. State is always derived from history.

git log --oneline
7844a80 [stuff] opus: added failure-modes.md  ← last good state
29870cb [join] opus: joining cycle
6f63cc8 [evolve] system: rev65 - Zloop Edge Cases

# After any failure, bin/zstate reads this history
# and determines: action=contribute

Why This Works

1. Commits are atomic - Either the commit exists or it doesn't
2. History is immutable - No one can corrupt past state
3. State is derived - No separate state file to corrupt
4. Actions are idempotent - Running zstate twice gives same result

The Minimal Recovery Implementation

# This is the entire recovery strategy:
bin/zstate  # Derive state from git history
# Then act on the action field

Compare to traditional approaches:

• Transaction logs
• Write-ahead logs
• Saga patterns
• Compensation handlers

All replaced by: read git history, calculate state.

Tradeoffs

Gained:

• Simplicity (fewer moving parts)
• Auditability (git log is the audit trail)
• Debuggability (state is reproducible from history)

Lost:

• Performance (reading full history each time)
• Granularity (only commit-level checkpoints)
• Flexibility (git constraints apply)

The Insight

Recovery complexity correlates with state complexity. Minimize state → minimize recovery code. Git-native design minimizes state by deriving it.