Initial implementation of WAL in WM

Author: Aksem

docs/cli.md

@@ -55,11 +55,14 @@ python -m finecode run [options] <action> [<action> ...] [payload] [--config.<ke
 | `--project=<name>` | Run only in this project (matched by `[project].name` from `pyproject.toml`). Repeatable for multiple projects. |
 | `--concurrently` | Run actions concurrently within each project |
 | `--shared-server` | Connect to the shared persistent WM Server instead of starting a dedicated one |
+| `--wal` | Enable WM write-ahead log (WAL) for the dedicated WM server started by this run command |
 | `--log-level=<level>` | Set log level: `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `INFO`) |
 | `--no-env-config` | Ignore `FINECODE_CONFIG_*` environment variables |
 | `--no-save-results` | Do not write action results to the cache directory |
 | `--dev-env=<env>` | Override the detected dev environment. One of: `ai`, `ci`, `cli`, `ide`, `precommit` (default: auto-detected — see [Dev environment detection](#dev-environment-detection)) |
 
+WAL environment variable and storage settings are shared with `start-wm-server` — see [`start-wm-server`](#start-wm-server) for details.
+
 ### Payload
 
 Named parameters passed to the action payload. All must use `--<name>=<value>` form:
@@ -88,6 +91,7 @@ See [Configuration](configuration.md) for full details on config precedence.
 - With no `--project`: FineCode treats `cwd` (or `--workdir`) as the workspace root, discovers all projects, and runs the action in each project that defines it.
 - With `--project`: the action must exist in every specified project.
 - Action results are saved to `<venv>/cache/finecode/results/<action>.json` (one entry per project path).
+- WAL options on `run` apply only when FineCode starts a dedicated WM server (default mode). In `--shared-server` mode, configure WAL on the shared WM server process.
 
 ### Examples
 
@@ -227,12 +231,23 @@ Typically started automatically by MCP-compatible clients (for example, Claude C
 Start the FineCode Workspace Manager 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-wm-server [--log-level=<level>] [--disconnect-timeout=<seconds>]
+python -m finecode start-wm-server [--log-level=<level>] [--disconnect-timeout=<seconds>] [--wal]
 ```
 
 | Option | Description |
 | --- | --- |
 | `--log-level=<level>` | Set log level: `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `INFO`) |
 | `--disconnect-timeout=<seconds>` | Seconds to wait after the last client disconnects before shutting down (default: 30) |
+| `--wal` | Enable WM write-ahead log (WAL) for run lifecycle events. |
+
+Environment variable equivalent:
+
+- `FINECODE_WAL_ENABLED=1` (or `true`/`yes`/`on`)
+
+WAL storage and retention are fixed in this version:
+
+- WAL directory: `<venv>/state/finecode/wal/wm`
+- Max segment size: `1048576` bytes
+- Retention: last `20` segment files
 
 Usually started automatically by `start-lsp` or `start-mcp`. Can also be started manually for debugging.

src/finecode/cli.py

@@ -17,6 +17,13 @@
 _VALID_DEV_ENVS = {"ide", "cli", "ai", "precommit", "ci"}
 
 
+def _parse_env_bool(name: str, default: bool) -> bool:
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
 def detect_dev_env() -> str:
     """Detect dev environment from context. CI env var overrides the default 'cli'."""
     if os.environ.get("CI"):
@@ -273,6 +280,7 @@ def run(ctx) -> None:
     map_payload_fields: set[str] = set()
     shared_server: bool = False
     dev_env: str = detect_dev_env()
+    wal_enabled: bool | None = None
 
     # finecode run parameters
     for arg in args:
@@ -304,6 +312,8 @@ def run(ctx) -> None:
             map_payload_fields = {f.replace("-", "_") for f in fields.split(",")}
         elif arg == "--shared-server":
             shared_server = True
+        elif arg == "--wal":
+            wal_enabled = True
         elif arg.startswith("--dev-env"):
             dev_env = arg.removeprefix("--dev-env=")
             if dev_env not in _VALID_DEV_ENVS:
@@ -318,6 +328,16 @@ def run(ctx) -> None:
 
     logger_utils.init_logger(log_name="cli", log_level=log_level, stdout=True)
 
+    if wal_enabled is None:
+        wal_enabled = _parse_env_bool("FINECODE_WAL_ENABLED", False)
+
+    if shared_server and wal_enabled:
+        click.echo(
+            "Warning: --wal is ignored in --shared-server mode. "
+            "Enable WAL on the shared WM server process itself.",
+            err=True,
+        )
+
     # Parse handler config from env vars
     handler_config_overrides: dict[str, dict[str, dict[str, str]]] = {}
     if not no_env_config:
@@ -390,6 +410,7 @@ def run(ctx) -> None:
                 own_server=not shared_server,
                 log_level=log_level,
                 dev_env=dev_env,
+                wal_enabled=wal_enabled,
             )
         )
         click.echo(result.output)
@@ -576,14 +597,40 @@ def start_mcp(workdir: str | None, log_level: str, wm_port_file: str | None):
     show_default=True,
     help="Seconds to wait after the last client disconnects before shutting down.",
 )
-def start_wm_server(log_level: str, port_file: str | None, disconnect_timeout: int):
+@click.option(
+    "--wal",
+    "wal_enabled",
+    is_flag=True,
+    default=None,
+    help="Enable WM write-ahead log (WAL). Can also be enabled with FINECODE_WAL_ENABLED=1.",
+)
+def start_wm_server(
+    log_level: str,
+    port_file: str | None,
+    disconnect_timeout: int,
+    wal_enabled: bool | None,
+):
     """Start the FineCode WM Server standalone (TCP JSON-RPC). Auto-stops when all clients disconnect."""
-    from finecode.wm_server import wm_server
+    from finecode.wm_server import wal, wm_server
 
     log_file_path = logger_utils.init_logger(log_name="wm_server", log_level=log_level, stdout=False)
     wm_server._log_file_path = log_file_path
     port_file_path = pathlib.Path(port_file) if port_file else None
-    asyncio.run(wm_server.start_standalone(port_file=port_file_path, disconnect_timeout=disconnect_timeout))
+
+    env_wal_enabled = _parse_env_bool("FINECODE_WAL_ENABLED", False)
+    final_wal_enabled = wal_enabled if wal_enabled is not None else env_wal_enabled
+
+    wal_config = wal.WalConfig(
+        enabled=final_wal_enabled,
+    )
+
+    asyncio.run(
+        wm_server.start_standalone(
+            port_file=port_file_path,
+            disconnect_timeout=disconnect_timeout,
+            wal_config=wal_config,
+        )
+    )
 
 
 if __name__ == "__main__":

src/finecode/cli_app/commands/run_cmd.py

@@ -89,11 +89,16 @@ async def run_actions(
     own_server: bool = False,
     log_level: str = "INFO",
     dev_env: str = "cli",
+    wal_enabled: bool = False,
 ) -> utils.RunActionsResult:
     port_file = None
     try:
         if own_server:
-            port_file = wm_lifecycle.start_own_server(workdir_path, log_level=log_level)
+            port_file = wm_lifecycle.start_own_server(
+                workdir_path,
+                log_level=log_level,
+                wal_enabled=wal_enabled,
+            )
             try:
                 port = await wm_lifecycle.wait_until_ready_from_file(port_file)
             except TimeoutError as exc:

src/finecode/wm_server/context.py

@@ -9,6 +9,7 @@
 
 if TYPE_CHECKING:
     from finecode_jsonrpc._io_thread import AsyncIOThread
+    from finecode.wm_server.wal import WalWriter
 
 
 @dataclass
@@ -48,6 +49,7 @@ class WorkspaceContext:
     cached_actions_by_id: dict[str, CachedAction] = field(default_factory=dict)
     # payload schema cache: project_path → {action_name: JSON Schema fragment | None}
     ws_action_schemas: dict[Path, dict[str, dict | None]] = field(default_factory=dict)
+    wal_writer: WalWriter | None = None
 
 
 @dataclass

src/finecode/wm_server/services/run_service/proxy_utils.py

@@ -10,7 +10,7 @@
 from loguru import logger
 
 from finecode import user_messages
-from finecode.wm_server import find_project, context, domain, domain_helpers
+from finecode.wm_server import find_project, context, domain, domain_helpers, wal
 from finecode.wm_server.runner import runner_manager
 from finecode.wm_server.runner import runner_client
 from finecode.wm_server.runner.runner_manager import RunnerFailedToStart
@@ -674,6 +674,7 @@ async def run_action(
     initialize_all_handlers: bool = False,
     progress_token: int | str | None = None,
 ) -> RunActionResponse:
+    wal_run_id = wal.new_wal_run_id()
     formatted_params = str(params)
     if len(formatted_params) > 100:
         formatted_params = f"{formatted_params[:100]}..."
@@ -685,11 +686,32 @@ async def run_action(
         _result_formats = result_formats
 
     if project_def.status != domain.ProjectStatus.CONFIG_VALID:
+        wal.emit_run_event(
+            ws_context.wal_writer,
+            event_type=wal.WalEventType.RUN_REJECTED,
+            wal_run_id=wal_run_id,
+            action_name=action_name,
+            project_path=project_def.dir_path,
+            run_trigger=run_trigger.value,
+            dev_env=dev_env.value,
+            payload=wal.RunRejectedPayload(reason="invalid_project_config"),
+        )
         raise ActionRunFailed(
             f"Project {project_def.dir_path} has no valid configuration and finecode."
             + " Please check logs."
         )
 
+    wal.emit_run_event(
+        ws_context.wal_writer,
+        event_type=wal.WalEventType.RUN_ACCEPTED,
+        wal_run_id=wal_run_id,
+        action_name=action_name,
+        project_path=project_def.dir_path,
+        run_trigger=run_trigger.value,
+        dev_env=dev_env.value,
+        payload=wal.RunAcceptedPayload(params_hash=wal.params_hash(params)),
+    )
+
     payload = params
 
     # cases:
@@ -720,6 +742,7 @@ async def run_action(
             result_formats=_result_formats,
             initialize_all_handlers=initialize_all_handlers,
             progress_token=progress_token,
+            wal_run_id=wal_run_id,
         )
     else:
         # TODO: concurrent vs sequential, this value should be taken from action config
@@ -741,6 +764,7 @@ async def run_action(
                     result_formats=_result_formats,
                     initialize_all_handlers=initialize_all_handlers,
                     progress_token=progress_token,
+                    wal_run_id=wal_run_id,
                 )
 
     return response
@@ -757,7 +781,20 @@ async def _run_action_in_env_runner(
     result_formats: list[runner_client.RunResultFormat],
     initialize_all_handlers: bool = False,
     progress_token: int | str | None = None,
+    wal_run_id: str | None = None,
 ):
+    effective_wal_run_id = wal_run_id or wal.new_wal_run_id()
+    wal.emit_run_event(
+        ws_context.wal_writer,
+        event_type=wal.WalEventType.RUNNER_SELECTED,
+        wal_run_id=effective_wal_run_id,
+        action_name=action_name,
+        project_path=project_def.dir_path,
+        run_trigger=run_trigger.value,
+        dev_env=dev_env.value,
+        payload=wal.RunnerSelectedPayload(env_name=env_name),
+    )
+
     try:
         runner = await runner_manager.get_or_start_runner(
             project_def=project_def,
@@ -778,13 +815,46 @@ async def _run_action_in_env_runner(
         }
         if progress_token is not None:
             options["progress_token"] = progress_token
+        wal.emit_run_event(
+            ws_context.wal_writer,
+            event_type=wal.WalEventType.RUN_DISPATCHED,
+            wal_run_id=effective_wal_run_id,
+            action_name=action_name,
+            project_path=project_def.dir_path,
+            run_trigger=run_trigger.value,
+            dev_env=dev_env.value,
+            payload=wal.RunDispatchedPayload(
+                runner_id=runner.readable_id,
+                env_name=env_name,
+            ),
+        )
         response = await runner_client.run_action(
             runner=runner,
             action_name=action_name,
             params=payload,
             options=options,
         )
+        wal.emit_run_event(
+            ws_context.wal_writer,
+            event_type=wal.WalEventType.RUN_COMPLETED,
+            wal_run_id=effective_wal_run_id,
+            action_name=action_name,
+            project_path=project_def.dir_path,
+            run_trigger=run_trigger.value,
+            dev_env=dev_env.value,
+            payload=wal.RunCompletedPayload(return_code=response.return_code),
+        )
     except runner_client.BaseRunnerRequestException as error:
+        wal.emit_run_event(
+            ws_context.wal_writer,
+            event_type=wal.WalEventType.RUN_FAILED,
+            wal_run_id=effective_wal_run_id,
+            action_name=action_name,
+            project_path=project_def.dir_path,
+            run_trigger=run_trigger.value,
+            dev_env=dev_env.value,
+            payload=wal.RunFailedPayload(error=error.message, env_name=env_name),
+        )
         await user_messages.error(
             f"Action {action_name} failed in {runner.readable_id}: {error.message} . Log file: {runner.logs_path}"
         )