Add possibility to start cli commands with own server. Restore possibility to override configs in CLI commands.

Author: Aksem

docs/api-protocol.md

@@ -129,6 +129,51 @@ and starts extension runners.
 
 ---
 
+#### `workspace/setConfigOverrides`
+
+Set persistent handler config overrides on the server. Overrides are stored for
+the lifetime of the server and applied to all subsequent action runs — unlike the
+`config_overrides` field that was previously accepted by `actions/runBatch`, which
+required runners to be stopped first.
+
+- **Type:** request
+- **Clients:** CLI
+- **Status:** implemented
+
+**Params:**
+
+```json
+{
+  "overrides": {
+    "lint": {
+      "ruff": {"line_length": 120},
+      "": {"some_action_level_param": "value"}
+    }
+  }
+}
+```
+
+`overrides` format: `{action_name: {handler_name_or_"": {param: value}}}`.
+The empty-string key `""` means the override applies to all handlers of that action.
+
+**Result:** `{}`
+
+**Behaviour:**
+
+- Overrides are stored in the server's workspace context and applied to all
+  subsequent action runs.
+- If extension runners are already running, they receive a config update
+  immediately; initialized handlers are dropped and will be re-initialized with
+  the new config on the next run.
+- The CLI `run` command sends this message **before** `workspace/addDir` in
+  standalone mode (`--own-server`), so runners always start with the correct
+  config and no update push is required.
+- Config overrides are **not supported** in `--shared-server` mode: the CLI
+  will print a warning and ignore them.
+- Calling this method again replaces the previous overrides entirely.
+
+---
+
 #### `workspace/removeDir`
 
 Remove a workspace directory. Stops runners for affected projects and removes them
@@ -240,7 +285,6 @@ Execute a single action on a project.
   "action": "lint",
   "project": "finecode",
   "params": {"file_paths": ["/path/to/file.py"]},
-  "config_overrides": {"ruff": {"line_length": 120}},
   "options": {
     "result_formats": ["json", "string"],
     "trigger": "user",
@@ -284,7 +328,6 @@ Execute multiple actions across multiple projects. Used for batch operations.
   "actions": ["lint", "check_formatting"],
   "projects": ["finecode", "finecode_extension_api"],
   "params": {},
-  "config_overrides": {},
   "options": {
     "concurrent": false,
     "result_formats": ["json", "string"],

docs/cli.md

@@ -9,6 +9,36 @@ python -m finecode <command> [options]
 
 ---
 
+## Usage modes
+
+The `run` command supports two usage modes.
+
+### Standalone (one-shot) — default
+
+Each `run` invocation is fully independent. FineCode starts a dedicated API server subprocess for the duration of the command, then shuts it down on exit. This is the default behavior.
+
+```bash
+python -m finecode run lint
+```
+
+Use this in CI/CD pipelines or any context where you don't want persistent background processes. Results from one action can be saved to the file cache and referenced by a later action via `--map-payload-fields` (see the `run` reference below).
+
+### Persistent server
+
+A long-lived API server holds warm state — loaded configuration, started runners — across multiple `run` calls. Use `--shared-server` to connect to a running shared instance instead of starting a dedicated one.
+
+```bash
+# Connect to the shared server (start it first if needed):
+python -m finecode run --shared-server lint
+python -m finecode run --shared-server format
+```
+
+This mode is used automatically by the LSP and MCP integrations. It gives faster repeated runs because configuration loading and runner startup are amortized across calls.
+
+The server waits 30 seconds after the last client disconnects before shutting down (configurable via `--disconnect-timeout` on `start-api-server`).
+
+---
+
 ## `run`
 
 Run one or more actions across projects.
@@ -24,6 +54,7 @@ python -m finecode run [options] <action> [<action> ...] [payload] [--config.<ke
 | `--workdir=<path>` | Use `<path>` as the workspace root instead of `cwd` |
 | `--project=<name>` | Run only in this project. Repeatable for multiple projects. |
 | `--concurrently` | Run actions concurrently within each project |
+| `--shared-server` | Connect to the shared persistent API server instead of starting a dedicated one |
 | `--trace` | Enable verbose (trace-level) logging |
 | `--no-env-config` | Ignore `FINECODE_CONFIG_*` environment variables |
 | `--no-save-results` | Do not write action results to the cache directory |
@@ -155,14 +186,15 @@ Typically started automatically by MCP-compatible clients (for example, Claude C
 
 ## `start-api-server`
 
-Start the FineCode API server standalone (TCP JSON-RPC), listen for client connections. Auto-stops when the last client disconnects.
+Start the FineCode API server standalone (TCP JSON-RPC), listen for client connections. Shuts down after the last client disconnects and the disconnect timeout expires.
 
 ```text
-python -m finecode start-api-server [--trace]
+python -m finecode start-api-server [--trace] [--disconnect-timeout=<seconds>]
 ```
 
 | Option | Description |
 | --- | --- |
 | `--trace` | Enable verbose logging |
+| `--disconnect-timeout=<seconds>` | Seconds to wait after the last client disconnects before shutting down (default: 30) |
 
 Usually started automatically by `start-lsp` or `start-mcp`. Can also be started manually for debugging.

src/finecode/api_client.py

@@ -135,12 +135,50 @@ async def get_tree(self, parent_node_id: str | None = None) -> dict:
         result = await self.request("actions/getTree", params)
         return result
 
+    async def set_config_overrides(
+        self, overrides: dict
+    ) -> None:
+        """Set persistent handler config overrides on the server.
+
+        Overrides are stored for the lifetime of the server and applied to all
+        subsequent action runs.  Call this before ``add_dir`` if possible so that runners
+        always start with the correct config and no update push is required.
+
+        overrides format: {action_name: {handler_name_or_"": {param: value}}}
+        The empty-string key "" means the override applies to all handlers of
+        that action.
+        """
+        await self.request("workspace/setConfigOverrides", {"overrides": overrides})
+
+    async def run_batch(
+        self,
+        actions: list[str],
+        projects: list[str] | None = None,
+        params: dict | None = None,
+        params_by_project: dict[str, dict] | None = None,
+        options: dict | None = None,
+    ) -> dict:
+        """Run multiple actions across multiple (or all) projects.
+
+        Results are keyed by project path string, then action name.
+        All result keys use snake_case (return_code, result_by_format).
+        """
+        body: dict = {"actions": actions}
+        if projects is not None:
+            body["projects"] = projects
+        if params:
+            body["params"] = params
+        if params_by_project:
+            body["params_by_project"] = params_by_project
+        if options:
+            body["options"] = options
+        return await self.request("actions/runBatch", body)
+
     async def run_action(
         self,
         action: str,
         project: str,
         params: dict | None = None,
-        config_overrides: dict | None = None,
         options: dict | None = None,
     ) -> dict:
         """Run an action on a project."""
@@ -151,8 +189,6 @@ async def run_action(
         }
         if params:
             body["params"] = params
-        if config_overrides:
-            body["config_overrides"] = config_overrides
         return await self.request("actions/run", body)
 
     async def add_dir(self, dir_path: pathlib.Path) -> dict: