xrefkit 0.5.0__tar.gz → 0.6.0__tar.gz

{xrefkit-0.5.0/xrefkit.egg-info → xrefkit-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.5.0
+Version: 0.6.0
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -47,6 +47,44 @@ record evidence, preserve human judgment, and apply explicit completion checks.
 
 ## Why XRefKit?
 
+Experimental local tool: [Attention Pet](projects/attention-pet/README.en.md) helps
+people assess capability sufficiency and lower inference-cost candidates separately.
+Its Model Fit / Cost Fit estimates use uncalibrated profiles; it does not measure internal
+attention or switch models automatically.
+
+### Codex-only preview: Attention Pet
+
+Attention Pet is a small local companion for Codex work. It reads the current
+Codex chat's local session record, estimates whether the selected model meets
+the visible work requirements, and shows the result through a compact animated
+pet. It also shows lower inference-cost comparison candidates when the
+experimental profiles support one. The estimate is observational and does not
+change the Codex model, reasoning level, or chat.
+
+It does not measure token usage. It estimates the structural complexity of the
+work context the AI must handle, including retained items, dependencies,
+constraints, decision depth, conflicts, and dispersed evidence. It does not
+read model-internal attention or remaining context-window capacity.
+
+Run it from a Codex terminal in this repository so `CODEX_THREAD_ID` identifies
+the current chat:
+
+```powershell
+python -m xrefkit.attention_pet serve --port 8769
+```
+
+Open the printed `http://127.0.0.1:8769/` address in the Codex browser panel.
+The display follows the browser's preferred language: Japanese is used for a
+Japanese preference, with English as the fallback. Stop the process with
+Ctrl+C.
+
+This Codex preview is bound to the chat that launched it. Selecting another
+chat does not move the Pet automatically; launch it again from that chat when
+you want a separate view. The model and reasoning dropdowns only compare
+estimates and do not change the active Codex settings. See the
+[Attention Pet guide](projects/attention-pet/README.en.md) for interpretation,
+limitations, client integration, and API details.
+
 Using AI for real work creates recurring operating problems:
 
 ![Why XRefKit is needed](human-docs/en/assets/why_xrefkit_needed/whatis_xrefkit.png)

{xrefkit-0.5.0 → xrefkit-0.6.0}/README.md

@@ -8,6 +8,44 @@ record evidence, preserve human judgment, and apply explicit completion checks.
 
 ## Why XRefKit?
 
+Experimental local tool: [Attention Pet](projects/attention-pet/README.en.md) helps
+people assess capability sufficiency and lower inference-cost candidates separately.
+Its Model Fit / Cost Fit estimates use uncalibrated profiles; it does not measure internal
+attention or switch models automatically.
+
+### Codex-only preview: Attention Pet
+
+Attention Pet is a small local companion for Codex work. It reads the current
+Codex chat's local session record, estimates whether the selected model meets
+the visible work requirements, and shows the result through a compact animated
+pet. It also shows lower inference-cost comparison candidates when the
+experimental profiles support one. The estimate is observational and does not
+change the Codex model, reasoning level, or chat.
+
+It does not measure token usage. It estimates the structural complexity of the
+work context the AI must handle, including retained items, dependencies,
+constraints, decision depth, conflicts, and dispersed evidence. It does not
+read model-internal attention or remaining context-window capacity.
+
+Run it from a Codex terminal in this repository so `CODEX_THREAD_ID` identifies
+the current chat:
+
+```powershell
+python -m xrefkit.attention_pet serve --port 8769
+```
+
+Open the printed `http://127.0.0.1:8769/` address in the Codex browser panel.
+The display follows the browser's preferred language: Japanese is used for a
+Japanese preference, with English as the fallback. Stop the process with
+Ctrl+C.
+
+This Codex preview is bound to the chat that launched it. Selecting another
+chat does not move the Pet automatically; launch it again from that chat when
+you want a separate view. The model and reasoning dropdowns only compare
+estimates and do not change the active Codex settings. See the
+[Attention Pet guide](projects/attention-pet/README.en.md) for interpretation,
+limitations, client integration, and API details.
+
 Using AI for real work creates recurring operating problems:
 
 ![Why XRefKit is needed](human-docs/en/assets/why_xrefkit_needed/whatis_xrefkit.png)

{xrefkit-0.5.0 → xrefkit-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xrefkit"
-version = "0.5.0"
+version = "0.6.0"
 description = "Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit"
 readme = "README.md"
 requires-python = ">=3.11"

xrefkit-0.6.0/tests/test_attention_pet.py

@@ -0,0 +1,257 @@
+import json
+import threading
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+import pytest
+from pydantic import ValidationError
+
+from xrefkit.attention_pet.evaluator import Weights, evaluate
+from xrefkit.attention_pet.model import Conversation, Edge, Item, WorkingSet, extract
+from xrefkit.attention_pet.scenarios import scenario
+from xrefkit.attention_pet.server import make_server
+from xrefkit.attention_pet.store import Store
+
+
+def fixture(name="A", step=1):
+    return WorkingSet.model_validate(scenario(name, step)["workingSet"])
+
+
+def test_scenario_a_independent_requests_grow_gradually():
+    scores = [evaluate(fixture("A", s))["ral"] for s in range(1, 6)]
+    assert scores == sorted(scores)
+    assert max(b - a for a, b in zip(scores, scores[1:])) < 10
+
+
+def test_scenario_b_relationships_cost_more_than_independent_items():
+    a, b = evaluate(fixture("A", 5)), evaluate(fixture("B", 5))
+    assert a["features"]["active_items"] == b["features"]["active_items"]
+    assert b["ral"] > a["ral"] + 20
+    assert b["features"]["dependency_edges"] > 0
+
+
+def test_scenario_c_low_load_can_have_wrong_trajectory():
+    states = [evaluate(fixture("C", s)) for s in range(1, 4)]
+    assert len({s["ral"] for s in states}) == 1
+    assert states[-1]["ral"] < 40
+    assert states[-1]["trajectoryStability"] < states[0]["trajectoryStability"]
+    assert states[-1]["state"] == "WRONG TRAJECTORY"
+    assert states[-1]["expression"] == "wrong_trajectory"
+    assert "restart" in states[-1]["recommendedActions"]
+
+
+def test_scenario_d_summary_lowers_load_without_erasing_constraints():
+    store = Store()
+    before = store.submit(fixture("D"))
+    result = store.recover("summarize", before["state"]["observedAt"])
+    assert before["state"]["ral"] >= 75
+    assert result["state"]["ral"] < before["state"]["ral"]
+    assert result["state"]["deltaRal"] < 0
+    assert result["state"]["features"]["constraint"] == before["state"]["features"]["constraint"]
+    assert result["state"]["features"]["dependency_edges"] == before["state"]["features"]["dependency_edges"]
+    assert len(result["workingSet"]["items"]) == len(before["workingSet"]["items"])
+
+
+def test_scenario_e_restart_requires_fresh_validation_to_recover():
+    store = Store()
+    before = store.submit(fixture("E", 3))
+    handoff = store.recover("restart", before["state"]["observedAt"])
+    assert handoff["state"] == before["state"]  # Download is not a context restart.
+    fresh = fixture("E", 4)
+    fresh.observations = [o for o in fresh.observations if o.context != fresh.contextId]
+    unknown = store.submit(fresh)
+    assert unknown["state"]["trajectoryStability"] is None
+    recovered = store.submit(fixture("E", 5))
+    assert recovered["state"]["trajectoryStability"] > before["state"]["trajectoryStability"]
+    assert recovered["state"]["ral"] == before["state"]["ral"]
+
+
+def test_trend_uses_time_window_and_reports_feature_deltas():
+    store = Store()
+    a = store.submit(fixture("B", 1))
+    b = store.submit(fixture("B", 4))
+    assert b["state"]["deltaRal"] == b["state"]["ral"] - a["state"]["ral"]
+    assert b["state"]["trend"] == "rapid_rise"
+    assert {c["feature"] for c in b["state"]["changes"]} >= {"constraint", "dependency_edges"}
+    ws = fixture("B", 5)
+    ws.observedAt = 2000.0
+    assert store.submit(ws)["state"]["trend"] != "rapid_rise"
+
+
+def test_unknown_trajectory_does_not_override_load_and_task_switch_does_not_compare():
+    ws = fixture()
+    ws.observations = []
+    assert evaluate(ws)["state"] == "UNKNOWN"
+    assert evaluate(ws)["expression"] == "stable"
+    store = Store()
+    store.submit(ws)
+    assert store.submit(fixture("B"))["state"]["deltaRal"] is None
+
+
+@pytest.mark.parametrize("coverage", ["partial", "reviewed"])
+@pytest.mark.parametrize("step,expression", [(1,"stable"),(3,"loaded"),(5,"strained")])
+def test_structural_load_remains_visible_without_trajectory(coverage, step, expression):
+    ws = fixture("B", step)
+    ws.coverage = coverage
+    ws.observations = []
+    state = evaluate(ws)
+    assert state["trajectoryStability"] is None
+    assert state["state"] == "UNKNOWN"
+    assert state["expression"] == expression
+
+
+def test_fix_retains_relations_and_does_not_fake_lower_load():
+    store = Store()
+    before = store.submit(fixture("B", 3))
+    fixed = store.recover("fix", before["state"]["observedAt"])
+    assert fixed["state"]["ral"] == before["state"]["ral"]
+    assert all(i["fixed"] for i in fixed["workingSet"]["items"] if i["kind"] == "decision")
+
+
+def test_summary_preserves_history_referenced_by_active_items():
+    ws = fixture("D")
+    ws.dependencies.append(Edge(source="d0", target="h0-0", evidence="needed evidence"))
+    store = Store()
+    store.submit(ws)
+    result = store.recover("summarize", ws.observedAt)
+    assert next(i for i in result["workingSet"]["items"] if i["id"] == "h0-0")["status"] == "active"
+
+
+@pytest.mark.parametrize("action", ["split", "externalize", "resolve", "rebase", "restart"])
+def test_handoff_actions_do_not_claim_to_change_live_context(action):
+    store = Store()
+    before = store.submit(fixture())
+    result = store.recover(action, before["state"]["observedAt"])
+    assert result["recovery"]["effect"] == "handoff_created"
+    assert result["recovery"]["handoff"]["workingSet"] == before["workingSet"]
+    assert result["state"] == before["state"]
+
+
+@pytest.mark.parametrize("mutation", [
+    lambda d: d.update(unexpected="field"),
+    lambda d: d.update(observedAt=float("nan")),
+    lambda d: d.update(items=d["items"] * 2),
+    lambda d: d.update(dependencies=[{"source":"absent","target":"d0","evidence":"bad"}]),
+    lambda d: d["items"][0].update(depth=-1),
+    lambda d: d["items"][0].update(fixed="true"),
+])
+def test_invalid_boundary_data_is_rejected(mutation):
+    data = fixture().model_dump()
+    mutation(data)
+    with pytest.raises(ValidationError):
+        WorkingSet.model_validate(data)
+
+
+def test_timestamp_replay_and_stale_recovery():
+    store = Store()
+    ws = fixture()
+    first = store.submit(ws)
+    assert store.submit(ws) == first
+    stale = ws.model_copy(deep=True)
+    stale.observedAt = 1.0
+    with pytest.raises(ValueError, match="timestamps"):
+        store.submit(stale)
+    with pytest.raises(ValueError, match="refresh"):
+        store.recover("fix", 1.0)
+
+
+def test_extract_upserts_status_and_marks_unannotated_turn_partial():
+    data = scenario("A")["conversation"]
+    updated = dict(data["turns"][0]["items"][0], status="done")
+    data["turns"].append({"id":"update", "text":"Requirement complete", "items":[updated]})
+    ws = extract(Conversation.model_validate(data))
+    assert len(ws.items) == 5 and ws.items[0].status == "done"
+    data["turns"].append({"id":"unannotated", "text":"A new unknown requirement"})
+    assert extract(Conversation.model_validate(data)).coverage == "partial"
+    data["turns"][0]["items"][0]["source"] = "missing"
+    with pytest.raises(ValueError, match="supplied turn"):
+        extract(Conversation.model_validate(data))
+
+
+def test_persistence_restart_and_failed_write_do_not_mutate_state(tmp_path, monkeypatch):
+    from pathlib import Path
+    path = tmp_path / "session.json"
+    store = Store(path)
+    store.submit(fixture("B", 1))
+    before = store.submit(fixture("B", 2))
+    assert Store(path).view() == before
+    def fail(*args):
+        raise OSError("disk full")
+    monkeypatch.setattr(Path, "replace", fail)
+    with pytest.raises(OSError):
+        store.submit(fixture("B", 3))
+    assert store.view() == before
+
+
+def test_weights_validation():
+    with pytest.raises(ValueError):
+        Weights(working_set=-1)
+    with pytest.raises(ValueError):
+        Weights(working_set=float("nan"))
+
+
+def test_high_load_alone_never_recommends_restart():
+    state = evaluate(fixture("D"))
+    assert state["ral"] >= 75 and state["state"] == "HIGH LOAD"
+    assert "restart" not in state["recommendedActions"]
+
+
+@pytest.mark.parametrize("count,band", [(1,"stable"),(16,"loaded"),(24,"strained"),(30,"high_pressure"),(36,"unstable")])
+def test_five_visual_bands_and_critical_override(count, band):
+    ws = fixture()
+    ws.items = [Item(id=f"g-{i}", kind="goal", text="goal", source="test") for i in range(count)]
+    weights = Weights(working_set=100, dependency_complexity=0, constraint_density=0,
+                      decision_depth=0, conflict_pressure=0, context_dispersion=0)
+    assert evaluate(ws, weights=weights)["expression"] == band
+    ws.observations = fixture("C", 3).observations
+    result = evaluate(ws, weights=weights)
+    assert result["state"] == ("CRITICAL" if count >= 30 else "WRONG TRAJECTORY")
+
+
+def test_empty_partial_snapshot_stays_unknown_and_bounds_hold():
+    ws = WorkingSet(taskId="empty",contextId="c",observedAt=1.0,items=[])
+    result = evaluate(ws)
+    assert result["ral"] == 0 and result["trajectoryStability"] is None
+    assert result["state"] == "UNKNOWN"
+
+
+def test_http_api_auth_origin_validation_recovery_and_assets():
+    server, launch = make_server(Store())
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    base, token = launch.rstrip("/"), server.write_token
+    def request(path, data=None, auth=True, origin=None):
+        headers = {"Authorization":f"Bearer {token}"} if auth else {}
+        if origin:
+            headers["Origin"] = origin
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        req = Request(base + path, json.dumps(data).encode() if data is not None else None, headers)
+        with urlopen(req, timeout=5) as response:
+            return response.read()
+    try:
+        assert b"Attention Pet" in request("/", auth=False)
+        for path in ("/pet.js", "/pet.css"):
+            assert request(path, auth=False)
+        assert json.loads(request("/api/state", auth=False))["state"] is None
+        with pytest.raises(HTTPError) as error:
+            request("/api/snapshot", fixture().model_dump(), auth=False)
+        assert error.value.code == 401
+        with pytest.raises(HTTPError) as error:
+            request("/api/snapshot", fixture().model_dump(), origin="https://example.com")
+        assert error.value.code == 403
+        with pytest.raises(HTTPError) as error:
+            request("/api/snapshot", {"ral":99})
+        assert error.value.code == 400
+        before = json.loads(request("/api/conversation", scenario("D")["conversation"]))
+        after = json.loads(request("/api/recover", {"action":"summarize", "expectedObservedAt":before["state"]["observedAt"]}))
+        assert after["state"]["ral"] < before["state"]["ral"]
+        assert json.loads(request("/api/state"))["state"] == after["state"]
+        with pytest.raises(HTTPError) as error:
+            request("/api/demo", {"scenario":"C", "step":3})
+        assert error.value.code == 404
+        assert json.loads(request("/api/state"))["state"] == after["state"]
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=5)

xrefkit-0.6.0/tests/test_attention_pet_client_protocol.py

@@ -0,0 +1,302 @@
+"""Same-host client protocol and session switching."""
+
+import json
+import subprocess
+import sys
+import threading
+from pathlib import Path
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+import pytest
+
+from xrefkit.attention_pet.client_protocol import ClientStateSource, PROTOCOL_VERSION
+from xrefkit.attention_pet.client_protocol import ClientState
+from xrefkit.attention_pet.client import AttentionPetClient, ClientProtocolError
+from xrefkit.attention_pet.evaluator import Weights
+from xrefkit.attention_pet.server import make_server
+from xrefkit.attention_pet.store import Store
+
+
+def payload(session: str, revision: int, item_count: int = 1) -> dict:
+    observed = float(100 + revision)
+    return {
+        "protocolVersion": PROTOCOL_VERSION,
+        "provider": "codex-desktop",
+        "clientInstanceId": "window-1",
+        "sessionId": session,
+        "activationRevision": revision,
+        "observedAt": observed,
+        "model": "gpt-6-sol",
+        "reasoning": "medium",
+        "capabilities": {
+            "activeSessionChanged": True,
+            "promptSubmitted": True,
+            "modelSelected": True,
+            "fullConversationAccess": False,
+        },
+        "workingSet": {
+            "schemaVersion": 1,
+            "taskId": "task-" + session,
+            "contextId": session,
+            "observedAt": observed,
+            "coverage": "partial",
+            "items": [
+                {"id": f"item-{index}", "kind": "goal", "text": "structured item",
+                 "source": f"event-{index}"}
+                for index in range(item_count)
+            ],
+            "dependencies": [],
+            "observations": [],
+        },
+    }
+
+
+def test_handshake_authentication_and_active_session_switching(tmp_path):
+    source = ClientStateSource(tmp_path / "sessions", Weights())
+    server, launch = make_server(Store(), source=source)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    base = launch.rstrip("/")
+    auth = {"Authorization": f"Bearer {server.write_token}"}
+
+    def get(path, headers=None):
+        with urlopen(Request(base + path, headers=headers or {}), timeout=5) as response:
+            return json.load(response)
+
+    def post(path, value):
+        request = Request(base + path, json.dumps(value).encode(),
+                          {**auth, "Content-Type": "application/json"})
+        with urlopen(request, timeout=5) as response:
+            return json.load(response)
+
+    try:
+        with pytest.raises(HTTPError) as error:
+            get("/api/client/handshake")
+        assert error.value.code == 401
+        hello = get("/api/client/handshake", auth)
+        assert hello == {
+            "service": "xrefkit-attention-pet",
+            "protocolVersion": PROTOCOL_VERSION,
+            "instanceId": server.instance_id,
+            "capabilities": ["active-session", "working-set-snapshot"],
+            "writeAuthentication": "bearer",
+            "hostScope": "loopback",
+        }
+
+        accepted = post("/api/active-session", payload("session-a", 1, 1))
+        assert accepted["accepted"] is True
+        assert accepted["instanceId"] == server.instance_id
+        assert post("/api/active-session", payload("session-a", 1, 1)) == accepted
+        first = get("/api/state")
+        assert first["source"]["sessionId"] == "session-a"
+        assert first["source"]["activationRevision"] == 1
+        assert first["source"]["profile"] == "sol"
+        assert first["state"]["features"]["active_items"] == 1
+        english = get("/api/state?lang=en")
+        assert english["fit"]["presentation"]["headline"].startswith("For the work currently visible")
+        assert english["fit"]["presentation"]["coverageLabel"] == "Partial"
+
+        with pytest.raises(HTTPError) as error:
+            get("/api/state?lang=fr")
+        assert error.value.code == 400
+
+        next_session = payload("session-b", 2, 2)
+        next_session["model"] = "gpt-6-astra"
+        next_session["reasoning"] = "high"
+        post("/api/active-session", next_session)
+        second = get("/api/state?model=&reasoning=medium")
+        assert second["source"]["sessionId"] == "session-b"
+        assert second["fit"]["selectedProfile"] == {"model": "astra", "reasoning": "high"}
+        assert second["state"]["features"]["active_items"] == 2
+        manual_comparison = get("/api/state?model=sol&reasoning=medium")
+        assert manual_comparison["fit"]["selectedProfile"] == {"model": "sol", "reasoning": "medium"}
+
+        with pytest.raises(HTTPError) as error:
+            post("/api/active-session", payload("session-a", 1, 1))
+        assert error.value.code == 409
+        assert get("/api/state")["source"]["sessionId"] == "session-b"
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=5)
+
+
+def test_state_response_keeps_one_session_when_activation_follows_snapshot(tmp_path, monkeypatch):
+    source = ClientStateSource(tmp_path / "sessions", Weights())
+    source.activate(ClientState.model_validate(payload("session-a", 1)))
+    next_session = payload("session-b", 2)
+    next_session["model"] = "gpt-6-astra"
+    next_session["reasoning"] = "high"
+    next_state = ClientState.model_validate(next_session)
+    original_snapshot = source.snapshot
+
+    def switch_after_snapshot(fallback_store):
+        snapshot = original_snapshot(fallback_store)
+        source.activate(next_state)
+        return snapshot
+
+    monkeypatch.setattr(source, "snapshot", switch_after_snapshot)
+    server, launch = make_server(Store(), source=source)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        with urlopen(launch + "api/state?model=&reasoning=medium", timeout=5) as response:
+            before = json.load(response)
+        assert before["state"]["taskId"] == "task-session-a"
+        assert before["source"]["sessionId"] == "session-a"
+        assert before["fit"]["selectedProfile"] == {"model": "sol", "reasoning": "medium"}
+
+        monkeypatch.setattr(source, "snapshot", original_snapshot)
+        with urlopen(launch + "api/state?model=&reasoning=medium", timeout=5) as response:
+            after = json.load(response)
+        assert after["state"]["taskId"] == "task-session-b"
+        assert after["source"]["sessionId"] == "session-b"
+        assert after["fit"]["selectedProfile"] == {"model": "astra", "reasoning": "high"}
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=5)
+
+
+def test_client_snapshot_blocks_activation_until_all_session_fields_are_read(tmp_path, monkeypatch):
+    source = ClientStateSource(tmp_path / "sessions", Weights())
+    source.activate(ClientState.model_validate(payload("session-a", 1)))
+    next_session = payload("session-b", 2)
+    next_session["model"] = "gpt-6-astra"
+    next_session["reasoning"] = "high"
+    next_state = ClientState.model_validate(next_session)
+    view_read = threading.Event()
+    resume_view = threading.Event()
+    activation_started = threading.Event()
+    activation_done = threading.Event()
+    captured = {}
+    original_view = source.view
+
+    def pause_after_view(fallback_store):
+        result = original_view(fallback_store)
+        view_read.set()
+        assert resume_view.wait(timeout=5)
+        return result
+
+    def read_snapshot():
+        captured["snapshot"] = source.snapshot(Store())
+
+    def activate_next():
+        activation_started.set()
+        source.activate(next_state)
+        activation_done.set()
+
+    monkeypatch.setattr(source, "view", pause_after_view)
+    reader = threading.Thread(target=read_snapshot)
+    activator = threading.Thread(target=activate_next)
+    reader.start()
+    try:
+        assert view_read.wait(timeout=5)
+        activator.start()
+        assert activation_started.wait(timeout=5)
+        assert not activation_done.wait(timeout=0.1)
+    finally:
+        resume_view.set()
+        reader.join(timeout=5)
+        if activator.ident is not None:
+            activator.join(timeout=5)
+
+    assert not reader.is_alive() and not activator.is_alive()
+    result, selection, status = captured["snapshot"]
+    assert result["state"]["taskId"] == "task-session-a"
+    assert selection == ("sol", "medium")
+    assert status["sessionId"] == "session-a"
+    assert activation_done.is_set()
+    assert source.status()["sessionId"] == "session-b"
+
+
+def test_client_contract_rejects_mismatched_session_and_manual_mode(tmp_path):
+    source = ClientStateSource(tmp_path / "sessions", Weights())
+    server, launch = make_server(Store(), source=source)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    base = launch.rstrip("/")
+    auth = {"Authorization": f"Bearer {server.write_token}", "Content-Type": "application/json"}
+    try:
+        invalid = payload("session-a", 1)
+        invalid["workingSet"]["contextId"] = "different"
+        request = Request(base + "/api/active-session", json.dumps(invalid).encode(), auth)
+        with pytest.raises(HTTPError) as error:
+            urlopen(request, timeout=5)
+        assert error.value.code == 400
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=5)
+
+
+def test_provider_client_verifies_loopback_identity_and_acknowledgement(tmp_path):
+    source = ClientStateSource(tmp_path / "sessions", Weights())
+    server, launch = make_server(Store(), source=source)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        client = AttentionPetClient(launch, server.write_token,
+                                    instance_id=server.instance_id)
+        assert client.handshake()["service"] == "xrefkit-attention-pet"
+        state = ClientState.model_validate(payload("session-client", 3))
+        assert client.activate(state)["activeSessionId"] == "session-client"
+
+        with pytest.raises(ClientProtocolError, match="instance"):
+            AttentionPetClient(launch, server.write_token,
+                               instance_id="different").handshake()
+        with pytest.raises(ClientProtocolError, match="request failed"):
+            AttentionPetClient(launch, "wrong-token").handshake()
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=5)
+
+    for invalid in ["https://127.0.0.1:8769", "http://example.com:8769",
+                    "http://127.0.0.1", "http://127.0.0.1:8769/?token=value"]:
+        with pytest.raises(ValueError, match="127.0.0.1"):
+            AttentionPetClient(invalid, "token")
+
+    manual, manual_launch = make_server(Store())
+    thread = threading.Thread(target=manual.serve_forever, daemon=True)
+    thread.start()
+    try:
+        request = Request(manual_launch.rstrip("/") + "/api/active-session",
+                          json.dumps(payload("session-a", 1)).encode(),
+                          {"Authorization": f"Bearer {manual.write_token}",
+                           "Content-Type": "application/json"})
+        with pytest.raises(HTTPError) as error:
+            urlopen(request, timeout=5)
+        assert error.value.code == 409
+    finally:
+        manual.shutdown()
+        manual.server_close()
+        thread.join(timeout=5)
+
+
+def test_client_schema_and_launch_record_are_machine_readable(tmp_path):
+    root = Path(__file__).resolve().parents[1]
+    schema = json.loads((root / "projects/attention-pet/schema/client-state.schema.json").read_text(encoding="utf-8"))
+    assert schema == ClientState.model_json_schema()
+    packaged = json.loads((root / "xrefkit/resources/attention_pet/client-state.schema.json").read_text(encoding="utf-8"))
+    assert packaged == schema
+
+    process = subprocess.Popen(
+        [sys.executable, "-m", "xrefkit.attention_pet", "serve", "--client",
+         "--port", "0", "--session", str(tmp_path / "sessions")],
+        cwd=root, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
+        encoding="utf-8",
+    )
+    try:
+        launch = json.loads(process.stdout.readline())
+        assert launch["service"] == "xrefkit-attention-pet"
+        assert launch["protocolVersion"] == PROTOCOL_VERSION
+        assert launch["endpoint"].startswith("http://127.0.0.1:")
+        assert launch["writeToken"]
+        client = AttentionPetClient(launch["endpoint"], launch["writeToken"],
+                                    instance_id=launch["instanceId"])
+        assert client.handshake()["instanceId"] == launch["instanceId"]
+    finally:
+        process.terminate()
+        process.wait(timeout=10)