feat: add global device queue and readiness tracking

tests/unit/runtime/test_awake_lease.py

@@ -0,0 +1,128 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+
+import pytest
+
+from artemis.runtime.awake_lease import ScreenAwakeLease
+
+
+@pytest.fixture(autouse=True)
+def isolated_awake_directory(tmp_path, monkeypatch):
+    monkeypatch.setattr(
+        "artemis.runtime.awake_lease.get_temp_dir",
+        lambda _name: tmp_path,
+    )
+
+
+def test_first_lease_drains_legacy_references_and_acquires_exactly_one(monkeypatch):
+    lease = ScreenAwakeLease("device-123")
+    count = 3
+
+    def state():
+        return (count > 0, count)
+
+    def set_lock(action):
+        nonlocal count
+        count += 1 if action == "acquire" else -1
+        return True
+
+    monkeypatch.setattr(lease, "_wake_lock_state", state)
+    monkeypatch.setattr(lease, "_set_wake_lock", set_lock)
+
+    assert lease.acquire()
+    assert count == 1
+    assert lease.lease_path.exists()
+
+    lease.release()
+    assert count == 0
+
+
+def test_overlapping_clients_share_one_android_reference(monkeypatch):
+    first = ScreenAwakeLease("device-123")
+    second = ScreenAwakeLease("device-123")
+    count = 0
+
+    def state():
+        return (count > 0, count)
+
+    def set_lock(action):
+        nonlocal count
+        count += 1 if action == "acquire" else -1
+        return True
+
+    for lease in (first, second):
+        monkeypatch.setattr(lease, "_wake_lock_state", state)
+        monkeypatch.setattr(lease, "_set_wake_lock", set_lock)
+
+    assert first.acquire()
+    assert second.acquire()
+    assert count == 1
+
+    first.release()
+    assert count == 1
+    second.release()
+    assert count == 0
+
+
+def test_crashed_client_is_pruned_and_legacy_reference_is_recovered(monkeypatch):
+    crashed = ScreenAwakeLease("device-123")
+    crashed.lease_dir.mkdir(parents=True, exist_ok=True)
+    crashed.lease_path.write_text(
+        json.dumps(
+            {
+                "pid": 999999,
+                "process_created_at": 1.0,
+                "token": crashed.token,
+                "device_id": "device-123",
+            }
+        ),
+        encoding="utf-8",
+    )
+    replacement = ScreenAwakeLease("device-123")
+    count = 1
+
+    def state():
+        return (count > 0, count)
+
+    def set_lock(action):
+        nonlocal count
+        count += 1 if action == "acquire" else -1
+        return True
+
+    monkeypatch.setattr(replacement, "_wake_lock_state", state)
+    monkeypatch.setattr(replacement, "_set_wake_lock", set_lock)
+    monkeypatch.setattr(
+        ScreenAwakeLease,
+        "_owner_is_alive",
+        staticmethod(lambda payload: int(payload["pid"]) != 999999),
+    )
+
+    assert replacement.acquire()
+    assert not crashed.lease_path.exists()
+    assert count == 1
+
+    replacement.release()
+    assert count == 0
+
+
+def test_migration_cleanup_never_drains_a_live_legacy_owner(monkeypatch):
+    owner = ScreenAwakeLease("device-123")
+    owner.lease_dir.mkdir(parents=True, exist_ok=True)
+    owner.lease_path.write_text(json.dumps(owner._payload()), encoding="utf-8")
+    cleanup = ScreenAwakeLease("device-123")
+    cleanup._drain_references = lambda: pytest.fail("must not drain a live owner")
+
+    assert cleanup.cleanup_unowned_references() is False

tests/unit/runtime/test_awake_service.py

@@ -0,0 +1,166 @@
+from unittest.mock import MagicMock, patch
+
+from artemis.runtime.awake_service import (
+    AWAKE_STRATEGY_HEARTBEAT,
+    AWAKE_STRATEGY_USB,
+    ScreenAwakeService,
+    _configure_usb_stay_awake,
+    _discover_connected_device_ids,
+)
+
+
+def completed(stdout="", returncode=0, stderr=""):
+    return MagicMock(returncode=returncode, stdout=stdout, stderr=stderr)
+
+
+@patch("artemis.runtime.awake_service.ScreenAwakeLease")
+@patch("artemis.runtime.awake_service.subprocess.run")
+def test_usb_policy_is_primary_when_android_reports_it_active(mock_run, lease_type):
+    mock_run.side_effect = [
+        completed(),
+        completed(),
+        completed(),
+        completed("2\n"),
+        completed("  mIsPowered=true\n  mPlugType=2\n  mStayOn=true\n"),
+    ]
+
+    assert _configure_usb_stay_awake("device-123") == AWAKE_STRATEGY_USB
+
+    lease_type.assert_called_once_with("device-123")
+    lease_type.return_value.cleanup_unowned_references.assert_called_once_with()
+    commands = [call.args[0] for call in mock_run.call_args_list]
+    assert ["shell", "svc", "power", "stayon", "usb"] in [command[3:] for command in commands]
+    assert not any("SCREEN_BRIGHT_WAKE_LOCK" in command for command in commands)
+    assert not any("KEYCODE_UNKNOWN" in command for command in commands)
+
+
+@patch("artemis.runtime.awake_service.ScreenAwakeLease")
+@patch("artemis.runtime.awake_service.subprocess.run")
+def test_inactive_usb_policy_falls_back_to_effective_host_heartbeat(mock_run, _lease_type):
+    mock_run.side_effect = [
+        completed(),
+        completed(),
+        completed(),
+        completed("2\n"),
+        completed("  mIsPowered=true\n  mPlugType=2\n  mStayOn=false\n"),
+        completed(),
+    ]
+
+    assert _configure_usb_stay_awake("device-123") == AWAKE_STRATEGY_HEARTBEAT
+
+    assert mock_run.call_args_list[-1].args[0][-1] == "KEYCODE_UNKNOWN"
+
+
+@patch.dict("os.environ", {"ARTEMIS_KEEP_DEVICE_AWAKE": "false"})
+@patch("artemis.runtime.awake_service.subprocess.run")
+def test_awake_strategy_can_be_disabled(mock_run):
+    assert _configure_usb_stay_awake("device-123") is None
+    mock_run.assert_not_called()
+
+
+@patch("artemis.runtime.awake_service.threading.Thread")
+@patch("artemis.runtime.awake_service.threading.Event")
+@patch(
+    "artemis.runtime.awake_service._configure_usb_stay_awake",
+    return_value=AWAKE_STRATEGY_HEARTBEAT,
+)
+def test_host_heartbeat_lives_until_host_shutdown(configure, event_type, thread_type):
+    service = ScreenAwakeService()
+    stop_event = event_type.return_value
+    thread = thread_type.return_value
+
+    service.ensure_device("device-123")
+    service.ensure_device("device-123")
+
+    configure.assert_called_once_with("device-123")
+    thread.start.assert_called_once_with()
+    stop_event.set.assert_not_called()
+
+    service.shutdown()
+    service.shutdown()
+
+    stop_event.set.assert_called_once_with()
+    thread.join.assert_called_once_with(timeout=2.0)
+
+
+@patch("artemis.runtime.awake_service._run_awake_adb_command")
+@patch("artemis.runtime.awake_service.threading.Thread")
+@patch("artemis.runtime.awake_service.threading.Event")
+@patch(
+    "artemis.runtime.awake_service._configure_usb_stay_awake",
+    return_value=AWAKE_STRATEGY_HEARTBEAT,
+)
+def test_heartbeat_loop_uses_verified_user_activity_key(
+    _configure, event_type, thread_type, run_command
+):
+    stop_event = event_type.return_value
+    stop_event.wait.side_effect = [False, True]
+    service = ScreenAwakeService()
+
+    service.ensure_device("device-123")
+    heartbeat_target = thread_type.call_args.kwargs["target"]
+    heartbeat_target()
+
+    run_command.assert_called_once_with(
+        "device-123",
+        ["shell", "input", "keyevent", "KEYCODE_UNKNOWN"],
+        "send the host stay-awake heartbeat",
+    )
+
+
+@patch("artemis.runtime.awake_service.threading.Thread")
+@patch("artemis.runtime.awake_service.threading.Event")
+@patch("artemis.runtime.awake_service._discover_connected_device_ids")
+@patch(
+    "artemis.runtime.awake_service._configure_usb_stay_awake",
+    return_value=AWAKE_STRATEGY_USB,
+)
+def test_service_monitor_enrolls_a_device_attached_after_start(
+    configure, discover, event_type, thread_type
+):
+    discover.side_effect = [[], ["device-late"]]
+    stop_event = event_type.return_value
+    stop_event.wait.side_effect = [False, True]
+    stop_event.is_set.return_value = False
+    service = ScreenAwakeService()
+
+    service.start()
+    monitor_target = thread_type.call_args.kwargs["target"]
+    monitor_target()
+
+    configure.assert_called_once_with("device-late")
+    assert service.device_ids == ("device-late",)
+
+
+@patch("artemis.runtime.awake_service.threading.Thread")
+@patch("artemis.runtime.awake_service.threading.Event")
+@patch(
+    "artemis.runtime.awake_service._configure_usb_stay_awake",
+    return_value=AWAKE_STRATEGY_HEARTBEAT,
+)
+def test_disconnect_reconciliation_stops_heartbeat_and_allows_reenrollment(
+    configure, event_type, thread_type
+):
+    service = ScreenAwakeService()
+    stop_event = event_type.return_value
+    thread = thread_type.return_value
+    service.ensure_device("device-123")
+
+    service._reconcile_connected_devices(set())
+
+    stop_event.set.assert_called_once_with()
+    thread.join.assert_called_once_with(timeout=2.0)
+    assert service.device_ids == ()
+
+    service.ensure_device("device-123")
+    assert configure.call_count == 2
+
+
+@patch("artemis.runtime.awake_service.AdbClient")
+def test_discovery_honors_single_device_policy(adb_client):
+    adb_client.return_value.device_list.return_value = [
+        MagicMock(serial="device-1"),
+        MagicMock(serial="device-2"),
+    ]
+
+    assert _discover_connected_device_ids() == ["device-1"]

tests/unit/runtime/test_device_lock.py

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 import json
+import threading
+import time
 
 import pytest
 
@@ -34,7 +36,7 @@ def test_device_lock_blocks_a_second_process_owner():
     first.acquire()
     try:
         with pytest.raises(DeviceBusyError, match="first task"):
-            second.acquire()
+            second.acquire(blocking=False)
     finally:
         first.release()
 
@@ -79,9 +81,9 @@ def test_device_lock_release_does_not_remove_replacement_owner():
 
 def test_cleanup_stale_locks_keeps_live_owner(monkeypatch):
     live = DeviceExecutionLock("emulator-5554", "live task")
-    stale = DeviceExecutionLock("physical-device", "stale task")
     live.acquire()
-    stale.path.write_text(
+    stale_path = live.path.parent / "stale-device.lock"
+    stale_path.write_text(
         json.dumps(
             {
                 "pid": 999999,
@@ -105,6 +107,123 @@ def test_cleanup_stale_locks_keeps_live_owner(monkeypatch):
     try:
         assert DeviceExecutionLock.cleanup_stale_locks() == 1
         assert live.path.exists()
-        assert not stale.path.exists()
+        assert not stale_path.exists()
     finally:
         live.release()
+
+
+def test_device_lock_waits_and_runs_next_owner_in_fifo_order():
+    first = DeviceExecutionLock("emulator-5554", "first task")
+    second = DeviceExecutionLock("emulator-5554", "second task")
+    acquired = threading.Event()
+
+    first.acquire()
+
+    def acquire_second():
+        second.acquire()
+        acquired.set()
+
+    thread = threading.Thread(target=acquire_second)
+    thread.start()
+    time.sleep(0.15)
+    assert not acquired.is_set()
+
+    first.release()
+    assert acquired.wait(timeout=2.0)
+    second.release()
+    thread.join(timeout=2.0)
+
+
+def test_submission_reservations_preserve_order_before_workers_start():
+    first_ticket = DeviceExecutionLock.reserve("first submitted task")
+    second_ticket = DeviceExecutionLock.reserve("second submitted task")
+    second = DeviceExecutionLock("emulator-5554", "second task", second_ticket)
+    second_acquired = threading.Event()
+
+    def acquire_second():
+        second.acquire()
+        second_acquired.set()
+
+    thread = threading.Thread(target=acquire_second)
+    thread.start()
+    time.sleep(0.15)
+    assert not second_acquired.is_set()
+
+    first = DeviceExecutionLock("emulator-5554", "first task", first_ticket)
+    first.acquire()
+    first.release()
+
+    assert second_acquired.wait(timeout=2.0)
+    second.release()
+    thread.join(timeout=2.0)
+
+
+def test_cancelled_reservation_cannot_execute():
+    ticket = DeviceExecutionLock.reserve("cancelled task")
+    assert DeviceExecutionLock.cancel_reservation(ticket)
+
+    lock = DeviceExecutionLock("emulator-5554", "cancelled task", ticket)
+    with pytest.raises(DeviceBusyError, match="cancelled or expired"):
+        lock.acquire()
+
+
+def test_reservation_can_be_transferred_to_worker_process():
+    ticket = DeviceExecutionLock.reserve("submitted task")
+
+    assert DeviceExecutionLock.transfer_reservation(ticket, 4242, description="worker task")
+
+    path = next((DeviceExecutionLock("device").queue_dir).glob(f"*-{ticket}.wait"))
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    assert payload["pid"] == 4242
+    assert payload["description"] == "worker task"
+
+
+def test_waiting_acquire_can_be_cancelled_without_leaving_a_ticket():
+    owner = DeviceExecutionLock("emulator-5554", "owner")
+    waiter = DeviceExecutionLock("emulator-5554", "waiter")
+    cancel_event = threading.Event()
+    errors = []
+    owner.acquire()
+
+    def wait_for_device():
+        try:
+            waiter.acquire(cancel_event=cancel_event)
+        except DeviceBusyError as exc:
+            errors.append(str(exc))
+
+    thread = threading.Thread(target=wait_for_device)
+    thread.start()
+    time.sleep(0.15)
+    cancel_event.set()
+    thread.join(timeout=2.0)
+
+    try:
+        assert errors == ["Waiting for the Artemis device queue was cancelled."]
+        assert list(waiter.queue_dir.glob("*.wait")) == []
+    finally:
+        owner.release()
+
+
+def test_active_owner_is_discoverable_and_can_be_annotated(monkeypatch):
+    monkeypatch.setenv("ARTEMIS_TASK_INGRESS", "cli")
+    monkeypatch.delenv("ARTEMIS_SESSION_ID", raising=False)
+    owner_lock = DeviceExecutionLock("emulator-5554", "CLI task")
+    owner_lock.acquire()
+    try:
+        owner = DeviceExecutionLock.get_active_owner()
+        assert owner is not None
+        assert owner.pid == owner_lock._read_owner(owner_lock.path).pid
+        assert owner.ingress == "cli"
+        assert owner.session_id is None
+        assert DeviceExecutionLock.is_active_owner(owner)
+
+        assert DeviceExecutionLock.annotate_active_owner(
+            session_id="cli-session",
+            ingress="cli",
+        )
+        annotated = DeviceExecutionLock.get_active_owner()
+        assert annotated is not None
+        assert annotated.session_id == "cli-session"
+        assert annotated.ingress == "cli"
+    finally:
+        owner_lock.release()

tests/unit/runtime/test_supervisor.py

@@ -0,0 +1,27 @@
+from unittest.mock import MagicMock, patch
+
+from artemis.runtime.supervisor import ProcessSupervisor
+
+
+def test_verified_termination_rejects_reused_pid():
+    process = MagicMock()
+    process.create_time.return_value = 200.0
+    with (
+        patch("psutil.Process", return_value=process),
+        patch.object(ProcessSupervisor, "terminate_tree") as terminate_tree,
+    ):
+        assert ProcessSupervisor.terminate_tree_verified(1234, 100.0) is False
+
+    terminate_tree.assert_not_called()
+
+
+def test_verified_termination_stops_matching_process_tree():
+    process = MagicMock()
+    process.create_time.return_value = 100.0
+    with (
+        patch("psutil.Process", return_value=process),
+        patch.object(ProcessSupervisor, "terminate_tree", return_value=True) as terminate_tree,
+    ):
+        assert ProcessSupervisor.terminate_tree_verified(1234, 100.0) is True
+
+    terminate_tree.assert_called_once_with(1234, timeout_seconds=3.0)