Merge branch 'master' into feat/issue-643-request-preview-initiate
This commit is contained in:
@@ -0,0 +1,53 @@
|
||||
# MCP restart classes and blast-radius permissions (#663)
|
||||
|
||||
This is the machine-enforced class matrix used by
|
||||
`restart_coordinator.RESTART_CLASS_POLICIES`. It implements the narrower-first
|
||||
recovery ladder from #655 and the authorization policy from #656, using the
|
||||
path inventory from #657 and the impact coordinator from #658. Product and
|
||||
delivery lineage: vision #652 and roadmap #653.
|
||||
|
||||
Unknown class names are denied. The coordinator requires both the class
|
||||
permission and an eligible request role. Approval gates are additional: a
|
||||
caller cannot turn a request permission into execution authority.
|
||||
|
||||
| Restart class | Required permission | Expected blast radius | Drain requirement | Approval requirement | Audit requirement | Recovery behavior |
|
||||
|---|---|---|---|---|---|---|
|
||||
| `client_reconnect` | `mcp.reconnect.client` | none | none | self service | class, actor, client namespace, reason, outcome | Reconnect only the caller's client transport. No daemon or peer work changes. |
|
||||
| `session_reconnect` | `mcp.reconnect.session` | low | requesting-session safe point | self service | class, actor, session, reason, outcome | Rebind identity, capability, and workspace state for one session. |
|
||||
| `worker_restart` | `mcp.restart.worker.request` | low | target worker | controller approval + automated gates | class, actor, worker, approval, scoped drain, outcome | Restart one worker after its own leases and mutations drain. |
|
||||
| `role_runtime_restart` | `mcp.restart.role_runtime.request` | medium | target role runtime | controller approval + automated gates | class, actor, role namespace, approval, scoped drain, outcome | Restart and re-probe one role runtime; unrelated roles remain available. |
|
||||
| `connector_restart` | `mcp.restart.connector.request` | medium | target connector | controller approval + automated gates | class, actor, connector, approval, scoped drain, outcome | Restart one connector while unrelated runtimes remain available. |
|
||||
| `configuration_reload` | `mcp.reload.configuration.request` | low | mutation quiesce | controller approval + automated gates | class, actor, configuration revision, approval, outcome | Gracefully reload configuration without replacing the daemon. |
|
||||
| `rolling_mcp_restart` | `mcp.restart.rolling.request` | medium | one instance at a time | controller approval + automated gates | class, actor, instance order, approval, per-instance drains, outcome | Drain, restart, verify, and restore each instance before advancing. |
|
||||
| `full_mcp_restart` | `mcp.restart.full.request` | high | all sessions and mutations | controller approval + automated gates | class, actor, full impact, approval, full drain proof, outcome | Replace the complete MCP runtime only after a verified full drain. |
|
||||
| `host_restart` | `mcp.restart.host.request` | high | all host work | controller approval + infrastructure operator | class, actor, host/change or incident id, approval, full drain proof, outcome | Hand off to infrastructure ownership and reconcile every runtime afterward. |
|
||||
|
||||
## Drain boundary
|
||||
|
||||
Only `full_mcp_restart` and `host_restart` set `full_drain_required=true`.
|
||||
Reconnects and configuration reloads do not disrupt peer sessions. Worker,
|
||||
role-runtime, and connector restarts evaluate only their explicitly named
|
||||
target. Rolling restart drains one instance at a time. Missing required target
|
||||
scope denies the request rather than silently widening it to a full restart.
|
||||
|
||||
## Permission and approval boundary
|
||||
|
||||
Author, reviewer, merger, and reconciler roles may self-request reconnects and
|
||||
request scoped worker/role/connector/reload recovery. They cannot request
|
||||
rolling, full, or host restart classes. Controller/operator/admin roles may
|
||||
request the broader classes, while execution remains operator/admin-owned.
|
||||
Controller approval is independently required for every class above a session
|
||||
reconnect. Host restart additionally requires infrastructure-operator proof.
|
||||
|
||||
The MCP request tool derives class permissions from its authenticated runtime
|
||||
role. It does not accept caller-supplied permissions. Controller and operator
|
||||
authorization are read from the already-running daemon environment, never
|
||||
from a request argument.
|
||||
|
||||
## Audit and failure behavior
|
||||
|
||||
Every impact audit and every console restart/reload audit includes a
|
||||
`restart_class` field. The impact audit also includes the exact
|
||||
`required_permission`. Unknown classes, missing permissions, ineligible roles,
|
||||
missing approval, missing scoped targets, and incomplete inventory all deny
|
||||
fail closed. Manual process kills remain forbidden and contaminating (#630).
|
||||
@@ -6,11 +6,23 @@ 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
|
||||
This lands the coordinator + impact DTO + the 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.
|
||||
restart/reload/kill paths).
|
||||
|
||||
The **drain-proof hard gate now executes inside this tool** (#661, via PR #882):
|
||||
an apply request (`dry_run=False`) is evaluated against a drain proof here and
|
||||
denied when that proof is missing, expired, unclean, tampered with, or stale.
|
||||
It is no longer a separate child operation. What remains a later child is only
|
||||
the **execution** step — actually stopping and restoring a process. This tool
|
||||
still never restarts anything: `apply_supported` is always `false` and
|
||||
`restart_performed` is always `false`.
|
||||
|
||||
The coordinator now routes every request through the restart-class policy
|
||||
matrix defined for #663. See
|
||||
[`mcp-restart-classes.md`](./mcp-restart-classes.md) for permissions, expected
|
||||
blast radius, scoped drain and approval requirements, audit fields, and
|
||||
recovery behavior for all nine classes.
|
||||
|
||||
## Components
|
||||
|
||||
@@ -19,7 +31,8 @@ scope here.
|
||||
| `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. |
|
||||
| `gitea_request_mcp_restart` | `gitea_mcp_server.py` | MCP tool: gathers inventory from the #613 DB, calls the coordinator, returns the report, and on `dry_run=False` runs the #661 drain-proof hard gate. Never restarts a process. |
|
||||
| `drain_proof.gate_apply_restart` | `drain_proof.py` | The #661 hard gate: verifies a drain proof against the current impact fingerprint, or records an authorized break-glass bypass. |
|
||||
|
||||
## Dimensions evaluated
|
||||
|
||||
@@ -77,17 +90,61 @@ authorization is present.
|
||||
```text
|
||||
gitea_request_mcp_restart(remote, host, org, repo,
|
||||
dry_run=True, request_override=False,
|
||||
session_id=None, limit=200)
|
||||
session_id=None, limit=200,
|
||||
restart_class="full_mcp_restart",
|
||||
target_session_id=None, target_role=None,
|
||||
target_connector=None,
|
||||
drain_proof_json=None,
|
||||
request_break_glass=False)
|
||||
```
|
||||
|
||||
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).
|
||||
It **never restarts anything**: `apply_supported` is always `false` and
|
||||
`restart_performed` is always `false`.
|
||||
|
||||
### Dry-run versus apply
|
||||
|
||||
| Call | Behavior |
|
||||
|------|----------|
|
||||
| `dry_run=True` (default) | Read-only impact preview. No drain proof is required or consulted. |
|
||||
| `dry_run=False` | The #661 drain-proof hard gate runs **in this tool**. The outcome is reported under `apply_gate` / `apply_authorized`; a denial also returns a durable `incident` descriptor. Still no restart. |
|
||||
|
||||
### Authorization ordering
|
||||
|
||||
An apply requires **both** authorizations, and they are independent:
|
||||
|
||||
1. **Restart-class authorization** (#663) — the requester's role and permissions
|
||||
must allow the requested class, the class's approval requirement must be
|
||||
satisfied, and any target-scoped class must name its target. Failing any of
|
||||
these makes `allow_restart` `false`.
|
||||
2. **Drain-proof gate** (#661) — a valid, unexpired, clean proof bound to the
|
||||
current impact fingerprint, or an authorized break-glass.
|
||||
|
||||
`apply_authorized` is the conjunction: `gate.allow and allow_restart`. A clean
|
||||
drain proof therefore cannot override a class or requester-role denial, and a
|
||||
denied class never reports an authorized apply. `apply_gate` carries
|
||||
`drain_gate_allow` and `restart_class_authorized` so a denial is attributable to
|
||||
the authorization that produced it.
|
||||
|
||||
### Break-glass
|
||||
|
||||
Break-glass bypasses the **drain proof only** — never the restart-class matrix.
|
||||
It is honoured solely when `request_break_glass` is set *and* the environment
|
||||
carries `GITEA_BREAKGLASS_RESTART_AUTHORIZATION`; like operator override, the
|
||||
tool argument expresses caller intent and cannot be self-asserted by a worker
|
||||
session. `break_glass_requested` and `break_glass_authorized` are both reported,
|
||||
so a bypass is never silent.
|
||||
|
||||
### Fail closed on apply
|
||||
|
||||
A missing, malformed, expired, unclean, tampered, or fingerprint-stale drain
|
||||
proof denies the apply and returns an `incident` descriptor. An unknown restart
|
||||
class denies before any of this. Ambiguity always denies.
|
||||
|
||||
## Audit
|
||||
|
||||
Every evaluation carries an `audit_record` (event, coordinator version, verdict,
|
||||
allow decision, blast radius, counts, timestamp) so restart decisions are
|
||||
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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user