opencommand 0.1.0__py3-none-any.whl

opencommand/providers/provider.py

@@ -0,0 +1,157 @@
+"""Unified LLM provider layer for OpenCommand.
+
+All four target backends (Ollama, LM Studio, vLLM, llama.cpp) expose the OpenAI
+Chat Completions API, so a single client with per-backend presets covers them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator, Iterator
+
+try:
+    from openai import AsyncOpenAI, OpenAI
+except Exception:  # pragma: no cover - openai is a hard dep but keep import soft
+    AsyncOpenAI = None  # type: ignore
+    OpenAI = None  # type: ignore
+
+
+@dataclass
+class BackendPreset:
+    """Connection defaults for a local LLM server."""
+
+    name: str
+    base_url: str
+    default_model: str
+    api_key: str = "not-needed"
+    notes: str = ""
+
+
+# Presets for the four supported OpenAI-compatible servers.
+BACKENDS: dict[str, BackendPreset] = {
+    "ollama": BackendPreset("ollama", "http://localhost:11434/v1", "qwen2.5:7b",
+                            notes="ollama serve; pull models with `ollama pull`."),
+    "lmstudio": BackendPreset("lmstudio", "http://localhost:1234/v1",
+                              "lmstudio-community/qwen2.5-7b",
+                              notes="LM Studio -> Developer tab -> Start Server."),
+    "vllm": BackendPreset("vllm", "http://localhost:8000/v1",
+                          "Qwen/Qwen2.5-7B-Instruct", notes="vllm serve <model> --api-key token"),
+    "llamacpp": BackendPreset("llamacpp", "http://localhost:8080/v1", "local-model",
+                              notes="server --api-key token (llama.cpp server)."),
+}
+
+
+@dataclass
+class ChatMessage:
+    role: str
+    content: Any  # str or list[dict] for multimodal
+    name: str | None = None
+    tool_calls: list | None = None  # OpenAI-style tool calls (assistant turns)
+    tool_call_id: str | None = None  # links a tool result back to its call
+
+
+@dataclass
+class ProviderConfig:
+    backend: str = "ollama"
+    base_url: str | None = None
+    api_key: str | None = None
+    model: str | None = None
+    temperature: float = 0.2
+    max_tokens: int = 4096
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def resolve(self) -> BackendPreset:
+        preset = BACKENDS.get(self.backend)
+        if preset is None:
+            raise ValueError(
+                f"Unknown backend '{self.backend}'. "
+                f"Choose from: {', '.join(BACKENDS)}"
+            )
+        return preset
+
+    @property
+    def effective_base_url(self) -> str:
+        return self.base_url or self.resolve().base_url
+
+    @property
+    def effective_model(self) -> str:
+        return self.model or self.resolve().default_model
+
+    @property
+    def effective_api_key(self) -> str:
+        return self.api_key or self.resolve().api_key
+
+
+class BaseProvider:
+    """Interface every provider implements."""
+
+    def complete(self, messages: list[ChatMessage], **kw) -> ChatMessage:  # sync
+        raise NotImplementedError
+
+    async def acomplete(self, messages: list[ChatMessage], **kw) -> ChatMessage:
+        raise NotImplementedError
+
+    def stream(self, messages: list[ChatMessage], **kw) -> Iterator[ChatMessage]:
+        raise NotImplementedError
+
+    async def astream(self, messages: list[ChatMessage], **kw) -> AsyncIterator[ChatMessage]:
+        raise NotImplementedError
+
+
+class OpenAICompatibleProvider(BaseProvider):
+    """Talks to any OpenAI-compatible server (Ollama/LM Studio/vLLM/llama.cpp)."""
+
+    def __init__(self, cfg: ProviderConfig) -> None:
+        self.cfg = cfg
+        if OpenAI is None:
+            raise RuntimeError("openai package is required for the provider layer")
+        self._client = OpenAI(
+            base_url=cfg.effective_base_url,
+            api_key=cfg.effective_api_key,
+        )
+        self._aclient = AsyncOpenAI(
+            base_url=cfg.effective_base_url,
+            api_key=cfg.effective_api_key,
+        )
+
+    def _payload(self, messages: list[ChatMessage], **kw) -> dict[str, Any]:
+        payload = {
+            "model": self.cfg.effective_model,
+            "messages": [m.__dict__ for m in messages],
+            "temperature": kw.get("temperature", self.cfg.temperature),
+            "max_tokens": kw.get("max_tokens", self.cfg.max_tokens),
+        }
+        payload.update(self.cfg.extra)
+        payload.update({k: v for k, v in kw.items() if k not in payload})
+        return payload
+
+    def complete(self, messages: list[ChatMessage], **kw) -> ChatMessage:
+        resp = self._client.chat.completions.create(**self._payload(messages, **kw))
+        msg = resp.choices[0].message
+        return ChatMessage(role=msg.role, content=msg.content or "")
+
+    async def acomplete(self, messages: list[ChatMessage], **kw) -> ChatMessage:
+        resp = await self._aclient.chat.completions.create(**self._payload(messages, **kw))
+        msg = resp.choices[0].message
+        return ChatMessage(role=msg.role, content=msg.content or "")
+
+    def stream(self, messages: list[ChatMessage], **kw):
+        stream = self._client.chat.completions.create(
+            **self._payload(messages, **kw), stream=True
+        )
+        for chunk in stream:
+            if chunk.choices and chunk.choices[0].delta.content:
+                yield ChatMessage(role="assistant", content=chunk.choices[0].delta.content)
+
+    async def astream(self, messages: list[ChatMessage], **kw):
+        stream = await self._aclient.chat.completions.create(
+            **self._payload(messages, **kw), stream=True
+        )
+        async for chunk in stream:
+            if chunk.choices and chunk.choices[0].delta.content:
+                yield ChatMessage(role="assistant", content=chunk.choices[0].delta.content)
+
+
+def build_provider(cfg: ProviderConfig) -> BaseProvider:
+    """Factory: today every backend is OpenAI-compatible."""
+    return OpenAICompatibleProvider(cfg)

opencommand/swarm/agents/commander.py

@@ -0,0 +1,530 @@
+"""Commander: the orchestrating model.
+
+Takes a high-level GOAL, plans a multi-phase implementation, and dispatches
+batches of research and worker agents via the Supervisor. Updates memory and
+iterates until the goal and all subtasks are complete.
+
+Phase 6 advanced pipeline (orchestrator-workers + evaluator-optimizer), hardened
+for codebase-scale, fully-automated, long-horizon goals:
+
+  scaffold -> RESEARCH LOOP (refine until accurate) -> implement (workers) ->
+  TEST+DEBUG LOOP (until testable state passes) -> commander review gate
+  (evaluator-optimizer, incl. off-track check) -> live-verify (optional) ->
+  outer loop until the GOAL is 100% met.
+
+Research is looped *before* any worker is dispatched so implementation is always
+grounded in verified findings. Guardrails are injected into every prompt so the
+Commander and workers never diverge from the assigned task or the workspace.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from ...core.agent import AgentLoop
+from ...core.logging import get_logger
+from ...core.supervisor import Supervisor
+from ...core.tools import ToolRegistry
+from ...engine import Engine
+from ...engine.runner import LocalRunner
+from ...providers.provider import ChatMessage
+from ...modules.knowledge import KnowledgeBase
+from ...modules.tools.memory import save_note
+
+if TYPE_CHECKING:
+    from ...modules.system.automatic import LiveVerifyResult
+
+log = get_logger("swarm.commander")
+
+PLAN_PROMPT = (
+    "You are the Commander of an OpenCommand swarm. Given a GOAL, produce a "
+    "multi-phase plan as JSON: {\"phases\": [{\"name\": str, \"research\": [task], "
+    "\"workers\": [task]}]}. Keep each task concrete and independently executable. "
+    "Prefer research batches first (find best packages/tools/setups), then worker "
+    "batches that implement. Respond with JSON only."
+)
+
+REVIEW_PROMPT = (
+    "You are the Commander reviewing a completed phase against the original GOAL. "
+    "Decide whether the work actually satisfies the goal. Be strict: tests passing "
+    "is not enough if the wrong thing was built, requirements are missing, the "
+    "output is incomplete, or the work went OFF TRACK (modified unrelated files, "
+    "diverged from the goal, or re-planned the overall goal). Respond with JSON "
+    "only, using this shape:\n"
+    "{{\"passed\": true_or_false, \"off_track\": true_or_false, \"feedback\": "
+    "\"string\", \"missing\": [\"item\"]}}\n\n"
+    "GOAL: {goal}\nPHASE: {phase}\n\nWORK DONE:\n{report}"
+)
+
+RESEARCH_ASSESS_PROMPT = (
+    "You are the Commander assessing whether the research collected so far is "
+    "sufficient to implement the phase ACCURATELY. If there are gaps, unverified "
+    "claims, or unknowns that could make workers guess or go off track, list them "
+    "as concrete follow-up research tasks. Respond with JSON only, using this "
+    "shape:\n"
+    "{{\"sufficient\": true_or_false, \"gaps\": [\"follow-up research task\"], "
+    "\"note\": \"string\"}}\n\n"
+    "GOAL: {goal}\nPHASE: {phase}\n\nRESEARCH SO FAR:\n{research}"
+)
+
+# Injected into every research/worker prompt so the swarm stays on task and
+# inside the workspace. The files tool also hard-rejects path escapes.
+GUARDRAILS = (
+    "GUARDRAILS (strict, must follow):\n"
+    "- Stay strictly within the assigned task and the workspace. Do NOT modify "
+    "files unrelated to this task or phase.\n"
+    "- Do NOT re-plan the overall goal; implement only what is asked of you.\n"
+    "- Prefer running real commands/tests over claiming success. If a tool fails, "
+    "retry or report the error; never fabricate results.\n"
+    "- Stop when the task is complete; emit a final summary with no tool calls.\n"
+    "- All file writes must resolve under the workspace root (the files tool "
+    "rejects any path that escapes it)."
+)
+
+
+@dataclass
+class Phase:
+    name: str
+    research: list[str] = field(default_factory=list)
+    workers: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Plan:
+    phases: list[Phase] = field(default_factory=list)
+
+    @classmethod
+    def from_json(cls, text: str) -> "Plan":
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError:
+            start = text.find("{")
+            end = text.rfind("}") + 1
+            data = json.loads(text[start:end]) if start != -1 else {"phases": []}
+        return cls(phases=[
+            Phase(name=p.get("name", "phase"), research=p.get("research", []),
+                  workers=p.get("workers", []))
+            for p in data.get("phases", [])
+        ])
+
+
+@dataclass
+class ReviewResult:
+    passed: bool = False
+    off_track: bool = False
+    feedback: str = ""
+    missing: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_json(cls, text: str) -> "ReviewResult":
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError:
+            start = text.find("{")
+            end = text.rfind("}") + 1
+            data = json.loads(text[start:end]) if start != -1 else {}
+        return cls(
+            passed=bool(data.get("passed", False)),
+            off_track=bool(data.get("off_track", False)),
+            feedback=str(data.get("feedback", "")),
+            missing=list(data.get("missing", []) or []),
+        )
+
+
+@dataclass
+class ResearchAssessment:
+    sufficient: bool = False
+    gaps: list[str] = field(default_factory=list)
+    note: str = ""
+
+    @classmethod
+    def from_json(cls, text: str) -> "ResearchAssessment":
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError:
+            start = text.find("{")
+            end = text.rfind("}") + 1
+            data = json.loads(text[start:end]) if start != -1 else {}
+        return cls(
+            sufficient=bool(data.get("sufficient", False)),
+            gaps=list(data.get("gaps", []) or []),
+            note=str(data.get("note", "")),
+        )
+
+
+class Commander:
+    """Plans and drives the swarm for a GOAL.
+
+    The Commander uses a shared runner for planning/research; each worker gets a
+    dedicated runner instance from the engine pool so concurrent workers run
+    their inference in parallel (the GIL is released during llama.cpp generation).
+    A ``provider`` may be injected (tests / non-embedded backends) to override the
+    embedded commander runner.
+    """
+
+    def __init__(self, engine: Engine, supervisor: Supervisor,
+                 tools: ToolRegistry, workspace: Path,
+                 provider: "LocalRunner | None" = None) -> None:
+        self.engine = engine
+        self.provider = provider or engine.runner("commander")
+        self.supervisor = supervisor
+        self.tools = tools
+        self.workspace = workspace
+        # Knowledge base loads skills + tasks + docs + tool catalog into workers.
+        self.knowledge = KnowledgeBase(workspace, tools)
+
+    async def plan(self, goal: str) -> Plan:
+        msg = await self.provider.acomplete(
+            [ChatMessage(role="user", content=f"{PLAN_PROMPT}\n\nGOAL: {goal}")],
+            json_mode=True)
+        return Plan.from_json(msg.content or "{}")
+
+    # --- Standard pipeline (backward compatible) ---------------------------
+
+    async def execute(self, goal: str) -> str:
+        """Standard pipeline: plan -> research -> workers (no scaffold/review)."""
+        plan = await self.plan(goal)
+        save_note(self.workspace, "goal_plan",
+                  json.dumps({"goal": goal, "phases": [p.__dict__ for p in plan.phases]},
+                             indent=2), tags=["plan", "commander"])
+        report: list[str] = [f"GOAL: {goal}", f"Phases: {len(plan.phases)}"]
+        for idx, phase in enumerate(plan.phases, 1):
+            report.append(f"\n=== Phase {idx}: {phase.name} ===")
+            research_jobs = {f"research-{i}": self._research_job(i, t)
+                             for i, t in enumerate(phase.research)}
+            if research_jobs:
+                for k, v in (await self.supervisor.run_all(research_jobs)).items():
+                    report.append(f"  [{k}] {v[:300]}")
+            worker_jobs = {f"worker-{i}": self._worker_job(i, t)
+                           for i, t in enumerate(phase.workers)}
+            if worker_jobs:
+                for k, v in (await self.supervisor.run_all(worker_jobs)).items():
+                    report.append(f"  [{k}] {v[:300]}")
+        save_note(self.workspace, "goal_report", "\n".join(report), tags=["report"])
+        return "\n".join(report)
+
+    # --- Advanced pipeline (Phase 6, hardened) -----------------------------
+
+    async def execute_advanced(self, goal: str, max_research_loops: int = 3,
+                               max_test_loops: int = 5,
+                               verify_cmd: str | None = None,
+                               live_verify: bool = False) -> str:
+        """Fully-featured autonomous loop for a GOAL.
+
+        Per phase:
+          1. scaffold a stable working dir;
+          2. RESEARCH LOOP  -  run the research batch, then the Commander assesses
+             sufficiency and dispatches follow-up research tasks until findings
+             are accurate (or the loop cap is hit). Findings flow into workers.
+          3. implement workers (grounded in research + skills + guardrails);
+          4. TEST+DEBUG LOOP  -  once a testable state is reached, run the verify
+             command and let workers fix failures until it passes (or cap hit);
+          5. commander review gate (incl. off-track check);
+          6. optional live-verify via the desktop tool for UI goals.
+
+        The outer loop in ``run_automatic`` re-runs the whole pipeline with the
+        failing report as fix context until the GOAL is 100% met.
+        """
+        plan = await self.plan(goal)
+        save_note(self.workspace, "goal_plan",
+                  json.dumps({"goal": goal, "phases": [p.__dict__ for p in plan.phases]},
+                             indent=2), tags=["plan", "commander"])
+        # Also persist a templated markdown plan for human readability.
+        from ...modules.templates import template_for
+        from ...modules.tools.instructions import _now
+
+        plan_md = template_for("plan").render(
+            goal=goal, created=_now(),
+            phases=str(len(plan.phases)),
+            description="\n".join(f"- {p.name}" for p in plan.phases),
+        )
+        save_note(self.workspace, "goal_plan_md", plan_md, tags=["plan", "commander"])
+        log.info("planned goal=%r phases=%d", goal, len(plan.phases))
+        # Load skills + tasks + docs + tool catalog into every worker instance.
+        knowledge = self.knowledge.worker_context()
+        report: list[str] = [f"GOAL: {goal}", f"Phases: {len(plan.phases)}"]
+        for idx, phase in enumerate(plan.phases, 1):
+            report.append(f"\n=== Phase {idx}: {phase.name} ===")
+            scaffold_root = self._scaffold(phase, idx)
+            # 2. RESEARCH LOOP: refine until accurate before any worker runs.
+            research_ctx = await self._research_loop(
+                goal, phase, idx, report, knowledge, max_loops=max_research_loops)
+            # 3. Implement workers, grounded in research + knowledge + guardrails.
+            context = self._build_context(goal, phase, research_ctx, scaffold_root, knowledge)
+            worker_jobs = {f"worker-{i}": self._worker_job(i, t, context)
+                           for i, t in enumerate(phase.workers)}
+            if worker_jobs:
+                for k, v in (await self.supervisor.run_all(worker_jobs)).items():
+                    report.append(f"  [{k}] {v[:300]}")
+            # 4. TEST+DEBUG LOOP: reach a testable state, then fix until green.
+            if verify_cmd:
+                test_report = await self._test_debug_loop(
+                    goal, phase, context, verify_cmd, max_loops=max_test_loops)
+                report.append(test_report)
+            # 5. Commander review gate (evaluator-optimizer + off-track check).
+            review = await self.review_goal(goal, "\n".join(report), phase=phase.name)
+            report.append(f"  [review:{phase.name}] passed={review.passed} "
+                          f"off_track={review.off_track} {review.feedback[:200]}")
+            if review.missing:
+                report.append(f"  [review:{phase.name}] missing: {', '.join(review.missing)}")
+            # 6. Optional live-verify for UI/UX goals.
+            if live_verify:
+                lv = await self._live_verify(goal)
+                report.append(f"  [live-verify:{phase.name}] "
+                              f"{'PASS' if lv.ok else 'FAIL'}: {lv.summary}")
+        # 7. Self-improvement: distill what worked into skills/tasks/docs/memory
+        #    so the NEXT run (and next phase) starts smarter.
+        distill = await self.distill_lessons(goal, "\n".join(report))
+        report.append(f"\n[self-improve] {distill}")
+        log.info("advanced pipeline complete goal=%r self_improve=%s", goal, distill)
+        full_report = "\n".join(report)
+        save_note(self.workspace, "goal_report", full_report, tags=["report"])
+        # Also persist a templated markdown report for human readability.
+        report_md = template_for("report").render(
+            goal=goal, created=_now(), status="complete",
+            description=full_report[:4000],
+        )
+        save_note(self.workspace, "goal_report_md", report_md, tags=["report"])
+        return full_report
+
+    async def _research_loop(self, goal: str, phase: Phase, idx: int,
+                             report: list[str], knowledge: str,
+                             max_loops: int = 3) -> str:
+        """Loop research batches until the Commander judges findings sufficient.
+
+        Returns the accumulated research context (flowed into workers). Each
+        iteration runs the current research tasks concurrently, appends findings
+        to memory, and asks the Commander whether more research is needed.
+        """
+        tasks = list(phase.research)
+        ctx_parts: list[str] = []
+        for loop in range(max_loops):
+            if not tasks:
+                break
+            jobs = {f"research-{loop}-{i}": self._research_job(i, t, knowledge)
+                    for i, t in enumerate(tasks)}
+            results = await self.supervisor.run_all(jobs)
+            batch = "\n\n".join(f"[{k}]\n{v}" for k, v in results.items())
+            ctx_parts.append(batch)
+            save_note(self.workspace, f"research_{idx}_{loop}", batch,
+                      tags=["research", phase.name])
+            for k, v in results.items():
+                report.append(f"  [{k}] {v[:200]}")
+            # Commander assesses sufficiency of everything gathered so far.
+            assessment = await self.assess_research(goal, phase.name,
+                                                    "\n\n".join(ctx_parts))
+            if assessment.sufficient:
+                report.append(f"  [research:{phase.name}] sufficient after "
+                              f"{loop + 1} loop(s): {assessment.note[:120]}")
+                break
+            # Otherwise queue follow-up research tasks and loop again.
+            tasks = assessment.gaps
+            report.append(f"  [research:{phase.name}] gaps -> {len(tasks)} follow-up "
+                          f"task(s): {assessment.note[:120]}")
+        return "\n\n".join(ctx_parts)
+
+    async def distill_lessons(self, goal: str, report: str) -> str:
+        """Self-improvement gate: turn the run into new/updated instructions.
+
+        The Commander is asked to produce concrete instruction artifacts (skills,
+        task playbooks, docs, memory notes) capturing what worked, what to avoid,
+        and any gotchas  -  then writes them via the instructions tool so future
+        runs load them into every worker. Returns a short summary.
+        """
+        prompt = (
+            "You are the Commander performing a self-improvement pass after a run. "
+            "Distill the run into reusable instruction artifacts so future runs "
+            "start smarter. For each artifact, output ONE line:\n"
+            "  SKILL|<name>|<markdown body>\n"
+            "  TASK|<name>|<markdown body>\n"
+            "  DOC|<name>|<markdown body>\n"
+            "  MEMORY|<topic>|<tags csv>|<markdown body>\n"
+            "Each body MUST follow its required template shape (front-matter + "
+            "sections): skills need Summary/Conventions/When to use/Examples/Gotchas; "
+            "tasks need Objective/Preconditions/Steps/Verification/Rollback; docs need "
+            "Overview/Details/References; memory is a tagged note. Only emit artifacts "
+            "that are genuinely reusable (not one-off task details). Prefer updating an "
+            "existing skill/task if relevant. Output at most 6 lines. If nothing is "
+            "reusable, output NONE.\n\n"
+            f"GOAL: {goal}\n\nRUN REPORT:\n{report[:5000]}"
+        )
+        msg = await self.provider.acomplete(
+            [ChatMessage(role="user", content=prompt)], json_mode=False)
+        text = msg.content or "NONE"
+        written = self._apply_instructions(text)
+        return f"wrote {written} artifact(s)" if written else "no reusable artifacts"
+
+    def _apply_instructions(self, text: str) -> int:
+        """Parse the Commander's distillation lines and persist them.
+
+        Each artifact is one ``KIND|name|body`` (or ``MEMORY|topic|tags|body``)
+        record. Bodies may span multiple lines until the next ``KIND|`` record,
+        so we accumulate lines and flush when the next record starts.
+        """
+        from ...modules.tools.instructions import InstructionsTool
+
+        tool = InstructionsTool(self.workspace)
+        count = 0
+        cur_kind: str | None = None
+        cur_rest: str = ""
+        records: list[tuple[str, str]] = []
+
+        def _flush() -> None:
+            nonlocal cur_kind, cur_rest
+            if cur_kind is not None:
+                records.append((cur_kind, cur_rest.strip()))
+            cur_kind, cur_rest = None, ""
+
+        for raw in text.splitlines():
+            line = raw.strip()
+            if not line or line == "NONE":
+                continue
+            if "|" in line and line.split("|", 1)[0].strip().lower() in (
+                    "skill", "task", "doc", "memory"):
+                _flush()
+                cur_kind = line.split("|", 1)[0].strip().lower()
+                cur_rest = line.split("|", 1)[1]
+            elif cur_kind is not None:
+                cur_rest += "\n" + line
+            # lines before the first record are ignored
+        _flush()
+
+        for kind, rest in records:
+            try:
+                if kind == "memory":
+                    name, tags, body = rest.split("|", 2)
+                    res = tool.run("save", "memory", name=name.strip(),
+                                   body=body.strip(),
+                                   tags=[t.strip() for t in tags.split(",")])
+                elif kind in ("skill", "task", "doc"):
+                    name, body = rest.split("|", 1)
+                    res = tool.run("save", kind, name=name.strip(), body=body.strip())
+                else:
+                    continue
+                if not res.startswith("ERROR"):
+                    count += 1
+            except ValueError:
+                continue
+        return count
+
+    async def _test_debug_loop(self, goal: str, phase: Phase, context: str,
+                               verify_cmd: str, max_loops: int = 5) -> str:
+        """Reach a testable state, then run tests and let workers fix failures.
+
+        Returns a short report line. Uses the same verify command as the outer
+        loop; workers are given the failing output as fix context so they iterate
+        until green (or the cap is hit).
+        """
+        from ...modules.system.automatic import _verify
+
+        last = ""
+        for loop in range(max_loops):
+            rc, out = _verify(self, verify_cmd)
+            if rc == 0:
+                return (f"  [test:{phase.name}] {verify_cmd} -> PASS (exit 0) "
+                        f"after {loop} fix(es)")
+            last = (f"Tests failed (exit {rc}). Fix the issues, then re-run "
+                    f"`{verify_cmd}`.\nSTDOUT/STDERR:\n{out[:3000]}")
+            # Dispatch a focused fixer worker grounded in the failure.
+            fix_ctx = (f"{context}\n\n{last}\n\n"
+                       "Fix ONLY what is needed to make the tests pass. Do not "
+                       "modify unrelated files. Re-run the tests yourself to confirm.")
+            fix = {f"fixer-{loop}": self._worker_job(loop, "Fix failing tests", fix_ctx)}
+            res = await self.supervisor.run_all(fix)
+            for k, v in res.items():
+                last = f"  [{k}] {v[:200]}"
+        return (f"  [test:{phase.name}] {verify_cmd} -> STILL FAILING after "
+                f"{max_loops} fix loops. Last: {last[:200]}")
+
+    async def review_goal(self, goal: str, report: str,
+                          phase: str | None = None) -> ReviewResult:
+        """Commander verification gate: did the work actually meet the GOAL?
+
+        Returns a structured ReviewResult (incl. off_track). This is the evaluator
+        in the evaluator-optimizer loop and is what lets the Commander reject work
+        that a worker (or even a passing test suite) claimed was done, or that
+        diverged from the assigned task.
+        """
+        prompt = REVIEW_PROMPT.format(goal=goal, phase=phase or "all",
+                                      report=report[:6000])
+        msg = await self.provider.acomplete(
+            [ChatMessage(role="user", content=prompt)], json_mode=True)
+        return ReviewResult.from_json(msg.content or "{}")
+
+    async def assess_research(self, goal: str, phase: str, research: str) -> "ResearchAssessment":
+        """Commander gate: are the research findings sufficient to implement accurately?"""
+        prompt = RESEARCH_ASSESS_PROMPT.format(goal=goal, phase=phase,
+                                               research=research[:6000])
+        msg = await self.provider.acomplete(
+            [ChatMessage(role="user", content=prompt)], json_mode=True)
+        return ResearchAssessment.from_json(msg.content or "{}")
+
+    async def _live_verify(self, goal: str) -> LiveVerifyResult:
+        """Interactive validation via the desktop tool (vision + action loop)."""
+        from ...modules.system.automatic import _live_verify as _lv
+        return await _lv(self, goal)
+
+    # --- Helpers -----------------------------------------------------------
+
+    def _scaffold(self, phase: Phase, idx: int) -> str:
+        """Lay the foundation for a phase so workers fill in structure, not fight it.
+
+        Creates a stable working directory under .opencommand/scaffold and writes
+        a manifest from the required scaffold template. Returns the absolute path.
+        """
+        from ...modules.templates import template_for
+        from ...modules.tools.instructions import _now
+
+        root = self.workspace / ".opencommand" / "scaffold" / f"{idx:02d}-{phase.name}"
+        root.mkdir(parents=True, exist_ok=True)
+        tpl = template_for("scaffold")
+        manifest = tpl.render(
+            phase=phase.name, index=str(idx), created=_now(),
+            description=(f"Phase {idx}. Workers write implementation here. "
+                         f"Research tasks: {len(phase.research)}. "
+                         f"Worker tasks: {len(phase.workers)}."),
+        )
+        (root / "scaffold.md").write_text(manifest, encoding="utf-8")
+        return str(root)
+
+    def _build_context(self, goal: str, phase: Phase, research: str,
+                       scaffold_root: str, knowledge: str) -> str:
+        """Assemble the shared context block injected into every worker prompt.
+
+        ``knowledge`` already contains the skills + tasks + docs + tool catalog
+        loaded from the KnowledgeBase, so workers start with full instruction
+        context. Research findings and guardrails are layered on top.
+        """
+        parts = [
+            f"ORIGINAL GOAL: {goal}",
+            f"PHASE: {phase.name}",
+            f"WRITE CODE UNDER: {scaffold_root}",
+        ]
+        if research:
+            parts.append(f"RESEARCH CONTEXT (ground your work in this):\n{research}")
+        if knowledge:
+            parts.append(f"INSTRUCTIONS (skills/tasks/docs/tools):\n{knowledge}")
+        parts.append(GUARDRAILS)
+        return "\n\n".join(parts)
+
+    def _research_job(self, index: int, task: str, knowledge: str = ""):
+        # Research uses a dedicated worker runner so it can run concurrently with
+        # the Commander's planning and with other research/worker jobs.
+        runner = self.engine.worker_runner("worker", index)
+        async def _run() -> str:
+            prompt = (f"Research task: {task}. Summarize findings and best options "
+                      f"concisely and cite sources.\n\n{GUARDRAILS}")
+            if knowledge:
+                prompt += f"\n\nINSTRUCTIONS (skills/tasks/docs/tools):\n{knowledge}"
+            return await AgentLoop(runner, self.tools).run(prompt)
+        return _run
+
+    def _worker_job(self, index: int, task: str, context: str = ""):
+        runner = self.engine.worker_runner("worker", index)
+        async def _run() -> str:
+            prompt = task if not context else f"{context}\n\nTASK: {task}"
+            return await AgentLoop(runner, self.tools).run(prompt)
+        return _run