Implement durable MCP session checkpoint schema #660

New Issue

2026-07-10T15:31:36-05:00

jcwalker3 commented

2026-07-10 15:31:36 -05:00

Problem statement

Essential workflow state often lives only in MCP process memory or chat. Restarts lose session identity, stage, leases, and next actions—forcing human reconstruction.

Operational impact

Orphaned leases, duplicate work, no canonical resume; violates #628 autonomous handoff goals.

Scope

Durable checkpoint records including where applicable:

Session / runtime / LLM-provider identity · role · project/repo · issue/PR · worktree · branch/commit · capabilities · lease/lock ownership · workflow stage · last completed action · current/pending operation · pending mutation · evidence · blocker · next valid action · recovery instructions · timestamp/version

Write on stage transitions and pre-drain; post-start reconcile vs live Gitea/Git—never blind restore. Integrate with #559 lessons if applicable.

Non-goals

Full conversation transcript storage.
Secrets in checkpoints.

Required implementation investigation

control_plane_db; mcp_session_state; issue locks; PR leases; #559; #628; #655.

Proposed implementation direction

Versioned SessionCheckpoint table/file + writer API; redaction; reconcile on boot.

Security / workflow-safety

Redact tokens; RBAC for read; fail closed if checkpoint incomplete during drain.

Failure behavior

Checkpoint write failure → block drain completion.

Acceptance criteria

Schema documented and versioned.
Checkpoints written for multi-role session fixtures.
Reconcile detects stale head/lease mismatch.
No secrets in stored records (tests).
Links #652 #653 #655.

Required tests

Schema/redaction/reconcile unit tests.

Observability and audit

Checkpoint write/read metrics; errors durable.

Dependencies

Parent #655 · Soft-depends #659 · Vision #652 · Roadmap #653 · Related #559 Enforce autonomous canonical handoffs and dependency-aware concurrent task orchestration (#628)

Rollout

Write-only first; enforce completeness at drain gate.

Canonical issue state

STATE: ready-for-author
WHO_IS_NEXT: author
NEXT_ACTION: Implement checkpoint schema + writer + reconcile
NEXT_PROMPT: Author checkpoints under #655; PR; stop

Required proof

Schema + code + tests.

Required final response and handoff

Brief PR → reviewer.

## Problem statement Essential workflow state often lives only in MCP process memory or chat. Restarts lose session identity, stage, leases, and next actions—forcing human reconstruction. ## Operational impact Orphaned leases, duplicate work, no canonical resume; violates #628 autonomous handoff goals. ## Scope Durable checkpoint records including where applicable: * Session / runtime / LLM-provider identity · role · project/repo · issue/PR · worktree · branch/commit · capabilities · lease/lock ownership · workflow stage · last completed action · current/pending operation · pending mutation · evidence · blocker · next valid action · recovery instructions · timestamp/version Write on stage transitions and pre-drain; post-start reconcile vs live Gitea/Git—never blind restore. Integrate with #559 lessons if applicable. ## Non-goals * Full conversation transcript storage. * Secrets in checkpoints. ## Required implementation investigation control_plane_db; mcp_session_state; issue locks; PR leases; #559; #628; #655. ## Proposed implementation direction Versioned `SessionCheckpoint` table/file + writer API; redaction; reconcile on boot. ## Security / workflow-safety Redact tokens; RBAC for read; fail closed if checkpoint incomplete during drain. ## Failure behavior Checkpoint write failure → block drain completion. ## Acceptance criteria 1. Schema documented and versioned. 2. Checkpoints written for multi-role session fixtures. 3. Reconcile detects stale head/lease mismatch. 4. No secrets in stored records (tests). 5. Links #652 #653 #655. ## Required tests Schema/redaction/reconcile unit tests. ## Observability and audit Checkpoint write/read metrics; errors durable. ## Dependencies * Parent **#655** · Soft-depends **#659** · Vision **#652** · Roadmap **#653** · Related #559 #628 ## Rollout Write-only first; enforce completeness at drain gate. ## Canonical issue state ```text STATE: ready-for-author WHO_IS_NEXT: author NEXT_ACTION: Implement checkpoint schema + writer + reconcile NEXT_PROMPT: Author checkpoints under #655; PR; stop ``` ## Required proof Schema + code + tests. ## Required final response and handoff Brief PR → reviewer.