sysadminandClaude Opus 4.8
a7a283f449
Add pure post_restart_reconcile.reconcile_after_restart classifier with a machine-readable completion proof covering service health, sessions, leases, capabilities, worktrees, interrupted mutations (never auto-resumed), duplicates, and queue state. Soft-depends on #660 checkpoints (skipped with reason when the schema module is absent). Wire read-only MCP tool gitea_reconcile_after_restart, boot-once hook via gitea_assess_master_parity, log_only/enforce modes (mutation_hold), and docs. Closes #662 Related: #655 #652 #653 #660 #661 Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
57 lines
2.5 KiB
Markdown
57 lines
2.5 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 owner pids are unresolved
|
|
- **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
|