pocketshell 0.4.45__tar.gz → 0.4.47__tar.gz

{pocketshell-0.4.45 → pocketshell-0.4.47}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pocketshell
-Version: 0.4.45
+Version: 0.4.47
 Summary: Unified server-side Python utility for the PocketShell Android client.
 Project-URL: Homepage, https://github.com/alexeygrigorev/pocketshell
 Project-URL: Issues, https://github.com/alexeygrigorev/pocketshell/issues
@@ -21,7 +21,7 @@ Requires-Python: >=3.11
 Requires-Dist: click>=8.2.0
 Requires-Dist: google-auth>=2.0.0
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: quse==0.0.14
+Requires-Dist: quse==0.0.15
 Requires-Dist: tmuxctl>=0.3.5
 Provides-Extra: dev
 Requires-Dist: pytest>=8.4.0; extra == 'dev'

{pocketshell-0.4.45 → pocketshell-0.4.47}/pyproject.toml

@@ -14,7 +14,7 @@ name = "pocketshell"
 # scripts/check-pypi-version.sh enforces the stamped value matches the tag;
 # scripts/check-version-coupling.sh enforces the derivation itself is
 # single-sourced. See tools/pocketshell/README.md ("Version coupling").
-version = "0.4.45"
+version = "0.4.47"
 description = "Unified server-side Python utility for the PocketShell Android client."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -43,16 +43,19 @@ dependencies = [
     # Usage backend + single source of truth for the unified provider schema
     # (issue #1318). Pinned exactly: `pocketshell usage --json` expects quse's
     # provider-keyed `--json` document and fails loudly on schema drift, so the
-    # version is frozen, not a range. The published 0.0.14 wheel is the
-    # five-provider legacy shape with `short_term` / `long_term` records. The
-    # host boundary translates those records into canonical `windows`; it also
-    # accepts a separate top-level `windows` producer contract for newer or
-    # custom producers, without treating that shape as PyPI 0.0.14 provenance.
-    # Canonical-only providers such as OpenCode Go belong to that separate
-    # contract, not to the published-wheel provider list. 0.0.13 (#2195)
-    # historically added the `grok` provider; 0.0.11 (#1564) labeled each
-    # Codex window from its actual `limit_window_seconds`.
-    "quse==0.0.14",
+    # version is frozen, not a range. The published 0.0.15 wheel (upstream
+    # a86959e, issue #2293) is the six-provider CANONICAL producer: every
+    # record already carries the top-level `windows` map the Android parser
+    # reads, so the host boundary only injects the provider key and forwards
+    # the record unchanged. #2283's `short_term` / `long_term` translation for
+    # the older wheel is hard-cut (D22) — a legacy-shaped record now fails
+    # loudly. 0.0.15 is also the first published wheel that reports the `go`
+    # provider (OpenCode on the Go backend), so the OpenCode Go quota finally
+    # reaches the Usage panel; it is a provider of the pinned wheel, not a
+    # separate producer contract. 0.0.13 (#2195) historically added the `grok`
+    # provider; 0.0.11 (#1564) labeled each Codex window from its actual
+    # `limit_window_seconds`.
+    "quse==0.0.15",
     # FCM HTTP v1 push delivery (#690): service-account OAuth2 bearer minting
     # for `pocketshell push` / the `usage --capture` reset-push send. Imported
     # lazily and fail-soft — a host without it (or without a Firebase
@@ -126,11 +129,16 @@ exclude = [
 ]
 
 [tool.uv]
+# CI and local frozen-sync checks use the same installer semantics. Bump this
+# deliberately together with .github/workflows/tests.yml and validate the
+# committed lock before merging.
+required-version = "==0.10.11"
 # Keep the lockfile's reproducibility cutoff project-local. The host may have
 # a rolling global `exclude-newer` policy that predates deliberately pinned
-# releases (quse 0.0.14 and tmuxctl 0.3.5); this exact value is also the
-# `uv.lock` options cutoff and must be used when checking this lock.
-exclude-newer = "2026-08-27T22:00:00Z"
+# releases (quse 0.0.15 and tmuxctl 0.3.5); this exact value is also the
+# `uv.lock` options cutoff and must be used when checking this lock. Moved
+# past quse 0.0.15's 2026-08-28T12:09:07Z PyPI upload for issue #2293.
+exclude-newer = "2026-08-28T22:00:00Z"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{pocketshell-0.4.45 → pocketshell-0.4.47}/src/pocketshell/cards.py

@@ -58,6 +58,12 @@ from __future__ import annotations
 import os
 import re
 import sys
+import base64
+import errno
+import fcntl
+import logging
+import tempfile
+from contextlib import contextmanager
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
@@ -67,6 +73,10 @@ import click
 
 # Permissions for the per-session card file (owner-only, matches tree.py).
 NEW_FILE_MODE = 0o600
+_LOGGER = logging.getLogger(__name__)
+_UNSUPPORTED_SYNC_ERRNOS = {errno.EINVAL, errno.ENOTSUP}
+if hasattr(errno, "EOPNOTSUPP"):
+    _UNSUPPORTED_SYNC_ERRNOS.add(errno.EOPNOTSUPP)
 
 # Default checklist card id used when ``--id`` is omitted: a session has exactly
 # one "default" checklist unless the agent names them, which keeps the common
@@ -107,7 +117,7 @@ class CardPaths:
     cards_dir: Path
 
     def session_file(self, session: str) -> Path:
-        return self.cards_dir / f"{_sanitise_session(session)}.yaml"
+        return self.cards_dir / f"{_encode_session(session)}.yaml"
 
 
 # Env override for the cards root, so tests (and a non-default deployment) can
@@ -136,16 +146,10 @@ def resolve_paths(
     return CardPaths(cards_dir=base_home / ".pocketshell" / "cards")
 
 
-def _sanitise_session(session: str) -> str:
-    """Sanitise a tmux session name into a safe single-path-segment filename.
-
-    tmux session names cannot contain whitespace but can contain ``/``, ``.``
-    etc.; replace anything outside ``[A-Za-z0-9._-]`` so the name maps to one
-    flat file (no traversal, no nested dirs).
-    """
-    safe = re.sub(r"[^A-Za-z0-9._-]+", "_", session.strip())
-    safe = safe.strip(".") or "session"
-    return safe
+def _encode_session(session: str) -> str:
+    """Reversibly encode a tmux session as one safe path segment."""
+    encoded = base64.urlsafe_b64encode(session.encode("utf-8")).decode("ascii")
+    return "s-" + encoded.rstrip("=")
 
 
 def _ensure_dir(path: Path) -> None:
@@ -156,25 +160,90 @@ def _ensure_dir(path: Path) -> None:
         pass
 
 
+def _durability_barrier(fd: int, *, path: Path, kind: str) -> bool:
+    """Fsync one file or directory, tolerating only unsupported barriers."""
+    while True:
+        try:
+            os.fsync(fd)
+            return True
+        except OSError as error:
+            if error.errno == errno.EINTR:
+                continue
+            if error.errno in _UNSUPPORTED_SYNC_ERRNOS:
+                _LOGGER.warning(
+                    "durability barrier unavailable for %s %s: %s; "
+                    "continuing with atomic publication",
+                    kind,
+                    path,
+                    error,
+                )
+                return False
+            raise
+
+
+def _fsync_directory(path: Path) -> bool:
+    """Fsync a directory after rename when the filesystem supports it."""
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
+    try:
+        fd = os.open(str(path), flags)
+    except OSError as error:
+        if error.errno in _UNSUPPORTED_SYNC_ERRNOS:
+            _LOGGER.warning(
+                "durability barrier unavailable for directory %s: %s; "
+                "continuing with atomic publication",
+                path,
+                error,
+            )
+            return False
+        raise
+    try:
+        return _durability_barrier(fd, path=path, kind="directory")
+    finally:
+        os.close(fd)
+
+
 def _write_private(path: Path, text: str) -> None:
-    """Write ``text`` to ``path`` atomically with mode 0600 (copied from tree.py)."""
+    """Publish ``text`` atomically with file and directory durability barriers."""
     _ensure_dir(path.parent)
-    tmp = path.with_name(path.name + ".tmp")
-    fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, NEW_FILE_MODE)
+    fd, tmp_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    tmp = Path(tmp_name)
+    open_fd = fd
     try:
-        with os.fdopen(fd, "w", encoding="utf-8") as handle:
-            handle.write(text)
+        with os.fdopen(fd, "wb") as handle:
+            open_fd = -1
+            handle.write(text.encode("utf-8"))
+            handle.flush()
+            os.chmod(tmp, NEW_FILE_MODE)
+            _durability_barrier(handle.fileno(), path=tmp, kind="file")
+        os.replace(tmp, path)
+        _fsync_directory(path.parent)
     except BaseException:
+        if open_fd >= 0:
+            try:
+                os.close(open_fd)
+            except OSError:
+                pass
         try:
-            os.unlink(tmp)
+            tmp.unlink()
         except FileNotFoundError:
             pass
+        except OSError:
+            pass
         raise
-    os.replace(tmp, path)
-    try:
-        os.chmod(path, NEW_FILE_MODE)
-    except FileNotFoundError:
-        pass
+
+
+@contextmanager
+def _session_lock(path: Path):
+    """Hold the cross-process advisory lock for one session document."""
+    _ensure_dir(path.parent)
+    lock_path = path.with_suffix(path.suffix + ".lock")
+    fd = os.open(str(lock_path), os.O_RDWR | os.O_CREAT, NEW_FILE_MODE)
+    with os.fdopen(fd, "a+") as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(lock, fcntl.LOCK_UN)
 
 
 # ---------------------------------------------------------------------------
@@ -427,9 +496,7 @@ def _import_yaml() -> Any:
     return yaml
 
 
-def read_cards(session: str, *, paths: CardPaths) -> list[dict[str, Any]]:
-    """Return the session's list of cards (empty when none / unreadable)."""
-    path = paths.session_file(session)
+def _read_cards_file(path: Path, session: str) -> list[dict[str, Any]]:
     try:
         raw = path.read_text(encoding="utf-8")
     except (FileNotFoundError, IsADirectoryError, PermissionError):
@@ -443,14 +510,28 @@ def read_cards(session: str, *, paths: CardPaths) -> list[dict[str, Any]]:
         return []
     if not isinstance(doc, Mapping):
         return []
+    if doc.get("session") != session:
+        return []
     cards = doc.get("cards")
     if not isinstance(cards, list):
         return []
     return [dict(c) for c in cards if isinstance(c, Mapping)]
 
 
+def read_cards(session: str, *, paths: CardPaths) -> list[dict[str, Any]]:
+    """Return the session's list of cards (empty when none / unreadable)."""
+    return _read_cards_file(paths.session_file(session), session)
+
+
 def write_cards(session: str, cards: list[dict[str, Any]], *, paths: CardPaths) -> Path:
     """Atomically persist the session's card list as YAML. Returns the path."""
+    path = paths.session_file(session)
+    with _session_lock(path):
+        _write_cards_file(path, session, cards)
+    return path
+
+
+def _write_cards_file(path: Path, session: str, cards: list[dict[str, Any]]) -> None:
     yaml = _import_yaml()
     doc = {
         "schema": 1,
@@ -459,9 +540,22 @@ def write_cards(session: str, cards: list[dict[str, Any]], *, paths: CardPaths)
         "cards": cards,
     }
     text = yaml.safe_dump(doc, sort_keys=False, default_flow_style=False)
-    path = paths.session_file(session)
     _write_private(path, text)
-    return path
+
+
+def _mutate_cards(
+    session: str,
+    *,
+    paths: CardPaths,
+    mutation: Callable[[list[dict[str, Any]]], Any],
+) -> tuple[Path, Any]:
+    """Apply one read-modify-write transaction under the session lock."""
+    path = paths.session_file(session)
+    with _session_lock(path):
+        cards = _read_cards_file(path, session)
+        result = mutation(cards)
+        _write_cards_file(path, session, cards)
+    return path, result
 
 
 # ---------------------------------------------------------------------------
@@ -513,11 +607,13 @@ def upsert_card(session: str, card: dict[str, Any], *, paths: CardPaths) -> Path
     Replace preserves nothing of the old card — a re-push of a checklist by the
     agent is a full replace (hard-cut semantics; the new list is authoritative).
     """
-    cards = read_cards(session, paths=paths)
-    card_id = card["id"]
-    cards = [c for c in cards if c.get("id") != card_id]
-    cards.append(card)
-    return write_cards(session, cards, paths=paths)
+    def mutate(cards: list[dict[str, Any]]) -> None:
+        card_id = card["id"]
+        cards[:] = [c for c in cards if c.get("id") != card_id]
+        cards.append(card)
+
+    path, _ = _mutate_cards(session, paths=paths, mutation=mutate)
+    return path
 
 
 def apply_interaction(
@@ -532,23 +628,20 @@ def apply_interaction(
     Raises :class:`ValueError` when the card id is not found in the session, or
     when the type's :meth:`apply_interaction` rejects the interaction.
     """
-    cards = read_cards(session, paths=paths)
-    target: Optional[dict[str, Any]] = None
-    for card in cards:
-        if card.get("id") == card_id:
-            target = card
-            break
-    if target is None:
-        raise ValueError(f"no card with id {card_id!r} in session {session!r}")
-    handler = get_card_type(target.get("type", ""))
-    if handler is None:
-        raise ValueError(f"card {card_id!r} has unknown type {target.get('type')!r}")
-    body = target.get("body", {}) if isinstance(target.get("body"), Mapping) else {}
-    state = target.get("state", {}) if isinstance(target.get("state"), Mapping) else {}
-    new_state = handler.apply_interaction(dict(body), dict(state), interaction)
-    target["state"] = new_state
-    target["updated_at"] = _now_iso()
-    write_cards(session, cards, paths=paths)
+    def mutate(cards: list[dict[str, Any]]) -> dict[str, Any]:
+        target = next((card for card in cards if card.get("id") == card_id), None)
+        if target is None:
+            raise ValueError(f"no card with id {card_id!r} in session {session!r}")
+        handler = get_card_type(target.get("type", ""))
+        if handler is None:
+            raise ValueError(f"card {card_id!r} has unknown type {target.get('type')!r}")
+        body = target.get("body", {}) if isinstance(target.get("body"), Mapping) else {}
+        state = target.get("state", {}) if isinstance(target.get("state"), Mapping) else {}
+        target["state"] = handler.apply_interaction(dict(body), dict(state), interaction)
+        target["updated_at"] = _now_iso()
+        return target
+
+    _, target = _mutate_cards(session, paths=paths, mutation=mutate)
     return target
 
 

{pocketshell-0.4.45 → pocketshell-0.4.47}/src/pocketshell/daemon.py

@@ -56,6 +56,7 @@ versions when available) without RPC parameters or command output.
 from __future__ import annotations
 
 import json
+import fcntl
 import logging
 import os
 import re
@@ -356,6 +357,13 @@ def resolve_pid_path(socket_path: Optional[Path] = None) -> Path:
     return socket_path.with_suffix(".pid")
 
 
+def resolve_lock_path(socket_path: Optional[Path] = None) -> Path:
+    """Return the lifetime-ownership lock beside the daemon socket."""
+    if socket_path is None:
+        socket_path = resolve_socket_path()
+    return socket_path.with_suffix(".lock")
+
+
 def _ensure_socket_dir(socket_path: Path) -> None:
     """Create the socket's parent dir with mode 0700 if missing."""
     parent = socket_path.parent
@@ -890,6 +898,10 @@ class _RpcError(Exception):
         self.data = data
 
 
+class _DaemonAlreadyOwned(Exception):
+    """Another daemon holds the socket's lifetime lock."""
+
+
 class Daemon:
     """Unix-socket JSON-RPC 2.0 server for ``pocketshell`` subcommands.
 
@@ -922,6 +934,7 @@ class Daemon:
         self._cache = _Cache(clock=clock)
         self._clock = clock
         self._server_sock: Optional[socket.socket] = None
+        self._lifecycle_lock: Optional[Any] = None
         self._stop_event = threading.Event()
         self._last_activity = self._clock()
 
@@ -934,9 +947,17 @@ class Daemon:
 
     def _bind(self) -> socket.socket:
         _ensure_socket_dir(self.socket_path)
-        # Always unlink first. If a previous daemon crashed without
-        # cleanup the path is a dead file; bind() would fail with
-        # EADDRINUSE. Recreating cleanly is the documented self-heal.
+        lock_path = resolve_lock_path(self.socket_path)
+        lock_fd = os.open(str(lock_path), os.O_RDWR | os.O_CREAT, 0o600)
+        lock = os.fdopen(lock_fd, "a+")
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            lock.close()
+            raise _DaemonAlreadyOwned
+        self._lifecycle_lock = lock
+
+        # Only the lifetime-lock owner may replace a proven stale endpoint.
         try:
             os.unlink(self.socket_path)
         except FileNotFoundError:
@@ -948,9 +969,14 @@ class Daemon:
         # process umask (no fchmod hook on AF_UNIX at bind time).
         old_umask = os.umask(0o077)
         try:
-            sock.bind(str(self.socket_path))
-        finally:
-            os.umask(old_umask)
+            try:
+                sock.bind(str(self.socket_path))
+            finally:
+                os.umask(old_umask)
+        except BaseException:
+            sock.close()
+            self._release_lifecycle_lock()
+            raise
         sock.listen(8)
         # Defence in depth: chmod the socket explicitly in case some
         # platform ignored the umask.
@@ -994,7 +1020,10 @@ class Daemon:
         Idle timeout 0 disables the idle exit (used by future systemd
         ``Type=simple`` always-on mode).
         """
-        self._server_sock = self._bind()
+        try:
+            self._server_sock = self._bind()
+        except _DaemonAlreadyOwned:
+            return
         self._write_pid_file()
         self._last_activity = self._clock()
         # Trap SIGTERM so `daemon stop` (and systemd Stop) shuts us
@@ -1057,6 +1086,17 @@ class Daemon:
             self._server_sock = None
         self._remove_socket_file()
         self._remove_pid_file()
+        self._release_lifecycle_lock()
+
+    def _release_lifecycle_lock(self) -> None:
+        lock = self._lifecycle_lock
+        if lock is None:
+            return
+        self._lifecycle_lock = None
+        try:
+            fcntl.flock(lock, fcntl.LOCK_UN)
+        finally:
+            lock.close()
 
     # -- request handling ------------------------------------------------
 
@@ -1647,15 +1687,10 @@ def stop_daemon(
 ) -> bool:
     """Stop a running daemon and remove its socket.
 
-    Strategy:
-
-    1. If a PID file exists, ``os.kill(pid, SIGTERM)`` — clean shutdown
-       via the signal handler.
-    2. Wait up to ``timeout`` seconds for the socket file to disappear.
-    3. Fall through to the RPC ``daemon.shutdown`` method if the PID
-       file is missing (legacy or test-spawned daemons).
-    4. Always remove a stale socket file at the end so the next start
-       has a clean slate.
+    A responsive socket proves daemon identity, so shutdown always goes over
+    RPC. A numeric PID file alone is never trusted: the OS may have reused a
+    stale PID for an unrelated process. Stale paths are removed only while
+    holding the same exclusive lifetime lock used by startup.
 
     Returns ``True`` if a daemon was running and is now stopped,
     ``False`` if no daemon was running.
@@ -1663,41 +1698,45 @@ def stop_daemon(
     socket_path = socket_path or resolve_socket_path()
     pid_path = resolve_pid_path(socket_path)
 
-    pid = read_pid(pid_path)
     was_running = is_daemon_running(socket_path)
 
-    if pid is not None:
-        try:
-            os.kill(pid, signal.SIGTERM)
-        except ProcessLookupError:
-            pid = None
-        except PermissionError:
-            pid = None
-
-    if was_running and pid is None:
-        # No PID file or kill failed; try the RPC shutdown instead.
+    if was_running:
         try:
             call("daemon.shutdown", socket_path=socket_path, timeout=timeout)
         except (DaemonClientError, RuntimeError, OSError):
             pass
 
-    # Wait for the socket file to disappear.
-    deadline = time.monotonic() + timeout
-    while time.monotonic() < deadline:
-        if not socket_path.exists():
-            break
-        time.sleep(0.05)
-
-    # Final cleanup: remove the socket if the daemon did not clean up
-    # itself (SIGKILL recovery).
-    try:
-        os.unlink(socket_path)
-    except FileNotFoundError:
-        pass
+    if was_running:
+        # Give the proven daemon time to remove its owned paths. A stale,
+        # unresponsive socket has nobody to wait for and proceeds directly to
+        # ownership-locked cleanup below.
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if not socket_path.exists():
+                break
+            time.sleep(0.05)
+
+    # Clean stale metadata only if no daemon owns the lifecycle lock. Re-probe
+    # after acquiring it so a concurrent startup cannot be mistaken for stale.
+    _ensure_socket_dir(socket_path)
+    lock_fd = os.open(str(resolve_lock_path(socket_path)), os.O_RDWR | os.O_CREAT, 0o600)
+    lock = os.fdopen(lock_fd, "a+")
     try:
-        pid_path.unlink()
-    except FileNotFoundError:
-        pass
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            return was_running
+        if not is_daemon_running(socket_path):
+            try:
+                os.unlink(socket_path)
+            except FileNotFoundError:
+                pass
+            try:
+                pid_path.unlink()
+            except FileNotFoundError:
+                pass
+    finally:
+        lock.close()
 
     return was_running