Checkpoint

Checkpoint

Overview

Checkpoints record the successful completion of each pipeline phase. They are written after a phase finishes (never during) and enable:

• Resume: Restart a pipeline from a specific phase without re-running prior phases
• Validation: Verify that prior phase outputs are structurally sound before skipping
• Replay: Audit trail of pipeline execution across attempts
• Idempotency: Append-only writes with monotonically increasing attempt numbers

Checkpoints are backed by the omnibase_infra checkpoint node infrastructure and managed through the checkpoint_manager.py CLI wrapper.

Announce at start: "I'm using the checkpoint skill to manage pipeline state."

Backing Status ()

Backed by (real, non-stub): omnibase_infra/src/omnibase_infra/nodes/node_checkpoint_effect/ (EFFECT — read/write/list handlers) and omnibase_infra/src/omnibase_infra/nodes/node_checkpoint_validate_compute/ (COMPUTE — validate handler), invoked in practice via plugins/onex/hooks/lib/checkpoint_manager.py (functional CLI wrapper, no stub markers).

The generated omniclaude shell node_skill_checkpoint_orchestrator (maturity: stub in its contract.yaml) is a Polly-passthrough that is NOT the real dispatch path for this skill — it exists only from the bulk generate_skill_node.py pass and is never actually invoked. skill_functional_audit's naive node_<skill_name> path match doesn't resolve to the real omnibase_infra node names above, which is why it (mis)flags this skill as a facade. Tracked cleanup: (repoint the registry / retire the dead shell).

Storage Layout

Checkpoints are stored as YAML files under the user's home directory:

$ONEX_STATE_DIR/checkpoints/{ticket_id}/{run_id}/phase_{N}_{name}_a{attempt}.yaml

Where:

• {ticket_id} -- Linear ticket identifier (e.g., PROJ-1234)
• {run_id} -- Pipeline run UUID
• {N} -- Phase ordinal (1-4)
• {name} -- Phase value string
• {attempt} -- Monotonically increasing attempt counter

Example:

$ONEX_STATE_DIR/checkpoints/{ticket_id}/e3a1b2c4-d5f6-5a78-9bcd-ef1234567890/phase_1_implement_a1.yaml
$ONEX_STATE_DIR/checkpoints/{ticket_id}/e3a1b2c4-d5f6-5a78-9bcd-ef1234567890/phase_2_local_review_a1.yaml
$ONEX_STATE_DIR/checkpoints/{ticket_id}/e3a1b2c4-d5f6-5a78-9bcd-ef1234567890/phase_2_local_review_a2.yaml  # retry
$ONEX_STATE_DIR/checkpoints/{ticket_id}/e3a1b2c4-d5f6-5a78-9bcd-ef1234567890/phase_3_create_pr_a1.yaml

Note: Short run IDs (e.g., a1b2c3d4) are normalized to deterministic UUID v5 values on disk via _normalize_run_id(). The same short ID always maps to the same full UUID.

Writes are append-only: existing checkpoint files are never modified or overwritten.

Checkpoint Contract

Each checkpoint YAML file contains these fields:

Phase Ordinals

Per-Phase Payload Reference

implement

local_review

create_pr

ready_for_merge

CLI Usage

All operations use checkpoint_manager.py located at ${CLAUDE_PLUGIN_ROOT}/hooks/lib/checkpoint_manager.py.

Write a Checkpoint

python ${CLAUDE_PLUGIN_ROOT}/hooks/lib/checkpoint_manager.py write \
  --ticket-id {ticket_id} \
  --run-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --phase implement \
  --attempt 1 \
  --repo-commit-map '{"omniclaude": "a1b2c3d"}' \
  --artifact-paths '["src/foo.py", "tests/test_foo.py"]' \
  --payload '{"branch_name": "feat/{ticket_id}", "commit_sha": "a1b2c3d", "files_changed": ["src/foo.py"]}'

Output:

{
  "success": true,
  "checkpoint_path": "{ticket_id}/a1b2c3d4.../phase_1_implement_a1.yaml",
  "correlation_id": "..."
}

Read Latest Checkpoint

python ${CLAUDE_PLUGIN_ROOT}/hooks/lib/checkpoint_manager.py read \
  --ticket-id {ticket_id} \
  --run-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --phase implement

Output:

{
  "success": true,
  "correlation_id": "...",
  "checkpoint": { ... }
}

Validate a Checkpoint

Reads the checkpoint and then performs structural validation (schema version, path normalization, commit SHA format, phase-payload agreement, timestamp sanity).

python ${CLAUDE_PLUGIN_ROOT}/hooks/lib/checkpoint_manager.py validate \
  --ticket-id {ticket_id} \
  --run-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --phase implement

Output:

{
  "is_valid": true,
  "success": true,
  "errors": [],
  "warnings": [],
  "correlation_id": "...",
  "checkpoint": { ... }
}

List All Checkpoints

# All checkpoints for a ticket
python ${CLAUDE_PLUGIN_ROOT}/hooks/lib/checkpoint_manager.py list \
  --ticket-id {ticket_id}

# Scoped to a specific run
python ${CLAUDE_PLUGIN_ROOT}/hooks/lib/checkpoint_manager.py list \
  --ticket-id {ticket_id} \
  --run-id a1b2c3d4-e5f6-7890-abcd-ef1234567890

Output:

{
  "success": true,
  "count": 3,
  "checkpoints": [ ... ],
  "correlation_id": "..."
}

Integration with ticket-pipeline

The ticket-pipeline skill writes checkpoints after each phase completes and validates them during --skip-to resume. See plugins/onex/skills/ticket-pipeline/prompt.md for the integration details.

Error Handling

• omnibase_infra not installed: CLI prints JSON error and exits with code 1
• Invalid phase name: CLI prints JSON error with valid phase list
• Checkpoint already exists: Handler raises error (increment attempt_number)
• Path traversal: Handler rejects ticket IDs that escape the checkpoint root
• Absolute artifact paths: Rejected by both CLI and handler validation
• Corrupt YAML files: Skipped during list, reported during read

All checkpoint operations in the pipeline context are non-blocking -- write failures log a warning but do not stop the pipeline.

Cron-Closeout Checkpoint Protocol

The headless cron-closeout pattern (scripts/cron-closeout.sh) uses a separate, simpler checkpoint file for cross-invocation state persistence. This is distinct from the per-ticket pipeline checkpoints above.

Storage

$ONEX_STATE_DIR/pipeline_checkpoints/cron-closeout-state.yaml
$ONEX_STATE_DIR/pipeline_checkpoints/cron-closeout.lock

Checkpoint Schema

schema_version: "1.0.0"
pass_count: 5                          # Total completed passes
last_status: success                   # success | noop | failure | halt | unknown
last_run_at: 2026-03-28T22:00:00Z     # UTC timestamp of last completion
consecutive_failures: 0                # Reset to 0 on success/noop; +1 on failure/halt
dry_run: false                         # Whether last pass used --dry-run

Lock File

The lock file prevents concurrent cron invocations from overlapping. It contains:

pid: 12345
started_at: 2026-03-28T22:00:00Z

Lock timeout is 45 minutes (matching the autopilot cycle mutex). A new invocation finding a lock older than 45 minutes treats it as stale and removes it.

Circuit Breaker

3 consecutive failures (status failure or halt) prevent further invocations. To reset: edit consecutive_failures in the checkpoint file to 0, or delete the checkpoint file entirely.

Relationship to Pipeline Checkpoints

See Also

• ticket-pipeline skill (writes checkpoints after each phase)
• local-review skill (writes checkpoints after each iteration when --checkpoint is provided)
• omnibase_infra checkpoint nodes (infrastructure implementation)
• scripts/cron-closeout.sh (headless cron pattern)