sysadminandClaude Opus 4.8
e8bae606cb
Implement a sanctioned session lifecycle for post-restart reconciliation so active session rows with dead or reused owner PIDs can be terminalized without deleting history. Protect live owners, live leases, and live client-managed sessions; record durable session_retired audit events; keep cleanup idempotent under concurrent reconciles. Closes #969 Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
61 lines
2.7 KiB
Markdown
61 lines
2.7 KiB
Markdown
# Post-restart MCP reconciliation (#662)
|
|
|
|
After an MCP process restart, sessions, leases, capabilities, worktrees, and
|
|
interrupted mutations must be reconciled before operators claim a clean runtime.
|
|
This document describes the #662 completion-proof path.
|
|
|
|
## Components
|
|
|
|
| Piece | Where | Responsibility |
|
|
|-------|-------|----------------|
|
|
| `post_restart_reconcile.reconcile_after_restart` | `post_restart_reconcile.py` | Pure classification: inventory → completion proof DTO. No I/O. |
|
|
| `RestartCompletionProof` | `post_restart_reconcile.py` | Machine-readable proof (`.as_dict()` is JSON-serializable). |
|
|
| `gitea_reconcile_after_restart` | `gitea_mcp_server.py` | MCP tool: gathers inventory from the #613 control-plane DB + master-parity, classifies, returns the proof. Read-only. |
|
|
| Boot hook | `gitea_assess_master_parity` | First post-restart parity probe also runs reconcile once (log-only by default). |
|
|
|
|
## Dimensions
|
|
|
|
The assessor classifies:
|
|
|
|
- **service_health** — process healthy / parity mutation-safe
|
|
- **clients** — connected client descriptors (optional inventory)
|
|
- **sessions** — active session rows with dead or reused owner pids are
|
|
unresolved until retired via `#969` (`session_lifecycle` /
|
|
`apply_session_cleanup=true` on `gitea_reconcile_after_restart`, or
|
|
`gitea_retire_stale_workflow_sessions`). Live owners, live leases, and live
|
|
client-managed sessions are never retired.
|
|
- **checkpoints** — soft-depends on #660; skipped with reason when schema absent
|
|
- **leases** — live control-plane leases after restart
|
|
- **capabilities** — master-parity / stale-runtime (#610)
|
|
- **worktrees** — lease-bound paths missing on disk
|
|
- **interrupted_mutations** — mutating lease phases or explicit pending inventory; **never auto-resumed**
|
|
- **duplicates** — multiple live claims on the same work item
|
|
- **queue** — allocator resume safety
|
|
|
|
## Modes
|
|
|
|
| Mode | Env / arg | Behavior |
|
|
|------|-----------|----------|
|
|
| `log_only` (default) | unset or `GITEA_POST_RESTART_RECONCILE_MODE=log_only` | Proof only; `mutation_hold=false` |
|
|
| `enforce` | `GITEA_POST_RESTART_RECONCILE_MODE=enforce` or `mode=enforce` | Sets `mutation_hold=true` when overall status is degraded/failed or interrupted mutations remain |
|
|
|
|
## Follow-up issues
|
|
|
|
Unresolved dimensions produce `proposed_follow_ups` entries suitable for durable
|
|
Gitea issues. The MCP tool **does not create** those issues in v1 (rollout is
|
|
log-only first). Controllers may file them from the proof payload.
|
|
|
|
## Links
|
|
|
|
- Umbrella: #655
|
|
- Vision: #652 · Roadmap: #653
|
|
- Checkpoint schema: #660 (soft dependency)
|
|
- Drain proof: #661 (soft)
|
|
- This issue: #662
|
|
|
|
## Non-goals
|
|
|
|
- HA multi-instance failover
|
|
- Automatic silent mutation replay
|
|
- Implementing the #660 checkpoint schema itself
|