@vibelord/lanes 1.0.0

package/payload/lanes/libexec/statusd.py

@@ -0,0 +1,764 @@
+#!/usr/bin/env python3
+"""lanes status daemon: observes lanes, never touches them.
+
+Every few seconds: find LIVE tmux servers via `ps` (dead sockets are never probed), run one read-only
+`list-panes -a` per live server that the registry references, and publish ~/.local/state/lanes/status.json
+atomically, plus the one-line ~/.local/state/lanes/health. The sidebar, `lanes status`, `lanes doctor` and the
+future Throttle web harness all read those files.
+
+It never INVENTS a state. "No answer" (a tmux, ps, docker or zmx call that timed out or failed on an overloaded
+host) is not an observation: the lane keeps its last published state, marked stale, for at most STALE_MAX seconds
+and is 'unknown' after that. 'absent' / 'missing' are only published when a server answered without the session,
+or positively does not exist.
+"""
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import lanes_lib as L  # noqa: E402
+import session_actions as A  # noqa: E402
+import legacy_sessions as Legacy  # noqa: E402
+
+INTERVAL = float(os.environ.get('LANES_STATUS_INTERVAL', '3'))
+SLOWDOWN = {'ok': 1, 'busy': 2, 'critical': 4}   # a host under pressure gets FEWER spawns from us, not the same
+HEARTBEAT = 15          # status.json is rewritten at least this often, so its age proves that statusd is alive
+PROBE_TIMEOUT = 5
+CONTAINER_REFRESH = 300  # docker is asked again this often as a safety net; liveness itself comes from /proc/<pid>
+CONTAINER_RETRY = 30     # ... and at most this often while a container is down or docker did not answer
+ACTIVE_WINDOW = 20  # seconds since last output for a lane to count as active
+STALE_MAX = 300     # a lane nobody could observe for this long is published as 'unknown', no longer as last seen
+FIELDS = ['session_name', 'pane_pid', 'pane_dead', 'window_activity', 'pane_current_command',
+          'pane_current_path', 'window_width', 'window_height', 'session_attached', 'pane_tty',
+          'session_id', 'session_created',
+          # Alignment contract A4a: the group a session is attached onto (a Throttle Studio browser view is a
+          # grouped session), and which pane of which window represents the session's state.
+          'session_group', 'pane_active', 'window_active']
+FORMAT = '\t'.join('#{' + f + '}' for f in FIELDS)
+VIEW_PREFIX = 'view-'   # a Throttle Studio browser attach: a grouped session named view-<studio>-<ch>
+
+
+def log(where, error):
+    print(time.strftime('%FT%T'), where, type(error).__name__, error, flush=True)
+
+
+# ------------------------------------------------- the viewer rule (A4a)
+# A Throttle Studio browser attaches with `new-session -t <lane> -s view-<studio>-<ch>`: an independent
+# current window on the lane's windows. Such a session is a CLIENT of the lane, not a lane of its own, and
+# both surfaces must say so — the Host mirrors these three functions in `studio_host::tmux`. Pure, so the
+# rule is unit-testable without a server.
+
+
+def viewer_of(name, group, leaders):
+    """The lane session that live session `name` VIEWS, or None when it is a session in its own right.
+
+    A viewer is a tmux session GROUPED onto a group whose LEADER (`leaders`, see `group_leaders`) is a
+    DIFFERENT session — declared or not, so a browser on an undeclared Studio-started `st_<board>_<slug>`
+    lane is that lane's viewer too. Viewers are counted in the viewed lane's `attached`/`viewers`, never
+    listed as unregistered ghosts (the old `web-<ch>` spelling was, which is the defect this rule closes).
+    The value returned is the LEADER's session name, which is the group's name while that leader lives and
+    the oldest survivor's name once it does not.
+
+    The `view-` NAME alone is deliberately NOT enough, and these shapes must stay VISIBLE because nothing
+    alive may be hidden: an operator's own ungrouped `tmux new -s view-notes`, and the oldest survivor of a
+    group whose lane was killed under it, whose panes are still running. Both fall through to the 👻 list."""
+    leader = leaders.get(group) if group and group != name else None
+    return leader if leader is not None and leader != name else None
+
+
+def group_leaders(sessions):
+    """group name -> the live session that LEADS it, for the viewer rule. Mirrors the Host's
+    `inventory::group_leader` exactly, so the two surfaces cannot partition one listing differently.
+
+    tmux reports a leader's `#{session_group}` as its own name (and a session with no grouped member reports
+    no group at all), so the live leader is the first answer. When the named leader is GONE — a lane killed
+    under an attached browser, or killed and RECREATED (the recreated session reports NO group while the old
+    members still name it) — the group's OLDEST surviving member stands in, ties broken by name so both
+    surfaces choose the same one. Without the stand-in a Studio attach onto such a survivor produced a second
+    member of one leaderless group that NEITHER member could be seen to view, so the browser's own
+    `view-<studio>-<ch>` was drawn here as an openable 👻 while the Host counted it as a viewer (DEF-901;
+    the Host half landed in review round 5, this half in round 6, DEF-913)."""
+    def created(name):
+        try:
+            return int(sessions[name].get('session_created') or 0)
+        except (TypeError, ValueError):
+            return 0
+
+    leaders = {}
+    for group in {row.get('session_group') for row in sessions.values() if row.get('session_group')}:
+        row = sessions.get(group)
+        if row is not None and row.get('session_group') == group:
+            leaders[group] = group
+            continue
+        members = [name for name, member in sessions.items() if member.get('session_group') == group]
+        if members:
+            leaders[group] = min(members, key=lambda name: (created(name), name))
+    return leaders
+
+
+def split_viewers(sessions, registered=()):
+    """(lanes, viewers): the live sessions that are lanes in their own right, and per viewed lane session the
+    list of viewer session rows. `sessions` maps session_name -> its chosen `list-panes` row.
+
+    A DECLARED session (`registered`) is always a lane of its own, whatever it is grouped onto: an operator
+    can bind two declared lanes with tmux's own `new-session -t <other-lane> -s <name>`, and filing the second
+    one as a viewer published the registry's own row `absent` while its session was alive and attached — where
+    the Host's declared branch (`inventory::derive_status`) reads that session's panes and says `active`.
+    Only UNDECLARED grouped members are viewers (DEF-914)."""
+    leaders = group_leaders(sessions)
+    lanes, viewers = {}, {}
+    for name, row in sessions.items():
+        viewed = None if name in registered else viewer_of(name, row.get('session_group', ''), leaders)
+        if viewed is None:
+            lanes[name] = row
+        else:
+            viewers.setdefault(viewed, []).append(row)
+    return lanes, viewers
+
+
+def session_row(rows):
+    """The one `list-panes -a` row that represents a session: the ACTIVE pane of its ACTIVE window, else the
+    first listed row. The Host reads the same pane (`inventory::dead_active_pane`), so `dead` cannot mean one
+    thing in the sidebar and another in the Studio for a multi-window lane."""
+    for row in rows:
+        if row.get('window_active') == '1' and row.get('pane_active') == '1':
+            return row
+    return rows[0]
+
+
+def newest_activity(rows):
+    """The newest `window_activity` across a session's panes — the same reading as the Host's
+    `inventory::newest_window_activity`. An agent working in window 1 keeps the lane `active` in BOTH
+    surfaces while window 0 idles."""
+    newest = 0
+    for row in rows:
+        try:
+            newest = max(newest, int(row['window_activity']))
+        except (KeyError, ValueError):
+            continue
+    return newest
+
+
+def tmux_token(board):
+    """A board id as the Throttle Studio Host spells it inside a session name (`tmux::tmux_token`): anything
+    outside [A-Za-z0-9_-] becomes `_`. Every board id in the operator's registry is already [a-z-], so this
+    only matters for an id carrying a `.` or a `:` — where matching the raw id alone would never fire."""
+    return ''.join(c if (c.isascii() and (c.isalnum() or c in '_-')) else '_' for c in board)
+
+
+def board_named_by(name, boards):
+    """The board an UNDECLARED session NAMES, or None. A Studio-started lane is `st_<board>_<slug>` and a
+    Studio browser view is `view-<board>-<ch>` (contract A2/A5), both in the Host's own spelling
+    (`tmux_token`). Used only as the PREFERENCE handed to `session_actions.workspace_for`, which still
+    decides; a session that names no board is attributed by its working directory as before."""
+    for board in sorted(boards):
+        for spelling in {board, tmux_token(board)}:
+            if name.startswith(f'st_{spelling}_') or name.startswith(f'{VIEW_PREFIX}{spelling}-'):
+                return board
+    return None
+
+
+def live_tmux_sockets():
+    """Socket names (-L) of running tmux servers, from the process table only.
+    None = ps did not answer: the caller must then NOT conclude that any server is gone."""
+    rc, out, _err = L.run_bounded(['ps', '-eo', 'comm=,args='], 10)
+    if rc != 0:
+        return None
+    names = set()
+    for line in out.splitlines():
+        if not line.startswith('tmux: server'):
+            continue
+        parts = line.split()
+        for index, part in enumerate(parts):
+            if part == '-L' and index + 1 < len(parts):
+                names.add(parts[index + 1])
+    return names
+
+
+def keep(previous, lane_id, outcome):
+    """What to publish for a lane that could not be observed: its last published entry, marked stale — or
+    'unknown' when there is none, or once it has gone unobserved for STALE_MAX. Never 'absent' / 'missing'.
+    'stale_since' is set once and then carried along, so a kept entry is identical from cycle to cycle (no
+    rewrite of status.json, no sidebar repaint) until the one change to 'unknown'."""
+    old = (previous.get('lanes') or {}).get(lane_id) or {}
+    now = time.time()
+    since = old.get('stale_since')
+    since = since if isinstance(since, (int, float)) else int(now)
+    if old.get('state') in (None, 'unknown') or now - since > STALE_MAX:
+        return {'state': 'unknown', 'observed': outcome}
+    # 'active' is the one state that is a claim about NOW (output in the last 20 s): never true of a cached entry,
+    # and the one that readers which know nothing about 'stale' count and draw green. 'idle' is the seventh word
+    # a pre-DEF-823 statusd published for a zmx lane: a status.json written by that build seeds `new_context()`
+    # across the upgrade, so it is normalised here rather than drawn as an unknown glyph by the sidebar.
+    state = 'quiet' if old['state'] in ('active', 'idle') else old['state']
+    return dict(old, state=state, stale=True, observed=outcome, stale_since=since)
+
+
+def lane_entry(pane, now, activity=None, viewing=()):
+    """One live session's published row. `activity` is the NEWEST `window_activity` across the session's panes
+    (see `newest_activity`) and `viewing` the rows of the sessions that VIEW it (see `split_viewers`); both
+    default to "this pane alone", which is what a caller with a single row has."""
+    if activity is None:
+        try:
+            activity = int(pane['window_activity'])
+        except ValueError:
+            activity = 0
+    if pane['pane_dead'] == '1':
+        state = 'dead'
+    # INCLUSIVE, on the integer second: `#{window_activity}` is whole seconds, this daemon's clock is a float,
+    # and the Host compares integer seconds with `age <= ACTIVE_WINDOW_SECS` (`inventory::from_window_activity`).
+    # A strict float `<` made a lane exactly ACTIVE_WINDOW seconds idle `quiet` here and `active` in the Studio
+    # (DEF-885, re-lost to the #347 merge and re-landed as DEF-932).
+    elif int(now) - activity <= ACTIVE_WINDOW:
+        state = 'active'
+    else:
+        state = 'quiet'
+    entry = {'state': state, 'activity': activity, 'command': pane['pane_current_command'],
+             'cwd': pane['pane_current_path'], 'pid': int(pane['pane_pid'] or 0),
+             'size': f"{pane['window_width']}x{pane['window_height']}",
+             # Clients on the session itself plus the clients of every session that views it.
+             'attached': int(pane['session_attached'] or 0)
+             + sum(int(row.get('session_attached') or 0) for row in viewing),
+             'tty': pane['pane_tty']}
+    if viewing:   # skipped when 0, so a lane nobody views publishes byte-identically to before A4a
+        entry['viewers'] = len(viewing)
+    return entry
+
+
+def probe_server(info, socket, live):
+    if not info.get('pid'):
+        # Only a docker inspect that ANSWERED "pid 0" says the container is down. No record at all, or one that
+        # carries an error (docker did not answer) = nobody knows.
+        return ('noserver' if info and not info.get('error') else 'error'), ''
+    if live is not None and socket not in live:
+        return 'noserver', ''   # ps answered and lists no such server: a stale socket file is never probed
+    if (live is not None and info.get('running', True) and os.path.exists(f"{L.proc_root()}/{info['pid']}")
+            and not os.path.exists(L.tmux_socket(info, socket))):
+        # (container init alive: a container that went DOWN takes its sockets along and is 'missing', not this)
+        # The server process runs but its socket file is gone: somebody emptied the container's /tmp (2026-09-20,
+        # 04:24: every lane alive, every viewer saying "not running"). Nothing can be asked, nothing died.
+        return 'nosocket', ''
+    return L.tmux_probe(info, socket, ['list-panes', '-a', '-F', FORMAT], timeout=PROBE_TIMEOUT)
+
+
+def discovered_sockets(containers, live):
+    """Every LIVE `IDENT`-named tmux socket file in these workspace containers, as (container, socket).
+
+    The one discovery rule, read by `observe` (which lists their sessions as unregistered rows) and by
+    `reconcile_client_sizes` (which owes those sessions the same size policy — a lanes view can show any row
+    the sidebar draws, and the sockets a Studio-started lane may land on are by construction ones no
+    declaration names). Never starts a server to ask whether one exists: a socket file that is not in `live`
+    (statusd's process-table reading) is not probed.
+    """
+    found = []
+    for container, info in containers.items():
+        if not info.get('pid'):
+            continue
+        directory = Path(L.tmux_socket(info, 'discovery')).parent
+        try:
+            for path in sorted(directory.iterdir()):
+                if L.IDENT.fullmatch(path.name) and path.is_socket() and (live is None or path.name in live):
+                    found.append((container, path.name))
+        except OSError:
+            pass
+    return found
+
+
+def observe(registry, containers, live, previous=None):
+    """previous = the last published payload: what a lane keeps when its server gave no answer this time."""
+    previous = previous or {}
+    now = time.time()
+    lanes, servers, unregistered = {}, {}, {}
+    wanted, owners, counts = {}, {}, {}
+    for workspace in registry['workspaces']:
+        for lane in workspace['lanes']:
+            if lane['holder'] == 'tmux':
+                key = (lane['container'], lane['tmux']['socket'])
+                wanted.setdefault(key, []).append(lane)
+                owners.setdefault(key, set()).add(workspace['id'])
+                counts.setdefault(key, {})
+                counts[key][workspace['id']] = counts[key].get(workspace['id'], 0) + 1
+    prior = {}
+    for workspace_id, entries in (previous.get('unregistered') or {}).items():
+        for entry in entries:
+            if entry.get('holder') != 'tmux':
+                continue
+            key = A.session_key(entry)
+            # One session is ONE entry, listed in every owner's sidebar, so the board it was ATTRIBUTED to is
+            # the one it carries — not whichever listing this loop reached last.
+            #
+            # `shared` marks the verdict "no board could claim this one", and it is NOT a preference: the
+            # board such an entry carries was minted by the tally rule to own its id, and handing THAT back to
+            # `workspace_for` as the preference made it claimable on the next cycle (`preferred in by_id`
+            # returns at once) — so the multi-owner listing lasted exactly one INTERVAL and every other
+            # owner's sidebar lost the row again, the very drop DEF-915 closed (DEF-976). The verdict is
+            # recomputed from scratch each cycle instead; the id stays the one `old` carries.
+            prior[key] = (None if entry.get('shared') else (entry.get('workspace') or workspace_id), entry)
+            wanted.setdefault(key[:2], [])
+    # Discovery covers every live socket in these workspace containers, including shared/default
+    # servers and servers with no registered lane. Never start a server to ask whether it exists.
+    for key in discovered_sockets(containers, live):
+        wanted.setdefault(key, [])
+    for (container, socket), members in wanted.items():
+        info = containers.get(container) or {}
+        rows_by_session = {}
+        # One server (or one odd row) must not cost the other servers their cycle: whatever goes wrong in here
+        # ends as "no answer from THIS server".
+        try:
+            outcome, text = probe_server(info, socket, live)
+            for row in text.splitlines() if outcome == 'ok' else []:
+                values = dict(zip(FIELDS, row.split('\t')))
+                rows_by_session.setdefault(values['session_name'], []).append(values)
+        except Exception as error:
+            log(f'observe {container}/{socket}', error)
+            outcome, rows_by_session = 'error', {}
+        # A4a: every session is read through its ACTIVE pane and its NEWEST window activity, the same two
+        # readings the Host makes, so `dead`/`active` cannot mean one thing per surface on a multi-window lane.
+        sessions = {name: session_row(rows) for name, rows in rows_by_session.items()}
+        activities = {name: newest_activity(rows) for name, rows in rows_by_session.items()}
+        # ... and an UNDECLARED session grouped onto another live session is that session's viewer, not a lane.
+        registered = {lane['tmux']['session'] for lane in members}
+        own_sessions, viewers = split_viewers(sessions, registered)
+        answered = outcome in ('ok', 'noserver')
+        last = (previous.get('servers') or {}).get(f'{container}/{socket}') or {}
+        servers[f'{container}/{socket}'] = {'live': outcome == 'ok' if answered else last.get('live'),
+                                            'sessions': len(own_sessions) if answered else last.get('sessions', 0),
+                                            'outcome': outcome}
+        if not answered:
+            # The sessions nobody registered stay visible as well while their server does not answer.
+            for workspace_id, entries in (previous.get('unregistered') or {}).items():
+                for entry in entries:
+                    if entry.get('container') == container and (entry.get('tmux') or {}).get('socket') == socket:
+                        unregistered.setdefault(workspace_id, []).append(entry)
+                        lanes[entry['id']] = keep(previous, entry['id'], outcome)
+        if own_sessions:
+            # Nothing that is alive may be invisible: list sessions no registry mentions — except a VIEWER of a
+            # session on this socket (a grouped attach, Throttle Studio's `view-…` among them), which is that
+            # session's client, not a ghost.
+            for name in sorted(set(own_sessions) - registered):
+                try:
+                    pane = own_sessions[name]
+                    old_ws, old = prior.get((container, socket, name), (None, None))
+                    board_ids = {w['id'] for w in registry['workspaces']}
+                    workspace_id = A.workspace_for(registry, container, socket, pane['pane_current_path'],
+                                                   owners.get((container, socket), set()),
+                                                   old_ws or board_named_by(name, board_ids))
+                    listed = [workspace_id] if workspace_id else []
+                    if not workspace_id:
+                        # `workspace_for` proved no single board: several declare lanes on this socket and the
+                        # session names none of them and sits under no board's roots. Dropping it (main's rule,
+                        # taken back wholesale by the #347 merge) is the one thing this daemon may not do —
+                        # "nothing alive is ever hidden" — so it is listed in EVERY owner's sidebar, with its
+                        # id owned by the board declaring the most lanes on the socket, ties by name. ONE
+                        # session stays ONE id, ONE resolve file and ONE status row however many boards show
+                        # it (DEF-884, re-lost to the merge and re-landed as DEF-915).
+                        share = sorted(owners.get((container, socket)) or ()) or sorted(
+                            w['id'] for w in registry['workspaces']
+                            if w.get('container') == container
+                            or any(x.get('container') == container for x in w.get('lanes', [])))
+                        if not share:
+                            log(f'unassigned {container}/{socket}/{name}',
+                                ValueError(pane['pane_current_path']))
+                            continue
+                        tally = counts.get((container, socket), {})
+                        workspace_id = min(share, key=lambda x: (-tally.get(x, 0), x))
+                        listed = share
+                    entry = A.make_entry(workspace_id, container, socket, name, pane, old)
+                    if len(listed) > 1:
+                        # The verdict, carried on the entry so the NEXT cycle does not read the tally winner
+                        # as a board that claimed it (DEF-976). Readers of status.json see one more key on a
+                        # row they already had; the sidebar draws the row, never this field.
+                        entry['shared'] = True
+                    # A name outside the DECLARATION grammar (`(`, `)`, `/`, `,` — the `<name> (drain)` twins
+                    # among them) is listed like any other ghost, not dropped: the grammar governs what may be
+                    # DECLARED, never what may be SEEN, and `holders/tmux.sh` opens the raw name with
+                    # `-t "=$session"` (its own gate admits exactly what tmux itself accepts, DEF-891), and
+                    # `session_actions.close_session` closes it by session id (DEF-916). The `note` is carried
+                    # in status.json for readers of the document; no surface draws it today, and neither the
+                    # RUNBOOK nor the design doc may promise that it does.
+                    if not L.TMUX_SESSION.match(name):
+                        entry['note'] = 'session name outside the lane declaration grammar'
+                    found = lane_entry(pane, now, activities.get(name), viewers.get(name, []))
+                except Exception as error:
+                    log(f'observe {container}/{socket}/{name}', error)
+                    continue
+                for board_id in listed:
+                    unregistered.setdefault(board_id, []).append(entry)
+                lanes[entry['id']] = found
+        for lane in members:
+            session = lane['tmux']['session']
+            pane = own_sessions.get(session)
+            if not answered:
+                lanes[lane['id']] = keep(previous, lane['id'], outcome)
+            elif pane is None:
+                # 'absent' = the container is up but this session (or its whole tmux server) does not
+                # exist right now, e.g. a completed orchestrator turn; 'missing' = the container is down.
+                lanes[lane['id']] = {'state': 'absent' if info.get('running') else 'missing'}
+            else:
+                try:
+                    lanes[lane['id']] = lane_entry(pane, now, activities.get(session), viewers.get(session, []))
+                except Exception as error:   # a torn row: the session is there, its details are not readable
+                    log(f"observe {lane['id']}", error)
+                    lanes[lane['id']] = keep(previous, lane['id'], 'error')
+    return lanes, servers, unregistered
+
+
+VIEWER_TERM = 'xterm-lanesview'   # TERM alias used by holders/tmux.sh; visible as #{client_termname}
+
+
+CLIENT_FORMAT = '#{client_name}|#{session_name}|#{session_group}|#{client_termname}|#{client_flags}'
+
+# The Throttle Studio Host's own grouped session name (`studio_host::tmux::WebSession`):
+# `view-<studio>-<ch>`, plus the legacy `web-<ch>` it still recognises. The Host owns those clients' size
+# mode and un-flags them itself, so this daemon only ever ADDS the flag to them. Every other client — the
+# operator's editors, and an operator's own grouped scratch attach — gets the size back here. The test is
+# `lanes_lib.is_host_view`, the MIRROR of `WebSession::channel_of`; the `view-`/`web-` PREFIX this used to
+# read is strictly WIDER than anything the Host mints, so an operator's grouped `view-notes` was flagged
+# here and un-flagged by nobody — the DEF-852 stranding, surviving for a whole class of names (DEF-980).
+is_host_view = L.is_host_view
+
+
+def client_size_plan(rows):
+    """The `refresh-client` calls `reconcile_client_sizes` would make, as
+    (client_name, lane shown, is_lanes_view, was_ignoring, wanted_flag) — pure, so the rule is unit-testable
+    without a tmux server. `rows` are CLIENT_FORMAT lines already split on '|'.
+
+    Clients are bucketed by the lane they SHOW, not by their own `#{session_name}`: grouped sessions share the
+    lane's windows, so a client attached to `view-<studio>-<ch>` drives the lane's size under
+    `window-size latest` exactly like a client on the lane itself. Keying on `session_name` put such a client
+    in a bucket of its own, where no lanes view is ever present — so a browser `take` attach kept resizing the
+    operator's lanes view, and a browser `ignore` attach had the Host's `-f ignore-size` STRIPPED on the next
+    tick (MEASURED, 2026-09-20)."""
+    names = [row[0] for row in rows]
+    by_lane = {}
+    for name, session, group, term, flags in rows:
+        shows = group if group and group != session else session
+        by_lane.setdefault(shows, []).append(
+            (name, session, term == VIEWER_TERM, 'ignore-size' in flags.split(',')))
+    plan = []
+    for shows, clients in sorted(by_lane.items()):
+        viewed = any(is_viewer for _n, _s, is_viewer, _f in clients)
+        for name, session, is_viewer, ignoring in clients:
+            # Host and container pty NAMES can collide; a name that appears twice cannot be targeted safely.
+            if is_viewer or names.count(name) > 1 or ignoring == viewed:
+                continue
+            # A Studio browser client on its OWN grouped `view-<studio>-<ch>` session chose `ignore-size` for
+            # itself; only a lanes view may add the flag, and the Host un-flags that client itself
+            # (`studio_host::tmux::refresh_client_take_size_argv`) when no lanes view shows the lane. The
+            # exemption needs BOTH halves: grouped (an operator's ungrouped `view-notes` is a lane in its own
+            # right, whose editors must get the size back) AND a session name the HOST mints — the whole
+            # `channel_of` grammar, not the prefix. Keying on grouped alone exempted an operator's own
+            # `tmux new-session -t <lane> -s scratch` client — a shape `viewer_of` explicitly admits — which
+            # this daemon FLAGS when a lanes view arrives and then never un-flags, because nobody else
+            # un-flags a client that is not the Host's (DEF-852); keying on the PREFIX left the identical
+            # stranding for every grouped `view-notes`/`web-dev` the Host never minted (DEF-980).
+            if not viewed and session != shows and is_host_view(session):
+                continue
+            plan.append((name, shows, is_viewer, ignoring, 'ignore-size' if viewed else '!ignore-size'))
+    return plan
+
+
+def reconcile_client_sizes(registry, containers, live):
+    """Size policy "the lanes view wins": while a lanes-view client shows a lane, every other client of that lane
+    (Cursor / VS Code terminals, ad-hoc attaches, a Throttle Studio browser) is put into tmux's ignore-size; once
+    no viewer shows it, the editors get the size back. Only viewer-client flags are touched — never a lane, a pane
+    or an agent. The rule itself is `client_size_plan`."""
+    if live is None or (L.STATE / 'flags/coexist').exists():
+        return 0
+    changed = 0
+    # Every socket `observe` reads, not only the ones registered lanes bind. A lanes view can show any row the
+    # sidebar draws, and the sidebar draws every DISCOVERED session (a `New +` shell lives on
+    # `lanes-shells-<board>`, which no lane declares; a Studio-started lane on a Host-owned
+    # `[inventory.board_sockets]` socket is by construction on a socket no source declares) — so the policy
+    # "the lanes view wins" covered exactly the lanes the design claimed it covered, minus those (DEF-964).
+    # A discovered socket is governed EXACTLY like a registered one, both halves: a lanes view showing one of
+    # its lanes flags the other clients, and — once no view shows the lane — any client still carrying
+    # `ignore-size` is un-flagged, whoever set the flag. That second half is not free, and DEF-964's "a
+    # discovered socket with no viewer costs one `list-clients` and changes nothing" was false for a client
+    # an operator had put into `-f ignore-size` by hand on a socket the harness had never touched before
+    # (DEF-982). It is kept deliberately: emitting only the flagging half here would re-create DEF-852 on
+    # these sockets, where nothing else un-flags. Only client size flags are touched — never a lane, a pane
+    # or an agent.
+    sockets = {(lane['container'], lane['tmux']['socket']) for w in registry['workspaces'] for lane in w['lanes']
+               if lane['holder'] == 'tmux'}
+    sockets.update(discovered_sockets(containers, live))
+    for container, socket in sorted(sockets):
+        info = containers.get(container) or {}
+        if socket not in live or not info.get('pid'):
+            continue
+        output = L.tmux_query(info, socket, ['list-clients', '-F', CLIENT_FORMAT])
+        rows = [row.split('|') for row in (output or '').splitlines() if row.count('|') == 4]
+        for name, _shows, _is_viewer, _ignoring, want in client_size_plan(rows):
+            L.tmux_query(info, socket, ['refresh-client', '-t', name, '-f', want])
+            changed += 1
+    return changed
+
+
+def kept_zmx(previous, outcome, container=None):
+    """The zmx lanes published last time (of one container, or all of them), marked stale."""
+    lanes, groups = {}, {}
+    for workspace, entries in (previous.get('zmx') or {}).items():
+        for entry in entries:
+            if container is None or entry.get('container') == container:
+                groups.setdefault(workspace, []).append(entry)
+                lanes[entry['id']] = keep(previous, entry['id'], outcome)
+    return lanes, groups
+
+
+def zmx_state(agent):
+    """`(state, evidence)` for a zmx-held lane, from its lane-run agent sidecar.
+
+    `lane-run` writes `phase: agent` BEFORE it execs the agent command and `phase: shell` the instant that
+    command ends (MEASURED against `lanes/container/lane-run` with a scratch LANE_ROOT), so a lane that was
+    started through `lane new` ALWAYS has a sidecar while its session lives. A present sidecar is therefore
+    `quiet`, whatever its phase — never `active`: no window-activity evidence exists for a zmx lane, and
+    `phase: shell` means the agent ended while the lane's login shell runs on, which is the same shape a tmux
+    lane publishes `quiet` for.
+
+    An ABSENT or unreadable sidecar is `unknown`: nothing about the program is known. It used to be `dead`
+    with the sentence "the agent command ended", which `lane-run` cannot produce — the shapes that reach it
+    are a session made by raw `zmx attach` (never rooted in lane-run) or a deleted/unparseable state file
+    (DEF-893). A non-`agent` phase used to publish `idle`, a seventh word this daemon alone minted (DEF-823).
+    Pure, so both halves are unit-testable without a zmx daemon."""
+    if agent:
+        return 'quiet', f'lane-run agent phase {str(agent.get("phase") or "unset")!r}'
+    return 'unknown', 'no lane-run agent sidecar: this session was not started through `lane new`'
+
+
+def observe_zmx_container(container):
+    """-> (lanes, groups) of one container, or None when `zmx list` did not answer in time. Raises when it failed."""
+    lanes, groups = {}, {}
+    link = L.Path.home() / '.lz' / container
+    binaries = sorted((link / 'bin').glob('zmx-*')) if (link / 's').is_dir() else []
+    if not binaries:
+        return lanes, groups
+    env = {'PATH': '/usr/bin:/bin', 'HOME': str(L.Path.home()), 'ZMX_DIR': str(link / 's'), 'LANG': 'C.UTF-8'}
+    rc, out, err = L.run_bounded([str(binaries[-1]), 'list'], 15, env=env)
+    if rc is None:
+        return None
+    if rc != 0:
+        # Only rc 0 is an answer. A fork refused under memory pressure (127) or a child taken by the OOM killer
+        # (-9) has empty output as well — parsed, that reads "this container has no zmx lanes" and they all vanish.
+        raise L.LanesError(f'zmx list: rc {rc} {err.strip()[:200]}')
+    for line in out.splitlines():
+        fields = {k.strip(' →*>'): v for k, v in (part.split('=', 1) for part in line.split('\t') if '=' in part)}
+        name = fields.get('name', '')
+        if not L.IDENT.match(name):
+            continue
+        meta = L.read_json(link / 'meta' / f'{name}.json', {}) or {}
+        agent = L.read_json(link / 'state' / f'{name}.json', {}) or {}
+        workspace = meta.get('ws') or fields.get('ws') or '-'
+        lane_id = f'{workspace}--z-{name}'
+        version = str(meta.get('zmx_version') or binaries[-1].name.split('-', 1)[1])
+        groups.setdefault(workspace, []).append({
+            'id': lane_id, 'name': meta.get('title') or name, 'holder': 'zmx', 'container': container,
+            'zmx': {'name': name, 'version': version}, 'color': L.ANSI_SLOTS.get(meta.get('color')),
+            'icon': L.LANE_ICONS.get(meta.get('icon'), '🧵')})
+        L.atomic_write(L.STATE / 'resolve.dynamic' / lane_id,
+                       '\n'.join(['zmx', container, name, version, meta.get('title') or name]) + '\n')
+        state, evidence = zmx_state(agent)
+        lanes[lane_id] = {'state': state, 'evidence': evidence,
+                          'clients': int(fields.get('clients', 0) or 0), 'pid': int(fields.get('pid', 0) or 0),
+                          'agent': agent, 'cwd': meta.get('cwd', '')}
+    return lanes, groups
+
+
+def observe_zmx(containers, previous=None):
+    """zmx-held lanes describe themselves (labels + meta sidecar): no registry edit is needed to see one."""
+    lanes, groups = {}, {}
+    for container in containers:
+        try:
+            found = observe_zmx_container(container) or kept_zmx(previous or {}, 'timeout', container)
+        except Exception as error:
+            log(f'zmx {container}', error)
+            found = kept_zmx(previous or {}, 'error', container)
+        found_lanes, found_groups = found
+        lanes.update(found_lanes)
+        for workspace, entries in found_groups.items():
+            groups.setdefault(workspace, []).extend(entries)
+    return lanes, groups
+
+
+def pid_alive(pid):
+    return bool(pid) and os.path.exists(f'{L.proc_root()}/{pid}')
+
+
+def update_containers(ctx, registry, level):
+    """Container liveness is one stat of /proc/<init-pid> per cycle. docker is asked only for a reason — the
+    registry names other containers, a recorded pid vanished, a container is down / was never answered for, or the
+    5-minute safety net on a host that is not busy — and at most every CONTAINER_RETRY seconds. NEVER because a
+    probe failed: `docker inspect` (2 spawns, 20 s timeouts) every 3 s is a load generator on a host that is
+    already too slow to answer it."""
+    names = {lane['container'] for w in registry['workspaces'] for lane in w['lanes'] + w['extras']}
+    known = ctx['containers']
+    age = time.time() - ctx['containers_at']
+    unsettled = set(known) != names or any(not pid_alive(c.get('pid')) for c in known.values())
+    if age > CONTAINER_RETRY and (unsettled or (age > CONTAINER_REFRESH and level == 'ok')):
+        try:
+            ctx['containers'] = L.refresh_containers(names)
+        finally:
+            # Stamped AFTER the (possibly slow) docker round so that the pause between two rounds is real, and also
+            # when it raised: a failing refresh must not become the next retry storm.
+            ctx['containers_at'] = time.time()
+    for info in ctx['containers'].values():
+        info['running'] = pid_alive(info.get('pid'))
+
+
+def build_payload(ctx, level, reconcile=True):
+    """One observation pass -> the payload of status.json (None = there is no registry to observe). Every phase
+    fails alone: what it could not observe is republished as last seen (stale), the other phases still run."""
+    previous = ctx['payload']
+    try:
+        stamp = os.stat(L.STATE / 'registry.json').st_mtime_ns
+        if stamp != ctx['stamp']:
+            ctx['registry'], ctx['stamp'] = L.load_registry(), stamp
+    except Exception as error:   # keep observing with the last registry that loaded
+        log('registry', error)
+    registry = ctx['registry']
+    if registry is None:
+        return None
+    try:
+        update_containers(ctx, registry, level)
+    except Exception as error:
+        log('containers', error)
+    containers = ctx['containers']
+    try:
+        live = live_tmux_sockets()
+    except Exception as error:
+        log('ps', error)
+        live = None
+    try:
+        lanes, servers, unregistered = observe(registry, containers, live, previous)
+    except Exception as error:
+        log('observe', error)
+        lanes = {lane_id: keep(previous, lane_id, 'error') for lane_id in previous.get('lanes') or {}}
+        servers, unregistered = previous.get('servers') or {}, previous.get('unregistered') or {}
+    # Half of all our spawns, and only cosmetics (who dictates a window size): not on a host under pressure.
+    if reconcile and level == 'ok':
+        try:
+            reconcile_client_sizes(registry, containers, live)
+        except Exception as error:
+            log('reconcile', error)
+    try:
+        zmx_lanes, zmx_groups = observe_zmx(containers, previous)
+    except Exception as error:
+        log('zmx', error)
+        zmx_lanes, zmx_groups = kept_zmx(previous, 'error')
+    lanes.update(zmx_lanes)
+    legacy_lanes, legacy_groups = Legacy.observe()
+    lanes.update(legacy_lanes)
+    for workspace, entries in legacy_groups.items():
+        unregistered.setdefault(workspace, []).extend(entries)
+    return {'lanes': lanes, 'servers': servers, 'unregistered': unregistered, 'zmx': zmx_groups,
+            'containers': {k: {'running': v.get('running', False)} for k, v in containers.items()}}
+
+
+def new_context():
+    # Seeded from the file on disk: a statusd that (re)starts on a slow host still knows every lane's last state.
+    # The age of that file counts as time without an observation (keep() ages from 'stale_since'): a statusd that
+    # was down for a day must not republish yesterday's states as the last known ones.
+    seed = L.read_json(L.STATE / 'status.json', {}) or {}
+    written = float(seed.get('updated_at') or 0)
+    for entry in (seed.get('lanes') or {}).values():
+        entry.setdefault('stale_since', int(written))
+    return {'registry': None, 'stamp': 0, 'containers': {}, 'containers_at': 0.0,
+            'payload': seed, 'published': None, 'status_at': written}
+
+
+def cycle(ctx, reconcile=True):
+    """Observe once and ALWAYS publish -> (health level, payload or None)."""
+    started = time.time()
+    try:
+        health = L.compute_health()
+    except Exception as error:
+        log('health', error)
+        health = {}
+    level = health.get('level', 'ok')
+    try:
+        payload = build_payload(ctx, level, reconcile)
+    except Exception as error:
+        log('cycle', error)
+        payload = None
+    if payload is not None:
+        ctx['payload'] = payload
+        # Rewrite only on change (plus a heartbeat) so sidebars do not repaint for nothing. `health` changes every
+        # cycle and is therefore not part of the comparison.
+        if payload != ctx['published'] or started - ctx['status_at'] > HEARTBEAT:
+            try:
+                written = time.time()
+                L.atomic_write(L.STATE / 'status.json', json.dumps(dict(payload, health=health, updated_at=written)) + '\n')
+                ctx['published'], ctx['status_at'] = payload, written
+            except Exception as error:
+                log('status.json', error)
+    try:   # "servers alive, sockets deleted" as a flag file: view.sh, the sidebar and doctor read it without parsing
+        lost = sorted(key for key, server in ((payload or {}).get('servers') or {}).items() if server.get('outcome') == 'nosocket')
+        flag = L.STATE / 'flags' / 'sockets-lost'
+        if lost:
+            L.atomic_write(flag, '\n'.join(lost) + '\n')
+        elif payload is not None and flag.exists():
+            flag.unlink()
+    except Exception as error:
+        log('sockets-lost flag', error)
+    if health:   # no health computed = no line written: its age then tells the readers, which is the truth
+        try:
+            L.atomic_write(L.STATE / 'health', L.health_line(health, ctx['status_at']))
+        except Exception as error:
+            log('health file', error)
+    return level, payload
+
+
+def pause(level, elapsed):
+    return max(0.5, INTERVAL * SLOWDOWN.get(level, 1) - elapsed)
+
+
+def _registry_sources(registry):
+    """All terminals.json paths referenced by the current registry (unique, extant)."""
+    seen = set()
+    for w in (registry or {}).get('workspaces', []):
+        for lane in w.get('lanes', []):
+            src = lane.get('source')
+            if src and src not in seen:
+                seen.add(src)
+                yield src
+
+
+def main():
+    ctx = new_context()
+    last_triggered_sync = 0.0
+    source_mtimes = {}   # path -> mtime_ns at last check
+    while True:
+        started = time.time()
+        level, _payload = cycle(ctx)
+        # Hot-reload: check if any terminals.json changed since we last synced.
+        # Rate-limited to at most one triggered sync per 10 s to avoid thrashing.
+        if time.time() - last_triggered_sync > 10 and ctx['registry']:
+            for src in _registry_sources(ctx['registry']):
+                try:
+                    mtime = os.stat(src).st_mtime_ns
+                except OSError:
+                    continue
+                if src in source_mtimes and mtime != source_mtimes[src]:
+                    try:
+                        import subprocess as _sp
+                        lanes_bin = str(L.REPO / 'bin' / 'lanes')
+                        _sp.Popen([lanes_bin, 'sync'], stdout=_sp.DEVNULL, stderr=_sp.DEVNULL)
+                        last_triggered_sync = time.time()
+                    except Exception as sync_err:
+                        log('hot-sync', sync_err)
+                    break
+                source_mtimes[src] = mtime
+        time.sleep(pause(level, time.time() - started))
+
+
+if __name__ == '__main__':
+    if len(sys.argv) > 1 and sys.argv[1] == '--once':
+        # The same builder as the daemon, minus the one phase that is not an observation (client size flags).
+        _level, result = cycle(new_context(), reconcile=False)
+        if result is None:
+            sys.exit('statusd --once: nothing published (no registry yet? run `lanes sync`)')
+        print(json.dumps({'lanes': len(result['lanes']),
+                          'unregistered': {k: [e['name'] for e in v] for k, v in result['unregistered'].items()}}, indent=1))
+    else:
+        main()