devcouncil 0.2.0 → 0.3.0

package/src/devcouncil/telemetry/logging_setup.py

@@ -0,0 +1,244 @@
+"""Central logging configuration for DevCouncil.
+
+The codebase is sprinkled with ``logging.getLogger(__name__)`` calls across the
+orchestrator, planner, executors, verifier, and LLM layers — but historically no
+handler was ever installed, so every ``logger.info``/``logger.debug`` was silently
+discarded and only uncaught WARNING+ records reached stderr via Python's "last
+resort" handler. That made diagnosing the recurring run failures nearly
+impossible: the breadcrumbs existed but went nowhere.
+
+:func:`configure_logging` wires up two sinks, once per process:
+
+* a **rotating file** at ``.devcouncil/logs/devcouncil.log`` that always captures
+  *everything* at DEBUG — this is the durable record you grep after a bad run;
+* a **console** (stderr) handler whose level is dialed by ``-v``/``-q`` flags or
+  the ``DEVCOUNCIL_LOG_LEVEL`` env var, defaulting to WARNING so normal Rich CLI
+  output stays clean.
+
+It is idempotent: calling it again only adjusts the console level (e.g. when a
+command re-points at a different ``--project-root``), so importing modules can
+call it freely without stacking duplicate handlers.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from contextlib import contextmanager
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+from typing import Iterator, Optional
+
+# Sentinels so we can find (and reconfigure) our own handlers on repeat calls
+# without disturbing handlers another library may have installed on the root.
+_FILE_HANDLER_TAG = "devcouncil.file"
+_CONSOLE_HANDLER_TAG = "devcouncil.console"
+
+_LOG_FORMAT = "%(asctime)s %(levelname)-7s [%(name)s] %(message)s"
+_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+# Default file location (relative to a project root) for the durable run log.
+LOG_RELATIVE_PATH = Path(".devcouncil") / "logs" / "devcouncil.log"
+
+
+def _level_from_verbosity(verbosity: int, quiet: bool) -> int:
+    """Map ``-v`` count / ``-q`` flag to a console log level.
+
+    quiet -> ERROR; default(0) -> WARNING; -v -> INFO; -vv (or more) -> DEBUG.
+    """
+    if quiet:
+        return logging.ERROR
+    if verbosity <= 0:
+        return logging.WARNING
+    if verbosity == 1:
+        return logging.INFO
+    return logging.DEBUG
+
+
+def _resolve_console_level(verbosity: int, quiet: bool, log_level: Optional[str]) -> int:
+    """Console level precedence: explicit arg > env var > verbosity flags."""
+    explicit = log_level or os.environ.get("DEVCOUNCIL_LOG_LEVEL")
+    if explicit:
+        resolved = logging.getLevelName(explicit.strip().upper())
+        if isinstance(resolved, int):
+            return resolved
+    return _level_from_verbosity(verbosity, quiet)
+
+
+def _find_tagged_handler(logger: logging.Logger, tag: str) -> Optional[logging.Handler]:
+    for handler in logger.handlers:
+        if getattr(handler, "_devcouncil_tag", None) == tag:
+            return handler
+    return None
+
+
+def configure_logging(
+    project_root: Optional[Path] = None,
+    *,
+    verbosity: int = 0,
+    quiet: bool = False,
+    log_level: Optional[str] = None,
+) -> Optional[Path]:
+    """Install DevCouncil's file + console log handlers on the root logger.
+
+    Safe to call repeatedly. The file handler (DEBUG, rotating) is created once;
+    subsequent calls only update the console handler's level so a later command
+    invocation can raise/lower verbosity. Returns the resolved log file path, or
+    ``None`` if the file sink could not be created (console logging still works).
+    """
+    root = logging.getLogger()
+    # The root must pass DEBUG records through to handlers; each handler then
+    # applies its own threshold (file=DEBUG, console=user-selected).
+    root.setLevel(logging.DEBUG)
+
+    formatter = logging.Formatter(_LOG_FORMAT, datefmt=_DATE_FORMAT)
+    console_level = _resolve_console_level(verbosity, quiet, log_level)
+
+    # --- Console handler (stderr) -------------------------------------------
+    console = _find_tagged_handler(root, _CONSOLE_HANDLER_TAG)
+    if console is None:
+        console = logging.StreamHandler()  # defaults to stderr, keeps stdout clean
+        console._devcouncil_tag = _CONSOLE_HANDLER_TAG  # type: ignore[attr-defined]
+        console.setFormatter(formatter)
+        root.addHandler(console)
+    console.setLevel(console_level)
+
+    # --- Rotating file handler (always DEBUG) -------------------------------
+    log_path: Optional[Path] = None
+    if _find_tagged_handler(root, _FILE_HANDLER_TAG) is None:
+        base = Path(project_root) if project_root is not None else Path.cwd()
+        log_path = base / LOG_RELATIVE_PATH
+        try:
+            log_path.parent.mkdir(parents=True, exist_ok=True)
+            file_handler = RotatingFileHandler(
+                log_path,
+                maxBytes=5 * 1024 * 1024,  # 5 MB per file
+                backupCount=5,             # keep ~25 MB of history
+                encoding="utf-8",
+            )
+            file_handler._devcouncil_tag = _FILE_HANDLER_TAG  # type: ignore[attr-defined]
+            file_handler.setLevel(logging.DEBUG)
+            file_handler.setFormatter(formatter)
+            root.addHandler(file_handler)
+        except OSError:
+            # Read-only FS or unwritable path: degrade to console-only rather
+            # than crashing the command the user actually asked for.
+            log_path = None
+    else:
+        base = Path(project_root) if project_root is not None else Path.cwd()
+        log_path = base / LOG_RELATIVE_PATH
+
+    # Quieten chatty third-party loggers on the console; the file still gets them.
+    for noisy in ("httpx", "httpcore", "urllib3", "asyncio"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+
+    _install_excepthook()
+
+    logging.getLogger(__name__).debug(
+        "Logging configured (console=%s, file=%s)",
+        logging.getLevelName(console_level),
+        log_path,
+    )
+    return log_path
+
+
+def _install_excepthook() -> None:
+    """Ensure an uncaught exception is written to the log (with traceback) before exit.
+
+    A crash otherwise only prints a traceback to the terminal — gone once the scrollback
+    is. Routing it through logging means the full stack also lands in the durable DEBUG
+    file (and any active per-run log), which is exactly what you need to diagnose the
+    recurring failures. ``KeyboardInterrupt`` is left to the default handler so Ctrl-C
+    stays clean. Installed once; idempotent across repeat ``configure_logging`` calls.
+    """
+    import sys
+
+    if getattr(sys.excepthook, "_devcouncil_hook", False):
+        return
+    previous = sys.excepthook
+
+    def _hook(exc_type, exc_value, exc_tb):
+        if not issubclass(exc_type, KeyboardInterrupt):
+            logging.getLogger("devcouncil.crash").critical(
+                "Uncaught exception", exc_info=(exc_type, exc_value, exc_tb)
+            )
+        previous(exc_type, exc_value, exc_tb)
+
+    _hook._devcouncil_hook = True  # type: ignore[attr-defined]
+    sys.excepthook = _hook
+
+
+def set_log_dir(project_root: Path) -> Optional[Path]:
+    """Re-point the shared DEBUG file handler at ``project_root/.devcouncil/logs``.
+
+    The CLI callback configures logging before any command knows its ``--project-root``,
+    so the file handler initially lands under the current working directory. When a
+    command operates on a *different* root (``dev go --project-root /other/repo``), its
+    log should live with that project, not in cwd. Each command calls this once it has
+    resolved its root; if the handler already points there (the common ``.`` case) this
+    is a cheap no-op. Returns the (re)resolved log path, or ``None`` if it could not be
+    created (logging then stays on the previous handler / console).
+    """
+    target = Path(project_root) / LOG_RELATIVE_PATH
+    root = logging.getLogger()
+    existing = _find_tagged_handler(root, _FILE_HANDLER_TAG)
+    if existing is not None:
+        current = getattr(existing, "baseFilename", None)
+        if current and Path(current) == target.resolve():
+            return target  # already logging to this project's file — nothing to do
+
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        new_handler = RotatingFileHandler(
+            target, maxBytes=5 * 1024 * 1024, backupCount=5, encoding="utf-8"
+        )
+        new_handler._devcouncil_tag = _FILE_HANDLER_TAG  # type: ignore[attr-defined]
+        new_handler.setLevel(logging.DEBUG)
+        new_handler.setFormatter(logging.Formatter(_LOG_FORMAT, datefmt=_DATE_FORMAT))
+    except OSError:
+        return None
+
+    if existing is not None:
+        root.removeHandler(existing)
+        existing.close()
+    root.addHandler(new_handler)
+    logging.getLogger(__name__).debug("Log file re-pointed to %s", target)
+    return target
+
+
+@contextmanager
+def run_log(log_file: Path) -> Iterator[Optional[Path]]:
+    """Capture everything logged during a single invocation into its own DEBUG file.
+
+    The shared rotating ``devcouncil.log`` interleaves every command and rotates by
+    size, so isolating one run's complete trail there means grepping across rotations
+    and unrelated activity. This attaches a second, run-scoped DEBUG file handler for
+    the duration of the ``with`` block (e.g. ``.devcouncil/runs/<id>/run.log``) and
+    detaches it on exit — giving a clean, self-contained log for exactly that run on
+    top of the always-on shared log.
+
+    Best-effort: if the file can't be opened (read-only FS, bad path) the block still
+    runs with only the shared log. Yields the resolved path, or ``None`` on failure.
+    """
+    root = logging.getLogger()
+    handler: Optional[logging.Handler] = None
+    try:
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        handler = logging.FileHandler(log_file, encoding="utf-8")
+        handler._devcouncil_tag = "devcouncil.run"  # type: ignore[attr-defined]
+        handler.setLevel(logging.DEBUG)
+        handler.setFormatter(logging.Formatter(_LOG_FORMAT, datefmt=_DATE_FORMAT))
+        root.addHandler(handler)
+    except OSError:
+        if handler is not None:
+            root.removeHandler(handler)
+        handler = None
+        log_file = None  # type: ignore[assignment]
+
+    try:
+        yield log_file
+    finally:
+        if handler is not None:
+            handler.flush()
+            handler.close()
+            root.removeHandler(handler)

package/src/devcouncil/telemetry/stages.py

@@ -0,0 +1,141 @@
+"""Stage and step instrumentation for DevCouncil pipelines.
+
+A DevCouncil run moves through coarse *stages* (plan, execute, verify, repair,
+reconcile, report) each made of finer *steps*. When a run misbehaves, the first
+question is always "how far did it get, and what was the last thing it tried?".
+This module gives one consistent way to answer that:
+
+* :func:`log_stage` — a context manager that logs ``▶ <stage>`` on entry and
+  ``✔ <stage> (1.23s)`` / ``✖ <stage> failed (1.23s): ...`` on exit, with wall
+  time. It also mirrors the boundary to the structured JSONL trace
+  (:class:`~devcouncil.telemetry.traces.TraceLogger`) when a ``project_root`` is
+  given, so the human log and the machine trace stay in lock-step.
+* :func:`log_step` — a one-liner for a single step inside a stage.
+
+Both are best-effort: instrumentation must never be the reason a run fails, so
+trace-write errors are swallowed (the Python log line still goes out).
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Iterator, Optional
+
+logger = logging.getLogger("devcouncil.stage")
+
+
+def _safe_trace(
+    project_root: Optional[Path],
+    event_type: str,
+    details: dict[str, Any],
+    *,
+    run_id: Optional[str],
+    task_id: Optional[str],
+    summary: str,
+) -> None:
+    """Mirror a stage/step boundary to the JSONL trace, swallowing any error."""
+    if project_root is None:
+        return
+    try:
+        from devcouncil.telemetry.traces import TraceLogger
+
+        TraceLogger(Path(project_root)).log_event(
+            event_type, details, run_id=run_id, task_id=task_id, summary=summary
+        )
+    except Exception:  # pragma: no cover - tracing is strictly best-effort
+        logger.debug("Failed to mirror %s to trace", event_type, exc_info=True)
+
+
+def _context_suffix(context: dict[str, Any]) -> str:
+    if not context:
+        return ""
+    return " " + " ".join(f"{k}={v}" for k, v in context.items())
+
+
+@contextmanager
+def log_stage(
+    name: str,
+    *,
+    project_root: Optional[Path] = None,
+    run_id: Optional[str] = None,
+    task_id: Optional[str] = None,
+    **context: Any,
+) -> Iterator[None]:
+    """Log entry/exit (with timing) around a coarse pipeline stage.
+
+    Usage::
+
+        with log_stage("plan", project_root=root, run_id=run_id, goal=goal):
+            ...
+
+    Logs at INFO on success, ERROR on exception, and always reports elapsed time.
+    Re-raises whatever the body raised so control flow is unchanged.
+    """
+    suffix = _context_suffix(context)
+    logger.info("▶ %s%s", name, suffix)
+    _safe_trace(
+        project_root,
+        "stage_started",
+        {"stage": name, **context},
+        run_id=run_id,
+        task_id=task_id,
+        summary=f"Stage started: {name}",
+    )
+    start = time.monotonic()
+    try:
+        yield
+    except BaseException as exc:
+        elapsed = time.monotonic() - start
+        logger.error("✖ %s failed (%.2fs): %s", name, elapsed, exc)
+        _safe_trace(
+            project_root,
+            "stage_failed",
+            {"stage": name, "error": str(exc), "elapsed_s": round(elapsed, 3), **context},
+            run_id=run_id,
+            task_id=task_id,
+            summary=f"Stage failed: {name}",
+        )
+        raise
+    else:
+        elapsed = time.monotonic() - start
+        logger.info("✔ %s (%.2fs)", name, elapsed)
+        _safe_trace(
+            project_root,
+            "stage_completed",
+            {"stage": name, "elapsed_s": round(elapsed, 3), **context},
+            run_id=run_id,
+            task_id=task_id,
+            summary=f"Stage completed: {name}",
+        )
+
+
+def log_step(
+    message: str,
+    *,
+    project_root: Optional[Path] = None,
+    run_id: Optional[str] = None,
+    task_id: Optional[str] = None,
+    level: int = logging.INFO,
+    trace: bool = False,
+    **context: Any,
+) -> None:
+    """Log a single step within a stage.
+
+    By default this only writes the Python log (cheap, captured in full by the
+    file handler). Set ``trace=True`` for milestone steps worth recording in the
+    structured JSONL trace as well.
+    """
+    suffix = _context_suffix(context)
+    logger.log(level, "• %s%s", message, suffix)
+    if trace:
+        _safe_trace(
+            project_root,
+            "step",
+            {"message": message, **context},
+            run_id=run_id,
+            task_id=task_id,
+            summary=message,
+        )

package/src/devcouncil/telemetry/tracker.py

@@ -7,7 +7,11 @@ from devcouncil.telemetry.pricing import pricing_for_model
 class TelemetryTracker:
     def __init__(self, project_root: Path):
         self.log_file = project_root / ".devcouncil" / "logs" / "telemetry.json"
-        self.stats = self._load()
+        # log_usage() reloads the ledger immediately before saving (for concurrent-write
+        # safety), so any value read here would always be overwritten before use. Start
+        # from the same default shape _load() returns for a missing file instead of
+        # doing a dead disk read at construction.
+        self.stats: Dict[str, Any] = {"total_cost": 0.0, "total_prompt_tokens": 0, "total_completion_tokens": 0, "models": {}}
 
     def _load(self) -> Dict[str, Any]:
         if self.log_file.exists():
@@ -24,6 +28,13 @@ class TelemetryTracker:
             json.dump(self.stats, f, indent=2)
 
     def log_usage(self, model: str, usage: Dict[str, int], *, local: bool = False):
+        # Re-read the ledger immediately before mutating so the whole load->mutate->save
+        # runs as one synchronous (await-free) step. The router constructs a fresh tracker
+        # per call and only calls log_usage *after* the LLM await, so snapshotting the
+        # baseline at construction would let concurrent calls (e.g. plan.py's gather, or a
+        # parallelized SkillOpt _evaluate) each load the same baseline and clobber each
+        # other's entries on save. Reloading here makes the last writer additive, not lossy.
+        self.stats = self._load()
         prompt_tokens = usage.get("prompt_tokens", 0)
         completion_tokens = usage.get("completion_tokens", 0)
 

package/src/devcouncil/ui/dashboard.py

@@ -6,14 +6,18 @@ import time
 from importlib import resources
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
+from typing import TYPE_CHECKING
 from urllib.parse import urlparse
 
 from devcouncil.app.project_status import compute_phase
 from devcouncil.integrations.actions import apply_integration_target
 from devcouncil.integrations.check import build_integration_check_report, integration_status_summary
 from devcouncil.storage.db import get_db
-from devcouncil.storage.repositories import ArtifactGraphRepository, StateRepository, TaskRepository
-from devcouncil.telemetry.traces import read_trace_events
+from devcouncil.storage.repositories import ArtifactGraphRepository, StateRepository
+from devcouncil.telemetry.traces import TraceEvent, read_trace_events_since
+
+if TYPE_CHECKING:
+    from devcouncil.artifacts.graph import ArtifactGraph
 
 LOGO_ASSET = "devcouncil_logo_premium.png"
 LEGACY_LOGO_ASSET = "devcouncil-logo.svg"
@@ -41,9 +45,25 @@ def _load_run_manifest(manifest_path: Path) -> dict | None:
     return dict(manifest)
 
 
+# The glob+stat over every run manifest is wasteful on each 2-second poll; a
+# short TTL cache of the assembled result keeps the loop cheap.
+_RECENT_RUNS_TTL_SECONDS = 2.0
+_RECENT_RUNS_CACHE: dict[str, tuple[float, int, list[dict]]] = {}
+
+
+def _invalidate_recent_runs(project_root: Path) -> None:
+    _RECENT_RUNS_CACHE.pop(str(project_root), None)
+
+
 def recent_run_artifacts(project_root: Path, *, limit: int = 10) -> list[dict]:
+    key = str(project_root)
+    now = time.monotonic()
+    cached = _RECENT_RUNS_CACHE.get(key)
+    if cached is not None and cached[1] == limit and now - cached[0] < _RECENT_RUNS_TTL_SECONDS:
+        return cached[2]
     runs_dir = project_root / ".devcouncil" / "runs"
     if not runs_dir.exists():
+        _RECENT_RUNS_CACHE[key] = (now, limit, [])
         return []
     manifests: list[dict] = []
     for manifest_path in sorted(
@@ -58,6 +78,7 @@ def recent_run_artifacts(project_root: Path, *, limit: int = 10) -> list[dict]:
         manifests.append(manifest)
         if len(manifests) >= limit:
             break
+    _RECENT_RUNS_CACHE[key] = (now, limit, manifests)
     return manifests
 
 
@@ -82,6 +103,49 @@ def _invalidate_integration_summary(project_root: Path) -> None:
     _INTEGRATION_SUMMARY_CACHE.pop(str(project_root), None)
 
 
+# load_graph() runs six full-table scans, but the dashboard only needs the
+# coverage summary and task list. Cache the materialized graph for a short TTL so
+# the 2-second poll loop reuses it instead of rescanning every table each time.
+_ARTIFACT_GRAPH_TTL_SECONDS = 2.0
+_ARTIFACT_GRAPH_CACHE: dict[str, tuple[float, "ArtifactGraph"]] = {}
+
+
+def _artifact_graph_cached(project_root: Path, session) -> "ArtifactGraph":
+    key = str(project_root)
+    now = time.monotonic()
+    cached = _ARTIFACT_GRAPH_CACHE.get(key)
+    if cached is not None and now - cached[0] < _ARTIFACT_GRAPH_TTL_SECONDS:
+        return cached[1]
+    graph = ArtifactGraphRepository(session).load_graph()
+    _ARTIFACT_GRAPH_CACHE[key] = (now, graph)
+    return graph
+
+
+def _invalidate_artifact_graph(project_root: Path) -> None:
+    _ARTIFACT_GRAPH_CACHE.pop(str(project_root), None)
+
+
+# Re-reading and re-parsing the whole trace file on each poll is O(all events).
+# Keep a per-root byte cursor plus the last 50 parsed events; each refresh reads
+# only the bytes appended since the cursor. Semantics match the previous
+# ``list(read_trace_events(...))[-50:]`` (last 50 events, in order).
+_TRACE_EVENTS_LIMIT = 50
+_TRACE_EVENTS_CACHE: dict[str, tuple[int, list[TraceEvent]]] = {}
+
+
+def _recent_trace_events_cached(project_root: Path) -> list[TraceEvent]:
+    key = str(project_root)
+    cursor, buffer = _TRACE_EVENTS_CACHE.get(key, (0, []))
+    new_events, next_cursor = read_trace_events_since(project_root, cursor)
+    if next_cursor < cursor:
+        # File was truncated/rotated: discard the stale buffer and start over.
+        buffer = new_events[-_TRACE_EVENTS_LIMIT:]
+    elif new_events:
+        buffer = (buffer + new_events)[-_TRACE_EVENTS_LIMIT:]
+    _TRACE_EVENTS_CACHE[key] = (next_cursor, buffer)
+    return buffer
+
+
 def logo_svg() -> str:
     return resources.files("devcouncil.assets").joinpath(LEGACY_LOGO_ASSET).read_text(encoding="utf-8")
 
@@ -103,16 +167,16 @@ def dashboard_payload(project_root: Path) -> dict:
             "recent_runs": recent_run_artifacts(project_root),
         }
     with db.get_session() as session:
-        graph = ArtifactGraphRepository(session).load_graph()
+        graph = _artifact_graph_cached(project_root, session)
         state = StateRepository(session).get_state()
         phase = compute_phase(graph, state.current_phase if state else None)
-        tasks = [task.model_dump() for task in TaskRepository(session).get_all()]
+        tasks = [task.model_dump() for task in graph.tasks.values()]
         return {
             "initialized": True,
             "phase": phase,
             "coverage": graph.coverage_summary(),
             "tasks": tasks,
-            "events": [event.model_dump(by_alias=True) for event in list(read_trace_events(project_root))[-50:]],
+            "events": [event.model_dump(by_alias=True) for event in _recent_trace_events_cached(project_root)],
             "integrations": _integration_summary_cached(project_root),
             "recent_runs": recent_run_artifacts(project_root),
         }