Define MCP restart governance and authorization policy #656

New Issue

2026-07-10T15:30:41-05:00

jcwalker3 commented

2026-07-10 15:30:41 -05:00

Problem statement

There is no durable written policy stating who may restart MCP, under what conditions, that restart is last resort, and how controller approval / quorum / break-glass interact.

Operational impact

Operators and LLMs invent restart behavior; concurrent work is unsafe; #630/#642 lack policy backbone.

Scope

Policy doc: last-resort ladder (reconnect → refresh → scoped restart → full restart → host).
Authorization matrix by role (author/reviewer/merger/reconciler/controller/operator/admin).
Approved conditions: no affected sessions; full drain ack; controller+gates; quorum (if any); break-glass.
Decision: v1 = controller approval + automated safety gates unless investigation proves quorum is required day-one.
Explicit forbid: unilateral LLM/operator full restart with active peers.
Link dogfooding requirement for Gitea-Tools itself.

Non-goals

Implement coordinator code (later children).
Implement HA multi-instance.

Required implementation investigation

#655 umbrella; gitea_mcp_server.py auto-restart; #591/#584/#630/#642; profiles; #652/#653; control-plane guide rules on restart.

Proposed implementation direction

docs/architecture/mcp-restart-governance.md + reference from safety-model and webui deployment docs; policy IDs for enforcement code.

Security requirements

Privileged roles only for full restart; break-glass separate; audit mandate for all approvals.

Workflow-safety requirements

Restart never bypasses mutation gates mid-critical-section; drain before restart is mandatory except break-glass with incident.

Failure behavior

Ambiguous policy → deny restart.

Acceptance criteria

Policy document merged (or PR) with authorization matrix and v1 decision recorded.
States restart is last resort with enumerated narrower recoveries.
Forbids unilateral LLM full restart with affected sessions.
Break-glass conditions listed.
Linked from #655, #652, #653, #630, #642.

Required tests

Doc/link checks if available; policy ID constants tests when enforcement lands.

Observability and audit requirements

Policy version field for future audit events.

Dependencies and linkage

Parent: #655 · Vision: #652 · Roadmap: #653 · Related: #630, #642, Auto-restart Gitea MCP namespaces when master advances (#591)
Blocks: coordinator, break-glass, console approval UX

Rollout / migration

Publish policy before enabling any new restart tool; existing auto-restart must be inventoried (#656+).

Canonical issue state

STATE: ready-for-author
WHO_IS_NEXT: author
NEXT_ACTION: Write governance policy ADR/doc; open PR; stop
NEXT_PROMPT: Author implements #N policy only under #655; link #652 #653; PR; no code restarts

Required proof

PR with policy doc + cross-links.

Required final response and handoff

Brief PR → reviewer/controller for policy approval.

## Problem statement There is no durable written policy stating who may restart MCP, under what conditions, that restart is last resort, and how controller approval / quorum / break-glass interact. ## Operational impact Operators and LLMs invent restart behavior; concurrent work is unsafe; #630/#642 lack policy backbone. ## Scope * Policy doc: last-resort ladder (reconnect → refresh → scoped restart → full restart → host). * Authorization matrix by role (author/reviewer/merger/reconciler/controller/operator/admin). * Approved conditions: no affected sessions; full drain ack; controller+gates; quorum (if any); break-glass. * Decision: **v1 = controller approval + automated safety gates** unless investigation proves quorum is required day-one. * Explicit forbid: unilateral LLM/operator full restart with active peers. * Link dogfooding requirement for Gitea-Tools itself. ## Non-goals * Implement coordinator code (later children). * Implement HA multi-instance. ## Required implementation investigation #655 umbrella; `gitea_mcp_server.py` auto-restart; #591/#584/#630/#642; profiles; #652/#653; control-plane guide rules on restart. ## Proposed implementation direction `docs/architecture/mcp-restart-governance.md` + reference from safety-model and webui deployment docs; policy IDs for enforcement code. ## Security requirements Privileged roles only for full restart; break-glass separate; audit mandate for all approvals. ## Workflow-safety requirements Restart never bypasses mutation gates mid-critical-section; drain before restart is mandatory except break-glass with incident. ## Failure behavior Ambiguous policy → deny restart. ## Acceptance criteria 1. Policy document merged (or PR) with authorization matrix and v1 decision recorded. 2. States restart is last resort with enumerated narrower recoveries. 3. Forbids unilateral LLM full restart with affected sessions. 4. Break-glass conditions listed. 5. Linked from #655, #652, #653, #630, #642. ## Required tests Doc/link checks if available; policy ID constants tests when enforcement lands. ## Observability and audit requirements Policy version field for future audit events. ## Dependencies and linkage * Parent: **#655** · Vision: **#652** · Roadmap: **#653** · Related: #630, #642, #591 * Blocks: coordinator, break-glass, console approval UX ## Rollout / migration Publish policy before enabling any new restart tool; existing auto-restart must be inventoried (#656+). ## Canonical issue state ```text STATE: ready-for-author WHO_IS_NEXT: author NEXT_ACTION: Write governance policy ADR/doc; open PR; stop NEXT_PROMPT: Author implements #N policy only under #655; link #652 #653; PR; no code restarts ``` ## Required proof PR with policy doc + cross-links. ## Required final response and handoff Brief PR → reviewer/controller for policy approval.