Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)
Python
Fix Admin restart recovery and graceful shutdown (#1669)
Ali Khokhar2bc642b3bc6f
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex 9ffb8b4d..1e229262 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -256,6 +256,11 @@ transcriber, `ApplicationRuntime`, `ApiServices`, and ASGI application.[runtime/asgi.py](src/free_claude_code/runtime/asgi.py) drives runtime startup andshutdown through lifespan events.+The supervised `RuntimeServer` first signals `ApplicationRuntime.begin_shutdown`.+Chat stops admitting work and finishes its observer feeds before Uvicorn drains+HTTP connections. Chat operations can still settle and publish internally;+storage and provider resources remain owned until lifespan cleanup completes.+[runtime/provider_manager.py](src/free_claude_code/runtime/provider_manager.py)alone publishes, retires, and closes provider generations. Each inference requestholds a settings/provider snapshot through a lease. Provider-only Admin Apply@@ -286,6 +291,7 @@ client executables and native client state have separate owners.Lifecycle behavior is covered by[runtime tests](tests/runtime/test_application_runtime.py),+[supervised HTTP shutdown tests](tests/cli/test_server_shutdown.py),[provider-manager tests](tests/runtime/test_provider_manager.py), and[response-stream tests](tests/api/test_response_streams.py).@@ -328,6 +334,12 @@ key. Accepted changes either replace a provider generation or follow the runtimerestart path. Configuration readiness, live provider checks, and discovery areseparate states.+Automatic restart responses identify the old runtime instance. Admin polls the+local status endpoint until a different running instance is ready, then reloads+settings and retains credential warnings. A bounded reconnect failure offers a+retry without resubmitting edits. Status allows reads from validated loopback+origins so this also works when Apply changes the server address.+Authentication is defined in[api/dependencies.py](src/free_claude_code/api/dependencies.py):diff --git a/e2e/test_admin_apply.py b/e2e/test_admin_apply.pyindex ed5d26b5..b80bb34d 100644--- a/e2e/test_admin_apply.py+++ b/e2e/test_admin_apply.py@@ -104,6 +104,7 @@ def test_unverified_warning_survives_apply("required": restart,"automatic": restart,"admin_url": "/admin",+ "instance_id": "old-server",},"credential_checks": [{@@ -115,19 +116,21 @@ def test_unverified_warning_survives_apply(}),)+ page.route(+ "**/admin/api/status",+ lambda route: route.fulfill(+ json={"status": "running", "instance_id": "new-server"}+ ),+ )page.goto(f"{admin_base_url}/admin")expect(page.locator("#messageArea")).to_have_text("")page.locator("#field-NVIDIA_NIM_API_KEY").fill("new-key")page.get_by_role("button", name="Apply", exact=True).click()expect(page.locator("#messageArea")).to_contain_text("Verification unavailable.")- if restart:- expect(- page.get_by_role("link", name="Open Admin", exact=True)- ).to_have_attribute("href", "/admin")- expect(page.locator("#applyButton")).to_be_disabled()- else:- expect(page.locator("#dirtyState")).to_have_text("No changes")- expect(page.locator("#field-NVIDIA_NIM_API_KEY")).to_be_editable()+ expect(page.locator("#dirtyState")).to_have_text("No changes")+ expect(page.locator("#field-NVIDIA_NIM_API_KEY")).to_be_editable()+ expect(page.locator("#applyButton")).to_have_text("Apply")+ expect(page.locator("#messageArea")).to_contain_text("Verification unavailable.")def test_apply_network_error_unlocks_form_and_keeps_edits(@@ -143,3 +146,147 @@ def test_apply_network_error_unlocks_form_and_keeps_edits(expect(key).to_have_value("unsaved-key")expect(key).to_be_editable()expect(page.locator("#applyButton")).to_be_enabled()+++def test_restart_waits_for_a_new_running_server(page: Page, admin_base_url: str):+ pending: list[Route] = []+ page.route("**/admin/api/status", lambda route: pending.append(route))+ page.route(+ "**/admin/api/config/apply",+ lambda route: route.fulfill(+ json={+ "applied": True,+ "restart": {+ "required": True,+ "automatic": True,+ "admin_url": "/admin",+ "fields": ["NVIDIA_NIM_API_KEY"],+ "instance_id": "old-server",+ },+ "credential_checks": [],+ }+ ),+ )+ page.goto(f"{admin_base_url}/admin")+ expect(page.locator("#messageArea")).to_have_text("")+ page.locator("#field-NVIDIA_NIM_API_KEY").fill("new-key")+ with page.expect_request("**/admin/api/status"):+ page.get_by_role("button", name="Apply", exact=True).click()+ expect(page.locator("#applyButton")).to_have_text("Reconnecting…")+ for status in (+ {"status": "running", "instance_id": "old-server"},+ {"status": "stopping", "instance_id": "new-server"},+ ):+ with page.expect_request("**/admin/api/status"):+ pending.pop(0).fulfill(json=status)+ expect(page.locator("#view-providers")).to_have_attribute("inert", "")+ expect(page.locator("#dirtyState")).to_have_text("Changes saved")+ pending.pop(0).fulfill(json={"status": "running", "instance_id": "new-server"})+ expect(page.locator("#field-NVIDIA_NIM_API_KEY")).to_be_editable()+ expect(page.locator("#dirtyState")).to_have_text("No changes")+ expect(page.locator("#messageArea")).to_have_text("Applied")+++def test_restart_timeout_can_reconnect_without_resubmitting_keys(+ page: Page, admin_base_url: str+):+ ready = False+ submissions: list[object] = []++ def apply_result(route: Route):+ submissions.append(route.request.post_data_json)+ route.fulfill(+ json={+ "applied": True,+ "restart": {+ "required": True,+ "automatic": True,+ "admin_url": "/admin",+ "fields": ["NVIDIA_NIM_API_KEY"],+ "instance_id": "old-server",+ },+ "credential_checks": [+ {+ "key": "NVIDIA_NIM_API_KEY",+ "status": "unverified",+ "message": "Verification unavailable.",+ }+ ],+ }+ )++ def status_result(route: Route):+ if ready:+ route.fulfill(json={"status": "running", "instance_id": "new-server"})+ else:+ route.abort()++ page.route("**/admin/api/config/apply", apply_result)+ page.route("**/admin/api/status", status_result)+ page.goto(f"{admin_base_url}/admin")+ expect(page.locator("#messageArea")).to_have_text("")+ page.clock.install()+ page.locator("#field-NVIDIA_NIM_API_KEY").fill("new-key")+ with page.expect_request("**/admin/api/status"):+ page.get_by_role("button", name="Apply", exact=True).click()+ expect(page.locator("#applyButton")).to_have_text("Reconnecting…")+ page.clock.fast_forward(31_000)+ page.clock.run_for(1_000)+ reconnect = page.get_by_role("button", name="Reconnect", exact=True)+ expect(reconnect).to_be_enabled()+ expect(page.locator("#messageArea")).to_contain_text("Settings were saved")+ expect(page.locator("#messageArea")).to_contain_text("Verification unavailable.")+ expect(page.locator("#view-providers")).to_have_attribute("inert", "")+ expect(page.get_by_role("link", name="Open Admin")).to_have_attribute(+ "href", f"{admin_base_url}/admin"+ )+ ready = True+ reconnect.click()+ expect(page.locator("#field-NVIDIA_NIM_API_KEY")).to_be_editable()+ expect(page.locator("#messageArea")).to_contain_text("Verification unavailable.")+ assert submissions == [{"values": {"NVIDIA_NIM_API_KEY": "new-key"}}]+++def test_restart_to_another_local_origin_keeps_the_warning(+ page: Page, admin_base_url: str+):+ target = admin_base_url.replace("127.0.0.1", "localhost") + "/admin"+ page.route(+ "**/admin/api/config/apply",+ lambda route: route.fulfill(+ json={+ "applied": True,+ "restart": {+ "required": True,+ "automatic": True,+ "admin_url": target,+ "fields": ["HOST"],+ "instance_id": "old-server",+ },+ "credential_checks": [+ {+ "key": "NVIDIA_NIM_API_KEY",+ "status": "unverified",+ "message": "Verification unavailable.",+ }+ ],+ }+ ),+ )+ page.route(+ "**/admin/api/status",+ lambda route: route.fulfill(+ headers={"Access-Control-Allow-Origin": admin_base_url},+ json={"status": "running", "instance_id": "new-server"},+ ),+ )+ page.goto(f"{admin_base_url}/admin")+ expect(page.locator("#messageArea")).to_have_text("")+ page.locator("#field-NVIDIA_NIM_API_KEY").fill("new-key")+ page.get_by_role("button", name="Apply", exact=True).click()+ page.wait_for_url(target)+ expect(page.locator("#field-NVIDIA_NIM_API_KEY")).to_be_editable()+ expect(page.locator("#messageArea")).to_contain_text("Verification unavailable.")+ assert "new-key" not in page.url+ page.reload()+ expect(page.locator("#messageArea")).to_have_text("")diff --git a/pyproject.toml b/pyproject.tomlindex 5f72706d..9d997480 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "5.21.0"+version = "5.21.1"description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"readme = "README.md"requires-python = ">=3.14.0"diff --git a/src/free_claude_code/api/admin_routes.py b/src/free_claude_code/api/admin_routes.pyindex 3b2fd9b5..fbb89588 100644--- a/src/free_claude_code/api/admin_routes.py+++ b/src/free_claude_code/api/admin_routes.py@@ -5,7 +5,14 @@ from collections.abc import Mappingfrom pathlib import Pathimport httpx-from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request+from fastapi import (+ APIRouter,+ BackgroundTasks,+ Depends,+ HTTPException,+ Request,+ Response,+)from fastapi.responses import FileResponse, HTMLResponse, JSONResponsefrom loguru import loggerfrom pydantic import BaseModel, Field@@ -122,9 +129,15 @@ async def apply_admin_config(@router.get("/admin/api/status")async def admin_status(request: Request,+ response: Response,services: ApiServices = Depends(get_services),):require_loopback_admin(request)+ # A local Admin page may reconnect after Apply changes the listening port.+ # The existing security check admits only loopback callers and origins.+ if origin := request.headers.get("origin"):+ response.headers["Access-Control-Allow-Origin"] = origin+ response.headers["Vary"] = "Origin"return services.admin.admin_status()diff --git a/src/free_claude_code/api/admin_static/admin.js b/src/free_claude_code/api/admin_static/admin.jsindex 8b91b31d..494064ba 100644--- a/src/free_claude_code/api/admin_static/admin.js+++ b/src/free_claude_code/api/admin_static/admin.js@@ -1,6 +1,7 @@const state = {config: null,applying: false,+ restart: null,fields: new Map(),modelOptions: [],modelComboboxes: new Set(),@@ -887,8 +888,8 @@ function changedValues() {function updateDirtyState() {const count = Object.keys(changedValues()).length;byId("dirtyState").textContent =- count === 0 ? "No changes" : `${count} unsaved change${count === 1 ? "" : "s"}`;- byId("applyButton").disabled = state.applying || count === 0;+ state.restart ? "Changes saved" : count === 0 ? "No changes" : `${count} unsaved change${count === 1 ? "" : "s"}`;+ byId("applyButton").disabled = state.applying || (!state.restart && count === 0);}function clearCredentialError(input) {@@ -919,15 +920,93 @@ function showCredentialErrors(checks) {function setApplying(applying) {state.applying = applying;VIEW_GROUPS.filter((view) => view.id !== "chat").forEach((view) => {- byId(`view-${view.id}`).inert = applying;+ byId(`view-${view.id}`).inert = applying || !!state.restart;});if (applying) state.modelComboboxes.forEach((combobox) => combobox.close());- byId("applyButton").textContent = applying ? "Applying…" : "Apply";+ byId("applyButton").textContent = state.restart+ ? applying ? "Reconnecting…" : "Reconnect"+ : applying ? "Applying…" : "Apply";updateDirtyState();}+async function waitForRestart(restart, target) {+ const deadline = performance.now() + 30_000;+ const statusUrl = new URL("/admin/api/status", target);+ while (performance.now() < deadline) {+ try {+ const response = await fetch(statusUrl, {+ cache: "no-store",+ credentials: "omit",+ signal: AbortSignal.timeout(1500),+ });+ if (response.ok) {+ const status = await response.json();+ if (status.status === "running" && typeof status.instance_id === "string"+ && status.instance_id !== restart.instance_id) return;+ }+ } catch {+ // Closing listeners and unfinished startup are expected during a restart.+ }+ await new Promise((resolve) => setTimeout(resolve, 250));+ }+ throw new Error("The server has not reconnected yet.");+}++function appendAdminLink(target) {+ const link = document.createElement("a");+ link.href = target.href;+ link.textContent = "Open Admin";+ byId("messageArea").append(document.createElement("br"), link);+}++async function reconnectAfterRestart() {+ const { restart, warnings } = state.restart;+ const target = new URL(restart.admin_url || "/admin", window.location.href);+ setApplying(true);+ showMessage(["Applied. Reconnecting to the server…", ...warnings].join("\n"), warnings.length ? "warn" : "ok");+ try {+ await waitForRestart(restart, target);+ if (target.origin !== window.location.origin) {+ // Carry only the safe warning text across an address change, never edits.+ target.hash = new URLSearchParams({ "fcc-applied": JSON.stringify(warnings) }).toString();+ window.location.replace(target.href);+ return;+ }+ await load();+ state.restart = null;+ showMessage(["Applied", ...warnings].join("\n"), warnings.length ? "warn" : "ok");+ } catch (error) {+ showMessage([`Settings were saved. ${error.message} Use Reconnect to try again.`, ...warnings].join("\n"), "warn");+ appendAdminLink(target);+ } finally {+ setApplying(false);+ }+}++function showRestartNotice() {+ const url = new URL(window.location.href);+ const fragment = new URLSearchParams(url.hash.slice(1));+ const notice = fragment.get("fcc-applied");+ if (notice === null) return;+ fragment.delete("fcc-applied");+ url.hash = fragment.toString();+ window.history.replaceState(window.history.state, "", url);+ try {+ const warnings = JSON.parse(notice);+ if (Array.isArray(warnings) && warnings.every((warning) => typeof warning === "string")) {+ showMessage(["Applied", ...warnings].join("\n"), warnings.length ? "warn" : "ok");+ }+ } catch {+ // A malformed navigation notice must not prevent normal Admin use.+ }+}+async function apply() {if (state.applying) return;+ if (state.restart) {+ await reconnectAfterRestart();+ return;+ }const values = changedValues();if (!Object.keys(values).length) return;const checkingKeys = Object.keys(values).some((key) => {@@ -936,7 +1015,6 @@ async function apply() {});let rejectedField = null;let applied = false;- let restarting = false;setApplying(true);showMessage(checkingKeys ? "Checking API keys…" : "Applying…");try {@@ -956,18 +1034,8 @@ async function apply() {);const restart = result.restart || {};if (restart.required && restart.automatic) {- restarting = true;- showMessage(["Applied. Restarting server…", ...warnings].join("\n"), warnings.length ? "warn" : "ok");- if (warnings.length) {- const link = document.createElement("a");- link.href = restart.admin_url || "/admin";- link.textContent = "Open Admin";- byId("messageArea").append(document.createElement("br"), link);- } else {- setTimeout(() => {- window.location.href = restart.admin_url || "/admin";- }, 1600);- }+ state.restart = { restart, warnings };+ await reconnectAfterRestart();return;}const pending = restart.required ? restart.fields || [] : result.pending_fields || [];@@ -979,8 +1047,7 @@ async function apply() {} catch (error) {showMessage(applied ? `Applied, but could not reload settings: ${error.message}` : `Could not apply settings: ${error.message}`, "error");} finally {- // Keep the old page read-only while its server restarts.- setApplying(restarting);+ setApplying(false);if (rejectedField) {navigateToView("providers");rejectedField.closest(".settings-section")?.classList.add("show-advanced");@@ -1131,6 +1198,6 @@ window.addEventListener("popstate", () => {setActiveView(viewId, { scroll: false });});-load().catch((error) => {+load().then(showRestartNotice).catch((error) => {showMessage(error.message, "error");});diff --git a/src/free_claude_code/application/chat/events.py b/src/free_claude_code/application/chat/events.pyindex c2c5c27c..feca8a4e 100644--- a/src/free_claude_code/application/chat/events.py+++ b/src/free_claude_code/application/chat/events.py@@ -111,6 +111,10 @@ class ChatEventPublisher:if self._closed:returnself._closed = True+ self.disconnect_subscribers()++ def disconnect_subscribers(self) -> None:+ """Finish observer feeds while allowing owned work to settle and publish."""subscriptions = tuple(self._subscriptions)self._subscriptions.clear()for subscription in subscriptions:diff --git a/src/free_claude_code/application/chat/service.py b/src/free_claude_code/application/chat/service.pyindex fe52031a..4d2cf64f 100644--- a/src/free_claude_code/application/chat/service.py+++ b/src/free_claude_code/application/chat/service.py@@ -201,6 +201,12 @@ class ChatService:await self._store.close()self._started = False+ def begin_shutdown(self) -> None:+ """Stop new Chat work and finish feeds before HTTP connections drain."""+ self._accepting = False+ self._unavailable_message = "Chat Sessions is stopping."+ self._events.disconnect_subscribers()+async def close(self) -> None:self._accepting = Falseasync with self._active_lock:diff --git a/src/free_claude_code/cli/commands.py b/src/free_claude_code/cli/commands.pyindex 4a16c676..587e8d87 100644--- a/src/free_claude_code/cli/commands.py+++ b/src/free_claude_code/cli/commands.py@@ -1,8 +1,10 @@"""Implementations for installed Free Claude Code commands."""+import socketimport threadingimport timeimport webbrowser+from collections.abc import Callablefrom enum import StrEnumimport uvicorn@@ -37,6 +39,20 @@ class ServerStatus(StrEnum):STOPPED = "Stopped"+class RuntimeServer(uvicorn.Server):+ """Notify the runtime before Uvicorn waits for long-lived HTTP responses."""++ def __init__(+ self, config: uvicorn.Config, *, begin_shutdown: Callable[[], None]+ ) -> None:+ super().__init__(config)+ self._begin_shutdown = begin_shutdown++ async def shutdown(self, sockets: list[socket.socket] | None = None) -> None:+ self._begin_shutdown()+ await super().shutdown(sockets)++class ServerSupervisor:"""Own one FCC server lifecycle, including config-driven restarts."""@@ -162,7 +178,7 @@ class ServerSupervisor:),timeout_graceful_shutdown=SERVER_GRACEFUL_SHUTDOWN_SECONDS,)- server = uvicorn.Server(config)+ server = RuntimeServer(config, begin_shutdown=asgi_app.runtime.begin_shutdown)with self._lock:self._server = serverif self._stop_requested or self._restart_generation != restart_generation:diff --git a/src/free_claude_code/runtime/application.py b/src/free_claude_code/runtime/application.pyindex c3d968e5..64d5a827 100644--- a/src/free_claude_code/runtime/application.py+++ b/src/free_claude_code/runtime/application.py@@ -5,6 +5,7 @@ import inspectimport loggingimport osimport traceback+import uuidfrom collections.abc import Awaitable, Callable, Mappingfrom dataclasses import replace@@ -128,6 +129,8 @@ class ApplicationRuntime:)self._cli_manager: cli_managed.ManagedClaudeSessionManager | None = Noneself._started = False+ self._instance_id = uuid.uuid4().hex+ self._draining = Falseself._closed = Falseself._provider_manager_closed = Falseself._connected_accounts_closed = False@@ -168,6 +171,12 @@ class ApplicationRuntime:await self.close()raise+ def begin_shutdown(self) -> None:+ """Finish indefinite observer responses before the server drains HTTP."""+ self._draining = True+ if self._chat_service is not None:+ self._chat_service.begin_shutdown()+async def close(self) -> bool:async with self._close_lock:if self._closed:@@ -246,7 +255,8 @@ class ApplicationRuntime:def admin_status(self) -> JsonObject:settings = self.settingsreturn {- "status": "running",+ "status": "stopping" if self._draining else "running",+ "instance_id": self._instance_id,"host": settings.host,"port": settings.port,"model": settings.model,@@ -362,12 +372,15 @@ class ApplicationRuntime:settings: Settings,) -> JsonObject:automatic = bool(fields and self._restart_callback is not None)- return {+ result: JsonObject = {"required": bool(fields),"automatic": automatic,"admin_url": local_admin_url(settings) if automatic else None,"fields": list(fields),}+ if automatic:+ result["instance_id"] = self._instance_id+ return resultasync def _start_messaging_if_configured(self) -> None:try:diff --git a/tests/api/test_admin.py b/tests/api/test_admin.pyindex 047cca6d..7c18c9fc 100644--- a/tests/api/test_admin.py+++ b/tests/api/test_admin.py@@ -1668,6 +1668,7 @@ def test_admin_apply_restart_required_reports_automatic_restart(monkeypatch, tmpcallbacks.append("restart")app = create_test_app(restart_callback=restart_callback)+ instance_id = _local_client(app).get("/admin/api/status").json()["instance_id"]response = _local_client(app).post("/admin/api/config/apply",@@ -1683,10 +1684,35 @@ def test_admin_apply_restart_required_reports_automatic_restart(monkeypatch, tmp"automatic": True,"admin_url": "http://127.0.0.1:9090/admin","fields": ["PORT"],+ "instance_id": instance_id,}assert callbacks == ["restart"][email protected]("origin", ["http://127.0.0.1:8082", "http://localhost:9090"])+def test_admin_restart_status_can_be_read_from_another_local_address(origin):+ app = create_test_app()+ response = _local_client(app).get("/admin/api/status", headers={"Origin": origin})+ assert response.status_code == 200+ assert response.headers["Access-Control-Allow-Origin"] == origin+ assert response.headers["Vary"] == "Origin"+ initial = response.json()+ assert initial["status"] == "running"+ assert isinstance(initial["instance_id"], str) and initial["instance_id"]+ runtime_for_app(app).begin_shutdown()+ stopping = _local_client(app).get("/admin/api/status").json()+ assert stopping["status"] == "stopping"+ assert stopping["instance_id"] == initial["instance_id"]+++def test_admin_restart_status_does_not_allow_a_remote_web_origin():+ response = _local_client(create_test_app()).get(+ "/admin/api/status", headers={"Origin": "https://example.com"}+ )+ assert response.status_code == 403+ assert "Access-Control-Allow-Origin" not in response.headers++def test_admin_apply_restart_required_reports_manual_fallback(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)diff --git a/tests/application/test_chat_service.py b/tests/application/test_chat_service.pyindex b37a3ce6..a69778d9 100644--- a/tests/application/test_chat_service.py+++ b/tests/application/test_chat_service.py@@ -1820,7 +1820,10 @@ async def test_cancelled_delete_request_still_finishes_accepted_deletion(@pytest.mark.asyncio-async def test_close_waits_for_terminal_settlement(tmp_path: Path, monkeypatch):[email protected]("drain_feeds", [False, True])+async def test_close_waits_for_terminal_settlement(+ tmp_path: Path, monkeypatch, drain_feeds+):service, _runtime, store = await _service(tmp_path, FakeChatProvider())release_commit = asyncio.Event()service_closed = False@@ -1846,6 +1849,17 @@ async def test_close_waits_for_terminal_settlement(tmp_path: Path, monkeypatch):)await asyncio.wait_for(entered_commit.wait(), timeout=1)+ if drain_feeds:+ service.begin_shutdown()+ service.begin_shutdown()+ assert service.availability()[0] is False+ with pytest.raises(ChatUnavailableError):+ await service.subscribe()+ with pytest.raises(StopAsyncIteration):+ await asyncio.wait_for(+ anext(stream.subscription.__aiter__()), timeout=1+ )+close_task = asyncio.create_task(service.close())await asyncio.sleep(0.05)assert not close_task.done()diff --git a/tests/cli/test_entrypoints.py b/tests/cli/test_entrypoints.pyindex ae75ccd0..e3e9ae68 100644--- a/tests/cli/test_entrypoints.py+++ b/tests/cli/test_entrypoints.py@@ -333,12 +333,14 @@ def test_serve_supervisor_restarts_when_app_requests_restart() -> None:def build_asgi_app(_settings: Settings, restart_callback: Callable[[], None]):restart_callbacks.append(restart_callback)- app = SimpleNamespace(runtime=SimpleNamespace(is_closed=False))+ app = SimpleNamespace(+ runtime=SimpleNamespace(is_closed=False, begin_shutdown=lambda: None)+ )apps.append(app)return appclass FakeServer:- def __init__(self, config):+ def __init__(self, config, *, begin_shutdown):self.config = configself.should_exit = Falseservers.append(self)@@ -355,7 +357,7 @@ def test_serve_supervisor_restarts_when_app_requests_restart() -> None:with (patch.object(commands, "get_settings", get_settings),patch.object(commands.uvicorn, "Config", side_effect=fake_config),- patch.object(commands.uvicorn, "Server", side_effect=FakeServer),+ patch.object(commands, "RuntimeServer", side_effect=FakeServer),patch.object(commands, "build_asgi_app", side_effect=build_asgi_app),patch.object(commands, "schedule_open_admin_browser") as schedule_open_admin,patch.object(commands, "clear_settings_cache") as clear_settings_cache,@@ -379,10 +381,12 @@ def test_serve_supervisor_refuses_restart_after_incomplete_shutdown() -> None:def build_asgi_app(_settings: Settings, restart_callback: Callable[[], None]):restart_callbacks.append(restart_callback)- return SimpleNamespace(runtime=SimpleNamespace(is_closed=False))+ return SimpleNamespace(+ runtime=SimpleNamespace(is_closed=False, begin_shutdown=lambda: None)+ )class FakeServer:- def __init__(self, config):+ def __init__(self, config, *, begin_shutdown):self.config = configself.should_exit = Falseservers.append(self)@@ -397,7 +401,7 @@ def test_serve_supervisor_refuses_restart_after_incomplete_shutdown() -> None:with (patch.object(commands, "get_settings", get_settings),patch.object(commands.uvicorn, "Config", side_effect=fake_config),- patch.object(commands.uvicorn, "Server", side_effect=FakeServer),+ patch.object(commands, "RuntimeServer", side_effect=FakeServer),patch.object(commands, "build_asgi_app", side_effect=build_asgi_app),patch.object(commands, "schedule_open_admin_browser"),patch.object(commands, "clear_settings_cache") as clear_settings_cache,diff --git a/tests/cli/test_server_shutdown.py b/tests/cli/test_server_shutdown.pynew file mode 100644index 00000000..92ffbef1--- /dev/null+++ b/tests/cli/test_server_shutdown.py@@ -0,0 +1,114 @@+"""Exercise supervised shutdown with real HTTP event-feed connections."""++import asyncio+import socket+import threading+from pathlib import Path+from unittest.mock import AsyncMock++import httpx+import pytest++from free_claude_code.cli import commands+from free_claude_code.config.settings import Settings+from free_claude_code.runtime.application import RestartCallback+from free_claude_code.runtime.asgi import RuntimeASGIApp+from free_claude_code.runtime.bootstrap import build_asgi_app++[email protected]("restart", [False, True])+async def test_supervisor_drains_admin_event_feed_without_forced_cancellation(+ monkeypatch: pytest.MonkeyPatch,+ tmp_path: Path,+ caplog: pytest.LogCaptureFixture,+ restart: bool,+) -> None:+ with socket.socket() as listener:+ listener.bind(("127.0.0.1", 0))+ port = listener.getsockname()[1]+ settings = Settings().model_copy(+ update={+ "host": "127.0.0.1",+ "port": port,+ "messaging_platform": "none",+ "voice_note_enabled": False,+ "open_admin_browser": False,+ "log_file": str(tmp_path / "server.log"),+ }+ )+ apps: list[RuntimeASGIApp] = []++ def create_app(settings: Settings, *, restart_callback: RestartCallback):+ app = build_asgi_app(settings, restart_callback=restart_callback)+ # Only provider discovery is external; retain the real Chat, HTTP,+ # runtime cleanup, and supervisor lifecycle under investigation.+ monkeypatch.setattr(+ app.runtime.provider_manager, "warm_referenced_model_cache", AsyncMock()+ )+ monkeypatch.setattr(+ app.runtime.provider_manager, "start_model_list_refresh", lambda: None+ )+ apps.append(app)+ return app++ monkeypatch.setattr(commands, "load_server_settings", lambda: settings)+ monkeypatch.setattr(+ "free_claude_code.runtime.bootstrap.configure_logging",+ lambda *args, **kwargs: None,+ )+ monkeypatch.setattr(commands, "build_asgi_app", create_app)+ monkeypatch.setattr(commands, "kill_all_best_effort", lambda: None)+ monkeypatch.setattr(commands, "SERVER_GRACEFUL_SHUTDOWN_SECONDS", 0.2)+ supervisor = commands.ServerSupervisor(console_logging=False)+ thread = threading.Thread(target=supervisor.run, daemon=True)+ thread.start()+ stream_error: Exception | None = None+ try:+ async with asyncio.timeout(5):+ while supervisor.status != commands.ServerStatus.RUNNING:+ assert thread.is_alive()+ await asyncio.sleep(0.01)+ async with httpx.AsyncClient(timeout=3, trust_env=False) as client:+ status_url = f"http://127.0.0.1:{port}/admin/api/status"+ old_instance = (await client.get(status_url)).json()["instance_id"]+ events_url = f"http://127.0.0.1:{port}/admin/api/chat/events"+ async with (+ client.stream("GET", events_url) as first,+ client.stream("GET", events_url) as second,+ ):+ streams = [first.aiter_lines(), second.aiter_lines()]+ assert first.status_code == second.status_code == 200+ for lines in streams:+ async for line in lines:+ if line.startswith("event: feed.ready"):+ break+ if restart:+ assert supervisor.request_restart()+ else:+ supervisor.request_stop()+ for lines in streams:+ try:+ async for _line in lines:+ pass+ except httpx.HTTPError as exc:+ stream_error = exc+ if restart:+ async with asyncio.timeout(5):+ while (+ len(apps) < 2+ or supervisor.status != commands.ServerStatus.RUNNING+ ):+ assert thread.is_alive()+ await asyncio.sleep(0.01)+ new_status = (await client.get(status_url)).json()+ assert new_status["status"] == "running"+ assert new_status["instance_id"] != old_instance+ finally:+ supervisor.request_stop()+ await asyncio.to_thread(thread.join, 5)+ assert not thread.is_alive()+ assert stream_error is None, f"Event feed was cut off: {stream_error}"+ assert "timeout graceful shutdown exceeded" not in caplog.text+ assert all(app.runtime.is_closed for app in apps)+ assert len(apps) == (2 if restart else 1)diff --git a/tests/runtime/test_application_runtime.py b/tests/runtime/test_application_runtime.pyindex 96b21a40..ab3c09ba 100644--- a/tests/runtime/test_application_runtime.py+++ b/tests/runtime/test_application_runtime.py@@ -472,6 +472,7 @@ async def test_restart_required_apply_commits_without_hot_publication(tmp_path)tmp_path,pending_fields=("PORT",),)+ instance_id = runtime.admin_status()["instance_id"]with (patch(@@ -493,6 +494,7 @@ async def test_restart_required_apply_commits_without_hot_publication(tmp_path)"automatic": True,"admin_url": "http://127.0.0.1:9090/admin","fields": ["PORT"],+ "instance_id": instance_id,}restart.assert_not_awaited()await runtime.request_restart()diff --git a/uv.lock b/uv.lockindex 3758cfa3..543db0e8 100644--- a/uv.lock+++ b/uv.lock@@ -598,7 +598,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "5.21.0"+version = "5.21.1"source = { editable = "." }dependencies = [{ name = "aiohttp" },