@vibelord/lanes 1.1.1 → 1.3.0

package/payload/lanes/libexec/notify.py

@@ -19,12 +19,29 @@ NEEDS_YOU set. The six-word `state` is never read: the agent status is the only
     from the phone's picker never mutes pushes (DEF-1533). 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-1532). A suppressed transition is consumed, never sent later.
+  * Since cockpit v3 R7 (LNS-80) a person's profile `STATE/users/<login>.json` counts as well when its
+    `updated_by_device` is a desk device (same rule) and its mtime is within the window: the sidebar writes the mark
+    of an opened lane there too, so presence never hangs on `clients/<device>.seen.json` staying the place it is
+    kept; a phone's write, and a change no device made, never count: the CLI's writes are stamped `cli:<command>`
+    (`lanes workspaces|lane …`) or `cli:migration` (`lanes device claim`, `lanes keys adopt --login`, `lanes keys
+    owner`), so an admin over SSH naming a desk device mutes nobody (W9 review F3). Each mark belongs to a person (the
+    device's owner, users.login_for over STATE/members; the profile's login) and is recent within that person's own
+    window: their profile's `notify.quiet_s` when set, else the host's `quiet_when_device_active_s`. Recent marks of
+    one person alone mute; recent marks of several people fall back to the host window for all (presence_marks,
+    device_active).
   * 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.
+    when `action_url` (a template over `{lane}`, and `{doc}` for a `published` event — `action_url()`) 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.
 
+Published documents (plan W10 W4): the docs service's publish pick-up (`lanes-docsd`, docsd.Pickup), not this
+service, calls `notify_published` once a document an agent published from a lane is stored — the same config, the
+same desk-presence rule (device_active) and the same `send`, at most one push per lane per minute (docsd's
+PUBLISHED_PUSH_S), best effort. Its payload is `{title: 'Published', message: '<lane name> published a document (<kind>,
+<size>)\n/lanes-docs/d/<id>', priority: 2}` and, when `action_url` is set, the tap target with `{doc}` resolved —
+never the document's title, name or content: the topic is the host's, and the document may be for one login only.
+
 Enrolment requests (W8 A5, LNS-44): the same service also watches `STATE/enrol-requests/` (lanes-enrold's store;
 read through `enrold.load_requests`, so a request announced is one `lanes enrol list` shows). A request that is
 pending — not approved, denied or past `expires_at` — and has not been announced yet yields ONE push:
@@ -45,7 +62,9 @@ Config `~/.config/lanes/notify.conf` (`LANES_NOTIFY_CONF` overrides the path), `
 `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
+template, e.g. `https://lanes.example/?lane={lane}`; plan W10 W7 adds `{doc}`, the page `/lanes-docs/d/<id>` of the
+document a `published` push names — empty for a needs-you push; the docs service sends those, W4). Without a valid
+`url` and `topic` the service only tracks
 transitions and sends nothing. The config is re-read when notify.conf OR its `token_file` changes (inode, size,
 mtime or ctime, so a token written, rotated, removed or chmod-ed after notify.conf counts), and on every tick while
 sending is disabled, so a token that becomes readable switches the pushes on within one interval.
@@ -66,9 +85,11 @@ import urllib.request
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docs_store  # noqa: E402
 import enrold as E  # noqa: E402
 import lanes_lib as L  # noqa: E402
 import tokens  # noqa: E402
+import users as U  # 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
@@ -83,6 +104,9 @@ 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)
+                                                          # users/<login>.json written by a desk device counts too
+PUBLISHED_TITLE = 'Published'                            # a document published from a lane (notify_published)
+PUBLISHED_PRIORITY = 2
 ENROL_DIR = 'enrol-requests'                              # STATE/<this>/<id>.json: lanes-enrold's requests
 ENROL_SEEN = 'notify.enrol-seen.json'                     # STATE/<this>: the request ids already announced
 ENROL_TITLE = 'Enrol request'
@@ -163,37 +187,116 @@ def is_mobile(devices_dir, device):
     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-1533). `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 _names(directory, suffix):
+    try:
+        return {name[:-len(suffix)] for name in os.listdir(directory) if name.endswith(suffix)}
+    except OSError:
+        return set()
+
 
-    def recent(path):
+def presence_marks(clients_dir, devices_dir=None, users_dir=None, members_dir=None, profiles=None):
+    """[(login or None, mtime)]: every mark of someone at a device, whoever's window decides about it.
+      * `clients/<device>.<client>.pid` (`lanes attach`, any device, a phone included);
+      * `clients/<device>.seen.json` of a DESK device (a lane opened from its sidebar);
+      * `users/<login>.json` whose `updated_by_device` is a DESK device (cockpit v3 R7, LNS-80): the sidebar's mark
+        of a lane opened there and every other profile write made at that device (`lanes attach`, `lanes next|prev`,
+        `lanes here`) — so presence does not hang on the seen file staying in clients/. A change no device made is
+        nobody's: a CLI writer (`cli:<command>`, `cli:migration`: users.writer_device is None) or null (W9 review F3).
+    A desk device has a `<device>.*.pid` of any age and a `devices/<device>.json` that is not `mobile: true`
+    (DEF-1533: a phone's picker never counts, however the phone attached). The login of a device mark is its owner
+    (users.login_for over `members/` and `devices/<device>.json`; a pid file belongs to the longest known device name
+    it starts with, None when none or nobody owns it); a profile mark's is the profile's. The directories default to
+    the siblings of `clients_dir` (all four live in STATE); `profiles` is users.load_all(users_dir)'s list when the
+    caller has read it. A directory that cannot be read gives no marks."""
+    directory = Path(clients_dir)
+    state = directory.parent
+    devices_dir = state / 'devices' if devices_dir is None else Path(devices_dir)
+    users_dir = state / 'users' if users_dir is None else Path(users_dir)
+    members_dir = state / 'members' if members_dir is None else Path(members_dir)
+    owners, desks = {}, {}
+
+    def owner(device):
+        if device is None:
+            return None
+        if device not in owners:
+            meta = L.read_json(devices_dir / f'{device}.json')
+            owners[device] = U.login_for(device, meta if isinstance(meta, dict) else {}, members_dir)
+        return owners[device]
+
+    def desk(device):
+        if device not in desks:
+            desks[device] = (bool(device) and any(directory.glob(glob.escape(device) + '.' + PRESENCE))
+                             and not is_mobile(devices_dir, device))
+        return desks[device]
+
+    def mtime(path):
         try:
-            return now - path.stat().st_mtime <= window
+            return path.stat().st_mtime
         except OSError:
-            return False
+            return None
 
+    marks = []
+    known = {name for name in _names(devices_dir, '.json') | _names(members_dir, '.json') if L.IDENT.match(name)}
     try:
-        directory = Path(clients_dir)
-        if any(recent(path) for path in directory.glob(PRESENCE)):
-            return True
+        for path in directory.glob(PRESENCE):
+            at = mtime(path)
+            device = max((name for name in known if path.name.startswith(name + '.')
+                          and len(path.name) > len(name) + len('..pid')), key=len, default=None)
+            if at is not None:
+                marks.append((owner(device), at))
         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
+            device, at = path.name[:-len(SEEN)], mtime(path)
+            if at is not None and desk(device):
+                marks.append((owner(device), at))
     except OSError:
-        return False
-    return False
+        pass
+    for profile in U.load_all(users_dir)[0] if profiles is None else profiles:
+        device = U.writer_device(profile['updated_by_device'])
+        if device and desk(device):
+            at = mtime(U.path(profile['login'], users_dir))
+            if at is not None:
+                marks.append((profile['login'], at))
+    return marks
+
+
+def quiet_windows(profiles):
+    """{login: notify.quiet_s} of the profiles that set their own quiet window (DM-LANES-USER-PROFILE `notify`)."""
+    return {profile['login']: profile['notify']['quiet_s'] for profile in profiles if 'quiet_s' in profile['notify']}
+
+
+def device_active(clients_dir, window, now, devices_dir=None, users_dir=None, members_dir=None):
+    """True when someone was at a device recently enough to mute a push (presence_marks). `window` is the host's
+    `quiet_when_device_active_s`. Each mark is recent within its person's own window — their profile's
+    `notify.quiet_s` when set, else `window`; a device nobody owns always `window`. When the recent marks all
+    belong to one person (or all to devices nobody owns) that is presence; when they belong to several, the host
+    `window` decides for all of them (any mark within it). A window of 0 makes nothing recent: a person's
+    `quiet_s` 0 never mutes their own pushes, a host `window` of 0 never mutes anyone's but a person present alone
+    who set a `quiet_s` of their own. A missing directory is nobody present. Cockpit v3 R7 (LNS-80)."""
+    state = Path(clients_dir).parent
+    users_dir = state / 'users' if users_dir is None else Path(users_dir)
+
+    def within(at, span):
+        return span > 0 and now - at <= span
+
+    profiles = U.load_all(users_dir)[0]
+    marks = presence_marks(clients_dir, devices_dir, users_dir, members_dir, profiles)
+    quiet = quiet_windows(profiles)
+    recent = {login for login, at in marks if within(at, quiet.get(login, window) if login else window)}
+    if len(recent) <= 1:
+        return bool(recent)
+    return any(within(at, window) for _login, at in marks)
+
+
+def action_url(template, lane_id, doc_id=None):
+    """notify.conf's `action_url` template made a push's tap target -> the URL, or '' without a template. `{lane}` is
+    the lane id; `{doc}` (plan W10 W7) the page of the document a `published` event is about, `/lanes-docs/d/<id>`
+    (docs_store.URL; a docs_store id, else nothing), and nothing for an event without one (a needs-you push) — so
+    `https://<host>:8443{doc}` opens the document. Both are percent-quoted."""
+    if not template:
+        return ''
+    doc = docs_store.URL.format(doc_id) if isinstance(doc_id, str) and docs_store.ID_RE.match(doc_id) else ''
+    return (template.replace('{lane}', urllib.parse.quote(lane_id, safe=''))
+            .replace('{doc}', urllib.parse.quote(doc, safe='/')))
 
 
 def _note(lane_id, status, agent, names, config):
@@ -203,14 +306,50 @@ def _note(lane_id, status, agent, names, config):
     first = _line(f'{name}: {task} — {label}' if task else f'{name} — {label}')
     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=''))
+    url = action_url(config.get('action_url') or '', lane_id)
+    if url:
         note['click'] = url
         note['actions'] = [{'action': 'view', 'label': 'Open lane', 'url': url}]
     return note
 
 
+def _size(size):
+    if size < 1024:
+        return f'{size} B'
+    return f'{size / 1024:.1f} KiB' if size < 1024 * 1024 else f'{size / (1024 * 1024):.1f} MiB'
+
+
+def published_note(lane_id, meta, names, config):
+    """The push for a document stored from lane `lane_id` (`meta` its docs_store meta): the lane's name, the kind and
+    the size, and the document's page (module docstring) — never its title, name or content."""
+    name = _text(names.get(lane_id) or lane_id)
+    first = _line(f"{name} published a document ({_text(meta.get('kind'))}, {_size(int(meta.get('bytes') or 0))})")
+    note = {'lane': lane_id, 'status': 'published', 'doc': meta['id'], 'title': PUBLISHED_TITLE,
+            'message': f"{first}\n{docs_store.URL.format(meta['id'])}", 'priority': PUBLISHED_PRIORITY}
+    url = action_url(config.get('action_url') or '', lane_id, meta['id'])
+    if url:
+        note['click'] = url
+        note['actions'] = [{'action': 'view', 'label': 'Open document', 'url': url}]
+    return note
+
+
+def notify_published(lane_id, meta, names=None, conf_path=None, state=None, now=None, opener=None):
+    """Send the `published` push for a stored document (the docs service's pick-up calls it, W4) -> the note sent, or
+    None: sending disabled (no valid notify.conf at `conf_path`, else $LANES_NOTIFY_CONF, else the default), somebody
+    at a desk (device_active over `state`, default L.STATE), or the send failed (one journal line). Never raises for a
+    failed send; the caller rate-limits."""
+    config = read_config(conf_path or os.environ.get('LANES_NOTIFY_CONF') or DEFAULT_CONF)
+    if not config['enabled']:
+        return None
+    state = Path(state) if state is not None else L.STATE
+    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(state / 'clients', window, now, state / 'devices'):
+        return None
+    note = published_note(lane_id, meta, names or {}, config)
+    return note if send(note, config, opener) else None
+
+
 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."""
@@ -427,6 +566,7 @@ def main(argv=None):
         note = {'lane': 'test', 'status': 'test', 'title': 'lanes', 'message': 'lanes notify: test notification',
                 'priority': 3}
         return 0 if send(note, config) else 1
+    L.record_tree('notify', state)   # W9 U0: the unit's tree; `--test` (a one-shot) never records
     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)

package/payload/lanes/libexec/registrations.py

@@ -3,9 +3,25 @@ import json
 import time
 
 import lanes_lib as L
+import session_actions as A
 
 FILENAME = 'registered-sessions.json'
 VERSION = 1
+# What tmux names a session by — the identity statusd publishes on an unregistered row and `register` checks.
+IDENTITY_FORMAT = '#{session_id}\t#{session_created}'
+# tmux saying in words that no session has the name (`_answer`): a target that may not fail ("can't find session"), or
+# a targeted verb on a server holding no session at all ("no current target", `L.tmux_probe`'s DEF-967 note).
+ABSENT_WORDS = ("can't find session", 'no current target')
+
+
+class Unpublished(L.LanesError):
+    """The file was written; handing the session back or publishing the registry then failed (`lanes sync` publishes).
+    `record` is what the call returns when nothing fails — for `unregister`, the record with its `identity`, so the
+    undo still stands although the call raised (fix cycle 1 of S7, DEF-1826)."""
+
+    def __init__(self, message, record):
+        super().__init__(message)
+        self.record = record
 
 
 def key(entry):
@@ -13,6 +29,50 @@ def key(entry):
     return entry.get('container'), binding.get('socket'), binding.get('session')
 
 
+def _identity_query(session):
+    return ['display-message', '-p', '-t', '=' + session + ':', IDENTITY_FORMAT]
+
+
+def _ready(identity):
+    """`register`'s identity gate: a tmux session id `$<n>` and a creation time in digits -> (sid, created)."""
+    identity = identity if isinstance(identity, dict) else {}
+    sid, created = identity.get('session_id', ''), identity.get('created', '')
+    if not isinstance(sid, str) or not isinstance(created, str) or not sid.startswith('$') or not sid[1:].isdigit() or not created.isdigit():
+        raise L.LanesError('Session identity is not ready; wait for the next status update')
+    return sid, created
+
+
+def _probe(container, socket, session):
+    """tmux's answer for one binding's identity: (outcome, text) of `L.tmux_probe` (never starts a server)."""
+    info = (L.read_json(L.STATE / 'containers.json', {}) or {}).get(container) or {}
+    return L.tmux_probe(info, socket, _identity_query(session), 5)
+
+
+def _confirm(container, socket, session, identity):
+    """`register`'s live check: tmux must name this binding's session with exactly this identity, now."""
+    sid, created = _ready(identity)
+    outcome, observed = _probe(container, socket, session)
+    if outcome != 'ok' or observed.strip() != sid + '\t' + created:
+        raise L.LanesError('Session changed or could not be checked; nothing was registered')
+
+
+def _answer(outcome, text):
+    """What tmux's answer to `_identity_query` says about the binding -> ('live', {session_id, created}),
+    ('absent', None) or ('unknown', None). Absent: no server (`noserver`), or tmux 3.4's answer for a name no session
+    has — exit 0 with every field empty, because display-message's target may fail (MEASURED 2026-10-07, tmux 3.4,
+    with other sessions on the server and with none) — or `ABSENT_WORDS`. Unknown: a timeout or any other error (they
+    say NOTHING about the server, `L.tmux_probe`), or an answer that is no identity."""
+    if outcome == 'noserver' or (outcome == 'ok' and not text.strip()):
+        return 'absent', None
+    if outcome == 'ok':
+        parts = text.strip().split('\t')
+        if len(parts) == 2 and parts[0][:1] == '$' and parts[0][1:].isdigit() and parts[1].isdigit():
+            return 'live', {'session_id': parts[0], 'created': parts[1]}
+    elif outcome == 'error' and any(words in text.lower() for words in ABSENT_WORDS):
+        return 'absent', None
+    return 'unknown', None
+
+
 def eligible(entry):
     return entry.get('holder') == 'tmux' and bool(entry.get('tmux')) and not entry.get('legacy')
 
@@ -77,6 +137,17 @@ def apply(registry, data=None):
     return registry
 
 
+def _publish(registry, what):
+    """`publish_registry` for an action a person just took -> the containers whose own `~/.lz/registry.json` it
+    refused (DEF-1796), which the caller raises as `L.ProjectionRefused` once it holds its result. A publish that
+    raises (registry.json itself not written) is the same `<what> saved; run lanes sync …` refusal, without a result:
+    the change is saved but nothing shows it yet."""
+    try:
+        return L.publish_registry(registry) or []
+    except OSError as error:
+        raise L.LanesError(f'{what} saved; run lanes sync to finish publishing: {error}') from error
+
+
 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,
@@ -92,12 +163,12 @@ def rename(lane_id, new_name):
         registry = apply(L.load_registry(), data)
         registry['generated_at'] = time.time()
         L.atomic_write(L.workspaces_dir() / FILENAME, json.dumps(data, ensure_ascii=False, indent=2) + '\n')
-        try:
-            L.publish_registry(registry)
-        except OSError as error:
-            raise L.LanesError('Rename saved; run lanes sync to finish publishing: ' + str(error)) from error
-        return next((lane for w in registry['workspaces'] for lane in w['lanes'] if lane['id'] == lane_id),
+        refused = _publish(registry, 'Rename')
+        lane = next((lane for w in registry['workspaces'] for lane in w['lanes'] if lane['id'] == lane_id),
                     dict(record))
+        if refused:
+            raise L.ProjectionRefused('Rename', refused, lane)
+        return lane
 
 
 def register(workspace, entry, destination=None):
@@ -123,26 +194,153 @@ def register(workspace, entry, destination=None):
         L._require(L.IDENT, container, 'container')
         L._require(L.IDENT, socket, 'tmux socket')
         L._require(L.TMUX_SESSION, name, 'tmux session')
-        identity = actual.get('identity') or {}
-        sid, created = identity.get('session_id', ''), identity.get('created', '')
-        if not isinstance(sid, str) or not isinstance(created, str) or not sid.startswith('$') or not sid[1:].isdigit() or not created.isdigit():
-            raise L.LanesError('Session identity is not ready; wait for the next status update')
-        info = (L.read_json(L.STATE / 'containers.json', {}) or {}).get(container) or {}
-        outcome, observed = L.tmux_probe(info, socket, ['display-message', '-p', '-t', '=' + name + ':',
-                                                      '#{session_id}\t#{session_created}'], 5)
-        if outcome != 'ok' or observed.strip() != sid + '\t' + created:
-            raise L.LanesError('Session changed or could not be checked; nothing was registered')
+        _confirm(container, socket, name, actual.get('identity') or {})
         record = {'id': actual['id'], 'workspace': destination, 'name': L._title(actual['name']),
                   'container': container, 'tmux': dict(actual['tmux']),
                   'folder': L._require(L.SAFE_PATH, board.get('cwd') or L.CONTAINER_HOME, 'working directory')}
         if any(item['id'] == record['id'] or key(item) == key(record) for item in data['sessions']):
             raise L.LanesError(f'Registration already saved; check {FILENAME} and run lanes sync')
         data['sessions'].append(record)
-        registry = apply(registry, data)
+        return _save(registry, data, board, record['id'])
+
+
+def _save(registry, data, board, lane_id):
+    """Write the file, then publish the registry it gives -> the lane as `board` lists it. Holding registry_lock().
+    A publication that fails raises `Unpublished` carrying that lane: the record is saved, `lanes sync` publishes it.
+    A publication that a container refused its own `~/.lz/registry.json` (DEF-1796, `publish_registry`'s answer)
+    raises `L.ProjectionRefused` carrying that lane too: saved and published everywhere else, and said at once."""
+    registry = apply(registry, data)
+    registry['generated_at'] = time.time()
+    L.atomic_write(L.workspaces_dir() / FILENAME, json.dumps(data, ensure_ascii=False, indent=2) + '\n')
+    lane = next(lane for lane in board['lanes'] if lane['id'] == lane_id)
+    try:
+        refused = L.publish_registry(registry) or []
+    except OSError as error:
+        raise Unpublished('Registration saved; run lanes sync to finish publishing: ' + str(error), lane) from error
+    if refused:
+        raise L.ProjectionRefused('Registration', refused, lane)
+    return lane
+
+
+def ghost(record):
+    """The row statusd lists for this session once it is unregistered again — `session_actions.make_entry`'s shape:
+    the record's id and board (statusd's first listing of it takes both from `handback/`, whatever board its directory
+    names now — `session_actions.handed_back`), its name (handed back through `user-sessions/`) and the identity
+    `unregister` observed. The sidebar shows it under Unregistered at once, so the cursor that was on the lane stays
+    on it. None when `unregister` observed no live session (statusd will list nothing). Pure: no file is read or
+    written."""
+    identity = record.get('identity')
+    if not identity:
+        return None
+    return {'id': record['id'], 'name': record['name'], 'holder': 'tmux', 'container': record['container'],
+            'workspace': record['workspace'], 'tmux': dict(record['tmux']), 'color': None, 'icon': '👻',
+            'closable': True, 'identity': dict(identity)}
+
+
+def _listed(data, lane_id):
+    """Whether `apply` lists this record as a lane. It does not when the record's workspace left the catalog, uses
+    another container, or a repository declares the binding: such a record is in the file and nowhere else."""
+    try:
+        registry = apply(L.load_registry(), data)
+    except L.LanesError:
+        return False
+    return any(lane['id'] == lane_id and lane.get('registered_session')
+               for board in registry['workspaces'] for lane in board['lanes'])
+
+
+def unregister(lane_id):
+    """Take one added session out of registered-sessions.json — sidebar `u`, `lanes unregister <id>` (cockpit v3 S7,
+    LNS-65) — and publish the registry without it. Nothing is started, stopped, renamed or reattached: a session that
+    runs goes on as an UNREGISTERED one, under the same id, the same name and the same views. Declared lanes are not
+    here (their file is a repository's terminals.json: `session_actions.unregister_declared`).
+
+    tmux is asked first which session holds the binding (`_answer`). A live one is handed back
+    (`session_actions.hand_back`: its name, its board and id for statusd, its views — all before `publish_registry`
+    removes `resolve/<id>`, so a view that re-attaches in between still resolves). No session there (ended, container
+    down): nothing is handed back, statusd will list nothing. No usable answer (a timeout, an error that is not tmux
+    saying the session is absent): refused, nothing written — a session that runs would otherwise go back with no
+    identity, unnamed, and the undo would refuse it (fix cycle 1, DEF-1826). A record `apply` does not list (`_listed`)
+    is removed without asking tmux: nothing listed it, nothing moves.
+
+    -> the record exactly as it was stored, plus `identity` ({session_id, created}) when a session answered: what
+    `reregister` checks before it saves the record again. Once the record is out of the file, a failure to hand back or
+    publish raises `Unpublished` carrying that same result, so the undo still stands."""
+    with L.registry_lock():
+        data = load()
+        record = next((item for item in data['sessions'] if item['id'] == lane_id), None)
+        if record is None:
+            raise L.LanesError(f'{lane_id} is not a registered session in {FILENAME}; reload')
+        result, identity = dict(record), None
+        if _listed(data, lane_id):
+            state, identity = _answer(*_probe(*key(record)))
+            if state == 'unknown':
+                raise L.LanesError('Session could not be checked; nothing was unregistered')
+            if identity:
+                result['identity'] = identity
+        data['sessions'] = [item for item in data['sessions'] if item['id'] != lane_id]
+        registry = apply(L.load_registry(), data)
         registry['generated_at'] = time.time()
         L.atomic_write(L.workspaces_dir() / FILENAME, json.dumps(data, ensure_ascii=False, indent=2) + '\n')
         try:
-            L.publish_registry(registry)
+            if identity:
+                A.hand_back(record, identity)
+            refused = L.publish_registry(registry) or []
         except OSError as error:
-            raise L.LanesError('Registration saved; run lanes sync to finish publishing: ' + str(error)) from error
-        return next(lane for lane in board['lanes'] if lane['id'] == record['id'])
+            raise Unpublished('Unregistered; run lanes sync to finish publishing: ' + str(error), result) from error
+        if refused:   # out of the file and registry.json; a container's own projection still lists it (DEF-1796)
+            raise L.ProjectionRefused('Unregistered', refused, result)
+        return result
+
+
+def reregister(record):
+    """The undo of `unregister` — sidebar `z` within 10 s (cockpit v3 S7): save the record it returned again, the same
+    id, workspace, name, binding and folder, byte for byte, after the checks `register` makes. Refused, writing
+    nothing, when the binding is registered again meanwhile (a repository declaration or an added session), when its
+    workspace no longer uses that container, or when the session is not the one that was unregistered:
+
+    - `identity` given (a session ran when it was unregistered): `register`'s identity gate, then statusd's listing —
+      a session it lists under that binding must carry that identity — then tmux, now, must name exactly that session
+      (a session closed and re-created under the same name in the window is a different one);
+    - no `identity` (nothing ran there): it is restored only while nothing runs there now, which is the state it was
+      unregistered in — `_answer` says absent; a live session, or no usable answer, refuses.
+
+    A publication that fails after the record is saved raises `Unpublished` (the undo is done; `lanes sync` publishes)."""
+    saved = {'id': record.get('id'), 'workspace': record.get('workspace'), 'name': record.get('name'),
+             'container': record.get('container'), 'tmux': dict(record.get('tmux') or {}),
+             'folder': record.get('folder')}
+    with L.registry_lock():
+        data = load()
+        registry = apply(L.load_registry(), data)
+        for field in ('id', 'workspace', 'container'):
+            L._require(L.IDENT, saved[field], field)
+        L._title(saved['name'])
+        container, socket, session = key(saved)
+        L._require(L.IDENT, socket, 'tmux socket')
+        L._require(L.TMUX_SESSION, session, 'tmux session')
+        L._require(L.SAFE_PATH, saved['folder'], 'working directory')
+        entry = dict(saved, holder='tmux')
+        for board in registry['workspaces']:
+            if any(key(lane) == key(entry) for lane in board['lanes'] if lane.get('holder') == 'tmux'):
+                raise L.LanesError('Already registered in ' + (board.get('title') or board['id']))
+        board = next((w for w in destinations(registry, entry) if w['id'] == saved['workspace']), None)
+        if not board:
+            raise L.LanesError('Choose a workspace that uses this session’s container')
+        if any(item['id'] == saved['id'] or key(item) == key(saved) for item in data['sessions']):
+            raise L.LanesError(f'Registration already saved; check {FILENAME} and run lanes sync')
+        identity = record.get('identity')
+        if identity:
+            _ready(identity)
+            published = (L.read_json(L.STATE / 'status.json', {}) or {}).get('unregistered') or {}
+            if any(isinstance(item, dict) and key(item) == key(saved) and item.get('identity') != identity
+                   for entries in published.values() for item in entries or ()):
+                raise L.LanesError('Session changed; nothing was registered')
+            _confirm(container, socket, session, identity)
+        else:
+            state, _identity = _answer(*_probe(container, socket, session))
+            if state == 'live':
+                raise L.LanesError('A session runs under that name now; add it with a (lanes register); '
+                                   'nothing was registered')
+            if state == 'unknown':
+                raise L.LanesError('Session could not be checked; nothing was registered')
+        data['sessions'].append(saved)
+        return _save(registry, data, board, saved['id'])