@vibelord/lanes 1.0.1 → 1.0.2

package/payload/lanes/libexec/notify.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""Opt-in push notifications: one ntfy message per lane per transition into needs-you (plan Task 14).
+
+The desktop sidebar already raises one OSC 9 per transition while a terminal shows it (spec §4.9); this is the same
+event for the operator who is away from every terminal. `lanes-notify.service` (opt-in — no installer enables it)
+re-reads `STATE/status.json` when its mtime changes (checked every `--interval` seconds, 3 in the unit) and POSTs
+to an ntfy server when a lane's `agent.status` ENTERS `needs_input`, `needs_approval` or `errored` — the sidebar's
+NEEDS_YOU set. The six-word `state` is never read: the agent status is the only input.
+
+  * A status that stays the same is not news; a change between two needs-you statuses is (input → approval).
+  * The first document the service reads only seeds it: lanes that were already waiting when it (re)started are
+    not announced, so a restart never sends a burst.
+  * Presence suppression: nothing is sent while any device was at a desk within `quiet_when_device_active_s`
+    (default 120 s) — measured as the mtime of `STATE/clients/<device>.<client>.pid` (written only by
+    `lanes attach`), or of `STATE/clients/<device>.seen.json` (written by a sidebar when the operator opens a
+    lane) for a DESK device only: one with a `<device>.*.pid` of any age whose `STATE/devices/<device>.json` is not
+    `mobile: true`. Phone presence is decided by the device's mobile layout, not by how it attached: a Safari phone
+    has no `.pid`, and an SSH-only phone that ran `lanes attach phone --mobile` is still mobile, so opening a lane
+    from the phone's picker never mutes pushes (DEF-1452). A phone's own attach within the window still counts.
+    Typing in a lane touches neither file, so this is "attached or opened a lane at a desk recently", not "is
+    looking now" (DEF-1451). A suppressed transition is consumed, never sent later.
+  * Payload: `<lane name>: <agent task> — <status>` and, on a second line, the client command that opens the lane
+    (`lanes-launch lane <id>`). No client registers a URL scheme for it, so the push carries a tappable action only
+    when `action_url` (a template over `{lane}`) is configured.
+  * A failed send is one journal line (lane id and the failure class — never the topic or the bearer) and is not
+    retried; it never stops the service.
+
+Config `~/.config/lanes/notify.conf` (`LANES_NOTIFY_CONF` overrides the path), `key=value` lines, `#` comments,
+re-read when its mtime changes: `url` (ntfy server, http/https, required), `topic` (`[A-Za-z0-9_-]{1,64}`,
+required), `token_file` (a file holding an ntfy access token, optional — sent as a bearer, never logged; an
+unreadable one disables sending rather than sending unauthenticated), `quiet_when_device_active_s` (default 120;
+0 never suppresses), `action_url` (optional template, e.g. `https://lanes.example/?lane={lane}`). Without a valid
+`url` and `topic` the service only tracks transitions and sends nothing.
+
+Answering a `PermissionRequest`-held approval FROM the phone needs a request/response channel back into the hook;
+that is a follow-up design, not part of this module.
+"""
+import argparse
+import glob
+import json
+import os
+import re
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import lanes_lib as L  # noqa: E402
+import tokens  # noqa: E402
+
+TRIGGERS = ('needs_input', 'needs_approval', 'errored')   # the sidebar's NEEDS_YOU (sidebar.ATTENTION[0][3])
+LABELS = tokens.MOBILE_AGENT_LABELS                       # the phone's words: Needs you / Needs approval / Error
+PRIORITY = {'needs_approval': 4, 'errored': 4, 'needs_input': 3}
+DEFAULT_QUIET = 120
+DEFAULT_CONF = '~/.config/lanes/notify.conf'
+KEYS = ('url', 'topic', 'token_file', 'quiet_when_device_active_s', 'action_url')
+TOPIC = re.compile(r'^[A-Za-z0-9_-]{1,64}$')
+UNSAFE = re.compile(r'[\x00-\x1f\x7f-\x9f]')              # C0, DEL, C1: never inside a push line
+TEXT_MAX = 200                                            # characters of the first payload line
+TIMEOUT = 5
+PRESENCE = '*.pid'                                        # clients/ files only `lanes attach` writes
+SEEN = '.seen.json'                                       # a sidebar's opened-lane record; desk devices only
+                                                          # (a .pid of any age, devices/<device>.json not mobile)
+
+
+def _text(value):
+    return UNSAFE.sub('', str(value or ''))
+
+
+def read_config(path):
+    """notify.conf -> {url, topic, token_file, token, quiet_when_device_active_s, action_url, enabled}. Never raises."""
+    raw = {}
+    try:
+        lines = Path(os.path.expanduser(str(path))).read_text().splitlines()
+    except (OSError, UnicodeDecodeError):
+        lines = []
+    for line in lines:
+        line = line.strip()
+        if not line or line.startswith('#') or '=' not in line:
+            continue
+        key, value = (part.strip() for part in line.split('=', 1))
+        if key in KEYS:
+            raw[key] = value
+    try:
+        quiet = max(0, int(raw.get('quiet_when_device_active_s', DEFAULT_QUIET)))
+    except ValueError:
+        quiet = DEFAULT_QUIET
+    url = raw.get('url', '').rstrip('/')
+    topic = raw.get('topic', '')
+    config = {'url': url, 'topic': topic, 'token_file': raw.get('token_file', ''), 'token': None,
+              'quiet_when_device_active_s': quiet, 'action_url': raw.get('action_url', '')}
+    enabled = url.startswith(('http://', 'https://')) and bool(TOPIC.match(topic))
+    if enabled and config['token_file']:
+        try:
+            config['token'] = Path(os.path.expanduser(config['token_file'])).read_text().strip() or None
+        except (OSError, UnicodeDecodeError):
+            config['token'] = None
+        enabled = config['token'] is not None
+    config['enabled'] = enabled
+    return config
+
+
+def agent_statuses(document):
+    """status.json -> {lane id: agent status} for lanes with an agent{} (the six-word `state` is never read)."""
+    lanes = document.get('lanes') if isinstance(document, dict) else None
+    out = {}
+    for lane_id, entry in (lanes.items() if isinstance(lanes, dict) else ()):
+        agent = entry.get('agent') if isinstance(entry, dict) else None
+        if isinstance(agent, dict) and isinstance(agent.get('status'), str):
+            out[lane_id] = agent['status']
+    return out
+
+
+def lane_names(registry):
+    """registry.json -> {lane id: display name} over every workspace's lanes."""
+    out = {}
+    workspaces = registry.get('workspaces') if isinstance(registry, dict) else None
+    for ws in workspaces if isinstance(workspaces, list) else ():
+        if not isinstance(ws, dict):
+            continue
+        for lane in ws.get('lanes') or ():
+            if isinstance(lane, dict) and isinstance(lane.get('id'), str) and lane.get('name'):
+                out[lane['id']] = str(lane['name'])
+    return out
+
+
+def is_mobile(devices_dir, device):
+    """True when `STATE/devices/<device>.json` says `mobile: true` — the phone layout `lanes prepare|attach
+    --mobile` created, the same mark the device's sidebar reads. Missing or unreadable meta is not mobile."""
+    meta = L.read_json(Path(devices_dir) / f'{device}.json')
+    return isinstance(meta, dict) and bool(meta.get('mobile'))
+
+
+def device_active(clients_dir, window, now, devices_dir=None):
+    """True when a device attached (`<device>.<client>.pid`) or a desk device opened a lane (`<device>.seen.json`)
+    within `window` seconds of `now`. `seen.json` counts only for a device that has a `<device>.*.pid` of any age
+    (the mark of `lanes attach`) AND whose `devices_dir/<device>.json` is not `mobile: true`. The mobile flag is
+    the authoritative phone mark: a Safari phone never runs `lanes attach`, but an SSH-only phone may
+    (`lanes attach phone --mobile`, RUNBOOK) and its pid is never removed — so a lane opened from the phone's picker
+    never mutes the phone's own pushes, however it attached (DEF-1452). `devices_dir` defaults to the `devices`
+    directory beside `clients_dir` (both live in STATE). A missing directory is nobody present; a window of 0 is
+    never present."""
+    if window <= 0:
+        return False
+    devices_dir = Path(clients_dir).parent / 'devices' if devices_dir is None else Path(devices_dir)
+
+    def recent(path):
+        try:
+            return now - path.stat().st_mtime <= window
+        except OSError:
+            return False
+
+    try:
+        directory = Path(clients_dir)
+        if any(recent(path) for path in directory.glob(PRESENCE)):
+            return True
+        for path in directory.glob('*' + SEEN):
+            device = path.name[:-len(SEEN)]
+            if (device and recent(path) and any(directory.glob(glob.escape(device) + '.' + PRESENCE))
+                    and not is_mobile(devices_dir, device)):
+                return True
+    except OSError:
+        return False
+    return False
+
+
+def _note(lane_id, status, agent, names, config):
+    label = LABELS.get(status, status)
+    name = _text(names.get(lane_id) or lane_id)
+    task = _text(agent.get('name'))
+    first = f'{name}: {task} — {label}' if task else f'{name} — {label}'
+    if len(first) > TEXT_MAX:
+        first = first[:TEXT_MAX - 1] + '…'
+    note = {'lane': lane_id, 'status': status, 'title': label,
+            'message': f'{first}\nlanes-launch lane {lane_id}', 'priority': PRIORITY.get(status, 3)}
+    template = config.get('action_url') or ''
+    if template:
+        url = template.replace('{lane}', urllib.parse.quote(lane_id, safe=''))
+        note['click'] = url
+        note['actions'] = [{'action': 'view', 'label': 'Open lane', 'url': url}]
+    return note
+
+
+def notify_changes(prev_status, new_status, config, names=None, now=None, clients_dir=None, devices_dir=None):
+    """The notifications for lanes whose agent status ENTERED needs-you between two status.json documents.
+    `prev_status` None = the first read: seed only, nothing is news. Empty when a desk device is present."""
+    if prev_status is None:
+        return []
+    before = agent_statuses(prev_status)
+    lanes = new_status.get('lanes') if isinstance(new_status, dict) else None
+    changed = [(lane_id, status) for lane_id, status in agent_statuses(new_status).items()
+               if status in TRIGGERS and before.get(lane_id) != status]
+    if not changed:
+        return []
+    now = time.time() if now is None else now
+    window = int(config.get('quiet_when_device_active_s', DEFAULT_QUIET) or 0)
+    if device_active(clients_dir if clients_dir is not None else L.STATE / 'clients', window, now, devices_dir):
+        return []
+    names = names or {}
+    return [_note(lane_id, status, lanes[lane_id]['agent'], names, config) for lane_id, status in sorted(changed)]
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *_args, **_kwargs):   # a redirect would carry the bearer elsewhere: refuse it
+        return None
+
+
+def default_opener():
+    return urllib.request.build_opener(_NoRedirect()).open
+
+
+def send(note, config, opener=None):
+    """POST one notification as ntfy JSON to `config['url']`. True when the server accepted it. Any failure is one
+    stderr (journal) line naming the lane and the failure class — never the topic or the bearer — and False."""
+    body = {'topic': config['topic'], 'title': note['title'], 'message': note['message'],
+            'priority': note.get('priority', 3)}
+    for key in ('click', 'actions'):
+        if key in note:
+            body[key] = note[key]
+    headers = {'Content-Type': 'application/json'}
+    if config.get('token'):
+        headers['Authorization'] = f"Bearer {config['token']}"
+    request = urllib.request.Request(config['url'], data=json.dumps(body).encode(), headers=headers, method='POST')
+    try:
+        with (opener or default_opener())(request, timeout=TIMEOUT) as response:
+            status = getattr(response, 'status', 200)
+            if not 200 <= status < 300:
+                raise urllib.error.HTTPError(config['url'], status, 'not accepted', {}, None)
+        return True
+    except urllib.error.HTTPError as error:
+        why = f'HTTP {error.code}'
+    except urllib.error.URLError as error:
+        why = f'unreachable ({type(error.reason).__name__})' if not isinstance(error.reason, str) else 'unreachable'
+    except TimeoutError:
+        why = 'timed out'
+    except OSError as error:
+        why = type(error).__name__
+    except Exception as error:   # a push must never stop the service
+        why = type(error).__name__
+    print(f'notify: send failed for {note.get("lane")}: {why}', file=sys.stderr, flush=True)
+    return False
+
+
+class Watcher:
+    """Tails status.json by mtime; sends what notify_changes returns. The config and registry are re-read when
+    their mtime changes. The first readable document seeds the previous one."""
+
+    def __init__(self, state, conf_path, opener=None, clock=time.time):
+        self.state = Path(state)
+        self.conf_path = Path(os.path.expanduser(str(conf_path)))
+        self.opener, self.clock = opener, clock
+        self.prev = None
+        self.stamps = {}
+        self.config = read_config(self.conf_path)
+        self.names = {}
+
+    def _changed(self, key, path):
+        try:
+            stamp = path.stat().st_mtime_ns
+        except OSError:
+            stamp = None
+        if self.stamps.get(key, 'unset') == stamp:
+            return False
+        self.stamps[key] = stamp
+        return True
+
+    def tick(self):
+        if self._changed('conf', self.conf_path):
+            self.config = read_config(self.conf_path)
+        if self._changed('registry', self.state / 'registry.json'):
+            self.names = lane_names(L.read_json(self.state / 'registry.json'))
+        if not self._changed('status', self.state / 'status.json'):
+            return []
+        document = L.read_json(self.state / 'status.json')
+        if not isinstance(document, dict):
+            return []                   # a torn or missing file: keep the previous document
+        notes = notify_changes(self.prev, document, self.config, names=self.names, now=self.clock(),
+                               clients_dir=self.state / 'clients', devices_dir=self.state / 'devices')
+        self.prev = document
+        if not self.config['enabled']:
+            return []
+        for note in notes:
+            send(note, self.config, self.opener)
+        return notes
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog='notify', description='push needs-you transitions to an ntfy topic')
+    parser.add_argument('--interval', type=float, default=3.0, help='seconds between status.json checks')
+    parser.add_argument('--test', action='store_true', help='send one test notification and exit (1 = not sent)')
+    args = parser.parse_args(argv)
+    conf = os.environ.get('LANES_NOTIFY_CONF') or DEFAULT_CONF
+    state = Path(os.environ.get('LANES_STATE') or L.STATE)
+    if args.test:
+        config = read_config(conf)
+        if not config['enabled']:
+            print(f'notify: {conf} has no valid url and topic (or its token_file is unreadable)', file=sys.stderr)
+            return 1
+        note = {'lane': 'test', 'status': 'test', 'title': 'lanes', 'message': 'lanes notify: test notification',
+                'priority': 3}
+        return 0 if send(note, config) else 1
+    watcher = Watcher(state, conf)
+    if not watcher.config['enabled']:
+        print(f'notify: {conf} has no valid url and topic; tracking only until it does', file=sys.stderr, flush=True)
+    while True:
+        try:
+            watcher.tick()
+        except Exception as error:   # one bad tick is a journal line; the next tick tries again
+            print(f'notify: {type(error).__name__}: {error}', file=sys.stderr, flush=True)
+        time.sleep(max(1.0, args.interval))
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/payload/lanes/libexec/registrations.py

@@ -81,7 +81,7 @@ def rename(lane_id, new_name):
     """Display name of one registered session — this file is its only name authority (`apply` takes the lane's
     name from the record). Only `name` changes: the id, binding, workspace and folder stay, so view targets,
     resolve files and `lane open <id>` keep working. The `user-sessions/` and `resolve.dynamic/` files an
-    UNREGISTERED session is renamed through are never read for a registered one (DEF-1412)."""
+    UNREGISTERED session is renamed through are never read for a registered one (DEF-1475)."""
     name = L._title(new_name)
     with L.registry_lock():
         data = load()

package/payload/lanes/libexec/session_actions.py

@@ -72,8 +72,9 @@ def make_entry(workspace, container, socket, name, pane, previous=None):
     meta = L.read_json(L.STATE / 'user-sessions' / (entry['id'] + '.json'), {}) or {}
     if session_key(meta) == session_key(entry):
         entry['name'] = meta.get('name') or entry['name']
-    L.atomic_write(L.STATE / 'resolve.dynamic' / entry['id'],
-                   '\n'.join(['tmux', container, socket, name, entry['name']]) + '\n')
+    # statusd calls this for every unregistered session on every cycle: rewrite only a changed target or name.
+    L.atomic_write_if_changed(L.STATE / 'resolve.dynamic' / entry['id'],
+                              '\n'.join(['tmux', container, socket, name, entry['name']]) + '\n')
     return entry
 
 
@@ -178,7 +179,7 @@ def promote_to_registered(workspace_id, entry, registry):
         raise L.LanesError('Only tmux sessions can be promoted (zmx and exec holders are not supported)')
     # A binding any board already holds — a repository declaration or an adopted registered session — is
     # registered. Appending it again would make the repository declaration win the binding on the next sync,
-    # re-keying an adopted lane's id and orphaning its view targets (DEF-1411). Nothing is written.
+    # re-keying an adopted lane's id and orphaning its view targets (DEF-1474). Nothing is written.
     if entry.get('registered_session') or session_key(entry) in {
             session_key(lane) for w in registry.get('workspaces', []) for lane in w.get('lanes', [])
             if lane.get('holder') == 'tmux'}:
@@ -244,11 +245,9 @@ def _close_session(workspace, entry):
     if not published or session_key(published) != session_key(entry) or not entry.get('closable'):
         raise L.LanesError('Session changed; reload before closing')
     if entry.get('legacy'):
-        import legacy_sessions
-        legacy_sessions.close(entry)
-        clear_viewers(entry['id'])
-        (L.STATE / 'resolve.dynamic' / entry['id']).unlink(missing_ok=True)
-        return
+        # Plan Task 19 retired the pre-persistence Docker-shell tracker (legacy_sessions.py): only a status.json an
+        # older statusd wrote can still carry such a row. Refused before any process, tmux or file is touched.
+        raise L.LanesError('Legacy shells are retired; nothing was closed')
     registered = {session_key(lane) for w in registry['workspaces'] for lane in w.get('lanes', [])
                   if lane.get('holder') == 'tmux'}
     if session_key(entry) in registered: