Add stop-wm command to shut down the shared workspace server

The CLI could start a shared workspace server (start-wm-server
--detach --keep-alive) and recover it (restart-wm and friends), but had
no counterpart to stop it. A keep-alive server outlives its clients by
design, so the only way to end one was to kill the process by hand.

- Add `stop-wm` alongside the other recovery commands. Like them it
  requires --shared-server: stopping a private per-command server would
  report success while leaving the workspace an editor or agent uses
  untouched.
- Refuse with RecoveryFailed when no server is running, naming how to
  start one, rather than reporting a stop that did nothing.
- Send server/shutdown through the new ApiClient.shutdown and tolerate
  the server closing the socket before the response is read, as
  replace_running_server already does; the wait that follows verifies
  the stop.
- Add wm_lifecycle.wait_until_stopped, which polls running_port in a
  thread (its synchronous probe blocks for the full timeout on a
  filtered port) and fails with a timeout naming the port.
- Document the command in docs/cli.md and update "all four" to "all
  five".

Author: Aksem

docs/cli.md

@@ -272,8 +272,9 @@ narrowest one that covers what you edited, because nothing detects staleness for
 | `restart-runner` | any code a runner imported, and stuck or crashed runners | configuration |
 | `reload-config` | `pyproject.toml`, `finecode.toml` and presets — and, since it replaces runners, all code too | FineCode's own source |
 | `restart-wm` | everything, including FineCode's own source | — |
+| `stop-wm` | nothing — it stops the workspace | restart — pair with `start-wm-server --detach --keep-alive` |
 
-**All four require `--shared-server`.** Without it each command would start a
+**All five require `--shared-server`.** Without it each command would start a
 workspace server of its own, recover that, and exit — leaving the workspace an editor
 or agent is actually using untouched while reporting success. They exit with status 1
 and name the mode as the reason.
@@ -299,6 +300,9 @@ python -m finecode reload-config --shared-server --all-projects --rescan
 
 # after editing FineCode itself
 python -m finecode restart-wm --shared-server
+
+# stop the shared workspace server
+python -m finecode stop-wm --shared-server
 ```
 
 ## Dev environment detection
@@ -441,6 +445,9 @@ whatever owns that lifetime — a container start script, a systemd unit, a supe
 python -m finecode start-wm-server --detach --keep-alive
 ```
 
+Its counterpart is `python -m finecode stop-wm --shared-server`, which shuts that
+server back down.
+
 Keep-alive has no environment variable and is never inherited: it is passed
 explicitly by whoever starts the server, so the dedicated per-command servers cannot
 pick it up and stop stopping. The flip side is that a server started *lazily* by a

src/finecode/cli.py

@@ -9,6 +9,7 @@
     restart_runner,
     restart_wm,
     run,
+    stop_wm,
     version,
 )
 from finecode.lsp_server.cli import start_lsp
@@ -31,6 +32,7 @@ def cli(): ...
 cli.add_command(restart_runner)
 cli.add_command(reload_config)
 cli.add_command(restart_wm)
+cli.add_command(stop_wm)
 cli.add_command(version)
 
 

src/finecode/cli_app/cli.py

@@ -1077,6 +1077,19 @@ def restart_wm(log_level: str, shared_server: bool):
     )
 
 
+@click.command()
+@_LOG_LEVEL_OPTION
+@click.option("--shared-server", "shared_server", is_flag=True, default=False)
+def stop_wm(log_level: str, shared_server: bool):
+    """Stop the shared workspace server."""
+    from finecode.cli_app.commands import recover_cmd
+
+    _run_recovery(
+        lambda cwd: recover_cmd.stop_wm(workdir_path=cwd, own_server=not shared_server),
+        log_level,
+    )
+
+
 @click.command()
 @_LOG_LEVEL_OPTION
 @click.option("--shared-server", "shared_server", is_flag=True, default=False)

src/finecode/cli_app/commands/recover_cmd.py

@@ -1,5 +1,6 @@
 # docs: docs/cli.md
-"""Recovery commands: make a running workspace pick up what changed on disk.
+"""Recovery and stop commands: make a running workspace pick up what changed on disk,
+or stop the workspace.
 
 Every one of them requires ``--shared-server``. Recovery only means something to
 a workspace someone else is already using: starting a private server, recovering
@@ -176,3 +177,34 @@ async def restart_wm(workdir_path: pathlib.Path, own_server: bool = True) -> Non
             "otherClientsDisconnected": other_clients,
         }
     )
+
+
+async def stop_wm(
+    workdir_path: pathlib.Path, own_server: bool = True, timeout: float = 30
+) -> None:
+    require_shared_server(own_server, "stop-wm")
+    previous_port = await asyncio.to_thread(wm_lifecycle.running_port)
+    if previous_port is None:
+        raise RecoveryFailed(
+            "No FineCode workspace server is running, so there is nothing to stop. "
+            "Start one — an editor with the FineCode LSP, the MCP server, or "
+            "'python -m finecode start-wm-server' — and run this again."
+        )
+    client = await _connected_client(workdir_path)
+    try:
+        try:
+            await client.shutdown()
+        except (ConnectionError, OSError) as exception:
+            # Same as replace_running_server (wm_lifecycle.py):
+            # the server may close the socket before its response is read;
+            # it is stopping either way, which the wait below verifies.
+            logger.debug(f"WM server closed the connection on shutdown: {exception}")
+    finally:
+        await client.close()
+    try:
+        await wm_lifecycle.wait_until_stopped(timeout=timeout)
+    except TimeoutError as exception:
+        raise RecoveryFailed(
+            f"FineCode WM server on port {previous_port} did not stop within {timeout}s"
+        ) from exception
+    _report({"stopped": True, "port": previous_port})

src/finecode/wm_client.py

@@ -379,6 +379,10 @@ async def unsubscribe_logs(self) -> None:
         """Unsubscribe this connection from WM diagnostic logs."""
         await self.request("server/unsubscribeLogs", {})
 
+    async def shutdown(self) -> dict:
+        """Ask the WM server to shut down."""
+        return await self.request("server/shutdown")
+
     # -- Workspace methods --------------------------------------------------
 
     async def list_projects(self) -> list[dict]:

src/finecode/wm_server/wm_lifecycle.py

@@ -153,6 +153,19 @@ async def wait_until_ready(timeout: float = 30) -> int:
     )
 
 
+async def wait_until_stopped(timeout: float = 30) -> None:
+    """Wait until no WM server is listening. Returns None."""
+    deadline = asyncio.get_event_loop().time() + timeout
+    while asyncio.get_event_loop().time() < deadline:
+        # In a thread: `running_port` probes with a synchronous connect that
+        # takes its full timeout when the port is filtered rather than refused.
+        port = await asyncio.to_thread(running_port)
+        if port is None:
+            return
+        await asyncio.sleep(STARTUP_READY_POLL_INTERVAL_SECONDS)
+    raise TimeoutError(f"FineCode WM server did not stop within {timeout}s")
+
+
 def start_own_server(
     workdir: pathlib.Path,
     log_level: str = "INFO",