executor

executor

Carrying out a verified command on THIS device.

By the time anything here runs, the command has already survived every check of spec §9. What remains is the narrowest possible action — and the discipline of spec §34: a remote tool never touches storage directly, it asks the same services the local UI asks. Otherwise the mesh becomes a second source of truth, and the two drift.

Screens are opened by publishing an event the desktop shell listens to, not by driving the window from here: the app already knows how to route success://…, and duplicating that knowledge would guarantee the two disagree eventually.

Classes

Functions:

push_shell_event

push_shell_event(entry: dict[str, Any]) -> bool

Queue one verified event for the shell. False when the queue is full.

It used to evict the OLDEST — del _pending[:-_MAX_PENDING] — and say nothing. Those oldest entries had already been answered SUCCESS to the device that sent them, so dropping them turned a past promise into a lie after the fact, and nothing anywhere recorded it.

flush_pending delivers up to twenty commands per device in one tick (dispatch.limit_per_device) while this queue holds sixteen, so the case is reachable the moment a peer comes back from an hour offline.

Refusing the NEWEST is the only policy under which every SUCCESS already handed out stays true. The new command gets an honest failure instead, which its sender can act on — the evicted ones could not.

Source code in src/diapason/mesh/executor.py

def push_shell_event(entry: dict[str, Any]) -> bool:
    """Queue one verified event for the shell. False when the queue is full.

    It used to evict the OLDEST — `del _pending[:-_MAX_PENDING]` — and say
    nothing. Those oldest entries had already been answered SUCCESS to the
    device that sent them, so dropping them turned a past promise into a lie
    after the fact, and nothing anywhere recorded it.

    `flush_pending` delivers up to twenty commands per device in one tick
    (`dispatch.limit_per_device`) while this queue holds sixteen, so the case
    is reachable the moment a peer comes back from an hour offline.

    Refusing the NEWEST is the only policy under which every SUCCESS already
    handed out stays true. The new command gets an honest failure instead,
    which its sender can act on — the evicted ones could not.
    """
    if len(_pending) >= _MAX_PENDING:
        logger.warning(
            "shell queue full (%d): refusing a new entry rather than "
            "dropping one already answered SUCCESS",
            _MAX_PENDING,
        )
        return False
    _pending.append(entry)
    return True

push_navigation

push_navigation(entry: dict[str, Any]) -> bool

Backward-compatible name for screen and notification events.

Source code in src/diapason/mesh/executor.py

def push_navigation(entry: dict[str, Any]) -> bool:
    """Backward-compatible name for screen and notification events."""
    return push_shell_event(entry)

pending_navigations

pending_navigations(
    *, drain: bool = True
) -> list[dict[str, Any]]

What the shell should open, oldest first.

A draining read is the ONLY evidence this process has that a window is attached: nothing registers, nothing announces itself, the shell simply polls. drain=False is a diagnostic read and deliberately does not count — looking is not collecting, and a debugging curl must not make the machine believe someone is watching the screen.

Source code in src/diapason/mesh/executor.py

def pending_navigations(*, drain: bool = True) -> list[dict[str, Any]]:
    """What the shell should open, oldest first.

    A draining read is the ONLY evidence this process has that a window is
    attached: nothing registers, nothing announces itself, the shell simply
    polls. `drain=False` is a diagnostic read and deliberately does not count
    — looking is not collecting, and a debugging `curl` must not make the
    machine believe someone is watching the screen.
    """
    global _last_collection_ms
    items = list(_pending)
    if drain:
        _last_collection_ms = now_ms()
        _pending.clear()
    return items

shell_is_collecting

shell_is_collecting(*, now: int | None = None) -> bool

Has a window emptied the queue recently enough to still be there?

26 August 2026. Every handler below used to push an entry onto _pending and return a sentence in the past tense — "Notification affichée.", "L'élément est affiché." — having displayed precisely nothing. The only code that displays anything is the React shell polling /v1/mesh/inbox.

It cost a real evening: a Windows PC ran the Python server with no window open at all. Notifications sent from the Mac were answered SUCCESS / "Notification affichée.", recorded as such on both machines, while the entries sat in _pending until the seventeenth pushed the first out silently. Nobody saw a thing, and every screen said otherwise (§100).

This does not prove the notification WILL be shown — the shell could be denied permission by the OS a second later. It proves the far more useful negative: that nobody is there to show it.

Source code in src/diapason/mesh/executor.py

def shell_is_collecting(*, now: int | None = None) -> bool:
    """Has a window emptied the queue recently enough to still be there?

    26 August 2026. Every handler below used to push an entry onto `_pending`
    and return a sentence in the past tense — "Notification affichée.",
    "L'élément est affiché." — having displayed precisely nothing. The only
    code that displays anything is the React shell polling `/v1/mesh/inbox`.

    It cost a real evening: a Windows PC ran the Python server with no window
    open at all. Notifications sent from the Mac were answered SUCCESS /
    "Notification affichée.", recorded as such on both machines, while the
    entries sat in `_pending` until the seventeenth pushed the first out
    silently. Nobody saw a thing, and every screen said otherwise (§100).

    This does not prove the notification WILL be shown — the shell could be
    denied permission by the OS a second later. It proves the far more useful
    negative: that nobody is there to show it.
    """
    if _last_collection_ms is None:
        return False
    return (now if now is not None else now_ms()) - _last_collection_ms < (
        _COLLECTION_WINDOW_MS
    )