@vibelord/lanes 1.0.0

package/payload/lanes/libexec/sidebar.py

@@ -0,0 +1,872 @@
+#!/usr/bin/env python3
+"""Lane sidebar: a plain terminal program (no zellij plugin, no curses).
+
+Shows one workspace's lanes with color, icon and live status. Selecting a lane writes the view's
+target file and signals the viewport supervisor; the zellij layout is never touched.
+Fully usable from the keyboard (touch/mouse is a bonus):
+  ↑/↓ j/k move · Enter/→/Space open · J/K open next/previous lane · / filter · Esc clear · g/G · r reload
+  2 / 3 open the lane under the cursor in the 2nd / 3rd viewport (wide view sessions)
+Upload box (bottom): click it or press U (Ctrl-Alt-u from anywhere), then DROP FILES anywhere on the window. A
+terminal delivers a drop as a paste of the LOCAL path into the focused pane, so the box must have focus first; the
+file itself is then sent by the upload helper on your machine (it only reads folders you allowed there).
+Truthful under load: a lane statusd could not observe keeps its last glyph, dimmed, with a `?`; the footer line warns
+when the host is under pressure or statusd has fallen behind (age of $STATE/health, measured with our own clock).
+Run via libexec/sidebar (a loop), so it never leaves its pane empty.
+"""
+import json
+import os
+import re
+import select
+import shlex
+import signal
+import subprocess
+import sys
+import termios
+import time
+from pathlib import Path
+import tty
+import unicodedata
+
+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
+
+STATE = os.environ.get('LANES_STATE') or os.path.expanduser('~/.local/state/lanes')
+# The six words statusd publishes (alignment contract A3) and the helper word for an `exec` lane. There is no
+# seventh: statusd's zmx observer used to publish `idle`, which no other surface knew (DEF-823).
+GLYPHS = {'active': ('●', '32'), 'quiet': ('○', '2'), 'missing': ('✖', '31'), 'absent': ('–', '2'),
+          'dead': ('!', '33'), 'helper': ('·', '2'), 'unknown': ('?', '2')}
+# The phone sidebar spells the same six words (plus `helper`) in full. The keys are GLYPHS's keys and the
+# vocabulary gate pins that: this map kept `idle` for a whole release after DEF-823 removed it from GLYPHS,
+# because the gate read GLYPHS alone and the map was a literal buried inside `render_mobile` (DEF-983).
+MOBILE_LABELS = {'active': 'Active', 'quiet': 'Quiet', 'missing': 'Container offline',
+                 'absent': 'Not started', 'dead': 'Ended', 'helper': 'Tool',
+                 'unknown': 'Checking status'}
+
+
+def viewer_mark(status):
+    """The mark after a lane's name when other sessions view it: one dot per viewer, at most three."""
+    count = int((status or {}).get('viewers') or 0)
+    return '·' * min(3, count)
+
+
+def read_json(path):
+    try:
+        with open(path) as handle:
+            return json.load(handle)
+    except (OSError, ValueError):
+        return None
+
+
+def mtime(path):
+    try:
+        return os.stat(path).st_mtime_ns
+    except OSError:
+        return 0
+
+
+def cell_width(text):
+    width = 0
+    for ch in text:
+        if unicodedata.combining(ch) or ch in '‍️':
+            continue
+        width += 2 if unicodedata.east_asian_width(ch) in ('W', 'F') else 1
+    return width
+
+
+def clip(text, width):
+    out, used = [], 0
+    for ch in text:
+        w = cell_width(ch)
+        if used + w > width:
+            break
+        out.append(ch)
+        used += w
+    return ''.join(out), used
+
+
+HEALTH_STALE = 30   # seconds; statusd rewrites $STATE/health every cycle, at most ~12 s apart when it slows itself down
+
+
+def health_banner(health, written, now):
+    """The footer warning; '' = nothing to say. `health` = L.read_health(), `written` = the file's mtime in seconds
+    (0 = no such file: a statusd from before it existed — nothing is known, so nothing is claimed).
+    statusd is what freezes on a thrashing host, so the age is measured HERE, with our clock, from the file's mtime.
+    The age comes first: a sidebar is 36 cells wide, and "what you see is N minutes old" must survive the clipping."""
+    if os.path.exists(os.path.join(STATE, 'flags', 'sockets-lost')):
+        # Short, and first: it explains every "not running" on the screen. The fix is one command on the server.
+        return '⚠ lane sockets deleted — lanes run; on the server: lanes sockets repair'
+    if not written:
+        return ''
+    parts, age = [], int(now - written)
+    if age > HEALTH_STALE:
+        parts.append(f'status {age // 60} m old' if age >= 60 else f'status {age // 10 * 10} s old')
+    level = health.get('level', 'ok')
+    if level != 'ok':
+        parts.append('host under memory pressure' if level == 'critical' else 'host busy')
+    return '⚠ ' + ' · '.join(parts) if parts else ''
+
+
+SLOTS = ['main', 'b', 'c']
+BOX_ROWS = 4
+PASTE_START, PASTE_END = '\033[200~', '\033[201~'
+
+
+class Sidebar:
+    def __init__(self, device, workspace, slot='main', viewports='1'):
+        self.device, self.workspace, self.slot = device, workspace, slot
+        self.mobile = bool((read_json(os.path.join(STATE, 'devices', device + '.json')) or {}).get('mobile'))
+        self.mobile_owner, self.mobile_titles, self.next_mobile_poll = False, {}, 0
+        try:
+            self.viewports = max(1, min(len(SLOTS), int(viewports)))
+        except ValueError:
+            self.viewports = 1
+        self.view_dir = os.path.join(STATE, 'views', device)
+        self.target_file = self.slot_file(slot, 'target')
+        self.pid_file = self.slot_file(slot, 'pid')
+        self.registry_path = os.path.join(STATE, 'registry.json')
+        self.status_path = os.path.join(STATE, 'status.json')
+        self.health_path = os.path.join(STATE, 'health')
+        self.health, self.health_stamp, self.banner = {}, None, ''
+        self.entries, self.title, self.errors = [], workspace, []
+        self.status, self.unregistered, self.zmx = {}, [], []
+        self.cursor, self.top = 0, 0
+        self.filter, self.filtering = '', False
+        self.renaming, self.rename_value, self.rename_entry = False, '', None
+        self.promoting, self.promote_entry = False, None
+        self.stamp = (0, 0, 0)
+        self._prev_entry_count = -1      # for scroll memory
+        self.size = (0, 0)
+        self.dirty = True
+        self.message = ''
+        self.box, self.box_top = False, 10 ** 6
+        self.entry_top, self.entry_height = 2, 1
+        self.armed, self.paste_buffer = False, None
+        self.upload = None          # {'id', 'spool', 'names', 'at'} while a request is in flight
+        self.upload_note, self.upload_note_at = '', 0
+
+    def slot_file(self, slot, kind):
+        return os.path.join(self.view_dir, f'{self.workspace}.{slot}.{kind}')
+
+    def slot_target(self, slot):
+        try:
+            with open(self.slot_file(slot, 'target')) as handle:
+                return handle.readline().strip()
+        except OSError:
+            return ''
+
+    # ---------------------------------------------------------------- data
+    def reload(self, force=False):
+        stamp = (mtime(self.registry_path), mtime(self.status_path),
+                 sum(mtime(self.slot_file(slot, 'target')) for slot in SLOTS[:self.viewports]))
+        if stamp == self.stamp and not force:
+            return
+        if stamp[0] != self.stamp[0] or force:
+            registry = read_json(self.registry_path) or {}
+            boards = registry.get('workspaces', [])
+            self.mobile_owner = self.mobile and bool(boards) and boards[0]['id'] == self.workspace
+            self.mobile_titles = {w.get('title') or w['id']: w['id'] for w in boards}
+            self.mobile_titles.update({tool['tab']: tool['view'] for tool in registry.get('tools', [])})
+            for workspace in registry.get('workspaces', []):
+                if workspace.get('id') == self.workspace:
+                    self.title = workspace.get('title') or self.workspace
+                    self.entries = list(workspace.get('lanes', [])) + list(workspace.get('extras', []))
+                    self.errors = workspace.get('errors', [])
+                    break
+        if stamp[1] != self.stamp[1] or force:
+            status = read_json(self.status_path) or {}
+            self.status = status.get('lanes', {})
+            self.unregistered = (status.get('unregistered') or {}).get(self.workspace, [])
+            self.zmx = (status.get('zmx') or {}).get(self.workspace, [])
+        self.stamp = stamp
+        self.dirty = True
+        # Scroll memory: preserve scroll top when list length is stable.
+        # Cursor is already clamped by render() on every draw.
+        new_count = len(self.visible())
+        if new_count != self._prev_entry_count:
+            self._prev_entry_count = new_count
+            self.top = 0   # reset scroll position on structural change
+
+    def poll_mobile_view(self):
+        """One sidebar observes the phone's web client and the first display of each full-width view.
+
+        Safari bypasses `lanes attach`, which normally sets clients/<device>.ready. Hidden mobile tabs have a
+        plausible placeholder size, so they also need a per-workspace first-display gate before attaching tmux.
+        """
+        if not self.mobile_owner or time.monotonic() < self.next_mobile_poll:
+            return
+        self.next_mobile_poll = time.monotonic() + 1
+        command = [os.environ.get('LANES_ZELLIJ') or 'zellij', '-s', self.device, 'action']
+        ready = os.path.join(STATE, 'clients', self.device + '.ready')
+        if not os.path.exists(ready):
+            rc, out, _err = L.run_bounded(command + ['list-clients'], 2)
+            if rc != 0 or not any(re.match(r'^\s*\d+\s', line) for line in out.splitlines()):
+                return
+            L.atomic_write(Path(ready), f'{time.time()}\n')
+        rc, out, _err = L.run_bounded(command + ['list-tabs', '-j'], 2)
+        if rc != 0:
+            return
+        try:
+            title = next(tab['name'] for tab in json.loads(out) if tab.get('active'))
+        except (ValueError, KeyError, StopIteration, TypeError):
+            return
+        workspace = self.mobile_titles.get(title)   # the "<workspace> ☰" picker tab never attaches a lane
+        if workspace:
+            shown = Path(self.view_dir) / f'{workspace}.main.shown'
+            if not shown.exists():
+                L.atomic_write(shown, f'{time.time()}\n')
+
+    def poll_health(self):
+        """Keep the footer banner current. Deliberately NOT part of reload()'s stamp: the health file changes every
+        statusd cycle and would repaint every sidebar every cycle — only a changed banner TEXT marks the screen
+        dirty. Polled every tick, because the case that matters is the one where no file changes at all any more."""
+        stamp = mtime(self.health_path)
+        if stamp != self.health_stamp:
+            self.health_stamp, self.health = stamp, L.read_health(STATE)
+        banner = health_banner(self.health, stamp / 1e9, time.time())
+        if banner != self.banner:
+            self.banner, self.dirty = banner, True
+
+    def current_target(self):
+        try:
+            with open(self.target_file) as handle:
+                return handle.readline().strip()
+        except OSError:
+            try:
+                with open(os.path.join(STATE, 'defaults', self.workspace)) as handle:
+                    return handle.readline().strip()
+            except OSError:
+                return ''
+
+    def visible(self):
+        entries = list(self.entries)
+        if self.zmx:
+            entries.append({'id': '', 'divider': True, 'name': f'zmx lanes ({len(self.zmx)})'})
+            entries += self.zmx
+        # Everything statusd lists as unregistered is shown, `view-…` names included: under the viewer rule
+        # those are orphaned or operator-made sessions that are ALIVE, and nothing alive is ever hidden.
+        entries.append({'id': '', 'divider': True, 'name': f'Unregistered ({len(self.unregistered)})'})
+        entries.append({'id': self.workspace + '--new-shell', 'name': 'New +', 'action': 'new-shell', 'icon': '＋'})
+        entries += self.unregistered
+        if not self.filter:
+            return entries
+        needle = self.filter.lower()
+        scored = [(self._fuzzy_score(needle, e.get('name', '').lower()), e)
+                  for e in entries if not e.get('divider')]
+        return [e for score, e in sorted(
+            ((s, e) for s, e in scored if s > 0), key=lambda t: -t[0])]
+
+    @staticmethod
+    def _fuzzy_score(needle, name):
+        """Score how well `needle` matches `name` (both lower-case). Returns 0 if no fuzzy match.
+        Characters of needle must appear in name in order; bonus for prefix or word-boundary hits."""
+        if not needle:
+            return 0
+        if needle in name:
+            return 1000 + (500 if name.startswith(needle) else 0)
+        pos, score = 0, 0
+        for ch in needle:
+            found = name.find(ch, pos)
+            if found < 0:
+                return 0
+            # Bonus for boundary: start of string, or after a non-alphanumeric separator
+            if found == 0 or not name[found - 1].isalnum():
+                score += 10
+            pos = found + 1
+        return max(1, score)
+
+    # -------------------------------------------------------------- actions
+    def open_lane(self, entry, slot=None):
+        if entry.get('divider'):
+            return
+        slot = slot or self.slot
+        if slot not in SLOTS[:self.viewports]:
+            self.message = 'this view has no such viewport (open a wide view: lanes-window w2)'
+            self.dirty = True
+            return
+        if entry.get('action') == 'new-shell':
+            self.new_shell(slot)
+            return
+        target_file, pid_file = self.slot_file(slot, 'target'), self.slot_file(slot, 'pid')
+        if self.slot_target(slot) == entry['id']:
+            self.focus_lane(slot)
+            self.filter, self.filtering, self.dirty = '', False, True
+            return
+        os.makedirs(self.view_dir, exist_ok=True)
+        tmp = target_file + f'.{os.getpid()}.tmp'
+        with open(tmp, 'w') as handle:
+            handle.write(entry['id'] + '\n')
+        os.replace(tmp, target_file)
+        try:
+            with open(pid_file) as handle:
+                pid = int(handle.read().strip())
+            with open(f'/proc/{pid}/cmdline', 'rb') as handle:
+                if b'view.sh' in handle.read():
+                    os.kill(pid, signal.SIGUSR1)
+        except (OSError, ValueError):
+            self.message = 'view not running yet'
+        self.focus_lane(slot)
+        self.filter, self.filtering = '', False
+        self.dirty = True
+
+    def new_shell(self, slot=None):
+        self.message = 'Creating shell…'
+        self.render()
+        try:
+            entry = A.new_shell(self.workspace)
+            self.unregistered.append(entry)
+            self.status[entry['id']] = {'state': 'quiet'}
+            self.open_lane(entry, slot)
+            self.message = 'Created ' + entry['name']
+        except (L.LanesError, OSError, ValueError) as error:
+            self.message = str(error)
+        self.dirty = True
+
+    def close_lane(self, entry):
+        if not entry.get('closable'):
+            return
+        self.message = 'Closing ' + entry['name'] + '…'
+        self.render()
+        try:
+            A.close_session(self.workspace, entry)
+            self.unregistered = [e for e in self.unregistered if e['id'] != entry['id']]
+            self.status.pop(entry['id'], None)
+            self.message = 'Closed ' + entry['name']
+        except (L.LanesError, OSError, ValueError) as error:
+            self.message = str(error)
+        self.dirty = True
+
+    def start_rename(self, entry):
+        """Begin inline rename of the lane under the cursor."""
+        if entry.get('divider') or entry.get('action'):
+            return
+        self.renaming = True
+        self.rename_entry = entry
+        self.rename_value = entry.get('name', '')
+        self.dirty = True
+
+    def commit_rename(self):
+        """Confirm the in-progress rename."""
+        entry = self.rename_entry
+        new_name = self.rename_value.strip()
+        self.renaming, self.rename_entry, self.rename_value = False, None, ''
+        if not new_name or not entry:
+            self.dirty = True
+            return
+        try:
+            if entry.get('closable') or entry.get('id', '').find('--x-') >= 0:
+                # Unregistered session
+                updated = A.rename_session(self.workspace, entry, new_name)
+                for lst in (self.unregistered, self.zmx):
+                    for i, e in enumerate(lst):
+                        if e['id'] == entry['id']:
+                            lst[i] = dict(e, name=new_name)
+                self.message = f'Renamed → {new_name}'
+            else:
+                # Registered lane: write displayNames override to the manifest + sync
+                source = entry.get('source')
+                registry_name = entry.get('registry_name') or entry.get('name', '')
+                if not source:
+                    raise L.LanesError('No manifest source for this lane; edit terminals.json directly')
+                A.rename_registered(source, registry_name, new_name)
+                # Trigger a registry rebuild
+                import subprocess as _sp
+                _sp.Popen([os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+                                        'bin', 'lanes'), 'sync'],
+                          stdout=_sp.DEVNULL, stderr=_sp.DEVNULL)
+                self.message = f'Renamed → {new_name} (sync triggered)'
+        except (L.LanesError, OSError, ValueError) as error:
+            self.message = str(error)
+        self.dirty = True
+
+    def start_promote(self, entry):
+        """Begin promotion confirmation for an unregistered session."""
+        if entry.get('divider') or entry.get('action'):
+            return
+        if not entry.get('closable') and entry.get('holder') != 'tmux':
+            self.message = 'Only tmux sessions can be promoted'
+            self.dirty = True
+            return
+        self.promoting = True
+        self.promote_entry = entry
+        self.dirty = True
+
+    def commit_promote(self):
+        """Confirm the in-progress promotion (caller has already checked 'y')."""
+        entry = self.promote_entry
+        self.promoting, self.promote_entry = False, None
+        if not entry:
+            self.dirty = True
+            return
+        try:
+            registry = read_json(self.registry_path) or {}
+            A.promote_to_registered(self.workspace, entry, registry)
+            # Trigger a registry rebuild so the lane moves from unregistered → registered
+            import subprocess as _sp
+            _sp.Popen([os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+                                    'bin', 'lanes'), 'sync'],
+                      stdout=_sp.DEVNULL, stderr=_sp.DEVNULL)
+            self.unregistered = [e for e in self.unregistered if e['id'] != entry['id']]
+            self.message = f'Promoted — reload in a moment'
+            self.reload(force=True)
+        except (L.LanesError, OSError, ValueError) as error:
+            self.message = str(error)
+        self.dirty = True
+
+    def spools(self):
+        """Where an upload request may be spooled, best first. A suffixed view (mac-2, mac-w2) belongs to the machine
+        whose base device (mac) `lanes attach` recorded in devices/<device>.json: that machine's ONE helper serves
+        the base spool. The view's own spool stays as the fallback (an older client runs a helper per window).
+        Read per drop, not at start: the base is learnt at the first attach, and this sidebar is older than that."""
+        own = os.path.join(STATE, 'upload-requests', self.device)
+        meta = read_json(os.path.join(STATE, 'devices', self.device + '.json'))
+        base = meta.get('base') if isinstance(meta, dict) else None
+        if isinstance(base, str) and base and self.device.startswith(base + '-'):   # a prefix of our own, valid name
+            return [os.path.join(STATE, 'upload-requests', base), own]
+        return [own]
+
+    def dropped(self, text):
+        """A drop arrives as a paste of local path(s). Ask this device's upload helper to send them."""
+        self.armed = False
+        try:
+            tokens = shlex.split(text.strip())
+        except ValueError:
+            tokens = text.split()
+        paths = []
+        for token in tokens:
+            if token.startswith('file://'):
+                token = re.sub(r'%([0-9A-Fa-f]{2})', lambda m: chr(int(m.group(1), 16)), token[7:])
+            if token.startswith('/') and '\n' not in token:
+                paths.append(token)
+        if not paths or len(paths) != len(tokens):
+            self.upload_note, self.upload_note_at = 'that was not a file drop', time.time()
+            return
+        spool = next((s for s in self.spools() if time.time() - mtime(os.path.join(s, 'agent.alive')) / 1e9 <= 12), None)
+        if not spool:   # no helper is serving either spool
+            self.upload_note, self.upload_note_at = 'no upload helper on this device (reopen lanes-launch)', time.time()
+            return
+        request = f'{int(time.time() * 1000)}-{os.getpid()}'
+        # The sidecar names the view that asked — the device whose lane gets the paste (`lanes upload --request`).
+        # Written before the .req exists: a helper takes a .req the moment it appears.
+        with open(os.path.join(spool, f'{request}.dev'), 'w') as handle:
+            handle.write(self.device + '\n')
+        tmp = os.path.join(spool, f'.{request}.tmp')
+        with open(tmp, 'w') as handle:
+            handle.write('\n'.join([self.workspace, '1'] + paths) + '\n')
+        os.replace(tmp, os.path.join(spool, f'{request}.req'))
+        self.upload = {'id': request, 'spool': spool, 'names': [os.path.basename(p) for p in paths], 'at': time.time()}
+
+    def poll_upload(self):
+        if not self.upload:
+            return
+        base = os.path.join(self.upload['spool'], self.upload['id'])   # the results land where the request went
+        progress_at = mtime(base + '.progress') / 1e9
+        if progress_at > self.upload.get('progress_at', 0):
+            progress = read_json(base + '.progress') or {}
+            self.upload.update(progress_at=progress_at, bytes=progress.get('bytes', 0))
+        note = None
+        if os.path.exists(base + '.done'):
+            note = '✓ ' + ', '.join(self.upload['names'])[:60]
+            self.focus_lane()
+        elif os.path.exists(base + '.err'):
+            try:
+                with open(base + '.err') as handle:
+                    note = '✖ ' + handle.readline().strip()[:70]
+            except OSError:
+                note = '✖ upload failed'
+        elif time.time() - max(self.upload['at'], progress_at) > 120:
+            note = '✖ upload timed out'
+        if note:
+            for suffix in ('.done', '.err', '.sent', '.req', '.dev', '.progress'):
+                try:
+                    os.unlink(base + suffix)
+                except OSError:
+                    pass
+            self.upload, self.upload_note, self.upload_note_at, self.dirty = None, note, time.time(), True
+
+    def focus_lane(self, slot=None):
+        if os.environ.get('ZELLIJ'):
+            actions = ([['go-to-tab-name', self.title]] if self.mobile else
+                       [['move-focus', 'right']] * (SLOTS.index(slot or self.slot) + 1))
+            for action in actions:
+                try:
+                    subprocess.run([os.environ.get('LANES_ZELLIJ') or 'zellij', 'action', *action], timeout=3,
+                                   stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+                except (OSError, subprocess.SubprocessError):
+                    break
+
+    def box_lines(self, cols):
+        """The upload box: BOX_ROWS lines, last rows of the sidebar."""
+        inner = max(4, cols - 2)
+        if self.upload:
+            spin = '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏'[int(time.time() * 8) % 10]
+            body, style = [f'{spin} sending {len(self.upload["names"])} file(s)…', ', '.join(self.upload['names'])], '33'
+            if self.upload.get('bytes'):
+                body[1] = f'{self.upload["bytes"] / 1048576:.1f} MiB · ' + body[1]
+        elif self.armed:
+            body, style = ['⬇  DROP FILES NOW', 'anywhere on this window · Esc'], '1;32'
+        elif self.upload_note and time.time() - self.upload_note_at < 8:
+            body, style = [self.upload_note, f'→ {self.workspace}/uploads'], '36'
+        else:
+            body, style = ['⬆ uploads — click, then drop', f'→ {self.workspace}/uploads  (U)'], '2'
+        lines = [f'\033[{style}m┌{"─" * inner}┐\033[0m']
+        for text in body[:BOX_ROWS - 2]:
+            text, used = clip(' ' + text, inner)
+            lines.append(f'\033[{style}m│\033[0m\033[{style}m{text}{" " * (inner - used)}\033[0m\033[{style}m│\033[0m')
+        lines.append(f'\033[{style}m└{"─" * inner}┘\033[0m')
+        return lines
+
+    # ------------------------------------------------------------ rendering
+    def render(self):
+        try:
+            cols, rows = os.get_terminal_size(sys.stdout.fileno())
+        except OSError:
+            cols, rows = 36, 24
+        self.size = (cols, rows)
+        if self.mobile:
+            self.render_mobile(cols, rows)
+            return
+        entries = self.visible()
+        self.box = rows >= 14
+        body = max(1, rows - 3 - (BOX_ROWS if self.box else 0))
+        self.box_top = 2 + body     # 1-based screen row where the box starts
+        self.cursor = max(0, min(self.cursor, len(entries) - 1))
+        if self.cursor < self.top:
+            self.top = self.cursor
+        if self.cursor >= self.top + body:
+            self.top = self.cursor - body + 1
+        target = self.current_target()
+        others = {slot: self.slot_target(slot) for slot in SLOTS[1:self.viewports]}
+        out = ['\033[?25l\033[H']
+        counts = sum(1 for e in self.entries if self.status.get(e['id'], {}).get('state') == 'active')
+        header, used = clip(f' {self.title}', cols - 8)
+        out.append(f'\033[1m{header}\033[0m\033[2m{" " * max(1, cols - used - 7)}{counts:>2}/{len(self.entries):<3}\033[0m\033[K\r\n')
+        for row in range(body):
+            index = self.top + row
+            if index >= len(entries):
+                out.append('\033[K\r\n')
+                continue
+            entry = entries[index]
+            if entry.get('divider'):
+                label, used_cols = clip(f'── {entry["name"]} ', cols - 1)
+                out.append(f'\033[2m{label}{"─" * max(0, cols - 1 - used_cols)}\033[0m\033[K\r\n')
+                continue
+            if entry.get('action'):
+                marker = '▌' if index == self.cursor else ' '
+                label, _ = clip(marker + ' New +', cols - 1)
+                out.append(f'\033[32m{label}\033[0m\033[K\r\n')
+                continue
+            observed = self.status.get(entry['id'], {})
+            state = observed.get('state', 'helper' if entry.get('holder') == 'exec' else 'unknown')
+            glyph, glyph_color = GLYPHS.get(state, GLYPHS['unknown'])
+            # stale = statusd got no answer about this lane and republished its LAST state: same glyph, dimmed, and a
+            # '?' in the spare cell after it (no cell is added: rows, clicks and the upload box stay where they are).
+            tail = ' '
+            if observed.get('stale') and glyph != '?':
+                glyph_color, tail = '2;' + glyph_color, '\033[2m?'
+            is_target, is_cursor = entry['id'] == target, index == self.cursor
+            shown = ''.join(mark for slot, mark in zip(SLOTS[1:self.viewports], '²³') if others.get(slot) == entry['id'])
+            shown += viewer_mark(self.status.get(entry['id']))
+            marker = '▌' if is_cursor else ' '
+            icon = entry.get('icon') or '💻'
+            icon_pad = ' ' * (3 - cell_width(icon))
+            name_width = max(1, cols - (12 if entry.get('closable') else 9))
+            # Status age suffix: show how long ago the lane was last active (quiet lanes only, compact)
+            age_suffix = ''
+            if state == 'quiet':
+                activity = observed.get('activity')
+                if activity:
+                    age_s = int(time.time() - activity)
+                    if age_s >= 60:
+                        age_suffix = f'  {age_s // 60}m'
+                    elif age_s >= 10:
+                        age_suffix = f'  {age_s}s'
+            name, name_used = clip(entry.get('name', entry['id']) + shown + age_suffix, name_width)
+            color = entry.get('color')
+            style = ('1;' if is_target else '') + ('4;' if is_cursor else '')
+            fg = f'38;5;{color}' if isinstance(color, int) else '39'
+            background = ''  # theme-agnostic: the cursor row is marked by ▌ + underline, not a fixed color
+            pad = ' ' * max(0, name_width - name_used)
+            close = f'\033[{max(1, cols - 2)}G\033[31m×\033[0m' if entry.get('closable') else ''
+            out.append(f'{background}\033[36m{marker}\033[39m{icon}{icon_pad}\033[{style}{fg}m{name}\033[22;24;39m{pad} '
+                       f'\033[{glyph_color}m{glyph}\033[0m{background}{tail}\033[0m{close}\033[K\r\n')
+        footer_style = '2'
+        if self.renaming:
+            footer = f' Rename: {self.rename_value}█'
+            footer_style = '36'
+        elif self.promoting:
+            name = self.promote_entry.get('name', '') if self.promote_entry else ''
+            footer = f' Promote {name!r} to registered? y/n'
+            footer_style = '33'
+        elif self.filtering or self.filter:
+            footer = f' /{self.filter}'
+        elif self.banner:   # above everything but the filter being typed: a frozen picture must never look live
+            footer, footer_style = ' ' + self.banner, '33'
+        elif self.errors:
+            footer = ' ⚠ registry: ' + self.errors[0]
+        elif self.message:
+            footer = ' ' + self.message
+        else:
+            footer = ' ⏎ open · + new · x close · R rename · / find'
+        footer, _ = clip(footer, cols - 1)
+        if self.box:
+            for line in self.box_lines(cols):
+                out.append(line + '\033[K\r\n')
+        out.append(f'\033[2m{"─" * cols}\033[0m\r\n\033[{footer_style}m{footer}\033[0m\033[K\033[J')
+        sys.stdout.write(''.join(out))
+        sys.stdout.flush()
+        self.dirty = False
+
+    def render_mobile(self, cols, rows):
+        """Three terminal rows per lane make the entire row a finger-sized touch target."""
+        entries = self.visible()
+        self.box = False  # the Mac file-drop helper is not available in a phone browser
+        self.entry_top, self.entry_height = 3, 3 if rows >= 8 else 1
+        body = max(1, (rows - 3) // self.entry_height)
+        self.box_top = self.entry_top + body * self.entry_height
+        self.cursor = max(0, min(self.cursor, len(entries) - 1))
+        self.top = max(0, min(self.top, self.cursor))
+        if self.cursor >= self.top + body:
+            self.top = self.cursor - body + 1
+        target = self.current_target()
+        out = ['\033[?25l\033[H']
+
+        def line(value='', style='0', closable=False):
+            value, _ = clip(value, max(1, cols - (5 if closable else 1)))
+            close = f'\033[{max(1, cols - 2)}G\033[31m×\033[0m' if closable else ''
+            out.append(f'\033[{style}m{value}\033[0m{close}\033[K\r\n')
+
+        count = sum(not e.get('divider') and not e.get('action') for e in entries)
+        line(f'  LANES  ·  {count}', '1;36')
+        line()
+        for index in range(self.top, self.top + body):
+            if index >= len(entries):
+                for _ in range(self.entry_height):
+                    line()
+                continue
+            entry = entries[index]
+            observed = self.status.get(entry['id'], {})
+            lane_state = observed.get('state', 'helper' if entry.get('holder') == 'exec' else 'unknown')
+            selected = entry['id'] == target
+            marker = '›' if index == self.cursor else ' '
+            if entry.get('divider'):
+                line('  ' + entry['name'], '2')
+            elif entry.get('action'):
+                line(f'{marker}  New +', '1;32')
+            else:
+                # The viewer dots are the sidebar's rule, not the desktop render's: the phone is the one
+                # surface where the operator cannot also see the Studio tab, so a lane a browser views has
+                # to say so HERE too (DEF-983).
+                line(f'{marker} {entry.get("icon") or "▧"}  {entry.get("name", entry["id"])}'
+                     + viewer_mark(observed),
+                     '1;32' if selected or entry.get('action') else '1', entry.get('closable', False))
+            if self.entry_height > 1:
+                label = MOBILE_LABELS.get(lane_state, lane_state)
+                detail = ('Viewing · ' if selected else '') + label
+                if entry.get('action'):
+                    detail = 'Create a persistent shell'
+                if observed.get('stale'):
+                    detail += ' · status delayed'
+                line('     ' + detail if not entry.get('divider') else '', '2')
+                line()
+        for _ in range(max(0, rows - (2 + body * self.entry_height + 1))):
+            line()
+        footer = (' /' + self.filter if self.filtering or self.filter else
+                  ' ' + self.banner if self.banner else
+                  ' ' + self.errors[0] if self.errors else
+                  ' ' + self.message if self.message else ' Swipe to scroll · Tap to open')
+        footer, _ = clip(footer, max(1, cols - 1))
+        out.append(f'\033[2m{footer}\033[0m\033[K\033[J')
+        sys.stdout.write(''.join(out))
+        sys.stdout.flush()
+        self.dirty = False
+
+    # ---------------------------------------------------------------- input
+    def handle(self, data):
+        # Bracketed paste (a drop, or a real paste) can span several reads: buffer until its end marker.
+        if self.paste_buffer is not None:
+            self.paste_buffer += data
+            data = ''
+        elif PASTE_START in data:
+            before, _, after = data.partition(PASTE_START)
+            self.paste_buffer, data = after, before
+        if self.paste_buffer is not None and PASTE_END in self.paste_buffer:
+            pasted, _, tail = self.paste_buffer.partition(PASTE_END)
+            self.paste_buffer = None
+            self.dropped(pasted)
+            self.dirty = True
+            data += tail
+        entries = self.visible()
+        i = 0
+        while i < len(data):
+            ch = data[i]
+            if ch == '\033':
+                rest = data[i + 1:]
+                if rest.startswith('[<'):  # SGR mouse
+                    end = next((k for k, c in enumerate(rest) if c in 'Mm'), -1)
+                    if end < 0:
+                        break
+                    try:
+                        button, _x, y = (int(v) for v in rest[2:end].split(';'))
+                    except ValueError:
+                        button, y = -1, 0
+                    pressed = rest[end] == 'M'
+                    if button == 64:
+                        self.cursor -= 3
+                    elif button == 65:
+                        self.cursor += 3
+                    elif button == 0 and pressed and self.box and y >= self.box_top:
+                        self.armed = True   # the click also gave this pane the focus: the next drop lands here
+                    elif button == 0 and pressed:
+                        index = self.top + (y - self.entry_top) // self.entry_height
+                        if 0 <= index < len(entries) and self.entry_top <= y < self.box_top:
+                            self.cursor = index
+                            if entries[index].get('closable') and _x >= max(1, self.size[0] - 4):
+                                self.close_lane(entries[index])
+                            else:
+                                self.open_lane(entries[index])
+                    i += end + 2
+                    self.dirty = True
+                    continue
+                if rest[:2] in ('[A', 'OA'):
+                    self.cursor -= 1; i += 3
+                elif rest[:2] in ('[B', 'OB'):
+                    self.cursor += 1; i += 3
+                elif rest[:2] in ('[C', 'OC'):
+                    if entries:
+                        self.open_lane(entries[self.cursor])
+                    i += 3
+                elif rest[:2] == '[5':
+                    self.cursor -= 10; i += 4
+                elif rest[:2] == '[6':
+                    self.cursor += 10; i += 4
+                elif rest[:1] == '[':  # any other CSI: skip to its final byte
+                    end = next((k for k, c in enumerate(rest[1:], 1) if '@' <= c <= '~'), len(rest) - 1)
+                    i += end + 2
+                else:
+                    if self.armed:
+                        self.armed = False
+                        self.focus_lane()
+                    if self.renaming:
+                        self.renaming, self.rename_entry, self.rename_value = False, None, ''
+                        self.message = 'Cancelled'
+                    elif self.promoting:
+                        self.promoting, self.promote_entry = False, None
+                        self.message = 'Cancelled'
+                    self.filter, self.filtering = '', False
+                    i += 1
+                self.dirty = True
+                continue
+            if self.renaming:
+                if ch in '\r\n':
+                    self.commit_rename()
+                elif ch in '\x7f\x08':
+                    self.rename_value = self.rename_value[:-1]
+                elif ch == '\x1b':   # handled above; here for completeness
+                    pass
+                elif ch.isprintable():
+                    self.rename_value += ch
+            elif self.promoting:
+                if ch in 'yY':
+                    self.commit_promote()
+                else:
+                    self.promoting, self.promote_entry = False, None
+                    self.message = 'Cancelled'
+            elif self.filtering:
+                if ch in '\r\n':
+                    self.filtering = False
+                    if entries:
+                        self.open_lane(entries[min(self.cursor, len(entries) - 1)])
+                elif ch in '\x7f\x08':
+                    self.filter = self.filter[:-1]
+                elif ch.isprintable():
+                    self.filter += ch
+                    self.cursor = 0
+            elif ch in '\r\n ':
+                if entries:
+                    self.open_lane(entries[self.cursor])
+            elif ch in '23' and self.viewports > 1:
+                if entries:
+                    self.open_lane(entries[self.cursor], SLOTS[int(ch) - 1])
+            elif ch in 'JK':  # open the next / previous lane relative to the one being shown
+                lanes = [e for e in entries if not e.get('divider')]
+                if lanes:
+                    ids = [e['id'] for e in lanes]
+                    target = self.current_target()
+                    index = ids.index(target) if target in ids else -1
+                    entry = lanes[(index + (1 if ch == 'J' else -1)) % len(lanes)]
+                    self.cursor = entries.index(entry)
+                    self.open_lane(entry)
+            elif ch == 'j':
+                self.cursor += 1
+            elif ch == 'k':
+                self.cursor -= 1
+            elif ch == 'g':
+                self.cursor = 0
+            elif ch == 'G':
+                self.cursor = len(entries) - 1
+            elif ch == '/':
+                self.filtering, self.filter, self.cursor = True, '', 0
+            elif ch == 'U':
+                self.armed = True
+            elif ch == '+':
+                self.new_shell()
+            elif ch == 'x' and entries:
+                self.close_lane(entries[min(self.cursor, len(entries) - 1)])
+            elif ch == 'R' and entries:
+                entry = entries[min(self.cursor, len(entries) - 1)]
+                self.start_rename(entry)
+            elif ch == 'P' and entries:
+                entry = entries[min(self.cursor, len(entries) - 1)]
+                self.start_promote(entry)
+            elif ch == 'r':
+                self.reload(force=True)
+            self.dirty = True
+            i += 1
+
+    def run(self):
+        fd = sys.stdin.fileno()
+        saved = termios.tcgetattr(fd)
+        try:
+            tty.setraw(fd)
+            sys.stdout.write('\033[?1049h\033[?1000h\033[?1006h\033[?2004h\033[2J')
+            self.reload(force=True)
+            target = self.current_target()
+            for index, entry in enumerate(self.visible()):
+                if entry['id'] == target:
+                    self.cursor = index
+            last_size = None
+            while True:
+                self.reload()
+                self.poll_mobile_view()
+                try:
+                    size = tuple(os.get_terminal_size(sys.stdout.fileno()))
+                except OSError:
+                    size = None
+                if size != last_size:
+                    last_size, self.dirty = size, True
+                self.poll_upload()
+                self.poll_health()
+                if self.upload or self.armed or (self.upload_note and time.time() - self.upload_note_at < 9):
+                    self.dirty = True
+                if self.dirty:
+                    self.render()
+                ready, _, _ = select.select([fd], [], [], 0.15 if self.upload else 1.0)
+                if ready:
+                    data = os.read(fd, 4096)
+                    if not data:
+                        time.sleep(1)  # pty closed: let the wrapper loop decide
+                        return
+                    self.message = ''
+                    self.handle(data.decode('utf-8', 'replace'))
+        finally:
+            sys.stdout.write('\033[?2004l\033[?1006l\033[?1000l\033[?1049l\033[?25h')
+            sys.stdout.flush()
+            termios.tcsetattr(fd, termios.TCSADRAIN, saved)
+
+
+if __name__ == '__main__':
+    if len(sys.argv) < 3:
+        sys.exit('usage: sidebar.py <device> <workspace> [slot]')
+    signal.signal(signal.SIGINT, signal.SIG_IGN)
+    Sidebar(*sys.argv[1:5]).run()