@vibelord/lanes 1.0.0

package/payload/lanes/client/omarchy/discover.sh

@@ -0,0 +1,56 @@
+#!/bin/sh
+# READ-ONLY discovery for the lanes client on an Omarchy machine. Changes nothing. Run it on the machine
+# (or:  ssh anarchy 'sh -s' < client/omarchy/discover.sh ). Output is the input for install.sh decisions.
+section() { printf '\n== %s\n' "$1"; }
+have() { command -v "$1" >/dev/null 2>&1; }
+show() { [ -r "$1" ] && { printf -- '--- %s\n' "$1"; sed -n "1,${2:-40}p" "$1"; } || printf -- '--- %s (absent)\n' "$1"; }
+
+section system
+uname -srm; . /etc/os-release 2>/dev/null && echo "$PRETTY_NAME"
+for v in "$HOME/.local/share/omarchy/version" /usr/share/omarchy/version; do [ -r "$v" ] && echo "omarchy version file: $(cat "$v")"; done
+have omarchy-version && echo "omarchy-version: $(omarchy-version 2>/dev/null)"
+[ -d "$HOME/.local/share/omarchy/.git" ] && echo "omarchy git: $(git -C "$HOME/.local/share/omarchy" describe --tags --always 2>/dev/null)"
+echo "cpu: $(grep -m1 'model name' /proc/cpuinfo | cut -d: -f2- | sed 's/^ //') x$(nproc)"; free -h | sed -n 2p
+lspci 2>/dev/null | grep -i -E 'vga|3d|display' | cut -c1-120
+
+section 'display + hyprland'
+have hyprctl && { hyprctl version 2>/dev/null | sed -n '1,3p'; hyprctl monitors 2>/dev/null | grep -E '^Monitor|\s+[0-9]+x[0-9]+@|scale' | head -12; }
+echo "XDG_CURRENT_DESKTOP=${XDG_CURRENT_DESKTOP:-} XDG_SESSION_TYPE=${XDG_SESSION_TYPE:-}"
+
+section terminals
+for t in ghostty alacritty kitty foot wezterm; do have $t && echo "$t: $($t --version 2>/dev/null | head -1)"; done
+show "$HOME/.config/xdg-terminals.list" 10
+echo "TERMINAL=${TERMINAL:-unset}"; grep -rhs 'TERMINAL' "$HOME/.config/uwsm/default" "$HOME/.config/uwsm/env" 2>/dev/null | head -5
+show "$HOME/.config/ghostty/config" 60
+ls -la "$HOME/.config/omarchy/current/" 2>/dev/null | cut -c1-140
+ls "$HOME/.config/omarchy/current/theme/" 2>/dev/null | tr '\n' ' '; echo
+have ghostty && { echo "--- ghostty default keybinds using ctrl+alt:"; ghostty +list-keybinds --default 2>/dev/null | grep -i 'ctrl+alt\|alt+ctrl' | head -20; }
+infocmp xterm-ghostty >/dev/null 2>&1 && echo "terminfo xterm-ghostty: present" || echo "terminfo xterm-ghostty: MISSING"
+
+section 'hyprland config (user-owned files)'
+show "$HOME/.config/hypr/hyprland.conf" 40
+echo "--- bindings that involve CTRL+ALT anywhere:"
+grep -rhn -i -E '^\s*bind[a-z]*\s*=\s*[^,]*CTRL[^,]*ALT|^\s*bind[a-z]*\s*=\s*[^,]*ALT[^,]*CTRL' "$HOME/.config/hypr" "$HOME/.local/share/omarchy/default/hypr" 2>/dev/null | cut -c1-160 | head -30
+echo "--- is SUPER SHIFT, L taken?"
+grep -rhn -i -E '^\s*bind[a-z]*\s*=\s*SUPER SHIFT\s*,\s*L\s*,' "$HOME/.config/hypr" "$HOME/.local/share/omarchy/default/hypr" 2>/dev/null | head -5
+echo "--- window rule syntax in use:"; grep -rhs -m3 -E '^\s*windowrule(v2)?\s*=' "$HOME/.local/share/omarchy/default/hypr" "$HOME/.config/hypr" 2>/dev/null | head -4
+have uwsm && echo "uwsm: yes"; have uwsm-app && echo "uwsm-app: yes"; ls "$HOME/.local/share/omarchy/bin" 2>/dev/null | grep -E 'launch|tui|terminal' | tr '\n' ' '; echo
+
+section 'network + ssh'
+have tailscale && { tailscale version 2>/dev/null | head -1; tailscale status 2>&1 | head -4; }
+systemctl is-enabled sshd 2>/dev/null | sed 's/^/sshd enabled: /'; systemctl is-active sshd 2>/dev/null | sed 's/^/sshd active: /'
+(have ufw && sudo -n ufw status verbose 2>/dev/null | head -12) || echo "ufw status needs sudo (skipped)"
+ssh -V 2>&1
+ls -la "$HOME/.ssh" 2>/dev/null | awk '{print $1, $NF}' | grep -v -E '^total' | head -14
+grep -n -i -E '^\s*(Host|Include)\s' "$HOME/.ssh/config" 2>/dev/null | head -20
+echo "--- can this machine reach the lanes server directly?"
+# Use the installed alias; never probe a particular deployment from a generic diagnostic.
+ssh -o BatchMode=yes -o ConnectTimeout=4 lanes true </dev/null 2>/dev/null &&
+    echo 'lanes: SSH reachable and authorized' || echo 'lanes: not configured, unreachable, or unauthorized'
+pgrep -af 'ssh .*-R ' 2>/dev/null | cut -c1-160 | head -4
+
+section 'existing multiplexer / lanes bits'
+for t in zellij tmux mosh coder; do have $t && echo "$t: $($t --version 2>/dev/null | head -1)"; done
+ls -d "$HOME/.config/zellij" "$HOME/.config/lanes" "$HOME/lanes" "$HOME/.local/bin/coder-launch" "$HOME/.local/bin/lanes-launch" 2>/dev/null
+fc-list 2>/dev/null | grep -i -E 'jetbrains|caskaydia|nerd' | cut -d: -f2 | sort -u | head -8
+echo "shell: $SHELL"; echo done

package/payload/lanes/client/omarchy/lanes.conf

@@ -0,0 +1,5 @@
+# lanes on Hyprland with a hyprlang config (Omarchy 3.x). Sourced from ~/.config/hypr/hyprland.conf.
+bindd = SUPER SHIFT, L, Lanes, exec, omarchy-launch-or-focus ^org\.omarchy\.lanes$ "uwsm-app -- lanes-window"
+bindd = SUPER SHIFT ALT, L, Lanes (wide 2 viewports), exec, uwsm-app -- lanes-window w2
+# Omarchy 3's terminal tag does not cover org.omarchy.*: tag the lanes window so Super+C/V use the terminal keys.
+windowrule = tag +terminal, match:class ^(org\.omarchy\.lanes)$

package/payload/lanes/client/omarchy/lanes.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Type=Application
+Name=Lanes
+Comment=Remote agent lanes on the workspace server
+Exec=lanes-window
+Icon=utilities-terminal
+Terminal=false
+Categories=Development;
+StartupWMClass=org.omarchy.lanes

package/payload/lanes/client/omarchy/lanes.lua

@@ -0,0 +1,14 @@
+-- lanes workspace server client (see ~/lanes/docs/RUNBOOK.md). Loaded from ~/.config/hypr/hyprland.lua
+-- by one line:  require("hypr.lanes")   — remove that line and this file to uninstall.
+
+-- Launch-or-focus, Omarchy's own form (as shipped for Obsidian): pressing it again focuses the lanes window.
+o.bind("SUPER + SHIFT + L", "Lanes", { launch = "lanes-window", focus = "^org\\.omarchy\\.lanes$" })
+-- A WIDE view session for a full-width window: two viewports side by side per workspace (w3 = three).
+-- In the sidebar: Enter opens in the first viewport, 2 / 3 open the lane in the second / third.
+o.bind("SUPER + SHIFT + ALT + L", "Lanes (wide, 2 viewports)", { launch = "lanes-window w2" })
+
+-- Screenshot / copied file on the clipboard -> the board's uploads/ folder, and its path typed into the lane you look at.
+o.bind("SUPER + SHIFT + U", "Lanes: upload clipboard", "lanes-upload --clipboard --paste")
+
+-- Optional, like the org.omarchy.herdr rule: keep the lanes window on a fixed workspace.
+-- o.window([[^org\.omarchy\.lanes$]], { workspace = "4 silent" })

package/payload/lanes/client/ssh.stanza.in

@@ -0,0 +1,54 @@
+# lanes: direct path to the workspace server "@ALIAS@" (Tailscale, no relay in between).
+# Generated by the lanes installer into ~/.ssh/config.d/lanes.conf and pulled in by ONE `Include` line in
+# ~/.ssh/config; nothing else in your SSH setup is changed. Re-run the installer instead of editing this file.
+# Options that only some OpenSSH builds know (ObscureKeystrokeTiming, UseKeychain) are written ONLY when this
+# machine's ssh accepts them: an unknown option is a parse error for EVERY host, even inside a non-matching block.
+Host lanes
+    HostName @HOST@
+    User @USER@
+    HostKeyAlias @ALIAS@
+    IdentityFile @IDENTITY@
+    IdentitiesOnly yes
+    RequestTTY force
+    # Patient on purpose. ConnectTimeout also covers banner + key exchange: a server under memory pressure needs more
+    # than 5 s for those alone and must not look unreachable. A dead path (sleep/wake, Wi-Fi change) is detected
+    # within ~60 s and the client loop reconnects; giving up after 15 s turned a slow server into a reconnect storm.
+    ConnectTimeout 20
+    ServerAliveInterval 10
+    ServerAliveCountMax 6
+    TCPKeepAlive no
+#@OBSCURE@     # OpenSSH >= 9.5 quantises keystrokes to 20 ms and adds chaff; on a private WireGuard path that is pure latency.
+#@OBSCURE@     ObscureKeystrokeTiming no
+    Compression no
+    # A passphrase is asked once: the key then lives in the agent (and, on macOS, the keychain).
+    AddKeysToAgent yes
+#@KEYCHAIN@     UseKeychain yes
+    # One dedicated connection per window: never reuse a master left behind by a sleeping laptop.
+    ControlMaster no
+    ControlPath none
+    ForwardAgent no
+    ForwardX11 no
+    LogLevel ERROR
+#@PUBLIC@
+#@PUBLIC@ # Fallback path: the same sshd over the server's public address (key-only). lanes-launch uses it only after two
+#@PUBLIC@ # immediate connect failures on `lanes` (tailnet down); it goes back to the tailnet on the next healthy session.
+#@PUBLIC@ Host lanes-public
+#@PUBLIC@     HostName @PUBLIC_HOST@
+#@PUBLIC@     User @USER@
+#@PUBLIC@     HostKeyAlias @ALIAS@
+#@PUBLIC@     IdentityFile @IDENTITY@
+#@PUBLIC@     IdentitiesOnly yes
+#@PUBLIC@     RequestTTY force
+#@PUBLIC@     ConnectTimeout 20
+#@PUBLIC@     ServerAliveInterval 10
+#@PUBLIC@     ServerAliveCountMax 6
+#@PUBLIC@     TCPKeepAlive no
+#@PUBLIC@ #@OBSCURE@     ObscureKeystrokeTiming no
+#@PUBLIC@     Compression yes
+#@PUBLIC@     AddKeysToAgent yes
+#@PUBLIC@ #@KEYCHAIN@     UseKeychain yes
+#@PUBLIC@     ControlMaster no
+#@PUBLIC@     ControlPath none
+#@PUBLIC@     ForwardAgent no
+#@PUBLIC@     ForwardX11 no
+#@PUBLIC@     LogLevel ERROR

package/payload/lanes/container/env.sh

@@ -0,0 +1,16 @@
+# lanes env.sh — keep temp files OFF the RAM-backed /tmp. POSIX sh; SOURCED (never executed) from the shell profiles
+# as ~/.lz/env.sh, so it must be safe under `set -eu`, print nothing, and leave no helper variable behind.
+#
+# /tmp in the container is a tmpfs: every byte in it is container memory (2026-09-19: 95 of 208 GiB). This points
+# the two knobs that fill it — TMPDIR (compilers, test runners, mktemp) and CLAUDE_CODE_TMPDIR (agent scratch and
+# task output) — at a directory on the home volume instead. `lanes tmp reap` keeps that directory from growing.
+#   * Only NEW shells and agents see it; whatever already runs keeps /tmp until it restarts.
+#   * tmux is NOT affected: it honours TMUX_TMPDIR only, so lane sockets stay in /tmp/tmux-<uid>.
+#   * Nothing is created here: no directory (or a read-only one) = no change. Opt out per shell or for good with
+#     LANES_TMP_OPTOUT=1 (any value, even empty, counts). LANES_TMP_DIR names another directory.
+if [ -z "${LANES_TMP_OPTOUT+set}" ] && [ -d "${LANES_TMP_DIR:-/home/coder/.tmp}" ] \
+        && [ -w "${LANES_TMP_DIR:-/home/coder/.tmp}" ] && [ -x "${LANES_TMP_DIR:-/home/coder/.tmp}" ]; then
+    TMPDIR=${LANES_TMP_DIR:-/home/coder/.tmp}
+    CLAUDE_CODE_TMPDIR=$TMPDIR
+    export TMPDIR CLAUDE_CODE_TMPDIR
+fi

package/payload/lanes/container/lane

@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+"""lane — the in-container lane contract (Python 3 stdlib). Installed at /home/coder/.lz/bin/lane.
+
+A lane is one long-lived agent terminal, held by a per-lane zmx daemon (byte pass-through + instant
+re-attach). Viewers, orchestrators and the web harness use ONLY these verbs, so the holder stays swappable.
+
+  lane new <id> [--ws W] [--title T] [--cwd DIR] [--icon I] [--color C] -- <command...>
+  lane open <lane-id>         the uniform entry point for editors (Cursor / VS Code terminals.json): attach to the
+                              lane; if it does not exist, run its recorded create recipe. Never nests inside tmux.
+                              While the lanes view shows the lane, attach with ignore-size (the lanes view owns the size).
+  lane attach <id>            attach this terminal (never creates)
+  lane send <id> <text...>    type into the lane (use $'\\r' for Enter)
+  lane capture <id> [--lines N] [--vt]   print scrollback (plain text, or VT with --vt)
+  lane ls [--json]            lanes with holder metadata
+  lane status <id>            JSON: running?, last exit of the agent command, meta
+  lane kill <id>              stop the lane (the ONLY verb that ends an agent)
+"""
+import json
+import os
+import pty
+import re
+import select
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+ROOT = Path(os.environ.get('LANE_ROOT', '/home/coder/.lz'))
+VERSION = os.environ.get('LANE_ZMX_VERSION', '0.8.1')
+ZMX = ROOT / 'bin' / f'zmx-{VERSION}'
+SOCKETS, META, STATE = ROOT / 's', ROOT / 'meta', ROOT / 'state'
+IDENT = re.compile(r'^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$')
+
+
+def zmx_env(extra=None):
+    env = {'PATH': '/usr/local/bin:/usr/bin:/bin', 'HOME': str(Path.home()), 'SHELL': '/bin/bash',
+           'LANG': 'C.UTF-8', 'ZMX_DIR': str(SOCKETS), 'ZMX_NO_DETACH_KEY': '1',
+           'TERM': os.environ.get('TERM', 'xterm-256color')}
+    env.update(extra or {})
+    return env
+
+
+def zmx(*args, **kwargs):
+    return subprocess.run([str(ZMX), *args], env=zmx_env(), capture_output=True, text=True, timeout=30, **kwargs)
+
+
+def lane_id(value):
+    if not IDENT.match(value or ''):
+        sys.exit('lane: invalid lane id (letters, digits, _ . -; max 64)')
+    return value
+
+
+def alive(name):
+    """The socket file is the liveness signal; `zmx list` supplies the metadata.
+    (`zmx list` rows can be indented / carry a current-session marker: keys are stripped when parsed.)"""
+    try:
+        return (SOCKETS / name).is_socket()
+    except OSError:
+        return False
+
+
+def sessions(expect=None, attempts=4):
+    rows = {}
+    for attempt in range(attempts):
+        rows = {}
+        for line in zmx('list').stdout.splitlines():
+            fields = {k.strip(' \u2192*>'): v for k, v in (part.split('=', 1) for part in line.split('\t') if '=' in part)}
+            if fields.get('name'):
+                rows[fields['name']] = fields
+        if not expect or expect in rows or not alive(expect):
+            break
+        time.sleep(0.4)
+    return rows
+
+
+def option(args, name, default=None):
+    if name in args:
+        index = args.index(name)
+        value = args[index + 1]
+        del args[index:index + 2]
+        return value
+    return default
+
+
+def cmd_new(args):
+    if '--' not in args:
+        sys.exit('lane new: give the command after `--`')
+    split = args.index('--')
+    head, command = args[:split], args[split + 1:]
+    if not command:
+        sys.exit('lane new: empty command')
+    workspace = option(head, '--ws', '')
+    title = option(head, '--title', '')
+    cwd = option(head, '--cwd', str(Path.home()))
+    icon = option(head, '--icon', '')
+    color = option(head, '--color', '')
+    name = lane_id(head[0] if head else '')
+    if workspace and not IDENT.match(workspace):
+        sys.exit('lane new: invalid workspace id')
+    if not Path(cwd).is_dir():
+        sys.exit(f'lane new: no such directory: {cwd}')
+    if alive(name) or name in sessions():
+        sys.exit(f'lane new: {name} already exists (never replaced implicitly)')
+    for directory in (SOCKETS, META, STATE):
+        directory.mkdir(parents=True, exist_ok=True)
+    meta = {'id': name, 'ws': workspace, 'title': title or name, 'cwd': cwd, 'icon': icon, 'color': color,
+            'command': command, 'holder': 'zmx', 'zmx_version': VERSION, 'created_at': time.time()}
+    tmp = META / f'.{name}.json.tmp'
+    tmp.write_text(json.dumps(meta, ensure_ascii=False) + '\n')
+    tmp.replace(META / f'{name}.json')
+    labels = f'ws={workspace or "-"} holder=zmx-{VERSION}'
+    # zmx creates a session only through `attach`; do it on a throwaway pty and let go once it is listed.
+    # The lane's root process is lane-run: a defined, minimal environment; it never exits.
+    argv = [str(ZMX), 'attach', '--labels', labels, name, str(ROOT / 'bin/lane-run'), name, cwd, '--'] + command
+    pid, master = pty.fork()
+    if pid == 0:
+        os.chdir(cwd)
+        os.execve(argv[0], argv, zmx_env({'TERM': 'xterm-256color'}))
+    deadline = time.time() + 10
+    while time.time() < deadline and not alive(name):
+        if select.select([master], [], [], 0.1)[0]:  # never block: a quiet client must not hang creation
+            try:
+                os.read(master, 65536)
+            except OSError:
+                break
+    time.sleep(0.3)
+    os.kill(pid, 15)
+    os.close(master)
+    os.waitpid(pid, 0)
+    if not alive(name) or name not in sessions(expect=name):
+        sys.exit(f'lane new: {name} did not start')
+    print(name)
+
+
+VIEWER_TERM = 'xterm-lanesview'   # TERM of host lanes-view tmux clients (holders/tmux.sh), seen as #{client_termname}
+
+
+def registry_entry(lane):
+    try:
+        data = json.loads((ROOT / 'registry.json').read_text())
+        lanes = data['lanes']
+    except (OSError, ValueError, KeyError):
+        sys.exit('lane open: no registry yet (the host runs `lanes sync` every 2 minutes)')
+    if int(data.get('version', 1)) > 1:
+        sys.exit('lane open: the registry is newer than this `lane` — on the host run: lanes install-container <container>')
+    if lane not in lanes:
+        sys.exit(f'lane open: unknown lane {lane!r} — regenerate with `lanes cursor-sync` on the host')
+    return lanes[lane]
+
+
+def tmux_cmd(socket, *args):
+    env = {k: v for k, v in os.environ.items() if k != 'TMUX'}
+    return subprocess.run(['tmux', '-L', socket, *args], capture_output=True, text=True, timeout=15, env=env)
+
+
+def cmd_open(args):
+    if not args or not re.match(r'^[A-Za-z0-9][A-Za-z0-9_.-]*$', args[0]):
+        sys.exit('usage: lane open <lane-id>')
+    entry = registry_entry(args[0])
+    if os.environ.get('TMUX') and '--force' not in args:
+        sys.exit(f"lane open: already inside tmux — refusing to nest. The lane is: {json.dumps(entry.get('tmux') or entry.get('zmx'))}")
+    env = {k: v for k, v in os.environ.items() if k not in ('TMUX', 'TMUX_PANE')}
+    if entry.get('holder') == 'zmx':
+        name = entry['zmx']['name']
+        if alive(name):
+            os.execve(str(ZMX), [str(ZMX), 'attach', name, '/bin/false'], zmx_env())
+    else:
+        socket, session = entry['tmux']['socket'], entry['tmux']['session']
+        if tmux_cmd(socket, 'has-session', '-t', f'={session}').returncode == 0:
+            clients = tmux_cmd(socket, 'list-clients', '-t', f'={session}', '-F', '#{client_termname}').stdout.split()
+            argv = ['tmux', '-L', socket, 'attach-session']
+            if VIEWER_TERM in clients:
+                argv += ['-f', 'ignore-size']   # the lanes view is showing this lane: never resize it from here
+            os.execvpe('tmux', argv + ['-t', f'={session}'], env)
+    # The lane does not exist: run the recipe the repository recorded for it (it creates AND attaches).
+    recipe = entry.get('create')
+    folder = entry.get('folder') or str(Path.home())
+    if not recipe:
+        sys.exit(f"lane open: {entry.get('name')} is not running and has no create recipe")
+    recipe = recipe.replace('${workspaceFolder}', folder).replace('[workspaceFolder]', folder)
+    print(f"[lane] {entry.get('name')} is not running — creating it with its recorded recipe…", flush=True)
+    try:
+        os.chdir(folder)
+    except OSError:
+        pass
+    os.execvpe('bash', ['bash', '-lc', recipe], env)
+
+
+def cmd_attach(args):
+    name = lane_id(args[0] if args else '')
+    if not alive(name):
+        sys.exit(f'lane attach: {name} is not running (never created implicitly)')
+    # Clean environment on purpose: with ZMX_SESSION set, zmx would SWITCH the calling session instead of attaching.
+    os.execve(str(ZMX), [str(ZMX), 'attach', name, '/bin/false'], zmx_env())
+
+
+def cmd_send(args):
+    name = lane_id(args[0] if args else '')
+    result = zmx('send', name, ' '.join(args[1:]))
+    sys.stderr.write(result.stderr)
+    sys.exit(result.returncode)
+
+
+def cmd_capture(args):
+    lines = int(option(args, '--lines', '0') or 0)
+    flags = ['--vt'] if '--vt' in args else []
+    name = lane_id(next((a for a in args if not a.startswith('--')), ''))
+    text = zmx('history', name, *flags).stdout
+    if lines:
+        text = '\n'.join(text.splitlines()[-lines:]) + '\n'
+    sys.stdout.write(text)
+
+
+def describe():
+    rows = []
+    for name, fields in sorted(sessions().items()):
+        meta = {}
+        try:
+            meta = json.loads((META / f'{name}.json').read_text())
+        except (OSError, ValueError):
+            pass
+        state = {}
+        try:
+            state = json.loads((STATE / f'{name}.json').read_text())
+        except (OSError, ValueError):
+            pass
+        rows.append({'id': name, 'holder': 'zmx', 'pid': int(fields.get('pid', 0)), 'clients': int(fields.get('clients', 0)),
+                     'ws': meta.get('ws', ''), 'title': meta.get('title', name), 'cwd': meta.get('cwd', ''),
+                     'icon': meta.get('icon', ''), 'color': meta.get('color', ''), 'agent': state})
+    return rows
+
+
+def cmd_ls(args):
+    rows = describe()
+    if '--json' in args:
+        print(json.dumps(rows, ensure_ascii=False, indent=1))
+        return
+    for row in rows:
+        agent = row['agent'].get('phase', '?')
+        print(f"{row['id']:<40} {row['ws']:<18} clients={row['clients']} {agent:<8} {row['title']}")
+
+
+def cmd_status(args):
+    name = lane_id(args[0] if args else '')
+    row = next((r for r in describe() if r['id'] == name), None)
+    print(json.dumps(row or {'id': name, 'running': False}, ensure_ascii=False, indent=1))
+    sys.exit(0 if row else 1)
+
+
+def cmd_kill(args):
+    name = lane_id(args[0] if args else '')
+    result = zmx('kill', name)
+    for path in (META / f'{name}.json', STATE / f'{name}.json'):
+        try:
+            path.unlink()
+        except OSError:
+            pass
+    sys.stderr.write(result.stderr)
+    sys.exit(result.returncode)
+
+
+COMMANDS = {'new': cmd_new, 'open': cmd_open, 'attach': cmd_attach, 'send': cmd_send, 'capture': cmd_capture, 'ls': cmd_ls,
+            'status': cmd_status, 'kill': cmd_kill}
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2 or sys.argv[1] not in COMMANDS:
+        sys.exit(__doc__)
+    COMMANDS[sys.argv[1]](sys.argv[2:])

package/payload/lanes/container/lane-run

@@ -0,0 +1,34 @@
+#!/bin/sh
+# lane-run — root process of every zmx-held lane. It NEVER exits on its own (a zmx session ends when its
+# root command ends): it runs the agent command, records how it ended, then offers a login shell in the
+# same directory, then loops back to the shell forever. "Lanes never die on agent exit."
+# usage: lane-run <lane-id> <cwd> -- <command...>
+set -u
+id=${1:?lane id}; cwd=${2:?cwd}; shift 2
+[ "${1:-}" = "--" ] && shift
+root=${LANE_ROOT:-/home/coder/.lz}
+mkdir -p "$root/state"
+
+record() {  # phase, exit code
+    printf '{"phase": "%s", "exit": %s, "at": %s, "pid": %s}\n' "$1" "${2:-null}" "$(date +%s)" "$$" > "$root/state/.$id.json.tmp" \
+        && mv "$root/state/.$id.json.tmp" "$root/state/$id.json"
+}
+
+# A defined, minimal environment: nothing from whoever created the lane leaks into the agent.
+# LANE_ID gives exact agent -> lane attribution (readable from /proc/<pid>/environ).
+cd "$cwd" 2>/dev/null || cd "$HOME"
+export LANE_ID="$id" TERM=xterm-256color COLORTERM=truecolor LANG=C.UTF-8 FORCE_COLOR=3 CLICOLOR=1 FORCE_HYPERLINK=1
+unset NO_COLOR NODE_DISABLE_COLORS ZMX_SESSION TMUX ZELLIJ ZELLIJ_SESSION_NAME ZELLIJ_PANE_ID XDG_CACHE_HOME
+
+trap '' HUP   # a vanishing client must never take the lane down
+record agent null
+# Through a login shell so PATH and tool shims match an interactive lane.
+bash -lc 'exec "$@"' lane-agent "$@"
+code=$?
+while :; do
+    record shell "$code"
+    printf '\n\033[2m[lane %s] command ended (exit %s) — login shell in %s. The lane stays.\033[0m\n' "$id" "$code" "$cwd"
+    bash -l
+    code=$?
+    sleep 1
+done

package/payload/lanes/docs/ARCHITECTURE.md

@@ -0,0 +1,93 @@
+# How the setup fits together
+
+Lanes has three parts: a Linux workspace host, long-running terminal sessions inside its containers, and
+views on desktop or phone. The host owns views and derived registries. The container owns each agent's
+terminal. Installing or closing a view does not end a lane.
+
+## Source of truth and sync
+
+1. The deployment's `catalog.json` orders workspaces and selects their manifests.
+2. Each manifest identifies container names and repository `.vscode/terminals.json` paths.
+3. `lanes sync` reads those files through the container's mounted home and emits the host registry,
+   exact socket/session resolve files, and the container's `.lz/registry.json` projection.
+4. The status daemon observes tmux sessions and publishes status/health snapshots. Failed or timed-out
+   probes mean unknown; they do not prove a missing session. A bad terminal registry retains the last good board.
+
+`lanes cursor-sync` is a separate, explicit writer. Its default is a diff; `--write` takes backups and changes
+editor commands to `lane open <id>`. The original create recipe and exact tmux binding remain in the registry's
+`lanes` block. Automatic sync never commits or pushes those edits. `cursor-commit --push` is an opt-in workflow.
+
+## Views and panes
+
+`lanes attach DEVICE` creates or reattaches the device's Zellij view. Layouts have one tab per workspace,
+a lane sidebar, and one to three viewports. The mobile layout uses separate picker and full-width view tabs.
+Its hidden viewports do not attach at placeholder dimensions; they wait until a real client displays them.
+
+The tmux holder reaches the container's socket through `/proc/<init-pid>/root`, scrubs the viewer environment,
+and uses `tmux -N` so an attach cannot create a server accidentally. Guarded geometry and client identification
+keep the visible view and editor attachments coordinated. Zmx is a separately pinned alternative holder;
+installing it does not migrate existing tmux lanes.
+
+The sidebar always includes **Unregistered** and **New +**. Discovery observes live sockets in workspace
+containers, including shared and unlisted servers. A session GROUPED onto another live session is that session's
+VIEWER — counted in the viewed lane's `attached`/`viewers`, never listed as a session of its own
+(`statusd.viewer_of`); when the group's named leader is gone its OLDEST surviving member leads for that rule,
+and a DECLARED session is always its own row whatever it is grouped onto. Every other session is associated with
+a board by previous assignment, then by the board its own NAME carries (a Throttle Studio `st_<board>_<slug>`
+lane, a `view-<board>-<ch>` browser attach), then by socket ownership or working-directory roots. Optional
+manifest `discoveryRoots` extends those roots. A discovered assignment remains stable after a directory change;
+a session no single board can claim is listed by EVERY owner of its socket rather than dropped, and ambiguity is
+logged rather than resolved by guess.
+
+Explicit **New +** starts a detached tmux shell inside the workspace container on its dedicated
+`lanes-shells-<workspace>` socket. Reopening only attaches. Explicit **×** closes an unregistered session after
+rechecking its session ID and creation time and refusing registered lanes; affected viewers become empty.
+The tmux close condition is checked inside the server, protecting a replacement created between observation
+and the action. `user-sessions/` stores display metadata; `status.json` and `resolve.dynamic/` are projections.
+Legacy Docker shells imported into `legacy-sessions/` are observed by PID/start identity. Closing rechecks the
+owner, preserves that root identity through the process-family scan, and requires a verified root pidfd before
+signaling the original process family. Failed verification keeps the recovery record. These older connections cannot be recreated; their
+metadata is local recovery state, never a recipe to start replacement jobs. See [state contracts](../../docs/master-datamodel.md).
+
+The `lane` command lives in `/home/coder/.lz/bin`. `open` attaches or creates using its saved recipe;
+`attach` never creates; `send`, `capture`, `ls` and `status` are explicit operations. Only `kill` ends a lane.
+These commands operate inside the container, independently of the Zellij viewer's lifetime.
+
+## Desktop and uploads
+
+The client installer creates an SSH alias and dedicated terminal configuration, using the selected profile's
+host key and the user's SSH key. `lanes-launch` reconnects its view and provides a helper channel for uploads.
+A background helper can serve the same channel when installed; on macOS it runs under the Lanes Helper app's
+identity so folder permissions work.
+
+The sidebar sends an upload request naming paths, workspace and device. The client checks its folder allowlist,
+streams an archive over SSH, and reports original errors and progress. The host extracts data into that
+workspace's `uploads/` folder without overwriting files; an optional paste places the resulting paths in the
+selected lane. Active transfers have an idle timeout, not a short total-duration limit. Credentials, `.git`
+metadata and disallowed folders cannot be uploaded through the helper.
+
+## Web and phone
+
+Tailscale Serve terminates private HTTPS on 8443 and forwards to the dedicated Caddy user service on loopback
+8083. Caddy serves `web/` and forwards native assets, authentication and WebSockets to Zellij on loopback 8082.
+Zellij's existing token/cookie checks remain authoritative; the mobile layer adds no second login system.
+
+The phone shell uses the pinned client's window hooks for workspaces, panes, input and sizing. A visible
+**Type here** field holds the original terminal input. Programmatic input focus is blocked on phones, so a
+swipe, refresh or server message cannot summon the keyboard. Native taps on input fields still work.
+Safe-area insets and the visual viewport handle the Home indicator, rotation and keyboard.
+
+## Installed files and services
+
+`install/services.py` renders the service templates against the actual checkout and installed binary paths.
+It replaces old unit symlinks atomically and creates `~/.local/share/lanes/current` as a discovery shortcut.
+No service requires the checkout to be named `~/lanes`. Re-run the server installer after moving it.
+
+Core units are the status observer and sync, ensure and garbage-collection timers. The web units are opt-in.
+Temporary-file cleanup and process protection have explicit plan/apply or enable steps; installation does not
+arm them. The root host guard is also separate and records rollback values. See [the runbook](RUNBOOK.md)
+and [host protection](HOST-GUARD.md) for those operations.
+
+The package uses Python's standard library and POSIX shell. Host binaries are versioned and checksum-pinned
+in `holders.lock`; Zellij's web assets are served by that binary and integrity-pinned in `web/index.html`.
+Deployment profiles, workspace catalogs and runtime state remain distinct from shared source code.