Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
from __future__ import annotations
import asyncio
import logging
import sqlite3
import threading
import time
from contextlib import closing
from types import SimpleNamespace
from typing import Any
from unittest.mock import Mock
import pytest
from core.runtime_activation import (
RuntimeActivationCommit,
RuntimeActivationRegistry,
RuntimeActivationResolution,
)
from core.runtime_recovery import FallbackRequestRecoveryHandler
from core.scheduled_tasks import ScheduledTaskService, TaskExecutionRequest, TaskExecutionStore
from core.session_activities import SessionActivityRegistry
from modules.agents.base import AGENT_RUNTIME_TURN_KEY, AGENT_RUNTIME_TURN_TOKEN
from modules.agents.claude_agent import ClaudeAgent
from modules.agents.codex.agent import CodexAgent
from modules.agents.opencode.agent import OpenCodeAgent
from modules.agents.opencode.server import OpenCodeGeneration
from modules.agents.service import AgentService
from tests.codex_generation_support import init_generation_state, install_codex_transport
from tests.fake_pid_helpers import fake_pid
def _join(thread: threading.Thread) -> None:
thread.join(timeout=2)
assert not thread.is_alive()
def test_admission_first_commit_finishes_before_retirement_predicate() -> None:
registry = RuntimeActivationRegistry()
identity = registry.attach("claude", "runtime-1")
commit_entered = threading.Event()
allow_commit = threading.Event()
retire_started = threading.Event()
order: list[str] = []
admission: list[RuntimeActivationCommit[str]] = []
retired: list[bool] = []
def commit() -> str:
order.append("commit-entered")
commit_entered.set()
assert allow_commit.wait(timeout=2)
order.append("commit-finished")
return "owner"
def admit() -> None:
admission.append(registry.commit_if_current(identity, commit))
def retire() -> None:
retire_started.set()
def final_predicate() -> bool:
order.append("retire-predicate")
return True
retired.append(registry.retire_if_current(identity, final_predicate))
admission_thread = threading.Thread(target=admit)
retirement_thread = threading.Thread(target=retire)
admission_thread.start()
assert commit_entered.wait(timeout=2)
retirement_thread.start()
assert retire_started.wait(timeout=2)
allow_commit.set()
_join(admission_thread)
_join(retirement_thread)
assert admission == [RuntimeActivationCommit(admitted=True, value="owner")]
assert retired == [True]
assert order == ["commit-entered", "commit-finished", "retire-predicate"]
assert registry.current("claude", "runtime-1") is None
assert registry.current("claude", "runtime-1", include_retired=True) == identity
def test_task_request_serialization_excludes_the_live_activation_boundary() -> None:
registry = RuntimeActivationRegistry()
identity = registry.attach("claude", "runtime-1")
request = TaskExecutionRequest(
id="run-1",
request_type="agent_run",
observed_activation_identity=identity,
)
payload = request.to_dict()
assert "observed_activation_identity" not in payload
assert payload["id"] == "run-1"
def test_cleanup_first_retirement_rejects_delayed_owner_commit() -> None:
registry = RuntimeActivationRegistry()
identity = registry.attach("claude", "runtime-1")
predicate_entered = threading.Event()
allow_retirement = threading.Event()
admission_started = threading.Event()
commit_called = threading.Event()
admission: list[RuntimeActivationCommit[str]] = []
retired: list[bool] = []
def final_predicate() -> bool:
predicate_entered.set()
assert allow_retirement.wait(timeout=2)
return True
def retire() -> None:
retired.append(registry.retire_if_current(identity, final_predicate))
def admit() -> None:
admission_started.set()
admission.append(
registry.commit_if_current(
identity,
lambda: commit_called.set() or "owner",
)
)
retirement_thread = threading.Thread(target=retire)
admission_thread = threading.Thread(target=admit)
retirement_thread.start()
assert predicate_entered.wait(timeout=2)
admission_thread.start()
assert admission_started.wait(timeout=2)
allow_retirement.set()
_join(retirement_thread)
_join(admission_thread)
assert retired == [True]
assert admission == [RuntimeActivationCommit(admitted=False)]
assert not commit_called.is_set()
def test_replacement_generation_rejects_old_identity() -> None:
registry = RuntimeActivationRegistry()
old_identity = registry.attach("codex", "/workspace")
current_identity = registry.attach("codex", "/workspace")
old_commit_called = False
def old_commit() -> None:
nonlocal old_commit_called
old_commit_called = True
old_result = registry.commit_if_current(old_identity, old_commit)
current_result = registry.commit_if_current(current_identity, lambda: "started")
assert old_result == RuntimeActivationCommit(admitted=False)
assert old_commit_called is False
assert current_result == RuntimeActivationCommit(admitted=True, value="started")
assert registry.current("codex", "/workspace") == current_identity
def test_retired_activation_targets_are_bounded_without_admitting_old_identity() -> None:
registry = RuntimeActivationRegistry()
oldest = registry.attach("codex", "/workspace/0")
assert registry.retire_if_current(oldest, lambda: True)
for index in range(1, 200):
identity = registry.attach("codex", f"/workspace/{index}")
assert registry.retire_if_current(identity, lambda: True)
commit = Mock(return_value="started")
assert not registry.commit_if_current(oldest, commit).admitted
commit.assert_not_called()
assert registry.tracked_target_count() == 0
assert registry.retired_diagnostic_count() <= 64
def test_retirement_reservation_rejects_admission_until_abort() -> None:
registry = RuntimeActivationRegistry()
identity = registry.attach("claude", "runtime-1")
reservation = registry.reserve_retirement(identity)
assert reservation is not None
rejected = Mock(return_value="owner")
assert not registry.commit_if_current(identity, rejected).admitted
rejected.assert_not_called()
assert registry.finish_retirement(reservation, retire=False)
admitted = registry.commit_if_current(identity, lambda: "owner")
assert admitted == RuntimeActivationCommit(admitted=True, value="owner")
def test_retirement_reservation_can_retire_and_release_registry_target() -> None:
registry = RuntimeActivationRegistry()
identity = registry.attach("claude", "runtime-1")
reservation = registry.reserve_retirement(identity)
assert reservation is not None
assert registry.finish_retirement(reservation, retire=True)
assert registry.current("claude", "runtime-1") is None
assert registry.current("claude", "runtime-1", include_retired=True) == identity
assert registry.tracked_target_count() == 0
def test_backend_binding_resolvers_use_exact_anchor_and_workdir() -> None:
registry = RuntimeActivationRegistry()
claude_identity = registry.attach("claude", "anchor:/work")
claude_client = SimpleNamespace(
_vibe_runtime_activation_identity=claude_identity,
_vibe_runtime_base_session_id="anchor",
_vibe_runtime_workdir="/work",
)
claude = object.__new__(ClaudeAgent)
claude.claude_sessions = {"opaque-runtime-key": claude_client}
assert claude.runtime_activation_identity_for_session_binding(
session_anchor="anchor",
workdir="/work",
) == claude_identity
assert claude.runtime_activation_identity_for_session_binding(
session_anchor="missing",
workdir=None,
) is None
with pytest.raises(ValueError, match="changed workdir"):
claude.runtime_activation_identity_for_session_binding(
session_anchor="anchor",
workdir="/other",
)
codex_identity = registry.attach("codex", "/work#1")
codex = init_generation_state(object.__new__(CodexAgent))
install_codex_transport(
codex, "/work", SimpleNamespace(), activation=codex_identity, sessions={"anchor": "thread"}
)
codex._session_mgr = SimpleNamespace(
get_cwd=lambda anchor: "/work" if anchor == "anchor" else None,
)
assert codex.runtime_activation_identity_for_session_binding(
session_anchor="anchor",
workdir="/work",
) == codex_identity
with pytest.raises(ValueError, match="changed workdir"):
codex.runtime_activation_identity_for_session_binding(
session_anchor="anchor",
workdir="/other",
)
def test_opencode_binding_resolver_follows_each_sessions_generation() -> None:
registry = RuntimeActivationRegistry()
def generation(generation_id: str, port: int) -> OpenCodeGeneration:
return OpenCodeGeneration(
generation_id=generation_id,
pid=fake_pid(port),
port=port,
spec_digest=generation_id,
process_created_at=1.0,
)
retiring = generation("ocg_old", 1)
current = generation("ocg_new", 2)
opencode = object.__new__(OpenCodeAgent)
opencode.controller = SimpleNamespace(runtime_activation=registry)
opencode._runtime = SimpleNamespace(current=lambda: current)
opencode._session_generations = {"anchor": retiring}
opencode._session_manager = SimpleNamespace(
get_request_session=lambda anchor: (
("", "/work", "route") if anchor == "anchor" else None
)
)
opencode._attach_generation_activation(retiring)
opencode._attach_generation_activation(current)
# A session's live turn commits against the process that runs it; any
# other session would start its next turn on the current generation.
assert retiring.identity != current.identity
assert opencode.runtime_activation_identity_for_session_binding(
session_anchor="anchor",
workdir="/work",
) == retiring.identity
assert opencode.runtime_activation_identity_for_request(
SimpleNamespace(base_session_id="anchor")
) == retiring.identity
assert opencode.runtime_activation_identity_for_session_binding(
session_anchor="other",
workdir="/work",
) == current.identity
with pytest.raises(ValueError, match="changed workdir"):
opencode.runtime_activation_identity_for_session_binding(
session_anchor="anchor",
workdir="/other",
)
asyncio.run(opencode._on_generation_stopping(retiring, False))
assert registry.commit_if_current(retiring.identity, lambda: "accepted") == RuntimeActivationCommit(
admitted=False
)
assert registry.is_current(current.identity)
def test_session_binding_lookup_failure_is_not_resource_absence() -> None:
service = object.__new__(AgentService)
service.agents = {
"codex": SimpleNamespace(
runtime_activation_identity_for_session_binding=lambda **_binding: (
(_ for _ in ()).throw(RuntimeError("lookup failed"))
)
)
}
resolution = service.runtime_activation_identity_for_session_binding(
"codex",
session_anchor="anchor",
workdir="/work",
)
assert resolution == RuntimeActivationResolution(authoritative=False)
def test_session_binding_lookup_for_an_unregistered_backend_is_resource_absence() -> None:
"""No registered agent means no runtime resource: a definite absence, as the
request lookup already answers it, never an inconclusive lookup to retry."""
service = object.__new__(AgentService)
service.agents = {}
binding = service.runtime_activation_identity_for_session_binding(
"codex",
session_anchor="anchor",
workdir="/work",
)
assert binding == RuntimeActivationResolution(authoritative=True)
assert binding == service.runtime_activation_identity_for_request(
"codex", SimpleNamespace(session_key="route:base")
)
def test_request_lookup_failure_is_not_resource_absence() -> None:
service = object.__new__(AgentService)
service.agents = {
"codex": SimpleNamespace(
runtime_activation_identity_for_request=lambda _request: (
(_ for _ in ()).throw(ValueError("ambiguous route"))
)
)
}
resolution = service.runtime_activation_identity_for_request(
"codex",
SimpleNamespace(session_key="route:base"),
)
assert resolution == RuntimeActivationResolution(authoritative=False)
def test_claude_request_route_resolution_distinguishes_absence_and_ambiguity() -> None:
registry = RuntimeActivationRegistry()
first_identity = registry.attach("claude", "runtime-main")
second_identity = registry.attach("claude", "runtime-routing")
claude = object.__new__(ClaudeAgent)
claude.claude_sessions = {}
request = SimpleNamespace(session_key="route:base")
assert claude.runtime_activation_identity_for_request(request) is None
claude.claude_sessions = {
"runtime-main": SimpleNamespace(
_vibe_runtime_activation_identity=first_identity,
_vibe_runtime_fallback_session_key="route:base",
)
}
assert claude.runtime_activation_identity_for_request(request) == first_identity
claude.claude_sessions["runtime-routing"] = SimpleNamespace(
_vibe_runtime_activation_identity=second_identity,
_vibe_runtime_fallback_session_key="route:base",
)
with pytest.raises(ValueError, match="ambiguous"):
claude.runtime_activation_identity_for_request(request)
def test_hfr_137_claude_ambiguous_route_blocks_fallback_claim() -> None:
registry = RuntimeActivationRegistry()
claude = object.__new__(ClaudeAgent)
claude.claude_sessions = {
"runtime-main": SimpleNamespace(
_vibe_runtime_activation_identity=registry.attach(
"claude", "runtime-main"
),
_vibe_runtime_fallback_session_key="route:base",
),
"runtime-routing": SimpleNamespace(
_vibe_runtime_activation_identity=registry.attach(
"claude", "runtime-routing"
),
_vibe_runtime_fallback_session_key="route:base",
),
}
controller = SimpleNamespace(runtime_activation=registry)
agent_service = AgentService(controller, activation_registry=registry)
agent_service.agents = {"claude": claude}
controller.agent_service = agent_service
request_store = SimpleNamespace(claim=Mock())
scheduled = object.__new__(ScheduledTaskService)
scheduled.controller = controller
scheduled.request_store = request_store
pending = TaskExecutionRequest(
id="run-route",
request_type="agent_run",
agent_backend="claude",
session_key="route:base",
)
assert scheduled._claim_pending_request(pending) is None
request_store.claim.assert_not_called()
def test_backend_without_activation_contract_has_no_runtime_resource() -> None:
service = object.__new__(AgentService)
service.agents = {"legacy": SimpleNamespace()}
resolution = service.runtime_activation_identity_for_request(
"legacy",
SimpleNamespace(session_key="route:base"),
)
assert resolution == RuntimeActivationResolution(
authoritative=True,
identity=None,
)
def test_fallback_claim_fails_closed_when_runtime_lookup_is_ambiguous() -> None:
registry = RuntimeActivationRegistry()
pending = TaskExecutionRequest(
id="run-ambiguous",
request_type="agent_run",
agent_backend="codex",
session_key="route:base",
)
request_store = SimpleNamespace(claim=Mock())
service = object.__new__(ScheduledTaskService)
service.controller = SimpleNamespace(
agent_service=SimpleNamespace(
agents={"codex": object()},
activation_registry=registry,
runtime_activation_identity_for_request=lambda _backend, _request: (
RuntimeActivationResolution(authoritative=False)
),
),
runtime_activation=registry,
)
service.request_store = request_store
assert service._claim_pending_request(pending) is None
request_store.claim.assert_not_called()
def test_hfr_137_codex_session_key_claim_observes_retired_generation() -> None:
"""HFR-137: legacy routes cannot bypass the exact Codex generation."""
registry = RuntimeActivationRegistry()
identity = registry.attach("codex", "/work#1")
codex = init_generation_state(object.__new__(CodexAgent))
install_codex_transport(codex, "/work", SimpleNamespace(), activation=identity, sessions={"base": "thread"})
codex._session_mgr = SimpleNamespace(
get_sessions_by_session_key=lambda _route: ["base"],
get_cwd=lambda _base: "/work",
)
controller = SimpleNamespace(runtime_activation=registry)
codex.controller = controller
agent_service = AgentService(
controller,
activation_registry=registry,
)
agent_service.agents = {"codex": codex}
controller.agent_service = agent_service
request_store = SimpleNamespace(claim=Mock())
scheduled = object.__new__(ScheduledTaskService)
scheduled.controller = controller
scheduled.request_store = request_store
pending = TaskExecutionRequest(
id="run-route",
request_type="agent_run",
agent_backend="codex",
session_key="route:base",
)
assert registry.retire_if_current(identity, lambda: True)
assert scheduled._claim_pending_request(pending) is None
request_store.claim.assert_not_called()
def test_hfr_137_legacy_agent_run_resolves_one_catalog_backend_before_probe() -> None:
"""HFR-137: a legacy Agent reference cannot become a multi-backend probe."""
registry = RuntimeActivationRegistry()
codex_identity = registry.attach("codex", "/work")
registry.attach("opencode", "session-1")
probes: list[str] = []
pending = TaskExecutionRequest(
id="run-custom-agent",
request_type="agent_run",
agent_id="agt-custom",
agent_name="reviewer",
)
def resolve(backend: str, _request: Any) -> RuntimeActivationResolution:
probes.append(backend)
if backend == "codex":
return RuntimeActivationResolution(
authoritative=True,
identity=codex_identity,
)
return RuntimeActivationResolution(
authoritative=True,
identity=registry.current("opencode", "session-1"),
)
request_store = SimpleNamespace(claim=Mock(return_value=pending))
scheduled = object.__new__(ScheduledTaskService)
scheduled.controller = SimpleNamespace(
vibe_agent_store=SimpleNamespace(
get_by_id=lambda agent_id: (
SimpleNamespace(backend="codex")
if agent_id == "agt-custom"
else None
),
get=lambda _name: pytest.fail("stable agent_id must win over its name"),
),
agent_service=SimpleNamespace(
agents={"codex": object(), "opencode": object()},
activation_registry=registry,
runtime_activation_identity_for_request=resolve,
),
runtime_activation=registry,
)
scheduled.request_store = request_store
claimed = scheduled._claim_pending_request(pending)
assert claimed is pending
assert pending.observed_activation_identity is codex_identity
assert probes == ["codex"]
request_store.claim.assert_called_once_with(pending.id)
class _ActivityStore:
def __init__(self) -> None:
self.upserts: list[tuple[dict[str, Any], str]] = []
def upsert_activity(self, activity: dict[str, Any], *, phase: str) -> None:
self.upserts.append((activity, phase))
def test_activity_registry_remains_compatible_without_activation_registry() -> None:
store = _ActivityStore()
activities = SessionActivityRegistry(store)
started = activities.start(
backend="claude",
runtime_key="runtime-1",
session_id="ses-1",
activity_id="task-1",
kind="background_task",
)
progressed = activities.progress(
backend="claude",
runtime_key="runtime-1",
session_id="ses-1",
activity_id="task-1",
description="Halfway",
)
assert started is not None
assert progressed is not None
assert progressed.description == "Halfway"
assert [phase for _, phase in store.upserts] == ["active", "active"]
@pytest.mark.parametrize("session_id", [None, "ses-1"])
def test_hfr_137_stale_activity_progress_cannot_rebuild_active_owner(
session_id: str | None,
) -> None:
activation_registry = RuntimeActivationRegistry()
old_identity = activation_registry.attach("claude", "runtime-1")
assert activation_registry.retire_if_current(old_identity, lambda: True)
current_identity = activation_registry.attach("claude", "runtime-1")
store = _ActivityStore()
activities = SessionActivityRegistry(
store,
activation_registry=activation_registry,
)
stale = activities.progress(
backend="claude",
runtime_key="runtime-1",
session_id=session_id,
activity_id="late-task",
description="Delayed receiver event",
activation_identity=old_identity,
)
assert stale is None
assert activities.has_active("claude", "runtime-1") is False
assert store.upserts == []
current = activities.start(
backend="claude",
runtime_key="runtime-1",
session_id=session_id,
activity_id="current-task",
kind="background_task",
activation_identity=current_identity,
)
assert current is not None
assert activities.has_active("claude", "runtime-1") is True
assert [phase for _, phase in store.upserts] == ["active"]
def test_hfr_137_stale_activity_completion_and_teardown_preserve_replacement() -> None:
"""HFR-137: only the exact receiver generation can settle its Activity."""
activation_registry = RuntimeActivationRegistry()
old_identity = activation_registry.attach("claude", "runtime-1")
store = _ActivityStore()
activities = SessionActivityRegistry(
store,
activation_registry=activation_registry,
)
assert activities.set_connection(
backend="claude",
runtime_key="runtime-1",
session_id="ses-1",
state="connected",
activation_identity=old_identity,
)
assert activities.start(
backend="claude",
runtime_key="runtime-1",
session_id="ses-1",
activity_id="task-1",
kind="background_task",
activation_identity=old_identity,
)
current_identity = activation_registry.attach("claude", "runtime-1")
assert activities.set_connection(
backend="claude",
runtime_key="runtime-1",
session_id="ses-1",
state="connected",
activation_identity=current_identity,
)
assert activities.progress(
backend="claude",
runtime_key="runtime-1",
session_id="ses-1",
activity_id="task-1",
description="Replacement owns progress",
activation_identity=current_identity,
)
stale = activities.complete(
backend="claude",
runtime_key="runtime-1",
activity_id="task-1",
status="completed",
expects_output=True,
activation_identity=old_identity,
)
stale_teardown = activities.end_runtime(
"claude",
"runtime-1",
activation_identity=old_identity,
retain_terminal_snapshots=True,
)
assert stale is None
assert stale_teardown == []
assert activities.has_active("claude", "runtime-1") is True
assert activities.session_state("ses-1")["connection"] == "connected"
completed = activities.complete(
backend="claude",
runtime_key="runtime-1",
activity_id="task-1",
status="completed",
expects_output=True,
activation_identity=current_identity,
)
assert completed is not None
assert activities.has_active("claude", "runtime-1") is False
def test_configured_activity_registry_requires_matching_activation_identity() -> None:
activation_registry = RuntimeActivationRegistry()
identity = activation_registry.attach("claude", "runtime-1")
store = _ActivityStore()
activities = SessionActivityRegistry(
store,
activation_registry=activation_registry,
)
missing = activities.start(
backend="claude",
runtime_key="runtime-1",
session_id=None,
activity_id="missing",
kind="background_task",
)
mismatched = activities.start(
backend="codex",
runtime_key="runtime-1",
session_id=None,
activity_id="mismatched",
kind="background_task",
activation_identity=identity,
)
assert missing is None
assert mismatched is None
assert store.upserts == []
class _NativeStartManager:
def __init__(self) -> None:
self.calls: list[tuple[str, str, str]] = []
self.entered = threading.Event()
self.allow_commit = threading.Event()
def on_native_start(
self,
_context: Any,
*,
backend: str,
runtime_key: str,
runtime_turn_id: str,
) -> None:
self.entered.set()
assert self.allow_commit.wait(timeout=2)
self.calls.append((backend, runtime_key, runtime_turn_id))
def _native_start_service(
registry: RuntimeActivationRegistry,
) -> tuple[AgentService, _NativeStartManager, Any]:
manager = _NativeStartManager()
controller = SimpleNamespace(session_turns=manager)
service = AgentService(controller, activation_registry=registry)
context = SimpleNamespace(
platform_specific={
AGENT_RUNTIME_TURN_KEY: "runtime-1",
AGENT_RUNTIME_TURN_TOKEN: "turn-1",
}
)
gate = service._get_turn_gate("runtime-1")
gate.token = "turn-1"
gate.backend = "claude"
gate.context = context
return service, manager, context
def test_hfr_137_native_start_admission_first_blocks_retirement_until_durable_commit() -> None:
registry = RuntimeActivationRegistry()
identity = registry.attach("claude", "resource-1")
service, manager, context = _native_start_service(registry)
retirement_started = threading.Event()
retired: list[bool] = []
admission_thread = threading.Thread(
target=lambda: service.mark_runtime_turn_started(
context,
activation_identity=identity,
)
)
def retire() -> None:
retirement_started.set()
retired.append(registry.retire_if_current(identity, lambda: True))
retirement_thread = threading.Thread(target=retire)
admission_thread.start()
assert manager.entered.wait(timeout=2)
retirement_thread.start()
assert retirement_started.wait(timeout=2)
manager.allow_commit.set()
_join(admission_thread)
_join(retirement_thread)
assert manager.calls == [("claude", "runtime-1", "turn-1")]
assert retired == [True]
assert service._get_turn_gate("runtime-1").runtime_started is True
def test_hfr_137_native_start_cleanup_first_rejects_old_generation_commit() -> None:
registry = RuntimeActivationRegistry()
identity = registry.attach("claude", "resource-1")
service, manager, context = _native_start_service(registry)
predicate_entered = threading.Event()
allow_retirement = threading.Event()
admission_started = threading.Event()
def final_predicate() -> bool:
predicate_entered.set()
assert allow_retirement.wait(timeout=2)
return True
retirement_thread = threading.Thread(
target=lambda: registry.retire_if_current(identity, final_predicate)
)
def admit() -> None:
admission_started.set()
service.mark_runtime_turn_started(context, activation_identity=identity)
admission_thread = threading.Thread(target=admit)
retirement_thread.start()
assert predicate_entered.wait(timeout=2)
admission_thread.start()
assert admission_started.wait(timeout=2)
allow_retirement.set()
_join(retirement_thread)
_join(admission_thread)
assert manager.calls == []
assert service._get_turn_gate("runtime-1").runtime_started is False
@pytest.mark.parametrize("session_id", [None, "ses-1"])
def test_hfr_137_claude_receiver_forwards_generation_to_activity_admission(
session_id: str | None,
) -> None:
activation_registry = RuntimeActivationRegistry()
old_identity = activation_registry.attach("claude", "runtime-1")
assert activation_registry.retire_if_current(old_identity, lambda: True)
store = _ActivityStore()
activities = SessionActivityRegistry(
store,
activation_registry=activation_registry,
)
activity_service = SimpleNamespace(activities=activities)
session_handler = SimpleNamespace(
mark_session_active=lambda _runtime_key: pytest.fail(
"stale Activity marked the runtime active"
),
touch_session_activity=lambda _runtime_key: pytest.fail(
"stale Activity refreshed the runtime baseline"
),
)
agent = object.__new__(ClaudeAgent)
agent.controller = SimpleNamespace(agent_service=activity_service)
agent.session_handler = session_handler
agent._pending_requests = {}
agent._detached_foreground_tool_use_ids = {}
agent._detached_foreground_task_ids = {}
agent._foreground_tool_use_ids = {}
context = SimpleNamespace(
platform_specific={"agent_session_id": session_id} if session_id else {}
)
message = SimpleNamespace(
subtype="task_started",
task_id="late-task",
task_type="background_task",
description="Delayed receiver event",
)
handled = agent._handle_activity_message(
message,
"runtime-1",
context,
activation_identity=old_identity,
)
assert handled is True
assert activities.has_active("claude", "runtime-1") is False
assert store.upserts == []
def _fallback_service(
registry: RuntimeActivationRegistry,
request_store: Any,
identity: Any,
*,
backend_ready: bool = True,
) -> ScheduledTaskService:
agent_service = SimpleNamespace(
activation_registry=registry,
agents={"claude": object()},
is_backend_ready=lambda _backend: backend_ready,
runtime_activation_identity_for_request=lambda backend, request: (
identity if backend == "claude" else None
),
)
service = object.__new__(ScheduledTaskService)
service.controller = SimpleNamespace(
agent_service=agent_service,
runtime_activation=registry,
)
service.request_store = request_store
return service
def test_hfr_137_cleanup_first_rejects_fallback_claim() -> None:
"""HFR-137: a retired generation cannot turn its queued Run into a claim."""
registry = RuntimeActivationRegistry()
identity = registry.attach("claude", "runtime-1")
predicate_entered = threading.Event()
allow_retirement = threading.Event()
admission_started = threading.Event()
claim_calls: list[str] = []
claims: list[TaskExecutionRequest | None] = []
pending = TaskExecutionRequest(
id="run-1",
request_type="agent_run",
agent_backend="claude",
)
request_store = SimpleNamespace(
claim=lambda request_id: claim_calls.append(request_id) or pending,
)
service = _fallback_service(registry, request_store, identity)
def retire() -> None:
def final_predicate() -> bool:
predicate_entered.set()
assert allow_retirement.wait(timeout=2)
return True
assert registry.retire_if_current(identity, final_predicate)
def claim() -> None:
admission_started.set()
claims.append(service._claim_pending_request(pending))
retirement_thread = threading.Thread(target=retire)
claim_thread = threading.Thread(target=claim)
retirement_thread.start()
assert predicate_entered.wait(timeout=2)
claim_thread.start()
assert admission_started.wait(timeout=2)
allow_retirement.set()
_join(retirement_thread)
_join(claim_thread)
assert claims == [None]
assert claim_calls == []
def test_hfr_137_claim_that_loses_to_cleanup_during_its_write_is_given_back() -> None:
"""HFR-137, #2655: a claim writes with no boundary held, so a cleanup that starts meanwhile retires the generation
at once instead of waiting for the write. The claim, confirmed after it lands, finds its generation retired and is
given back to the queue, so nothing ever starts on the retired generation."""
registry = RuntimeActivationRegistry()
identity = registry.attach("claude", "runtime-1")
claim_entered = threading.Event()
allow_claim = threading.Event()
pending = TaskExecutionRequest(
id="run-1",
request_type="agent_run",
agent_backend="claude",
)
claimed_request = TaskExecutionRequest(
id=pending.id,
request_type=pending.request_type,
agent_backend=pending.agent_backend,
)
requeued: list[str] = []
def claim(_request_id: str) -> TaskExecutionRequest:
claim_entered.set()
assert allow_claim.wait(timeout=2)
return claimed_request
request_store = SimpleNamespace(
claim=claim,
requeue=lambda request_id: requeued.append(request_id),
)
service = _fallback_service(registry, request_store, identity)
claims: list[TaskExecutionRequest | None] = []
retired: list[bool] = []
claim_thread = threading.Thread(
target=lambda: claims.append(service._claim_pending_request(pending))
)
retirement_thread = threading.Thread(
target=lambda: retired.append(registry.retire_if_current(identity, lambda: True))
)
claim_thread.start()
assert claim_entered.wait(timeout=2)
retirement_thread.start()
# The cleanup does not wait for the claim's write.
_join(retirement_thread)
assert retired == [True]
allow_claim.set()
_join(claim_thread)
assert claims == [None]
assert requeued == [pending.id]
def test_hfr_137_backend_drain_rejects_fallback_claim() -> None:
"""HFR-137: a draining backend cannot acquire a fallback Run claim."""
registry = RuntimeActivationRegistry()
identity = registry.attach("claude", "runtime-1")
pending = TaskExecutionRequest(
id="run-1",
request_type="agent_run",
agent_backend="claude",
)
claim_calls: list[str] = []
request_store = SimpleNamespace(
claim=lambda request_id: claim_calls.append(request_id) or pending,
)
service = _fallback_service(
registry,
request_store,
identity,
backend_ready=False,
)
assert service._claim_pending_request(pending) is None
assert claim_calls == []
def test_hfr_137_backend_drain_requeues_existing_pre_pid_claim() -> None:
"""HFR-137: a pre-PID claim never waits on the drain it would pin."""
registry = RuntimeActivationRegistry()
identity = registry.attach("claude", "runtime-1")
requeued: list[str] = []
request = TaskExecutionRequest(
id="run-1",
request_type="agent_run",
agent_backend="claude",
observed_activation_identity=identity,
)
request_store = SimpleNamespace(
refresh_claimed_request=lambda current: current,
mark_execution_started=lambda _request_id: pytest.fail("draining claim started"),
requeue=lambda request_id: requeued.append(request_id),
)
service = _fallback_service(
registry,
request_store,
identity,
backend_ready=False,
)
marked_request, started = asyncio.run(
service._mark_execution_started_for_claimed_request(request)
)
assert marked_request is request
assert started is False
assert requeued == [request.id]
def test_hfr_137_pid_marker_that_loses_to_cleanup_during_its_write_is_requeued() -> None:
"""HFR-137, #2655: the start marker writes with no boundary held, so a cleanup that starts meanwhile retires the
generation at once instead of waiting for the write. The start, confirmed after the marker lands, finds its
generation retired: the execution does not start, and the claim goes back to the queue, marker cleared."""
registry = RuntimeActivationRegistry()
identity = registry.attach("claude", "runtime-1")
marker_entered = threading.Event()
allow_marker = threading.Event()
request = TaskExecutionRequest(
id="run-1",
request_type="agent_run",
agent_backend="claude",
observed_activation_identity=identity,
)
requeued: list[str] = []
def mark_execution_started(_request_id: str) -> bool:
marker_entered.set()
assert allow_marker.wait(timeout=2)
return True
request_store = SimpleNamespace(
refresh_claimed_request=lambda current: current,
mark_execution_started=mark_execution_started,
requeue=lambda request_id: requeued.append(request_id),
)
service = _fallback_service(registry, request_store, identity)
marked: list[tuple[TaskExecutionRequest, bool]] = []
retired: list[bool] = []
marker_thread = threading.Thread(
target=lambda: marked.append(
asyncio.run(service._mark_execution_started_for_claimed_request(request))
)
)
retirement_thread = threading.Thread(
target=lambda: retired.append(registry.retire_if_current(identity, lambda: True))
)
marker_thread.start()
assert marker_entered.wait(timeout=2)
retirement_thread.start()
# The cleanup does not wait for the marker's write.
_join(retirement_thread)
assert retired == [True]
allow_marker.set()
_join(marker_thread)
assert marked == [(request, False)]
assert requeued == [request.id]
def test_a_claim_waiting_for_the_sqlite_writer_never_holds_the_boundary_the_loop_needs(tmp_path) -> None:
"""#2655: the scheduler claims off the loop, and its claim waits for SQLite's writer. The loop admits Session Turns
inside a transaction that already holds the writer, and only then takes the activation boundary. A claim that held
the boundary while it waited for the writer would make the loop wait for SQLite's busy timeout. It never holds it
there, so the loop takes the boundary at once, and the claim lands when the loop's transaction ends."""
db_path = tmp_path / "state.sqlite"
with closing(sqlite3.connect(db_path)) as setup:
setup.execute("CREATE TABLE claims (run_id TEXT)")
setup.commit()
registry = RuntimeActivationRegistry()
identity = registry.attach("claude", "runtime-1")
pending = TaskExecutionRequest(id="run-1", request_type="agent_run", agent_backend="claude")
claim_writing = threading.Event()
def claim(request_id: str) -> TaskExecutionRequest:
with closing(sqlite3.connect(db_path, timeout=2)) as conn:
claim_writing.set()
conn.execute("BEGIN IMMEDIATE")
conn.execute("INSERT INTO claims VALUES (?)", (request_id,))
conn.commit()
return pending
request_store = SimpleNamespace(
claim=claim,
requeue=lambda _request_id: pytest.fail("a claim made on a live generation was given back"),
)
service = _fallback_service(registry, request_store, identity)
claims: list[TaskExecutionRequest | None] = []
errors: list[BaseException] = []
def run_claim() -> None:
try:
claims.append(service._claim_pending_request(pending))
except Exception as exc:
errors.append(exc)
with closing(sqlite3.connect(db_path, timeout=2)) as loop_transaction:
loop_transaction.execute("BEGIN IMMEDIATE")
claim_thread = threading.Thread(target=run_claim)
claim_thread.start()
assert claim_writing.wait(timeout=2)
time.sleep(0.1) # the claim now waits for the writer this transaction holds
started = time.monotonic()
with registry.hold_if_current(identity) as admitted:
waited = time.monotonic() - started
loop_transaction.commit()
_join(claim_thread)
assert waited < 0.05, f"the loop waited {waited:.2f}s on a claim that held the boundary while waiting for SQLite"
assert admitted is True
assert errors == []
assert claims == [pending]
def test_a_claim_confirmed_before_a_graceful_cleanup_keeps_its_generation() -> None:
"""#2655: a claim confirmed while its generation was live stands. A graceful cleanup whose final snapshot sees the
claimed Run as an owner declines, and the Run then starts on that generation."""
registry = RuntimeActivationRegistry()
identity = registry.attach("claude", "runtime-1")
pending = TaskExecutionRequest(id="run-1", request_type="agent_run", agent_backend="claude")
owners: set[str] = set()
request_store = SimpleNamespace(
claim=lambda request_id: owners.add(request_id) or pending,
refresh_claimed_request=lambda current: current,
mark_execution_started=lambda _request_id: True,
requeue=lambda _request_id: pytest.fail("a confirmed claim was given back"),
)
service = _fallback_service(registry, request_store, identity)
claimed = service._claim_pending_request(pending)
assert claimed is pending
assert registry.retire_if_current(identity, lambda: not owners) is False
assert asyncio.run(service._mark_execution_started_for_claimed_request(claimed)) == (claimed, True)
def _sqlite_request_store(tmp_path, monkeypatch) -> tuple[TaskExecutionStore, TaskExecutionRequest]:
monkeypatch.setenv("AVIBE_HOME", str(tmp_path))
request_store = TaskExecutionStore()
queued = request_store.enqueue_agent_run(message="run", agent_backend="claude", session_id="ses-runtime")
return request_store, queued
def _failing_requeue(_request_id: str) -> None:
raise sqlite3.OperationalError("database is locked")
def test_a_claim_whose_give_back_fails_starts_nothing_and_is_requeued_by_recovery(
tmp_path, monkeypatch, caplog
) -> None:
"""#2655: a claim that lost to a cleanup is given back to the queue. When that write fails too, the claim is still
refused, so nothing starts on the retired generation, and the failure is logged. The claim it left has no start
marker, so the claimed-run recovery puts the Run back in the queue, to run again."""
request_store, queued = _sqlite_request_store(tmp_path, monkeypatch)
registry = RuntimeActivationRegistry()
identity = registry.attach("claude", "runtime-1")
def claim_while_cleanup_lands(request_id: str) -> TaskExecutionRequest | None:
assert registry.retire_if_current(identity, lambda: True)
return request_store.claim(request_id)
service = _fallback_service(
registry,
SimpleNamespace(claim=claim_while_cleanup_lands, requeue=_failing_requeue),
identity,
)
with caplog.at_level(logging.ERROR, logger="core.runtime_activation"):
assert service._claim_pending_request(queued) is None
assert "lost to the retirement of claude" in caplog.text
left = request_store.get_run(queued.id)
assert left["status"] == "running" and left["pid"] is None
recovery = FallbackRequestRecoveryHandler(request_store.sqlite_backend)
items, _has_more = recovery.scan(limit=10, occupied=frozenset())
assert [recovery.process_sync(item) for item in items] == [True]
assert request_store.get_run(queued.id)["status"] == "queued"
def test_a_start_whose_give_back_fails_never_runs_and_settles_as_interrupted(tmp_path, monkeypatch) -> None:
"""#2655: a start marker that lost to a cleanup is cleared by giving the claim back. When that write fails too, the
execution never starts. The marker it left reads, to recovery, as an execution that may have begun, so recovery
settles the Run as interrupted, with its failure notice, rather than running it again: the cost of a failed write
racing a retirement, which only a persisted generation could undo (see the design note)."""
request_store, queued = _sqlite_request_store(tmp_path, monkeypatch)
registry = RuntimeActivationRegistry()
identity = registry.attach("claude", "runtime-1")
claimed = request_store.claim(queued.id)
assert claimed is not None
claimed.observed_activation_identity = identity
def mark_while_cleanup_lands(request_id: str) -> bool:
assert registry.retire_if_current(identity, lambda: True)
return request_store.mark_execution_started(request_id)
service = _fallback_service(
registry,
SimpleNamespace(
refresh_claimed_request=lambda current: current,
mark_execution_started=mark_while_cleanup_lands,
requeue=_failing_requeue,
),
identity,
)
with pytest.raises(sqlite3.OperationalError):
asyncio.run(service._mark_execution_started_for_claimed_request(claimed))
assert request_store.get_run(queued.id)["pid"] is not None
request_store.recover_processing()
settled = request_store.get_run(queued.id)
assert settled["status"] == "failed" and settled["pid"] is None
def test_a_boundary_held_off_the_loop_thread_is_reported_with_its_caller(caplog) -> None:
"""#2655: off the controller loop thread, ``commit_if_current`` and ``hold_if_current`` would hold the boundary
across their commit's I/O while the loop takes it synchronously. Such a call is logged as an error naming its
caller, so a new off-loop holder cannot bring the loop stall back unnoticed."""
registry = RuntimeActivationRegistry()
identity = registry.attach("claude", "runtime-1")
registry.bind_loop_thread() # this thread plays the controller loop
def holder_on_a_worker_commits() -> None:
registry.commit_if_current(identity, lambda: None)
def holder_on_a_worker_holds() -> None:
with registry.hold_if_current(identity):
pass
with caplog.at_level(logging.ERROR, logger="core.runtime_activation"):
registry.commit_if_current(identity, lambda: None)
with registry.hold_if_current(identity):
pass
assert not caplog.records, "a holder on the loop thread was reported"
for target in (holder_on_a_worker_commits, holder_on_a_worker_holds):
worker = threading.Thread(target=target)
worker.start()
_join(worker)
reports = [record.getMessage() for record in caplog.records if record.levelno == logging.ERROR]
assert len(reports) == 2
assert "commit_if_current" in reports[0] and "in holder_on_a_worker_commits" in reports[0]
assert "hold_if_current" in reports[1] and "in holder_on_a_worker_holds" in reports[1]