phone_lease: fair FIFO queue; drop fix_waifu2x
Some checks are pending
md-naming / markdown naming convention (push) Waiting to run
Pre-commit checks / pre-commit (${{ matrix.group }}) (mypy, mypy) (push) Waiting to run
Pre-commit checks / pre-commit (${{ matrix.group }}) (pylint, pylint) (push) Waiting to run
Pre-commit checks / pre-commit (${{ matrix.group }}) (rest, ) (push) Waiting to run
Pre-commit checks / pre-commit (${{ matrix.group }}) (shellcheck, shellcheck) (push) Waiting to run
Python tests / test (push) Waiting to run
repo-contract / repo contract (push) Waiting to run
Shell tests / shell-tests (push) Waiting to run
Shell tests / lib-tests (push) Waiting to run
Shell tests / arch-tests (push) Waiting to run

Finish the queue left uncommitted on 2026-11-17: callers that find a
scope taken get a ticket and are granted in arrival order, dead
sessions are reaped at once. The CLI keeps exit 3 for a held scope.
fix_waifu2x.sh patched the CUDA waifu2x build, now uninstalled.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWV2U9cEtTMTf7iQWin
This commit is contained in:
Krzysztof Rudnicki 2026-11-21 11:50:32 +01:00
parent e9ba82ed66
commit 24503e9197
14 changed files with 893 additions and 201 deletions

View File

@ -0,0 +1,14 @@
{
"title": "phone_lease fair FIFO queue",
"objective": "Sessions that find a phone scope taken get a ticket and are granted in arrival order; dead sessions' leases and tickets are dropped at once; a whole-phone hold ends 30 s after its first grant.",
"acceptance_criteria": [
"python_pkg/phone_lease tests pass with 100% branch coverage (test_fifo, test_alive, test_queue_props plus the old suites)",
"CLI: a second owner on a held package exits 3 with its place in line; another package is granted in parallel; the queued owner gets the lease after release",
"the CLI keeps exit 3 for a held scope, which phone_deploy_launch.sh depends on"
],
"out_of_scope": [
"Changing the CLI exit code to QUEUED_EXIT (75)",
"~/.claude phone scripts"
],
"verifier": "python_pkg/phone_lease/tests and the CLI run in the evidence file"
}

View File

@ -1,31 +0,0 @@
{
"intent": "i3blocks gaming/shutdown/screen-locker blocks find daily-limits' cache even when the X session started without XDG_RUNTIME_DIR.",
"scope": [
"linux_configuration/i3blocks/{gaming_budget,shutdown_countdown,screen_locker}.sh",
"linux_configuration/tests/test_i3blocks_efficiency.sh",
"Non-goal: repairing logind's lost bus connection (needs a logind restart/relogin)"
],
"changes": [
"XDG_RUNTIME_DIR fallback changed from /tmp to /run/user/$UID (bash builtin, no fork)",
"Regression check: no i3blocks script may fall back to /tmp for XDG_RUNTIME_DIR"
],
"verification": [
{
"command": "env -u XDG_RUNTIME_DIR bash linux_configuration/i3blocks/gaming_budget.sh (and shutdown_countdown.sh)",
"result": "pass",
"evidence": "🎮 5h00 left · 0h00/5h00 +🧩1h +📖1h +⚙1h / ⏻ 20:40 +🧩50m +📖30m +⚙1h →max 23:00; live bar confirmed by user"
},
{
"command": "bash linux_configuration/tests/test_i3blocks_{efficiency,shutdown_hint,gaming_budget}.sh",
"result": "pass",
"evidence": "all three suites exit 0"
}
],
"risks": [
"A non-systemd login would still have no /run/user/$UID; the blocks then show the existing missing-cache state"
],
"rollback": [
"git revert this commit",
"Re-run the three i3blocks test suites"
]
}

View File

@ -0,0 +1,33 @@
{
"intent": "Finish the phone_lease FIFO queue left uncommitted on 2026-11-17 so the repo's test gate collects again, and drop fix_waifu2x.sh, dead since waifu2x-converter-cpp-cuda-git was removed.",
"scope": [
"python_pkg/phone_lease: lease.py, ops.py, owner.py, __init__.py, _model.py, _queue.py and tests",
"linux_configuration/fixes/fix_waifu2x.sh deleted",
"Non-goal: the CLI exit codes and the ~/.claude phone scripts stay as they are"
],
"changes": [
"lease.py loads and saves a Book (leases, queue, next ticket number, whole-phone start) under flock and delegates grant/queue rules to the pure _queue core; acquire raises PhoneQueuedError (a PhoneBusyError) with the caller's position",
"ops.release drops the caller's ticket as well as its lease; ops.queue_of lists the line; owner.owner_alive decides which owners are dead so tidy() reaps them",
"test_fifo's clock fixture also drives ops.time, since release and status_all read the wall clock"
],
"verification": [
{
"command": ".venv/bin/python -m pytest -q --cov=python_pkg/phone_lease --cov-branch python_pkg/phone_lease",
"result": "pass",
"evidence": "91 passed; every phone_lease module at 100% branch coverage"
},
{
"command": "PHONE_LEASE_DIR=<tmp> python -m python_pkg.phone_lease acquire PIXEL --package a --wait 0 (owners A, B, C, then A release, B again)",
"result": "pass",
"evidence": "A rc=0; B rc=3 'you are #1 in line (ticket 1)'; C on pkg:c rc=0; B after release rc=0; queue empty"
}
],
"risks": [
"WHOLE_PHONE_MAX_TTL drops from 300 s to 30 s and DEFAULT_WAIT from 60 s to 50 s (the WIP's design for the 60 s tool cap); a whole-phone job longer than 30 s now loses its hold",
"Old lease files without a queue read as an empty queue"
],
"rollback": [
"git revert this commit",
"Rerun python_pkg/phone_lease tests and one phone_deploy.sh claim"
]
}

View File

@ -1,22 +0,0 @@
#!/bin/bash
# Fix waifu2x-converter-cpp-cuda-git for CUDA 13+
# CUDA 13 minimum supported arch is sm_75 (Turing)
PKGBUILD="$HOME/.cache/yay/waifu2x-converter-cpp-cuda-git/PKGBUILD"
if [[ ! -f "$PKGBUILD" ]]; then
echo "PKGBUILD not found. Run 'yay waifu2x-converter-cpp-cuda-git' first to download it."
exit 1
fi
# Add sed commands to prepare() function to replace sm_52/ptx52 with sm_75/ptx75
if grep -q 's/sm_52/sm_75' "$PKGBUILD"; then
echo "PKGBUILD already patched."
else
sed -i '/^prepare() {$/a\
# Fix for CUDA 13+ which requires sm_75+ (Turing)\
sed -i "s/sm_52/sm_75/g" waifu2x-converter-cpp/CMakeLists.txt\
sed -i "s/ptx52/ptx75/g" waifu2x-converter-cpp/CMakeLists.txt\
sed -i "s/ptx52/ptx75/g" waifu2x-converter-cpp/src/modelHandler_CUDA.cpp' "$PKGBUILD"
echo "PKGBUILD patched. Now run 'yay waifu2x-converter-cpp-cuda-git' again."
fi

View File

@ -12,44 +12,66 @@ twice. This package hands out *scoped* leases:
* the owner is the nearest ancestor ``claude`` process (one per session);
* the serial is always resolved (:mod:`.serial`), never a placeholder, so
every caller agrees on which phone a lease is for;
* a lease expires ``ttl`` seconds after its last refresh.
* a lease expires ``ttl`` seconds after its last refresh;
* callers that find their scope taken wait in a fair FIFO queue: each gets a
ticket it keeps for :data:`TICKET_TTL` seconds after its last try, and
leases and tickets of sessions that died are dropped at once.
Sessions that drive apps on their own virtual display
(``~/.claude/scripts/phone_vd.sh``) need only a package lease, so several of
them can work on one phone at the same time.
"""
from python_pkg.phone_lease import _cleanup
from python_pkg.phone_lease.lease import (
DEFAULT_TTL,
DEFAULT_WAIT,
QUEUED_EXIT,
SCREEN,
TICKET_TTL,
WHOLE_PHONE,
WHOLE_PHONE_MAX_TTL,
Clock,
Lease,
PhoneBusyError,
PhoneQueuedError,
Terms,
Ticket,
acquire,
scope_of,
)
from python_pkg.phone_lease.ops import holds, reap, release, status, status_all
from python_pkg.phone_lease.owner import owner_id
from python_pkg.phone_lease.ops import (
holds,
queue_of,
reap,
release,
status,
status_all,
)
from python_pkg.phone_lease.owner import owner_alive, owner_id
from python_pkg.phone_lease.serial import NoPhoneError, resolve_serial
__all__ = [
"DEFAULT_TTL",
"DEFAULT_WAIT",
"QUEUED_EXIT",
"SCREEN",
"TICKET_TTL",
"WHOLE_PHONE",
"WHOLE_PHONE_MAX_TTL",
"Clock",
"Lease",
"NoPhoneError",
"PhoneBusyError",
"PhoneQueuedError",
"Terms",
"Ticket",
"_cleanup",
"acquire",
"holds",
"owner_alive",
"owner_id",
"queue_of",
"reap",
"release",
"resolve_serial",

View File

@ -0,0 +1,109 @@
"""The lease file's records, its constants, and the errors ``acquire`` raises.
Split out of ``lease.py`` so the pure queue core (:mod:`._queue`) and the
file layer (:mod:`.lease`) share one definition without importing each other.
"""
from __future__ import annotations
from dataclasses import dataclass, field
import time
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from collections.abc import Callable
@dataclass(frozen=True)
class Clock:
"""The two things ``acquire`` needs from ``time``; tests hand in fakes."""
now: Callable[[], float] = time.time
sleep: Callable[[float], None] = time.sleep
# Seconds a lease outlives its last refresh; a quiet session frees the phone.
DEFAULT_TTL = 180.0
# Seconds ``acquire`` waits in the queue before answering "queued, retry".
# Every Claude tool call is capped at 60 s, so a wait must end well before.
DEFAULT_WAIT = 50.0
# A whole-phone hold stops everyone else: 30 s from its first grant, however
# often the holder refreshes it.
WHOLE_PHONE_MAX_TTL = 30.0
# Seconds a queue ticket survives its owner's last attempt, so a caller that
# got "queued" and reruns the same command keeps its place in line.
TICKET_TTL = 90.0
# Exit code for "queued, retry": EX_TEMPFAIL from sysexits.h.
QUEUED_EXIT = 75
SCREEN = "__screen__"
WHOLE_PHONE = "whole-phone"
class PhoneBusyError(RuntimeError):
"""Raised when a fresh, conflicting lease belongs to another owner."""
class PhoneQueuedError(PhoneBusyError):
"""The wait ran out with the caller still in line; its ticket is kept."""
def __init__(self, message: str, *, position: int, number: int) -> None:
"""Keep the place in line next to the message."""
super().__init__(message)
self.position = position
self.number = number
def conflicts(scope: str, other: str) -> bool:
"""Whether two owners may not hold ``scope`` and ``other`` at once."""
return WHOLE_PHONE in (scope, other) or scope == other
@dataclass(frozen=True)
class Lease:
"""One entry of the lease file."""
serial: str
owner: str
expires: float
note: str
scope: str = f"pkg:{SCREEN}"
cleanup: tuple[str, ...] = field(default_factory=tuple)
def is_expired(self, now: float) -> bool:
"""True once ``now`` has passed the expiry."""
return now >= self.expires
def conflicts_with(self, owner: str, scope: str) -> bool:
"""Whether this lease stops ``owner`` from taking ``scope``."""
return self.owner != owner and conflicts(self.scope, scope)
def describe(self) -> str:
"""One line for an error or a status readout."""
until = time.strftime("%H:%M:%S", time.localtime(self.expires))
what = "" if self.scope == f"pkg:{SCREEN}" else f" [{self.scope}]"
return (
f"phone {self.serial}{what} held by {self.owner} ({self.note}) "
f"until {until}"
)
@dataclass(frozen=True)
class Ticket:
"""One caller waiting in line for a scope; ``number`` orders the line."""
owner: str
scope: str
number: int
seen: float
note: str = ""
def describe(self) -> str:
"""One line for an error or a status readout."""
return f"queued #{self.number} {self.owner} [{self.scope}] ({self.note})"
def scope_of(package: str | None = None, *, whole_phone: bool = False) -> str:
"""The scope string for a package, the whole phone, or the real screen."""
if whole_phone:
return WHOLE_PHONE
return f"pkg:{package or SCREEN}"

View File

@ -0,0 +1,153 @@
"""The fair queue, as pure functions over one lease file's contents.
No files and no clock here: :func:`python_pkg.phone_lease.lease.locked_update`
loads a :class:`Book` under the flock, calls :func:`tidy` and then one of
:func:`take` / :func:`leave`, and writes it back. The rules:
* a caller is granted a scope when no foreign lease conflicts with it and no
foreign ticket that conflicts with it has a lower number than its own;
everyone else gets a ticket (kept :data:`TICKET_TTL` after each attempt)
and its position in line. Different packages never conflict, so they are
granted side by side;
* a holder's refresh never pushes its expiry out while a conflicting foreign
ticket waits (the *drain* rule), so busy holders cannot starve the line;
* a whole-phone hold ends :data:`WHOLE_PHONE_MAX_TTL` after its first grant;
* leases and tickets of dead owners are dropped at once (:func:`tidy`).
"""
from __future__ import annotations
from dataclasses import dataclass, field, replace
from typing import TYPE_CHECKING
from python_pkg.phone_lease._model import (
TICKET_TTL,
WHOLE_PHONE,
WHOLE_PHONE_MAX_TTL,
Lease,
Ticket,
conflicts,
)
if TYPE_CHECKING:
from collections.abc import Callable
@dataclass
class Book:
"""Everything one lease file holds."""
leases: list[Lease] = field(default_factory=list)
tickets: list[Ticket] = field(default_factory=list)
next_number: int = 1
# "<owner> <scope>" -> first grant of a whole-phone hold, for its cap.
since: dict[str, float] = field(default_factory=dict)
@dataclass(frozen=True)
class Grant:
"""What one attempt got: a lease, or a place in line and who is ahead."""
lease: Lease | None
position: int = 0
number: int = 0
blocker: str = ""
new_cleanup: bool = False
def _key(owner: str, scope: str) -> str:
return f"{owner} {scope}"
def tidy(book: Book, now: float, alive: Callable[[str], bool]) -> list[Lease]:
"""Drop expired or orphaned leases and tickets; return the dropped leases.
The caller runs the dropped leases' cleanup commands (outside the lock).
"""
keep: list[Lease] = []
gone: list[Lease] = []
for lease in book.leases:
(keep if not lease.is_expired(now) and alive(lease.owner) else gone).append(
lease
)
book.leases = keep
book.tickets = [
x for x in book.tickets if now < x.seen + TICKET_TTL and alive(x.owner)
]
held = {_key(x.owner, x.scope) for x in keep}
book.since = {k: v for k, v in book.since.items() if k in held}
return gone
def take(book: Book, want: Lease, ttl: float, now: float) -> Grant:
"""Grant or refresh ``want`` if the line allows it, else queue it."""
key = (want.owner, want.scope)
held = next((x for x in book.leases if (x.owner, x.scope) == key), None)
mine = next((x for x in book.tickets if (x.owner, x.scope) == key), None)
rivals = [
x
for x in book.tickets
if x.owner != want.owner and conflicts(x.scope, want.scope)
]
if held is None:
blocker = next(
(x for x in book.leases if x.conflicts_with(want.owner, want.scope)),
None,
)
ahead = [x for x in rivals if mine is None or x.number < mine.number]
if blocker is not None or ahead:
first = blocker.describe() if blocker is not None else ahead[0].describe()
return _queue(book, want, mine, len(ahead) + 1, first, now)
return _grant(book, want, held, ttl, now, drain=bool(rivals))
def _grant(
book: Book, want: Lease, held: Lease | None, ttl: float, now: float, *, drain: bool
) -> Grant:
key = _key(want.owner, want.scope)
expires = now + ttl
if want.scope == WHOLE_PHONE:
start = book.since.get(key, now) if held is not None else now
book.since[key] = start
expires = min(expires, start + WHOLE_PHONE_MAX_TTL)
old: tuple[str, ...] = ()
if held is not None:
old = held.cleanup
if drain:
expires = held.expires
cleanup = old + tuple(c for c in dict.fromkeys(want.cleanup) if c not in old)
granted = replace(want, expires=expires, cleanup=cleanup)
book.leases = [x for x in book.leases if x is not held] + [granted]
book.tickets = [
x for x in book.tickets if (x.owner, x.scope) != (want.owner, want.scope)
]
return Grant(granted, new_cleanup=bool(cleanup) and not old)
def _queue(
book: Book, want: Lease, mine: Ticket | None, position: int, first: str, now: float
) -> Grant:
if mine is None:
mine = Ticket(want.owner, want.scope, book.next_number, now, want.note)
book.next_number += 1
book.tickets.append(mine)
else:
fresh = replace(mine, seen=now, note=want.note)
book.tickets = [fresh if x is mine else x for x in book.tickets]
return Grant(None, position=position, number=mine.number, blocker=first)
def leave(book: Book, owner: str, scope: str) -> tuple[list[Lease], bool]:
"""Drop ``owner``'s lease and ticket on ``scope``.
Returns the dropped leases (their cleanup is the caller's) and whether
anything at all was dropped.
"""
mine = (owner, scope)
dropped = [x for x in book.leases if (x.owner, x.scope) == mine]
tickets = [x for x in book.tickets if (x.owner, x.scope) != mine]
found = bool(dropped) or len(tickets) < len(book.tickets)
book.leases = [x for x in book.leases if (x.owner, x.scope) != mine]
book.tickets = tickets
book.since.pop(_key(owner, scope), None)
return dropped, found

View File

@ -1,6 +1,7 @@
"""The lease file, its owner identity, and the acquire/release operations.
"""The lease file, and the acquire operation that waits in its fair queue.
One JSON file per phone holds every live lease on it. A lease has a *scope*:
One JSON file per phone holds every live lease on it, the queue of callers
waiting for one, and the start of each whole-phone hold. A lease has a *scope*:
* ``pkg:<package>`` -- one app (install, launch, driving it). Two sessions can
hold different packages at once. ``pkg:__screen__`` is the phone's real
@ -9,89 +10,67 @@ One JSON file per phone holds every live lease on it. A lease has a *scope*:
Doze, screen sleep, reboot, a focus-mode deploy). It conflicts with every
foreign lease, is capped at :data:`WHOLE_PHONE_MAX_TTL`, and carries cleanup
commands that run exactly once, on release or expiry.
The queue rules live in :mod:`._queue`; this module only loads and saves the
file under ``flock`` and runs cleanup commands outside the lock.
"""
from __future__ import annotations
from dataclasses import asdict, dataclass, field
from dataclasses import asdict, dataclass
import fcntl
import json
import os
from pathlib import Path
import time
from typing import TYPE_CHECKING
from python_pkg.phone_lease import _cleanup
from python_pkg.phone_lease import _cleanup, _queue
from python_pkg.phone_lease import owner as owner_mod
from python_pkg.phone_lease._model import (
DEFAULT_TTL,
DEFAULT_WAIT,
QUEUED_EXIT,
SCREEN,
TICKET_TTL,
WHOLE_PHONE,
WHOLE_PHONE_MAX_TTL,
Clock,
Lease,
PhoneBusyError,
PhoneQueuedError,
Ticket,
scope_of,
)
from python_pkg.phone_lease._queue import Book
from python_pkg.phone_lease.owner import owner_id
if TYPE_CHECKING:
from collections.abc import Callable
__all__ = [
"DEFAULT_TTL",
"DEFAULT_WAIT",
"QUEUED_EXIT",
"SCREEN",
"TICKET_TTL",
"WHOLE_PHONE",
"WHOLE_PHONE_MAX_TTL",
"Clock",
"Lease",
"PhoneBusyError",
"PhoneQueuedError",
"Terms",
"Ticket",
"acquire",
"scope_of",
]
@dataclass(frozen=True)
class Clock:
"""The two things ``acquire`` needs from ``time``; tests hand in fakes."""
now: Callable[[], float] = time.time
sleep: Callable[[float], None] = time.sleep
# Seconds a lease outlives its last refresh; a quiet session frees the phone.
DEFAULT_TTL = 180.0
# Seconds ``acquire`` waits on a foreign lease before giving up.
DEFAULT_WAIT = 60.0
# A whole-phone lease stops everyone else, so it can never be held for long.
WHOLE_PHONE_MAX_TTL = 300.0
SCREEN = "__screen__"
WHOLE_PHONE = "whole-phone"
# Where lease files live; overridable so tests never touch the real one.
LEASE_DIR = Path(
os.environ.get("PHONE_LEASE_DIR", str(Path.home() / ".cache" / "phone-lease"))
)
class PhoneBusyError(RuntimeError):
"""Raised when a fresh, conflicting lease belongs to another owner."""
@dataclass(frozen=True)
class Lease:
"""One entry of the lease file."""
serial: str
owner: str
expires: float
note: str
scope: str = f"pkg:{SCREEN}"
cleanup: tuple[str, ...] = field(default_factory=tuple)
def is_expired(self, now: float) -> bool:
"""True once ``now`` has passed the expiry."""
return now >= self.expires
def conflicts_with(self, owner: str, scope: str) -> bool:
"""Whether this lease stops ``owner`` from taking ``scope``."""
if self.owner == owner:
return False
return WHOLE_PHONE in (self.scope, scope) or self.scope == scope
def describe(self) -> str:
"""One line for an error or a status readout."""
until = time.strftime("%H:%M:%S", time.localtime(self.expires))
what = "" if self.scope == f"pkg:{SCREEN}" else f" [{self.scope}]"
return (
f"phone {self.serial}{what} held by {self.owner} ({self.note}) "
f"until {until}"
)
def scope_of(package: str | None = None, *, whole_phone: bool = False) -> str:
"""The scope string for a package, the whole phone, or the real screen."""
if whole_phone:
return WHOLE_PHONE
return f"pkg:{package or SCREEN}"
def lease_paths(serial: str) -> tuple[Path, Path]:
"""The lock file and the lease file for ``serial``."""
LEASE_DIR.mkdir(parents=True, exist_ok=True)
@ -109,67 +88,74 @@ def _parse(raw: object) -> Lease | None:
return Lease(**{**asdict(lease), "cleanup": tuple(lease.cleanup)})
def read_leases(path: Path) -> list[Lease]:
"""Every lease in the file. Pre-scope files hold one bare object."""
def _ticket(raw: object) -> Ticket | None:
if not isinstance(raw, dict):
return None
try:
return Ticket(**raw)
except TypeError:
return None
def read_book(path: Path) -> Book:
"""Everything in the file; damaged parts read as empty.
Pre-scope files hold one bare lease object, pre-queue files only leases.
"""
try:
raw = json.loads(path.read_text(encoding="utf-8"))
except OSError, ValueError:
return []
items = raw.get("leases", [raw]) if isinstance(raw, dict) else []
return [lease for lease in map(_parse, items) if lease is not None]
def write_leases(path: Path, leases: list[Lease]) -> None:
"""Replace the lease file's contents with ``leases``."""
path.write_text(
json.dumps({"leases": [asdict(lease) for lease in leases]}), encoding="utf-8"
return Book()
if not isinstance(raw, dict):
return Book()
leases = [x for x in map(_parse, raw.get("leases", [raw])) if x is not None]
queue = raw.get("queue", [])
tickets = [x for x in map(_ticket, queue if isinstance(queue, list) else []) if x]
after = max((x.number for x in tickets), default=0) + 1
number = raw.get("next")
since = raw.get("since")
return Book(
leases=leases,
tickets=tickets,
next_number=max(number, after) if isinstance(number, int) else after,
since=dict(since) if isinstance(since, dict) else {},
)
def locked_update(
serial: str, change: Callable[[list[Lease], float], list[Lease]], now: float
) -> list[Lease]:
"""Apply ``change`` to the live leases under the lock.
def read_leases(path: Path) -> list[Lease]:
"""Every lease in the file, expired or not."""
return read_book(path).leases
Expired leases are dropped on the way in; their cleanup commands run after
the lock is released, so a slow ``adb`` never blocks another session.
def write_book(path: Path, book: Book) -> None:
"""Replace the file's contents with ``book``."""
body = {
"leases": [asdict(x) for x in book.leases],
"queue": [asdict(x) for x in book.tickets],
"next": book.next_number,
"since": book.since,
}
path.write_text(json.dumps(body), encoding="utf-8")
def locked_update[T](serial: str, change: Callable[[Book, float], T], now: float) -> T:
"""Apply ``change`` to the tidied book under the lock and return its result.
Expired leases and those of dead owners are dropped first (:func:`._queue.tidy`);
their cleanup commands run after the lock is released, so a slow ``adb``
never blocks another session.
"""
lock_path, lease_path = lease_paths(serial)
lock_path, path = lease_paths(serial)
with lock_path.open("w", encoding="utf-8") as lock:
fcntl.flock(lock, fcntl.LOCK_EX)
leases = read_leases(lease_path)
expired = [lease for lease in leases if lease.is_expired(now)]
live = change([lease for lease in leases if not lease.is_expired(now)], now)
write_leases(lease_path, live)
for lease in expired:
book = read_book(path)
# Looked up on each call so tests (and conftest) can patch owner_alive.
gone = _queue.tidy(book, now, owner_mod.owner_alive)
result = change(book, now)
write_book(path, book)
for lease in gone:
_cleanup.run(lease.cleanup)
return live
def _attempt(
serial: str, want: Lease, ttl: float, now: float
) -> tuple[Lease | None, Lease | None, bool]:
"""One locked try at ``want``: (granted lease, blocker, newly taken)."""
out: list[Lease | None] = [None, None]
fresh = [True]
def take(live: list[Lease], at: float) -> list[Lease]:
blocker = next(
(x for x in live if x.conflicts_with(want.owner, want.scope)), None
)
if blocker is not None:
out[1] = blocker
return live
prior = next(
(x for x in live if (x.owner, x.scope) == (want.owner, want.scope)), None
)
fresh[0] = prior is None
granted = Lease(**{**asdict(want), "expires": at + ttl})
out[0] = granted
return [x for x in live if x is not prior] + [granted]
locked_update(serial, take, now)
return out[0], out[1], fresh[0]
return result
@dataclass(frozen=True)
@ -181,6 +167,17 @@ class Terms:
cleanup: tuple[str, ...] = ()
def _queued_message(grant: _queue.Grant, wait: float) -> str:
return (
f"{grant.blocker} -- waited {wait:.0f}s; you are #{grant.position} in line "
f"(ticket {grant.number}). To keep your place, rerun the same command "
f"within {TICKET_TTL:.0f}s. Or drive the app on your own virtual display "
"(~/.claude/scripts/phone_vd.sh, needs only a package lease), or the "
"headless emulator (~/.claude/scripts/phone_emu.sh); see the phone-deploy "
"skill."
)
def acquire(
serial: str,
note: str = "",
@ -192,34 +189,28 @@ def acquire(
) -> Lease:
"""Take or refresh a lease on ``serial`` for one ``scope`` (see :func:`scope_of`).
Waits up to ``terms.wait`` seconds for conflicting foreign leases to
expire, polling once a second, then raises :class:`PhoneBusyError`.
Waits in line up to ``terms.wait`` seconds, polling once a second, then
raises :class:`PhoneQueuedError` with the caller's ticket kept.
"""
me = owner_id() if owner is None else owner
terms = terms or Terms()
ttl = terms.ttl
if scope == WHOLE_PHONE:
ttl = min(ttl, WHOLE_PHONE_MAX_TTL)
cleanup = terms.cleanup
wait = terms.wait
clock = clock or Clock()
deadline = clock.now() + wait
want = Lease(serial, me, 0.0, note, scope, terms.cleanup)
deadline = clock.now() + terms.wait
while True:
mine, blocker, is_new = _attempt(
serial, Lease(serial, me, 0.0, note, scope, cleanup), ttl, clock.now()
grant = locked_update(
serial,
lambda book, at: _queue.take(book, want, terms.ttl, at),
clock.now(),
)
if mine is not None:
if is_new and cleanup:
if grant.lease is not None:
if grant.new_cleanup:
_cleanup.spawn_reaper(serial, me, scope)
return mine
return grant.lease
if clock.now() >= deadline:
msg = (
f"{blocker.describe() if blocker else serial} -- waited {wait:.0f}s. "
"Do not retry "
"in a loop: drive the app on your own virtual display instead "
"(~/.claude/scripts/phone_vd.sh, needs only a package lease), or the "
"headless emulator (~/.claude/scripts/phone_emu.sh); see the "
"phone-deploy skill."
raise PhoneQueuedError(
_queued_message(grant, terms.wait),
position=grant.position,
number=grant.number,
)
raise PhoneBusyError(msg)
clock.sleep(1.0)

View File

@ -5,14 +5,16 @@ from __future__ import annotations
import time
from typing import TYPE_CHECKING
from python_pkg.phone_lease import _cleanup
from python_pkg.phone_lease import _cleanup, _queue
from python_pkg.phone_lease.lease import (
SCREEN,
WHOLE_PHONE,
Clock,
Lease,
Ticket,
lease_paths,
locked_update,
read_book,
read_leases,
)
from python_pkg.phone_lease.owner import owner_id
@ -27,18 +29,17 @@ REAP_POLL = 5.0
def release(
serial: str, *, scope: str = f"pkg:{SCREEN}", owner: str | None = None
) -> bool:
"""Drop ``owner``'s lease on ``scope``, running its cleanup. True if dropped."""
"""Drop ``owner``'s lease and ticket on ``scope``, running the lease's cleanup.
True if anything was dropped.
"""
me = owner_id() if owner is None else owner
dropped: list[Lease] = []
def drop(live: list[Lease], _now: float) -> list[Lease]:
dropped.extend(x for x in live if (x.owner, x.scope) == (me, scope))
return [x for x in live if x not in dropped]
locked_update(serial, drop, time.time())
dropped, found = locked_update(
serial, lambda book, _now: _queue.leave(book, me, scope), time.time()
)
for lease in dropped:
_cleanup.run(lease.cleanup)
return bool(dropped)
return found
def status_all(serial: str, now: float | None = None) -> list[Lease]:
@ -47,6 +48,15 @@ def status_all(serial: str, now: float | None = None) -> list[Lease]:
return [x for x in read_leases(lease_paths(serial)[1]) if not x.is_expired(at)]
def queue_of(serial: str) -> list[Ticket]:
"""The tickets in ``serial``'s file, first in line first (read-only).
Stale tickets stay listed until the next locked update tidies them out.
"""
tickets = read_book(lease_paths(serial)[1]).tickets
return sorted(tickets, key=lambda x: x.number)
def status(
serial: str, now: float | None = None, *, scope: str = f"pkg:{SCREEN}"
) -> Lease | None:
@ -96,7 +106,7 @@ def reap(
return False
if lease.is_expired(clock.now()):
# locked_update drops expired leases and runs their cleanup itself.
locked_update(serial, lambda live, _now: live, clock.now())
locked_update(serial, lambda _book, _now: None, clock.now())
return True
# Wake at least every few seconds so a released lease frees the reaper.
clock.sleep(min(REAP_POLL, max(0.5, lease.expires - clock.now())))

View File

@ -34,3 +34,23 @@ def owner_id(pid: int | None = None, environ: dict[str, str] | None = None) -> s
# it may contain spaces, so split after its closing paren.
current = int(stat.rsplit(")", 1)[1].split()[1])
return f"pid:{origin}"
def owner_alive(owner: str, *, proc_root: Path = Path("/proc")) -> bool:
"""Whether ``owner``'s session still runs, so its leases and tickets stay.
``claude:<pid>`` lives while that pid is a ``claude`` process (a reused pid
running anything else counts as dead); ``<tool>:<pid>`` lives while the pid
exists. ``pid:<pid>`` is the CLI's own short-lived process, and explicit
names (``PHONE_LEASE_OWNER``) carry no pid, so both always count as alive.
"""
kind, _, pid = owner.partition(":")
if not pid.isdigit() or kind == "pid":
return True
comm = proc_root / pid / "comm"
if kind != "claude":
return comm.parent.exists()
try:
return comm.read_text(encoding="utf-8").strip() == "claude"
except OSError:
return False

View File

@ -0,0 +1,22 @@
"""Every lease test runs with live owners unless it says otherwise.
Tests name owners ``claude:1``, ``claude:2`` ...; on a real machine pid 1 is
systemd, so the dead-owner reaper would drop those leases mid-test.
"""
from __future__ import annotations
from typing import TYPE_CHECKING
from unittest.mock import patch
import pytest
if TYPE_CHECKING:
from collections.abc import Iterator
@pytest.fixture(autouse=True)
def owners_alive() -> Iterator[None]:
"""Treat every owner as alive; reaping tests patch their own answer."""
with patch("python_pkg.phone_lease.owner.owner_alive", return_value=True):
yield

View File

@ -0,0 +1,37 @@
"""Which lease owners count as dead: only sessions whose process is gone."""
from __future__ import annotations
from typing import TYPE_CHECKING
import pytest
from python_pkg.phone_lease.owner import owner_alive
if TYPE_CHECKING:
from pathlib import Path
@pytest.fixture
def proc(tmp_path: Path) -> Path:
for pid, comm in ((10, "claude"), (11, "zsh"), (12, "bash")):
(tmp_path / str(pid)).mkdir()
(tmp_path / str(pid) / "comm").write_text(f"{comm}\n")
return tmp_path
@pytest.mark.parametrize(
("owner", "alive"),
[
("claude:10", True),
("claude:11", False), # pid reused by another program
("claude:99", False), # gone
("phone_deploy:12", True),
("phone_deploy:99", False),
("pid:99", True), # the CLI's own pid: dead right after acquire
("ci-run-7", True),
("claude:abc", True),
],
)
def test_owner_alive(proc: Path, owner: str, *, alive: bool) -> None:
assert owner_alive(owner, proc_root=proc) is alive

View File

@ -0,0 +1,215 @@
"""The fair queue: tickets, FIFO grants, kept places, drain, caps, dead owners."""
from __future__ import annotations
import json
from types import SimpleNamespace
from typing import TYPE_CHECKING
from unittest.mock import MagicMock, patch
import pytest
from python_pkg.phone_lease import (
QUEUED_EXIT,
TICKET_TTL,
WHOLE_PHONE,
WHOLE_PHONE_MAX_TTL,
Clock,
Lease,
PhoneQueuedError,
Terms,
_cleanup,
acquire,
queue_of,
release,
status_all,
)
from python_pkg.phone_lease import lease as lease_mod
from python_pkg.phone_lease import ops as ops_mod
if TYPE_CHECKING:
from collections.abc import Iterator
from pathlib import Path
class Time:
"""A settable clock shared by every call in one test."""
def __init__(self) -> None:
self.now = 0.0
def clock(self) -> Clock:
def sleep(secs: float) -> None:
self.now += secs
return Clock(now=lambda: self.now, sleep=sleep)
@pytest.fixture(autouse=True)
def cleanup_run(tmp_path: Path) -> Iterator[MagicMock]:
with (
patch.object(lease_mod, "LEASE_DIR", tmp_path / "leases"),
patch.object(_cleanup, "run", return_value=[]) as run,
patch.object(_cleanup, "spawn_reaper"),
):
yield run
@pytest.fixture
def t(monkeypatch: pytest.MonkeyPatch) -> Time:
"""The test clock; ``release`` and ``status_all`` read it too."""
clock = Time()
monkeypatch.setattr(ops_mod, "time", SimpleNamespace(time=lambda: clock.now))
return clock
def take(
t: Time,
owner: str,
scope: str,
*,
ttl: float = 10.0,
wait: float = 0.0,
cleanup: tuple[str, ...] = (),
) -> Lease:
terms = Terms(ttl=ttl, wait=wait, cleanup=cleanup)
return acquire("P", owner, scope=scope, terms=terms, owner=owner, clock=t.clock())
def queued(t: Time, owner: str, scope: str) -> PhoneQueuedError:
with pytest.raises(PhoneQueuedError) as caught:
take(t, owner, scope)
return caught.value
def test_the_exit_code_is_tempfail() -> None:
assert QUEUED_EXIT == 75
def test_waiters_get_tickets_in_arrival_order(t: Time) -> None:
take(t, "A", "pkg:a")
first, second = queued(t, "B", "pkg:a"), queued(t, "C", "pkg:a")
assert (first.position, second.position) == (1, 2)
assert first.number < second.number
assert "rerun the same command" in str(second)
assert [(x.owner, x.scope) for x in queue_of("P")] == [
("B", "pkg:a"),
("C", "pkg:a"),
]
def test_a_freed_scope_goes_to_the_first_ticket(t: Time) -> None:
take(t, "A", "pkg:a")
queued(t, "B", "pkg:a")
queued(t, "C", "pkg:a")
release("P", scope="pkg:a", owner="A")
assert queued(t, "C", "pkg:a").position == 2 # B is first in line
take(t, "B", "pkg:a")
assert queued(t, "C", "pkg:a").position == 1
assert [x.owner for x in queue_of("P")] == ["C"]
def test_other_packages_pass_the_queue(t: Time) -> None:
take(t, "A", "pkg:a")
queued(t, "B", "pkg:a")
take(t, "C", "pkg:c")
assert {x.owner for x in status_all("P")} == {"A", "C"}
def test_a_whole_phone_waiter_holds_back_later_packages(t: Time) -> None:
take(t, "A", "pkg:a")
queued(t, "B", WHOLE_PHONE)
assert queued(t, "C", "pkg:c").position == 2
def test_a_retry_keeps_its_place_for_the_ticket_ttl(t: Time) -> None:
take(t, "A", "pkg:a", ttl=1000)
queued(t, "B", "pkg:a")
t.now = TICKET_TTL - 5
queued(t, "C", "pkg:a")
t.now = TICKET_TTL - 1
assert queued(t, "B", "pkg:a").position == 1
t.now = 2 * TICKET_TTL # B never came back; C did not either
assert queued(t, "D", "pkg:a").position == 1
def test_waiting_inside_acquire_keeps_the_ticket_fresh(t: Time) -> None:
take(t, "A", "pkg:a", ttl=1000)
with pytest.raises(PhoneQueuedError):
take(t, "B", "pkg:a", wait=50)
assert queue_of("P")[0].seen == pytest.approx(t.now)
def test_a_wait_ends_in_a_grant_when_the_holder_expires(t: Time) -> None:
take(t, "A", "pkg:a", ttl=3)
got = take(t, "B", "pkg:a", wait=10)
assert got.owner == "B"
assert queue_of("P") == []
def test_a_holder_cannot_outlast_a_waiter_by_refreshing(t: Time) -> None:
take(t, "A", "pkg:a", ttl=10)
t.now = 5
assert take(t, "A", "pkg:a", ttl=10).expires == 15
queued(t, "B", "pkg:a")
t.now = 8
assert take(t, "A", "pkg:a", ttl=10).expires == 15
def test_whole_phone_hold_is_capped_from_the_first_grant(t: Time) -> None:
assert WHOLE_PHONE_MAX_TTL == 30
first = take(t, "A", WHOLE_PHONE, ttl=9999)
assert first.expires == 30
t.now = 20
assert take(t, "A", WHOLE_PHONE, ttl=9999).expires == 30
t.now = 31 # expired: a new hold starts its own 30 s
assert take(t, "A", WHOLE_PHONE, ttl=9999).expires == 61
def test_dead_owners_are_reaped_at_once(t: Time, cleanup_run: MagicMock) -> None:
take(t, "A", "pkg:x", ttl=1000)
queued(t, "claude:9", "pkg:x")
take(t, "claude:9", "pkg:y", ttl=1000, cleanup=("undo",))
with patch(
"python_pkg.phone_lease.owner.owner_alive",
side_effect=lambda owner: owner != "claude:9",
):
assert queued(t, "B", "pkg:x").position == 1
assert [x.owner for x in queue_of("P")] == ["B"]
assert take(t, "B", "pkg:y").owner == "B"
cleanup_run.assert_any_call(("undo",))
def test_refresh_merges_cleanup_and_reaps_new_cleanup() -> None:
t = Time()
with patch.object(_cleanup, "spawn_reaper") as spawn:
take(t, "A", WHOLE_PHONE)
take(t, "A", WHOLE_PHONE, cleanup=("svc wifi enable",))
take(t, "A", WHOLE_PHONE, cleanup=("svc data enable",))
got = take(t, "A", WHOLE_PHONE)
assert got.cleanup == ("svc wifi enable", "svc data enable")
spawn.assert_called_once_with("P", "A", WHOLE_PHONE)
def test_release_drops_the_callers_ticket(t: Time) -> None:
take(t, "A", "pkg:a")
queued(t, "B", "pkg:a")
assert release("P", scope="pkg:a", owner="B") is True
assert queue_of("P") == []
def test_damaged_queue_entries_are_skipped(t: Time, tmp_path: Path) -> None:
(tmp_path / "leases").mkdir()
(tmp_path / "leases" / "P.json").write_text(
json.dumps({"leases": [], "queue": [1, {"bad": 1}], "next": "x", "since": [3]})
)
assert queue_of("P") == []
take(t, "A", "pkg:a")
assert queued(t, "B", "pkg:a").number == 1
def test_a_file_that_is_not_an_object_reads_as_empty(tmp_path: Path) -> None:
(tmp_path / "leases").mkdir()
(tmp_path / "leases" / "P.json").write_text("[1, 2]")
assert queue_of("P") == []
assert status_all("P") == []

View File

@ -0,0 +1,119 @@
"""Laws of the pure queue core: exclusion, FIFO, parallelism, no starvation.
Drives :mod:`python_pkg.phone_lease._queue` directly (no files, no flock) the
way ``locked_update`` does: ``tidy`` first, then one ``take`` or ``leave``.
"""
from __future__ import annotations
from hypothesis import given, settings
from hypothesis import strategies as st
from python_pkg.phone_lease._model import WHOLE_PHONE, Lease, conflicts
from python_pkg.phone_lease._queue import Book, leave, take, tidy
OWNERS = ("A", "B", "C", "D")
SCOPES = ("pkg:a", "pkg:b", WHOLE_PHONE)
TTL = 10.0
PROPS = settings(max_examples=150, deadline=None, derandomize=True)
step = st.one_of(
st.tuples(st.just("take"), st.sampled_from(OWNERS), st.sampled_from(SCOPES)),
st.tuples(st.just("leave"), st.sampled_from(OWNERS), st.sampled_from(SCOPES)),
st.tuples(st.just("tick"), st.sampled_from(("1", "5", "12", "40")), st.just("")),
)
def _alive(_owner: str) -> bool:
return True
def _should_grant(book: Book, owner: str, scope: str) -> bool:
"""The rule written the obvious way: nothing foreign in force or ahead."""
if any(x.owner == owner and x.scope == scope for x in book.leases):
return True
mine = next(
(x.number for x in book.tickets if (x.owner, x.scope) == (owner, scope)),
None,
)
blocked = any(x.owner != owner and conflicts(x.scope, scope) for x in book.leases)
ahead = any(
x.owner != owner
and conflicts(x.scope, scope)
and (mine is None or x.number < mine)
for x in book.tickets
)
return not blocked and not ahead
def _exclusive(book: Book) -> bool:
return not any(
a.owner != b.owner and conflicts(a.scope, b.scope)
for i, a in enumerate(book.leases)
for b in book.leases[i + 1 :]
)
@PROPS
@given(st.lists(step, max_size=40))
def test_grants_follow_the_fifo_rule_and_never_overlap(
steps: list[tuple[str, str, str]],
) -> None:
book, now = Book(), 0.0
for kind, who, scope in steps:
if kind == "tick":
now += float(who)
continue
owner = who
tidy(book, now, _alive)
if kind == "leave":
leave(book, owner, scope)
continue
expected = _should_grant(book, owner, scope)
got = take(book, Lease("P", owner, 0.0, "", scope), TTL, now)
assert (got.lease is not None) == expected
assert (got.position == 0) == expected
assert _exclusive(book)
numbers = [x.number for x in book.tickets]
assert numbers == sorted(set(numbers))
@PROPS
@given(
st.lists(
st.tuples(st.sampled_from(OWNERS), st.sampled_from(SCOPES)),
min_size=1,
max_size=8,
unique=True,
),
st.lists(st.floats(1.0, 5.0), min_size=1, max_size=5),
)
def test_every_waiter_is_served_while_holders_keep_refreshing(
wants: list[tuple[str, str]], gaps: list[float]
) -> None:
"""Adversarial holders refresh every round; drain + TTL still serve all."""
book, now = Book(), 0.0
served: set[tuple[str, str]] = set()
bound = (len(wants) + 1) * (int(TTL) + 2) * 2
for round_no in range(bound):
tidy(book, now, _alive)
for owner, scope in wants:
got = take(book, Lease("P", owner, 0.0, "", scope), TTL, now)
if got.lease is not None:
served.add((owner, scope))
assert _exclusive(book)
if served == set(wants):
break
now += gaps[round_no % len(gaps)]
assert served == set(wants)
@PROPS
@given(st.sets(st.sampled_from(("pkg:a", "pkg:b", "pkg:c", "pkg:d")), min_size=1))
def test_different_packages_are_all_granted_at_once(scopes: set[str]) -> None:
book = Book()
for i, scope in enumerate(sorted(scopes)):
got = take(book, Lease("P", f"o{i}", 0.0, "", scope), TTL, 0.0)
assert got.lease is not None
assert len(book.leases) == len(scopes)
assert book.tickets == []