devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/devflow_event_worker.py

@@ -0,0 +1,1292 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+import binascii
+import io
+import json
+import logging
+import os
+import shutil
+import subprocess
+import threading
+import time
+import zlib
+from contextlib import redirect_stderr, redirect_stdout, suppress
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Callable
+from urllib.parse import quote
+
+import typer
+
+from .api_keys import (
+    DevflowTransportGrantStore,
+    bootstrap_provider_api_keys,
+    set_runtime_provider_api_key,
+    store_provider_api_key,
+    unwrap_api_key_event_payload,
+)
+from .devflow_state import _postgrest_request, _resolve_supabase_rest_config
+
+logger = logging.getLogger(__name__)
+from devin.dag_two_arm import run_devin_two_arm_dag as run_devin_chat_dag
+from devflow_engine.idea.response_mode import current_response_mode_label
+from devflow_engine.idea.traditional_stories import TraditionalStoryInsufficiencyError, generate_traditional_user_story_set
+from .project_registry import normalize_github_selector, read_projects_registry
+from .source_scope.dag import run_source_to_scope_dag
+from .stores.execution_store import ExecutionStore
+
+PRIMARY_DEVFLOW_EVENT_TYPES = {
+    "devflow.project.init.request": "project_init",
+    "devflow.project.import.request": "project_import",
+    "devflow.project.repo_tree.request": "project_repo_tree",
+    "devflow.project.source_docs.add.request": "source_docs_add",
+    "devflow.source_scope.run.request": "source_scope_run",
+    "devflow.idea.intake.request": "idea_intake",
+    "devflow.idea.stories.generate.request": "idea_stories_generate",
+    "devflow_settings_changed": "settings_changed",
+    "devflow_API_KEY": "api_key",
+}
+
+_ALREADY_REGISTERED_TOKENS = (
+    "already registered",
+    "already exists",
+    "duplicate",
+    "already imported",
+)
+
+_REPO_TREE_EXCLUDED_DIR_NAMES = {".git", ".devflow", "node_modules", ".venv", "__pycache__"}
+_SECRET_SETTING_TOKENS = ("key", "token", "secret", "password")
+
+
+@dataclass(frozen=True)
+class DevflowDispatchResult:
+    event_id: str
+    execution_run_id: int
+    workflow_key: str
+    command: list[str]
+    result: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class DevflowEventWorkerLoopResult:
+    processed: int = 0
+    failed: int = 0
+    idle: bool = False
+
+
+@dataclass(frozen=True)
+class _CliInvocationResult:
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+def _extract_project_id_from_cli_output(output: str) -> str | None:
+    for line in output.splitlines():
+        if not line.lower().startswith("project_id:"):
+            continue
+        value = line.split(":", 1)[1].strip()
+        if value:
+            return value
+    return None
+
+
+def _utcnow_iso() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def _project_metadata(project: dict[str, Any]) -> dict[str, Any]:
+    metadata = project.get("metadata")
+    if isinstance(metadata, dict):
+        return dict(metadata)
+    metadata = project.get("metadata_json")
+    if isinstance(metadata, dict):
+        return dict(metadata)
+    return {}
+
+
+def _normalize_planes(raw: Any) -> list[str]:
+    if isinstance(raw, str):
+        return [item.strip() for item in raw.split(",") if item.strip()]
+    if isinstance(raw, list):
+        return [str(item).strip() for item in raw if str(item).strip()]
+    return []
+
+
+def _result_message(exc: TraditionalStoryInsufficiencyError) -> str:
+    report = exc.report
+    return json.dumps(
+        {
+            "error": "traditional story set insufficient after refinement loop",
+            "story_set_id": exc.story_set_id,
+            "stories_dir": str(exc.root),
+            "report_path": str(exc.report_path),
+            "pass_count": report.get("pass_count"),
+            "passed": report.get("passed"),
+            "final_findings": report.get("final_findings"),
+        },
+        sort_keys=True,
+    )
+
+
+class DevflowEventWorkerService:
+    def __init__(self, *, worker_id: str = "devflow-engine-supabase-event-worker") -> None:
+        self.worker_id = worker_id
+        bootstrap_provider_api_keys()
+
+    def fetch_next_requested_event(self) -> dict[str, Any] | None:
+        events = self._fetch_candidate_events()
+        for event in events:
+            event_type = str(event.get("event_type") or "")
+            workflow_key = PRIMARY_DEVFLOW_EVENT_TYPES.get(event_type)
+            if workflow_key is None:
+                continue
+            claimed = self._claim_event(event_id=str(event["id"]), workflow_key=workflow_key)
+            if claimed is not None:
+                return claimed
+        return None
+
+    def dispatch_next_event(self) -> DevflowDispatchResult | None:
+        event = self.fetch_next_requested_event()
+        if event is None:
+            return None
+        project = self._fetch_project(project_id=str(event["project_id"]))
+        return self.dispatch_event(event=event, project=project)
+
+    def dispatch_event(self, *, event: dict[str, Any], project: dict[str, Any]) -> DevflowDispatchResult:
+        event_id = str(event["id"])
+        workflow_key = PRIMARY_DEVFLOW_EVENT_TYPES.get(str(event.get("event_type") or ""))
+        if workflow_key is None:
+            raise RuntimeError(f"Unsupported DevFlow event type: {event.get('event_type')}")
+
+        company_payload = self._company_payload(project=project, event=event)
+        started_at = _utcnow_iso()
+        command: list[str] = []
+        run = self._insert_execution_run(
+            {
+                "event_id": event_id,
+                "project_id": str(project["id"]),
+                "workflow_key": workflow_key,
+                "status": "processing",
+                "worker_id": self.worker_id,
+                "command": command,
+                "company_payload": company_payload,
+                "started_at": started_at,
+                "last_heartbeat_at": started_at,
+                "summary": f"Dispatching {workflow_key}",
+            }
+        )
+        execution_run_id = int(run["id"])
+        step = self._insert_execution_step_run(
+            {
+                "execution_run_id": execution_run_id,
+                "step_name": "dispatch_devflow_engine",
+                "status": "processing",
+                "command": command,
+                "started_at": started_at,
+            }
+        )
+        step_id = int(step["id"])
+
+        self._update_event(
+            event_id=event_id,
+            fields={
+                "run_id": str(execution_run_id),
+                "status": "processing",
+                "stage": workflow_key,
+                "error": None,
+                "producer": self.worker_id,
+            },
+        )
+
+        try:
+            command = self._build_command(event=event, project=project)
+            self._update_execution_step_run(step_id=step_id, fields={"command": command})
+            self._update_execution_run(execution_run_id=execution_run_id, fields={"command": command})
+            result = self._execute_event(event=event, project=project)
+        except Exception as exc:
+            finished_at = _utcnow_iso()
+            error_message = str(exc)
+            self._update_execution_step_run(
+                step_id=step_id,
+                fields={
+                    "status": "failed",
+                    "finished_at": finished_at,
+                    "error": error_message,
+                    "result": {"error": error_message},
+                },
+            )
+            self._update_execution_run(
+                execution_run_id=execution_run_id,
+                fields={
+                    "status": "failed",
+                    "finished_at": finished_at,
+                    "last_heartbeat_at": finished_at,
+                    "error": error_message,
+                    "result": {"error": error_message},
+                },
+            )
+            self._update_event(
+                event_id=event_id,
+                fields={
+                    "status": "error",
+                    "stage": workflow_key,
+                    "error": error_message,
+                    "producer": self.worker_id,
+                    "payload": self._merge_event_payload(
+                        event=event,
+                        extra_payload={
+                            "workflow_key": workflow_key,
+                            "dispatch_command": command,
+                            "execution_result": {"error": error_message},
+                        },
+                    ),
+                },
+            )
+            raise
+
+        finished_at = _utcnow_iso()
+        local_repo_root = result.get("local_repo_root")
+        if isinstance(local_repo_root, str) and local_repo_root.strip():
+            self._update_project(
+                project_id=str(project["id"]),
+                fields={"devflow_repo_root": local_repo_root.strip()},
+            )
+
+        self._update_execution_step_run(
+            step_id=step_id,
+            fields={
+                "status": "completed",
+                "finished_at": finished_at,
+                "result": result,
+            },
+        )
+        self._update_execution_run(
+            execution_run_id=execution_run_id,
+            fields={
+                "status": "completed",
+                "finished_at": finished_at,
+                "last_heartbeat_at": finished_at,
+                "summary": f"Completed {workflow_key}" + (" (already registered)" if result.get("already_registered") else ""),
+                "result": result,
+                "error": None,
+            },
+        )
+        self._update_event(
+            event_id=event_id,
+            fields={
+                "status": "completed",
+                "stage": workflow_key,
+                "error": None,
+                "producer": self.worker_id,
+                "payload": self._merge_event_payload(
+                    event=event,
+                    extra_payload={
+                        "workflow_key": workflow_key,
+                        "dispatch_command": command,
+                        "execution_result": result,
+                    },
+                ),
+            },
+        )
+
+        return DevflowDispatchResult(
+            event_id=event_id,
+            execution_run_id=execution_run_id,
+            workflow_key=workflow_key,
+            command=command,
+            result=result,
+        )
+
+    def _execute_event(self, *, event: dict[str, Any], project: dict[str, Any]) -> dict[str, Any]:
+        event_type = str(event.get("event_type") or "")
+        if event_type == "devflow.project.init.request":
+            return self._run_project_init_request(event=event, project=project)
+        if event_type == "devflow.project.import.request":
+            return self._run_project_import_request(event=event, project=project)
+        if event_type == "devflow.project.repo_tree.request":
+            return self._run_project_repo_tree_request(event=event, project=project)
+        if event_type == "devflow.project.source_docs.add.request":
+            return self._run_project_source_docs_add_request(event=event, project=project)
+        if event_type == "devflow.source_scope.run.request":
+            return self._run_source_scope_request(event=event, project=project)
+        if event_type == "devflow.idea.intake.request":
+            return self._run_idea_intake_request(event=event, project=project)
+        if event_type == "devflow.idea.stories.generate.request":
+            return self._run_idea_stories_generate_request(event=event, project=project)
+        if event_type == "devflow_settings_changed":
+            return self._run_settings_changed_request(event=event, project=project)
+        if event_type == "devflow_API_KEY":
+            return self._run_api_key_event(event=event, project=project)
+        raise RuntimeError(f"Unsupported DevFlow event type: {event_type}")
+
+    def _run_project_init_request(self, *, event: dict[str, Any], project: dict[str, Any]) -> dict[str, Any]:
+        payload = dict(event.get("payload") or {})
+        repo_root = self._resolve_local_repo_root(project=project, event=event)
+        create_new = self._is_new_project_init_request(payload=payload)
+        if repo_root is None and not create_new:
+            raise RuntimeError("project init event requires an existing local_repo_root/workspace_path")
+        name = str(payload.get("name") or project.get("name") or "").strip()
+        if not name:
+            raise RuntimeError("project init event requires project name")
+        command_result = self._invoke_cli_command(
+            cwd=(repo_root or Path.cwd()),
+            func_name="project_init",
+            kwargs={
+                "name": name,
+                "new": create_new,
+                "template": payload.get("template"),
+                "project_type": payload.get("project_type"),
+            },
+        )
+        if command_result.returncode != 0:
+            raise RuntimeError(command_result.stderr or command_result.stdout or "project init failed")
+        if repo_root is None:
+            repo_root = self._resolve_new_project_repo_root(name=name)
+        return {
+            "returncode": 0,
+            "stdout": command_result.stdout,
+            "stderr": command_result.stderr,
+            "local_repo_root": str(repo_root),
+        }
+
+    def _run_project_import_request(self, *, event: dict[str, Any], project: dict[str, Any]) -> dict[str, Any]:
+        payload = dict(event.get("payload") or {})
+        repo_spec = self._project_import_repo_spec(payload=payload, project=project)
+        authoritative_project_id = str(project.get("id") or "").strip() or str(event.get("project_id") or "").strip()
+        command_result = self._invoke_cli_command(
+            cwd=Path.cwd(),
+            func_name="project_import",
+            kwargs={
+                "repo_spec": repo_spec,
+                "init": payload.get("init"),
+                "supabase_project_id": authoritative_project_id or None,
+            },
+        )
+        combined_output = f"{command_result.stdout}\n{command_result.stderr}".lower()
+        already_registered = command_result.returncode != 0 and any(token in combined_output for token in _ALREADY_REGISTERED_TOKENS)
+        if command_result.returncode != 0 and not already_registered:
+            raise RuntimeError(command_result.stderr or command_result.stdout or "project import failed")
+        reported_project_id = _extract_project_id_from_cli_output(command_result.stdout)
+        if authoritative_project_id and reported_project_id and reported_project_id != authoritative_project_id:
+            raise RuntimeError(
+                "project import returned mismatched project_id "
+                f"(authoritative={authoritative_project_id}, reported={reported_project_id})"
+            )
+        local_repo_root = self._resolve_imported_repo_root(project=project, event=event, repo_spec=repo_spec, init_template=payload.get("init"))
+        return {
+            "returncode": 0 if already_registered else command_result.returncode,
+            "project_id": authoritative_project_id or reported_project_id,
+            "stdout": command_result.stdout,
+            "stderr": command_result.stderr,
+            "already_registered": already_registered,
+            "local_repo_root": None if local_repo_root is None else str(local_repo_root),
+        }
+
+    def _run_project_repo_tree_request(self, *, event: dict[str, Any], project: dict[str, Any]) -> dict[str, Any]:
+        repo_root = self._require_repo_root(project=project, event=event)
+        entries: list[dict[str, str]] = []
+        for current_root, dirnames, filenames in os.walk(repo_root):
+            dirnames[:] = [name for name in dirnames if name not in _REPO_TREE_EXCLUDED_DIR_NAMES]
+            current_path = Path(current_root)
+            for filename in sorted(filenames):
+                path = (current_path / filename).resolve()
+                rel = path.relative_to(repo_root).as_posix()
+                entries.append({"path": rel, "type": "file"})
+        return {
+            "entry_count": len(entries),
+            "entries": entries,
+            "local_repo_root": str(repo_root),
+        }
+
+    def _run_project_source_docs_add_request(self, *, event: dict[str, Any], project: dict[str, Any]) -> dict[str, Any]:
+        payload = dict(event.get("payload") or {})
+        repo_root = self._require_repo_root(project=project, event=event)
+        source_mode = str(payload.get("source_mode") or "").strip().lower()
+        if source_mode not in {"filesystem", "repo"}:
+            raise RuntimeError("source docs add event requires source_mode of 'filesystem' or 'repo'")
+
+        source_docs_root = repo_root / "ai_docs" / "context" / "source_docs"
+        source_docs_root.mkdir(parents=True, exist_ok=True)
+        added_files: list[str] = []
+
+        if source_mode == "repo":
+            repo_paths = [str(item).strip() for item in (payload.get("repo_paths") or []) if str(item).strip()]
+            if not repo_paths:
+                raise RuntimeError("source docs add event requires repo_paths when source_mode=repo")
+            for rel in repo_paths:
+                source_path = self._resolve_repo_relative_path(base=repo_root, raw=rel)
+                if not source_path.exists() or not source_path.is_file():
+                    raise RuntimeError(f"Selected repo file does not exist: {rel}")
+                destination_path = self._resolve_repo_relative_path(base=source_docs_root, raw=rel)
+                if source_path == destination_path:
+                    added_files.append(destination_path.relative_to(repo_root).as_posix())
+                    continue
+                destination_path.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(source_path, destination_path)
+                added_files.append(destination_path.relative_to(repo_root).as_posix())
+        else:
+            files = payload.get("files") or []
+            if not isinstance(files, list) or not files:
+                raise RuntimeError("source docs add event requires files when source_mode=filesystem")
+            for item in files:
+                if not isinstance(item, dict):
+                    raise RuntimeError("source docs add event files entries must be objects")
+                name = str(item.get("name") or "").strip()
+                encoded = str(item.get("content_base64") or "")
+                if not name or not encoded:
+                    raise RuntimeError("source docs add event filesystem files require name and content_base64")
+                try:
+                    raw_bytes = base64.b64decode(encoded, validate=True)
+                except (ValueError, binascii.Error) as exc:
+                    raise RuntimeError(f"Invalid base64 payload for source doc file {name}") from exc
+                # Decompress gzip if the file was compressed before upload
+                compression = str(item.get("compression") or "").lower()
+                if compression == "gzip":
+                    try:
+                        raw_bytes = zlib.decompress(raw_bytes, 16 + zlib.MAX_WBITS)
+                    except Exception as exc:
+                        raise RuntimeError(f"Failed to decompress gzip payload for {name}: {exc}") from exc
+                destination_path = self._resolve_repo_relative_path(base=source_docs_root, raw=Path(name).name)
+                destination_path.parent.mkdir(parents=True, exist_ok=True)
+                destination_path.write_bytes(raw_bytes)
+                added_files.append(destination_path.relative_to(repo_root).as_posix())
+
+        # After saving, check for DDR (FileMaker DDR XML) files and run ddr-docs for each
+        ddr_results: list[dict[str, Any]] = []
+        xml_files = [f for f in added_files if f.lower().endswith(".xml")]
+        key_layout_name = payload.get("key_layout_layout_name")
+        for xml_file in xml_files:
+            ddr_input_path = repo_root / xml_file
+            # Use the XML filename (without extension) as the output subdirectory name
+            ddr_name = Path(xml_file).stem
+            ddr_output_dir = repo_root / "ai_docs" / "context" / "source_docs" / "ddr" / ddr_name
+            try:
+                cmd = [
+                    "/Users/devflow/repos/FM2Web/.agent-venv/bin/ddr-docs",
+                    "analyze", "full-analysis",
+                    "--input", str(ddr_input_path),
+                    "--output-dir", str(ddr_output_dir),
+                    "--journey-depth", "5",
+                ]
+                if key_layout_name:
+                    cmd.extend(["--entry-point-layout", str(key_layout_name)])
+                result = subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    timeout=300,
+                    env={**os.environ, "PATH": "/usr/local/bin:/usr/bin:/bin"},
+                )
+                if result.returncode == 0:
+                    ddr_results.append({
+                        "status": "success",
+                        "input_file": xml_file,
+                        "output_dir": str(ddr_output_dir),
+                        "key_layout": key_layout_name or None,
+                        "stdout": result.stdout[-500:] if result.stdout else "",
+                    })
+                else:
+                    ddr_results.append({
+                        "status": "failed",
+                        "input_file": xml_file,
+                        "key_layout": key_layout_name or None,
+                        "error": result.stderr[-500:] if result.stderr else result.stdout[-500:],
+                    })
+            except Exception as exc:
+                ddr_results.append({
+                    "status": "error",
+                    "input_file": xml_file,
+                    "key_layout": key_layout_name or None,
+                    "error": str(exc),
+                })
+
+        result_data = {
+            "source_mode": source_mode,
+            "added_count": len(added_files),
+            "added_files": added_files,
+            "source_docs_root": str(source_docs_root),
+            "local_repo_root": str(repo_root),
+        }
+        if ddr_results:
+            result_data["ddr_analysis"] = ddr_results if len(ddr_results) > 1 else ddr_results[0]
+        return result_data
+
+
+    def _run_source_scope_request(self, *, event: dict[str, Any], project: dict[str, Any]) -> dict[str, Any]:
+        payload = dict(event.get("payload") or {})
+        repo_root = self._require_repo_root(project=project, event=event)
+        intake_id = str(payload.get("intake_id") or "").strip()
+        if not intake_id:
+            raise RuntimeError("source-scope event requires intake_id")
+        source_refs: list[dict[str, Any]] = []
+        for raw in payload.get("sources") or []:
+            path = Path(str(raw)).expanduser()
+            source_refs.append({"type": "doc", "path": str(path), "title": path.name})
+        text = payload.get("text")
+        if text:
+            source_refs.append({"type": "notes", "title": f"{intake_id}.md", "text": str(text)})
+        if not source_refs:
+            raise RuntimeError("source-scope event requires sources or text")
+        store = self._store_for_repo(repo_root)
+        result = run_source_to_scope_dag(
+            repo_root=repo_root,
+            store=store,
+            project_id=str(project["id"]),
+            source_intake_id=intake_id,
+            source_refs=source_refs,
+            requested_by=str(payload.get("requested_by") or "marcus"),
+        )
+        if result.exit_code != 0:
+            raise RuntimeError(result.message or "source-scope run failed")
+        return {
+            "exit_code": result.exit_code,
+            "run_id": result.run_id,
+            "pipeline_dir": str(result.pipeline_dir),
+            "message": result.message,
+            "outcome": result.outcome,
+            "local_repo_root": str(repo_root),
+        }
+
+    def _run_idea_intake_request(self, *, event: dict[str, Any], project: dict[str, Any]) -> dict[str, Any]:
+        payload = dict(event.get("payload") or {})
+        repo_root = self._require_repo_root(project=project, event=event)
+        idea_id = str(payload.get("idea_id") or event.get("idea_id") or "").strip()
+        if not idea_id:
+            raise RuntimeError("idea intake event requires idea_id")
+        source_path = payload.get("source_path")
+        store = self._store_for_repo(repo_root)
+        result = run_devin_chat_dag(
+            repo_root=repo_root,
+            store=store,
+            idea_id=idea_id,
+            text=(None if payload.get("text") is None else str(payload.get("text"))),
+            source_path=(Path(str(source_path)).expanduser().resolve() if source_path else None),
+            max_stories=int(payload.get("max_stories") or 0),
+            planes=_normalize_planes(payload.get("planes")),
+            response_mode_label=(
+                None
+                if payload.get("response_mode_label") is None and payload.get("response_mode") is None
+                else str(payload.get("response_mode_label") or payload.get("response_mode"))
+            ),
+        )
+        if result.exit_code != 0:
+            raise RuntimeError(result.message or "idea intake failed")
+        return {
+            "exit_code": result.exit_code,
+            "run_id": result.run_id,
+            "pipeline_dir": str(result.pipeline_dir),
+            "message": result.message,
+            "outcome": result.outcome,
+            "local_repo_root": str(repo_root),
+        }
+
+    def _run_idea_stories_generate_request(self, *, event: dict[str, Any], project: dict[str, Any]) -> dict[str, Any]:
+        payload = dict(event.get("payload") or {})
+        repo_root = self._require_repo_root(project=project, event=event)
+        idea_id = str(payload.get("idea_id") or event.get("idea_id") or "").strip()
+        if not idea_id:
+            raise RuntimeError("idea stories generate event requires idea_id")
+        try:
+            story_set = generate_traditional_user_story_set(
+                repo_root=repo_root,
+                idea_id=idea_id,
+                max_stories=int(payload.get("max_stories") or 0),
+            )
+        except FileNotFoundError as exc:
+            raise RuntimeError(f"Missing idea artifact for idea_id={idea_id}") from exc
+        except ValueError as exc:
+            raise RuntimeError(str(exc)) from exc
+        except TraditionalStoryInsufficiencyError as exc:
+            raise RuntimeError(_result_message(exc)) from exc
+        return {
+            "story_set_id": story_set.story_set_id,
+            "stories_dir": str(story_set.root),
+            "story_paths": [str(path) for path in story_set.story_paths],
+            "sufficiency_report": story_set.sufficiency_report,
+            "local_repo_root": str(repo_root),
+        }
+
+    def _run_settings_changed_request(self, *, event: dict[str, Any], project: dict[str, Any]) -> dict[str, Any]:
+        payload = dict(event.get("payload") or {})
+        raw_settings = payload.get("settings")
+        if not isinstance(raw_settings, dict) or not raw_settings:
+            raise RuntimeError("devflow_settings_changed requires payload.settings object")
+
+        settings = dict(raw_settings)
+        applied_keys: list[str] = []
+
+        llm_mode = settings.pop("llm_mode", None)
+        llm_provider = settings.pop("llm_provider", None)
+        if llm_mode is not None or llm_provider is not None:
+            current_config = self._read_global_config()
+            resolved_mode = str(llm_mode if llm_mode is not None else current_config.get("llm_mode") or "").strip().lower()
+            resolved_provider = str(llm_provider if llm_provider is not None else current_config.get("llm_provider") or "").strip().lower()
+            if resolved_mode not in {"cli", "api"}:
+                raise RuntimeError("devflow_settings_changed requires llm_mode to be cli or api for provider updates")
+            if not resolved_provider:
+                raise RuntimeError("devflow_settings_changed requires llm_provider when updating llm_mode/provider")
+            command_result = self._invoke_cli_command(
+                cwd=Path.cwd(),
+                func_name="config_llm_set_provider",
+                kwargs={"mode": resolved_mode, "provider": resolved_provider},
+            )
+            if command_result.returncode != 0:
+                raise RuntimeError(command_result.stderr or command_result.stdout or "config llm-set-provider failed")
+            applied_keys.extend(["llm_mode", "llm_provider"])
+
+        for key, value in settings.items():
+            normalized_key = str(key).strip()
+            if not normalized_key:
+                continue
+            if self._is_secret_setting_key(normalized_key):
+                raise RuntimeError(
+                    f"devflow_settings_changed cannot apply secret setting '{normalized_key}'; use devflow_API_KEY"
+                )
+            command_result = self._invoke_cli_command(
+                cwd=Path.cwd(),
+                func_name="config_set",
+                kwargs={"key": normalized_key, "value": self._stringify_setting_value(value), "project_id": None},
+            )
+            if command_result.returncode != 0:
+                raise RuntimeError(command_result.stderr or command_result.stdout or f"config set failed for {normalized_key}")
+            applied_keys.append(normalized_key)
+
+        return {
+            "applied_settings": applied_keys,
+            "config_scope": "global",
+            "local_repo_root": str(self._resolve_local_repo_root(project=project, event=event) or Path.cwd()),
+        }
+
+    def _run_api_key_event(self, *, event: dict[str, Any], project: dict[str, Any]) -> dict[str, Any]:
+        payload = dict(event.get("payload") or {})
+        grant_store = self._resolve_transport_grant_store()
+        try:
+            unwrapped = unwrap_api_key_event_payload(payload=payload, grant_store=grant_store)
+        finally:
+            grant_store.close()
+
+        provider = str(unwrapped["provider"] or "")
+        api_key = str(unwrapped["api_key"] or "")
+        tier = str(unwrapped["tier"] or "").strip() or None
+
+        store_provider_api_key(provider, api_key)
+        env_var = set_runtime_provider_api_key(provider, api_key)
+
+        return {
+            "provider": provider,
+            "tier": tier,
+            "env_var": env_var,
+            "storage": {
+                "runtime_env": True,
+                "macos_keychain": True,
+            },
+            "local_repo_root": str(self._resolve_local_repo_root(project=project, event=event) or Path.cwd()),
+        }
+
+    def _build_command(self, *, event: dict[str, Any], project: dict[str, Any]) -> list[str]:
+        payload = dict(event.get("payload") or {})
+        event_type = str(event.get("event_type") or "")
+        if event_type == "devflow.project.init.request":
+            command = ["devflow", "project", "init", "--name", str(payload.get("name") or project.get("name") or "")]
+            if self._is_new_project_init_request(payload=payload):
+                command.append("--new")
+            if payload.get("template"):
+                command.extend(["--template", str(payload["template"])])
+            if payload.get("project_type"):
+                command.extend(["--project-type", str(payload["project_type"])])
+            return command
+        if event_type == "devflow.project.import.request":
+            repo_spec = self._project_import_repo_spec(payload=payload, project=project)
+            command = ["devflow", "project", "import", repo_spec]
+            if payload.get("init"):
+                command.extend(["--init", str(payload["init"])])
+            return command
+        if event_type == "devflow.project.repo_tree.request":
+            repo_root = self._require_repo_root(project=project, event=event)
+            return ["devflow-event-worker", "project-repo-tree", "--repo", str(repo_root)]
+        if event_type == "devflow.project.source_docs.add.request":
+            repo_root = self._require_repo_root(project=project, event=event)
+            command = ["devflow-event-worker", "source-docs-add", "--repo", str(repo_root), "--source-mode", str(payload.get("source_mode") or "")]
+            for repo_path in payload.get("repo_paths") or []:
+                command.extend(["--repo-path", str(repo_path)])
+            for file_name in payload.get("file_names") or []:
+                command.extend(["--file", str(file_name)])
+            return command
+        if event_type == "devflow.source_scope.run.request":
+            intake_id = payload.get("intake_id")
+            if not intake_id:
+                raise RuntimeError("source-scope event requires intake_id")
+            command = ["devflow", "source-scope", "run", "--project-id", str(project["id"]), "--intake-id", str(intake_id)]
+            for source in payload.get("sources") or []:
+                command.extend(["--source", str(source)])
+            if payload.get("text"):
+                command.extend(["--text", str(payload["text"])])
+            if payload.get("requested_by"):
+                command.extend(["--requested-by", str(payload["requested_by"])])
+            return command
+        if event_type == "devflow.idea.intake.request":
+            idea_id = payload.get("idea_id") or event.get("idea_id")
+            if not idea_id:
+                raise RuntimeError("idea intake event requires idea_id")
+            command = ["devflow", "idea", "intake", "--idea", str(idea_id)]
+            if payload.get("text"):
+                command.extend(["--text", str(payload["text"])])
+            if payload.get("source_path"):
+                command.extend(["--from", str(payload["source_path"])])
+            if payload.get("max_stories") is not None:
+                command.extend(["--max-stories", str(payload["max_stories"])])
+            if payload.get("planes"):
+                command.extend(["--planes", ",".join(_normalize_planes(payload.get("planes")))])
+            command.extend(["--response-mode", str(payload.get("response_mode_label") or current_response_mode_label())])
+            return command
+        if event_type == "devflow.idea.stories.generate.request":
+            idea_id = payload.get("idea_id") or event.get("idea_id")
+            if not idea_id:
+                raise RuntimeError("idea stories generate event requires idea_id")
+            command = ["devflow", "idea", "stories", "generate", "--idea", str(idea_id)]
+            if payload.get("max_stories") is not None:
+                command.extend(["--max-stories", str(payload["max_stories"])])
+            return command
+        if event_type == "devflow_settings_changed":
+            return ["devflow-event-worker", "settings-changed", "--event-type", "devflow_settings_changed"]
+        if event_type == "devflow_API_KEY":
+            return ["devflow-event-worker", "api-key", "--event-type", "devflow_API_KEY"]
+        raise RuntimeError(f"Unsupported DevFlow event type: {event_type}")
+
+    def _company_payload(self, *, project: dict[str, Any], event: dict[str, Any]) -> dict[str, Any]:
+        payload = dict(event.get("payload") or {})
+        metadata = _project_metadata(project)
+        company_payload = payload.get("company_payload")
+        if isinstance(company_payload, dict):
+            return company_payload
+        if isinstance(metadata.get("company_payload"), dict):
+            return dict(metadata["company_payload"])
+        return {
+            "organization_id": project.get("organization_id"),
+            "customer_id": project.get("customer_id"),
+            "project_name": project.get("name"),
+            "environment": project.get("environment"),
+        }
+
+    def _require_repo_root(self, *, project: dict[str, Any], event: dict[str, Any]) -> Path:
+        repo_root = self._resolve_local_repo_root(project=project, event=event)
+        if repo_root is None:
+            raise RuntimeError(f"Unable to resolve local repo root for project {project.get('id')}")
+        return repo_root
+
+    def _resolve_local_repo_root(self, *, project: dict[str, Any], event: dict[str, Any]) -> Path | None:
+        payload = dict(event.get("payload") or {})
+        for candidate in (
+            payload.get("local_repo_root"),
+            payload.get("workspace_path"),
+            project.get("devflow_repo_root"),
+        ):
+            path = self._coerce_existing_path(candidate)
+            if path is not None:
+                return path
+
+        repo_url = project.get("repo_url") or payload.get("repo_spec")
+        normalized_repo_url = normalize_github_selector(str(repo_url)) if isinstance(repo_url, str) else None
+        registry = read_projects_registry()
+        for item in registry.get("projects", []):
+            if not isinstance(item, dict):
+                continue
+            item_remote = str(item.get("remote_url") or "").strip()
+            if repo_url and item_remote and item_remote in {str(repo_url), str(normalized_repo_url or "")}:
+                path = self._coerce_existing_path(item.get("repo_root") or item.get("workspace_path"))
+                if path is not None:
+                    return path
+            if str(item.get("project_id") or "").strip() == str(project.get("id") or "").strip():
+                path = self._coerce_existing_path(item.get("repo_root") or item.get("workspace_path"))
+                if path is not None:
+                    return path
+        return None
+
+    def _resolve_imported_repo_root(self, *, project: dict[str, Any], event: dict[str, Any], repo_spec: str, init_template: Any) -> Path | None:
+        if init_template:
+            return Path(repo_spec).expanduser().resolve()
+        path = self._coerce_existing_path(project.get("devflow_repo_root"))
+        if path is not None:
+            return path
+        path = self._resolve_local_repo_root(project=project, event=event)
+        if path is not None:
+            return path
+        spec_path = self._coerce_existing_path(repo_spec)
+        if spec_path is not None:
+            return spec_path
+        return None
+
+    def _project_import_repo_spec(self, *, payload: dict[str, Any], project: dict[str, Any]) -> str:
+        raw_repo_spec = payload.get("repo_spec") or project.get("repo_url") or project.get("devflow_repo_root")
+        if not isinstance(raw_repo_spec, str) or not raw_repo_spec.strip():
+            raise RuntimeError("project import event requires repo_spec or project repo_url")
+        repo_spec = raw_repo_spec.strip()
+        if payload.get("init"):
+            return repo_spec
+        if normalize_github_selector(repo_spec) is not None:
+            return repo_spec
+        trimmed_repo_spec = repo_spec.strip("/")
+        if trimmed_repo_spec and trimmed_repo_spec != repo_spec and normalize_github_selector(trimmed_repo_spec) is not None:
+            return trimmed_repo_spec
+        return repo_spec
+
+    def _is_new_project_init_request(self, *, payload: dict[str, Any]) -> bool:
+        mode = str(payload.get("init_mode") or payload.get("mode") or "").strip().lower()
+        if mode in {"new", "create"}:
+            return True
+        if bool(payload.get("new")) or bool(payload.get("create")) or bool(payload.get("create_project")):
+            return True
+        return bool(payload.get("template") or payload.get("project_type"))
+
+    def _resolve_new_project_repo_root(self, *, name: str) -> Path:
+        from .cli import app as cli_app
+
+        return cli_app.resolve_canonical_repo_root(name, None)
+
+    def _coerce_existing_path(self, raw: Any) -> Path | None:
+        if not isinstance(raw, str) or not raw.strip():
+            return None
+        path = Path(raw).expanduser().resolve()
+        if path.exists():
+            return path
+        return None
+
+    def _resolve_repo_relative_path(self, *, base: Path, raw: str) -> Path:
+        candidate = (base / raw).resolve()
+        try:
+            candidate.relative_to(base.resolve())
+        except ValueError as exc:
+            raise RuntimeError(f"Path escapes allowed root: {raw}") from exc
+        return candidate
+
+    def _store_for_repo(self, repo_root: Path) -> ExecutionStore:
+        repo_root = repo_root.expanduser().resolve()
+        (repo_root / ".devflow").mkdir(parents=True, exist_ok=True)
+        return ExecutionStore(repo_root / ".devflow" / "execution.sqlite")
+
+    def _read_global_config(self) -> dict[str, Any]:
+        from .cli import app as cli_app
+
+        return cli_app._read_toml(cli_app._global_devflow_dir() / "config.toml")
+
+    def _is_secret_setting_key(self, key: str) -> bool:
+        lowered = key.strip().lower()
+        return any(token in lowered for token in _SECRET_SETTING_TOKENS)
+
+    def _stringify_setting_value(self, value: Any) -> str:
+        if isinstance(value, bool):
+            return "true" if value else "false"
+        if value is None:
+            return ""
+        return str(value)
+
+    def _resolve_transport_grant_store(self) -> DevflowTransportGrantStore:
+        return DevflowTransportGrantStore.from_env()
+
+    def _invoke_cli_command(self, *, cwd: Path, func_name: str, kwargs: dict[str, Any]) -> _CliInvocationResult:
+        from .cli import app as cli_app
+
+        target = getattr(cli_app, func_name)
+        stdout_buffer = io.StringIO()
+        stderr_buffer = io.StringIO()
+        prior_cwd = Path.cwd()
+        try:
+            os.chdir(cwd)
+            with redirect_stdout(stdout_buffer), redirect_stderr(stderr_buffer):
+                try:
+                    target(**kwargs)
+                    exit_code = 0
+                except typer.Exit as exc:
+                    exit_code = 0 if exc.exit_code in (None, 0) else int(exc.exit_code)
+        finally:
+            os.chdir(prior_cwd)
+        return _CliInvocationResult(
+            returncode=exit_code,
+            stdout=stdout_buffer.getvalue(),
+            stderr=stderr_buffer.getvalue(),
+        )
+
+    def _fetch_candidate_events(self) -> list[dict[str, Any]]:
+        url, key = self._require_supabase_config()
+        rows = _postgrest_request(
+            method="GET",
+            url=f"{url}/rest/v1/devflow_execution_events?select=*&status=eq.queued&run_id=is.null&order=occurred_at.asc&limit=25",
+            key=key,
+        )
+        if not isinstance(rows, list):
+            return []
+        return [dict(row) for row in rows if isinstance(row, dict)]
+
+    def _claim_event(self, *, event_id: str, workflow_key: str) -> dict[str, Any] | None:
+        url, key = self._require_supabase_config()
+        rows = _postgrest_request(
+            method="PATCH",
+            url=f"{url}/rest/v1/devflow_execution_events?id=eq.{quote(event_id)}&status=eq.queued&run_id=is.null",
+            key=key,
+            body={
+                "status": "processing",
+                "stage": workflow_key,
+                "error": None,
+            },
+            prefer="return=representation",
+        )
+        if not isinstance(rows, list) or not rows:
+            return None
+        row = rows[0]
+        if not isinstance(row, dict):
+            return None
+        return dict(row)
+
+    def _fetch_project(self, *, project_id: str) -> dict[str, Any]:
+        url, key = self._require_supabase_config()
+        rows = _postgrest_request(
+            method="GET",
+            url=f"{url}/rest/v1/devflow_projects?select=*&id=eq.{quote(project_id)}&limit=1",
+            key=key,
+        )
+        if not isinstance(rows, list) or not rows or not isinstance(rows[0], dict):
+            raise RuntimeError(f"DevFlow project {project_id} not found")
+        return dict(rows[0])
+
+    def _insert_execution_run(self, payload: dict[str, Any]) -> dict[str, Any]:
+        url, key = self._require_supabase_config()
+        rows = _postgrest_request(
+            method="POST",
+            url=f"{url}/rest/v1/devflow_execution_runs",
+            key=key,
+            body=payload,
+            prefer="return=representation",
+        )
+        if not isinstance(rows, list) or not rows or not isinstance(rows[0], dict):
+            raise RuntimeError("Failed to insert devflow_execution_runs row")
+        return dict(rows[0])
+
+    def _insert_execution_step_run(self, payload: dict[str, Any]) -> dict[str, Any]:
+        url, key = self._require_supabase_config()
+        rows = _postgrest_request(
+            method="POST",
+            url=f"{url}/rest/v1/devflow_execution_step_runs",
+            key=key,
+            body=payload,
+            prefer="return=representation",
+        )
+        if not isinstance(rows, list) or not rows or not isinstance(rows[0], dict):
+            raise RuntimeError("Failed to insert devflow_execution_step_runs row")
+        return dict(rows[0])
+
+    def _update_execution_run(self, *, execution_run_id: int, fields: dict[str, Any]) -> None:
+        url, key = self._require_supabase_config()
+        _postgrest_request(
+            method="PATCH",
+            url=f"{url}/rest/v1/devflow_execution_runs?id=eq.{execution_run_id}",
+            key=key,
+            body=fields,
+        )
+
+    def _update_execution_step_run(self, *, step_id: int, fields: dict[str, Any]) -> None:
+        url, key = self._require_supabase_config()
+        _postgrest_request(
+            method="PATCH",
+            url=f"{url}/rest/v1/devflow_execution_step_runs?id=eq.{step_id}",
+            key=key,
+            body=fields,
+        )
+
+    def _update_event(self, *, event_id: str, fields: dict[str, Any]) -> None:
+        url, key = self._require_supabase_config()
+        _postgrest_request(
+            method="PATCH",
+            url=f"{url}/rest/v1/devflow_execution_events?id=eq.{quote(event_id)}",
+            key=key,
+            body=fields,
+        )
+
+    def _update_project(self, *, project_id: str, fields: dict[str, Any]) -> None:
+        url, key = self._require_supabase_config()
+        _postgrest_request(
+            method="PATCH",
+            url=f"{url}/rest/v1/devflow_projects?id=eq.{quote(project_id)}",
+            key=key,
+            body=fields,
+        )
+
+    def _merge_event_payload(self, *, event: dict[str, Any], extra_payload: dict[str, Any]) -> dict[str, Any]:
+        merged = dict(event.get("payload") or {})
+        merged.update(extra_payload)
+        return merged
+
+    def _require_supabase_config(self) -> tuple[str, str]:
+        config = _resolve_supabase_rest_config()
+        if config is None:
+            raise RuntimeError("Supabase REST config unavailable for DevFlow event worker")
+        return config
+
+
+class SupabaseRealtimeListener:
+    """Supabase Realtime WebSocket listener for a single table's INSERT events.
+
+    Uses the Phoenix channel protocol (Supabase Realtime v1/v2 wire format).
+    Runs in a background daemon thread. When an INSERT is received on the
+    subscribed table, the ``on_event`` callback is invoked from the listener
+    thread.
+
+    If the connection cannot be established or drops, the listener retries
+    after a back-off delay without raising — the caller should treat
+    ``is_connected`` as informational only and always maintain a polling
+    fallback.
+
+    Usage::
+
+        listener = SupabaseRealtimeListener(
+            url="https://...supabase.co",
+            key="service-role-key",
+            table="devflow_execution_events",
+            on_event=my_callback,
+        )
+        listener.start()
+        ...
+        listener.stop()
+    """
+
+    _HEARTBEAT_INTERVAL_S: float = 25.0
+    _RECONNECT_DELAY_S: float = 5.0
+    _RECV_TIMEOUT_S: float = 1.0
+
+    def __init__(
+        self,
+        *,
+        url: str,
+        key: str,
+        table: str = "devflow_execution_events",
+        on_event: Callable[[], None],
+    ) -> None:
+        self._url = url.rstrip("/")
+        self._key = key
+        self._table = table
+        self._on_event = on_event
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._connected = False
+        self._ref_counter = 0
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def start(self) -> None:
+        """Start the listener in a background daemon thread."""
+        if self._thread is not None and self._thread.is_alive():
+            return
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self._run, daemon=True, name="supabase-realtime-listener")
+        self._thread.start()
+
+    def stop(self, timeout: float = 5.0) -> None:
+        """Signal the listener to stop and wait for the thread to exit."""
+        self._stop_event.set()
+        if self._thread is not None:
+            self._thread.join(timeout=timeout)
+
+    @property
+    def is_connected(self) -> bool:
+        return self._connected
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _next_ref(self) -> str:
+        self._ref_counter += 1
+        return str(self._ref_counter)
+
+    def _ws_url(self) -> str:
+        base = self._url
+        if base.startswith("https://"):
+            base = "wss://" + base[8:]
+        elif base.startswith("http://"):
+            base = "ws://" + base[7:]
+        return f"{base}/realtime/v1/websocket?apikey={self._key}&vsn=1.0.0"
+
+    def _run(self) -> None:
+        """Thread entry-point: runs the asyncio event loop."""
+        asyncio.run(self._listen_loop())
+
+    async def _listen_loop(self) -> None:
+        """Outer reconnect loop — keeps retrying until stop() is called."""
+        try:
+            import websockets  # type: ignore[import-untyped]
+        except ImportError:
+            logger.warning("devflow-realtime: websockets package not available; falling back to polling-only mode")
+            return
+
+        ws_url = self._ws_url()
+        while not self._stop_event.is_set():
+            try:
+                async with websockets.connect(
+                    ws_url,
+                    open_timeout=10,
+                    close_timeout=5,
+                    additional_headers={"apikey": self._key, "Authorization": f"Bearer {self._key}"},
+                ) as ws:
+                    self._connected = True
+                    logger.debug("devflow-realtime: connected to %s", ws_url)
+                    await self._session(ws)
+            except Exception as exc:
+                logger.debug("devflow-realtime: connection error: %s", exc)
+            finally:
+                self._connected = False
+
+            if not self._stop_event.is_set():
+                # Wait before reconnecting, but wake immediately if stop() is called.
+                await asyncio.sleep(self._RECONNECT_DELAY_S)
+
+    async def _session(self, ws: Any) -> None:
+        """Single WebSocket session: join channel, handle events, send heartbeats."""
+        channel_topic = f"realtime:public:{self._table}"
+        join_ref = self._next_ref()
+
+        join_msg = json.dumps(
+            {
+                "topic": channel_topic,
+                "event": "phx_join",
+                "payload": {
+                    "config": {
+                        "broadcast": {"ack": False, "self": False},
+                        "presence": {"key": ""},
+                        "postgres_changes": [
+                            {"event": "INSERT", "schema": "public", "table": self._table}
+                        ],
+                    }
+                },
+                "ref": join_ref,
+                "join_ref": join_ref,
+            }
+        )
+        await ws.send(join_msg)
+
+        heartbeat_task = asyncio.create_task(self._heartbeat(ws))
+        try:
+            await self._receive_loop(ws)
+        finally:
+            heartbeat_task.cancel()
+            with suppress(Exception):
+                await heartbeat_task
+
+    async def _heartbeat(self, ws: Any) -> None:
+        """Send Phoenix heartbeat messages every HEARTBEAT_INTERVAL_S seconds."""
+        while True:
+            await asyncio.sleep(self._HEARTBEAT_INTERVAL_S)
+            if self._stop_event.is_set():
+                break
+            try:
+                hb = json.dumps({"topic": "phoenix", "event": "heartbeat", "payload": {}, "ref": self._next_ref()})
+                await ws.send(hb)
+            except Exception:
+                break
+
+    async def _receive_loop(self, ws: Any) -> None:
+        """Read messages from the WebSocket and dispatch callbacks."""
+        while not self._stop_event.is_set():
+            try:
+                raw = await asyncio.wait_for(ws.recv(), timeout=self._RECV_TIMEOUT_S)
+            except asyncio.TimeoutError:
+                continue
+            except Exception:
+                # Connection dropped — exit so the outer loop can reconnect.
+                return
+
+            try:
+                msg = json.loads(raw)
+            except Exception:
+                continue
+
+            event = msg.get("event")
+            if event == "postgres_changes":
+                # Supabase Realtime v2: payload.data.type == "INSERT"
+                data = (msg.get("payload") or {}).get("data") or {}
+                change_type = str(data.get("type") or "").upper()
+                if change_type == "INSERT":
+                    logger.debug("devflow-realtime: INSERT on %s — waking dispatch loop", self._table)
+                    try:
+                        self._on_event()
+                    except Exception:
+                        pass
+            elif event == "phx_error":
+                logger.debug("devflow-realtime: received phx_error — reconnecting")
+                return
+            elif event == "system":
+                # Supabase Realtime v2 system messages (subscription confirmations etc.)
+                status = str((msg.get("payload") or {}).get("status") or "").lower()
+                if status == "error":
+                    logger.debug("devflow-realtime: system error — reconnecting")
+                    return
+
+
+class DevflowEventWorkerLoopService:
+    def __init__(
+        self,
+        *,
+        service: DevflowEventWorkerService | None = None,
+        sleep_seconds: float = 3.0,
+        max_iterations: int | None = None,
+        use_realtime: bool = True,
+    ) -> None:
+        self.service = service or DevflowEventWorkerService()
+        self.sleep_seconds = sleep_seconds
+        self.max_iterations = max_iterations
+        self.use_realtime = use_realtime
+        # Event set by the realtime listener to wake the dispatch loop immediately.
+        self._wakeup = threading.Event()
+
+    def _on_realtime_event(self) -> None:
+        """Called from the realtime listener thread when a new INSERT arrives."""
+        self._wakeup.set()
+
+    def _build_realtime_listener(self) -> SupabaseRealtimeListener | None:
+        """Attempt to create a realtime listener; return None if config is unavailable."""
+        if not self.use_realtime:
+            return None
+        config = _resolve_supabase_rest_config()
+        if config is None:
+            return None
+        url, key = config
+        return SupabaseRealtimeListener(url=url, key=key, on_event=self._on_realtime_event)
+
+    def run_once(self) -> DevflowEventWorkerLoopResult:
+        try:
+            result = self.service.dispatch_next_event()
+        except Exception:
+            return DevflowEventWorkerLoopResult(failed=1, idle=False)
+        if result is None:
+            return DevflowEventWorkerLoopResult(idle=True)
+        return DevflowEventWorkerLoopResult(processed=1, idle=False)
+
+    def run_forever(self) -> DevflowEventWorkerLoopResult:
+        processed = 0
+        failed = 0
+        iterations = 0
+
+        listener = self._build_realtime_listener()
+        if listener is not None:
+            listener.start()
+            logger.debug("devflow-realtime: listener started (realtime-enabled loop)")
+
+        try:
+            while True:
+                outcome = self.run_once()
+                iterations += 1
+                processed += outcome.processed
+                failed += outcome.failed
+                if self.max_iterations is not None and iterations >= self.max_iterations:
+                    return DevflowEventWorkerLoopResult(processed=processed, failed=failed, idle=outcome.idle)
+                if outcome.idle:
+                    # Wait up to sleep_seconds, but wake early if realtime delivers an event.
+                    self._wakeup.wait(timeout=self.sleep_seconds)
+                    self._wakeup.clear()
+        finally:
+            if listener is not None:
+                listener.stop()