Simplify per /simplify review

Three actionable findings from the parallel reuse / quality / efficiency
agents:

1. Real bug — efficiency review caught a missing wait_for_port_free in
   force_restart_server_preserving_mode's dev branch. stop_dev_server()
   issues OS.kill and returns, but the listener can take >500ms to
   release the port; start_dev_server's fixed 500ms timer then races
   the old uvicorn shutdown and the --reload spawn fails to bind.
   Mirrored the managed path's wait via _wait_for_port_free.

2. Trim doc comments restating WHAT per CLAUDE.md "default to no
   comments" — kept only the WHY (the adoption-arm trap). Drops
   ~17 lines across mcp_dock.gd and plugin.gd.

3. Extract _seed_dev_restart_btn / _cleanup_dev_restart_btn helpers
   in test_dock.gd to match the file's existing _seed_server_row /
   _cleanup_server_row pattern. Cuts boilerplate across the three
   new dispatch/state tests.

Also drops a no-op bool() cast on a value already typed bool.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dsarno

plugin/addons/godot_ai/mcp_dock.gd

@@ -174,13 +174,9 @@ var _mode_override_btn: OptionButton
 var _setup_section: VBoxContainer
 var _setup_container: VBoxContainer
 var _dev_server_btn: Button
-## Force-respawn button shown alongside `_dev_server_btn` in dev checkouts
-## when Developer mode is on. Same-version Python edits get adopted as
-## compatible (server_lifecycle.gd `start_server` adoption arm), so neither
-## the version-drift restart nor the spawn-failure restart surfaces — this
-## is the unconditional "kill whatever's there and respawn from current
-## source" affordance contributors need to pick up source changes that
-## don't bump the version.
+## Same-version Python edits get adopted as compatible, so neither the
+## drift nor the crash Restart button surfaces — this is the unconditional
+## kick contributors need to pick up source changes without a version bump.
 var _dev_restart_btn: Button
 var _log_viewer: LogViewerScript
 
@@ -1413,12 +1409,9 @@ func _on_dev_server_pressed() -> void:
 	_update_dev_restart_btn.call_deferred()
 
 
-## Pure helper — `Restart Server` is enabled whenever there's *something*
-## to restart on the HTTP port (managed server we spawned/adopted, OR an
-## external `--reload` dev server we recognize by brand). Disabled when
-## nothing is running, with a tooltip that says so. Static so the unit
-## test in `test_dock_dev_server_btn.gd` can cover the truth table without
-## a real plugin.
+## Pure helper for the Restart Server button — enabled iff something is
+## running on the HTTP port we can kick. Static so `test_dock_dev_server_btn`
+## can cover the truth table without a real plugin.
 static func _restart_server_btn_state(has_managed: bool, dev_running: bool) -> Dictionary:
 	var port := ClientConfigurator.http_port()
 	if has_managed or dev_running:
@@ -1441,13 +1434,11 @@ func _update_dev_restart_btn() -> void:
 		return
 	if _plugin == null:
 		return
-	## Same defensive guard as `_update_dev_server_btn` for the self-update
-	## mixed-state window where the dock is alive but the plugin script
-	## class is mid-reload and missing methods. See #168.
+	## See _update_dev_server_btn — same #168 self-update mixed-state guard.
 	if not (_plugin.has_method("has_managed_server") and _plugin.has_method("is_dev_server_running")):
 		return
 	var state := _restart_server_btn_state(_plugin.has_managed_server(), _plugin.is_dev_server_running())
-	_dev_restart_btn.disabled = not bool(state["enabled"])
+	_dev_restart_btn.disabled = not state["enabled"]
 	_dev_restart_btn.tooltip_text = state["tooltip"]
 
 

plugin/addons/godot_ai/plugin.gd

@@ -1413,21 +1413,23 @@ func force_restart_server() -> void:
 	_lifecycle.force_restart_server()
 
 
-## Force-respawn whichever server is currently running on this port,
-## preserving its launch mode. Managed servers go through the lifecycle's
-## kill+respawn path; `--reload` dev servers are killed by brand match and
-## relaunched with `--reload` so the user keeps Python auto-reload.
-##
-## Used by the dock's "Restart Server" button in dev mode, where same-version
-## edits to Python source get adopted as compatible and the server keeps
-## running stale code. Returns true if a restart was attempted, false if no
-## server is running on the HTTP port.
+## Same-version Python edits get adopted as compatible by the lifecycle's
+## start_server arm, so reloading or relaunching just re-adopts the stale
+## process. This is the "kill whatever's there and respawn from current
+## source" path the dock's Restart Server button hits, preserving managed
+## vs --reload mode.
 func force_restart_server_preserving_mode() -> bool:
 	if has_managed_server():
 		_lifecycle.force_restart_server()
 		return true
 	if is_dev_server_running():
 		stop_dev_server()
+		## OS.kill returns synchronously but the listener can take longer
+		## to release the port — without this wait, start_dev_server's
+		## fixed 500ms timer races the old uvicorn shutdown and the new
+		## --reload spawn fails to bind. Mirrors the managed path's wait
+		## inside _lifecycle.force_restart_server.
+		_wait_for_port_free(ClientConfigurator.http_port(), 5.0)
 		start_dev_server()
 		return true
 	return false

test_project/tests/test_dock.gd

@@ -1005,65 +1005,57 @@ func test_restart_server_btn_visibility_follows_dev_mode_toggle() -> void:
 		"dev toggle off must hide the Setup section, hiding the Restart Server button")
 
 
-func test_restart_server_btn_dispatches_to_force_restart_preserving_mode() -> void:
-	## Click handler must call `force_restart_server_preserving_mode` so the
-	## plugin picks the right kill+respawn path (managed vs --reload) for
-	## whatever's currently running.
-	var plugin := _RestartDispatchPlugin.new()
-	plugin.has_managed = true
+## Mirrors `_seed_server_row` / `_cleanup_server_row`: stand up just enough
+## of the dock for the per-frame restart-button helpers to run without a
+## full `_build_ui` pass.
+func _seed_dev_restart_btn(plugin: _RestartDispatchPlugin) -> void:
 	_dock._plugin = plugin
 	_dock._dev_restart_btn = Button.new()
 
-	_dock._on_dev_restart_pressed()
-	var calls: int = plugin.preserve_mode_calls
 
+func _cleanup_dev_restart_btn(plugin: _RestartDispatchPlugin) -> void:
 	_dock._dev_restart_btn.free()
 	_dock._dev_restart_btn = null
 	_dock._plugin = null
 	plugin.free()
 
+
+func test_restart_server_btn_dispatches_to_force_restart_preserving_mode() -> void:
+	var plugin := _RestartDispatchPlugin.new()
+	plugin.has_managed = true
+	_seed_dev_restart_btn(plugin)
+
+	_dock._on_dev_restart_pressed()
+	var calls: int = plugin.preserve_mode_calls
+
+	_cleanup_dev_restart_btn(plugin)
 	assert_eq(calls, 1,
 		"Click must call force_restart_server_preserving_mode exactly once")
 
 
 func test_restart_server_btn_disabled_when_nothing_running() -> void:
-	## Per-frame `_update_dev_restart_btn` must reflect the live plugin
-	## state. With neither managed nor dev server running, the button
-	## stays disabled with an explanatory tooltip.
 	var plugin := _RestartDispatchPlugin.new()
-	plugin.has_managed = false
-	plugin.dev_running = false
-	_dock._plugin = plugin
-	_dock._dev_restart_btn = Button.new()
+	_seed_dev_restart_btn(plugin)
 
 	_dock._update_dev_restart_btn()
 	var disabled: bool = _dock._dev_restart_btn.disabled
 	var tooltip: String = _dock._dev_restart_btn.tooltip_text
 
-	_dock._dev_restart_btn.free()
-	_dock._dev_restart_btn = null
-	_dock._plugin = null
-	plugin.free()
-
+	_cleanup_dev_restart_btn(plugin)
 	assert_true(disabled, "No server running must disable the button")
 	assert_contains(tooltip, "No godot-ai server is running")
 
 
 func test_restart_server_btn_enabled_when_managed_running() -> void:
 	var plugin := _RestartDispatchPlugin.new()
 	plugin.has_managed = true
-	_dock._plugin = plugin
-	_dock._dev_restart_btn = Button.new()
+	_seed_dev_restart_btn(plugin)
 
 	_dock._update_dev_restart_btn()
 	var disabled: bool = _dock._dev_restart_btn.disabled
 	var tooltip: String = _dock._dev_restart_btn.tooltip_text
 
-	_dock._dev_restart_btn.free()
-	_dock._dev_restart_btn = null
-	_dock._plugin = null
-	plugin.free()
-
+	_cleanup_dev_restart_btn(plugin)
 	assert_false(disabled, "Managed server running must enable the button")
 	assert_contains(tooltip, "current source",
 		"Tooltip must explain the button picks up source changes")