devcouncil 0.1.1 → 0.2.0

package/src/devcouncil/executors/native/agent.py

@@ -1,16 +1,24 @@
 from typing import List, Dict, Any
+import asyncio
 from rich.console import Console
 from pydantic import BaseModel
 from devcouncil.domain.task import Task
 from devcouncil.domain.requirement import Requirement
 from devcouncil.execution.executor import Executor, ExecutionResult
-from devcouncil.llm.router import ModelRouter
+from devcouncil.llm.router import ModelRouter, StructuredOutputError
 from devcouncil.execution.task_runner import TaskRunner
 from devcouncil.execution.context_builder import ContextBuilder
+from devcouncil.execution.prompt_builder import PromptBuilder
 from devcouncil.execution.paths import resolve_project_path
+from devcouncil.app.errors import ExecutionError
 
 console = Console()
 
+# Resilience bounds for the preview native loop.
+MAX_AGENT_STEPS = 10
+MAX_STRUCTURED_FAILURES = 2          # model can't produce a valid action -> give up cleanly
+MAX_CONSECUTIVE_PATCH_FAILURES = 3   # stop spinning on a patch the model can't fix
+
 class ToolCall(BaseModel):
     tool: str
     args: Dict[str, Any]
@@ -24,23 +32,40 @@ class NativeAgent(Executor):
     def __init__(self, router: ModelRouter, task_runner: TaskRunner):
         self.router = router
         self.task_runner = task_runner
+        # ContextBuilder is retained only for the cheap list_files file listing; the
+        # implementation context itself uses the budgeted PromptBuilder so the native
+        # executor gets the same repo-map orientation, symbol outlines, dependents and
+        # context-window budgeting as the CLI executors (rather than a flat JSON dump).
         self.context_builder = ContextBuilder(task_runner.project_root)
+        self.prompt_builder = PromptBuilder(task_runner.project_root)
+
+    def run_task(self, task: Task, requirements: List[Requirement]) -> ExecutionResult:
+        """Run the preview native executor behind the normal synchronous executor contract."""
+        return asyncio.run(self._run_task_async(task, requirements))
 
-    async def run_task(self, task: Task, requirements: List[Requirement]) -> ExecutionResult:
+    async def _run_task_async(self, task: Task, requirements: List[Requirement]) -> ExecutionResult:
         console.print(f"Starting [bold]Native Executor[/bold] for task {task.id}...")
+        console.print("[yellow]Native executor is preview quality; DevCouncil verification remains the completion gate.[/yellow]")
         
-        # 1. Gather rich context
-        context_json = self.context_builder.build_task_context(task, requirements)
-        
+        # 1. Gather rich context (budgeted; includes repo-map orientation + symbol outlines)
+        context_block = self.prompt_builder.build_task_prompt(task, requirements)
+        from devcouncil.planning.correction_manifest import load_latest_correction_manifest
+
+        correction = load_latest_correction_manifest(self.task_runner.project_root, task.id)
+        correction_block = ""
+        if correction is not None:
+            correction_block = f"\nCorrection Manifest:\n{correction.model_dump_json(indent=2)}\n"
+
         system_prompt = f"""
 You are the DevCouncil Native Agent. Your goal is to implement the provided task.
 Current Project Context:
-{context_json}
+{context_block}
+{correction_block}
 
 You have access to the following tools:
 - read_file(path: str)
 - list_files()
-- apply_patch(patch: str)
+- apply_patch(patch: str)  OR  apply_patch(path: str, content: str) as a fallback when a valid unified diff cannot be produced
 - run_command(command: str)
 
 Rules:
@@ -54,19 +79,59 @@ Rules:
         # Initial task prompt
         messages.append({"role": "user", "content": f"Begin implementing task {task.id} based on the context provided."})
 
-        # Basic tool loop (Max 10 steps for safety in MVP)
-        for step in range(10):
-            action = await self.router.complete_structured(
-                role="native_agent", 
-                messages=messages,
-                schema=AgentAction
-            )
-            
+        # Bounded tool loop. Counters let us fail a single task cleanly instead of
+        # crashing the whole run (structured-output faults) or spinning on an
+        # unfixable patch.
+        structured_failures = 0
+        consecutive_patch_failures = 0
+        for step in range(MAX_AGENT_STEPS):
+            try:
+                action = await self.router.complete_structured(
+                    role="native_agent",
+                    messages=messages,
+                    schema=AgentAction,
+                )
+            except StructuredOutputError as exc:
+                # The model could not produce a valid action even after healing/retry.
+                # native_agent has no fallback by design, so handle it here rather than
+                # letting it propagate and abort the entire `dev go` run.
+                structured_failures += 1
+                console.print(f"[red]Native agent could not parse a valid action: {exc}[/red]")
+                if structured_failures >= MAX_STRUCTURED_FAILURES:
+                    return ExecutionResult(
+                        success=False,
+                        message=f"Native agent gave up after {structured_failures} unparseable responses.",
+                    )
+                messages.append({
+                    "role": "user",
+                    "content": (
+                        "[System] Your previous response was not valid JSON for the "
+                        "AgentAction schema. Reply with a single valid JSON object only "
+                        "(fields: thought, tool_calls, finish) — no prose, no fences."
+                    ),
+                })
+                continue
+            structured_failures = 0
+
             console.print(f"\n[bold]Step {step+1}:[/bold] {action.thought}")
-            
+
+            # Record the agent's own turn so subsequent steps see what it already did.
+            # Without this the model only sees tool RESULTS, not its prior actions, and
+            # tends to repeat itself and never converge within the step budget.
+            messages.append({"role": "assistant", "content": action.model_dump_json()})
+
             if action.finish:
                 console.print("[green]Native agent signaled completion.[/green]")
-                return ExecutionResult(success=True, message="Agent signaled completion")
+                return ExecutionResult(success=True, message="Agent signaled completion; pending DevCouncil verification")
+
+            if not action.tool_calls:
+                # No action and not finished — nudge instead of silently burning a step.
+                messages.append({"role": "user", "content": (
+                    "[System] You produced no tool_calls and did not finish. Call a tool "
+                    "(read_file/list_files/apply_patch/run_command) to make progress, or set "
+                    "finish=true if the task is complete."
+                )})
+                continue
 
             for tool_call in action.tool_calls:
                 result_summary = ""
@@ -90,8 +155,26 @@ Rules:
                     elif tool_call.tool == "write_file":
                         raise PermissionError("write_file is disabled for the native executor; use apply_patch.")
                     elif tool_call.tool == "apply_patch":
-                        self.task_runner.apply_patch(tool_call.args["patch"], task)
-                        result_summary = "Successfully applied patch."
+                        if "path" in tool_call.args and "content" in tool_call.args:
+                            # Fallback for when the model can't produce a valid unified
+                            # diff. Routes through write_file, which enforces the same
+                            # planned-files permission check — no widening of scope.
+                            self.task_runner.write_file(
+                                tool_call.args["path"], tool_call.args["content"], task
+                            )
+                            consecutive_patch_failures = 0
+                            result_summary = f"Wrote {tool_call.args['path']} via path+content fallback."
+                        else:
+                            patch = tool_call.args.get("patch", "")
+                            if not patch or not patch.strip():
+                                raise ExecutionError(
+                                    "Empty patch. Provide a unified git diff beginning with "
+                                    "'diff --git a/<path> b/<path>', then '--- a/<path>' (or "
+                                    "'--- /dev/null' for a new file), '+++ b/<path>', and '@@' hunks."
+                                )
+                            self.task_runner.apply_patch(patch, task)
+                            consecutive_patch_failures = 0
+                            result_summary = "Successfully applied patch."
                     elif tool_call.tool == "run_command":
                         cmd_result = self.task_runner.run_command(tool_call.args["command"], task)
                         result_summary = f"Command finished with exit code {cmd_result.exit_code}."
@@ -101,7 +184,25 @@ Rules:
                     messages.append({"role": "user", "content": f"[Tool Result] '{tool_call.tool}': {result_summary}"})
                 except Exception as e:
                     console.print(f"[red]Error executing tool {tool_call.tool}: {e}[/red]")
-                    messages.append({"role": "user", "content": f"[Tool Error] '{tool_call.tool}' failed: {e}"})
+                    if tool_call.tool == "apply_patch":
+                        consecutive_patch_failures += 1
+                        if consecutive_patch_failures >= MAX_CONSECUTIVE_PATCH_FAILURES:
+                            return ExecutionResult(
+                                success=False,
+                                message=(
+                                    f"Native agent failed to apply a patch "
+                                    f"{consecutive_patch_failures} times in a row."
+                                ),
+                            )
+                        messages.append({"role": "user", "content": (
+                            f"[Tool Error] 'apply_patch' failed: {e}\n"
+                            "Re-read the target file, match the existing context lines EXACTLY, "
+                            "and do NOT resubmit the same patch. If you cannot produce a valid "
+                            "unified diff, call apply_patch with 'path' and 'content' instead to "
+                            "write the whole file."
+                        )})
+                    else:
+                        messages.append({"role": "user", "content": f"[Tool Error] '{tool_call.tool}' failed: {e}"})
 
         console.print("[red]Native agent reached maximum step limit.[/red]")
         return ExecutionResult(success=False, message="Reached maximum step limit")

package/src/devcouncil/gating/checks/clean_git.py

@@ -9,7 +9,9 @@ class CleanGitCheck:
 
     def _is_runtime_state(self, line: str) -> bool:
         path = line[3:].strip().replace("\\", "/")
-        return path.startswith(".devcouncil/")
+        # DevCouncil manages the root .gitignore itself (ensure_gitignore runs on
+        # init and before every task), so it must not block execution.
+        return path.startswith(".devcouncil/") or path == ".gitignore"
     
     def check(self, project_root, task_id: str) -> list[Gap]:
         try:

package/src/devcouncil/gating/checks/secret_scan_check.py

@@ -1,34 +1,53 @@
+import re
 from typing import List
 from devcouncil.domain.gap import Gap
 from devcouncil.utils.redaction import SECRET_PATTERNS, redact_string
 
+# Captures the new-file starting line from a unified-diff hunk header (@@ -a,b +c,d @@).
+_HUNK_RE = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@")
+
+
 class SecretScanner:
     """Scans code diffs for potential secrets (API keys, tokens, etc.)."""
-    
+
     def scan_diff(self, diff_content: str, task_id: str) -> List[Gap]:
-        gaps = []
-        lines = diff_content.splitlines()
+        gaps: List[Gap] = []
         current_file = "unknown_file"
-        
-        for i, line in enumerate(lines):
+        new_line_no = 0  # line number in the new file, tracked across hunks
+        counter = 0      # ensures unique gap ids
+
+        for line in diff_content.splitlines():
             if line.startswith("+++ b/"):
                 current_file = line[6:]
                 continue
-                
-            # Only scan added lines in diff
-            if not line.startswith("+") or line.startswith("+++"):
+            if line.startswith("+++") or line.startswith("---") or line.startswith("diff "):
+                continue
+            hunk = _HUNK_RE.match(line)
+            if hunk:
+                new_line_no = int(hunk.group(1))
+                continue
+            if line.startswith("-"):
+                continue  # removed line — does not advance the new-file counter
+            if line.startswith("+"):
+                for key_type, pattern in SECRET_PATTERNS.items():
+                    if pattern.search(line):
+                        counter += 1
+                        gaps.append(Gap(
+                            id=f"GAP-{task_id}-SECRET-{key_type.upper()}-{new_line_no}-{counter}",
+                            severity="critical",
+                            gap_type="security_risk",
+                            task_id=task_id,
+                            description=f"Potential {key_type} found in {current_file}:{new_line_no}.",
+                            evidence=[redact_string(line.strip())],
+                            recommended_fix="Remove the secret and use environment variables or a secret manager.",
+                            blocking=True,
+                            # Populate the routing fields so the security NextAction points
+                            # the agent straight at the file:line instead of forcing a re-grep.
+                            file=current_file,
+                            line=new_line_no,
+                        ))
+                new_line_no += 1
                 continue
-                
-            for key_type, pattern in SECRET_PATTERNS.items():
-                if pattern.search(line):
-                    gaps.append(Gap(
-                        id=f"GAP-{task_id}-SECRET-{key_type.upper()}-{i}",
-                        severity="critical",
-                        gap_type="security_risk",
-                        task_id=task_id,
-                        description=f"Potential {key_type} found in {current_file} (diff line {i+1}).",
-                        evidence=[redact_string(line.strip())],
-                        recommended_fix="Remove the secret and use environment variables or a secret manager.",
-                        blocking=True
-                    ))
+            # Context or blank line — advances the new-file counter.
+            new_line_no += 1
         return gaps

package/src/devcouncil/gating/policy.py

@@ -15,6 +15,64 @@ class GateResult(BaseModel):
     passed: bool
     gaps: List[Gap]
 
+
+def _find_dependency_cycle(tasks: List[Task]) -> Optional[List[str]]:
+    """Return one dependency cycle as an id path (e.g. [A, B, A]), or None. Only edges
+    to known task ids are followed; unknown deps are reported separately."""
+    ids = {t.id for t in tasks}
+    graph = {t.id: [d for d in t.depends_on if d in ids] for t in tasks}
+    WHITE, GREY, BLACK = 0, 1, 2
+    color = {tid: WHITE for tid in graph}
+    stack: List[str] = []
+
+    def visit(node: str) -> Optional[List[str]]:
+        color[node] = GREY
+        stack.append(node)
+        for nxt in graph.get(node, []):
+            if color[nxt] == GREY:
+                return stack[stack.index(nxt):] + [nxt]
+            if color[nxt] == WHITE:
+                found = visit(nxt)
+                if found:
+                    return found
+        stack.pop()
+        color[node] = BLACK
+        return None
+
+    for tid in graph:
+        if color[tid] == WHITE:
+            found = visit(tid)
+            if found:
+                return found
+    return None
+
+
+def topological_order(tasks: List[Task]) -> List[Task]:
+    """Order tasks so every task follows the ones it depends on. Stable: preserves the
+    given order among independent tasks. Falls back to the original order if a cycle
+    makes a full ordering impossible (the plan gate blocks cycles separately)."""
+    by_id = {t.id: t for t in tasks}
+    indegree = {t.id: 0 for t in tasks}
+    dependents: dict[str, List[str]] = {t.id: [] for t in tasks}
+    for task in tasks:
+        for dep in task.depends_on:
+            if dep in by_id:
+                indegree[task.id] += 1
+                dependents[dep].append(task.id)
+    # Kahn's algorithm, seeded in original order for stability.
+    ready = [t.id for t in tasks if indegree[t.id] == 0]
+    ordered: List[str] = []
+    while ready:
+        current = ready.pop(0)
+        ordered.append(current)
+        for child in dependents[current]:
+            indegree[child] -= 1
+            if indegree[child] == 0:
+                ready.append(child)
+    if len(ordered) != len(tasks):  # cycle — fall back to original order
+        return list(tasks)
+    return [by_id[tid] for tid in ordered]
+
 class GatePolicy:
     """Central engine for executing project and task level quality gates."""
     
@@ -104,6 +162,65 @@ class GatePolicy:
                     blocking=True,
                 ))
 
+        # Surface read-only-only tasks at PLANNING time (advisory): a task that declares
+        # planned files but none writable can implement nothing, and was previously only
+        # caught at execution by the task-readiness gate.
+        for task in tasks:
+            if task.planned_files and not any(
+                pf.allowed_change in ("create", "modify", "delete") for pf in task.planned_files
+            ):
+                gaps.append(Gap(
+                    id=f"GAP-PLAN-{task.id}-READ-ONLY",
+                    severity="medium",
+                    gap_type="task_not_implemented",
+                    task_id=task.id,
+                    description=(
+                        f"Task {task.id} declares planned files but none are writable "
+                        "(all read_only); it cannot implement any change. Expected only if "
+                        "this is an analysis-only task."
+                    ),
+                    recommended_fix=(
+                        "Grant 'create', 'modify', or 'delete' to at least one planned file, "
+                        "or confirm the task is intentionally analysis-only."
+                    ),
+                    blocking=False,
+                ))
+
+        # Surface overlapping ownership (advisory): when 2+ tasks each declare a
+        # writable (create/modify/delete) change to the SAME file, the plan is
+        # over-decomposed — the later task tends to duplicate or conflict with the
+        # earlier one (e.g. both add the same function), which then fails per-task
+        # verification. Consolidating a file's work into one task avoids this.
+        writers_by_file: dict[str, list[str]] = {}
+        for task in tasks:
+            for pf in task.planned_files:
+                if pf.allowed_change in ("create", "modify", "delete"):
+                    path = pf.path.replace("\\", "/")
+                    writers_by_file.setdefault(path, [])
+                    if task.id not in writers_by_file[path]:
+                        writers_by_file[path].append(task.id)
+        for path, owners in writers_by_file.items():
+            if len(owners) > 1:
+                gaps.append(Gap(
+                    id=f"GAP-PLAN-OVERLAP-{owners[0]}-{path.replace('/', '_')}",
+                    severity="medium",
+                    gap_type="task_not_implemented",
+                    description=(
+                        f"{len(owners)} tasks ({', '.join(owners)}) each declare writable "
+                        f"changes to {path}; overlapping ownership over-decomposes the plan "
+                        "and tends to cause duplicate/conflicting edits at execution."
+                    ),
+                    recommended_fix=(
+                        f"Consolidate the work on {path} into a single task, or scope the "
+                        "others to read_only."
+                    ),
+                    blocking=False,
+                ))
+
+        # Validate the task dependency DAG: unknown depends_on ids and cycles would make
+        # execution ordering impossible / stall the run, so block the plan on them.
+        gaps.extend(self._validate_task_dependencies(tasks))
+
         for assumption in assumptions or []:
             if (
                 assumption.impact == "high"
@@ -159,32 +276,63 @@ class GatePolicy:
         # 2. Check planned files
         gaps.extend(self.planned_files.check(task))
 
-        # 3. Check execution/verification evidence contract
-        if not task.allowed_commands:
+        # 3. Surface a missing execution/verification contract — but do NOT block
+        # execution on it. The executor still needs to run to implement the code,
+        # and the evidence requirement is genuinely enforced at verify time
+        # (acceptance_criteria_unproven / NOAC gaps). Blocking here only prevents
+        # implementation and stalls multi-task plans when the planner under-specs a
+        # task; these stay advisory so the work can proceed and be judged on output.
+        if not task.allowed_commands and not task.expected_tests:
             gaps.append(Gap(
                 id=f"GAP-{task.id}-NO-COMMANDS",
-                severity="high",
+                severity="medium",
                 gap_type="missing_test",
                 task_id=task.id,
                 description=f"Task {task.id} has no allowed commands for execution or verification.",
-                recommended_fix="Add explicit allowed_commands for the task before execution.",
-                blocking=True,
+                recommended_fix="Add explicit allowed_commands or expected_tests so verification can prove the acceptance criteria.",
+                blocking=False,
             ))
 
         if not task.expected_tests:
             gaps.append(Gap(
                 id=f"GAP-{task.id}-NO-EXPECTED-EVIDENCE",
-                severity="high",
+                severity="medium",
                 gap_type="missing_test",
                 task_id=task.id,
                 description=f"Task {task.id} has no expected verification evidence.",
                 recommended_fix="Add expected_tests or targeted static/manual review commands that prove the acceptance criteria.",
-                blocking=True,
+                blocking=False,
             ))
 
-        # 4. Check for task dependencies (if implemented)
-        
         return GateResult(
-            passed=len([g for g in gaps if g.blocking]) == 0, 
+            passed=len([g for g in gaps if g.blocking]) == 0,
             gaps=gaps
         )
+
+    def _validate_task_dependencies(self, tasks: List[Task]) -> List[Gap]:
+        """Block on a malformed dependency DAG: unknown depends_on ids and cycles."""
+        gaps: List[Gap] = []
+        ids = {t.id for t in tasks}
+        for task in tasks:
+            unknown = [dep for dep in task.depends_on if dep not in ids]
+            if unknown:
+                gaps.append(Gap(
+                    id=f"GAP-PLAN-{task.id}-UNKNOWN-DEP",
+                    severity="high",
+                    gap_type="task_not_implemented",
+                    task_id=task.id,
+                    description=f"Task {task.id} depends on unknown task(s): {', '.join(unknown)}.",
+                    recommended_fix="Reference only task IDs that exist in this plan, or remove the dependency.",
+                    blocking=True,
+                ))
+        cycle = _find_dependency_cycle(tasks)
+        if cycle:
+            gaps.append(Gap(
+                id="GAP-PLAN-DEP-CYCLE",
+                severity="high",
+                gap_type="task_not_implemented",
+                description=f"Task dependency cycle detected: {' -> '.join(cycle)}.",
+                recommended_fix="Break the cycle so the tasks can be ordered and executed.",
+                blocking=True,
+            ))
+        return gaps

package/src/devcouncil/hardware.py

@@ -0,0 +1,184 @@
+"""Host hardware detection used to size local (Ollama) models.
+
+DevCouncil runs the council roles against whatever LLM provider is configured.
+For the local ``ollama`` provider the model has to fit in host memory. On Apple
+Silicon Macs that memory is *unified* (shared by CPU/GPU/OS), so total RAM is the
+ceiling. On a host with a discrete GPU (NVIDIA), Ollama offloads to VRAM, so the
+*VRAM* is the practical ceiling instead — a 64 GB box with an 8 GB GPU should not be
+told to run a model that only fits in system RAM. This module exposes small, pure
+helpers so ``dev doctor`` and ``dev setup`` can recommend a model that will actually
+run instead of a one-size-fits-all default, on macOS, Linux and Windows.
+
+Everything here is best-effort and stdlib-only: detection failures return
+``None`` rather than raising, so callers degrade to the static default.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+from dataclasses import dataclass
+
+# Recommended Ollama context window for DevCouncil's large planning prompts.
+# Kept in sync with the value surfaced by `dev doctor`.
+RECOMMENDED_NUM_CTX = 16384
+
+# Fallback model when the host is unknown or has little memory. Matches the
+# static defaults in ``llm/model_defaults.yaml``.
+DEFAULT_OLLAMA_MODEL = "qwen2.5-coder:7b"
+
+# RAM (GiB) -> recommended qwen2.5-coder size. Highest matching tier wins.
+# Sizes are chosen so the quantized weights plus a 16k context comfortably fit
+# alongside the OS in Apple Silicon unified memory.
+_OLLAMA_MODEL_TIERS: tuple[tuple[float, str], ...] = (
+    (48.0, "qwen2.5-coder:32b"),
+    (24.0, "qwen2.5-coder:14b"),
+    (0.0, "qwen2.5-coder:7b"),
+)
+
+
+def is_macos() -> bool:
+    return platform.system() == "Darwin"
+
+
+def is_apple_silicon() -> bool:
+    """True on Apple-Silicon (arm64) Macs."""
+    return is_macos() and platform.machine() == "arm64"
+
+
+def mac_chip_brand() -> str | None:
+    """Marketing CPU string on macOS (e.g. ``Apple M3 Pro``), else None."""
+    if not is_macos():
+        return None
+    try:
+        out = subprocess.check_output(
+            ["sysctl", "-n", "machdep.cpu.brand_string"],
+            text=True,
+            timeout=5,
+        ).strip()
+        return out or None
+    except Exception:
+        return None
+
+
+def total_ram_gb() -> float | None:
+    """Total physical RAM in GiB, or None if it cannot be determined."""
+    try:
+        if is_macos():
+            out = subprocess.check_output(
+                ["sysctl", "-n", "hw.memsize"], text=True, timeout=5
+            ).strip()
+            return int(out) / (1024**3)
+        # POSIX (Linux): pages * page size.
+        pages = os.sysconf("SC_PHYS_PAGES")
+        page_size = os.sysconf("SC_PAGE_SIZE")
+        return (pages * page_size) / (1024**3)
+    except (OSError, ValueError, AttributeError, subprocess.SubprocessError):
+        return None
+
+
+def nvidia_vram_gb() -> float | None:
+    """Total VRAM (GiB) of the largest NVIDIA GPU via ``nvidia-smi``, else ``None``.
+
+    On hosts with a discrete NVIDIA GPU this is the real ceiling for Ollama, since the
+    model is offloaded to VRAM. Returns ``None`` when ``nvidia-smi`` is absent (no GPU,
+    Apple Silicon, or an unsupported vendor), so callers fall back to total RAM."""
+    if not shutil.which("nvidia-smi"):
+        return None
+    try:
+        out = subprocess.check_output(
+            ["nvidia-smi", "--query-gpu=memory.total", "--format=csv,noheader,nounits"],
+            text=True,
+            timeout=5,
+            stderr=subprocess.DEVNULL,
+        ).strip()
+    except (OSError, subprocess.SubprocessError):
+        return None
+    sizes_mib: list[float] = []
+    for line in out.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            sizes_mib.append(float(line))
+        except ValueError:
+            continue
+    if not sizes_mib:
+        return None
+    return max(sizes_mib) / 1024.0  # MiB -> GiB
+
+
+def recommend_ollama_model(ram_gb: float | None = None, vram_gb: float | None = None) -> str:
+    """Largest qwen2.5-coder size expected to run on the host.
+
+    When a discrete GPU's ``vram_gb`` is known it is the ceiling (Ollama offloads to
+    VRAM); otherwise total system RAM is used (correct for unified-memory Macs and
+    CPU-only hosts)."""
+    if ram_gb is None:
+        ram_gb = total_ram_gb()
+    effective = vram_gb if vram_gb is not None else ram_gb
+    if effective is None:
+        return DEFAULT_OLLAMA_MODEL
+    for floor, model in _OLLAMA_MODEL_TIERS:
+        if effective >= floor:
+            return model
+    return DEFAULT_OLLAMA_MODEL
+
+
+@dataclass(frozen=True)
+class HostSummary:
+    """A snapshot of the host relevant to local-model sizing."""
+
+    is_macos: bool
+    is_apple_silicon: bool
+    chip: str | None
+    ram_gb: float | None
+    recommended_ollama_model: str
+    vram_gb: float | None = None
+
+    @property
+    def ram_label(self) -> str:
+        return f"{self.ram_gb:.0f} GB" if self.ram_gb is not None else "unknown RAM"
+
+    @property
+    def vram_label(self) -> str | None:
+        return f"{self.vram_gb:.0f} GB VRAM" if self.vram_gb is not None else None
+
+    @property
+    def chip_label(self) -> str:
+        if self.chip:
+            return self.chip
+        if self.is_apple_silicon:
+            return "Apple Silicon"
+        if self.vram_gb is not None:
+            return "discrete GPU host"
+        return "this host"
+
+    @property
+    def platform_label(self) -> str:
+        """Human label for the sizing row across OSes."""
+        if self.is_macos:
+            return "Apple Silicon" if self.is_apple_silicon else "Mac (Intel)"
+        system = platform.system()
+        return system or "Host"
+
+    @property
+    def memory_label(self) -> str:
+        """Memory ceiling used for the recommendation (VRAM if discrete GPU, else RAM)."""
+        vram = self.vram_label
+        return f"{vram} (GPU)" if vram else self.ram_label
+
+
+def describe_host() -> HostSummary:
+    ram = total_ram_gb()
+    vram = nvidia_vram_gb()
+    return HostSummary(
+        is_macos=is_macos(),
+        is_apple_silicon=is_apple_silicon(),
+        chip=mac_chip_brand(),
+        ram_gb=ram,
+        vram_gb=vram,
+        recommended_ollama_model=recommend_ollama_model(ram, vram),
+    )