@vibelord/lanes 1.1.1 → 1.2.0

package/payload/lanes/libexec/session_actions.py

@@ -20,8 +20,14 @@ def session_key(entry):
     return entry.get('container'), binding.get('socket'), binding.get('session')
 
 
+def binding_digest(container, socket, name):
+    """sha256 hex of one tmux binding: the tail of `session_id` (its first 10 characters) and the name of the binding's
+    `handback/` file."""
+    return hashlib.sha256(json.dumps([container, socket, name]).encode()).hexdigest()
+
+
 def session_id(workspace, container, socket, name):
-    digest = hashlib.sha256(json.dumps([container, socket, name]).encode()).hexdigest()[:10]
+    digest = binding_digest(container, socket, name)[:10]
     return f'{workspace}--x-{L.slug(name)[:40]}-{digest}'
 
 
@@ -78,6 +84,48 @@ def make_entry(workspace, container, socket, name, pane, previous=None):
     return entry
 
 
+def handback_path(container, socket, name):
+    return L.STATE / 'handback' / (binding_digest(container, socket, name) + '.json')
+
+
+def hand_back(record, identity):
+    """What a session `registrations.unregister` releases keeps as an UNREGISTERED one (cockpit v3 S7): its name in
+    `user-sessions/<id>.json` (make_entry's name authority), the board and id it was registered under in
+    `handback/<binding digest>.json` (`handed_back`: statusd's first listing of it), and its views in
+    `resolve.dynamic/<id>`. `identity` is the {session_id, created} tmux named for the binding: the hand-back is that
+    session's alone. Raises OSError (the caller has already saved the record)."""
+    container, socket, name = session_key(record)
+    binding = {'container': container, 'holder': 'tmux', 'tmux': {'socket': socket, 'session': name}}
+    L.atomic_write(L.STATE / 'user-sessions' / (record['id'] + '.json'),
+                   json.dumps(dict({'id': record['id'], 'workspace': record['workspace']}, **binding,
+                                   name=record['name'])) + '\n')
+    L.atomic_write(handback_path(container, socket, name),
+                   json.dumps(dict({'id': record['id'], 'workspace': record['workspace']}, **binding,
+                                   identity=dict(identity))) + '\n')
+    make_entry(record['workspace'], container, socket, name,
+               {'session_id': identity['session_id'], 'session_created': identity['created']}, record)
+
+
+def handed_back(container, socket, name, pane):
+    """statusd's seed for a session it lists with no listing of its own from the previous cycle -> (board, previous)
+    for `make_entry`, or (None, None). A session that was REGISTERED has none, and statusd would mint its id from
+    whichever board its directory names now — another board's id, under the raw tmux name, whenever the agent moved
+    (fix cycle 1 of S7, DEF-1826). `hand_back` left the board and id it was registered under; they apply only to the
+    session tmux named then (same binding, same session id and creation time), so a session re-created under that name
+    later is attributed as any other. One read of a small file, for a session's first listing only. Never raises on a
+    damaged file (statusd would skip a live session for the cycle): anything unexpected is no hand-back."""
+    meta = L.read_json(handback_path(container, socket, name), {})
+    if not isinstance(meta, dict) or not isinstance(meta.get('tmux'), dict) or \
+            session_key(meta) != (container, socket, name):
+        return None, None
+    identity = meta.get('identity') if isinstance(meta.get('identity'), dict) else {}
+    if (not identity.get('session_id') or identity.get('session_id') != pane.get('session_id')
+            or identity.get('created') != pane.get('session_created')
+            or not all(isinstance(meta.get(field), str) and L.IDENT.match(meta[field]) for field in ('id', 'workspace'))):
+        return None, None
+    return meta['workspace'], {'id': meta['id']}
+
+
 def new_shell(workspace):
     registry = L.load_registry()
     board = next((w for w in registry['workspaces'] if w['id'] == workspace), None)
@@ -143,12 +191,17 @@ def rename_session(workspace, entry, new_name):
     return dict(entry, name=new_name)
 
 
-def rename_registered(manifest_path, repo_id, registry_name, new_name):
+def rename_registered(manifest_path, repo_id, registry_name, new_name, declared_display=None):
     """Display override for one declared terminal. The reader is `lanes_lib._workspace_lanes`, which looks at
     `repositories[i].displayNames` keyed by the terminal's declared name — the manifest's top level (and the
     lane's terminals.json `source`) has no such key. `registry_name` is the lane's title (repository prefix +
-    declared name); renaming back to it clears the override. The lane id never changes (lanes_lib.lane_id_for).
-    The first write keeps a `<manifest>.bak-<UTC timestamp>` copy beside it. Callers run `lanes sync`."""
+    declared name). This is the HOST layer and wins over the container's own `lanes.terminals[<name>].displayName`
+    (LNS-33), which the lane carries as `declared_display` and which this never writes. Renaming back to the lane's
+    default — `declared_display` when the container declares one, else the title — clears the override; any other
+    name (the title included, when the container declares a different name) is kept as one, or the reader would
+    fall back to the container's name and the rename would silently do nothing. The lane id never changes
+    (lanes_lib.lane_id_for). The first write keeps a `<manifest>.bak-<UTC timestamp>` copy beside it. Callers run
+    `lanes sync`."""
     L._title(new_name)
     path = Path(manifest_path)
     original = path.read_text()
@@ -159,8 +212,8 @@ def rename_registered(manifest_path, repo_id, registry_name, new_name):
     prefix = repo.get('prefix') or ''
     declared = registry_name[len(prefix):] if prefix and registry_name.startswith(prefix) else registry_name
     names = repo.setdefault('displayNames', {})
-    if new_name == registry_name:
-        names.pop(declared, None)   # removing the override restores the default title
+    if new_name == (declared_display or registry_name):
+        names.pop(declared, None)   # removing the override restores the lane's default name
     else:
         names[declared] = new_name
     if not any(path.parent.glob(path.name + '.bak-*')):
@@ -169,12 +222,49 @@ def rename_registered(manifest_path, repo_id, registry_name, new_name):
     L.atomic_write(path, json.dumps(data, indent=2, ensure_ascii=False) + '\n', mode=0o644)
 
 
-def promote_to_registered(workspace_id, entry, registry):
+def declared_in(lane):
+    """Where a DECLARED lane is declared, as a person edits it: a repository lane's `source` (its terminals.json, the
+    container's spelling) or `catalog.json` for a lane of an SSH workspace (`sshWorkspaces`); None for anything else —
+    an added session (registered-sessions.json is the registrations module's), an unregistered one, a zmx row."""
+    if lane.get('registered_session') or lane.get('closable'):
+        return None
+    return lane.get('source') or ('catalog.json' if lane.get('holder') == 'ssh' else None)
+
+
+def declared_text(lane, dash='—'):
+    """What `u` (sidebar) and `lanes unregister` say about a declared lane no editor of ours writes — a lane of an SSH
+    workspace, declared in `catalog.json` (`declared_in`): `declared in <where> — edit the file`. A repository lane
+    (its terminals.json `source`) is taken out by `unregister_lane` instead (cockpit v3 S7 + M4, wired at the fan-in).
+    `dash` is the caller's `dash` mark (the sidebar's ASCII footer is seven-bit)."""
+    return f'declared in {declared_in(lane)} {dash} edit the file'
+
+
+def promoted_id(workspace_id, repo_id, name):
+    """The id `lanes sync` gives the terminal `promote_to_registered` declares as `name`: lanes_lib.lane_id_for — the
+    one slug helper sync uses — over the title `_workspace_lanes` builds, the repository's `prefix` + the declared name.
+    The prefix is read from the board's manifest (`repo_id` is the source lane's `repo`); a manifest that cannot be
+    read predicts the unprefixed id. A PREDICTION: sync suffixes an id another lane of the board already holds
+    (`-2`, `build_registry`), so a reader never trusts it without the binding (the sidebar's `settle_pending`)."""
+    prefix = ''
+    if repo_id:
+        try:
+            manifest = L.read_site_json(L.manifest_path(workspace_id))
+            repo = next((r for r in manifest.get('repositories') or []
+                         if isinstance(r, dict) and r.get('id') == repo_id), {})
+            prefix = repo.get('prefix') or ''
+        except (L.LanesError, OSError, ValueError, KeyError, TypeError):
+            prefix = ''
+    return L.lane_id_for(workspace_id, {'name': prefix + name})
+
+
+def promote_to_registered(workspace_id, entry, registry, name=None):
     """Promote an unregistered tmux session to a registered lane by writing its binding to terminals.json.
 
-    The session must have holder=='tmux' and the workspace must have exactly one repository source
-    (unambiguous write target). After this call, callers should run `lanes sync` and reload.
-    Raises LanesError for unsupported configurations or invalid session state."""
+    `name` is the terminal's declared name — the sidebar's `P` asks for it (cockpit v3 S8); without it, the session's
+    own name. The session must have holder=='tmux' and the workspace must have exactly one repository source
+    (unambiguous write target), and neither a published lane nor that file may bind the session already. Returns the id
+    `lanes sync` is expected to give the lane (`promoted_id`). After this call, callers should run `lanes sync`. Raises
+    LanesError for unsupported configurations or invalid session state."""
     if entry.get('holder') != 'tmux':
         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
@@ -189,9 +279,9 @@ def promote_to_registered(workspace_id, entry, registry):
         raise L.LanesError('Workspace not found')
     # Find the terminals.json source — must be a single unambiguous file. A source is (container, spelling): the
     # same spelling in two containers (one repository cloned in two boxes) is two files, so it is still ambiguous.
-    sources = [(lane.get('container') or board.get('container') or '', lane['source'])
-               for lane in board.get('lanes', []) if lane.get('source')]
-    unique_sources = list(dict.fromkeys(sources))
+    sources = {(lane.get('container') or board.get('container') or '', lane['source']): lane.get('repo')
+               for lane in board.get('lanes', []) if lane.get('source')}
+    unique_sources = list(sources)
     if not unique_sources:
         raise L.LanesError(
             'No registry source found for this workspace; add the lane to terminals.json manually')
@@ -210,11 +300,19 @@ def promote_to_registered(workspace_id, entry, registry):
     session_name = tmux.get('session', '')
     if not socket_name or not session_name:
         raise L.LanesError('Session has no tmux binding; cannot promote')
+    name = L._title(entry.get('name', session_name) if name is None else name)
     data = json.loads(terminals_path.read_text())
     terminals = data.get('terminals') or []
     lane_block = data.setdefault('lanes', {})
     lane_terminals = lane_block.setdefault('terminals', {})
-    name = entry.get('name', session_name)
+    # A session this file already binds — under any name — is promoted already: the next sync lists its lane. A
+    # second terminal bound to it would give one tmux session two lanes (DEF-1555's shape), and the registry cannot
+    # say so between the write and the sync that lists it: a `P` on another device, or on this one after the sidebar
+    # let the row go (S8 fix cycle 1, DEF-1762). So the file is asked, as build_registry reads it. Nothing is written.
+    for terminal in terminals:
+        bound = L.declared_tmux(data, terminal.get('name')) or {}
+        if (bound.get('socketName'), bound.get('sessionName')) == (socket_name, session_name):
+            raise L.LanesError(f"Already declared as {terminal.get('name')!r}; lanes sync lists it")
     # Guard: do not overwrite an existing registered terminal with the same name
     if any(t.get('name') == name for t in terminals):
         raise L.LanesError(f'A terminal named {name!r} already exists; rename it first')
@@ -229,6 +327,76 @@ def promote_to_registered(workspace_id, entry, registry):
     # Remove the user-sessions metadata — the terminal is now governed by the registry
     meta_path = L.STATE / 'user-sessions' / (entry['id'] + '.json')
     meta_path.unlink(missing_ok=True)
+    return promoted_id(workspace_id, sources[unique_sources[0]], name)
+
+
+class DeclaredRefused(L.LanesError):
+    """unregister_declared / unregister_lane refused: `code` is the machine code lane-mcp's `lanes_unregister`
+    answers for the same case (last_terminal, adopted_lane, not_declared_here, source_link, …)."""
+
+    def __init__(self, message, code):
+        super().__init__(message)
+        self.code = code
+
+
+def unregister_declared(source_path, name, root=None):
+    """Remove the declared terminal `name` from the terminals.json at `source_path` (the HOST path: L.host_path of the
+    lane's `source`) — its `terminals[]` item and its `lanes.terminals` entry — with the editor lane-mcp's
+    `lanes_unregister` runs in the container (lane_core.terminals_remove through edit_file): one span, re-read before
+    the atomic write, the file's mode kept, never the root `throttle` object, never a rename or reorder, never the
+    last terminal. `root` is the container's home volume: a symbolic link at or above the file below it refuses
+    (`source_link`; from the host it would resolve outside the container, the DEF-1796 class). The session keeps
+    running and shows as an unregistered session once `lanes sync` has run (callers run it; lanes-statusd's
+    hot-sync also starts one within ~15 s of the edit). -> {'path', 'name', 'changed': bool}. DeclaredRefused
+    otherwise. The sidebar's `u` and `lanes unregister` on a declared lane call unregister_lane, which finds both
+    arguments (cockpit v3 S7's hook, wired to this editor at the fan-in)."""
+    core = L.lane_core()
+
+    def transform(text):
+        if text is None:
+            raise core.LaneError(f'{source_path} does not exist', 'source_missing')
+        return core.terminals_remove(text, name)
+    try:
+        before, after, _backup = core.edit_file(Path(source_path), transform, root=root)
+    except core.LaneError as error:
+        raise DeclaredRefused(str(error), error.code or 'refused') from error
+    return {'path': str(source_path), 'name': name, 'changed': before != after}
+
+
+def unregister_lane(lane_id, registry=None):
+    """unregister_declared for a lane of the published registry: a DECLARED tmux lane (a terminals.json `source`),
+    never an adopted session (`registered_session`: registered-sessions.json is its authority) or an unregistered
+    one. The file is reached through the container's home volume (the registry's `containers`, else
+    containers.json) and the terminal found the way lane-mcp finds it (lane_core.declared_name: its tmux binding in
+    `lanes.terminals` or the `throttle` block, else the one name that ends its `registry_name`).
+    -> {'lane', 'source', 'path', 'name', 'changed'}."""
+    core = L.lane_core()
+    registry = L.load_registry() if registry is None else registry
+    lane = next((item for w in registry['workspaces'] for item in w['lanes'] if item['id'] == lane_id), None)
+    if lane is None:
+        raise DeclaredRefused(f'{lane_id} is not a lane of the registry; reload', 'not_in_container')
+    if lane.get('registered_session'):
+        raise DeclaredRefused(f'{lane_id} was adopted (registered-sessions.json), not declared in a terminals.json',
+                              'adopted_lane')
+    if not lane.get('source'):
+        raise DeclaredRefused(f'{lane_id} names no terminals.json', 'not_declared_here')
+    info = (registry.get('containers') or {}).get(lane.get('container')) \
+        or (L.read_json(L.STATE / 'containers.json', {}) or {}).get(lane.get('container')) or {}
+    path = L.host_path(info, lane['source'])
+    try:
+        _ident, text = core._snapshot(path, info['home'])
+    except core.LaneError as error:
+        raise DeclaredRefused(str(error), error.code or 'refused') from error
+    if text is None:
+        raise DeclaredRefused(f'{lane["source"]} does not exist in {lane.get("container")}', 'source_missing')
+    try:
+        doc = core.strict_json(text, lane['source'])
+    except core.LaneError as error:
+        raise DeclaredRefused(str(error), error.code or 'refused') from error
+    name = core.declared_name(doc, lane)
+    if name is None:
+        raise DeclaredRefused(f'{lane["source"]} declares no terminal that matches {lane_id}', 'not_declared_here')
+    return dict(unregister_declared(path, name, root=info['home']), lane=lane_id, source=lane['source'])
 
 
 def close_session(workspace, entry):

package/payload/lanes/libexec/sidebar

@@ -1,8 +1,16 @@
 #!/bin/sh
-# Never leave the sidebar pane empty: restart the TUI if it ever exits.
+# Never leave the sidebar pane empty: restart the TUI if it ever exits (after a 1 s pause: no restart storm).
+# Exit 75 is the sidebar's self-swap (cockpit v3 U5): an update flipped ~/.local/share/lanes/current to a new tree, and
+# the idle sidebar saved its cursor, scroll, seen marks and filter (views/<device>/<ws>.<slot>.sidebar.state) for its
+# successor. Re-execute this wrapper at once — no pause — from $here, the LOGICAL directory it was started from: `cd`
+# and `pwd -L` keep a `current` symlink in it, so a layout's `…/current/libexec/sidebar` now runs the new tree's
+# wrapper and sidebar.py. (A sidebar started from a `pkg/<version>` path never exits 75: its re-exec would run the
+# same tree, so it shows the footer's version note instead.)
 trap '' INT QUIT
-here=$(cd "$(dirname "$0")" && pwd)
+here=$(cd "$(dirname "$0")" && pwd -L)
 while :; do
-    python3 -S -E "$here/sidebar.py" "$@" || :
+    rc=0
+    python3 -S -E "$here/sidebar.py" "$@" || rc=$?
+    if [ "$rc" = 75 ]; then exec "$here/sidebar" "$@"; fi
     sleep 1
 done