session-state

Session State Management

Overview

OCR uses **SQLite** as the primary state store for reliable progress tracking. The database is located at `.ocr/data/ocr.db` and is managed through the `ocr state` CLI commands. Agents use these CLI commands at each phase transition instead of writing state files directly.

Cross-Mode Compatibility

Sessions are **always** stored in the project's `.ocr/data/ocr.db` database and mirrored to `.ocr/sessions/`, regardless of installation mode:

| Mode | Skills Location | State Store | Sessions Mirror | |------|-----------------|-------------|-----------------| | **CLI** | `.ocr/skills/` | `.ocr/data/ocr.db` | `.ocr/sessions/` | | **Plugin** | Plugin cache | `.ocr/data/ocr.db` | `.ocr/sessions/` |

This means:

• The `ocr progress` CLI works identically in both modes
• Running `npx @open-code-review/cli progress` from any project picks up the session state
• No configuration needed — the CLI always reads from `.ocr/data/ocr.db`

State Data Model

The following fields are tracked per session in SQLite:

{
  "session_id": "{session-id}",
  "workflow_type": "review",
  "status": "active",
  "current_phase": "reviews",
  "phase_number": 4,
  "current_round": 1,
  "current_map_run": 1,
  "started_at": "{ISO-8601-TIMESTAMP}",
  "round_started_at": "{ISO-8601-TIMESTAMP}",
  "map_started_at": "{ISO-8601-TIMESTAMP}",
  "updated_at": "{ISO-8601-TIMESTAMP}"
}

**Minimal by design**: Round and map run metadata is derived from the filesystem, not stored in the database.

**Field descriptions**:

• `workflow_type`: Current workflow type (`"review"` or `"map"`) — enables `ocr progress` to track correct workflow
• `started_at`: When the session was created (first `/ocr-review` or `/ocr-map`)
• `round_started_at`: When the current review round began (set when starting round ≥ 1)
• `map_started_at`: When the current map run began (set when starting a map run)
• `current_map_run`: Current map run number (only present during map workflow)
• `updated_at`: Last modification time (updated at every phase transition)

**Derived from filesystem** (not stored):

• Round count: enumerate `rounds/round-*/` directories
• Round completion: check for `final.md` in round directory
• Reviewers in round: list files in `rounds/round-{n}/reviews/`
• Discourse complete: check for `discourse.md` in round directory
• Map run count: enumerate `map/runs/run-*/` directories
• Map run completion: check for `map.md` in run directory

Orchestration Events Table

In addition to the session state, SQLite tracks an **orchestration events timeline** in the `orchestration_events` table. Each `ocr state advance` call automatically logs an event, providing a complete history of phase transitions with timestamps. This enables:

• Post-session analytics (time spent per phase)
• Debugging stalled reviews
• Progress timeline reconstruction

Events are stored with the session ID, phase name, phase number, and timestamp.

Session Status

The `status` field controls session visibility:

| Status | Meaning | Progress CLI | Agent Resume | |--------|---------|--------------|---------------| | `active` | In progress | Shows in auto-detect | Can resume | | `closed` | Complete and dismissed | Skipped | Cannot resume |

**Lifecycle:** 1. Session created via `ocr state begin` → `status: "active"` 2. Review in progress → `status: "active"`, `current_phase` updates via `ocr state advance` 3. Phase 8 complete → `ocr state finish` sets `status: "closed"`, `current_phase: "complete"`

The `ocr progress` command only auto-detects sessions with `status: "active"`. Closed sessions are accessible via `/ocr-history` and `/ocr-show`.

Agent-session journal: the `kind` field

Each journaled process (`ocr session list --json`, the dashboard's `/api/agent-sessions`) carries a typed **`kind`** — branch on it instead of parsing the `command` string to tell what a process is:

| `kind` | Meaning | |--------|---------| | `supervisor` | A workflow-owning process (a dashboard-spawned `review`/`map`). Its death cascade-closes its dependents. | | `instance` | A reviewer instance journaled via `ocr session start-instance`. Never owns a workflow's lifecycle. | | `utility` | A fire-and-forget command with no journaled heartbeat. |

CLI Commands for State Management

Agents MUST use these CLI commands to manage session state. **Do NOT write state files directly.**

> **Note**: These commands require the OCR CLI. Install globally with `npm install -g @open-code-review/cli` or prefix with `npx @open-code-review/cli`.

Atomic state API (preferred)

As of v2.0 the CLI exposes a small set of **atomic, invariant-checked** verbs. Prefer these — they make correct state updates the default and make incorrect ones impossible:

| Verb | Use it to | Guarantee | |------|-----------|-----------| | `ocr state begin` | start or resume a workflow | returns `{session_id, round, phase, completeness}` | | `ocr state advance --phase <name>` | mark you've reached a phase | graph-validated; rejects illegal jumps; phase number derived | | `ocr state complete-round --stdin` | finalize a review round | **one transaction**: writes meta + `round_completed` + advances + transitions to `complete`. Refuses unless you've reached `synthesis`. Idempotent. | | `ocr state complete-map --stdin` | finalize a map run | map analogue | | `ocr state finish [--abort]` | close the workflow | **refuses** unless the current round/run is complete; `--abort` records an abandoned session | | `ocr state status --json` | ask "is it done? what's missing?" | machine-readable completeness + `next_action` |

**The CLI now enforces the lifecycle.** `ocr state finish` will *refuse* (exit code 6) to close a workflow whose current round/run has no `round_completed`/`map_completed`. This is by design — it makes the "completed too soon" failure impossible. If you genuinely need to abandon a workflow, use `ocr state finish --abort`.

**Exit codes** (branch on these instead of