Activity-aware duration tracking and release versioning (v0.3.0)

Governor now distinguishes "terminal open" from "human working" by detecting
idle gaps between tool calls. Gaps exceeding a configurable threshold (default
30 min) are recorded and subtracted from session/mode durations. Resolves the
overnight-terminal false nudge problem (Design Thread #7).

Adds proper release infrastructure: _version.py as single source of truth,
EXPORT_SCHEMA_VERSION constant, CHANGELOG.md retro-filled from commit history,
annotated git tags for all releases.

Export schema: 0.2.0 -> 0.3.0 (adds active_duration_minutes, idle_gaps).
116 tests passing (26 new).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: m3me

CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to Vibe Harness are documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Export schema version is tracked independently — it describes the JSON export
+format, not the software release. Schema version is noted in each release when
+it changes.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-02-13
+
+Activity-aware duration tracking. The governor now distinguishes "terminal open"
+from "human working" by detecting idle gaps between tool calls.
+
+### Added
+- `IdleGap` dataclass for recording detected idle periods
+- `active_session_minutes()` and `active_mode_minutes()` on `VibeSession` — elapsed minus idle time
+- `total_idle_minutes()` for total detected idle time
+- `activity.idle_threshold_minutes` config setting (default: 30)
+- `away Xh detected` line in `vibe_check()` output when idle time exists
+- `active_duration_minutes` and `idle_gaps` fields in session export
+- `_version.py` as single source of truth for package version
+- `EXPORT_SCHEMA_VERSION` constant in `session.py`
+- `CHANGELOG.md` (this file), retro-filled from commit history
+- Git tags for all releases (`v0.1.0`, `v0.2.0`, `v0.3.0`)
+- 26 new tests (116 total)
+
+### Changed
+- Governor evaluates rules against active durations, not raw elapsed time
+- `vibe_check()` and status line display active durations
+- `time_in_mode_summary()` subtracts idle gaps per mode span
+- Export schema version: `0.2.0` → `0.3.0`
+
+### Fixed
+- Overnight/idle terminal no longer triggers false "step away" nudge
+
+## [0.2.0] - 2026-02-06
+
+Defeasible governance with full accountability trace.
+
+### Added
+- `GovernanceRule` and `RuleEvaluation` dataclasses
+- Five priority-ordered rules: cooldown suppression, session duration, mode duration, mode drift, interaction count
+- Full governance trace recorded on every evaluation — which rules fired, which were defeated, and by what
+- `evaluate_rules()` returns `(message, trace)` tuple
+- Governance trace included in session export
+- ESL-A v0.1 license
+- Slash commands: `/vibe`, `/vibe-mode`, `/vibe-history`
+
+### Changed
+- Governor architecture: from simple threshold checks to defeasible rule engine
+- Export schema version: `0.1.0` → `0.2.0`
+
+## [0.1.0] - 2026-02-05
+
+Initial release. Layer 1: manual mode switching with research-informed presets.
+
+### Added
+- FastMCP server with stdio transport
+- 5 working modes: explore, build, think-with, ship, cool-off
+- Transition friction matrix (none/medium/high) with double-call confirmation for high friction
+- `vibe_set_mode()`, `vibe_check()`, `vibe_nudge()`, `vibe_history()`, `vibe_session_export()`, `vibe_configure()` tools
+- `vibe://context` and `vibe://status` MCP resources
+- Three-layer config resolution: defaults < user < project < runtime
+- JSONL mode history at `~/.vibe-harness/mode-history.jsonl`
+- Versioned JSON session export
+- Onboarding message for first-time users
+- 73 unit tests
+
+[Unreleased]: https://github.com/m3data/vibe-harness-mcp/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/m3data/vibe-harness-mcp/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/m3data/vibe-harness-mcp/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/m3data/vibe-harness-mcp/releases/tag/v0.1.0

_version.py

@@ -0,0 +1,6 @@
+"""Single source of truth for the package version.
+
+Update this when cutting a release. pyproject.toml must match.
+"""
+
+__version__ = "0.3.0"

config.py

@@ -16,6 +16,7 @@
     "nudges.cooldown_minutes": 15,
     "friction.enabled": True,
     "export.auto_export": False,
+    "activity.idle_threshold_minutes": 30,
 }
 
 USER_CONFIG = Path.home() / ".vibe-harness" / "config.json"

formatters.py

@@ -28,8 +28,9 @@ def format_vibe_check(session, *, nudge: Optional[str] = None) -> str:
     if not mode_def:
         return "Session state unavailable."
 
-    mode_min = round(session.mode_duration_minutes())
-    session_min = round(session.session_duration_minutes())
+    mode_min = round(session.active_mode_minutes())
+    session_min = round(session.active_session_minutes())
+    idle_min = round(session.total_idle_minutes())
 
     lines = [
         f"Mode: {mode_def['name']}",
@@ -42,6 +43,13 @@ def format_vibe_check(session, *, nudge: Optional[str] = None) -> str:
         f"  switches  {len(session.transitions)}",
     ]
 
+    if idle_min > 0:
+        hours = idle_min / 60
+        if hours >= 1:
+            lines.append(f"  away      {hours:.1f}h detected")
+        else:
+            lines.append(f"  away      {idle_min}min detected")
+
     if session.nudges_surfaced > 0:
         lines.append(f"  nudges    {session.nudges_surfaced}")
 
@@ -61,7 +69,7 @@ def format_status_line(session) -> str:
     """One-line status for vibe://status resource."""
     mode_def = get_mode(session.mode)
     name = mode_def["name"] if mode_def else session.mode
-    mode_min = round(session.mode_duration_minutes())
+    mode_min = round(session.active_mode_minutes())
     return f"{name} | {mode_min}min | {session.interaction_count} interactions | {session.nudges_surfaced} nudges"
 
 

governor.py

@@ -76,8 +76,8 @@ def _build_session_state(session) -> dict:
     now = datetime.now(timezone.utc)
     return {
         "mode": session.mode,
-        "mode_minutes": session.mode_duration_minutes(),
-        "session_minutes": session.session_duration_minutes(),
+        "mode_minutes": session.active_mode_minutes(),
+        "session_minutes": session.active_session_minutes(),
         "interactions": session.interaction_count,
         "switches": len(session.transitions),
         "last_nudge_at": session.last_nudge_at,

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vibe-harness"
-version = "0.2.0"
+version = "0.3.0"
 description = "MCP server that tunes human-AI interaction rhythm based on working modes and biosignal data"
 requires-python = ">=3.10"
 license = "ESL-A-0.1"

server.py

@@ -13,6 +13,7 @@
 
 from mcp.server.fastmcp import FastMCP
 
+from _version import __version__
 from session import VibeSession
 from modes import valid_modes, get_mode
 from formatters import format_mode_switch, format_vibe_check, format_status_line, format_history, format_nudge_output, format_onboarding

session.py

@@ -7,11 +7,34 @@
 from typing import Optional
 import uuid
 
+import config
 from modes import get_friction, get_friction_message, default_mode, validate_mode, get_mode
 
 HISTORY_DIR = Path.home() / ".vibe-harness"
 HISTORY_FILE = HISTORY_DIR / "mode-history.jsonl"
 
+# Export schema version — tracks the JSON export format independently of the
+# package version. Bump when adding/removing/renaming fields in to_export_dict().
+EXPORT_SCHEMA_VERSION = "0.3.0"
+
+
+@dataclass
+class IdleGap:
+    """A detected period of inactivity between tool calls."""
+    start: datetime
+    end: datetime
+
+    @property
+    def duration_seconds(self) -> float:
+        return (self.end - self.start).total_seconds()
+
+    def to_dict(self) -> dict:
+        return {
+            "start": self.start.isoformat(),
+            "end": self.end.isoformat(),
+            "duration_minutes": round(self.duration_seconds / 60, 1),
+        }
+
 
 @dataclass
 class ModeTransition:
@@ -51,13 +74,29 @@ class VibeSession:
     # Tracks interaction count at last mode switch for per-mode counting
     _interactions_at_last_switch: int = field(default=0, repr=False)
 
+    # Activity tracking for idle gap detection
+    last_interaction_at: Optional[datetime] = field(default=None, repr=False)
+    _idle_gaps: list[IdleGap] = field(default_factory=list, repr=False)
+
     # High-friction confirmation state
     _pending_mode: Optional[str] = field(default=None, repr=False)
     _pending_friction: Optional[str] = field(default=None, repr=False)
     _onboarding_shown: bool = field(default=False, repr=False)
 
     def record_interaction(self) -> None:
-        """Increment interaction counter. Call on every tool invocation."""
+        """Increment interaction counter and detect idle gaps.
+
+        Call on every tool invocation. If the gap since the last interaction
+        exceeds the idle threshold, records an IdleGap so active duration
+        calculations can subtract idle time.
+        """
+        now = datetime.now(timezone.utc)
+        if self.last_interaction_at is not None:
+            gap_seconds = (now - self.last_interaction_at).total_seconds()
+            threshold_minutes = config.get("activity.idle_threshold_minutes")
+            if gap_seconds >= threshold_minutes * 60:
+                self._idle_gaps.append(IdleGap(start=self.last_interaction_at, end=now))
+        self.last_interaction_at = now
         self.interaction_count += 1
 
     def record_governance_evaluation(self, evaluations: list[dict]) -> None:
@@ -197,50 +236,99 @@ def session_duration_minutes(self) -> float:
         delta = datetime.now(timezone.utc) - self.started_at
         return delta.total_seconds() / 60
 
+    def _total_idle_seconds(self, since: datetime) -> float:
+        """Sum idle gap durations that fall after `since`.
+
+        Handles gaps that straddle the `since` boundary by only counting
+        the portion after `since`.
+        """
+        total = 0.0
+        for gap in self._idle_gaps:
+            if gap.end <= since:
+                continue
+            effective_start = max(gap.start, since)
+            total += (gap.end - effective_start).total_seconds()
+        return total
+
+    def active_session_minutes(self) -> float:
+        """Session duration minus idle time."""
+        elapsed = self.session_duration_minutes()
+        idle = self._total_idle_seconds(self.started_at) / 60
+        return max(0.0, elapsed - idle)
+
+    def active_mode_minutes(self) -> float:
+        """Current mode duration minus idle time since mode started."""
+        elapsed = self.mode_duration_minutes()
+        idle = self._total_idle_seconds(self.mode_since) / 60
+        return max(0.0, elapsed - idle)
+
+    def total_idle_minutes(self) -> float:
+        """Total idle time detected across the session."""
+        return self._total_idle_seconds(self.started_at) / 60
+
     def interactions_since_last_switch(self) -> int:
         """Interactions since last mode transition."""
         return self.interaction_count - self._interactions_at_last_switch
 
     def time_in_mode_summary(self) -> dict[str, float]:
-        """Calculate time spent in each mode during this session."""
+        """Calculate active time spent in each mode during this session.
+
+        Subtracts idle gaps from each mode's time allocation so the summary
+        reflects active time, not wall-clock time.
+        """
         summary: dict[str, float] = {}
         now = datetime.now(timezone.utc)
 
         if not self.transitions:
             mode = self.mode
-            minutes = (now - self.started_at).total_seconds() / 60
-            summary[mode] = round(minutes, 1)
+            elapsed = (now - self.started_at).total_seconds() / 60
+            idle = self._total_idle_seconds(self.started_at) / 60
+            summary[mode] = round(max(0.0, elapsed - idle), 1)
             return summary
 
+        # Build list of (mode, start, end) spans
+        spans: list[tuple[str, datetime, datetime]] = []
+
         # Time from session start to first transition
         first = self.transitions[0]
-        start_minutes = (first.timestamp - self.started_at).total_seconds() / 60
-        initial_mode = first.from_mode
-        summary[initial_mode] = summary.get(initial_mode, 0) + start_minutes
+        spans.append((first.from_mode, self.started_at, first.timestamp))
 
         # Time between transitions
         for i, t in enumerate(self.transitions):
-            if i + 1 < len(self.transitions):
-                end = self.transitions[i + 1].timestamp
-            else:
-                end = now
-            minutes = (end - t.timestamp).total_seconds() / 60
-            summary[t.to_mode] = summary.get(t.to_mode, 0) + minutes
+            end = self.transitions[i + 1].timestamp if i + 1 < len(self.transitions) else now
+            spans.append((t.to_mode, t.timestamp, end))
+
+        # Accumulate active time per mode
+        for mode, span_start, span_end in spans:
+            elapsed = (span_end - span_start).total_seconds() / 60
+            idle = self._total_idle_seconds(span_start) / 60
+            # Only count idle time within this span
+            idle_in_span = 0.0
+            for gap in self._idle_gaps:
+                if gap.end <= span_start or gap.start >= span_end:
+                    continue
+                effective_start = max(gap.start, span_start)
+                effective_end = min(gap.end, span_end)
+                idle_in_span += (effective_end - effective_start).total_seconds() / 60
+            active = max(0.0, elapsed - idle_in_span)
+            summary[mode] = summary.get(mode, 0) + active
 
         return {k: round(v, 1) for k, v in summary.items()}
 
     def to_export_dict(self) -> dict:
         """Full session data for JSON export."""
         return {
-            "schema_version": "0.2.0",
+            "schema_version": EXPORT_SCHEMA_VERSION,
             "session_id": self.session_id,
             "started_at": self.started_at.isoformat(),
             "exported_at": datetime.now(timezone.utc).isoformat(),
             "duration_minutes": round(self.session_duration_minutes(), 1),
+            "active_duration_minutes": round(self.active_session_minutes(), 1),
             "current_mode": self.mode,
             "interaction_count": self.interaction_count,
             "nudges_surfaced": self.nudges_surfaced,
             "transitions": [t.to_dict() for t in self.transitions],
+            "idle_gaps": [g.to_dict() for g in self._idle_gaps],
             "time_in_mode": self.time_in_mode_summary(),
             "governance_trace": self.governance_trace,
         }