codevigil 0.3.0__tar.gz → 0.4.0__tar.gz

{codevigil-0.3.0 → codevigil-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codevigil
-Version: 0.3.0
+Version: 0.4.0
 Summary: Local, privacy-preserving observability for Claude Code sessions.
 Project-URL: Homepage, https://github.com/Mathews-Tom/codevigil
 Project-URL: Issues, https://github.com/Mathews-Tom/codevigil/issues
@@ -231,7 +231,7 @@ Local, privacy-preserving observability for Claude Code sessions.
 codevigil tails `~/.claude/projects/**/*.jsonl` on disk, computes signal metrics about reasoning and tool-use patterns, and surfaces them in a rich terminal dashboard or as JSON / markdown reports. **Zero network egress, no data ever leaves your machine.**
 
 [![Status](https://img.shields.io/badge/status-beta-blue.svg)](https://github.com/Mathews-Tom/codevigil)
-[![Version](https://img.shields.io/badge/version-0.3.0-informational.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.4.0-informational.svg)](CHANGELOG.md)
 [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
 [![CI](https://github.com/Mathews-Tom/codevigil/actions/workflows/ci.yml/badge.svg)](https://github.com/Mathews-Tom/codevigil/actions/workflows/ci.yml)
@@ -261,7 +261,7 @@ codevigil ingest        # one-shot cold-ingest into persistent memory (first run
 codevigil watch         # project roll-up dashboard, resumes every file from its cached cursor
 ```
 
-`codevigil ingest` walks every JSONL under `watch.root`, parses it end-to-end, and writes a durable record (session id, file id, cursor offset, collector state, metric summary) to the local SQLite store under `~/.local/state/codevigil/`. You run it once after install. Subsequent `codevigil watch` ticks seek past the saved cursor on every file, so the hot path only processes newly-appended events. If the store is absent on startup, `watch` will bootstrap it for you.
+`codevigil ingest` walks every JSONL under `watch.roots`, parses them end-to-end, and writes a durable record (root-aware session key, raw session id, file id, cursor offset, collector state, metric summary) to the local SQLite store under `~/.local/state/codevigil/`. You run it once after install. Subsequent `codevigil watch` ticks seek past the saved cursor on every file, so the hot path only processes newly-appended events. If the store is absent on startup, `watch` will bootstrap it for you.
 
 `codevigil watch` then prints a live **project-row** dashboard: one row per Claude Code project, with the fleet-worst severity, the active session count, and the aggregate metric summary. The top line shows fleet totals (session count, CRIT/WARN/OK tallies, project count, last-updated wall-clock tick). Every session's rolling-window collector state is restored from the store so restart does not erase your percentile baselines.
 
@@ -317,12 +317,13 @@ Full flag reference for every subcommand: [docs/cli.md](docs/cli.md).
 
 ## Configuration
 
-codevigil resolves its configuration from a layered precedence chain: built-in defaults → `~/.config/codevigil/config.toml` → `CODEVIGIL_*` environment variables → CLI flags. Run `codevigil config check` to see every resolved key with its source.
+codevigil resolves its configuration from a layered precedence chain: built-in defaults → `~/.config/codevigil/config.toml` → `CODEVIGIL_*` environment variables → CLI flags. `watch.roots` is the canonical multi-root setting; `watch.root` and `CODEVIGIL_WATCH_ROOT` remain supported as deprecated single-root aliases. Run `codevigil config check` to see every resolved key with its source and any deprecation notices.
 
 A minimal `~/.config/codevigil/config.toml`:
 
 ```toml
 [watch]
+roots = ["~/.claude/projects"]
 poll_interval = 1.0
 
 [collectors.read_edit_ratio]
@@ -349,7 +350,7 @@ Five user-facing collectors plus an always-on integrity gate:
 
 ## Persistent memory
 
-0.3.0 adds a local SQLite-backed processed-session store under `~/.local/state/codevigil/processed/`. Every finalised session writes a durable row — session id, file id, cursor byte offset, collector state snapshot, and derived metric summary — and the watcher seeds each polled file from the cached cursor on startup instead of re-parsing JSONL from byte 0. Rolling-window collector state (the `read_edit_ratio` 50-event deque, the `reasoning_loop` burst counter) is restored verbatim across restarts. Run `codevigil ingest` once after install; after that, `codevigil watch` only processes newly-appended events on the hot path. Disable the cursor cache for reproducible cold-start benchmarks with `watch.cursor_cache_enabled = false`. Schema, migration policy, and the invariants the store upholds live in [docs/design.md](docs/design.md).
+0.4.0 adds first-class multi-root support on top of the local SQLite-backed processed-session store under `~/.local/state/codevigil/processed/`. Every finalised session now writes a root-aware identity (`session_key`, raw `session_id`, cursor byte offset, collector state snapshot, and derived metric summary), and the watcher seeds each polled file from the cached cursor on startup instead of re-parsing JSONL from byte 0. Rolling-window collector state (the `read_edit_ratio` 50-event deque, the `reasoning_loop` burst counter) is restored verbatim across restarts, even when different roots contain the same `session_id`. Run `codevigil ingest` once after install; after that, `codevigil watch` only processes newly-appended events on the hot path. Disable the cursor cache for reproducible cold-start benchmarks with `watch.cursor_cache_enabled = false`. Schema, migration policy, and the invariants the store upholds live in [docs/design.md](docs/design.md).
 
 ## Cohort trend reports
 
@@ -366,7 +367,7 @@ Both new default collectors (`thinking`, `prompts`) surface in cohort reports as
 
 ## Task classifier `[experimental]`
 
-0.2.0 adds a turn-level task classifier that labels each Claude Code turn as `exploration`, `mutation_heavy`, `debug_loop`, `planning`, or `mixed` using a two-stage cascade (tool-presence heuristic → keyword regex on the user message, stdlib `re` only, zero network, zero new dependencies). Session-level labels aggregate turn labels by majority vote. Labels surface in four places:
+The experimental task classifier labels each Claude Code turn as `exploration`, `mutation_heavy`, `debug_loop`, `planning`, or `mixed` using a two-stage cascade (tool-presence heuristic → keyword regex on the user message, stdlib `re` only, zero network, zero new dependencies). Session-level labels aggregate turn labels by majority vote. Labels surface in four places:
 
 - **`history list`** — new `task_type` column and `--task-type <label>` filter
 - **`history heatmap --axis task_type`** — cross-tab metrics against task labels

{codevigil-0.3.0 → codevigil-0.4.0}/README.md

@@ -5,7 +5,7 @@ Local, privacy-preserving observability for Claude Code sessions.
 codevigil tails `~/.claude/projects/**/*.jsonl` on disk, computes signal metrics about reasoning and tool-use patterns, and surfaces them in a rich terminal dashboard or as JSON / markdown reports. **Zero network egress, no data ever leaves your machine.**
 
 [![Status](https://img.shields.io/badge/status-beta-blue.svg)](https://github.com/Mathews-Tom/codevigil)
-[![Version](https://img.shields.io/badge/version-0.3.0-informational.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.4.0-informational.svg)](CHANGELOG.md)
 [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
 [![CI](https://github.com/Mathews-Tom/codevigil/actions/workflows/ci.yml/badge.svg)](https://github.com/Mathews-Tom/codevigil/actions/workflows/ci.yml)
@@ -35,7 +35,7 @@ codevigil ingest        # one-shot cold-ingest into persistent memory (first run
 codevigil watch         # project roll-up dashboard, resumes every file from its cached cursor
 ```
 
-`codevigil ingest` walks every JSONL under `watch.root`, parses it end-to-end, and writes a durable record (session id, file id, cursor offset, collector state, metric summary) to the local SQLite store under `~/.local/state/codevigil/`. You run it once after install. Subsequent `codevigil watch` ticks seek past the saved cursor on every file, so the hot path only processes newly-appended events. If the store is absent on startup, `watch` will bootstrap it for you.
+`codevigil ingest` walks every JSONL under `watch.roots`, parses them end-to-end, and writes a durable record (root-aware session key, raw session id, file id, cursor offset, collector state, metric summary) to the local SQLite store under `~/.local/state/codevigil/`. You run it once after install. Subsequent `codevigil watch` ticks seek past the saved cursor on every file, so the hot path only processes newly-appended events. If the store is absent on startup, `watch` will bootstrap it for you.
 
 `codevigil watch` then prints a live **project-row** dashboard: one row per Claude Code project, with the fleet-worst severity, the active session count, and the aggregate metric summary. The top line shows fleet totals (session count, CRIT/WARN/OK tallies, project count, last-updated wall-clock tick). Every session's rolling-window collector state is restored from the store so restart does not erase your percentile baselines.
 
@@ -91,12 +91,13 @@ Full flag reference for every subcommand: [docs/cli.md](docs/cli.md).
 
 ## Configuration
 
-codevigil resolves its configuration from a layered precedence chain: built-in defaults → `~/.config/codevigil/config.toml` → `CODEVIGIL_*` environment variables → CLI flags. Run `codevigil config check` to see every resolved key with its source.
+codevigil resolves its configuration from a layered precedence chain: built-in defaults → `~/.config/codevigil/config.toml` → `CODEVIGIL_*` environment variables → CLI flags. `watch.roots` is the canonical multi-root setting; `watch.root` and `CODEVIGIL_WATCH_ROOT` remain supported as deprecated single-root aliases. Run `codevigil config check` to see every resolved key with its source and any deprecation notices.
 
 A minimal `~/.config/codevigil/config.toml`:
 
 ```toml
 [watch]
+roots = ["~/.claude/projects"]
 poll_interval = 1.0
 
 [collectors.read_edit_ratio]
@@ -123,7 +124,7 @@ Five user-facing collectors plus an always-on integrity gate:
 
 ## Persistent memory
 
-0.3.0 adds a local SQLite-backed processed-session store under `~/.local/state/codevigil/processed/`. Every finalised session writes a durable row — session id, file id, cursor byte offset, collector state snapshot, and derived metric summary — and the watcher seeds each polled file from the cached cursor on startup instead of re-parsing JSONL from byte 0. Rolling-window collector state (the `read_edit_ratio` 50-event deque, the `reasoning_loop` burst counter) is restored verbatim across restarts. Run `codevigil ingest` once after install; after that, `codevigil watch` only processes newly-appended events on the hot path. Disable the cursor cache for reproducible cold-start benchmarks with `watch.cursor_cache_enabled = false`. Schema, migration policy, and the invariants the store upholds live in [docs/design.md](docs/design.md).
+0.4.0 adds first-class multi-root support on top of the local SQLite-backed processed-session store under `~/.local/state/codevigil/processed/`. Every finalised session now writes a root-aware identity (`session_key`, raw `session_id`, cursor byte offset, collector state snapshot, and derived metric summary), and the watcher seeds each polled file from the cached cursor on startup instead of re-parsing JSONL from byte 0. Rolling-window collector state (the `read_edit_ratio` 50-event deque, the `reasoning_loop` burst counter) is restored verbatim across restarts, even when different roots contain the same `session_id`. Run `codevigil ingest` once after install; after that, `codevigil watch` only processes newly-appended events on the hot path. Disable the cursor cache for reproducible cold-start benchmarks with `watch.cursor_cache_enabled = false`. Schema, migration policy, and the invariants the store upholds live in [docs/design.md](docs/design.md).
 
 ## Cohort trend reports
 
@@ -140,7 +141,7 @@ Both new default collectors (`thinking`, `prompts`) surface in cohort reports as
 
 ## Task classifier `[experimental]`
 
-0.2.0 adds a turn-level task classifier that labels each Claude Code turn as `exploration`, `mutation_heavy`, `debug_loop`, `planning`, or `mixed` using a two-stage cascade (tool-presence heuristic → keyword regex on the user message, stdlib `re` only, zero network, zero new dependencies). Session-level labels aggregate turn labels by majority vote. Labels surface in four places:
+The experimental task classifier labels each Claude Code turn as `exploration`, `mutation_heavy`, `debug_loop`, `planning`, or `mixed` using a two-stage cascade (tool-presence heuristic → keyword regex on the user message, stdlib `re` only, zero network, zero new dependencies). Session-level labels aggregate turn labels by majority vote. Labels surface in four places:
 
 - **`history list`** — new `task_type` column and `--task-type <label>` filter
 - **`history heatmap --axis task_type`** — cross-tab metrics against task labels

{codevigil-0.3.0 → codevigil-0.4.0}/codevigil/__init__.py

@@ -14,6 +14,6 @@ from codevigil.privacy import install as _install_privacy_hook
 
 _install_privacy_hook()
 
-__version__: str = "0.3.0"
+__version__: str = "0.4.0"
 
 __all__ = ["PrivacyViolationError", "__version__"]

{codevigil-0.3.0 → codevigil-0.4.0}/codevigil/aggregator.py

@@ -93,6 +93,7 @@ from codevigil.types import (
     SessionState,
     Severity,
 )
+from codevigil.watch_roots import LEGACY_ROOT_ID, legacy_session_key
 from codevigil.watcher import Source, SourceEvent, SourceEventKind
 
 _PARSE_HEALTH_NAME: str = "parse_health"
@@ -123,6 +124,9 @@ class _SessionContext:
     """
 
     session_id: str
+    session_key: str
+    root_id: str
+    root_label: str
     file_path: Path
     project_hash: str
     parser: SessionParser
@@ -158,6 +162,69 @@ class _SessionContext:
 _ClockFn = Callable[[], float]
 
 
+class _SessionView:
+    """Compatibility view over the internal session-keyed context map."""
+
+    def __init__(self, sessions: dict[str, _SessionContext]) -> None:
+        self._sessions = sessions
+
+    def _resolve_key(self, key: str) -> str | None:
+        if key in self._sessions:
+            return key
+        matches = [
+            session_key for session_key, ctx in self._sessions.items() if ctx.session_id == key
+        ]
+        if len(matches) == 1:
+            return matches[0]
+        return None
+
+    def _get_resolved(self, key: str) -> _SessionContext | None:
+        resolved = self._resolve_key(key)
+        if resolved is None:
+            return None
+        return self._sessions[resolved]
+
+    def __getitem__(self, key: str) -> _SessionContext:
+        ctx = self._get_resolved(key)
+        if ctx is None:
+            raise KeyError(key)
+        return ctx
+
+    def get(self, key: str, default: Any = None) -> _SessionContext | Any:
+        ctx = self._get_resolved(key)
+        if ctx is None:
+            return default
+        return ctx
+
+    def pop(self, key: str, default: Any = None) -> _SessionContext | Any:
+        resolved = self._resolve_key(key)
+        if resolved is None:
+            return default
+        return self._sessions.pop(resolved, default)
+
+    def __contains__(self, key: object) -> bool:
+        return isinstance(key, str) and self._resolve_key(key) is not None
+
+    def values(self) -> Any:
+        return self._sessions.values()
+
+    def items(self) -> Any:
+        return self._sessions.items()
+
+    def __iter__(self) -> Any:
+        return iter(self._sessions)
+
+    def __len__(self) -> int:
+        return len(self._sessions)
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, dict):
+            return self._sessions == other
+        if isinstance(other, _SessionView):
+            return self._sessions == other._sessions
+        return NotImplemented
+
+
 class SessionAggregator:
     """Drive a :class:`Source` through parser, collectors, and lifecycle.
 
@@ -192,7 +259,7 @@ class SessionAggregator:
         self._sessions: dict[str, _SessionContext] = {}
         self._bootstrap: BootstrapManager | None = bootstrap
         # Phase C5: collector-state restore provider. Given a session
-        # ID, returns a ``{collector_name: state_dict}`` mapping from
+        # key, returns a ``{collector_name: state_dict}`` mapping from
         # the processed-session store, or ``None`` when no persisted
         # state exists for that session. Called once from
         # ``_ensure_session`` immediately after fresh collectors are
@@ -233,10 +300,10 @@ class SessionAggregator:
     # --------------------------------------------------------------- properties
 
     @property
-    def sessions(self) -> dict[str, _SessionContext]:
+    def sessions(self) -> _SessionView:
         """Read-only-ish accessor used by tests; do not mutate externally."""
 
-        return self._sessions
+        return _SessionView(self._sessions)
 
     @property
     def eviction_churn(self) -> int:
@@ -369,17 +436,18 @@ class SessionAggregator:
             # the aggregator just keeps consuming.
             return
         if kind is SourceEventKind.DELETE:
-            self._evict_session(source_event.session_id)
+            self._evict_session(self._event_session_key(source_event))
             return
 
     def _ensure_session(self, source_event: SourceEvent) -> _SessionContext:
         sid = source_event.session_id
-        existing = self._sessions.get(sid)
+        session_key = self._event_session_key(source_event)
+        existing = self._sessions.get(session_key)
         if existing is not None:
             return existing
         parser = SessionParser(session_id=sid)
         collectors = self._instantiate_collectors(parser)
-        self._maybe_restore_collector_state(sid, collectors)
+        self._maybe_restore_collector_state(session_key, collectors)
         now_clock = self._clock()
         now_wall = source_event.timestamp
         project_hash = self._extract_project_hash(source_event.path, session_id=sid)
@@ -393,6 +461,9 @@ class SessionAggregator:
         last_monotonic = now_clock - age_seconds
         ctx = _SessionContext(
             session_id=sid,
+            session_key=session_key,
+            root_id=source_event.root_id or LEGACY_ROOT_ID,
+            root_label=source_event.root_label or str(source_event.path.parent),
             file_path=source_event.path,
             project_hash=project_hash,
             parser=parser,
@@ -401,19 +472,19 @@ class SessionAggregator:
             last_event_time=now_wall,
             last_monotonic=last_monotonic,
         )
-        self._sessions[sid] = ctx
+        self._sessions[session_key] = ctx
         return ctx
 
     def _maybe_restore_collector_state(
         self,
-        session_id: str,
+        session_key: str,
         collectors: dict[str, Collector],
     ) -> None:
         """Hydrate collectors from persistent state when one is available.
 
         When the caller configured ``collector_state_provider`` (Phase
         C5 watch path), we consult the processed-session store keyed by
-        ``session_id``. A hit returns ``{collector_name: state_dict}``;
+        ``session_key``. A hit returns ``{collector_name: state_dict}``;
         each collector that implements ``restore_state`` then hydrates
         from its slice. Collectors that do not implement
         ``restore_state`` (or that lack a matching key in the stored
@@ -422,7 +493,7 @@ class SessionAggregator:
 
         if self._collector_state_provider is None:
             return
-        state = self._collector_state_provider(session_id)
+        state = self._collector_state_provider(session_key)
         if not state:
             return
         for name, collector in collectors.items():
@@ -459,6 +530,12 @@ class SessionAggregator:
                     continue
         return out
 
+    @staticmethod
+    def _event_session_key(source_event: SourceEvent) -> str:
+        if source_event.session_key:
+            return source_event.session_key
+        return legacy_session_key(source_event.session_id)
+
     def _extract_project_hash(self, path: Path, *, session_id: str) -> str:
         """Pull the project-hash directory from the canonical path layout.
 
@@ -731,7 +808,7 @@ class SessionAggregator:
             payload[collector_name] = snap
         if not payload:
             return
-        bootstrap.observe_session(ctx.session_id, payload)
+        bootstrap.observe_session(ctx.session_key, payload)
         if bootstrap.finalize_if_ready():
             record(
                 CodevigilError(
@@ -773,6 +850,9 @@ class SessionAggregator:
             state=ctx.state,
             snapshot_history=history,
             session_task_type=current_task_type,
+            session_key=ctx.session_key,
+            root_id=ctx.root_id,
+            root_label=ctx.root_label,
         )
 
     # ----------------------------------------------------------------- lifecycle
@@ -792,12 +872,12 @@ class SessionAggregator:
 
     def _evict_session(
         self,
-        session_id: str,
+        session_key: str,
         *,
         reason: str = "source_delete",
         silence_seconds: float | None = None,
     ) -> None:
-        ctx = self._sessions.pop(session_id, None)
+        ctx = self._sessions.pop(session_key, None)
         if ctx is None:
             return
         ctx.state = SessionState.EVICTED
@@ -806,7 +886,8 @@ class SessionAggregator:
         # watcher or a chatty editor that rolls files every few minutes
         # shows up as an elevated eviction rate in the INFO log.
         context: dict[str, Any] = {
-            "session_id": session_id,
+            "session_id": ctx.session_id,
+            "session_key": ctx.session_key,
             "reason": reason,
             "event_count": ctx.event_count,
             "remaining_sessions": len(self._sessions),
@@ -819,7 +900,8 @@ class SessionAggregator:
                 source=ErrorSource.AGGREGATOR,
                 code="aggregator.session_evicted",
                 message=(
-                    f"session {session_id!r} evicted ({reason}); {ctx.event_count} events processed"
+                    f"session {ctx.session_key!r} evicted ({reason}); "
+                    f"{ctx.event_count} events processed"
                 ),
                 context=context,
             )
@@ -859,6 +941,9 @@ class SessionAggregator:
         try:
             report = build_report(
                 session_id=ctx.session_id,
+                session_key=ctx.session_key,
+                root_id=ctx.root_id,
+                root_label=ctx.root_label,
                 project_hash=ctx.project_hash,
                 project_name=self._project_registry.resolve(ctx.project_hash),
                 model=None,  # Phase 5 wires model from session metadata