@vibelord/lanes 1.0.0

package/payload/lanes/install.sh

@@ -0,0 +1,603 @@
+#!/bin/sh
+# lanes — client installer for macOS and Linux. POSIX sh, no dependencies beyond OpenSSH.
+# Idempotent and additive: it adds new names only, and `--uninstall` removes exactly what it added.
+#
+#   ./install.sh                 install or update the client on this machine
+#   ./install.sh --server        install or update the Linux workspace server
+#   ./install.sh --check         verify terminal, SSH path, key and server (changes nothing)
+#   ./install.sh --uninstall     remove what the installer added (your SSH key and ~/Lanes Uploads are kept)
+#
+# Options
+#   --device NAME     name of this machine's view session (default: <user>-<hostname>; kept on re-install)
+#   --key PATH        SSH private key to use (default: the one already configured, else ~/.ssh/id_ed25519,
+#                     else a new dedicated key ~/.ssh/lanes_ed25519)
+#   --site FILE       server profile (default: site/site.conf, else the remembered client profile)
+#   --link            symlink the client into this checkout instead of copying it (for working on the harness)
+#   --coder-launch    also provide the command name `coder-launch` (an existing one is kept as coder-launch-legacy)
+#   --no-desktop      skip desktop integration (Lanes.app / .desktop entry / Hyprland key binding)
+#   --no-uploads      skip the uploads watch folder and the upload helper service
+#   --yes             never prompt (a new key is then created WITHOUT a passphrase)
+#
+# Exit status: 0 ready to use · 3 installed, but this machine's key is not authorized on the server yet ·
+#              4 installed, but the server is not reachable (Tailscale?) or did not answer in time (busy?) · 1 error
+set -eu
+here=$(cd "$(dirname "$0")" && pwd)
+if [ "${1:-}" = --server ]; then
+    shift
+    exec sh "$here/install/host-install.sh" "$@"
+fi
+os=$(uname -s)
+bin=$HOME/.local/bin
+config=${XDG_CONFIG_HOME:-$HOME/.config}/lanes
+share=${XDG_DATA_HOME:-$HOME/.local/share}/lanes
+state=${XDG_STATE_HOME:-$HOME/.local/state}/lanes-client     # helper.alive + logs of a client with the service side
+stamp=$(date -u +%Y%m%dT%H%M%SZ)
+label=ai.beyondwork.lanes-upload
+helper_label=ai.beyondwork.lanes-helper
+
+mode=install device= key= site_file=$here/site/site.conf link=0 coder_launch=0 desktop=1 uploads=1 assume_yes=0
+[ -r "$site_file" ] || site_file=$config/client-site.conf
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --check) mode=check ;;
+        --uninstall) mode=uninstall ;;
+        --device) device=${2:?--device NAME}; shift ;;
+        --key) key=${2:?--key PATH}; shift ;;
+        --site) site_file=${2:?--site FILE}; shift ;;
+        --link) link=1 ;;
+        --coder-launch) coder_launch=1 ;;
+        --no-desktop) desktop=0 ;;
+        --no-uploads) uploads=0 ;;
+        --yes|-y) assume_yes=1 ;;
+        -h|--help) sed -n '2,22p' "$0"; exit 0 ;;
+        *) echo "install.sh: unknown option $1 (see --help)" >&2; exit 1 ;;
+    esac
+    shift
+done
+
+say()  { printf '  %s\n' "$*"; }
+head_() { printf '\n%s\n' "$*"; }
+warn() { printf '  ! %s\n' "$*" >&2; }
+die()  { printf 'install.sh: %s\n' "$*" >&2; exit 1; }
+tilde() { case "$1" in "$HOME"/*) printf '~/%s' "${1#"$HOME"/}" ;; *) printf '%s' "$1" ;; esac; }
+
+# ---- site -----------------------------------------------------------------------------------------------------------
+site_value() { sed -n "s/^$1=//p" "$site_file" 2>/dev/null | head -n 1; }
+load_site() {
+    [ -r "$site_file" ] || die "choose a server: --site /path/to/site.conf (see site/README.md; team profile: --site site/beyondwork/site.conf)"
+    case "$(site_value LANES_SITE_SCHEMA)" in ''|1) ;; *) die "site file $site_file has a newer schema than this installer: update the checkout" ;; esac
+    server_host=$(site_value LANES_SERVER_HOST); server_user=$(site_value LANES_SERVER_USER)
+    server_alias=$(site_value LANES_SERVER_ALIAS); server_name=$(site_value LANES_SERVER_NAME)
+    server_public=$(site_value LANES_SERVER_PUBLIC)
+    [ -n "$server_public" ] || server_public=$(sed -n 's/^LANES_SERVER_PUBLIC=//p' "$config/site.cache" 2>/dev/null | head -n 1)
+    for value in "$server_host" "$server_user" "$server_alias"; do
+        case "$value" in ''|*[!A-Za-z0-9_.:-]*) die "site file $site_file: LANES_SERVER_HOST/USER/ALIAS missing or malformed" ;; esac
+    done
+    case "$server_public" in *[!A-Za-z0-9_.:-]*) server_public= ;; esac
+    pinned=$(dirname "$site_file")/known_hosts
+    [ "$site_file" != "$config/client-site.conf" ] || pinned=$config/client-known-hosts
+}
+
+# ---- identity -------------------------------------------------------------------------------------------------------
+default_device() {
+    name="$(id -un)-$(hostname -s 2>/dev/null || hostname 2>/dev/null || cat /etc/hostname)"
+    printf '%s' "$name" | tr 'A-Z' 'a-z' | tr -c 'a-z0-9_.-' '-' | sed 's/--*/-/g; s/^-*//; s/-*$//' | cut -c1-32
+}
+choose_device() {
+    if [ -z "$device" ] && [ -r "$config/device" ]; then device=$(head -n 1 "$config/device"); fi
+    [ -n "$device" ] || device=$(default_device)
+    device=$(printf '%s' "$device" | tr 'A-Z' 'a-z' | tr -c 'a-z0-9_.-' '-' | sed 's/--*/-/g; s/^-*//; s/-*$//' | cut -c1-32)
+    [ -n "$device" ] || die 'could not derive a device name; pass --device NAME'
+}
+choose_key() {
+    if [ -z "$key" ] && [ -r "$HOME/.ssh/config.d/lanes.conf" ]; then
+        key=$(awk '$1 == "IdentityFile" { print $2; exit }' "$HOME/.ssh/config.d/lanes.conf")
+    fi
+    case "$key" in "~/"*) key=$HOME/${key#"~/"} ;; esac
+    if [ -z "$key" ]; then
+        if [ -r "$HOME/.ssh/id_ed25519" ]; then key=$HOME/.ssh/id_ed25519; else key=$HOME/.ssh/lanes_ed25519; fi
+    fi
+}
+ensure_key() {
+    mkdir -p "$HOME/.ssh"; chmod 700 "$HOME/.ssh"
+    if [ ! -r "$key" ]; then
+        [ "$key" = "$HOME/.ssh/lanes_ed25519" ] || die "SSH key not found: $key"
+        say "creating a dedicated SSH key: $(tilde "$key")"
+        if [ "$assume_yes" = 1 ] || [ ! -t 0 ]; then
+            ssh-keygen -q -t ed25519 -N '' -C "lanes:$device" -f "$key"
+        else
+            say '(choose a passphrase, or press Enter twice for none — it is asked once and then kept in your agent/keychain)'
+            ssh-keygen -q -t ed25519 -C "lanes:$device" -f "$key"
+        fi
+    fi
+    [ -r "$key.pub" ] || ssh-keygen -y -f "$key" > "$key.pub"
+}
+
+# ---- ssh ------------------------------------------------------------------------------------------------------------
+# Does THIS machine's ssh know an option? (-F /dev/null: judge the binary, not the user's config.)
+ssh_knows() { ssh -F /dev/null -o "$1" -G localhost >/dev/null 2>&1; }
+optional() {   # optional <MARKER> <yes|no>: keep or drop the template lines carrying #@MARKER@
+    if [ "$2" = yes ]; then sed "s/^#@$1@ \{0,1\}//"; else grep -v "^#@$1@" || :; fi
+}
+render_stanza() {   # -> stdout
+    identity=$(tilde "$key")
+    public=no; [ -n "$server_public" ] && public=yes
+    obscure=no; ssh_knows ObscureKeystrokeTiming=no && obscure=yes
+    keychain=no; ssh_knows UseKeychain=yes && keychain=yes
+    sed -e "s|@HOST@|$server_host|g" -e "s|@USER@|$server_user|g" -e "s|@ALIAS@|$server_alias|g" \
+        -e "s|@IDENTITY@|$identity|g" -e "s|@PUBLIC_HOST@|$server_public|g" "$src/ssh.stanza.in" |
+        optional PUBLIC "$public" | optional OBSCURE "$obscure" | optional KEYCHAIN "$keychain"
+}
+install_ssh() {
+    mkdir -p "$HOME/.ssh/config.d"; chmod 700 "$HOME/.ssh" "$HOME/.ssh/config.d"
+    # Guard: our file is parsed for EVERY ssh destination. If the configuration parsed before and does not parse
+    # after, put the previous file back — never leave a machine whose ssh is broken for other hosts.
+    parsed_before=no; ssh -G lanes-selftest.invalid >/dev/null 2>&1 && parsed_before=yes
+    stanza=$HOME/.ssh/config.d/lanes.conf
+    rm -f "$stanza.prev"; [ -e "$stanza" ] && cp -p "$stanza" "$stanza.prev"
+    render_stanza > "$stanza.new"
+    chmod 600 "$stanza.new"; mv "$stanza.new" "$stanza"
+    touch "$HOME/.ssh/config"; chmod 600 "$HOME/.ssh/config"
+    # OpenSSH applies the FIRST value it sees and requires Include before any Host block: the line goes on top.
+    if ! grep -q '^Include config.d/lanes.conf' "$HOME/.ssh/config"; then
+        cp -p "$HOME/.ssh/config" "$HOME/.ssh/config.pre-lanes.$stamp"
+        { printf '# lanes workspace server (added %s by the lanes installer)\nInclude config.d/lanes.conf\n\n' "$stamp"
+          cat "$HOME/.ssh/config.pre-lanes.$stamp"; } > "$HOME/.ssh/config.new"
+        chmod 600 "$HOME/.ssh/config.new"; mv "$HOME/.ssh/config.new" "$HOME/.ssh/config"
+        say "~/.ssh/config: added one Include line (backup: config.pre-lanes.$stamp)"
+    fi
+    if ! ssh -G lanes >/dev/null 2>&1 || { [ "$parsed_before" = yes ] && ! ssh -G lanes-selftest.invalid >/dev/null 2>&1; }; then
+        problem=$(ssh -G lanes-selftest.invalid 2>&1 | head -n 2 | tr '\n' ' ')
+        if [ -e "$stanza.prev" ]; then mv "$stanza.prev" "$stanza"; else rm -f "$stanza"; fi
+        die "the generated SSH stanza does not parse on this machine — put the previous one back. ssh said: $problem"
+    fi
+    rm -f "$stanza.prev"
+    say "ssh: host alias 'lanes' -> $server_user@$server_host, key $(tilde "$key")$([ -n "$server_public" ] && echo ', fallback lanes-public')"
+    pin_host_key
+}
+# The server key is PINNED from the package (site/known_hosts): a new machine never trusts on first use.
+pin_host_key() {
+    [ -r "$pinned" ] || { warn "no pinned host key next to the site file: you will be asked to verify the fingerprint"; return 0; }
+    want=$(awk -v a="$server_alias" '$1 == a && $2 == "ssh-ed25519" { print $3; exit }' "$pinned")
+    have=$(ssh-keygen -F "$server_alias" 2>/dev/null | awk '!/^#/ && $2 == "ssh-ed25519" { print $3; exit }')
+    if [ -z "$have" ]; then
+        touch "$HOME/.ssh/known_hosts"; chmod 600 "$HOME/.ssh/known_hosts"
+        grep "^$server_alias " "$pinned" >> "$HOME/.ssh/known_hosts"
+        say "known_hosts: pinned the server key as '$server_alias'"
+    elif [ -n "$want" ] && [ "$have" != "$want" ]; then
+        warn "known_hosts already has a DIFFERENT key for '$server_alias' than this package pins. Not changed — ask the server admin which one is right."
+    fi
+}
+
+# ---- client files ---------------------------------------------------------------------------------------------------
+install_client() {
+    mkdir -p "$bin" "$config"
+    if [ "$site_file" != "$config/client-site.conf" ]; then
+        cp "$site_file" "$config/client-site.conf"
+        if [ -r "$pinned" ]; then cp "$pinned" "$config/client-known-hosts"; else rm -f "$config/client-known-hosts"; fi
+    fi
+    existing=$(readlink "$bin/lanes-launch" 2>/dev/null || :)
+    case "$existing" in "$here"/client/*) link=1 ;; esac          # a development checkout stays linked
+    if [ "$link" = 1 ]; then
+        target=$here/client
+    else
+        target=$share/client
+        mkdir -p "$target"
+        rm -rf "$target.new"; mkdir -p "$target.new"
+        cp -R "$here/client/." "$target.new/"
+        cp "$here/VERSION" "$target.new/VERSION" 2>/dev/null || :
+        rm -f "$target.new/install.sh" "$target.new/omarchy/discover.sh"      # checkout-only helpers
+        rm -rf "$target.old"; [ -d "$target" ] && mv "$target" "$target.old"
+        mv "$target.new" "$target"; rm -rf "$target.old"
+    fi
+    chmod +x "$target/lanes-launch" "$target/lanes-window" "$target/lanes-upload"
+    for name in lanes-launch lanes-window lanes-upload; do ln -sfn "$target/$name" "$bin/$name"; done
+    say "commands: lanes-launch, lanes-window, lanes-upload in $(tilde "$bin") ($([ "$link" = 1 ] && echo "linked to this checkout" || echo "copied to $(tilde "$target")"))"
+    printf '%s\n' "$device" > "$config/device"
+    say "device (view session) name: $device"
+    # (a non-interactive ssh session has a minimal PATH: ask the login shell before complaining)
+    login_path=$("${SHELL:-/bin/sh}" -lc 'printf %s "$PATH"' 2>/dev/null || :)
+    case ":$PATH:$login_path:" in *":$bin:"*) ;; *)
+        rc='~/.profile'; case "${SHELL:-}" in */zsh) rc='~/.zprofile' ;; */bash) [ "$os" = Darwin ] && rc='~/.bash_profile' ;; */fish) rc='~/.config/fish/config.fish' ;; esac
+        warn "$(tilde "$bin") is not on your PATH. Add it (then open a new terminal):"
+        case "${SHELL:-}" in */fish) warn "    fish_add_path $bin" ;; *) warn "    echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> $rc" ;; esac ;;
+    esac
+    if [ "$coder_launch" = 1 ]; then
+        if [ -e "$bin/coder-launch" ] && [ ! -L "$bin/coder-launch" ]; then
+            mv "$bin/coder-launch" "$bin/coder-launch-legacy"; say 'kept the previous coder-launch as coder-launch-legacy'
+        fi
+        ln -sfn "$target/lanes-launch" "$bin/coder-launch"; say '`coder-launch` now starts the lanes client'
+    fi
+    # Ghostty: a SEPARATE instance with its own config file; the everyday Ghostty config is only read, never written.
+    { echo "# Generated by the lanes installer — edit the sources in client/ghostty/ and re-run it."
+      echo "command = $bin/lanes-launch"
+      cat "$target/ghostty/common.conf"
+      if [ "$os" = Darwin ]; then cat "$target/ghostty/macos.conf"; else cat "$target/ghostty/omarchy.conf"; fi
+    } > "$config/ghostty.conf"
+}
+
+find_terminal() {
+    if [ "$os" = Darwin ]; then
+        for app in /Applications/Ghostty.app "$HOME/Applications/Ghostty.app"; do
+            [ -d "$app" ] && { say "terminal: Ghostty ($app)"; return 0; }
+        done
+        warn 'Ghostty is not installed: `brew install --cask ghostty` (or ghostty.org). Until then run `lanes-launch` in any terminal.'
+    elif command -v ghostty >/dev/null 2>&1; then say "terminal: Ghostty ($(ghostty --version 2>/dev/null | head -n 1))"
+    elif command -v foot >/dev/null 2>&1; then
+        say 'terminal: Foot (Ghostty is used automatically once installed — Omarchy: omarchy-pkg-add ghostty)'
+    else
+        warn 'no Ghostty or Foot found: install Ghostty for the lanes window, or run `lanes-launch` in any terminal.'
+    fi
+}
+
+# ---- desktop integration --------------------------------------------------------------------------------------------
+install_desktop() {
+    if [ "$os" = Darwin ]; then
+        app="$HOME/Applications/Lanes.app"
+        if [ ! -d "$app" ] && command -v osacompile >/dev/null 2>&1; then
+            mkdir -p "$HOME/Applications"
+            osacompile -o "$app" -e "do shell script \"$bin/lanes-window >/dev/null 2>&1 &\"" >/dev/null 2>&1 &&
+                say "app: $(tilde "$app") (Spotlight: Lanes)"
+        fi
+        return 0
+    fi
+    mkdir -p "$HOME/.local/share/applications"
+    sed "s|^Exec=.*|Exec=$bin/lanes-window|" "$target/omarchy/lanes.desktop" > "$HOME/.local/share/applications/lanes.desktop"
+    # Hyprland (Omarchy): follow the LIVE config generation — Omarchy 4 = Lua, Omarchy 3 = hyprlang. One added
+    # line, validated with `hyprctl configerrors`, and reverted automatically if Hyprland reports any error.
+    hypr=$HOME/.config/hypr
+    if [ -f "$hypr/hyprland.lua" ]; then
+        main=$hypr/hyprland.lua; piece=$hypr/lanes.lua; line='require("hypr.lanes")'; cp "$target/omarchy/lanes.lua" "$piece"
+    elif [ -f "$hypr/hyprland.conf" ]; then
+        main=$hypr/hyprland.conf; piece=$hypr/lanes.conf; line='source = ~/.config/hypr/lanes.conf'; cp "$target/omarchy/lanes.conf" "$piece"
+    else
+        say 'desktop: added a "Lanes" launcher entry (no Hyprland config found, so no key binding)'; return 0
+    fi
+    if grep -qF "$line" "$main"; then say 'Hyprland: lanes key bindings already present (bind file refreshed)'; return 0; fi
+    backup=$main.pre-lanes.$stamp; cp -p "$main" "$backup"
+    comment='--'; [ "${main##*.}" = lua ] || comment='#'
+    printf '\n%s lanes workspace server (remove this line and %s to uninstall)\n%s\n' "$comment" "$(basename "$piece")" "$line" >> "$main"
+    signature=$(ls -t "/run/user/$(id -u)/hypr/" 2>/dev/null | head -n 1)
+    if [ -n "$signature" ] && command -v hyprctl >/dev/null 2>&1; then
+        export HYPRLAND_INSTANCE_SIGNATURE=$signature
+        hyprctl reload >/dev/null 2>&1 || :; sleep 1
+        if [ -n "$(hyprctl configerrors 2>/dev/null | tr -d '[:space:]')" ]; then
+            cp -p "$backup" "$main"; rm -f "$piece"; hyprctl reload >/dev/null 2>&1 || :
+            warn "Hyprland reported config errors -> reverted $(tilde "$main") (nothing changed)"
+        else
+            say "Hyprland: Super+Shift+L opens (or focuses) the lanes window — validated, backup $(basename "$backup")"
+        fi
+    else
+        say "Hyprland config updated (no running instance to validate against) — backup $(basename "$backup")"
+    fi
+}
+
+# ---- uploads --------------------------------------------------------------------------------------------------------
+install_uploads() {
+    watch=$(cat "$config/uploads-dir" 2>/dev/null || echo "$HOME/Lanes Uploads")
+    mkdir -p "$watch"
+    for board in ${boards:-}; do mkdir -p "$watch/$board"; done
+    [ -e "$watch/README.txt" ] || printf '%s\n' \
+        'Drop files here: they are uploaded to the uploads/ folder of the board your lanes view is showing.' \
+        'Drop them into a <board>/ subfolder to choose the board. Sent files move to .sent/<date>/.' \
+        'The in-container path lands on your clipboard. Command line: lanes-upload --help' > "$watch/README.txt"
+    if [ "$os" = Darwin ]; then
+        plist=$HOME/Library/LaunchAgents/$label.plist
+        mkdir -p "$HOME/Library/LaunchAgents"
+        { printf '%s\n' '<?xml version="1.0" encoding="UTF-8"?>' \
+            '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">' \
+            '<plist version="1.0"><dict>' "<key>Label</key><string>$label</string>" \
+            "<key>ProgramArguments</key><array><string>/bin/sh</string><string>$bin/lanes-upload</string><string>--watch-run</string></array>" \
+            '<key>ThrottleInterval</key><integer>2</integer>' '<key>WatchPaths</key><array>' "<string>$watch</string>"
+          for board in ${boards:-}; do printf '<string>%s</string>\n' "$watch/$board"; done
+          printf '%s\n' '</array>' "<key>StandardErrorPath</key><string>$config/upload-watch.log</string>" '</dict></plist>'
+        } > "$plist"
+        launchctl bootout "gui/$(id -u)/$label" >/dev/null 2>&1 || :
+        launchctl bootstrap "gui/$(id -u)" "$plist" >/dev/null 2>&1 || launchctl load "$plist" >/dev/null 2>&1 || :
+        # A droplet: drag files onto it (Dock / Finder toolbar) to upload AND type the path into the lane you look at.
+        app="$HOME/Applications/Lanes Upload.app"
+        if [ "$desktop" = 1 ] && [ ! -d "$app" ] && command -v osacompile >/dev/null 2>&1; then
+            mkdir -p "$HOME/Applications"
+            osacompile -o "$app" -e 'on open theItems' -e 'set args to ""' -e 'repeat with anItem in theItems' \
+                -e 'set args to args & " " & quoted form of POSIX path of anItem' -e 'end repeat' \
+                -e "do shell script \"$bin/lanes-upload --paste\" & args" -e 'end open' \
+                -e 'on run' -e "do shell script \"$bin/lanes-upload --clipboard --paste\"" -e 'end run' >/dev/null 2>&1 &&
+                say "droplet: $(tilde "$app") (drop files on it; double-click = upload the clipboard screenshot)"
+        fi
+    elif command -v systemctl >/dev/null 2>&1; then
+        units=${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user
+        mkdir -p "$units"
+        { printf '%s\n' '[Unit]' 'Description=lanes: upload files dropped into the watch folder' '[Path]' "PathChanged=$watch"
+          for board in ${boards:-}; do printf 'PathChanged=%s\n' "$watch/$board"; done
+          printf '%s\n' 'Unit=lanes-upload.service' '[Install]' 'WantedBy=default.target'; } > "$units/lanes-upload.path"
+        printf '%s\n' '[Unit]' 'Description=lanes: process the uploads watch folder' '[Service]' 'Type=oneshot' \
+            "ExecStart=/bin/sh $bin/lanes-upload --watch-run" > "$units/lanes-upload.service"
+        systemctl --user daemon-reload >/dev/null 2>&1 || :
+        systemctl --user enable --now lanes-upload.path >/dev/null 2>&1 || :
+    fi
+    say "uploads: drop files into \"$(tilde "$watch")\" (or a <board>/ subfolder) — or drag them onto the box in the sidebar"
+}
+
+# ---- upload helper service ------------------------------------------------------------------------------------------
+# The helper that serves the sidebar's upload box is a child of the lanes window, so it dies with it. As ONE service
+# per machine (`lanes-launch --helper <device> --service`, kept alive by launchd / systemd) it outlives every window.
+# That takes a client that does its half: touch $state/helper.alive on every READY/PING line from the server, start
+# the in-window helper only while that file is older than 90 s, and back off while the server is away. An older
+# lanes-launch ignores --service and retries its ssh login every 3 s — as a service that is around the clock, against
+# a server that may be thrashing. So the service is installed ONLY for a client that knows helper.alive, judged on
+# the INSTALLED file (that is what would run); with any other client the open window serves the upload box, as before.
+helper_supported() { grep -q 'helper\.alive' "$bin/lanes-launch" 2>/dev/null; }
+helper_loaded() {
+    if [ "$os" = Darwin ]; then launchctl print "gui/$(id -u)/$helper_label" >/dev/null 2>&1
+    else [ "$(systemctl --user is-active lanes-helper.service 2>/dev/null)" = active ]; fi
+}
+# Where the service's stderr goes: launchd writes the file named in the plist, a systemd user unit writes the journal.
+helper_log() { if [ "$os" = Darwin ]; then printf '%s' "$(tilde "$state")/helper-service.log"; else printf 'journalctl --user -u lanes-helper'; fi; }
+install_macos_helper_app() {
+    helper_app=$HOME/Applications/Lanes\ Helper.app
+    helper_source=$here/client/macos-helper.applescript
+    # Keep the signed bundle unchanged on ordinary reinstalls, so macOS keeps its folder grants.
+    if [ -f "$helper_app/Contents/Resources/source.applescript" ] &&
+        cmp -s "$helper_source" "$helper_app/Contents/Resources/source.applescript" &&
+        codesign --verify "$helper_app" >/dev/null 2>&1; then return 0; fi
+    mkdir -p "$share" "$HOME/Applications"
+    build=$(mktemp -d "$share/helper-build.XXXXXX")
+    built=$build/Lanes\ Helper.app
+    osacompile -o "$built" "$helper_source"
+    cp "$helper_source" "$built/Contents/Resources/source.applescript"
+    /usr/libexec/PlistBuddy -c "Add :CFBundleIdentifier string $helper_label" "$built/Contents/Info.plist"
+    /usr/libexec/PlistBuddy -c 'Add :LSUIElement bool true' "$built/Contents/Info.plist"
+    for folder in Downloads Desktop Documents; do
+        /usr/libexec/PlistBuddy -c "Add :NS${folder}FolderUsageDescription string Upload the files you drop onto Lanes to your workspace server." "$built/Contents/Info.plist"
+    done
+    codesign --force --sign - "$built" >/dev/null 2>&1
+    rm -rf "$helper_app"
+    mv "$built" "$helper_app"
+    rmdir "$build"
+}
+install_helper_service() {
+    if ! helper_supported; then say 'upload helper: the open lanes window serves the upload box (this client has no service mode)'; return 0; fi
+    mkdir -p "$state"
+    if [ "$os" = Darwin ]; then
+        install_macos_helper_app
+        plist=$HOME/Library/LaunchAgents/$helper_label.plist
+        mkdir -p "$HOME/Library/LaunchAgents"
+        printf '%s\n' '<?xml version="1.0" encoding="UTF-8"?>' \
+            '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">' \
+            '<plist version="1.0"><dict>' "<key>Label</key><string>$helper_label</string>" \
+            "<key>ProgramArguments</key><array><string>$helper_app/Contents/MacOS/applet</string></array>" \
+            '<key>KeepAlive</key><true/>' '<key>RunAtLoad</key><true/>' '<key>ProcessType</key><string>Interactive</string>' \
+            '<key>ThrottleInterval</key><integer>10</integer>' \
+            "<key>StandardErrorPath</key><string>$state/helper-service.log</string>" '</dict></plist>' > "$plist"
+        launchctl bootout "gui/$(id -u)/$helper_label" >/dev/null 2>&1 || :
+        # bootout returns before a RUNNING job is gone, and bootstrap fails (error 5) until it is: wait for it.
+        tries=0; while helper_loaded && [ "$tries" -lt 5 ]; do sleep 1; tries=$((tries + 1)); done
+        launchctl bootstrap "gui/$(id -u)" "$plist" >/dev/null 2>&1 || launchctl load "$plist" >/dev/null 2>&1 || :
+        say 'macOS folder access: choose Allow when Lanes Helper asks to read a folder you upload from'
+    elif command -v systemctl >/dev/null 2>&1; then
+        units=${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user
+        mkdir -p "$units"
+        printf '%s\n' '[Unit]' 'Description=lanes: upload helper of this machine (serves the upload box of every lanes window)' \
+            '[Service]' "ExecStart=/bin/sh $bin/lanes-launch --helper $device --service" 'Restart=always' 'RestartSec=5' \
+            '[Install]' 'WantedBy=default.target' > "$units/lanes-helper.service"
+        systemctl --user daemon-reload >/dev/null 2>&1 || :
+        # enable + restart (not `enable --now`): an update must run the NEW client, a first install connects once.
+        systemctl --user enable lanes-helper.service >/dev/null 2>&1 || :
+        systemctl --user restart lanes-helper.service >/dev/null 2>&1 || :
+        # A user unit has no terminal to ask for a passphrase and cannot be handed SSH_AUTH_SOCK by this script
+        # (PassEnvironment is not valid in user units). (-P '': succeeds only for a key without a passphrase.)
+        ssh-keygen -y -P '' -f "$key" >/dev/null 2>&1 ||
+            warn "your key has a passphrase: the helper service can only log in through an agent the systemd user manager knows (\`systemctl --user import-environment SSH_AUTH_SOCK\` at session start, then \`systemctl --user restart lanes-helper\`). Until then the open window serves the upload box."
+    else
+        say 'upload helper: no launchd or systemd here — the open lanes window serves the upload box'; return 0
+    fi
+    if helper_loaded; then say "upload helper: a background service for '$device' — independent of any window, restarted by the system"
+    else warn "upload helper: the service did not start (log: $(helper_log)) — the open window serves the upload box instead"; fi
+}
+# Epoch mtime. GNU form first: GNU `stat -f` means "file system" and prints that before failing; BSD rejects -c silently.
+mtime() { stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null; }
+# --check: is anything serving the upload box? Whoever does (the service, or a window's own helper when there is no
+# service) touches helper.alive on every READY/PING line from the server (one every 5 s); serving = younger than 90 s.
+check_helper() {
+    # (a client without the service side never writes helper.alive: there is nothing to measure, and nothing wrong)
+    if ! helper_supported; then say 'upload helper: an open lanes window serves the upload box itself (this client has no service mode)'; return 0; fi
+    service='no service (./install.sh adds it)'; if helper_loaded; then service='service running'; fi
+    seen=$(mtime "$state/helper.alive") || seen=
+    if [ -z "$seen" ] && helper_loaded; then warn "upload helper: $service, but it has never reached the server (log: $(helper_log))"; return 0; fi
+    # (no service and no heartbeat may be a choice: --no-uploads, or no window opened yet)
+    if [ -z "$seen" ]; then say "upload helper: $service — an open lanes window serves the upload box itself"; return 0; fi
+    age=$(( $(date +%s) - seen ))
+    if [ "$age" -lt 90 ]; then say "ok   upload helper: $service; last heard from the server ${age}s ago"
+    else warn "upload helper: $service; last heard from the server ${age}s ago (log: $(helper_log))"; fi
+}
+
+# ---- server ---------------------------------------------------------------------------------------------------------
+# Every call to the server is BOUNDED. A thrashing host accepts the connection and then says nothing for minutes;
+# ConnectTimeout does not cover the remote command, and macOS has no timeout(1) — so a watchdog subshell does it.
+#   bounded <command…>   runs it until $deadline (epoch seconds) -> $out, $err, $rc; rc 124 = killed, not finished.
+# The watchdog watches the temp file, not the pid: once the child is reaped its pid can belong to anyone. The
+# child keeps our stdin through fd 9 (an async job gets /dev/null otherwise; the terminfo push is piped in).
+bounded() {
+    left=$(( deadline - $(date +%s) )); out=; err=; rc=124
+    [ "$left" -gt 0 ] || return 124
+    tmp=$(mktemp)
+    exec 9<&0
+    "$@" <&9 9<&- > "$tmp" 2> "$tmp.err" &
+    pid=$!
+    exec 9<&-
+    ( while [ "$left" -gt 0 ]; do sleep 1; left=$((left - 1)); [ -e "$tmp" ] || exit 0; done
+      : > "$tmp.late"; kill -TERM "$pid" 2>/dev/null; sleep 2
+      if [ -e "$tmp" ]; then kill -KILL "$pid" 2>/dev/null; fi ) </dev/null >/dev/null 2>&1 &
+    rc=0; wait "$pid" 2>/dev/null || rc=$?        # (2>: bash reports a child that died of our TERM as "Terminated: 15")
+    if [ -e "$tmp.late" ]; then rc=124; fi
+    out=$(cat "$tmp"); err=$(cat "$tmp.err")
+    rm -f "$tmp" "$tmp.err" "$tmp.late"
+    return "$rc"
+}
+# -> server_state: ok | unauthorized | unreachable | hostkey | old | slow ; server_note: detail
+# The whole server part of an install takes at most ~25 s: 15 s for the greeting + 10 s for after_authorized
+# (the greeting gets 90 s in ONE case: a terminal and a key with a passphrase, where ssh may be waiting for a human).
+check_server() {
+    # ConnectTimeout also covers banner + key exchange: 10 s, because a busy server needs seconds for those alone.
+    opts='-o RequestTTY=no -o ConnectTimeout=10 -o PasswordAuthentication=no -o KbdInteractiveAuthentication=no'
+    patience=15
+    # With a terminal, let ssh ask for the key's passphrase once; without one, never hang on a prompt.
+    if [ -t 0 ] && [ "$assume_yes" = 0 ]; then
+        opts="$opts -o BatchMode=no"
+        # ...and then a human may be typing: do not kill the prompt. (-P '' succeeds only for a key without a passphrase.)
+        ssh-keygen -y -P '' -f "$key" >/dev/null 2>&1 || patience=90
+    else
+        opts="$opts -o BatchMode=yes"
+    fi
+    deadline=$(( $(date +%s) + patience ))
+    # shellcheck disable=SC2086
+    bounded ssh $opts -o LogLevel=ERROR lanes "\$HOME/.local/bin/lanes hello $device" || :
+    out=$(printf '%s\n%s' "$out" "$err")
+    server_note=$(printf '%s' "$out" | tail -n 1)
+    case "$out" in
+        ok\ *|*"
+ok "*) server_state=ok; server_note=$(printf '%s\n' "$out" | grep '^ok ' | tail -n 1) ;;
+        *'Host key verification failed'*|*'REMOTE HOST IDENTIFICATION HAS CHANGED'*) server_state=hostkey ;;
+        *'Permission denied'*|*'Too many authentication failures'*) server_state=unauthorized ;;
+        # The TCP connection stood but sshd never greeted: the host is there and overloaded, not "Tailscale is down".
+        *'during banner exchange'*) server_state=slow ;;
+        *) if [ "$rc" = 124 ]; then server_state=slow; elif [ "$rc" = 255 ]; then server_state=unreachable; else server_state=old; fi ;;
+    esac
+}
+after_authorized() {
+    deadline=$(( $(date +%s) + 10 ))
+    # site facts served by the server (kept out of the distributed package), e.g. the public fallback address
+    bounded ssh -o RequestTTY=no -o BatchMode=yes lanes '$HOME/.local/bin/lanes client-config' || :
+    facts=$(printf '%s\n' "$out" | grep '^LANES_[A-Z_]*=[A-Za-z0-9_.:@/-]*$' || :)
+    if [ -n "$facts" ]; then
+        printf '%s\n' "$facts" > "$config/site.cache"
+        public=$(printf '%s\n' "$facts" | sed -n 's/^LANES_SERVER_PUBLIC=//p' | head -n 1)
+        if [ -n "$public" ] && [ "$public" != "$server_public" ]; then server_public=$public; install_ssh >/dev/null; say "ssh: added the fallback path lanes-public"; fi
+    fi
+    # the terminal's terminfo entry for the ssh login on the server (user-level, no sudo)
+    if infocmp -x xterm-ghostty >/dev/null 2>&1 &&
+       ! bounded ssh -o RequestTTY=no -o BatchMode=yes lanes 'infocmp xterm-ghostty >/dev/null 2>&1' && [ "$rc" != 124 ]; then
+        infocmp -x xterm-ghostty | bounded ssh -o RequestTTY=no -o BatchMode=yes lanes 'mkdir -p ~/.terminfo && tic -x -o ~/.terminfo - 2>/dev/null' &&
+            say 'pushed the xterm-ghostty terminfo entry to the server' || say 'terminfo push failed (the session falls back to xterm-256color)'
+    fi
+    bounded ssh -o RequestTTY=no -o BatchMode=yes lanes '$HOME/.local/bin/lanes workspaces' || :
+    boards=$(printf '%s\n' "$out" | grep -E '^[A-Za-z0-9_.-]+$' || :)
+    # $deadline is absolute: once it has passed every later call returns 124 at once, so the last rc tells it all.
+    # Nothing is lost — the facts, the terminfo entry and the board folders come with the next run.
+    if [ "$rc" = 124 ]; then server_state=slow; fi
+}
+report_server() {
+    case "$server_state" in
+        ok) say "server: $server_note" ;;
+        old) warn "server answered, but without the expected greeting (an older server?): $server_note" ;;
+        unauthorized)
+            head_ 'One step left: this machine is not authorized on the server yet.'
+            say 'Send this PUBLIC key to your workspace-server admin (it is safe to share):'
+            printf '\n    %s\n\n' "$(cat "$key.pub")"
+            say "They add that line to ~$server_user/.ssh/authorized_keys on the server ($server_alias)."
+            say 'Then run:  ./install.sh --check      and open the window with:  lanes-window' ;;
+        hostkey) warn "the server's host key does not match what this machine trusts as '$server_alias' — do NOT connect; ask the admin." ;;
+        slow)
+            # An overloaded server is not a broken client (and not lost lanes): finish the local install, say so, exit 4.
+            if [ "$mode" = install ]; then warn 'server did not answer in time (busy?) — installed; run ./install.sh --check later'
+            else warn 'server did not answer in time (busy?) — run ./install.sh --check again later'; fi ;;
+        unreachable)
+            head_ "The server ($server_host) is not reachable from this machine."
+            say 'The path runs over Tailscale: is it running, and is this machine in the tailnet?'
+            ts=$(command -v tailscale 2>/dev/null || echo /Applications/Tailscale.app/Contents/MacOS/Tailscale)
+            if [ -x "$ts" ]; then say "tailscale: $("$ts" status 2>&1 | head -n 1)"; else say 'tailscale: not installed (tailscale.com/download)'; fi
+            say "detail: $server_note" ;;
+    esac
+}
+
+# ---- modes ----------------------------------------------------------------------------------------------------------
+do_install() {
+    command -v ssh >/dev/null 2>&1 || die 'OpenSSH (ssh) is required'
+    case "$os" in Darwin|Linux) ;; *) die "unsupported system: $os (macOS and Linux only)" ;; esac
+    load_site; src=$here/client
+    head_ "lanes client $(cat "$here/VERSION" 2>/dev/null || echo dev) -> $server_user@$server_alias"
+    choose_device; choose_key; ensure_key
+    install_client; src=$target
+    install_ssh
+    find_terminal
+    head_ 'Checking the server…'
+    check_server
+    boards=
+    if [ "$server_state" = ok ] || [ "$server_state" = old ]; then after_authorized; fi
+    report_server
+    if [ "$desktop" = 1 ]; then head_ 'Desktop'; install_desktop; fi
+    if [ "$uploads" = 1 ]; then [ "$desktop" = 1 ] || head_ 'Uploads'; install_uploads; install_helper_service; fi
+    case "$server_state" in
+        ok|old)
+            head_ 'Ready.'
+            say 'Open the window:   lanes-window          (Omarchy: Super+Shift+L · macOS: the Lanes app)'
+            say 'In any terminal:   lanes-launch          one lane only: lanes-launch lane <id> · list: lanes-launch ls'
+            say 'Keys:  Ctrl-Alt-←/→ board · Ctrl-Alt-↑/↓ lane · Ctrl-Alt-/ find · Ctrl-Alt-u upload box · close the window to detach'
+            exit 0 ;;
+        unauthorized) exit 3 ;;
+        *) exit 4 ;;
+    esac
+}
+
+do_check() {
+    load_site; src=$here/client; choose_device; choose_key
+    head_ "lanes client check -> $server_user@$server_alias"
+    for name in lanes-launch lanes-window lanes-upload; do
+        if [ -x "$bin/$name" ]; then say "ok   $name -> $(readlink "$bin/$name" 2>/dev/null || echo "$bin/$name")"; else warn "missing: $bin/$name (run ./install.sh)"; fi
+    done
+    say "device: $device · key: $(tilde "$key")$([ -r "$key" ] || echo ' (MISSING)')"
+    ssh -G lanes 2>/dev/null | awk '$1 == "hostname" { print "  ssh alias lanes -> " $2 }'
+    find_terminal
+    check_helper
+    check_server; report_server
+    case "$server_state" in ok) exit 0 ;; unauthorized) exit 3 ;; *) exit 4 ;; esac
+}
+
+do_uninstall() {
+    head_ 'Removing the lanes client from this machine'
+    for name in lanes-launch lanes-window lanes-upload coder-launch; do
+        case "$(readlink "$bin/$name" 2>/dev/null || :)" in */lanes/client/*|"$here"/client/*) rm -f "$bin/$name"; say "removed $bin/$name" ;; esac
+    done
+    if [ -e "$bin/coder-launch-legacy" ] && [ ! -e "$bin/coder-launch" ]; then mv "$bin/coder-launch-legacy" "$bin/coder-launch"; say 'restored the previous coder-launch'; fi
+    if [ "$os" = Darwin ]; then
+        for agent in "$label" "$helper_label"; do
+            launchctl bootout "gui/$(id -u)/$agent" >/dev/null 2>&1 || :
+            rm -f "$HOME/Library/LaunchAgents/$agent.plist"
+        done
+        rm -rf "$HOME/Applications/Lanes.app" "$HOME/Applications/Lanes Upload.app" "$HOME/Applications/Lanes Helper.app"
+    else
+        units=${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user
+        systemctl --user disable --now lanes-upload.path >/dev/null 2>&1 || :
+        systemctl --user disable --now lanes-helper.service >/dev/null 2>&1 || :
+        rm -f "$units/lanes-upload.path" "$units/lanes-upload.service" "$units/lanes-helper.service"
+        systemctl --user daemon-reload >/dev/null 2>&1 || :
+        rm -f "$HOME/.local/share/applications/lanes.desktop"
+        for main in "$HOME/.config/hypr/hyprland.lua" "$HOME/.config/hypr/hyprland.conf"; do
+            [ -f "$main" ] && grep -q -F -e 'require("hypr.lanes")' -e 'source = ~/.config/hypr/lanes.conf' "$main" || continue
+            cp -p "$main" "$main.pre-lanes-uninstall.$stamp"
+            grep -v -F -e 'lanes workspace server (remove this line' -e 'require("hypr.lanes")' -e 'source = ~/.config/hypr/lanes.conf' \
+                "$main.pre-lanes-uninstall.$stamp" > "$main" || :
+            say "Hyprland: removed the lanes line from $(tilde "$main") (backup kept)"
+        done
+        rm -f "$HOME/.config/hypr/lanes.lua" "$HOME/.config/hypr/lanes.conf"
+        command -v hyprctl >/dev/null 2>&1 && hyprctl reload >/dev/null 2>&1 || :
+    fi
+    if grep -q '^Include config.d/lanes.conf' "$HOME/.ssh/config" 2>/dev/null; then
+        cp -p "$HOME/.ssh/config" "$HOME/.ssh/config.pre-lanes-uninstall.$stamp"
+        grep -v -e '^Include config.d/lanes.conf' -e '^# lanes workspace server (added ' "$HOME/.ssh/config.pre-lanes-uninstall.$stamp" > "$HOME/.ssh/config" || :
+        chmod 600 "$HOME/.ssh/config"; say '~/.ssh/config: removed the Include line (backup kept)'
+    fi
+    rm -f "$HOME/.ssh/config.d/lanes.conf"
+    rm -rf "$share/client" "$state"
+    # A Linux account can run both roles. Keep server catalogs and any files
+    # the client did not create in the shared configuration directory.
+    rm -f "$config/device" "$config/ghostty.conf" "$config"/ghostty.*.conf \
+        "$config/client-site.conf" "$config/client-known-hosts" "$config/site.cache" \
+        "$config/upload-allow" "$config/uploads-dir" "$config/upload-watch.log"
+    rmdir "$config" 2>/dev/null || :
+    say 'stopped the upload agents (watch folder, upload helper service); removed the client, its settings and its logs'
+    say "kept: your SSH key, the known_hosts entry, and \"$HOME/Lanes Uploads\""
+    say 'Your view session on the server stays until an admin removes it (it holds no agents: lanes are never touched).'
+}
+
+case "$mode" in install) do_install ;; check) do_check ;; uninstall) do_uninstall ;; esac