MCP restart coordinator and impact analysis (#658)

Before any sanctioned MCP restart, a central coordinator evaluates the live control-plane state and produces an impact preview so operators and the web console (#642 / #652) can see the blast radius before concurrent LLM work is disrupted. Uncoordinated restarts destroy in-flight author/reviewer/merger work and give operators no way to see what they are about to break.

This lands the coordinator + impact DTO + a dry-run MCP tool. It is the single sanctioned entry point for restart evaluation post-#657 (which inventoried the restart/reload/kill paths). The mutative apply path — actually performing a restart — is a later child gated by a drain proof and is explicitly out of scope here.

The coordinator now routes every request through the restart-class policy matrix defined for #663. See mcp-restart-classes.md for permissions, expected blast radius, scoped drain and approval requirements, audit fields, and recovery behavior for all nine classes.

Components

Piece	Where	Responsibility
`restart_coordinator.evaluate_restart_impact`	`restart_coordinator.py`	Pure classification: inventory → impact report DTO. No I/O, no restart.
`RestartImpactReport` / `SessionImpact` / `LeaseImpact`	`restart_coordinator.py`	Console-facing DTO (`.as_dict()` is JSON-serializable).
`ControlPlaneDB.list_sessions`	`control_plane_db.py`	Read-only session inventory (the process-level unit a restart kills).
`gitea_request_mcp_restart`	`gitea_mcp_server.py`	MCP tool: gathers inventory from the #613 DB, calls the coordinator, returns the report. Dry-run only.

Dimensions evaluated

The coordinator classifies the inventory across the dimensions #658 requires:

Sessions — every active MCP session; a restart terminates all of them. Liveness = status == active and the owner pid is alive and the heartbeat is fresh (default window 15 min). Dead/stale sessions do not count toward blast radius.
Leases / locks — control-plane leases joined with work items and their freshness (lease_lifecycle.classify_lease_freshness). Only active (live owner) leases are disruptive; expired / released / dead-process leases never withhold a restart.
Issue / PR work — the issues and PRs behind disruptive leases.
Mutations / critical sections — a live lease carrying an author worktree or a mutating phase (implementing, publishing, merging, …) is a critical section a restart must not sever.
Terminal (merge) lock — an active terminal lock always makes a restart unsafe.
Prior recovery attempts — narrower recovery already tried (e.g. sanctioned client reconnects) is echoed so the operator sees the escalation history.

Verdict

Exactly three verdicts, matching the acceptance criteria:

Verdict	`allow_restart`	Meaning
`safe`	`true`	No other live sessions, no live leases, no terminal lock.
`unsafe`	`false`	Live work would be disrupted and no operator override is present — or the inventory could not be completed (fail closed).
`override`	`true`	Live work present, but an operator override accepts the blast radius.

override_would_allow tells the console whether an override path exists for the current state. blast_radius is a none / low / medium / high severity band derived from the affected session and work counts.

Fail closed

If the control-plane inventory cannot be completed (DB unavailable, a listing failed), inventory_complete is false and the verdict is unsafe / deny. An incomplete evaluation must never green-light a restart.

Operator override authority

Override authority is read from the environment variable GITEA_OPERATOR_RESTART_OVERRIDE_AUTHORIZATION and never from a tool argument. A worker session cannot set an environment variable on an already-running daemon, so override cannot be self-asserted (same pattern as the #630 daemon-maintenance authorization). The request_override tool argument only expresses caller intent; it takes effect solely when the environment authorization is present.

The tool

gitea_request_mcp_restart(remote, host, org, repo,
                          dry_run=True, request_override=False,
                          session_id=None, limit=200,
                          restart_class="full_mcp_restart",
                          target_session_id=None, target_role=None,
                          target_connector=None)

Read-only, dry-run, and it never restarts anything. apply_supported is always false; passing dry_run=False performs no restart and reports that apply is gated by a drain proof (a separate child).

Audit

Every evaluation carries an audit_record (event, coordinator version, verdict, restart class, required permission, allow decision, blast radius, counts, timestamp) so restart decisions are auditable. No secrets flow through the coordinator — session ids, pids, and profiles are operational metadata only.

A representative dry-run report is in mcp-restart-impact-sample.json.

5.2 KiB Raw Blame History