docs: failure semantics & why-not-a-naive-marker-file guide

[samuelagents]

Motivation

The most common idempotency bug is writing the marker before the effect succeeds, which permanently swallows the message on failure. A dedicated guide should make the failure semantics explicit so users pick the right lease and understand retry behavior.

Proposal

Add docs/failure-semantics.md covering:

• The state machine: pending → done | failed, and what each means.
• Why a failed effect stays retryable (anti-swallow), with a before/after code example.
• Lease tuning: how leaseMs interacts with crash recovery and concurrent runners.
• Comparison table vs a naive touch-a-file marker.

Acceptance

• Guide written and linked from README.
• Includes the swallow-bug anti-pattern and the corrected pattern.