diff --git a/docs/superpowers/contracts/phone-lease-fifo-queue-2026-11-21.json b/docs/superpowers/contracts/phone-lease-fifo-queue-2026-11-21.json new file mode 100644 index 00000000..d28e4511 --- /dev/null +++ b/docs/superpowers/contracts/phone-lease-fifo-queue-2026-11-21.json @@ -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" +} diff --git a/docs/superpowers/evidence/i3blocks-runtime-dir-fallback-2026-10-12.json b/docs/superpowers/evidence/i3blocks-runtime-dir-fallback-2026-10-12.json deleted file mode 100644 index b3a48b2b..00000000 --- a/docs/superpowers/evidence/i3blocks-runtime-dir-fallback-2026-10-12.json +++ /dev/null @@ -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" - ] -} diff --git a/docs/superpowers/evidence/phone-lease-fifo-queue-2026-11-21.json b/docs/superpowers/evidence/phone-lease-fifo-queue-2026-11-21.json new file mode 100644 index 00000000..75b91c95 --- /dev/null +++ b/docs/superpowers/evidence/phone-lease-fifo-queue-2026-11-21.json @@ -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= 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" + ] +} diff --git a/linux_configuration/fixes/fix_waifu2x.sh b/linux_configuration/fixes/fix_waifu2x.sh deleted file mode 100755 index 22163845..00000000 --- a/linux_configuration/fixes/fix_waifu2x.sh +++ /dev/null @@ -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 diff --git a/python_pkg/phone_lease/__init__.py b/python_pkg/phone_lease/__init__.py index 6db30257..16a869ea 100644 --- a/python_pkg/phone_lease/__init__.py +++ b/python_pkg/phone_lease/__init__.py @@ -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", diff --git a/python_pkg/phone_lease/_model.py b/python_pkg/phone_lease/_model.py new file mode 100644 index 00000000..a7bd532b --- /dev/null +++ b/python_pkg/phone_lease/_model.py @@ -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}" diff --git a/python_pkg/phone_lease/_queue.py b/python_pkg/phone_lease/_queue.py new file mode 100644 index 00000000..bff66469 --- /dev/null +++ b/python_pkg/phone_lease/_queue.py @@ -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 + # " " -> 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 diff --git a/python_pkg/phone_lease/lease.py b/python_pkg/phone_lease/lease.py index 411a6234..97b3a2c0 100644 --- a/python_pkg/phone_lease/lease.py +++ b/python_pkg/phone_lease/lease.py @@ -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:`` -- 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) diff --git a/python_pkg/phone_lease/ops.py b/python_pkg/phone_lease/ops.py index de269fea..69f3330a 100644 --- a/python_pkg/phone_lease/ops.py +++ b/python_pkg/phone_lease/ops.py @@ -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()))) diff --git a/python_pkg/phone_lease/owner.py b/python_pkg/phone_lease/owner.py index c48f6f1a..7708a23a 100644 --- a/python_pkg/phone_lease/owner.py +++ b/python_pkg/phone_lease/owner.py @@ -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:`` lives while that pid is a ``claude`` process (a reused pid + running anything else counts as dead); ``:`` lives while the pid + exists. ``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 diff --git a/python_pkg/phone_lease/tests/conftest.py b/python_pkg/phone_lease/tests/conftest.py new file mode 100644 index 00000000..37e15f3f --- /dev/null +++ b/python_pkg/phone_lease/tests/conftest.py @@ -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 diff --git a/python_pkg/phone_lease/tests/test_alive.py b/python_pkg/phone_lease/tests/test_alive.py new file mode 100644 index 00000000..5aee1a5c --- /dev/null +++ b/python_pkg/phone_lease/tests/test_alive.py @@ -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 diff --git a/python_pkg/phone_lease/tests/test_fifo.py b/python_pkg/phone_lease/tests/test_fifo.py new file mode 100644 index 00000000..8c037728 --- /dev/null +++ b/python_pkg/phone_lease/tests/test_fifo.py @@ -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") == [] diff --git a/python_pkg/phone_lease/tests/test_queue_props.py b/python_pkg/phone_lease/tests/test_queue_props.py new file mode 100644 index 00000000..efa7b8a0 --- /dev/null +++ b/python_pkg/phone_lease/tests/test_queue_props.py @@ -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 == []