cli: add crash-safe, resumable agent-loop ledger #2602

Goal

Make the agent ledger crash-safe and allow a stopped loop to resume or hand off deterministically without duplicating mutations.

Background

The ledger in #2577 records loop events, but a controller can be interrupted during an append, GitHub mutation, lease transition, or hosted-check observation. Without a recovery contract, a retry can duplicate claims, draft PRs, comments, or repairs. A deterministic harness needs durable idempotency and explicit recovery outcomes.

Tracking: #2555. Depends on #2577 and feeds #2578, #2580, and #2581.

Scope

• Define atomic event append, partial-line recovery, schema-version handling, and corruption diagnostics.
• Add run checkpoints and idempotency keys for claim, prepare, draft-PR, comment, and repair operations.
• Define resume, abandon, and handoff behavior after process interruption, lease expiry, network failure, or ambiguous GitHub response.
• Ensure recovery never repeats a non-idempotent mutation without readback.
• Add deterministic replay fixtures for interruption before, during, and after each external mutation.

Acceptance Criteria

• A truncated or malformed ledger fails closed with a recoverable finding and never silently discards events.
• Resume either continues from a verified checkpoint or produces a clear handoff; it never duplicates a GitHub mutation.
• Ambiguous API outcomes require readback before retry.
• Recovery events are redacted, schema-valid, and linked to the original run ID.
• Fixtures cover crash, network failure, lease expiry, and manual takeover.

Validation

BASE_CLI_SOURCE_DIR=../base-cli/lib/python \
PYTHONPATH=../base-cli/lib/python:lib/python:cli/python \
python -m pytest tests/contracts <new ledger recovery tests>
git diff --check

Non-Goals

• No remote telemetry or hosted ledger service.
• No distributed locking service.
• No automatic merge or release recovery.

Project Fields

• Status: Backlog
• Priority: P1
• Area: CLI
• Initiative: Agentic Coding Platform
• Size: M
• Milestone: v1.13.0
• Category: enhancement

Agent Assignment

Assignee: codeforester. Implementation-ready after #2577's event shape is stable; use an issue-backed worktree.

Plan revision (2026-10-16)

Add #2582 as a prerequisite alongside #2577. The ledger extension must define atomic append/checkpoint behavior, partial-line recovery, idempotency keys, GitHub readback after ambiguous API results, and explicit resume, abandon, and handoff states. A resumed run must not duplicate a PR, claim, mutation, or metric. Interruption and crash fixtures must be shared with #2582 and must prove redaction after recovery.