misterdev 0.2.0__py3-none-any.whl

misterdev/core/execution/governance.py

@@ -0,0 +1,283 @@
+"""Governance layer: risk classification + approval gates (opt-in).
+
+Classifies a shell command (or a described action) as *risky* when it matches a
+destructive, irreversible, or paid operation — ``rm -rf``, ``git push --force``,
+``DROP TABLE``/``DROP DATABASE``, ``kubectl delete``, ``terraform apply``/
+``destroy``, cloud-CLI ``delete``/``rm``, ``docker rmi``/``system prune``,
+deploy/publish commands, and ``curl ... | sh`` pipe-to-shell. Ordinary build,
+test, and lint commands (``cargo test``, ``pytest -q``, ``npm run build``,
+``ruff check``, ``true``/``false``) classify as SAFE.
+
+Design mirrors :mod:`misterdev.core.context.lsp` / ``container`` / ``mcp``:
+strictly opt-in (``orchestrator.governance`` is off by default), never raises
+into the caller, and a no-op when off so behavior is byte-identical to today.
+
+When ON, :class:`GovernancePolicy.authorize` is consulted by the command seam:
+- SAFE actions are always authorized.
+- A risky action in *autonomous* (non-interactive) mode is REFUSED unless
+  ``governance.auto_approve`` is set, and an escalation is recorded.
+- A risky action in *interactive* mode prompts the operator (the prompt callable
+  is injected so tests stay deterministic and the loop never hangs on stdin).
+
+The classifier is intentionally precise: a false positive on a normal build
+command would block real builds, so patterns are anchored to the destructive
+*verb* (e.g. ``rm`` with a recursive/force flag, ``delete``/``destroy``
+subcommands of known tools), never to incidental substrings.
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import Callable, List, Optional, Tuple
+
+from misterdev.logging_setup import setup_logger
+
+logger = setup_logger(__name__)
+
+
+# Each entry: (compiled regex, human reason). Patterns match against the raw
+# command string. They are anchored to a destructive verb/flag combination so
+# ordinary build/test/lint commands cannot trip them. `re.IGNORECASE` is applied
+# uniformly; SQL keywords and CLI verbs are case-insensitive in practice.
+_RISK_RULES: Tuple[Tuple[str, str], ...] = (
+    # rm with a recursive OR force flag (combined or split): rm -rf, rm -r -f,
+    # rm --recursive, rm -fr. Plain `rm file` is NOT flagged (recoverable enough,
+    # and far too common to gate). The flag cluster must contain r or f.
+    (
+        r"\brm\s+(?:-[a-z]*[rf][a-z]*\b|--recursive\b|--force\b)",
+        "recursive/forced file removal (rm -rf)",
+    ),
+    # git push --force / -f / --force-with-lease (history rewrite is irreversible
+    # on the remote). A plain `git push` is gated separately below as a publish.
+    (
+        r"\bgit\s+push\b.*(?:--force\b|--force-with-lease\b|\s-f\b)",
+        "force push rewrites remote history",
+    ),
+    # plain git push (publishes to a remote; reversible but external side effect).
+    (r"\bgit\s+push\b", "git push publishes to a remote"),
+    # SQL destructive DDL: DROP TABLE / DROP DATABASE / DROP SCHEMA, TRUNCATE.
+    (r"\bdrop\s+(?:table|database|schema)\b", "SQL DROP destroys schema/data"),
+    (r"\btruncate\s+table\b", "SQL TRUNCATE deletes all rows"),
+    # kubectl delete (any resource).
+    (r"\bkubectl\s+delete\b", "kubectl delete removes cluster resources"),
+    # terraform apply / destroy (provisions or tears down real infrastructure).
+    (
+        r"\bterraform\s+(?:apply|destroy)\b",
+        "terraform apply/destroy mutates infrastructure",
+    ),
+    # Cloud CLIs with a delete/rm subcommand: aws ... rm/delete, gcloud ...
+    # delete, az ... delete. Anchored to the CLI name + a delete-family verb so
+    # read-only cloud commands (list/describe/get) are SAFE.
+    (
+        r"\baws\b[^|;&]*\b(?:rm|delete|delete-[a-z-]+|terminate-[a-z-]+)\b",
+        "aws delete/terminate is destructive",
+    ),
+    (r"\bgcloud\b[^|;&]*\bdelete\b", "gcloud delete is destructive"),
+    (r"\baz\b[^|;&]*\bdelete\b", "az delete is destructive"),
+    # docker/podman image removal and prune (reclaims/destroys images/volumes).
+    (r"\b(?:docker|podman)\s+rmi\b", "container image removal (rmi)"),
+    (
+        r"\b(?:docker|podman)\s+system\s+prune\b",
+        "docker system prune deletes unused data",
+    ),
+    (
+        r"\b(?:docker|podman)\s+volume\s+(?:rm|prune)\b",
+        "container volume removal/prune",
+    ),
+    # Package publish (paid/irreversible release to a public registry).
+    (r"\bnpm\s+publish\b", "npm publish releases a package"),
+    (r"\b(?:cargo|yarn|pnpm)\s+publish\b", "package publish releases to a registry"),
+    (r"\btwine\s+upload\b", "twine upload publishes to PyPI"),
+    (r"\bpip\s+upload\b", "pip upload publishes a package"),
+    (r"\bgh\s+release\s+create\b", "gh release create publishes a release"),
+    # Deploy verbs of common tools (external side effect, often paid).
+    (
+        r"\b(?:vercel|netlify|fly|flyctl|wrangler|heroku)\s+deploy\b",
+        "deploy command pushes to a hosting provider",
+    ),
+    (r"\bserverless\s+deploy\b", "serverless deploy provisions cloud resources"),
+    (r"\bkubectl\s+apply\b", "kubectl apply mutates cluster state"),
+    # curl/wget piped directly into a shell (executes untrusted remote code).
+    (
+        r"\b(?:curl|wget)\b[^|]*\|\s*(?:sudo\s+)?(?:ba)?sh\b",
+        "pipe-to-shell executes untrusted remote code",
+    ),
+    # dd to a block device (overwrites disks).
+    (r"\bdd\b[^|;&]*\bof=/dev/", "dd to a device overwrites a disk"),
+    # mkfs / fdisk (formats/partitions a disk).
+    (r"\bmkfs\b", "mkfs formats a filesystem"),
+)
+
+_COMPILED_RULES: Tuple[Tuple[re.Pattern, str], ...] = tuple(
+    (re.compile(pat, re.IGNORECASE), reason) for pat, reason in _RISK_RULES
+)
+
+# Longest command slice matched against user-supplied approval_required patterns;
+# bounds worst-case regex backtracking (see is_risky).
+_MAX_PATTERN_INPUT = 4096
+
+
+def is_risky(
+    command: str, extra_patterns: Optional[List[str]] = None
+) -> Tuple[bool, str]:
+    """Classify ``command`` as risky (destructive/irreversible/paid) or SAFE.
+
+    Returns ``(True, reason)`` for a risky command, ``(False, "")`` otherwise.
+    Never raises: a malformed extra pattern is logged and skipped so a bad policy
+    entry can never break the build loop. ``extra_patterns`` are project-supplied
+    additional risky regexes (``governance.approval_required``).
+    """
+    if not command or not isinstance(command, str):
+        return False, ""
+    for rule, reason in _COMPILED_RULES:
+        if rule.search(command):
+            return True, reason
+    # Bound the input a user-supplied pattern matches against: an adversarial
+    # (or accidentally pathological) approval_required regex can backtrack
+    # catastrophically, and its cost grows with input length. Real commands are
+    # short, so capping the matched slice removes the ReDoS blowup without
+    # affecting classification of legitimate commands.
+    probe = command[:_MAX_PATTERN_INPUT]
+    for raw in extra_patterns or []:
+        try:
+            if re.search(raw, probe, re.IGNORECASE):
+                return True, f"matches policy pattern: {raw}"
+        except re.error as e:
+            logger.warning(f"Ignoring invalid governance pattern {raw!r}: {e}")
+    return False, ""
+
+
+@dataclass
+class GovernanceDecision:
+    """Outcome of an authorization check."""
+
+    allowed: bool
+    risky: bool
+    reason: str = ""
+    escalated: bool = False
+
+
+@dataclass
+class GovernancePolicy:
+    """Approval policy consulted by the command seam when governance is ON.
+
+    ``enabled`` mirrors ``orchestrator.governance``; when False the policy is a
+    transparent no-op (everything authorized, nothing recorded), so default-off
+    behavior is identical to today. ``interactive`` selects prompt-vs-block for a
+    risky action. ``prompt`` is injected (defaults to a non-interactive denier)
+    so the loop never blocks on stdin in tests/autonomous runs.
+    """
+
+    enabled: bool = False
+    interactive: bool = False
+    auto_approve: bool = False
+    approval_required: List[str] = field(default_factory=list)
+    audit: Optional["object"] = None  # AuditTrail-like; duck-typed to avoid a cycle
+    prompt: Optional[Callable[[str, str], bool]] = None
+    escalations: List[dict] = field(default_factory=list)
+
+    def classify(self, command: str) -> Tuple[bool, str]:
+        return is_risky(command, self.approval_required)
+
+    def authorize(self, command: str, action: str = "command") -> GovernanceDecision:
+        """Decide whether ``command`` may run. SAFE always allowed; risky depends
+        on mode + auto_approve. Records an escalation + audit entry on refusal.
+
+        Never raises: any audit/prompt failure degrades to a recorded decision.
+        """
+        if not self.enabled:
+            return GovernanceDecision(allowed=True, risky=False)
+
+        risky, reason = self.classify(command)
+        if not risky:
+            return GovernanceDecision(allowed=True, risky=False)
+
+        if self.auto_approve:
+            self._record("gate", command, action, reason, allowed=True, escalated=False)
+            return GovernanceDecision(
+                allowed=True, risky=True, reason=reason, escalated=False
+            )
+
+        if self.interactive and self.prompt is not None:
+            try:
+                approved = bool(self.prompt(command, reason))
+            except Exception as e:  # prompt must never break the loop
+                logger.warning(f"Governance prompt failed, refusing: {e}")
+                approved = False
+            self._record(
+                "gate",
+                command,
+                action,
+                reason,
+                allowed=approved,
+                escalated=not approved,
+            )
+            return GovernanceDecision(
+                allowed=approved,
+                risky=True,
+                reason=reason,
+                escalated=not approved,
+            )
+
+        # Autonomous (non-interactive) + no auto_approve: block and escalate.
+        self._record("gate", command, action, reason, allowed=False, escalated=True)
+        return GovernanceDecision(
+            allowed=False, risky=True, reason=reason, escalated=True
+        )
+
+    def _record(
+        self,
+        kind: str,
+        command: str,
+        action: str,
+        reason: str,
+        allowed: bool,
+        escalated: bool,
+    ) -> None:
+        if escalated:
+            self.escalations.append(
+                {"command": command, "action": action, "reason": reason}
+            )
+        if self.audit is not None:
+            try:
+                self.audit.record(
+                    "gate",
+                    action=action,
+                    command=command,
+                    reason=reason,
+                    allowed=allowed,
+                    escalated=escalated,
+                )
+            except Exception as e:  # audit must never break execution
+                logger.debug(f"Governance audit record failed: {e}")
+
+
+def policy_from_config(
+    config: dict,
+    interactive: bool = False,
+    audit: Optional[object] = None,
+    prompt: Optional[Callable[[str, str], bool]] = None,
+) -> GovernancePolicy:
+    """Build a :class:`GovernancePolicy` from a merged config dict.
+
+    Reads ``orchestrator.governance`` (bool, default False) and the top-level
+    ``governance`` section (``approval_required`` list, ``auto_approve`` bool).
+    Never raises on a malformed section; missing/odd values degrade to defaults.
+    """
+    from misterdev.config import get_setting
+
+    enabled = bool(get_setting(config, "orchestrator", "governance"))
+    gov = config.get("governance") or {}
+    if not isinstance(gov, dict):
+        gov = {}
+    approval_required = gov.get("approval_required") or []
+    if not isinstance(approval_required, list):
+        approval_required = []
+    auto_approve = bool(gov.get("auto_approve", False))
+    return GovernancePolicy(
+        enabled=enabled,
+        interactive=interactive,
+        auto_approve=auto_approve,
+        approval_required=[str(p) for p in approval_required],
+        audit=audit,
+        prompt=prompt,
+    )

misterdev/core/execution/outcomes.py

@@ -0,0 +1,50 @@
+"""Shared result type for the optional, non-blocking gates.
+
+The runtime smoke, web, vision, and mutation gates all report the same tri-state
+outcome — SKIP / GREEN / RED — with the same ``passed`` and ``skipped`` meaning,
+plus a ``reason`` and gate-specific evidence. This centralizes the status
+vocabulary and the small boilerplate so each gate's result class only declares
+its own evidence fields.
+"""
+
+# Tri-state gate status. GREEN passed; RED failed (blocks the build); SKIP is
+# "no opinion" (missing config/dep, unparseable, or timeout) and never blocks.
+SKIP = "skip"
+GREEN = "green"
+RED = "red"
+
+
+class GateOutcome:
+    """Base for a gate result: a SKIP/GREEN/RED ``status`` and a ``reason``.
+
+    Subclasses add their own evidence fields and call ``super().__init__``.
+    ``passed`` is GREEN; ``skipped`` is SKIP.
+    """
+
+    def __init__(self, status: str, reason: str = ""):
+        self.status = status
+        self.reason = reason
+
+    @property
+    def passed(self) -> bool:
+        return self.status == GREEN
+
+    @property
+    def skipped(self) -> bool:
+        return self.status == SKIP
+
+
+class GateContext:
+    """Inputs a registered plugin gate receives.
+
+    ``project_path`` is the repo (or target subdir) root; ``commands`` are the
+    resolved build/test/lint/typecheck commands; ``env_activate`` is the optional
+    host-venv activation prefix. A plugin gate is ``callable(GateContext) ->
+    GateOutcome`` registered on ``misterdev.plugins.GATES``; a RED outcome blocks
+    the build, SKIP/GREEN do not.
+    """
+
+    def __init__(self, project_path, commands, env_activate=None):
+        self.project_path = project_path
+        self.commands = commands
+        self.env_activate = env_activate

misterdev/core/execution/progress.py

@@ -0,0 +1,120 @@
+"""Task progress persistence for crash recovery.
+
+Saves completed and failed task IDs to disk after each task finishes.
+On build start, checks for existing progress and resumes from where
+the previous run left off.
+"""
+
+import hashlib
+import json
+import threading
+from pathlib import Path
+from typing import Dict, Optional, Set
+
+from misterdev.logging_setup import setup_logger
+from misterdev.utils.file_utils import (
+    atomic_write,
+    orchestrator_state_file,
+)
+
+logger = setup_logger(__name__)
+
+
+def compute_task_hash(task, project_path: Path) -> str:
+    """Content hash of a task's inputs: its devplan file + target file mtimes.
+
+    Used to detect when a previously-completed task needs re-running because
+    its spec or the files it touches changed since it last succeeded.
+    """
+    h = hashlib.sha256()
+    source_ref = getattr(task, "source_ref", None)
+    if source_ref:
+        try:
+            h.update(Path(source_ref).read_bytes())
+        except OSError:
+            pass
+    # Fold in the task's own spec so that LLM-decomposed tasks (which have no
+    # source_ref and reuse generic ids like T-001 across separate builds) get a
+    # hash that reflects their actual content. Without this, a fresh plan's
+    # T-001 collides with a prior build's completed T-001 and is wrongly skipped.
+    for attr in ("title", "description"):
+        h.update(str(getattr(task, attr, "")).encode())
+    for f in sorted(getattr(task, "files_to_create", [])):
+        h.update(f"create:{f}".encode())
+    for f in sorted(getattr(task, "files_to_modify", [])):
+        h.update(f"modify:{f}".encode())
+        fp = Path(project_path) / f
+        if fp.exists():
+            h.update(f"{f}:{fp.stat().st_mtime_ns}".encode())
+    return h.hexdigest()[:16]
+
+
+class ProgressTracker:
+    """Persists build progress so a crash at task 18 resumes from 18, not 1."""
+
+    def __init__(self, project_path: Path):
+        self._file = orchestrator_state_file(project_path, "progress.json")
+        self.completed: Set[str] = set()
+        self.failed: Set[str] = set()
+        self.hashes: Dict[str, str] = {}
+        self._lock = threading.Lock()
+        self._load()
+
+    def _load(self):
+        if self._file.exists():
+            try:
+                data = json.loads(self._file.read_text(encoding="utf-8"))
+                self.completed = set(data.get("completed", []))
+                self.failed = set(data.get("failed", []))
+                self.hashes = dict(data.get("hashes", {}))
+            except (json.JSONDecodeError, OSError):
+                self.completed = set()
+                self.failed = set()
+                self.hashes = {}
+
+    def _save(self):
+        data = json.dumps(
+            {
+                "completed": sorted(self.completed),
+                "failed": sorted(self.failed),
+                "hashes": self.hashes,
+            },
+            indent=2,
+        )
+        atomic_write(self._file, data)
+
+    def mark_completed(self, task_id: str, task_hash: Optional[str] = None):
+        with self._lock:
+            self.completed.add(task_id)
+            self.failed.discard(task_id)
+            if task_hash is not None:
+                self.hashes[task_id] = task_hash
+            self._save()
+
+    def needs_rerun(self, task_id: str, current_hash: str) -> bool:
+        """True if the task isn't completed, or its inputs changed since."""
+        if task_id not in self.completed:
+            return True
+        recorded = self.hashes.get(task_id)
+        return recorded is None or recorded != current_hash
+
+    def mark_failed(self, task_id: str):
+        with self._lock:
+            self.failed.add(task_id)
+            self._save()
+
+    def is_done(self, task_id: str) -> bool:
+        return task_id in self.completed
+
+    def has_previous_run(self) -> bool:
+        return bool(self.completed or self.failed)
+
+    def reset(self):
+        self.completed.clear()
+        self.failed.clear()
+        self.hashes.clear()
+        if self._file.exists():
+            self._file.unlink()
+
+    def summary(self) -> str:
+        return f"{len(self.completed)} completed, {len(self.failed)} failed"

misterdev/core/execution/project.py

@@ -0,0 +1,231 @@
+from pathlib import Path
+from typing import Optional
+
+from misterdev.config import get_setting
+from misterdev.llm.client import BaseLLMClient, create_llm_client
+from misterdev.environments.base_env import BaseEnvironmentManager
+from misterdev.environments.venv_env import VenvEnvironmentManager
+from misterdev.core.task import TaskManager
+from misterdev.core.context.topography import TopographyEngine
+from misterdev.logging_setup import setup_logger
+
+logger = setup_logger(__name__)
+
+
+class ToolManager:
+    """Manages initialization and execution of tools."""
+
+    def __init__(self, tools_config: list):
+        self.tools = {}
+        # Importing the package registers the built-in tools; the registry also
+        # discovers third-party tools from the ``misterdev.tools`` entry-point
+        # group, so a plugin adds a tool type with no change here.
+        import misterdev.tools  # noqa: F401 - registration side effect
+        from misterdev.plugins import TOOLS
+
+        for tc in tools_config:
+            tool_type = tc.get("type")
+            tool_cls = TOOLS.get(tool_type)
+            if tool_cls is None:
+                if tool_type:
+                    logger.warning(
+                        f"Unknown tool type {tool_type!r}; falling back to command"
+                    )
+                tool_cls = TOOLS.get("command")
+            tool = tool_cls(tc)
+            self.tools[tool.name] = tool
+
+    def get_tool(self, name: str):
+        return self.tools.get(name)
+
+
+class Project:
+    """Represents an active project with all its dependencies initialized."""
+
+    def __init__(self, path: str | Path, config: dict):
+        self.path = Path(path)
+        self.config = config
+
+        self.name = config.get("name", self.path.name)
+        self.description = config.get("description", "")
+
+        self.llm_client = self._init_llm_client()
+        self.env_manager = self._init_env_manager()
+        self.tool_manager = ToolManager(config.get("tools", []))
+        self.task_manager = TaskManager(self)
+        # Model ledger/selector are built lazily on first use: they touch the
+        # .orchestrator dir and only matter when dynamic_selection is enabled.
+        self._model_ledger = None
+        self._model_selector = None
+        self._llm_cache = None
+        self._semantic_ranker = None
+        self._ranker_built = False
+        self._mcp = None
+        self._mcp_built = False
+        self._audit_trail = None
+        self._governance_policy = None
+        self._governance_built = False
+        # Topography (symbol graph) is built lazily on first use, not here:
+        # every CLI command registers all known projects, and eagerly scanning
+        # each one's whole tree just to list/status is wasted work. The executor
+        # calls initialize() (idempotent) before it needs the graph.
+        self.topography = TopographyEngine(
+            self.path,
+            self.llm_client,
+            golden_paths=get_setting(config, "orchestrator", "golden_paths"),
+        )
+
+    @property
+    def model_ledger(self):
+        """Persistent per-model performance store (lazy, file-backed)."""
+        if self._model_ledger is None:
+            from misterdev.core.economics.model_ledger import ModelLedger
+
+            self._model_ledger = ModelLedger(
+                self.path / ".orchestrator" / "model_stats.json"
+            )
+        return self._model_ledger
+
+    @property
+    def model_selector(self):
+        """Ledger-driven model selection policy (lazy)."""
+        if self._model_selector is None:
+            from misterdev.core.economics.model_selector import (
+                ModelSelector,
+            )
+
+            self._model_selector = ModelSelector(
+                self.config, self.model_ledger, free_models=self._harvest_free_models()
+            )
+        return self._model_selector
+
+    @property
+    def semantic_ranker(self):
+        """Embedding-based context ranker, or None when unavailable/disabled.
+
+        Built at most once (discovery hits the network); a None result is
+        remembered so topography falls back to arbitrary order without retrying.
+        """
+        if not self._ranker_built:
+            self._ranker_built = True
+            if get_setting(self.config, "llm", "semantic_retrieval"):
+                from misterdev.core.economics.embeddings import (
+                    EmbeddingCache,
+                    SemanticRanker,
+                )
+                from misterdev.llm.client import create_embedding_client
+
+                weight = get_setting(self.config, "llm", "lexical_weight")
+                embedder = create_embedding_client(self.config)
+                cache = (
+                    EmbeddingCache(
+                        self.path / ".orchestrator" / "embeddings.json", embedder.model
+                    )
+                    if embedder is not None
+                    else None
+                )
+                # Always build a ranker: with no embedder it ranks lexically,
+                # which still beats the arbitrary-order slice.
+                self._semantic_ranker = SemanticRanker(embedder, cache, weight)
+        return self._semantic_ranker
+
+    @property
+    def mcp(self):
+        """MCP tool-host manager, or None when no servers are configured.
+
+        Built at most once (the manager itself is cheap; discovery is deferred
+        to first access of ``.tools`` and is timeout-bounded). A None result is
+        remembered so callers can skip MCP entirely without retrying.
+        """
+        if not self._mcp_built:
+            self._mcp_built = True
+            mcp_cfg = self.config.get("mcp") or {}
+            servers = mcp_cfg.get("servers") or []
+            if servers:
+                from misterdev.core.integration.mcp import MCPManager
+
+                manager = MCPManager(servers, allow_tools=mcp_cfg.get("allow_tools"))
+                self._mcp = manager if manager.enabled else None
+        return self._mcp
+
+    @property
+    def llm_cache(self):
+        """Response memoization store, or None when caching is disabled."""
+        if self._llm_cache is None and get_setting(self.config, "llm", "cache"):
+            from misterdev.core.economics.llm_cache import LLMCache
+
+            self._llm_cache = LLMCache(self.path / ".orchestrator" / "llm_cache")
+        return self._llm_cache
+
+    @property
+    def audit_trail(self):
+        """Append-only JSONL audit trail (lazy, file-backed under .orchestrator).
+
+        Defaults ON: it only appends observability records to a gitignored file
+        and degrades to a no-op if the path is unwritable, so it cannot regress a
+        build. A run that wants it silent leaves the file unread (no behavioral
+        effect either way)."""
+        if self._audit_trail is None:
+            from misterdev.core.audit import AuditTrail
+
+            self._audit_trail = AuditTrail(self.path, enabled=True)
+        return self._audit_trail
+
+    @property
+    def governance_policy(self):
+        """Risk-classified approval policy, or None when governance is off.
+
+        Built from config in AUTONOMOUS mode (interactive prompting is a deferred
+        seam: threading stdin into the wave loop risks a hang, so unattended runs
+        BLOCK a risky command and record an escalation unless governance.
+        auto_approve is set). None when orchestrator.governance is false, so the
+        command seam stays byte-identical to today."""
+        if not self._governance_built:
+            self._governance_built = True
+            from misterdev.core.execution.governance import (
+                policy_from_config,
+            )
+
+            policy = policy_from_config(
+                self.config, interactive=False, audit=self.audit_trail
+            )
+            self._governance_policy = policy if policy.enabled else None
+        return self._governance_policy
+
+    def _harvest_free_models(self) -> list:
+        """Current free OpenRouter models when use_free_models is enabled."""
+        if not get_setting(self.config, "llm", "use_free_models"):
+            return []
+        import time
+
+        from misterdev.core.economics.free_models import FreeModelCache
+
+        cache = FreeModelCache(self.path / ".orchestrator" / "free_models.json")
+        try:
+            return cache.get(time.time())
+        except Exception as e:
+            logger.warning(f"Free-model harvest skipped: {e}")
+            return []
+
+    def _init_llm_client(self) -> BaseLLMClient:
+        return create_llm_client(self.config)
+
+    def _init_env_manager(self) -> Optional[BaseEnvironmentManager]:
+        env_config = self.config.get("environment", {})
+        env_type = env_config.get("type")
+        if env_type == "venv":
+            return VenvEnvironmentManager(env_config, self.path)
+        if env_type in ("docker", "container"):
+            from misterdev.environments.container_env import (
+                ContainerEnvironmentManager,
+            )
+
+            gov = self.config.get("governance") or {}
+            network = gov.get("network") if gov.get("network") == "none" else None
+            return ContainerEnvironmentManager(
+                env_config,
+                self.path,
+                language=self.config.get("language", ""),
+                network=network,
+            )
+        return None