# Checkpoint

> Pipeline checkpoint management for resume, replay, and phase validation

- Skill: `omninode-ai/checkpoint` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add omninode-ai/checkpoint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/omninode-ai/checkpoint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: OmniNode-ai (https://skillmd.com/u/omninode-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/omninode-ai/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 (<TICKET>)

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: <TICKET> (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:

| Field | Type | Description |
|-------|------|-------------|
| `schema_version` | string | Forward-compatibility version (currently `"1.0.0"`) |
| `run_id` | UUID | Pipeline run correlation ID |
| `ticket_id` | string | Linear ticket identifier |
| `phase` | enum | Pipeline phase that completed |
| `timestamp_utc` | datetime | UTC timestamp of phase completion (explicitly injected) |
| `repo_commit_map` | dict[str, str] | Mapping of repo name to commit SHA |
| `artifact_paths` | tuple[str, ...] | Relative paths of output artifacts |
| `attempt_number` | int (>=1) | Monotonically increasing attempt counter |
| `phase_payload` | union | Phase-specific payload (discriminated on `phase` field) |

### Phase Ordinals

| Phase | Ordinal | Value |
|-------|---------|-------|
| Implement | 1 | `implement` |
| Local Review | 2 | `local_review` |
| Create PR | 3 | `create_pr` |
| Ready for Merge | 4 | `ready_for_merge` |

## Per-Phase Payload Reference

### implement

| Field | Type | Description |
|-------|------|-------------|
| `phase` | literal `"implement"` | Discriminator |
| `branch_name` | string | Git branch name created |
| `commit_sha` | string (7-40 hex) | HEAD commit SHA after implementation |
| `files_changed` | tuple[str, ...] | Relative paths of changed files |

### local_review

| Field | Type | Description |
|-------|------|-------------|
| `phase` | literal `"local_review"` | Discriminator |
| `iteration_count` | int (>=1) | Number of review-fix iterations |
| `issue_fingerprints` | tuple[str, ...] | Fingerprints of issues found and resolved |
| `last_clean_sha` | string (7-40 hex) | Commit SHA of the last clean state |

### create_pr

| Field | Type | Description |
|-------|------|-------------|
| `phase` | literal `"create_pr"` | Discriminator |
| `pr_url` | string | Full URL of the created PR |
| `pr_number` | int (>=1) | PR number on the remote |
| `head_sha` | string (7-40 hex) | HEAD SHA pushed to the remote |

### ready_for_merge

| Field | Type | Description |
|-------|------|-------------|
| `phase` | literal `"ready_for_merge"` | Discriminator |
| `label_applied_at` | datetime | UTC timestamp when the merge-ready label was applied |

## CLI Usage

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

### Write a Checkpoint

```bash
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:
```json
{
  "success": true,
  "checkpoint_path": "{ticket_id}/a1b2c3d4.../phase_1_implement_a1.yaml",
  "correlation_id": "..."
}
```

### Read Latest Checkpoint

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

Output:
```json
{
  "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).

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

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

### List All Checkpoints

```bash
# 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:
```json
{
  "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

```yaml
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:

```yaml
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

| Aspect | Pipeline Checkpoints | Cron-Closeout Checkpoint |
|--------|---------------------|--------------------------|
| Scope | Per-ticket, per-phase | Per-cron-loop, aggregate |
| Storage | `$ONEX_STATE_DIR/checkpoints/{ticket_id}/` | `$ONEX_STATE_DIR/pipeline_checkpoints/` |
| Schema | Full phase payloads | Simple pass/fail counter |
| Writer | `checkpoint_manager.py` | `cron-closeout.sh` |
| Purpose | Resume mid-pipeline | Track cron loop health |

## 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)