devcouncil 0.1.1 → 0.2.0

package/src/devcouncil/storage/repositories.py

@@ -1,4 +1,4 @@
-from sqlmodel import Session, select, delete
+from sqlmodel import Session, col, delete, select
 from typing import List, Optional, Any
 import json
 from devcouncil.storage.models import (
@@ -14,7 +14,7 @@ from devcouncil.domain.requirement import Requirement, AcceptanceCriterion
 from devcouncil.domain.assumption import Assumption
 from devcouncil.domain.task import Task, PlannedFile
 from devcouncil.domain.gap import Gap
-from devcouncil.domain.evidence import CommandResult, DiffEvidence, TestEvidence
+from devcouncil.domain.evidence import CommandResult, DiffEvidence, DiffCoverageEvidence, TestEvidence
 from devcouncil.domain.critique import CritiqueFinding
 from devcouncil.artifacts.graph import ArtifactGraph
 
@@ -28,14 +28,14 @@ class RequirementRepository:
         results = []
         for m in models:
             ac_list = [AcceptanceCriterion.model_validate(ac) for ac in json.loads(m.acceptance_criteria_json)]
-            results.append(Requirement(
-                id=m.id,
-                title=m.title,
-                description=m.description,
-                priority=m.priority,
-                source=m.source,
-                acceptance_criteria=ac_list
-            ))
+            results.append(Requirement.model_validate({
+                "id": m.id,
+                "title": m.title,
+                "description": m.description,
+                "priority": m.priority,
+                "source": m.source,
+                "acceptance_criteria": ac_list,
+            }))
         return results
 
     def save(self, req: Requirement):
@@ -59,16 +59,16 @@ class AssumptionRepository:
         statement = select(AssumptionModel)
         models = self.session.exec(statement).all()
         return [
-            Assumption(
-                id=m.id,
-                statement=m.statement,
-                confidence=m.confidence,
-                impact=m.impact,
-                reversible=m.reversible,
-                requires_user_confirmation=m.requires_user_confirmation,
-                linked_requirement_ids=json.loads(m.linked_requirement_ids_json),
-                status=m.status,
-            )
+            Assumption.model_validate({
+                "id": m.id,
+                "statement": m.statement,
+                "confidence": m.confidence,
+                "impact": m.impact,
+                "reversible": m.reversible,
+                "requires_user_confirmation": m.requires_user_confirmation,
+                "linked_requirement_ids": json.loads(m.linked_requirement_ids_json),
+                "status": m.status,
+            })
             for m in models
         ]
 
@@ -97,18 +97,18 @@ class TaskRepository:
             return None
         
         pf_list = [PlannedFile.model_validate(pf) for pf in json.loads(m.planned_files_json)]
-        return Task(
-            id=m.id,
-            title=m.title,
-            description=m.description,
-            requirement_ids=json.loads(m.requirement_ids_json),
-            acceptance_criterion_ids=json.loads(m.acceptance_criterion_ids_json),
-            planned_files=pf_list,
-            expected_tests=json.loads(m.expected_tests_json),
-            allowed_commands=json.loads(m.allowed_commands_json),
-            forbidden_changes=json.loads(m.forbidden_changes_json),
-            status=m.status
-        )
+        return Task.model_validate({
+            "id": m.id,
+            "title": m.title,
+            "description": m.description,
+            "requirement_ids": json.loads(m.requirement_ids_json),
+            "acceptance_criterion_ids": json.loads(m.acceptance_criterion_ids_json),
+            "planned_files": pf_list,
+            "expected_tests": json.loads(m.expected_tests_json),
+            "allowed_commands": json.loads(m.allowed_commands_json),
+            "forbidden_changes": json.loads(m.forbidden_changes_json),
+            "status": m.status,
+        })
 
     def get_all(self) -> List[Task]:
         statement = select(TaskModel)
@@ -116,18 +116,18 @@ class TaskRepository:
         results = []
         for m in models:
             pf_list = [PlannedFile.model_validate(pf) for pf in json.loads(m.planned_files_json)]
-            results.append(Task(
-                id=m.id,
-                title=m.title,
-                description=m.description,
-                requirement_ids=json.loads(m.requirement_ids_json),
-                acceptance_criterion_ids=json.loads(m.acceptance_criterion_ids_json),
-                planned_files=pf_list,
-                expected_tests=json.loads(m.expected_tests_json),
-                allowed_commands=json.loads(m.allowed_commands_json),
-                forbidden_changes=json.loads(m.forbidden_changes_json),
-                status=m.status
-            ))
+            results.append(Task.model_validate({
+                "id": m.id,
+                "title": m.title,
+                "description": m.description,
+                "requirement_ids": json.loads(m.requirement_ids_json),
+                "acceptance_criterion_ids": json.loads(m.acceptance_criterion_ids_json),
+                "planned_files": pf_list,
+                "expected_tests": json.loads(m.expected_tests_json),
+                "allowed_commands": json.loads(m.allowed_commands_json),
+                "forbidden_changes": json.loads(m.forbidden_changes_json),
+                "status": m.status,
+            }))
         return results
 
     def save(self, task: Task):
@@ -155,17 +155,21 @@ class GapRepository:
         models = self.session.exec(statement).all()
         results = []
         for m in models:
-            results.append(Gap(
-                id=m.id,
-                severity=m.severity,
-                gap_type=m.gap_type,
-                requirement_id=m.requirement_id,
-                task_id=m.task_id,
-                description=m.description,
-                evidence=json.loads(m.evidence_json),
-                recommended_fix=m.recommended_fix,
-                blocking=m.blocking
-            ))
+            results.append(Gap.model_validate({
+                "id": m.id,
+                "severity": m.severity,
+                "gap_type": m.gap_type,
+                "requirement_id": m.requirement_id,
+                "task_id": m.task_id,
+                "description": m.description,
+                "evidence": json.loads(m.evidence_json),
+                "recommended_fix": m.recommended_fix,
+                "blocking": m.blocking,
+                "file": m.file,
+                "line": m.line,
+                "suggested_command": m.suggested_command,
+                "acceptance_criterion_id": m.acceptance_criterion_id,
+            }))
         return results
 
     def save(self, gap: Gap):
@@ -178,17 +182,21 @@ class GapRepository:
             description=gap.description,
             evidence_json=json.dumps(gap.evidence),
             recommended_fix=gap.recommended_fix,
-            blocking=gap.blocking
+            blocking=gap.blocking,
+            file=gap.file,
+            line=gap.line,
+            suggested_command=gap.suggested_command,
+            acceptance_criterion_id=gap.acceptance_criterion_id,
         )
         self.session.merge(model)
         self.session.commit()
 
     def delete_for_task(self, task_id: str):
-        self.session.exec(delete(GapModel).where(GapModel.task_id == task_id))
+        self.session.exec(delete(GapModel).where(col(GapModel.task_id) == task_id))
         self.session.commit()
 
     def delete_plan_gaps(self):
-        self.session.exec(delete(GapModel).where(GapModel.id.like("GAP-PLAN-%")))
+        self.session.exec(delete(GapModel).where(col(GapModel.id).like("GAP-PLAN-%")))
         self.session.commit()
 
 class EvidenceRepository:
@@ -224,22 +232,40 @@ class EvidenceRepository:
         self.session.add(model)
         self.session.commit()
 
+    def save_diff_coverage_evidence(self, ev: DiffCoverageEvidence):
+        model = EvidenceModel(
+            type="diff_coverage",
+            task_id=ev.task_id,
+            data_json=ev.model_dump_json()
+        )
+        self.session.add(model)
+        self.session.commit()
+
+    def get_command_results_for_task(self, task_id: str) -> List[CommandResult]:
+        statement = select(EvidenceModel).where(EvidenceModel.task_id == task_id).where(
+            EvidenceModel.type == "command"
+        )
+        models = self.session.exec(statement).all()
+        return [CommandResult.model_validate(json.loads(m.data_json)) for m in models]
+
     def get_all(self) -> List[Any]:
         statement = select(EvidenceModel)
         models = self.session.exec(statement).all()
-        results = []
+        results: List[Any] = []
         for m in models:
             data = json.loads(m.data_json)
             if m.type == "command":
                 results.append(CommandResult.model_validate(data))
             elif m.type == "diff":
                 results.append(DiffEvidence.model_validate(data))
+            elif m.type == "diff_coverage":
+                results.append(DiffCoverageEvidence.model_validate(data))
             elif m.type == "test":
                 results.append(TestEvidence.model_validate(data))
         return results
 
     def delete_for_task(self, task_id: str):
-        self.session.exec(delete(EvidenceModel).where(EvidenceModel.task_id == task_id))
+        self.session.exec(delete(EvidenceModel).where(col(EvidenceModel.task_id) == task_id))
         self.session.commit()
 
 
@@ -251,19 +277,19 @@ class CritiqueFindingRepository:
         statement = select(CritiqueFindingModel)
         models = self.session.exec(statement).all()
         return [
-            CritiqueFinding(
-                id=m.id,
-                source_agent=m.source_agent,
-                target_plan_id=m.target_plan_id,
-                severity=m.severity,
-                finding_type=m.finding_type,
-                claim=m.claim,
-                linked_requirement_id=m.linked_requirement_id,
-                suggested_requirement=m.suggested_requirement,
-                suggested_task=m.suggested_task,
-                falsifiable_check=m.falsifiable_check,
-                status=m.status,
-            )
+            CritiqueFinding.model_validate({
+                "id": m.id,
+                "source_agent": m.source_agent,
+                "target_plan_id": m.target_plan_id,
+                "severity": m.severity,
+                "finding_type": m.finding_type,
+                "claim": m.claim,
+                "linked_requirement_id": m.linked_requirement_id,
+                "suggested_requirement": m.suggested_requirement,
+                "suggested_task": m.suggested_task,
+                "falsifiable_check": m.falsifiable_check,
+                "status": m.status,
+            })
             for m in models
         ]
 
@@ -386,6 +412,10 @@ class ArtifactGraphRepository:
         for ev in self.evidence_repo.get_all():
             if isinstance(ev, CommandResult):
                 graph.add_command_result(ev)
+            elif isinstance(ev, DiffCoverageEvidence):
+                # Must precede DiffEvidence: distinct type, and the diff↔coverage proof
+                # was silently dropped on reload before this branch existed.
+                graph.add_diff_coverage_evidence(ev)
             elif isinstance(ev, DiffEvidence):
                 graph.add_diff_evidence(ev)
             elif isinstance(ev, TestEvidence):
@@ -416,8 +446,40 @@ class StateRepository:
     def record_phase(self, phase: str):
         current = self.get_state()
         history = []
+        prev = None
         if current:
             history = json.loads(current.history_json)
-        if not history or history[-1] != phase:
-            history.append(phase)
+            prev = current.current_phase
+        # Keep the persisted history a LEGAL transition sequence. A repair re-run records
+        # TASK_EXECUTING straight after a terminal TASK_BLOCKED/TASK_VERIFIED, which is not
+        # a direct transition; bridge it through the intermediate phase (TASK_READY) so the
+        # state machine's invariant holds on reload. Fail-soft: an unbridgeable jump is
+        # still recorded verbatim rather than lost.
+        for step in self._bridge_phases(prev, phase):
+            if not history or history[-1] != step:
+                history.append(step)
         self.save_state(phase, history)
+
+    @staticmethod
+    def _bridge_phases(prev: Optional[str], target: str) -> List[str]:
+        """Return the phases to append so prev -> ... -> target is a legal path.
+
+        Inserts a single intermediate phase when prev cannot transition directly to
+        target but a one-hop bridge exists (the repair loop's
+        TASK_BLOCKED/TASK_VERIFIED -> TASK_READY -> TASK_EXECUTING). Returns ``[target]``
+        when prev is unknown, equal, already-legal, or no one-hop bridge exists."""
+        if prev is None or prev == target:
+            return [target]
+        try:
+            from devcouncil.app.state_machine import TRANSITIONS, ProjectPhase
+
+            prev_phase = ProjectPhase(prev)
+            target_phase = ProjectPhase(target)
+        except (ImportError, ValueError):
+            return [target]
+        if target_phase in TRANSITIONS.get(prev_phase, set()):
+            return [target]
+        for mid in TRANSITIONS.get(prev_phase, set()):
+            if target_phase in TRANSITIONS.get(mid, set()):
+                return [mid.value, target]
+        return [target]

package/src/devcouncil/telemetry/cost.py

@@ -1,34 +1,140 @@
+import json
 import logging
-from typing import Dict
+from pathlib import Path
+from typing import Any, Dict, List
+
+from devcouncil.telemetry.pricing import pricing_for_model
 
 logger = logging.getLogger(__name__)
 
+UNATTRIBUTED = "(unattributed)"
+
+
 class CostEstimator:
     """Estimates LLM usage cost based on provider pricing."""
-    
-    # Rough estimates, update for production
-    PRICING = {
-        "anthropic/claude-3.5-sonnet": {"input": 0.000003, "output": 0.000015},
-        "anthropic/claude-3-opus": {"input": 0.000015, "output": 0.000075},
-        "anthropic/claude-sonnet-4": {"input": 0.000003, "output": 0.000015},
-        "google/gemini-pro-1.5": {"input": 0.00000125, "output": 0.000005},
-        "google/gemini-2.5-pro": {"input": 0.00000125, "output": 0.00001},
-        "openai/gpt-4o": {"input": 0.000005, "output": 0.000015},
-        "openai/o3-mini": {"input": 0.0000011, "output": 0.0000044},
-    }
 
     # Conservative default for unknown models
-    DEFAULT_PRICING = {"input": 0.000005, "output": 0.000015}
+    DEFAULT_PRICING = {"prompt_per_1k": 0.005, "completion_per_1k": 0.015}
+
+    # Local providers run on-device and incur no per-token cost. Ollama model ids
+    # are open-ended (e.g. ``qwen2.5-coder:7b`` or an ``ollama/<name>`` form), so
+    # match the conventional prefixes rather than relying on the open-ended yaml.
+    LOCAL_MODEL_PREFIXES = ("ollama/", "ollama:")
+
+    @classmethod
+    def _is_local_model(cls, model: str) -> bool:
+        return model.startswith(cls.LOCAL_MODEL_PREFIXES)
 
     @classmethod
     def estimate_cost(cls, model: str, usage: Dict[str, int]) -> float:
-        prices = cls.PRICING.get(model)
-        if not prices:
+        # Local/Ollama models are free regardless of yaml coverage; short-circuit
+        # before the conservative DEFAULT_PRICING fallback would bill them.
+        if cls._is_local_model(model):
+            return 0.0
+        prices = pricing_for_model(model, cls.DEFAULT_PRICING)
+        if prices == cls.DEFAULT_PRICING:
             logger.debug("Unknown model for cost estimation: %s — using default pricing", model)
-            prices = cls.DEFAULT_PRICING
             
         prompt_tokens = usage.get("prompt_tokens", 0)
         completion_tokens = usage.get("completion_tokens", 0)
         
-        cost = (prompt_tokens * prices["input"]) + (completion_tokens * prices["output"])
+        cost = ((prompt_tokens / 1000.0) * prices["prompt_per_1k"]) + (
+            (completion_tokens / 1000.0) * prices["completion_per_1k"]
+        )
         return cost
+
+
+def _model_calls_file(project_root: Path) -> Path:
+    return project_root / ".devcouncil" / "logs" / "model_calls.jsonl"
+
+
+def read_cost_records(project_root: Path) -> List[Dict[str, Any]]:
+    """Read the model-call ledger and attach an estimated cost to each record.
+
+    Never raises: malformed lines are skipped. Records missing ``task_id`` /
+    ``run_id`` (older entries written before per-task attribution) keep those as
+    ``None`` so callers can bucket them under ``(unattributed)``.
+    """
+    log_file = _model_calls_file(project_root)
+    records: List[Dict[str, Any]] = []
+    if not log_file.exists():
+        return records
+    try:
+        lines = log_file.read_text(encoding="utf-8").splitlines()
+    except Exception as exc:
+        logger.debug("Failed to read model_calls ledger: %s", exc)
+        return records
+
+    for line in lines:
+        if not line.strip():
+            continue
+        try:
+            entry = json.loads(line)
+        except Exception as exc:
+            logger.debug("Skipping invalid model_calls line: %s", exc)
+            continue
+        model = ""
+        response = entry.get("response")
+        if isinstance(response, dict):
+            model = str(response.get("model", "") or "")
+        raw_usage = entry.get("usage")
+        usage: Dict[str, Any] = raw_usage if isinstance(raw_usage, dict) else {}
+        # Local providers (ollama) are always free, regardless of the open-ended model
+        # tag Ollama echoes back (e.g. ``mistral:latest``) — trust the recorded provider
+        # over fragile model-id prefix matching.
+        provider = str(entry.get("provider") or "")
+        try:
+            cost = 0.0 if provider == "ollama" else CostEstimator.estimate_cost(model, usage)
+        except Exception:
+            cost = 0.0
+        records.append(
+            {
+                "task_id": entry.get("task_id"),
+                "run_id": entry.get("run_id"),
+                "timestamp": entry.get("timestamp"),
+                "model": model,
+                "usage": usage,
+                "cost": cost,
+            }
+        )
+    return records
+
+
+def _group(records: List[Dict[str, Any]], key: str) -> Dict[str, Dict[str, Any]]:
+    groups: Dict[str, Dict[str, Any]] = {}
+    for record in records:
+        raw = record.get(key)
+        bucket = str(raw) if isinstance(raw, str) and raw else UNATTRIBUTED
+        group = groups.setdefault(
+            bucket,
+            {"cost": 0.0, "calls": 0, "prompt_tokens": 0, "completion_tokens": 0},
+        )
+        raw_usage = record.get("usage")
+        usage: Dict[str, Any] = raw_usage if isinstance(raw_usage, dict) else {}
+        group["cost"] += float(record.get("cost", 0.0) or 0.0)
+        group["calls"] += 1
+        group["prompt_tokens"] += int(usage.get("prompt_tokens", 0) or 0)
+        group["completion_tokens"] += int(usage.get("completion_tokens", 0) or 0)
+    return groups
+
+
+def group_cost(project_root: Path) -> Dict[str, Any]:
+    """Aggregate model-call cost grouped by ``task_id`` and ``run_id``.
+
+    Returns a JSON-friendly summary: a grand total plus per-task and per-run
+    breakdowns. Unattributed records (older entries, or calls made without a
+    task/run context) are bucketed under ``(unattributed)``. Never raises.
+    """
+    records = read_cost_records(project_root)
+    total_cost = sum(float(record.get("cost", 0.0) or 0.0) for record in records)
+    return {
+        "total_cost": total_cost,
+        "total_calls": len(records),
+        "by_task": _group(records, "task_id"),
+        "by_run": _group(records, "run_id"),
+    }
+
+
+def cost_by_task(project_root: Path) -> Dict[str, Dict[str, Any]]:
+    """Convenience accessor for the per-task cost breakdown (used by ``dev status``)."""
+    return group_cost(project_root)["by_task"]

package/src/devcouncil/telemetry/model_pricing.yaml

@@ -0,0 +1,48 @@
+anthropic/claude-3-opus:
+  prompt_per_1k: 0.015
+  completion_per_1k: 0.075
+anthropic/claude-3.5-sonnet:
+  prompt_per_1k: 0.003
+  completion_per_1k: 0.015
+anthropic/claude-sonnet-4:
+  prompt_per_1k: 0.003
+  completion_per_1k: 0.015
+google/gemini-pro-1.5:
+  prompt_per_1k: 0.00125
+  completion_per_1k: 0.005
+google/gemini-2.5-pro:
+  prompt_per_1k: 0.00125
+  completion_per_1k: 0.01
+openai/gpt-4o:
+  prompt_per_1k: 0.005
+  completion_per_1k: 0.015
+openai/o3-mini:
+  prompt_per_1k: 0.0011
+  completion_per_1k: 0.0044
+anthropic/claude-sonnet-4.6:
+  prompt_per_1k: 0.003
+  completion_per_1k: 0.015
+anthropic/claude-opus-4.8:
+  prompt_per_1k: 0.005
+  completion_per_1k: 0.025
+openai/gpt-5.5:
+  prompt_per_1k: 0.005
+  completion_per_1k: 0.03
+google/gemini-2.5-flash:
+  prompt_per_1k: 0.0003
+  completion_per_1k: 0.0025
+# Local Ollama models run on-device and are free. Bare tags (no ``ollama/``
+# prefix) are listed here so the cost reporter shows $0; the cost.py prefix
+# guard covers any other ``ollama/`` or ``ollama:`` model id.
+qwen2.5-coder:7b:
+  prompt_per_1k: 0.0
+  completion_per_1k: 0.0
+qwen2.5-coder:14b:
+  prompt_per_1k: 0.0
+  completion_per_1k: 0.0
+qwen2.5-coder:32b:
+  prompt_per_1k: 0.0
+  completion_per_1k: 0.0
+llama3.1:
+  prompt_per_1k: 0.0
+  completion_per_1k: 0.0

package/src/devcouncil/telemetry/pricing.py

@@ -0,0 +1,28 @@
+from functools import lru_cache
+from importlib import resources
+from typing import Dict
+
+import yaml
+
+MODEL_PRICING_RESOURCE = "model_pricing.yaml"
+
+
+@lru_cache(maxsize=1)
+def load_model_pricing() -> Dict[str, Dict[str, float]]:
+    data = resources.files(__package__).joinpath(MODEL_PRICING_RESOURCE).read_text(encoding="utf-8")
+    loaded = yaml.safe_load(data) or {}
+    return {
+        str(model): {
+            "prompt_per_1k": float(pricing.get("prompt_per_1k", 0.0)),
+            "completion_per_1k": float(pricing.get("completion_per_1k", 0.0)),
+        }
+        for model, pricing in loaded.items()
+        if isinstance(pricing, dict)
+    }
+
+
+def pricing_for_model(model: str, default: Dict[str, float] | None = None) -> Dict[str, float]:
+    pricing = load_model_pricing().get(model)
+    if pricing is not None:
+        return pricing
+    return default or {"prompt_per_1k": 0.0, "completion_per_1k": 0.0}

package/src/devcouncil/telemetry/traces.py

@@ -3,7 +3,7 @@ import logging
 import uuid
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Dict, Iterable, Optional
+from typing import Any, Dict, Iterable, List, Optional, Tuple
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -31,14 +31,17 @@ class TraceEvent(BaseModel):
     def from_legacy(cls, raw: Dict[str, Any]) -> "TraceEvent":
         if raw.get("schema") == TRACE_SCHEMA_VERSION:
             return cls.model_validate(raw)
-        details = raw.get("details") if isinstance(raw.get("details"), dict) else {}
-        task_id = details.get("task_id") if isinstance(details.get("task_id"), str) else None
-        summary = details.get("summary") if isinstance(details.get("summary"), str) else ""
+        raw_details = raw.get("details")
+        details: Dict[str, Any] = raw_details if isinstance(raw_details, dict) else {}
+        raw_task_id = details.get("task_id")
+        raw_summary = details.get("summary")
+        raw_run_id = raw.get("run_id")
         return cls(
+            schema=TRACE_SCHEMA_VERSION,
             type=str(raw.get("type", "legacy_event")),
-            run_id=raw.get("run_id"),
-            task_id=task_id,
-            summary=summary,
+            run_id=raw_run_id if isinstance(raw_run_id, str) else None,
+            task_id=raw_task_id if isinstance(raw_task_id, str) else None,
+            summary=raw_summary if isinstance(raw_summary, str) else "",
             details=details,
         )
 
@@ -61,6 +64,7 @@ class TraceLogger:
     ) -> TraceEvent:
         """Append an orchestration event trace."""
         trace = TraceEvent(
+            schema=TRACE_SCHEMA_VERSION,
             type=event_type,
             details=details,
             run_id=run_id,
@@ -89,3 +93,54 @@ def read_trace_events(project_root: Path) -> Iterable[TraceEvent]:
         except Exception as exc:
             logger.debug("Skipping invalid trace line: %s", exc)
     return events
+
+
+def read_trace_events_since(
+    project_root: Path, cursor: Optional[int] = None
+) -> Tuple[List[TraceEvent], int]:
+    """Incrementally read trace events appended after ``cursor``.
+
+    The cursor is a byte offset into the trace file, which is robust to appends
+    (the file is append-only) and makes repeated polling O(new bytes) rather than
+    O(all events). Returns ``(events, next_cursor)`` where ``next_cursor`` should
+    be passed back on the next call to fetch only newer events.
+
+    Never raises: on any error it returns an empty batch and a safe cursor. A
+    ``cursor`` past the current end-of-file (e.g. the log was rotated/truncated)
+    is treated as a reset so the caller still makes progress.
+    """
+    trace_file = project_root / ".devcouncil" / "logs" / "traces.jsonl"
+    start = cursor if isinstance(cursor, int) and cursor >= 0 else 0
+    if not trace_file.exists():
+        return [], start
+
+    try:
+        size = trace_file.stat().st_size
+        # File shrank (rotation/truncation) — restart from the beginning.
+        if start > size:
+            start = 0
+
+        with open(trace_file, "rb") as f:
+            f.seek(start)
+            chunk = f.read()
+    except Exception as exc:
+        logger.debug("Failed incremental trace read: %s", exc)
+        return [], start
+
+    # Only consume up to the last complete line so a half-written final line is
+    # re-read (not skipped) on the next poll once it is fully flushed.
+    last_newline = chunk.rfind(b"\n")
+    if last_newline == -1:
+        return [], start
+    consumed = chunk[: last_newline + 1]
+    next_cursor = start + len(consumed)
+
+    events: List[TraceEvent] = []
+    for raw_line in consumed.decode("utf-8", errors="replace").splitlines():
+        if not raw_line.strip():
+            continue
+        try:
+            events.append(TraceEvent.from_legacy(json.loads(raw_line)))
+        except Exception as exc:
+            logger.debug("Skipping invalid trace line: %s", exc)
+    return events, next_cursor