@smilintux/skcapstone 0.1.0 → 0.2.3

package/tests/test_mood.py

@@ -0,0 +1,394 @@
+"""Tests for the agent mood tracker."""
+
+from __future__ import annotations
+
+import json
+import threading
+from pathlib import Path
+
+import pytest
+
+from skcapstone.mood import (
+    MoodSnapshot,
+    MoodTracker,
+    _classify_social,
+    _classify_stress,
+    _classify_success,
+    _compute_summary,
+)
+
+
+# ---------------------------------------------------------------------------
+# Axis classifier unit tests
+# ---------------------------------------------------------------------------
+
+
+class TestClassifySuccess:
+    """Unit tests for _classify_success."""
+
+    def test_high_rate_is_happy(self) -> None:
+        """>=90% success rate maps to 'happy'."""
+        assert _classify_success(0.95) == "happy"
+        assert _classify_success(1.0) == "happy"
+        assert _classify_success(0.9) == "happy"
+
+    def test_moderate_rate_is_content(self) -> None:
+        """70–89% maps to 'content'."""
+        assert _classify_success(0.80) == "content"
+        assert _classify_success(0.70) == "content"
+
+    def test_borderline_rate_is_neutral(self) -> None:
+        """50–69% maps to 'neutral'."""
+        assert _classify_success(0.60) == "neutral"
+        assert _classify_success(0.50) == "neutral"
+
+    def test_low_rate_is_frustrated(self) -> None:
+        """<50% maps to 'frustrated'."""
+        assert _classify_success(0.49) == "frustrated"
+        assert _classify_success(0.0) == "frustrated"
+
+
+class TestClassifySocial:
+    """Unit tests for _classify_social."""
+
+    def test_high_frequency_is_social(self) -> None:
+        """>=10 msgs/hr maps to 'social'."""
+        assert _classify_social(10.0) == "social"
+        assert _classify_social(20.0) == "social"
+
+    def test_medium_frequency_is_active(self) -> None:
+        """3–9 msgs/hr maps to 'active'."""
+        assert _classify_social(5.0) == "active"
+        assert _classify_social(3.0) == "active"
+
+    def test_low_frequency_is_quiet(self) -> None:
+        """0.5–2 msgs/hr maps to 'quiet'."""
+        assert _classify_social(1.0) == "quiet"
+        assert _classify_social(0.5) == "quiet"
+
+    def test_no_activity_is_isolated(self) -> None:
+        """<0.5 msgs/hr maps to 'isolated'."""
+        assert _classify_social(0.1) == "isolated"
+        assert _classify_social(0.0) == "isolated"
+
+
+class TestClassifyStress:
+    """Unit tests for _classify_stress."""
+
+    def test_very_low_errors_are_calm(self) -> None:
+        """<5% error rate maps to 'calm'."""
+        assert _classify_stress(0.0) == "calm"
+        assert _classify_stress(0.04) == "calm"
+
+    def test_low_errors_are_relaxed(self) -> None:
+        """5–14% maps to 'relaxed'."""
+        assert _classify_stress(0.10) == "relaxed"
+        assert _classify_stress(0.05) == "relaxed"
+
+    def test_moderate_errors_are_tense(self) -> None:
+        """15–29% maps to 'tense'."""
+        assert _classify_stress(0.20) == "tense"
+        assert _classify_stress(0.15) == "tense"
+
+    def test_high_errors_are_stressed(self) -> None:
+        """>=30% maps to 'stressed'."""
+        assert _classify_stress(0.30) == "stressed"
+        assert _classify_stress(1.0) == "stressed"
+
+
+class TestComputeSummary:
+    """Unit tests for _compute_summary."""
+
+    def test_stressed_overrides_all(self) -> None:
+        """'stressed' dominates regardless of other axes."""
+        assert _compute_summary("happy", "social", "stressed") == "stressed"
+
+    def test_frustrated_overrides_non_stressed(self) -> None:
+        """'frustrated' wins when stress is not 'stressed'."""
+        assert _compute_summary("frustrated", "social", "calm") == "frustrated"
+        assert _compute_summary("frustrated", "active", "relaxed") == "frustrated"
+
+    def test_tense_follows_frustrated(self) -> None:
+        """'tense' wins when not frustrated."""
+        assert _compute_summary("content", "active", "tense") == "tense"
+
+    def test_isolated_when_not_engaged(self) -> None:
+        """Isolation surfaces when not otherwise stressed or frustrated."""
+        assert _compute_summary("neutral", "isolated", "calm") == "isolated"
+
+    def test_flourishing_when_happy_and_active(self) -> None:
+        """Happy + socially active → 'flourishing'."""
+        assert _compute_summary("happy", "social", "calm") == "flourishing"
+        assert _compute_summary("happy", "active", "calm") == "flourishing"
+
+    def test_happy_without_social(self) -> None:
+        """Happy but quiet stays 'happy'."""
+        assert _compute_summary("happy", "quiet", "calm") == "happy"
+
+    def test_content_maps_to_content(self) -> None:
+        """content + quiet + calm → 'content'."""
+        assert _compute_summary("content", "quiet", "calm") == "content"
+
+    def test_fallback_is_neutral(self) -> None:
+        """neutral + quiet + calm → 'neutral'."""
+        assert _compute_summary("neutral", "quiet", "calm") == "neutral"
+
+
+# ---------------------------------------------------------------------------
+# MoodTracker integration tests
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def tracker(tmp_path: Path) -> MoodTracker:
+    """MoodTracker using a temp home directory."""
+    return MoodTracker(home=tmp_path)
+
+
+class TestMoodTrackerUpdate:
+    """Tests for MoodTracker.update()."""
+
+    def test_happy_high_success(self, tracker: MoodTracker) -> None:
+        """High response rate produces 'happy' success_mood."""
+        snap = tracker.update(messages=100, responses=95, errors=0)
+        assert snap.success_mood == "happy"
+        assert snap.summary in ("happy", "flourishing")
+
+    def test_frustrated_low_success(self, tracker: MoodTracker) -> None:
+        """Low response rate produces 'frustrated' success_mood and summary."""
+        snap = tracker.update(messages=100, responses=10, errors=0)
+        assert snap.success_mood == "frustrated"
+        assert snap.summary == "frustrated"
+
+    def test_stressed_high_errors(self, tracker: MoodTracker) -> None:
+        """High error rate produces 'stressed' and overrides success in summary."""
+        snap = tracker.update(messages=100, responses=90, errors=40)
+        assert snap.stress_mood == "stressed"
+        assert snap.summary == "stressed"
+
+    def test_calm_low_errors(self, tracker: MoodTracker) -> None:
+        """Near-zero errors produce 'calm' stress mood."""
+        snap = tracker.update(messages=50, responses=49, errors=1)
+        assert snap.stress_mood == "calm"
+
+    def test_social_high_frequency(self, tracker: MoodTracker) -> None:
+        """Many messages in a short window → 'social'."""
+        # 100 messages over 1 hour = 100 msgs/hr
+        snap = tracker.update(messages=100, responses=90, errors=0, window_hours=1)
+        assert snap.social_mood == "social"
+
+    def test_isolated_no_messages(self, tracker: MoodTracker) -> None:
+        """Few messages in a long window → 'isolated'."""
+        snap = tracker.update(messages=2, responses=2, errors=0, window_hours=24)
+        assert snap.social_mood == "isolated"
+
+    def test_zero_messages_defaults_to_neutral(self, tracker: MoodTracker) -> None:
+        """Zero messages produce safe default rates (no division by zero)."""
+        snap = tracker.update(messages=0, responses=0, errors=0)
+        assert snap.success_rate == 1.0
+        assert snap.error_rate == 0.0
+        assert snap.summary in ("neutral", "isolated")  # isolated because 0 msgs/hr
+
+    def test_rates_are_clamped_to_four_decimals(self, tracker: MoodTracker) -> None:
+        """success_rate and error_rate are rounded to 4 decimal places."""
+        snap = tracker.update(messages=3, responses=2, errors=1)
+        # 2/3 ≈ 0.6667, 1/3 ≈ 0.3333
+        assert snap.success_rate == round(2 / 3, 4)
+        assert snap.error_rate == round(1 / 3, 4)
+
+    def test_updated_at_is_set(self, tracker: MoodTracker) -> None:
+        """updated_at is populated after update."""
+        snap = tracker.update(messages=5, responses=5, errors=0)
+        assert snap.updated_at != ""
+        assert "T" in snap.updated_at  # ISO-8601 format
+
+
+# ---------------------------------------------------------------------------
+# Persistence
+# ---------------------------------------------------------------------------
+
+
+class TestMoodPersistence:
+    """Tests for save / load round-trip."""
+
+    def test_update_persists_file(self, tmp_path: Path) -> None:
+        """update() writes mood.json to the home directory."""
+        tracker = MoodTracker(home=tmp_path)
+        tracker.update(messages=10, responses=9, errors=0)
+        assert (tmp_path / "mood.json").exists()
+
+    def test_reload_recovers_state(self, tmp_path: Path) -> None:
+        """A second MoodTracker in the same home loads the saved snapshot."""
+        t1 = MoodTracker(home=tmp_path)
+        t1.update(messages=20, responses=18, errors=1)
+
+        t2 = MoodTracker(home=tmp_path)
+        snap = t2.snapshot
+        assert snap.messages_processed == 20
+        assert snap.responses_sent == 18
+        assert snap.errors == 1
+
+    def test_corrupt_file_yields_neutral(self, tmp_path: Path) -> None:
+        """Corrupt mood.json is silently ignored; tracker starts neutral."""
+        mood_path = tmp_path / "mood.json"
+        mood_path.write_text("not valid json {{{", encoding="utf-8")
+        tracker = MoodTracker(home=tmp_path)
+        snap = tracker.snapshot
+        assert snap.summary == "neutral"
+
+    def test_missing_file_yields_neutral(self, tmp_path: Path) -> None:
+        """Absent mood.json yields a neutral default snapshot."""
+        tracker = MoodTracker(home=tmp_path / "nonexistent")
+        snap = tracker.snapshot
+        assert snap.summary == "neutral"
+
+
+# ---------------------------------------------------------------------------
+# update_from_metrics
+# ---------------------------------------------------------------------------
+
+
+class TestUpdateFromMetrics:
+    """Tests for MoodTracker.update_from_metrics()."""
+
+    def test_reads_consciousness_metrics(self, tmp_path: Path) -> None:
+        """update_from_metrics reads from ConsciousnessMetrics.to_dict()."""
+        from skcapstone.metrics import ConsciousnessMetrics
+
+        cm = ConsciousnessMetrics(home=tmp_path, persist_interval=0)
+        for _ in range(5):
+            cm.record_message("peer-a")
+        for _ in range(4):
+            cm.record_response(50.0, "ollama", "fast")
+        cm.record_error()
+
+        tracker = MoodTracker(home=tmp_path)
+        snap = tracker.update_from_metrics(cm)
+        assert snap.messages_processed == 5
+        assert snap.responses_sent == 4
+        assert snap.errors == 1
+
+    def test_bad_metrics_object_returns_current_snapshot(self, tmp_path: Path) -> None:
+        """update_from_metrics with a broken object returns existing snapshot."""
+
+        class _BrokenMetrics:
+            def to_dict(self):
+                raise RuntimeError("broken")
+
+        tracker = MoodTracker(home=tmp_path)
+        snap_before = tracker.snapshot
+        snap_after = tracker.update_from_metrics(_BrokenMetrics())
+        assert snap_after.summary == snap_before.summary
+
+
+# ---------------------------------------------------------------------------
+# load_snapshot classmethod
+# ---------------------------------------------------------------------------
+
+
+class TestLoadSnapshot:
+    """Tests for MoodTracker.load_snapshot()."""
+
+    def test_returns_default_when_no_file(self, tmp_path: Path) -> None:
+        """Returns a neutral MoodSnapshot when no file exists."""
+        snap = MoodTracker.load_snapshot(home=tmp_path)
+        assert isinstance(snap, MoodSnapshot)
+        assert snap.summary == "neutral"
+
+    def test_returns_saved_snapshot(self, tmp_path: Path) -> None:
+        """Returns the persisted snapshot when mood.json exists."""
+        t = MoodTracker(home=tmp_path)
+        t.update(messages=30, responses=28, errors=0)
+        snap = MoodTracker.load_snapshot(home=tmp_path)
+        assert snap.messages_processed == 30
+
+
+# ---------------------------------------------------------------------------
+# describe()
+# ---------------------------------------------------------------------------
+
+
+class TestDescribe:
+    """Tests for MoodTracker.describe()."""
+
+    def test_describe_contains_summary(self, tracker: MoodTracker) -> None:
+        """describe() includes the summary word."""
+        tracker.update(messages=10, responses=10, errors=0)
+        text = tracker.describe()
+        assert "Mood summary" in text
+
+    def test_describe_contains_all_axes(self, tracker: MoodTracker) -> None:
+        """describe() mentions all three mood axes."""
+        tracker.update(messages=10, responses=9, errors=0)
+        text = tracker.describe()
+        assert "Success" in text
+        assert "Social" in text
+        assert "Stress" in text
+
+    def test_describe_contains_updated_at(self, tracker: MoodTracker) -> None:
+        """describe() includes the updated_at timestamp."""
+        tracker.update(messages=5, responses=5, errors=0)
+        text = tracker.describe()
+        assert "Updated" in text
+
+
+# ---------------------------------------------------------------------------
+# Thread safety
+# ---------------------------------------------------------------------------
+
+
+class TestThreadSafety:
+    """Tests for concurrent MoodTracker access."""
+
+    def test_concurrent_updates_are_safe(self, tmp_path: Path) -> None:
+        """Concurrent update() calls do not raise exceptions."""
+        tracker = MoodTracker(home=tmp_path)
+        errors: list[Exception] = []
+
+        def _work(i: int) -> None:
+            try:
+                tracker.update(messages=i + 1, responses=i, errors=0)
+            except Exception as exc:
+                errors.append(exc)
+
+        threads = [threading.Thread(target=_work, args=(i,)) for i in range(20)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert errors == [], f"Unexpected errors: {errors}"
+        # Snapshot must still be a valid MoodSnapshot
+        snap = tracker.snapshot
+        assert isinstance(snap, MoodSnapshot)
+
+
+# ---------------------------------------------------------------------------
+# MoodSnapshot model
+# ---------------------------------------------------------------------------
+
+
+class TestMoodSnapshot:
+    """Tests for MoodSnapshot model."""
+
+    def test_defaults_are_neutral(self) -> None:
+        """Default snapshot is neutral / quiet / calm."""
+        snap = MoodSnapshot()
+        assert snap.summary == "neutral"
+        assert snap.success_mood == "neutral"
+        assert snap.social_mood == "quiet"
+        assert snap.stress_mood == "calm"
+
+    def test_json_serializable(self) -> None:
+        """MoodSnapshot serializes to valid JSON."""
+        snap = MoodSnapshot(
+            messages_processed=5,
+            responses_sent=5,
+            errors=0,
+            summary="happy",
+            updated_at="2026-03-02T12:00:00+00:00",
+        )
+        data = snap.model_dump_json()
+        parsed = json.loads(data)
+        assert parsed["summary"] == "happy"
+        assert parsed["messages_processed"] == 5

package/tests/test_multi_agent.py

@@ -0,0 +1,269 @@
+"""Tests for multi-agent daemon isolation.
+
+Covers:
+- Per-agent home directory resolution (opus → agents/opus/, jarvis → agents/jarvis/)
+- Per-agent port assignment (opus=7777, jarvis=7778, unknown → next available)
+- Default (no-agent) mode keeps backward-compatible home and port
+- SKCAPSTONE_AGENT env var propagation
+- DaemonConfig accepts distinct homes and ports for simultaneous agents
+- PID files are isolated per agent home
+- is_running / read_pid are home-scoped (no cross-agent interference)
+- CLI --agent option resolves correct home path
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_agent_home(tmp_path: Path, agent: str) -> Path:
+    """Create a minimal agent home inside tmp_path/agents/<agent>/."""
+    home = tmp_path / "agents" / agent
+    home.mkdir(parents=True)
+    return home
+
+
+# ---------------------------------------------------------------------------
+# 1. _resolve_agent_home  — home directory isolation
+# ---------------------------------------------------------------------------
+
+
+class TestResolveAgentHome:
+    def test_named_agent_uses_agents_subdir(self, tmp_path: Path):
+        """--agent opus → ~/.skcapstone/agents/opus/"""
+        from skcapstone.cli.daemon import _resolve_agent_home
+
+        with patch("skcapstone.cli.daemon.SKCAPSTONE_ROOT", str(tmp_path)):
+            result = _resolve_agent_home("opus", str(tmp_path))
+
+        assert result == (tmp_path / "agents" / "opus").expanduser()
+
+    def test_jarvis_uses_own_subdir(self, tmp_path: Path):
+        """--agent jarvis → ~/.skcapstone/agents/jarvis/"""
+        from skcapstone.cli.daemon import _resolve_agent_home
+
+        with patch("skcapstone.cli.daemon.SKCAPSTONE_ROOT", str(tmp_path)):
+            result = _resolve_agent_home("jarvis", str(tmp_path))
+
+        assert result == (tmp_path / "agents" / "jarvis").expanduser()
+
+    def test_no_agent_uses_home_arg(self, tmp_path: Path):
+        """No --agent flag → use the --home value directly (backward compat)."""
+        from skcapstone.cli.daemon import _resolve_agent_home
+
+        custom_home = str(tmp_path / "custom")
+        result = _resolve_agent_home(None, custom_home)
+        assert result == Path(custom_home).expanduser()
+
+    def test_opus_and_jarvis_homes_are_distinct(self, tmp_path: Path):
+        """Opus and Jarvis home paths must not overlap."""
+        from skcapstone.cli.daemon import _resolve_agent_home
+
+        with patch("skcapstone.cli.daemon.SKCAPSTONE_ROOT", str(tmp_path)):
+            opus_home = _resolve_agent_home("opus", str(tmp_path))
+            jarvis_home = _resolve_agent_home("jarvis", str(tmp_path))
+
+        assert opus_home != jarvis_home
+        assert "opus" in str(opus_home)
+        assert "jarvis" in str(jarvis_home)
+
+
+# ---------------------------------------------------------------------------
+# 2. _resolve_agent_port  — port isolation
+# ---------------------------------------------------------------------------
+
+
+class TestResolveAgentPort:
+    def test_opus_gets_7777(self):
+        """opus always gets port 7777."""
+        from skcapstone.cli.daemon import _resolve_agent_port
+
+        assert _resolve_agent_port("opus", None) == 7777
+
+    def test_jarvis_gets_7778(self):
+        """jarvis always gets port 7778."""
+        from skcapstone.cli.daemon import _resolve_agent_port
+
+        assert _resolve_agent_port("jarvis", None) == 7778
+
+    def test_explicit_port_overrides_agent_default(self):
+        """Explicit --port always wins over the agent default."""
+        from skcapstone.cli.daemon import _resolve_agent_port
+
+        assert _resolve_agent_port("opus", 9999) == 9999
+        assert _resolve_agent_port("jarvis", 8000) == 8000
+
+    def test_no_agent_defaults_to_7777(self):
+        """Single-agent / no-flag mode uses 7777."""
+        from skcapstone.cli.daemon import _resolve_agent_port
+
+        assert _resolve_agent_port(None, None) == 7777
+
+    def test_unknown_agent_gets_next_port(self):
+        """An agent not in AGENT_PORTS gets max(ports)+1."""
+        from skcapstone import AGENT_PORTS
+        from skcapstone.cli.daemon import _resolve_agent_port
+
+        expected = max(AGENT_PORTS.values()) + 1
+        result = _resolve_agent_port("brandnew", None)
+        assert result == expected
+
+    def test_opus_and_jarvis_ports_differ(self):
+        """Opus and Jarvis must listen on different ports."""
+        from skcapstone.cli.daemon import _resolve_agent_port
+
+        assert _resolve_agent_port("opus", None) != _resolve_agent_port("jarvis", None)
+
+
+# ---------------------------------------------------------------------------
+# 3. AGENT_PORTS registry in __init__
+# ---------------------------------------------------------------------------
+
+
+class TestAgentPortsRegistry:
+    def test_opus_registered(self):
+        from skcapstone import AGENT_PORTS
+
+        assert "opus" in AGENT_PORTS
+        assert AGENT_PORTS["opus"] == 7777
+
+    def test_jarvis_registered(self):
+        from skcapstone import AGENT_PORTS
+
+        assert "jarvis" in AGENT_PORTS
+        assert AGENT_PORTS["jarvis"] == 7778
+
+    def test_all_ports_unique(self):
+        from skcapstone import AGENT_PORTS
+
+        ports = list(AGENT_PORTS.values())
+        assert len(ports) == len(set(ports)), "Duplicate ports in AGENT_PORTS"
+
+
+# ---------------------------------------------------------------------------
+# 4. PID-file isolation — is_running / read_pid are home-scoped
+# ---------------------------------------------------------------------------
+
+
+class TestPidIsolation:
+    def test_pid_file_written_to_agent_home(self, tmp_path: Path):
+        """PID file is created inside the agent's own home directory."""
+        from skcapstone.daemon import DaemonConfig, DaemonService
+
+        opus_home = _make_agent_home(tmp_path, "opus")
+        config = DaemonConfig(home=opus_home, port=7777)
+
+        svc = DaemonService(config)
+        # Call _write_pid directly without starting the full daemon.
+        svc._write_pid()
+
+        pid_file = opus_home / "daemon.pid"
+        assert pid_file.exists()
+        assert int(pid_file.read_text().strip()) == os.getpid()
+
+    def test_pid_files_are_isolated_between_agents(self, tmp_path: Path):
+        """Writing opus PID does not affect jarvis PID file."""
+        from skcapstone.daemon import DaemonConfig, DaemonService, read_pid
+
+        opus_home = _make_agent_home(tmp_path, "opus")
+        jarvis_home = _make_agent_home(tmp_path, "jarvis")
+
+        opus_svc = DaemonService(DaemonConfig(home=opus_home, port=7777))
+        opus_svc._write_pid()
+
+        # Jarvis home has no PID file → read_pid returns None.
+        assert read_pid(jarvis_home) is None
+
+    def test_is_running_false_without_pid_file(self, tmp_path: Path):
+        """is_running returns False when no PID file exists."""
+        from skcapstone.daemon import is_running
+
+        empty_home = _make_agent_home(tmp_path, "nobody")
+        assert is_running(empty_home) is False
+
+    def test_read_pid_returns_current_pid_after_write(self, tmp_path: Path):
+        """read_pid returns the PID we just wrote."""
+        from skcapstone.daemon import DaemonConfig, DaemonService, read_pid
+
+        home = _make_agent_home(tmp_path, "opus")
+        svc = DaemonService(DaemonConfig(home=home, port=7777))
+        svc._write_pid()
+
+        assert read_pid(home) == os.getpid()
+
+
+# ---------------------------------------------------------------------------
+# 5. DaemonConfig — simultaneous distinct configs
+# ---------------------------------------------------------------------------
+
+
+class TestDaemonConfigMultiAgent:
+    def test_two_configs_have_distinct_homes_and_ports(self, tmp_path: Path):
+        """Two DaemonConfig instances for opus/jarvis stay isolated."""
+        from skcapstone.daemon import DaemonConfig
+
+        opus_home = _make_agent_home(tmp_path, "opus")
+        jarvis_home = _make_agent_home(tmp_path, "jarvis")
+
+        opus_cfg = DaemonConfig(home=opus_home, port=7777)
+        jarvis_cfg = DaemonConfig(home=jarvis_home, port=7778)
+
+        assert opus_cfg.home != jarvis_cfg.home
+        assert opus_cfg.port != jarvis_cfg.port
+        assert opus_cfg.port == 7777
+        assert jarvis_cfg.port == 7778
+
+    def test_log_files_are_in_respective_homes(self, tmp_path: Path):
+        """Each agent's log file lives under its own home."""
+        from skcapstone.daemon import DaemonConfig
+
+        opus_home = _make_agent_home(tmp_path, "opus")
+        jarvis_home = _make_agent_home(tmp_path, "jarvis")
+
+        opus_cfg = DaemonConfig(home=opus_home, port=7777)
+        jarvis_cfg = DaemonConfig(home=jarvis_home, port=7778)
+
+        assert str(opus_cfg.log_file).startswith(str(opus_home))
+        assert str(jarvis_cfg.log_file).startswith(str(jarvis_home))
+        assert opus_cfg.log_file != jarvis_cfg.log_file
+
+
+# ---------------------------------------------------------------------------
+# 6. SKCAPSTONE_AGENT env-var path derivation in __init__
+# ---------------------------------------------------------------------------
+
+
+class TestAgentHomeEnvVar:
+    def test_env_var_produces_agents_subdir(self, monkeypatch):
+        """SKCAPSTONE_AGENT=opus → AGENT_HOME includes agents/opus."""
+        import importlib
+
+        monkeypatch.setenv("SKCAPSTONE_AGENT", "opus")
+        monkeypatch.setenv("SKCAPSTONE_ROOT", "/tmp/sk")
+
+        import skcapstone as pkg
+        importlib.reload(pkg)
+
+        assert "agents/opus" in pkg.AGENT_HOME or "agents\\opus" in pkg.AGENT_HOME
+
+    def test_no_env_var_uses_root_directly(self, monkeypatch):
+        """Without SKCAPSTONE_AGENT, AGENT_HOME == SKCAPSTONE_ROOT."""
+        import importlib
+
+        monkeypatch.delenv("SKCAPSTONE_AGENT", raising=False)
+        monkeypatch.setenv("SKCAPSTONE_ROOT", "/tmp/sk")
+
+        import skcapstone as pkg
+        importlib.reload(pkg)
+
+        assert pkg.AGENT_HOME == pkg.SHARED_ROOT