feat(lib): implement A-4 M0~M1 BaseAgentAdapter pattern and resolve_home contract

tests/test_a4_adapter_contract.py

@@ -0,0 +1,47 @@
+# test_a4_adapter_contract.py — Contract tests for BaseAgentAdapter and resolve_home
+
+import os, pytest
+from lib_py.paths import resolve_home
+from lib_py.agents.registry import get_adapter, own_key, agent_of_row
+
+def test_resolve_home_contract():
+    # 1. When explicit home_dir is passed
+    assert resolve_home('/custom/home') == '/custom/home'
+
+    # 2. When HOME_DIR env var is set
+    orig = os.environ.get('HOME_DIR')
+    try:
+        os.environ['HOME_DIR'] = '/env/home'
+        assert resolve_home() == '/env/home'
+    finally:
+        if orig is None:
+            os.environ.pop('HOME_DIR', None)
+        else:
+            os.environ['HOME_DIR'] = orig
+
+    # 3. When HOME_DIR env var is NOT set, falls back to HOME / expanduser (~), NOT '' or '/'
+    env_copy = os.environ.copy()
+    env_copy.pop('HOME_DIR', None)
+    home_val = env_copy.get('HOME') or os.path.expanduser('~')
+    assert resolve_home() == home_val
+
+def test_agent_adapter_registry():
+    for agent in ('claude', 'agy', 'hermes', 'cline'):
+        adapter = get_adapter(agent)
+        assert adapter is not None
+        assert adapter.name == agent
+        assert adapter.own_key == f"{agent}_{'session' if agent == 'claude' else 'conversation'}_id_own"
+        assert own_key(agent) == adapter.own_key
+
+def test_agent_of_row_priority():
+    # Priority 1: Explicit 'agent' field
+    row1 = {'agent': 'agy', 'name': 'some-name-creator-claude'}
+    assert agent_of_row(row1) == 'agy'
+
+    # Priority 2: Session name suffix
+    row2 = {'name': 'my-workspace-planner-hermes'}
+    assert agent_of_row(row2) == 'hermes'
+
+    # Priority 3: pane.cmd exact match
+    row3 = {'pane': {'cmd': 'cline'}}
+    assert agent_of_row(row3) == 'cline'