@vibelord/lanes 1.0.0

package/payload/lanes/holders/tmux.sh

@@ -0,0 +1,111 @@
+#!/bin/sh
+# Attach this terminal to an EXISTING in-container tmux lane, straight over its unix socket.
+# usage: tmux.sh <container> <socket> <session>
+#
+# Guards (all mandatory, see docs/ARCHITECTURE.md):
+#   -N            never start a tmux server (a plain attach on a missing socket would start a phantom one)
+#   env -i        tmux's update-environment must not copy this host's SSH_* / DISPLAY into the lane
+#   init-pid      the socket is reached through /proc/<container-init-pid>/root, verified to be a docker cgroup
+#   pty guard     the lane's client-attached hook detaches any client whose tty NAME equals the lane's
+#                 pane_tty; host and container pty numbers can collide, so re-wrap in a fresh pty on a match
+#   ignore-size   while the old viewers coexist, never resize a live agent's window
+set -u
+state=${LANES_STATE:-$HOME/.local/state/lanes}
+container=${1:-} socket=${2:-} session=${3:-}
+fail() { echo "$2" >&2; exit "$1"; }   # the view shows the last stderr line on its status screen
+case "$container" in ''|-*|*[!A-Za-z0-9_.-]*) fail 64 'invalid container' ;; esac
+case "$socket" in ''|-*|*[!A-Za-z0-9_.-]*) fail 64 'invalid socket' ;; esac
+# The session gate admits what TMUX itself can hold, not what a lane may be DECLARED with. statusd lists every
+# live session, its name outside the declaration grammar or not (the `<name> (drain)` twins, a hand-made
+# `Planning Notes 2`), and the sidebar offers each as a 👻 row — so a gate copied from
+# `lanes_lib.TMUX_SESSION` refused `invalid session` (64) on exactly those rows and view.sh retried that refusal
+# for ever under a name the lane itself answers to (DEF-891). MEASURED (tmux 3.4): `new-session -s` accepts
+# `(`, `)`, `/`, `,`, `$`, a backtick, a quote and a leading `-`; only `:` and `.` are rewritten to `_`, so
+# such a name simply has no session and fails below with the precise "no such tmux session". The name never
+# reaches a shell: it is one argv element behind `-t "$target"` (an EXACT match, so a leading `-` is inert),
+# and the pty re-wrap below hands it to `script` through the ENVIRONMENT, never inside a quoted command string.
+# Control characters stay refused: no listing round-trips them.
+case "$session" in ''|*[[:cntrl:]]*) fail 64 'invalid session' ;; esac
+# Every target carries the WINDOW suffix `:`. A trailing `;` ends a tmux command in ANY argv element, so a bare
+# `-t "=$session"` on a live session named `foo;` resolved `=foo`: MEASURED (tmux 3.4, scratch server) an
+# `attach-session -t '=foo;'` put the client on `foo` — a lane the operator did not select — while with `foo`
+# gone `has-session -t '=foo;'` failed "can't find session: foo" although `foo;` was listed. With the suffix
+# the same three calls resolve `foo;` (`attach-session -t '=foo;:'` landed on `foo;`, `-f ignore-size` intact).
+# `:` alone is the session's CURRENT window, which is what a plain attach selects anyway (DEF-917).
+target="=$session:"
+
+is_container_pid() {
+    [ "${1:-0}" -gt 0 ] 2>/dev/null && [ -r "/proc/$1/cgroup" ] && grep -q docker "/proc/$1/cgroup" 2>/dev/null
+}
+pid=$(cat "$state/containers/$container.pid" 2>/dev/null || echo 0)
+if ! is_container_pid "$pid"; then
+    pid=$(docker inspect -f '{{.State.Pid}}' "$container" 2>/dev/null || echo 0)
+    is_container_pid "$pid" || fail 69 "container $container is not running"
+fi
+path=/proc/$pid/root/tmp/tmux-${LANES_CONTAINER_UID:-1000}/$socket
+if [ ! -S "$path" ]; then
+    # statusd saw the server PROCESS alive while its socket file is gone = somebody emptied the container's /tmp.
+    # 75 (try again), not 69: the lane exists, so the view keeps its "THE LANE IS STILL RUNNING" headline.
+    if grep -q -x -F "$container/$socket" "$state/flags/sockets-lost" 2>/dev/null; then
+        fail 75 "the lane runs, but its tmux socket file was deleted (emptied /tmp?) — on the server: lanes sockets repair"
+    fi
+    fail 69 "tmux server '$socket' is not running in $container"
+fi
+
+# Viewer marker: a user-level terminfo alias of xterm-256color (install/host-install.sh). tmux 3.4 reads terminfo
+# on the client side and exposes the name as #{client_termname}; `xterm*` keeps tmux's default xterm features.
+# (#{client_cwd} is empty in tmux 3.4, so the working directory cannot serve as the marker.)
+view_term=xterm-256color
+if infocmp xterm-lanesview >/dev/null 2>&1; then view_term=xterm-lanesview; fi
+lanes_tmux() {
+    env -i PATH=/usr/bin:/bin HOME="$HOME" TERM="$view_term" LANG=C.UTF-8 COLORTERM=truecolor \
+        tmux -N -u -2 -T RGB,hyperlinks -S "$path" "$@"
+}
+lanes_tmux has-session -t "$target" 2>/dev/null || fail 66 "lane $socket / $session is not provisioned (no such tmux session)"
+# ... and the session that ANSWERED is the one asked for. `$<n>`, `@<n>` and `%<n>` are tmux OBJECT IDs, and
+# neither the `=` exact-match prefix nor the `:` window suffix stops the id lookup: MEASURED (tmux 3.4, scratch
+# server holding `plain`=$0, `other`=$1 and a session literally NAMED `$0`) `display-message -p -t '=$0:'`
+# answered `plain|$0`, `has-session` and `list-clients` succeeded against `plain`, and a real
+# `attach-session -f ignore-size -t '=$0:'` put the client on `plain` — a lane the operator did not select,
+# whose editor clients the size pass below would then put into ignore-size. The gate above admits such a name
+# on purpose (statusd lists every live session and the sidebar opens it, DEF-891), so the ANSWER is what is
+# checked, exactly as the Host's channel preflight checks it (`studio_host::channel`, `LaneMissing`). DEF-968.
+answering=$(lanes_tmux display-message -p -t "$target" '#{session_name}' 2>/dev/null || echo '')
+[ "$answering" = "$session" ] || fail 66 "lane $socket / $session is not provisioned (that target resolves the session '$answering')"
+
+flags=
+if [ -e "$state/flags/coexist" ] && [ ! -e "$state/flags/sized.${LANES_WS:-}" ]; then flags=ignore-size; fi
+if [ -e "$state/flags/readonly" ]; then flags=${flags:+$flags,}read-only; fi
+
+my_tty=$(tty 2>/dev/null || echo none)
+pane_tty=$(lanes_tmux display-message -p -t "$target" '#{pane_tty}' 2>/dev/null || echo unknown)
+if [ "$my_tty" = "$pane_tty" ] && [ -z "${LANES_REWRAPPED:-}" ]; then
+    # Same pty NAME in two mount namespaces: move this viewer onto a fresh pty. The three arguments travel in
+    # the ENVIRONMENT and the command string is single-quoted, so the inner `sh -c` expands them as values: a
+    # session name carrying a `'` (which tmux accepts) used to close the quoting and run the rest as a command.
+    LANES_REWRAPPED=1 LANES_STATE="$state" LANES_WS="${LANES_WS:-}" \
+    LANES_SELF="$0" LANES_ARG_CONTAINER="$container" LANES_ARG_SOCKET="$socket" LANES_ARG_SESSION="$session" \
+        exec script -qfc 'exec "$LANES_SELF" "$LANES_ARG_CONTAINER" "$LANES_ARG_SOCKET" "$LANES_ARG_SESSION"' /dev/null
+fi
+
+# The lanes view owns the size of the lane it shows: put editor terminals (Cursor / VS Code, ad-hoc attaches)
+# already on this lane into ignore-size now. statusd reconciles continuously and gives them the size back once
+# no viewer shows the lane.
+if [ -z "$flags" ] && [ "$view_term" = xterm-lanesview ]; then
+    lanes_tmux list-clients -t "$target" -F '#{client_name}|#{client_termname}|#{client_flags}' 2>/dev/null |
+    while IFS='|' read -r c_name c_term c_flags; do
+        [ "$c_term" = xterm-lanesview ] && continue
+        case ",$c_flags," in *,ignore-size,*) continue ;; esac
+        [ "$c_name" = "$my_tty" ] && continue
+        lanes_tmux refresh-client -t "$c_name" -f ignore-size 2>/dev/null || :
+    done
+fi
+
+# exec: the supervisor's child pid must BE the tmux client, so a lane switch (SIGTERM) detaches it cleanly
+# instead of orphaning a client on this pty.
+if [ -n "$flags" ]; then
+    exec env -i PATH=/usr/bin:/bin HOME="$HOME" TERM="$view_term" LANG=C.UTF-8 COLORTERM=truecolor \
+        tmux -N -u -2 -T RGB,hyperlinks -S "$path" attach-session -f "$flags" -t "$target"
+fi
+exec env -i PATH=/usr/bin:/bin HOME="$HOME" TERM="$view_term" LANG=C.UTF-8 COLORTERM=truecolor \
+    tmux -N -u -2 -T RGB,hyperlinks -S "$path" attach-session -t "$target"

package/payload/lanes/holders/zmx.sh

@@ -0,0 +1,22 @@
+#!/bin/sh
+# Attach this terminal to an EXISTING zmx-held lane inside a container, straight over its unix socket.
+# usage: zmx.sh <container> <lane-name> <zmx-version>
+#
+#   * zmx has no attach-only flag: a missing session would be CREATED (here, on the host). Guard twice:
+#     the socket must exist, and the create-command is /bin/false so an accidental creation dies at once.
+#   * zmx has no IPC version handshake: run the very binary the lane's daemon runs (from the home volume).
+#   * sun_path is 108 bytes and the volume path alone is 74: reach the sockets through the short symlink
+#     ~/.lz/<container> -> <home volume>/.lz  (zmx does not canonicalise paths).
+#   * ZMX_NO_DETACH_KEY: Ctrl-\ belongs to the agent; leaving a lane is the view's job.
+set -u
+container=${1:-} name=${2:-} version=${3:-}
+fail() { echo "$2" >&2; exit "$1"; }
+case "$container" in ''|-*|*[!A-Za-z0-9_.-]*) fail 64 'invalid container' ;; esac
+case "$name" in ''|-*|*[!A-Za-z0-9_.-]*) fail 64 'invalid lane name' ;; esac
+case "$version" in ''|*[!0-9.]*) fail 64 'invalid zmx version' ;; esac
+link=$HOME/.lz/$container
+zmx=$link/bin/zmx-$version
+[ -x "$zmx" ] || fail 69 "zmx $version is not installed for $container"
+[ -S "$link/s/$name" ] || fail 66 "lane $name is not running"
+exec env -i PATH=/usr/bin:/bin HOME="$HOME" TERM=xterm-256color LANG=C.UTF-8 \
+    ZMX_DIR="$link/s" ZMX_NO_DETACH_KEY=1 "$zmx" attach "$name" /bin/false

package/payload/lanes/holders.lock

@@ -0,0 +1,5 @@
+# Pinned binaries. install/host-install.sh refuses anything whose sha256 differs.
+# name  version  sha256(tarball)  url
+# zellij 0.45.1: tarball digest matches GitHub's asset digest; inner binary d006c521…19dd matches the published .sha256sum.
+zellij 0.45.1 40bcc2e03f5d5ae8e054e39f676081fe12ab70871506996ba595834c3718eefc https://github.com/zellij-org/zellij/releases/download/v0.45.1/zellij-x86_64-unknown-linux-musl.tar.gz
+zmx 0.8.1 dfd75720b942466f28870731cc86dbc07afa72fb8f3bd5eeb4ff707e4eecebe8 https://github.com/neurosnap/zmx/releases/download/v0.8.1/zmx-0.8.1-linux-x86_64.tar.gz

package/payload/lanes/install/enable-phone.sh

@@ -0,0 +1,43 @@
+#!/bin/sh
+# Key-authenticated client entry point and local server setup. Tokens stay in the caller's terminal.
+set -eu
+repo=$(cd "$(dirname "$0")/.." && pwd)
+host= device=phone local=0 named=0
+while [ "$#" -gt 0 ]; do
+    case "$1" in
+        --host) host=${2:?--host SSH_ALIAS}; shift ;;
+        --local) local=1 ;;
+        -h|--help)
+            echo 'usage: enable-phone.sh [--host SSH_ALIAS | --local] [device]'
+            echo 'Client: --host lanes uses the SSH key from ./install.sh. Server: --local.'
+            exit 0 ;;
+        -*) echo "unknown option: $1" >&2; exit 2 ;;
+        *) [ "$named" = 0 ] || { echo 'only one device name is allowed' >&2; exit 2; }; device=$1; named=1 ;;
+    esac
+    shift
+done
+case "$device" in ''|-*|*[!A-Za-z0-9_.-]*) echo 'invalid device name' >&2; exit 2 ;; esac
+case "$host" in -*|*[!A-Za-z0-9_.@:-]*) echo 'invalid SSH host' >&2; exit 2 ;; esac
+[ "$local" = 0 ] || [ -z "$host" ] || { echo '--local and --host are mutually exclusive' >&2; exit 2; }
+if [ "$local" = 0 ] && [ "$(uname -s)" = Darwin ] && [ -z "$host" ]; then host=lanes; fi
+[ -t 0 ] && [ -t 1 ] || { echo 'Run enable-phone.sh in your own terminal; it displays a private login token.' >&2; exit 64; }
+if [ -n "$host" ]; then
+    exec ssh -t -o BatchMode=yes -o PreferredAuthentications=publickey -o ForwardAgent=no "$host" \
+        "exec sh \"\$HOME/.local/share/lanes/current/install/enable-phone.sh\" --local '$device'"
+fi
+command -v tailscale >/dev/null 2>&1 || { echo 'Install and connect Tailscale on the server first.' >&2; exit 1; }
+sh "$repo/install/enable-web.sh" "$device"
+if ! tailscale serve --bg --https=8443 http://127.0.0.1:8083; then
+    echo 'The server admin must allow this account to manage Tailscale Serve:' >&2
+    printf '  sudo tailscale set --operator=%s\n' "$(id -un)" >&2
+    echo 'Then run this command again. See docs/INSTALL.md for HTTPS setup.' >&2
+    exit 1
+fi
+dns=$(tailscale status --json | python3 -c 'import json,sys; print(json.load(sys.stdin)["Self"]["DNSName"].rstrip("."))')
+[ -n "$dns" ] || { echo 'This node needs Tailscale MagicDNS and HTTPS enabled.' >&2; exit 1; }
+printf '\nOn your phone, connect Tailscale and open:\n\n  https://%s:8443/%s\n\n' "$dns" "$device"
+printf 'The last line is NAME: TOKEN. Paste only TOKEN into the sign-in screen.\n'
+printf 'In Safari, Share > Add to Home Screen installs the app.\n\n'
+# Zellij 0.45.1 requires --create-token by itself; --token-name cannot accompany it.
+exec "${LANES_SHARE:-$HOME/.local/share/lanes}/bin/zellij-0.45.1" \
+    --config-dir "$repo/zellij" --config "$repo/zellij/config.kdl" web --create-token

package/payload/lanes/install/enable-web.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+# Enable loopback web services as the installed workspace user. Does not print a token.
+set -eu
+repo=$(cd "$(dirname "$0")/.." && pwd)
+device=${1:-phone}
+[ "$#" -le 1 ] || { echo 'usage: enable-web.sh [device]' >&2; exit 2; }
+case "$device" in ''|-*|*[!A-Za-z0-9_.-]*) echo 'invalid device name' >&2; exit 2 ;; esac
+command -v caddy >/dev/null 2>&1 || { echo 'Install Caddy first (see docs/INSTALL.md).' >&2; exit 1; }
+export XDG_RUNTIME_DIR=${XDG_RUNTIME_DIR:-/run/user/$(id -u)}
+"$repo/bin/lanes" prepare "$device" --mobile
+python3 "$repo/install/services.py"
+systemctl --user daemon-reload
+systemctl --user enable --now lanes-web.service lanes-mobile.service
+systemctl --user is-active --quiet lanes-web.service lanes-mobile.service
+printf '\nPhone frontend: 127.0.0.1:8083; Zellij: 127.0.0.1:8082 (loopback only).\n'
+printf 'For private HTTPS and a login token, run in your terminal:\n  sh "%s/install/enable-phone.sh" --local %s\n' "$repo" "$device"

package/payload/lanes/install/host-install.sh

@@ -0,0 +1,72 @@
+#!/bin/sh
+# Linux server install/update. Called by ./install.sh --server. Never runs as root.
+set -eu
+repo=$(cd "$(dirname "$0")/.." && pwd)
+start=1 check=0
+for argument in "$@"; do
+    case "$argument" in
+        --no-start) start=0 ;;
+        --check) check=1 ;;
+        -h|--help)
+            echo 'usage: ./install.sh --server [--check | --no-start]'
+            echo 'Installs pinned binaries and user services. --check changes nothing; --no-start only installs files.'
+            exit 0 ;;
+        *) echo "unknown server option: $argument" >&2; exit 2 ;;
+    esac
+done
+[ "$(uname -s)/$(uname -m)" = Linux/x86_64 ] || {
+    echo 'The pinned server binaries require Linux x86_64. macOS/Linux desktops use ./install.sh --site FILE.' >&2; exit 1;
+}
+[ "$(id -u)" != 0 ] || { echo 'Run as the workspace user, not root.' >&2; exit 1; }
+for command in python3 curl tar sha256sum infocmp tic install systemctl docker tmux; do
+    command -v "$command" >/dev/null 2>&1 || { echo "Missing prerequisite: $command (see docs/INSTALL.md)" >&2; exit 1; }
+done
+python3 -c 'import sys; sys.exit(0 if sys.version_info >= (3, 9) else "Python 3.9+ is required")'
+export XDG_RUNTIME_DIR=${XDG_RUNTIME_DIR:-/run/user/$(id -u)}
+if [ "$start" = 1 ]; then
+    systemctl --user show-environment >/dev/null
+    python3 -c 'import subprocess; subprocess.run(["docker", "info", "--format", "{{.ServerVersion}}"], check=True, timeout=15)'
+fi
+if [ "$check" = 1 ]; then
+    echo 'Server prerequisites: ready'
+    exit 0
+fi
+share=${LANES_SHARE:-$HOME/.local/share/lanes}
+state=${LANES_STATE:-$HOME/.local/state/lanes}
+mkdir -p "$share/bin" "$share/dl" "$state/flags"
+grep -v '^#' "$repo/holders.lock" | while read -r name version sha url; do
+    [ -n "$name" ] || continue
+    target=$share/bin/$name-$version
+    if [ -x "$target" ]; then echo "ok  $name $version"; continue; fi
+    archive=$share/dl/$(basename "$url")
+    curl -fsSL --retry 3 -o "$archive" "$url"
+    actual=$(sha256sum "$archive" | cut -d' ' -f1)
+    [ "$actual" = "$sha" ] || { echo "sha256 mismatch for $name" >&2; exit 1; }
+    temporary=$(mktemp -d)
+    trap 'rm -rf "$temporary"' EXIT HUP INT TERM
+    tar -xzf "$archive" -C "$temporary"
+    install -m 0755 "$temporary/$name" "$target"
+    rm -rf "$temporary"
+    trap - EXIT HUP INT TERM
+    echo "installed $target"
+done
+if ! infocmp xterm-lanesview >/dev/null 2>&1; then
+    infocmp -x xterm-256color | sed '1,3s/^xterm-256color|/xterm-lanesview|/' > "$share/dl/xterm-lanesview.ti"
+    tic -x -o "$HOME/.terminfo" "$share/dl/xterm-lanesview.ti"
+fi
+[ -e "$state/registry.json" ] || touch "$state/flags/coexist"
+python3 "$repo/install/services.py"
+catalog=$HOME/.config/lanes/workspaces/catalog.json
+if [ ! -e "$catalog" ] && [ ! -d "$repo/workspaces" ] && [ -z "${LANES_WORKSPACES:-}" ]; then
+    mkdir -p "$(dirname "$catalog")"
+    printf '{"version":1,"workspaces":[]}\n' > "$catalog"
+fi
+if [ "$start" = 1 ]; then
+    systemctl --user daemon-reload
+    "$repo/bin/lanes" sync
+    systemctl --user enable --now lanes-statusd.service lanes-sync.timer lanes-ensure.timer lanes-gc.timer
+fi
+printf '\nServer installed from %s\n' "$repo"
+echo 'Configure boards in ~/.config/lanes/workspaces/; see workspaces.example/README.md.'
+echo 'Next: lanes install-container CONTAINER; lanes sync; lanes doctor'
+echo 'Web access and host cleanup/guard timers remain opt-in; see docs/INSTALL.md.'

package/payload/lanes/install/services.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Register this checkout's user services without starting or restarting them."""
+import os
+import shutil
+from pathlib import Path
+import tempfile
+
+
+def unit_value(value, command=False):
+    value = str(value)
+    if any(c in value for c in '\r\n\0'):
+        raise ValueError('installation paths must not contain control characters')
+    value = value.replace('\\', '\\\\').replace('"', '\\"').replace('%', '%%')
+    return value.replace('$', '$$') if command else value
+
+
+def register(repo, home, share, state, workspaces=None):
+    repo, home, share, state = (Path(p).resolve() for p in (repo, home, share, state))
+    current = home / '.local/share/lanes/current'
+    links = ((current, repo), (home / '.local/bin/lanes', repo / 'bin/lanes'))
+    for link, _ in links:
+        if link.exists() and not link.is_symlink():
+            raise ValueError(f'{link} already exists and is not a symlink')
+    settings = [('LANES_REPO', repo), ('LANES_SHARE', share), ('LANES_STATE', state)]
+    if workspaces:
+        settings.append(('LANES_WORKSPACES', Path(workspaces).resolve()))
+    environment = ''.join(f'Environment="{name}={unit_value(value)}"\n' for name, value in settings)
+    rendered = {}
+    for source in sorted((repo / 'systemd').iterdir()):
+        if source.name.startswith('.') or source.suffix not in ('.service', '.timer', '.slice') or not source.is_file():
+            continue
+        content = source.read_text().replace('@REPO@', unit_value(repo, command=True))
+        content = content.replace('@SHARE@', unit_value(share, command=True))
+        content = content.replace('@CADDY@', unit_value(shutil.which('caddy') or '/usr/bin/caddy', command=True))
+        if '[Service]\n' in content:
+            content = content.replace('[Service]\n', '[Service]\n' + environment, 1)
+        rendered[source.name] = '# Generated by lanes/install/services.py; re-run the server installer to update.\n' + content
+    units = home / '.config/systemd/user'
+    units.mkdir(parents=True, exist_ok=True)
+    for name, content in rendered.items():
+        fd, temporary = tempfile.mkstemp(prefix='.lanes-', dir=units)
+        try:
+            with os.fdopen(fd, 'w') as handle:
+                handle.write(content)
+            os.chmod(temporary, 0o644)
+            os.replace(temporary, units / name)  # replace old symlinks, never write through them
+        finally:
+            if os.path.exists(temporary):
+                os.unlink(temporary)
+    for link, target in links:
+        link.parent.mkdir(parents=True, exist_ok=True)
+        if link.is_symlink():
+            link.unlink()
+        link.symlink_to(target)
+
+
+if __name__ == '__main__':
+    register(Path(__file__).resolve().parents[1], Path.home(),
+             os.environ.get('LANES_SHARE', Path.home() / '.local/share/lanes'),
+             os.environ.get('LANES_STATE', Path.home() / '.local/state/lanes'),
+             os.environ.get('LANES_WORKSPACES'))