multi-forge 0.5.0__tar.gz → 0.7.0__tar.gz

{multi_forge-0.5.0 → multi_forge-0.7.0}/.gitignore

@@ -59,10 +59,25 @@ ipython_config.py
 __pypackages__/
 
 # Claude Code local artifacts (machine-specific)
-.claude/
+.claude/*
+!.claude/commands/
+.claude/commands/*
+!.claude/commands/gather-context.md
+!.claude/commands/refactor_audit.md
+!.claude/commands/simplicity_audit.md
+
+# Codex local artifacts
+.agents/*
+!.agents/skills/
+.agents/skills/*
+!.agents/skills/gather-context/
+!.agents/skills/gather-context/SKILL.md
+!.agents/skills/refactor-audit/
+!.agents/skills/refactor-audit/SKILL.md
+!.agents/skills/simplicity-audit/
+!.agents/skills/simplicity-audit/SKILL.md
 
 # Codex local config
-.agents
 .codex/
 
 # Forge local artifacts (machine-specific, may contain sensitive transcript snippets)

{multi_forge-0.5.0 → multi_forge-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multi-forge
-Version: 0.5.0
+Version: 0.7.0
 Summary: Multi-runtime agent toolkit: proxy routing, cost control, session management, policy enforcement, and workflow orchestration
 Project-URL: Homepage, https://github.com/hapa1i/multi-forge
 Project-URL: Repository, https://github.com/hapa1i/multi-forge
@@ -56,15 +56,18 @@ Description-Content-Type: text/markdown
 **Multi-runtime agent toolkit: proxy routing, cost control, session management, and policy enforcement for coding
 agents.**
 
-Forge sits between you and your coding agent (Claude Code today, Codex and Gemini next), adding persistent sessions,
-multi-provider model routing, cost visibility with spend caps, and autonomous verification. You run
-`forge session start` instead of `claude`, and Forge handles the rest -- routing to your chosen model provider, tracking
-state across sessions, and enforcing policies.
+Forge sits between you and your coding agent (Claude Code by default, with Codex as an alternate runtime and Gemini
+next), adding persistent sessions, multi-provider model routing, cost visibility with spend caps, and autonomous
+verification. You run `forge session start` instead of `claude`; Forge then routes to your chosen model provider, tracks
+state across sessions, and enforces configured policies.
 
 ```bash
 # Use Claude with session tracking (no proxy needed)
 forge session start
 
+# Or run a different runtime entirely -- Codex as an alternate frontend
+forge session start --runtime codex    # interactive TUI; hooks/policy need a one-time Codex trust enrollment
+
 # Or route through different model providers (after creating proxies -- see Quick Start)
 forge session start planner --proxy openrouter-openai    # GPT for planning
 forge session start --proxy openrouter-gemini            # Gemini for review
@@ -146,7 +149,7 @@ forge extension enable
 # Launch Claude with session tracking (no proxy needed)
 forge session start
 
-# Or with multi-model routing via OpenRouter (easiest, no LiteLLM):
+# Or with multi-model routing via OpenRouter (no LiteLLM):
 forge auth login -c openrouter                        # Store OPENROUTER_API_KEY
 forge proxy create openrouter-anthropic               # Create and start a Claude-family proxy
 forge session start --proxy openrouter-anthropic
@@ -173,6 +176,12 @@ Existing pre-OSS Forge installs are not supported in-place. If upgrading:
 4. If you had `FORGE_CONTEXT_LIMIT` in your shell config, remove it. Use `CLAUDE_CODE_AUTO_COMPACT_WINDOW` for native
    Claude Code behavior, or `forge config set context_limit=N` for Forge proxy fallback.
 
+> [!NOTE]
+> **Corrupt state?** If Forge reports that its state is corrupt, it names the offending file and stops -- it never
+> silently runs on bad state. To recover, run `forge clean` to detect and remove corrupt Forge-written state. For a full
+> reset, delete `.forge` (project-local) or `~/.forge` (global) and re-run `forge extension enable`. Forge recreates
+> whatever it needs on the next run. Your own files and `proxy.yaml` config are never touched by `forge clean`.
+
 ### Example Workflow: Plan, Execute, Review
 
 With proxies configured, a typical feature workflow looks like:
@@ -198,37 +207,39 @@ forge session fork planner --into ../executor-worktree  # Path to executor's wor
 git push origin feature-branch
 ```
 
-Each step uses the best model for the job. The `--supervise` flag wires the planner as a semantic supervisor -- every
-code change is checked against the approved plan. Sessions track artifacts and transcripts automatically, so context
-flows across forks and resumes. See the [end-user guide](docs/end-user/) for the full tour, or run `/forge:walkthrough`
-inside Claude Code for an interactive walkthrough.
+This workflow can assign different model roles to planning, execution, and review. The `--supervise` flag wires the
+planner as a semantic supervisor -- every code change is checked against the approved plan. Sessions track artifacts and
+transcripts automatically, so forks and resumes can reuse that context. See the [end-user guide](docs/end-user/) for the
+full tour, or run `/forge:walkthrough` inside Claude Code for an interactive walkthrough.
 
 ## CLI Overview
 
-| Command Group          | Purpose                                      |
-| ---------------------- | -------------------------------------------- |
-| `forge claude`         | Bare launch, settings preset management      |
-| `forge session`        | Named sessions, worktrees, resume, fork      |
-| `forge memory`         | Project memory passports, shadow proposals   |
-| `forge proxy`          | Model routing, templates, tier mappings      |
-| `forge authentication` | Credential management (`credentials.yaml`)   |
-| `forge policy`         | Policy enforcement, plan supervision         |
-| `forge workflow`       | Workflow runners (panel, analyze, debate)    |
-| `forge search`         | Transcript search across sessions            |
-| `forge config`         | Runtime preferences (`~/.forge/config.yaml`) |
-| `forge extension`      | Enable/sync/disable extensions               |
-| `forge info`           | System health and installation info          |
+| Command Group     | Purpose                                      |
+| ----------------- | -------------------------------------------- |
+| `forge claude`    | Bare launch, settings preset management      |
+| `forge session`   | Named sessions, worktrees, resume, fork      |
+| `forge memory`    | Project memory passports, shadow proposals   |
+| `forge proxy`     | Model routing, templates, tier mappings      |
+| `forge auth`      | Credential management (`credentials.yaml`)   |
+| `forge policy`    | Policy enforcement, plan supervision         |
+| `forge workflow`  | Workflow runners (panel, analyze, debate)    |
+| `forge search`    | Transcript search across sessions            |
+| `forge config`    | Runtime preferences (`~/.forge/config.yaml`) |
+| `forge extension` | Enable/sync/disable extensions               |
+| `forge info`      | System health and installation info          |
 
 Run `forge <command> --help` for details on any command.
 
 ## Documentation
 
-| Audience         | Location                           | Contents                                             |
-| ---------------- | ---------------------------------- | ---------------------------------------------------- |
-| **Users**        | [docs/end-user/](docs/end-user/)   | Tour, guides for sessions, proxies, policies, ...    |
-| **Developers**   | [docs/developer/](docs/developer/) | Setup, coding standards, testing guidelines          |
-| **Architecture** | [docs/design.md](docs/design.md)   | System narrative, data flow, invariants              |
-| **Work Board**   | [docs/board/](docs/board/)         | Cards, checklists, change log, implementation memory |
+| Audience            | Location                                             | Contents                                              |
+| ------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
+| **Users**           | [docs/end-user/](docs/end-user/)                     | Tour, guides for sessions, proxies, policies, ...     |
+| **Developers**      | [docs/developer/](docs/developer/)                   | Setup, coding standards, testing guidelines           |
+| **Architecture**    | [docs/design.md](docs/design.md)                     | Core system narrative, data flow, invariants          |
+| **Workflow design** | [docs/design_workflows.md](docs/design_workflows.md) | Policy, skills, workflow runners, memory architecture |
+| **CLI reference**   | [docs/cli_reference.md](docs/cli_reference.md)       | Terminal and direct-command inventory                 |
+| **Work Board**      | [docs/board/](docs/board/)                           | Cards, checklists, change log, implementation memory  |
 
 ## Contributing
 

{multi_forge-0.5.0 → multi_forge-0.7.0}/README.md

@@ -15,15 +15,18 @@
 **Multi-runtime agent toolkit: proxy routing, cost control, session management, and policy enforcement for coding
 agents.**
 
-Forge sits between you and your coding agent (Claude Code today, Codex and Gemini next), adding persistent sessions,
-multi-provider model routing, cost visibility with spend caps, and autonomous verification. You run
-`forge session start` instead of `claude`, and Forge handles the rest -- routing to your chosen model provider, tracking
-state across sessions, and enforcing policies.
+Forge sits between you and your coding agent (Claude Code by default, with Codex as an alternate runtime and Gemini
+next), adding persistent sessions, multi-provider model routing, cost visibility with spend caps, and autonomous
+verification. You run `forge session start` instead of `claude`; Forge then routes to your chosen model provider, tracks
+state across sessions, and enforces configured policies.
 
 ```bash
 # Use Claude with session tracking (no proxy needed)
 forge session start
 
+# Or run a different runtime entirely -- Codex as an alternate frontend
+forge session start --runtime codex    # interactive TUI; hooks/policy need a one-time Codex trust enrollment
+
 # Or route through different model providers (after creating proxies -- see Quick Start)
 forge session start planner --proxy openrouter-openai    # GPT for planning
 forge session start --proxy openrouter-gemini            # Gemini for review
@@ -105,7 +108,7 @@ forge extension enable
 # Launch Claude with session tracking (no proxy needed)
 forge session start
 
-# Or with multi-model routing via OpenRouter (easiest, no LiteLLM):
+# Or with multi-model routing via OpenRouter (no LiteLLM):
 forge auth login -c openrouter                        # Store OPENROUTER_API_KEY
 forge proxy create openrouter-anthropic               # Create and start a Claude-family proxy
 forge session start --proxy openrouter-anthropic
@@ -132,6 +135,12 @@ Existing pre-OSS Forge installs are not supported in-place. If upgrading:
 4. If you had `FORGE_CONTEXT_LIMIT` in your shell config, remove it. Use `CLAUDE_CODE_AUTO_COMPACT_WINDOW` for native
    Claude Code behavior, or `forge config set context_limit=N` for Forge proxy fallback.
 
+> [!NOTE]
+> **Corrupt state?** If Forge reports that its state is corrupt, it names the offending file and stops -- it never
+> silently runs on bad state. To recover, run `forge clean` to detect and remove corrupt Forge-written state. For a full
+> reset, delete `.forge` (project-local) or `~/.forge` (global) and re-run `forge extension enable`. Forge recreates
+> whatever it needs on the next run. Your own files and `proxy.yaml` config are never touched by `forge clean`.
+
 ### Example Workflow: Plan, Execute, Review
 
 With proxies configured, a typical feature workflow looks like:
@@ -157,37 +166,39 @@ forge session fork planner --into ../executor-worktree  # Path to executor's wor
 git push origin feature-branch
 ```
 
-Each step uses the best model for the job. The `--supervise` flag wires the planner as a semantic supervisor -- every
-code change is checked against the approved plan. Sessions track artifacts and transcripts automatically, so context
-flows across forks and resumes. See the [end-user guide](docs/end-user/) for the full tour, or run `/forge:walkthrough`
-inside Claude Code for an interactive walkthrough.
+This workflow can assign different model roles to planning, execution, and review. The `--supervise` flag wires the
+planner as a semantic supervisor -- every code change is checked against the approved plan. Sessions track artifacts and
+transcripts automatically, so forks and resumes can reuse that context. See the [end-user guide](docs/end-user/) for the
+full tour, or run `/forge:walkthrough` inside Claude Code for an interactive walkthrough.
 
 ## CLI Overview
 
-| Command Group          | Purpose                                      |
-| ---------------------- | -------------------------------------------- |
-| `forge claude`         | Bare launch, settings preset management      |
-| `forge session`        | Named sessions, worktrees, resume, fork      |
-| `forge memory`         | Project memory passports, shadow proposals   |
-| `forge proxy`          | Model routing, templates, tier mappings      |
-| `forge authentication` | Credential management (`credentials.yaml`)   |
-| `forge policy`         | Policy enforcement, plan supervision         |
-| `forge workflow`       | Workflow runners (panel, analyze, debate)    |
-| `forge search`         | Transcript search across sessions            |
-| `forge config`         | Runtime preferences (`~/.forge/config.yaml`) |
-| `forge extension`      | Enable/sync/disable extensions               |
-| `forge info`           | System health and installation info          |
+| Command Group     | Purpose                                      |
+| ----------------- | -------------------------------------------- |
+| `forge claude`    | Bare launch, settings preset management      |
+| `forge session`   | Named sessions, worktrees, resume, fork      |
+| `forge memory`    | Project memory passports, shadow proposals   |
+| `forge proxy`     | Model routing, templates, tier mappings      |
+| `forge auth`      | Credential management (`credentials.yaml`)   |
+| `forge policy`    | Policy enforcement, plan supervision         |
+| `forge workflow`  | Workflow runners (panel, analyze, debate)    |
+| `forge search`    | Transcript search across sessions            |
+| `forge config`    | Runtime preferences (`~/.forge/config.yaml`) |
+| `forge extension` | Enable/sync/disable extensions               |
+| `forge info`      | System health and installation info          |
 
 Run `forge <command> --help` for details on any command.
 
 ## Documentation
 
-| Audience         | Location                           | Contents                                             |
-| ---------------- | ---------------------------------- | ---------------------------------------------------- |
-| **Users**        | [docs/end-user/](docs/end-user/)   | Tour, guides for sessions, proxies, policies, ...    |
-| **Developers**   | [docs/developer/](docs/developer/) | Setup, coding standards, testing guidelines          |
-| **Architecture** | [docs/design.md](docs/design.md)   | System narrative, data flow, invariants              |
-| **Work Board**   | [docs/board/](docs/board/)         | Cards, checklists, change log, implementation memory |
+| Audience            | Location                                             | Contents                                              |
+| ------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
+| **Users**           | [docs/end-user/](docs/end-user/)                     | Tour, guides for sessions, proxies, policies, ...     |
+| **Developers**      | [docs/developer/](docs/developer/)                   | Setup, coding standards, testing guidelines           |
+| **Architecture**    | [docs/design.md](docs/design.md)                     | Core system narrative, data flow, invariants          |
+| **Workflow design** | [docs/design_workflows.md](docs/design_workflows.md) | Policy, skills, workflow runners, memory architecture |
+| **CLI reference**   | [docs/cli_reference.md](docs/cli_reference.md)       | Terminal and direct-command inventory                 |
+| **Work Board**      | [docs/board/](docs/board/)                           | Cards, checklists, change log, implementation memory  |
 
 ## Contributing
 

{multi_forge-0.5.0 → multi_forge-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "multi-forge"
-version = "0.5.0"
+version = "0.7.0"
 description = "Multi-runtime agent toolkit: proxy routing, cost control, session management, policy enforcement, and workflow orchestration"
 readme = "README.md"
 license = "Apache-2.0"
@@ -122,16 +122,20 @@ disallow_untyped_calls = false
 constraint-dependencies = [
     "filelock>=3.20.3",
     "virtualenv>=20.36.1",
-    "aiohttp>=3.14.0",
-    "cryptography>=46.0.7",
-    "python-multipart>=0.0.26",
+    "aiohttp>=3.14.1",
+    "cryptography>=48.0.1",
+    "python-multipart>=0.0.31",
     "Pygments>=2.20.0",
-    "starlette>=1.0.1",
+    "PyJWT>=2.13.0",
+    "starlette>=1.3.1",
 ]
-# litellm pins fastapi-sso<0.17.0 but 0.16.x has a CSRF vulnerability.
-# Forge doesn't use fastapi-sso directly; override to force the patched version.
+# litellm proxy extras can pin vulnerable transitive dependencies before
+# upstream metadata catches up. Forge doesn't use these directly; override to
+# force patched versions required by Dependabot alerts.
 override-dependencies = [
+    "cryptography>=48.0.1",
     "fastapi-sso>=0.19.0",
+    "python-multipart>=0.0.31",
 ]
 
 [dependency-groups]

{multi_forge-0.5.0 → multi_forge-0.7.0}/src/forge/__init__.py

@@ -1,3 +1,3 @@
 """Multi-Forge - Multi-runtime agent toolkit."""
 
-__version__ = "0.5.0"
+__version__ = "0.7.0"

{multi_forge-0.5.0 → multi_forge-0.7.0}/src/forge/backend/__init__.py

@@ -12,17 +12,40 @@ from pathlib import Path
 from typing import Literal
 
 from forge.backend.registry import (
-    BackendInstance,
+    ManagedBackendProcess,
     BackendRegistry,
     BackendRegistryStore,
 )
+from forge.backend.sources import (
+    BackendInstanceAmbiguousError,
+    BackendInstanceMatchKind,
+    BackendInstanceNotFoundError,
+    BackendInstanceResolution,
+    BackendInstanceResolutionError,
+    LocalBackendLifecycle,
+    ModelSource,
+    ModelSourceCapabilities,
+    ModelSourceCatalogError,
+    ModelSourceNotFoundError,
+    SourceEndpoint,
+    backend_kind_for_source,
+    get_model_source,
+    list_model_sources,
+    model_source_for_template,
+    required_env_vars_for_source,
+    resolve_backend_instance,
+    resolve_backend_instance_id,
+    resolve_model_source_id,
+    template_env_vars_by_template,
+    validate_model_sources,
+)
 
 
 @dataclass(frozen=True)
 class BackendEnsureResult:
     """Result of ensure_backend() operation."""
 
-    instance: BackendInstance
+    process: ManagedBackendProcess
     source: Literal["reuse", "start"]
 
 
@@ -30,35 +53,35 @@ class BackendAdapter(ABC):
     """Abstract base class for backend lifecycle management."""
 
     @abstractmethod
-    def start(self, backend_id: str, config_path: Path, port: int) -> BackendInstance:
-        """Start backend, return instance details.
+    def start(self, process_id: str, config_path: Path, port: int) -> ManagedBackendProcess:
+        """Start backend, return managed process details.
 
         Args:
-            backend_id: Unique instance ID (e.g., "litellm-4000")
+            process_id: Managed process ID (e.g., "litellm-4000")
             config_path: Path to backend config file
             port: Port number to bind
 
         Returns:
-            BackendInstance with PID and status
+            ManagedBackendProcess with PID and status
 
         Raises:
             BackendStartError: If backend fails to start
         """
 
     @abstractmethod
-    def stop(self, instance: BackendInstance) -> None:
+    def stop(self, process: ManagedBackendProcess) -> None:
         """Stop backend (best effort).
 
         Args:
-            instance: Backend instance to stop
+            process: Managed backend process to stop
         """
 
     @abstractmethod
-    def health_check(self, instance: BackendInstance) -> bool:
+    def health_check(self, process: ManagedBackendProcess) -> bool:
         """Check if backend is healthy.
 
         Args:
-            instance: Backend instance to check
+            process: Managed backend process to check
 
         Returns:
             True if healthy, False otherwise
@@ -90,16 +113,16 @@ class BackendManager:
         """
         self.adapters[adapter_type] = adapter
 
-    def ensure_backend(self, backend_id: str, adapter_type: str, port: int) -> BackendEnsureResult:
+    def ensure_backend(self, process_id: str, adapter_type: str, port: int) -> BackendEnsureResult:
         """Ensure backend is running (reuse -> start pattern).
 
         Args:
-            backend_id: Backend instance ID (e.g., "litellm-4000")
+            process_id: Managed process ID (e.g., "litellm-4000")
             adapter_type: Adapter type (e.g., "litellm")
             port: Port number
 
         Returns:
-            BackendEnsureResult with instance and source ("reuse" or "start")
+            BackendEnsureResult with process and source ("reuse" or "start")
 
         Raises:
             BackendStartError: If backend fails to start
@@ -111,64 +134,86 @@ class BackendManager:
             raise ValueError(f"No adapter registered for type: {adapter_type}")
 
         registry = self.registry_store.read()
-        existing = registry.backends.get(backend_id)
+        existing = registry.processes.get(process_id)
 
         if existing:
             # health_check works with or without PID (port probe fallback)
             if adapter.health_check(existing):
-                return BackendEnsureResult(instance=existing, source="reuse")
+                return BackendEnsureResult(process=existing, source="reuse")
 
             def remove_dead(reg: BackendRegistry) -> None:
-                reg.backends.pop(backend_id, None)
+                reg.processes.pop(process_id, None)
 
             self.registry_store.update(timeout_s=10.0, mutate=remove_dead)
 
         config_path = get_backend_config_path(adapter_type)
         if not config_path.exists():
             raise BackendStartError(
-                f"Backend config not found: {config_path}\n" f"Create it with: forge backend create {adapter_type}"
+                f"Backend config not found: {config_path}\n"
+                f"Create it with: forge model backend create {adapter_type}"
             )
 
-        instance = adapter.start(backend_id, config_path, port)
+        process = adapter.start(process_id, config_path, port)
 
-        def add_instance(reg: BackendRegistry) -> None:
-            reg.backends[backend_id] = instance
+        def add_process(reg: BackendRegistry) -> None:
+            reg.processes[process_id] = process
 
-        self.registry_store.update(timeout_s=10.0, mutate=add_instance)
+        self.registry_store.update(timeout_s=10.0, mutate=add_process)
 
-        return BackendEnsureResult(instance=instance, source="start")
+        return BackendEnsureResult(process=process, source="start")
 
-    def stop_backend(self, backend_id: str) -> None:
+    def stop_backend(self, process_id: str) -> None:
         """Stop backend and remove from registry.
 
         Args:
-            backend_id: Backend instance ID
+            process_id: Managed process ID
 
         Raises:
-            ValueError: If backend not found
+            ValueError: If managed process not found
         """
         registry = self.registry_store.read()
-        instance = registry.backends.get(backend_id)
+        process = registry.processes.get(process_id)
 
-        if not instance:
-            raise ValueError(f"Backend not found: {backend_id}")
+        if not process:
+            raise ValueError(f"Managed process not found: {process_id}")
 
-        adapter = self.adapters.get(instance.adapter_type)
+        adapter = self.adapters.get(process.adapter_type)
         if adapter:
-            adapter.stop(instance)
+            adapter.stop(process)
 
-        def remove_instance(reg: BackendRegistry) -> None:
-            reg.backends.pop(backend_id, None)
+        def remove_process(reg: BackendRegistry) -> None:
+            reg.processes.pop(process_id, None)
 
-        self.registry_store.update(timeout_s=10.0, mutate=remove_instance)
+        self.registry_store.update(timeout_s=10.0, mutate=remove_process)
 
 
 __all__ = [
     "BackendAdapter",
     "BackendEnsureResult",
-    "BackendInstance",
+    "BackendInstanceAmbiguousError",
+    "ManagedBackendProcess",
+    "BackendInstanceMatchKind",
     "BackendManager",
+    "BackendInstanceNotFoundError",
+    "BackendInstanceResolution",
+    "BackendInstanceResolutionError",
     "BackendRegistry",
     "BackendRegistryStore",
     "BackendStartError",
+    "LocalBackendLifecycle",
+    "ModelSource",
+    "ModelSourceCapabilities",
+    "ModelSourceCatalogError",
+    "ModelSourceNotFoundError",
+    "SourceEndpoint",
+    "backend_kind_for_source",
+    "get_model_source",
+    "list_model_sources",
+    "model_source_for_template",
+    "required_env_vars_for_source",
+    "resolve_backend_instance",
+    "resolve_backend_instance_id",
+    "resolve_model_source_id",
+    "template_env_vars_by_template",
+    "validate_model_sources",
 ]

{multi_forge-0.5.0 → multi_forge-0.7.0}/src/forge/backend/adapters/litellm.py

@@ -19,7 +19,7 @@ from pathlib import Path
 import httpx
 
 from forge.backend import BackendAdapter, BackendStartError
-from forge.backend.registry import BackendInstance
+from forge.backend.registry import ManagedBackendProcess
 from forge.core.paths import get_forge_home
 from forge.core.state import now_iso
 
@@ -67,16 +67,16 @@ class LiteLLMAdapter(BackendAdapter):
 
         return False
 
-    def start(self, backend_id: str, config_path: Path, port: int) -> BackendInstance:
+    def start(self, process_id: str, config_path: Path, port: int) -> ManagedBackendProcess:
         """Start LiteLLM backend.
 
         Args:
-            backend_id: Backend instance ID (e.g., "litellm-4000")
+            process_id: Managed process ID (e.g., "litellm-4000")
             config_path: Path to LiteLLM config file
             port: Port number to bind
 
         Returns:
-            BackendInstance with PID and status
+            ManagedBackendProcess with PID and status
 
         Raises:
             BackendStartError: If backend fails to start
@@ -114,8 +114,8 @@ class LiteLLMAdapter(BackendAdapter):
                 pass  # Process already exited
             raise BackendStartError(f"LiteLLM failed to start on port {port}\nCheck logs: {log_file}")
 
-        return BackendInstance(
-            backend_id=backend_id,
+        return ManagedBackendProcess(
+            process_id=process_id,
             adapter_type="litellm",
             port=port,
             pid=proc.pid,
@@ -123,34 +123,34 @@ class LiteLLMAdapter(BackendAdapter):
             created_at=now_iso(),
         )
 
-    def stop(self, instance: BackendInstance) -> None:
+    def stop(self, process: ManagedBackendProcess) -> None:
         """Stop LiteLLM backend (best effort).
 
         Args:
-            instance: Backend instance to stop
+            process: Managed backend process to stop
         """
-        if instance.pid is None:
+        if process.pid is None:
             return
 
         try:
-            os.kill(instance.pid, 15)  # SIGTERM
+            os.kill(process.pid, 15)  # SIGTERM
         except (ProcessLookupError, PermissionError):
             pass
 
-    def health_check(self, instance: BackendInstance) -> bool:
+    def health_check(self, process: ManagedBackendProcess) -> bool:
         """Check if LiteLLM backend is healthy.
 
         Uses /health/liveliness for fast checks (~5ms) rather than the full
         /health endpoint which contacts all model providers (~5-10s).
 
         Args:
-            instance: Backend instance to check
+            process: Managed backend process to check
 
         Returns:
             True if healthy, False otherwise
         """
         try:
-            url = f"http://localhost:{instance.port}/health/liveliness"
+            url = f"http://localhost:{process.port}/health/liveliness"
             with httpx.Client(timeout=httpx.Timeout(2.0)) as client:
                 response = client.get(url)
                 return response.status_code == 200