@vibelord/lanes 1.1.1 → 1.3.0

package/payload/lanes/libexec/users.py

@@ -0,0 +1,614 @@
+"""lanes users — the per-user profile store users/<quote(login)>.json (cockpit v3 R1, LNS-74).
+
+One JSON file per person under ~/.local/state/lanes/users/ (directory 0700, files 0600), shared by every device that
+person owns (members.owner_for decides ownership, as devices/<device>.json records it):
+
+    {"version": 1, "login": "anna@example.com", "name": "Anna Berg",
+     "look": {"theme": "light", "color": "256", "glyphs": "ascii"},
+     "seen": {"bw-tools--lanes-zellij": 1791000000.25},
+     "workspaces": {"order": ["throttle", "bw-tools"], "hidden": []},
+     "lanes": {"pins": ["bw-tools--lanes-zellij"], "hidden": []},
+     "last_opened": {"lane": "bw-tools--lanes-zellij", "device": "anna-mbp", "at": 1791000000.25},
+     "notify": {"quiet_s": 120}, "updated_at": 1791000000.25, "updated_by_device": "anna-mbp"}
+
+  * The file name is urllib.parse.quote(login, safe='') + '.json' (a login carries '@', and may carry '/'); the
+    `login` inside the file is authoritative: a file whose login is not the one its name quotes is nobody's profile.
+    A login whose quoted name would not fit a file name (MAX_STEM) has no profile.
+  * Times are epoch seconds. `seen` is DM-LANES-CLIENT-SEEN's {lane id: when it was last opened} for the person (the
+    newest MAX_SEEN marks); `look` holds only the keys set, with bin/lanes LOOK_KEYS' values (`notify`/`dim` stay
+    per-device); `notify` holds `quiet_s` only when set; `last_opened` is null until a lane is opened. Lane ids are
+    L.IDENT (at most MAX_LANE_ID characters), workspace ids L.IDENT at most 64, devices members.device_name, `name`
+    one printable line (members._text: no control, format, surrogate, private-use or unassigned character).
+  * Readers are tolerant and never raise: an invalid entry is dropped on its own; unknown top-level keys (a newer
+    additive field) are kept and written back unchanged. A file that is not a JSON object, whose `version` is not 1
+    (absent = 1), or whose login does not match is not read (read() is None) and is never overwritten.
+  * Writers go through update(login, device, fn): under a flock on users/<stem>.lock waited for at most LOCK_S, the
+    stored profile is read, `fn` changes a copy, and the result is MERGED into the stored one: `seen` keeps the
+    later mark per lane, `last_opened` the later `at`, and every other field is last-writer-wins by `updated_at`
+    (stamped later than the stored one, so the writer's version wins them). A timeout, an unwritable store or an
+    unreadable file DROPS the write and returns False — it never raises into a sidebar; the next tick retries. An
+    update that changes nothing writes nothing (readers keyed on the file's mtime stay asleep).
+  * migrate(login) builds the profile from the person's devices: the look from the most recently attached (each look
+    key from the newest device that sets it; an existing profile's keys win), `seen` the union-max of their
+    clients/<device>.seen.json; then those devices' look keys leave devices/<device>.json so the profile wins. A key
+    a device file's `device_only` list names (`lanes attach --device-only`; device_only()) is that device's own and
+    is neither folded nor removed; the other look keys of a device file (unfolded()) are what migrates.
+  * Callers (cockpit v3 R2, LNS-75, bin/lanes): `lanes attach`'s theme/color/glyphs on a device with an owner
+    (login_for) go through update() and leave that device's file, unless `--device-only` keeps them there (and names
+    them in its `device_only` list); `lanes device claim` and `lanes keys adopt --login` / `lanes keys owner` migrate
+    the devices they name (with their windows) — a claim the member record agrees with included, which is how a
+    device owned since W8 folds the look it recorded before R2 (`lanes user show` names that look and the claim, R3
+    review fix DEF-1782); `lanes user list|show` read the store (device_logins, inspect) and write nothing. Since
+    cockpit v3 R3 (LNS-76) the sidebar of a device with an owner paints the profile's look beneath the device file's
+    `device_only` keys, re-reads the profile when its mtime moves (a stamp field), and writes `seen` + `last_opened`
+    through update() when a lane is opened there; `lanes next|prev` write them too. Since cockpit v3 R4 (LNS-77)
+    `workspaces{order, hidden}` arranges the view (arrange(): bin/lanes tab_specs for create_session and `lanes
+    upgrade-session`, which closes a hidden board's tab; the sidebar's phone owner board). Since R6 (LNS-79) `lanes
+    workspaces hide|show|order` and `lanes lane pin|unpin|hide|show` write `workspaces` and `lanes` through update(),
+    and `lanes here <device>` reads `last_opened`. Since R7 (LNS-80) the push notifier (notify.py) reads every profile
+    (load_all): one written by a desk device within the quiet window is presence, and `notify.quiet_s` is that
+    person's own window. `updated_by_device` names the device a change was made AT (a sidebar, `lanes attach`, `lanes
+    next|prev`, `lanes here`); the arranging verbs stamp `cli:<command>` and migrate() `cli:migration` instead
+    (writers that are no device, so an admin's verb over SSH is never somebody at a desk: W9 review F3).
+"""
+import copy
+import fcntl
+import json
+import math
+import os
+import re
+import time
+import urllib.parse
+from pathlib import Path
+
+import lanes_lib as L
+import members
+
+VERSION = 1
+LOCK_S = 1.0                     # seconds update() waits for users/<stem>.lock before it drops the write
+FIELDS = ('version', 'login', 'name', 'look', 'seen', 'workspaces', 'lanes', 'last_opened', 'notify', 'updated_at',
+          'updated_by_device')
+# bin/lanes LOOK_KEYS' theme/color/glyphs, value for value (test_users pins the equality).
+LOOK = {'theme': ('dark', 'light', 'auto'), 'color': ('truecolor', '256', '16', 'none'),
+        'glyphs': ('unicode', 'ascii', 'emoji')}
+MAX_STEM = 200                   # '.' + stem + '.json.' + 8 (L.atomic_write's temp name) stays under NAME_MAX 255
+MAX_LANE_ID = 256                # L.TRACE's cap: a longer lane id cannot be traced either
+MAX_SEEN = 1024                  # newest marks kept; an older mark only re-shows a Done lane until it is opened
+MAX_LANES = 512                  # entries per lanes.pins / lanes.hidden
+MAX_WORKSPACES = 256             # entries per workspaces.order / workspaces.hidden
+MAX_QUIET_S = 86400
+SEEN_SUFFIX = '.seen.json'       # clients/<device>.seen.json (DM-LANES-CLIENT-SEEN)
+STAMPS = ('updated_at', 'updated_by_device')
+# A profile writer that is no device (W9 review F3): `cli:<command>` — the CLI's arranging verbs (`cli:workspaces`,
+# `cli:lane`) and migrate() (MIGRATION, for `lanes device claim` / `lanes keys adopt --login` / `lanes keys owner`).
+# A device name (members.device_name, L.IDENT) cannot hold `:`, so a writer is never read as a device: the push
+# notifier's desk presence (notify.presence_marks) counts only a write a device made (writer_device).
+CLI_WRITER = re.compile(r'cli:[a-z][a-z-]{0,31}\Z')
+MIGRATION = 'cli:migration'
+
+
+def users_dir():
+    return L.STATE / 'users'
+
+
+# ------------------------------------------------------------------------------------------------------ identities
+
+def stem(login):
+    """The file stem of `login`'s profile: the login percent-quoted with nothing safe. Raises L.LanesError for a login
+    members.check_login refuses, or one whose stem is longer than MAX_STEM; never echoes the value."""
+    quoted = urllib.parse.quote(members.check_login(login), safe='')
+    if len(quoted) > MAX_STEM:
+        raise L.LanesError(f'login is too long for a profile file name (quoted, more than {MAX_STEM} characters)')
+    return quoted
+
+
+def login_of(file_stem):
+    """The login a file stem names (the inverse of stem() for every stem it makes)."""
+    return urllib.parse.unquote(file_stem)
+
+
+def path(login, directory=None):
+    return Path(directory or users_dir()) / f'{stem(login)}.json'
+
+
+def lock_path(login, directory=None):
+    return Path(directory or users_dir()) / f'{stem(login)}.lock'
+
+
+def check_lane(value):
+    """A lane id: L.IDENT, at most MAX_LANE_ID characters. Raises L.LanesError (never echoing the value)."""
+    if not isinstance(value, str) or len(value) > MAX_LANE_ID or not L.IDENT.match(value):
+        raise L.LanesError(f'a lane id is not an identifier of at most {MAX_LANE_ID} characters')
+    return value
+
+
+def check_workspace(value):
+    """A workspace id: L.IDENT, at most 64 characters (members' rule for board ids)."""
+    return members._ident(value, 'a workspace id', members.MAX_ID)
+
+
+def cli_writer(command):
+    """The `updated_by_device` a CLI command stamps on a profile it writes: `cli:<command>` (CLI_WRITER)."""
+    return check_writer('cli:' + command)
+
+
+def check_writer(value):
+    """A valid `updated_by_device`: a device name (members.device_name) or a CLI writer (CLI_WRITER). Raises
+    L.LanesError, never echoing the value."""
+    if isinstance(value, str) and CLI_WRITER.match(value):
+        return value
+    try:
+        return members.device_name(value)
+    except L.LanesError:
+        raise L.LanesError('a profile writer is a device name or cli:<command>') from None
+
+
+def writer_device(value):
+    """The device an `updated_by_device` value names — None for a CLI writer, None, or anything invalid: what the
+    push notifier may count as somebody at that device (W9 review F3)."""
+    return value if _valid(members.device_name, value) else None
+
+
+def _valid(check, value):
+    try:
+        check(value)
+    except L.LanesError:
+        return False
+    return True
+
+
+def _time(value):
+    """An epoch-seconds value a profile may hold: a finite, non-negative int or float (never a bool)."""
+    return (isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)
+            and value >= 0)
+
+
+# ---------------------------------------------------------------------------------------------------------- shape
+
+def empty(login):
+    """A profile with nothing set (what a person without a file has), exactly the schema in its order."""
+    return {'version': VERSION, 'login': login, 'name': None, 'look': {}, 'seen': {},
+            'workspaces': {'order': [], 'hidden': []}, 'lanes': {'pins': [], 'hidden': []}, 'last_opened': None,
+            'notify': {}, 'updated_at': 0, 'updated_by_device': None}
+
+
+def _ids(values, check, limit):
+    out, kept = [], set()
+    for value in values if isinstance(values, list) else ():
+        if isinstance(value, str) and value not in kept and _valid(check, value):
+            kept.add(value)
+            out.append(value)
+    return out[:limit]
+
+
+def _bounded(seen):
+    """`seen` as stored: the newest MAX_SEEN marks, keys in order (stable bytes)."""
+    if len(seen) > MAX_SEEN:
+        seen = dict(sorted(seen.items(), key=lambda item: (-item[1], item[0]))[:MAX_SEEN])
+    return dict(sorted(seen.items()))
+
+
+def _last_opened(value):
+    if not isinstance(value, dict):
+        return None
+    lane, device, at = value.get('lane'), value.get('device'), value.get('at')
+    if not (_valid(check_lane, lane) and _valid(members.device_name, device) and _time(at)):
+        return None
+    return {'lane': lane, 'device': device, 'at': at}
+
+
+def normalize(document, login=None):
+    """`document` as a v1 profile: every valid field in schema order, each invalid entry dropped on its own, unknown
+    top-level keys kept after the schema. `login`, when given, is the profile's login whatever the document says.
+    None when `document` is not an object or the login is not valid. Never raises."""
+    if not isinstance(document, dict):
+        return None
+    if not _valid(members.check_login, document.get('login') if login is None else login):
+        return None
+    profile = empty(document.get('login') if login is None else login)
+    name = document.get('name')
+    if _valid(lambda value: members._text(value, 'name', members.MAX_NAME, blanks=True), name):
+        profile['name'] = name
+    look = document.get('look')
+    if isinstance(look, dict):
+        profile['look'] = {key: look[key] for key, allowed in LOOK.items() if isinstance(look.get(key), str)
+                           and look[key] in allowed}
+    seen = document.get('seen')
+    if isinstance(seen, dict):
+        profile['seen'] = _bounded({lane: at for lane, at in seen.items() if _valid(check_lane, lane) and _time(at)})
+    for field, keys, check, limit in (('workspaces', ('order', 'hidden'), check_workspace, MAX_WORKSPACES),
+                                      ('lanes', ('pins', 'hidden'), check_lane, MAX_LANES)):
+        value = document.get(field)
+        if isinstance(value, dict):
+            profile[field] = {key: _ids(value.get(key), check, limit) for key in keys}
+    profile['last_opened'] = _last_opened(document.get('last_opened'))
+    notify = document.get('notify')
+    quiet = notify.get('quiet_s') if isinstance(notify, dict) else None
+    if isinstance(quiet, int) and not isinstance(quiet, bool) and 0 <= quiet <= MAX_QUIET_S:
+        profile['notify'] = {'quiet_s': quiet}
+    if _time(document.get('updated_at')):
+        profile['updated_at'] = document['updated_at']
+    if _valid(check_writer, document.get('updated_by_device')):
+        profile['updated_by_device'] = document['updated_by_device']
+    for key, value in document.items():
+        if isinstance(key, str) and key not in FIELDS:
+            profile[key] = copy.deepcopy(value)
+    return profile
+
+
+def merge(current, incoming):
+    """Two copies of one profile as one: `seen` the later mark per lane, `last_opened` the one with the later `at`,
+    every other field (identity, look, lists, notify, unknown keys, the stamps) from the copy with the later
+    `updated_at` — `incoming` on a tie. Either may be None (the other is returned, normalized). Pure."""
+    older, newer = (normalize(current) if current is not None else None,
+                    normalize(incoming) if incoming is not None else None)
+    if older is None or newer is None:
+        return newer if older is None else older
+    if older['updated_at'] > newer['updated_at']:
+        winner = older
+    else:
+        winner = newer
+    merged = copy.deepcopy(winner)
+    seen = dict(older['seen'])
+    for lane, at in newer['seen'].items():
+        seen[lane] = max(at, seen.get(lane, at))
+    merged['seen'] = _bounded(seen)
+    first, second = older['last_opened'], newer['last_opened']
+    merged['last_opened'] = copy.deepcopy(second if second and (not first or second['at'] >= first['at']) else first)
+    return merged
+
+
+def _encode(profile):
+    try:
+        return (json.dumps(profile, indent=2, ensure_ascii=False) + '\n').encode('utf-8')
+    except UnicodeEncodeError:                 # a lone surrogate in a kept unknown key: escape it rather than fail
+        return (json.dumps(profile, indent=2) + '\n').encode('ascii')
+
+
+def _content(profile):
+    return {key: value for key, value in profile.items() if key not in STAMPS}
+
+
+# --------------------------------------------------------------------------------------------------------- reading
+
+def _load(file, login):
+    """(profile, None), (None, None) when there is no file, or (None, reason) for a file that exists but is not
+    `login`'s v1 profile (the reason never echoes a value)."""
+    try:
+        data = Path(file).read_bytes()
+    except FileNotFoundError:
+        return None, None
+    except OSError as error:
+        return None, error.strerror or 'cannot be read'
+    try:
+        document = json.loads(data.decode('utf-8'))
+    except (UnicodeDecodeError, ValueError):
+        return None, 'not JSON'
+    if not isinstance(document, dict):
+        return None, 'not a JSON object'
+    version = document.get('version', VERSION)
+    if type(version) is not int or version != VERSION:
+        return None, f'not a version {VERSION} profile (another release of lanes wrote it)'
+    if document.get('login') != login:
+        return None, 'its login is not the one its file name quotes'
+    return normalize(document), None
+
+
+def read(login, directory=None):
+    """`login`'s profile, normalized, or None (no file, an invalid login, or a file that is not its v1 profile).
+    Never raises."""
+    try:
+        file = path(login, directory)
+    except L.LanesError:
+        return None
+    return _load(file, login)[0]
+
+
+def inspect(login, directory=None):
+    """(profile, problem) for `lanes user show`: the normalized profile or None, and why a file that exists is not
+    read (a reason that never echoes a value) or None. Raises L.LanesError for a login that can have no profile (the
+    message never echoes it)."""
+    return _load(path(login, directory), login)
+
+
+def load_all(directory=None):
+    """([profiles sorted by file name], [(file name, reason)] for every other users/*.json). Never raises."""
+    profiles, problems = [], []
+    try:
+        files = sorted(Path(directory or users_dir()).glob('*.json'))
+    except OSError:
+        return profiles, problems
+    for file in files:
+        file_stem = file.name[:-len('.json')]
+        login = login_of(file_stem)
+        if not _valid(stem, login) or stem(login) != file_stem:
+            problems.append((file.name, 'its name is not a quoted login'))
+            continue
+        profile, problem = _load(file, login)
+        if problem:
+            problems.append((file.name, problem))
+        elif profile is not None:
+            profiles.append(profile)
+    return profiles, problems
+
+
+# --------------------------------------------------------------------------------------------------------- writing
+
+def _acquire(lock, timeout):
+    """An open descriptor holding an exclusive flock on `lock` (created 0600), or None after `timeout` seconds or on
+    any OS error."""
+    try:
+        fd = os.open(lock, os.O_RDWR | os.O_CREAT | os.O_CLOEXEC, 0o600)
+    except OSError:
+        return None
+    deadline = time.monotonic() + timeout
+    while True:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            return fd
+        except BlockingIOError:
+            left = deadline - time.monotonic()
+            if left <= 0:
+                break
+            time.sleep(min(0.02, left))
+        except OSError:
+            break
+    os.close(fd)
+    return None
+
+
+def _stamp(now, current):
+    """The new `updated_at`: now, but always later than the stored one (a clock that stepped back included)."""
+    now = time.time() if now is None else now
+    return round(max(now, (current['updated_at'] if current else 0) + 0.001), 3)
+
+
+def update(login, device, fn, now=None, directory=None, timeout=LOCK_S):
+    """Change `login`'s profile: `fn` gets a copy of the stored profile (an empty one when there is none) and changes
+    it in place or returns the new one; the result, stamped `updated_at` (now, later than the stored one) and
+    `updated_by_device` = `device` — the device the change was made AT (a sidebar, `lanes attach`, `lanes
+    next|prev`, `lanes here`), a CLI writer `cli:<command>` (cli_writer, MIGRATION: no device, W9 review F3), or None
+    for a caller that names none — is merged into the stored profile (merge()) and written atomically (0600) under the
+    lock. -> True when the profile holds the change (an update that changes nothing writes nothing), False when the
+    write was DROPPED: the lock was not free within `timeout` seconds (`fn` never ran), the login or the writer is not
+    valid (check_writer), the store cannot be written, or the file
+    exists but is not this login's v1 profile (never overwritten). Never raises for those; an exception `fn` raises
+    (the caller's own refusal) propagates and nothing is written."""
+    try:
+        file, lock = path(login, directory), lock_path(login, directory)
+        if device is not None:
+            check_writer(device)
+    except L.LanesError:
+        return False
+    try:
+        members._private_dir(file.parent)
+    except OSError:
+        return False
+    fd = _acquire(lock, timeout)
+    if fd is None:
+        return False
+    try:
+        current, problem = _load(file, login)
+        if problem:
+            return False
+        working = copy.deepcopy(current) if current is not None else empty(login)
+        result = fn(working)
+        incoming = normalize(working if result is None else result, login)
+        if incoming is None:
+            return False
+        incoming['updated_at'], incoming['updated_by_device'] = _stamp(now, current), device
+        merged = merge(current, incoming)
+        if current is not None and _content(merged) == _content(current):
+            return True
+        L.atomic_write(file, _encode(merged), mode=0o600)
+        return True
+    except OSError:
+        return False
+    finally:
+        fcntl.flock(fd, fcntl.LOCK_UN)
+        os.close(fd)
+
+
+# ------------------------------------------------------------------------------------------------------- migration
+
+def _names(directory, suffix):
+    try:
+        return {name[:-len(suffix)] for name in os.listdir(directory) if name.endswith(suffix)}
+    except OSError:
+        return set()
+
+
+def _attached(clients, names):
+    """{device: the newest mtime of its clients/<device>.<client>.pid} — the attach marks `lanes attach` writes. A
+    device name may carry dots (L.IDENT), so each pid file belongs to the LONGEST of `names` it starts with."""
+    newest = {}
+    try:
+        entries = os.listdir(clients)
+    except OSError:
+        return newest
+    for entry in entries:
+        if not entry.endswith('.pid'):
+            continue
+        device = max((name for name in names if entry.startswith(name + '.') and len(entry) > len(name) + 5),
+                     key=len, default=None)
+        if device is None:
+            continue
+        try:
+            mtime = os.stat(os.path.join(clients, entry)).st_mtime
+        except OSError:
+            continue
+        newest[device] = max(mtime, newest.get(device, mtime))
+    return newest
+
+
+def owned_devices(login):
+    """[{device, meta, owner, attached}] for every device `login` owns — a devices/<device>.json view, or a device
+    with a clients/<device>.seen.json left — oldest attach first. The owner is members.owner_for over the device and
+    its recorded base (a window such as mac-2 is the mac's), as create_session derives it; `attached` is the newest
+    clients/<device>.*.pid mtime, else the view's created_at, else 0. Never raises."""
+    devices, clients = L.STATE / 'devices', L.STATE / 'clients'
+    names = {name for name in _names(devices, '.json') | _names(clients, SEEN_SUFFIX)
+             if _valid(members.device_name, name)}
+    attached = _attached(clients, names)
+    found = []
+    for name in names:
+        meta = L.read_json(devices / f'{name}.json')
+        meta = meta if isinstance(meta, dict) else {}
+        owner = members.owner_for((name, meta.get('base')), meta.get('owner'))
+        if owner and owner['login'] == login:
+            created = meta.get('created_at')
+            found.append({'device': name, 'meta': meta, 'owner': owner,
+                          'attached': attached.get(name, created if _time(created) else 0)})
+    return sorted(found, key=lambda found_device: (found_device['attached'], found_device['device']))
+
+
+def owner_of(device, meta=None, members_dir=None):
+    """The normalized owner {login, name, email} `device` follows, or None: members.owner_for over the device and the
+    base its devices/<device>.json records, the recorded owner kept while no member record speaks
+    (DM-LANES-DEVICE-OWNER) — exactly bin/lanes device_owner. `meta` is that file's document when the caller has it;
+    `members_dir` the members/ directory to consult (default members.members_dir(): the sidebar names the one beside
+    its own state). Never raises."""
+    if not _valid(members.device_name, device):
+        return None
+    if meta is None:
+        meta = L.read_json(L.STATE / 'devices' / f'{device}.json')
+    meta = meta if isinstance(meta, dict) else {}
+    return members.owner_for((device, meta.get('base')), meta.get('owner'), directory=members_dir)
+
+
+def login_for(device, meta=None, members_dir=None):
+    """The login whose profile `device` follows (cockpit v3 R2, LNS-75): owner_of's login, None for a device nobody
+    owns — which keeps its look and seen marks to itself. Callers: bin/lanes profile_for (`lanes attach`, `lanes
+    next|prev`) and the sidebar (cockpit v3 R3, LNS-76), so the profile a look is written to is the one painted. Never
+    raises."""
+    owner = owner_of(device, meta, members_dir)
+    return owner['login'] if owner else None
+
+
+def device_logins():
+    """{device: login or None} for every device lanes knows of — a devices/<device>.json view, a members/<device>.json
+    record, a clients/<device>.seen.json — through login_for. What `lanes user list|show` group by. Never raises."""
+    names = (_names(L.STATE / 'devices', '.json') | _names(members.members_dir(), '.json')
+             | _names(L.STATE / 'clients', SEEN_SUFFIX))
+    return {name: login_for(name) for name in sorted(names) if _valid(members.device_name, name)}
+
+
+# ------------------------------------------------------------------------------------- the person's arrangement
+
+def arrange(boards, profile):
+    """The workspace boards a person sees, in their order (cockpit v3 R4, LNS-77): `boards` (registry.json's
+    `workspaces`, catalog order) without the ids the profile's `workspaces.hidden` names, ordered by its
+    `workspaces.order` — the ids it names first, in its order (an id no board has is ignored), every board it does not
+    name after them in catalog order. An empty visible set is refused: a hidden list that would leave no board hides
+    none (no view, sidebar or phone is ever left without a board; the order still applies). `profile` None, or one
+    without `workspaces`, is the catalog unchanged. A new list; `boards` is not modified. Pure; never raises.
+    Callers: bin/lanes tab_specs (the tabs a view has, `lanes upgrade-session` closing the hidden ones) and the
+    sidebar (the phone's owner board, the first one shown)."""
+    spaces = profile.get('workspaces') if isinstance(profile, dict) else None
+    spaces = spaces if isinstance(spaces, dict) else {}
+    order, hidden = (spaces.get(key) if isinstance(spaces.get(key), list) else [] for key in ('order', 'hidden'))
+    rank = {}
+    for ident in order:
+        if isinstance(ident, str):
+            rank.setdefault(ident, len(rank))
+    hidden = {ident for ident in hidden if isinstance(ident, str)}
+    shown = [board for board in boards if board.get('id') not in hidden] or list(boards)
+    keyed = sorted(enumerate(shown), key=lambda item: (0, rank[item[1].get('id')], item[0])
+                   if item[1].get('id') in rank else (1, 0, item[0]))
+    return [board for _index, board in keyed]
+
+
+# ------------------------------------------------------------------------------------------- a device file's own look
+
+def device_only(meta):
+    """{key: value} of the look devices/<device>.json keeps for that device alone: each LOOK key its `device_only` list
+    names (`lanes attach --device-only` writes the list, cockpit v3 R3 review fix, DEF-1782) and holds a valid value
+    for, in LOOK order. Only these win over the owner's profile on that device (sidebar.layered_look). Anything that
+    is not such a list marks nothing. Pure; never raises."""
+    marked = meta.get('device_only') if isinstance(meta, dict) else None
+    if not isinstance(marked, list):
+        return {}
+    return {key: meta[key] for key, allowed in LOOK.items()
+            if key in marked and isinstance(meta.get(key), str) and meta[key] in allowed}
+
+
+def unfolded(meta):
+    """{key: value} of the device file's OTHER valid LOOK keys: a look recorded on the device before it had an owner,
+    or by a release before R2 gave owners a profile (whose record_look wrote every flag to the device file and marked
+    none). On a device with an owner it is painted only where the profile sets none (sidebar.layered_look), `lanes user
+    show` names it, and it is what migrate folds into the profile (`lanes device claim`, also when the member record
+    already names that login; `keys adopt --login`; `keys owner`). Never folded behind anyone's back: a device handed
+    to another person still holds its previous owner's look. Pure; never raises."""
+    if not isinstance(meta, dict):
+        return {}
+    own = device_only(meta)
+    return {key: meta[key] for key, allowed in LOOK.items()
+            if key not in own and isinstance(meta.get(key), str) and meta[key] in allowed}
+
+
+def mark_device_only(meta, keys):
+    """A copy of devices/<device>.json `meta` whose `device_only` list names `keys` (LOOK's keys among them, in LOOK
+    order), or without the list when none is left — so a device that never used --device-only keeps its bytes."""
+    marked = [key for key in LOOK if key in set(keys)]
+    updated = dict(meta)
+    if marked:
+        updated['device_only'] = marked
+    else:
+        updated.pop('device_only', None)
+    return updated
+
+
+def _drop_look(device):
+    """Remove the unfolded LOOK keys from an existing devices/<device>.json (bin/lanes' own encoding) — never a
+    --device-only one or its mark (an invalid value goes, and its mark with it); never creates the file."""
+    file = L.STATE / 'devices' / f'{device}.json'
+    meta = L.read_json(file)
+    if not isinstance(meta, dict):
+        return
+    own = device_only(meta)
+    updated = {key: value for key, value in meta.items() if key not in LOOK or key in own}
+    if 'device_only' in meta:
+        updated = mark_device_only(updated, own)
+    if updated == meta:
+        return
+    try:
+        L.atomic_write(file, json.dumps(updated) + '\n')
+    except OSError:
+        pass
+
+
+def migrate(login, devices=None, now=None, timeout=LOCK_S):
+    """Build `login`'s profile from the devices it owns (owned_devices; only those named in `devices` when given):
+    each look key from the most recently attached device that sets it, unless the profile already has that key;
+    `seen` the union-max of the devices' clients/<device>.seen.json and the profile's own; `name` from the member
+    record when the profile has none. Written through update() as MIGRATION (`cli:migration`: the fold is a CLI act —
+    a claim or an adoption, often over SSH — never somebody at one of those devices, W9 review F3); only after it
+    landed do those devices' look keys (theme, color, glyphs — never notify/dim) leave devices/<device>.json, so the
+    profile wins. A key the device file's `device_only` list marks (`lanes attach --device-only`) is the device's own
+    choice: it is neither folded nor removed (unfolded() is what moves). -> the stored profile (an empty one for a
+    login that owns no device), or None when the write was dropped (the lock, an unreadable profile, an invalid login:
+    no device file is touched then). Never raises."""
+    if not _valid(members.check_login, login):
+        return None
+    wanted = None if devices is None else {devices} if isinstance(devices, str) else set(devices)
+    owned = [found for found in owned_devices(login) if wanted is None or found['device'] in wanted]
+    look, seen = {}, {}
+    for found in owned:                                 # oldest attach first: the newest device's value wins per key
+        look.update(unfolded(found['meta']))
+        marks = L.clean_seen(L.read_json(L.STATE / 'clients' / f"{found['device']}{SEEN_SUFFIX}"))
+        for lane, at in marks.items():
+            seen[lane] = max(at, seen.get(lane, at))
+    name = next((found['owner']['name'] for found in reversed(owned) if found['owner'].get('name')), None)
+
+    def fill(profile):
+        profile['look'] = {**look, **profile['look']}
+        for lane, at in seen.items():
+            profile['seen'][lane] = max(at, profile['seen'].get(lane, at))
+        if profile['name'] is None and name:
+            profile['name'] = name
+
+    if not update(login, MIGRATION, fill, now=now, timeout=timeout):
+        return None
+    for found in owned:
+        _drop_look(found['device'])
+    return read(login)