@vibelord/lanes 1.0.0

package/payload/lanes/sudo/host-guard.sh

@@ -0,0 +1,356 @@
+#!/bin/sh
+# The lanes HOST GUARD — the second and last privileged piece of the lanes server. Run by hand on the workspace host:
+#     sudo sh ./sudo/host-guard.sh            read-only status + the plan of what --apply would do
+#     sudo sh ./sudo/host-guard.sh --apply    memory envelope for the harness/login path + the 60 s OOM-score guard
+#     sudo sh ./sudo/host-guard.sh --undo     recorded values back, guard removed
+# Why root: MemoryLow on user.slice and below is PID 1's to set (a user manager cannot protect itself: its ancestors
+# cap whatever it asks for), and LOWERING an oom_score_adj needs CAP_SYS_RESOURCE.
+# It never restarts, stops or signals anything, never calls docker, never runs or opens anything inside a container.
+# That is all it does, on purpose. The plan's DEFERRED measures (a smaller tmpfs /tmp, a container memory.high) are
+# not code: docs/HOST-GUARD.md has them as by-hand procedures with their preconditions, next to the NEVER list.
+set -eu
+umask 022
+
+# The three overrides exist for tests against a fake tree on a Mac; sudo's env_reset keeps them out of a real run.
+P=${LANES_PROC_ROOT:-/proc}
+CG=${LANES_CGROUP_ROOT:-/sys/fs/cgroup}
+D=${LANES_HG_DESTDIR:-}
+PREV=$D/var/lib/lanes-host-guard/prev
+GUARD=$D/usr/local/sbin/lanes-oom-guard
+UNITS=$D/etc/systemd/system
+CONF=$D/etc/lanes-host-guard.conf
+
+die() { echo "host-guard: $*" >&2; exit 1; }
+usage() { sed -n '2,10s/^# \{0,1\}//p' "$0"; }
+
+mode= guard_user=${SUDO_USER:-}
+while [ "$#" -gt 0 ]; do
+    case "$1" in
+        --user) guard_user=${2:?--user ACCOUNT}; shift ;;
+        --apply|--undo) [ -z "$mode" ] || { usage >&2; exit 2; }; mode=$1 ;;
+        -h|--help) usage; echo 'Add --user ACCOUNT when not invoked by the workspace user through sudo.'; exit 0 ;;
+        *) usage >&2; exit 2 ;;
+    esac
+    shift
+done
+[ "$(id -u)" = 0 ] || die 'run with sudo'
+case $guard_user in ''|root|*[!A-Za-z0-9._-]*) die 'specify the workspace account with --user ACCOUNT';; esac
+user=$guard_user
+[ -f "$CG/cgroup.controllers" ] || die "cgroup v2 is not mounted at $CG (a v1/hybrid host has no memory.low to set)"
+uid=$(id -u "$user") || die "no such user: $user"
+slice=$CG/user.slice/user-$uid.slice
+[ -d "$slice" ] || die "$slice does not exist: $user has no session and no lingering user manager"
+eval "guard_home=~$user"
+STATE=${LANES_STATE:-$guard_home/.local/state/lanes}
+
+# unit, the MemoryLow --apply gives it, its cgroup. Parent first: a child's protection is capped by every ancestor.
+# 4G on the slices = the ~1 GiB harness + sshd sessions (session-N.scope sits beside user@, not under it) + headroom;
+# 3G of that for the user manager, where statusd, the zellij servers and the viewers live.
+units() {
+    echo "user.slice 4G $CG/user.slice"
+    echo "user-$uid.slice 4G $slice"
+    echo "user@$uid.service 3G $slice/user@$uid.service"
+}
+
+first_line() { v='?'; if [ -r "$1" ]; then read -r v < "$1" || :; fi; echo "$v"; }
+
+gib() {  # bytes -> "12.3 GiB"; cgroup files say "max" for "no limit"
+    case $1 in ''|*[!0-9]*) echo "${1:-?}";; *) echo "$(($1 / 1073741824)).$(($1 % 1073741824 * 10 / 1073741824)) GiB";; esac
+}
+
+docker_cgroup() {  # $1 = pid -> its container's cgroup dir; fails unless that IS a docker container's cgroup
+    [ -r "$P/$1/cgroup" ] || return 1
+    while read -r line; do
+        p=${line#0::}
+        case $line in
+            0::*/docker-*.scope*) p=${p%%.scope*}.scope;;      # systemd driver; cut an in-container sub-cgroup off
+            0::/docker/*) p=${p#/docker/}; p=/docker/${p%%/*};;   # cgroupfs driver
+            *) continue;;
+        esac
+        if [ -d "$CG$p" ]; then echo "$CG$p"; return 0; fi
+    done < "$P/$1/cgroup"
+    return 1
+}
+
+# $1 = pid -> "fstype size_kib used_kib" of the container's /tmp: one statfs(2) through /proc/<pid>/root, no nsenter.
+# GNU `stat -f` first, because GNU df insists on NAMING the mount, and a tmpfs that exists only in the container's
+# mount namespace has no name out here (getcwd fails: "no file systems processed"). BSD stat has no -c: df it is.
+tmp_usage() {
+    dir=$P/$1/root/tmp
+    set -- $(stat -f -c '%T %S %b %f' "$dir" 2>/dev/null)     # type, block size, blocks, free blocks
+    case $#:${2:-}${3:-}${4:-} in
+        4:*[!0-9]*) ;;
+        4:*) echo "$1 $(($3 * $2 / 1024)) $((($3 - $4) * $2 / 1024))"; return 0;;
+    esac
+    df -Pk "$dir" 2>/dev/null | { read -r header; read -r fs size used rest && echo "$fs $size $used"; } || :
+}
+
+mem_stat() {  # $1 = cgroup dir -> anon, shmem (bytes)
+    anon=0 shmem=0
+    [ -r "$1/memory.stat" ] || return 0
+    while read -r key val; do case $key in anon) anon=$val;; shmem) shmem=$val;; esac; done < "$1/memory.stat"
+}
+
+# ---------------------------------------------------------------------------------------------------- the 60 s guard
+# One source for the installed script AND for the status summary (run from here with `sh -s status`), so what the
+# status shows is by construction what the timer does.
+guard_src() {
+    cat <<'GUARD'
+#!/bin/sh
+# lanes-oom-guard — installed by lanes/sudo/host-guard.sh --apply, which overwrites it: edit the source there.
+# Root, every 60 s (lanes-oom-guard.timer). Goal: when a container hits its memory limit the kernel's OOM killer takes
+# a build, never a lane. Pure /proc reads and writes; the only forks are one find+cat per cgroup tree, never one per
+# pid, so it stays cheap on a host that is already thrashing.
+#   lanes-oom-guard          protect (the timer)
+#   lanes-oom-guard status   print "<class> <oom_score_adj>" per protected process, change nothing
+#   lanes-oom-guard reset    put every mark of ours back to 0 (host-guard.sh --undo)
+set -u
+P=${LANES_PROC_ROOT:-/proc}
+CG=${LANES_CGROUP_ROOT:-/sys/fs/cgroup}
+CONF=${LANES_HOST_GUARD_CONF:-/etc/lanes-host-guard.conf}
+: "${agents:=claude codex codex-code-mode}" "${uid:=1000}" "${state_dir:=}"
+if [ -r "$CONF" ]; then . "$CONF"; fi
+mode=${1:-apply}
+
+# The policy is -900 (tmux servers, container init) and -500 (agents, zellij); the values written are one lower ON
+# PURPOSE. oom_score_adj is inherited over fork: every pane shell a marked tmux server starts, and every build a
+# marked agent starts, is born with the parent's mark — left alone, within days everything descended from a lane is
+# as protected as the lane and the killer takes the Coder agent or sshd instead. So each pass also puts an inherited
+# mark back to 0, and -901/-501 (values nobody else uses; docker's own is -500) are how it knows a mark is ours.
+# Never -1000: a cgroup in which nothing can be killed turns an OOM into a hang.
+SERVER=-901
+AGENT=-501
+
+ns_init() {  # $1 = pid: pid 1 of its own pid namespace AND in a docker cgroup? The pid files are written by the
+    # unprivileged lanes server and can be stale; root must never act on a recycled pid.
+    [ -r "$P/$1/cgroup" ] && [ -r "$P/$1/status" ] || return 1
+    ok=
+    while read -r line; do case $line in 0::*/docker-*.scope*|0::/docker/*) ok=1;; esac; done < "$P/$1/cgroup"
+    [ -n "$ok" ] || return 1
+    while read -r key val; do
+        case $key in NSpid:) set -- $val; [ $# -ge 2 ] || return 1; shift $(($# - 1)); [ "$1" = 1 ]; return;; esac
+    done < "$P/$1/status"
+    return 1
+}
+
+inits=' '
+if [ -n "$state_dir" ]; then
+    for f in "$state_dir"/containers/*.pid; do
+        [ -r "$f" ] || continue
+        read -r pid < "$f" || continue
+        case $pid in ''|0|*[!0-9]*) continue;; esac
+        if ns_init "$pid"; then inits="$inits$pid "; fi
+    done
+fi
+
+{
+    for pid in $inits; do echo "$pid init"; done
+    # Every docker container (either cgroup driver) + the whole user slice: the host-side zellij servers and any
+    # host tmux server live there, in scopes whose names vary. Classes are exact comm strings, so scanning wide
+    # touches nothing else. find, because a container may keep its processes in sub-cgroups.
+    for d in "$CG"/system.slice/docker-*.scope "$CG"/docker/* "$CG/user.slice/user-$uid.slice"; do
+        if [ -d "$d" ]; then find "$d" -name cgroup.procs -exec cat {} + 2>/dev/null; fi
+    done
+} | {
+    nset=0 nreset=0
+    while read -r pid forced; do
+        case $pid in ''|*[!0-9]*) continue;; esac
+        if [ -z "$forced" ]; then case $inits in *" $pid "*) continue;; esac; fi     # already handled as "init"
+        { read -r comm < "$P/$pid/comm" && read -r adj < "$P/$pid/oom_score_adj"; } 2>/dev/null || continue   # gone
+        case $adj in ''|*[!0-9-]*) continue;; esac
+        if [ -n "$forced" ]; then cls=init want=$SERVER
+        else
+            cls=$comm
+            case $comm in
+                'tmux: server') want=$SERVER;;   # tmux names itself so (prctl); clients are 'tmux: client'
+                zellij) want=$AGENT;;
+                '') want=0;;
+                # Claude Code's native binary is a file NAMED after its version (…/claude/versions/2.1.274), so that
+                # is its comm. Measured on the host 2026-09-19: claude x33, 2.1.274 x16, codex x40, codex-code-mode x10.
+                *[!0-9.]*) case " $agents " in *" $comm "*) want=$AGENT;; *) want=0;; esac;;
+                [0-9]*.[0-9]*.[0-9]*) want=$AGENT;;
+                *) want=0;;
+            esac
+        fi
+        if [ "$mode" = status ]; then
+            if [ "$want" != 0 ]; then echo "$cls $adj"
+            else case $adj in "$SERVER"|"$AGENT") echo "(inherited-mark) $adj";; esac; fi
+            continue
+        fi
+        if [ "$mode" = reset ]; then want=0; fi
+        new=
+        case $adj in
+            "$want") ;;
+            "$SERVER"|"$AGENT") new=$want;;      # our mark on the wrong process: inherited, or the class changed
+            *) if [ "$want" != 0 ] && [ "$adj" -gt "$want" ]; then new=$want; fi;;   # never RAISE a foreign value
+        esac
+        [ -n "$new" ] || continue
+        if { echo "$new" > "$P/$pid/oom_score_adj"; } 2>/dev/null; then
+            if [ "$new" = 0 ]; then nreset=$((nreset + 1)); else nset=$((nset + 1)); fi
+        fi
+    done
+    # Quiet when nothing changed: 1440 identical journal lines a day help nobody.
+    if [ "$mode" != status ] && [ $((nset + nreset)) -gt 0 ]; then
+        echo "lanes-oom-guard: $nset protected, $nreset inherited marks cleared"
+    fi
+}
+GUARD
+}
+
+run_guard() {  # before --apply there is no conf yet: uid and state dir go in through the environment, the conf wins
+    guard_src | LANES_PROC_ROOT=$P LANES_CGROUP_ROOT=$CG LANES_HOST_GUARD_CONF=$CONF uid=$uid state_dir=$STATE sh -s "$1"
+}
+
+# ------------------------------------------------------------------------------------------------------------ status
+status() {
+    echo "lanes host guard — status (read-only). user $user, uid $uid"
+    echo
+    echo 'Memory envelope (MemoryLow):'
+    units | while read -r unit val dir; do
+        now=$(systemctl show -p MemoryLow --value "$unit" 2>/dev/null </dev/null) || now='?'
+        printf '  %-20s systemd %-12s memory.low %-12s --apply: %s\n' "$unit" "${now:-?}" "$(first_line "$dir/memory.low")" "$val"
+    done
+    recursive=no
+    if [ -r "$P/mounts" ]; then
+        while read -r dev mp fs opts rest; do
+            if [ "$fs" = cgroup2 ]; then case ",$opts," in *,memory_recursiveprot,*) recursive=yes;; esac; fi
+        done < "$P/mounts"
+    fi
+    echo "  memory_recursiveprot: $recursive"
+    if [ "$recursive" = no ]; then
+        echo '  WARNING: without it a MemoryLow on these three units does not reach the leaf cgroups below them.'
+    fi
+
+    echo; echo 'Pressure (PSI):'
+    for r in memory io cpu; do
+        if [ -r "$P/pressure/$r" ]; then while read -r line; do printf '  %-7s %s\n' "$r" "$line"; done < "$P/pressure/$r"
+        else printf '  %-7s (no PSI in this kernel)\n' "$r"; fi
+    done
+
+    echo; echo "Containers (from $STATE/containers/*.pid):"
+    for f in "$STATE"/containers/*.pid; do
+        [ -r "$f" ] || continue
+        name=${f##*/}; name=${name%.pid}; pid=$(first_line "$f")
+        case $pid in ''|0|*[!0-9]*) echo "  $name: not running"; continue;; esac
+        if ! cg=$(docker_cgroup "$pid"); then echo "  $name: pid $pid is not in a docker cgroup (stale pid file)"; continue; fi
+        mem_stat "$cg"
+        kills='?'
+        if [ -r "$cg/memory.events" ]; then
+            while read -r key val; do case $key in oom_kill) kills=$val;; esac; done < "$cg/memory.events"
+        fi
+        echo "  $name  (pid $pid, ${cg##*/})"
+        echo "    memory.current $(gib "$(first_line "$cg/memory.current")") of max $(gib "$(first_line "$cg/memory.max")")," \
+             "high $(gib "$(first_line "$cg/memory.high")"); anon $(gib "$anon"), shmem $(gib "$shmem")"
+        echo "    swap.max $(gib "$(first_line "$cg/memory.swap.max")"), oom.group $(first_line "$cg/memory.oom.group"), oom_kill $kills"
+        set -- $(tmp_usage "$pid")
+        if [ $# -eq 3 ]; then
+            echo "    /tmp ($1): $(gib $(($3 * 1024))) used of $(gib $(($2 * 1024)))"
+        else echo '    /tmp: could not statvfs'; fi
+    done
+
+    echo; echo 'oom_score_adj by class (count, class, value; ours are -901 / -501):'
+    run_guard status | sort | uniq -c | sed 's/^/  /'
+
+    echo
+    oomd=$(systemctl is-active systemd-oomd.service 2>/dev/null) || :
+    echo "systemd-oomd: ${oomd:-unknown}"
+    if [ "$oomd" = active ]; then
+        echo '  WARNING: check `oomctl` — it must never manage system.slice or a docker scope (it kills whole cgroups).'
+    fi
+    if [ -e "$UNITS/lanes-oom-guard.timer" ]; then
+        timer=$(systemctl is-active lanes-oom-guard.timer 2>/dev/null) || :
+        echo "guard timer: installed, ${timer:-unknown}"
+    else echo 'guard timer: not installed'; fi
+
+    cat <<PLAN
+
+Plan — what --apply would do (this run changed nothing):
+  1. record the current MemoryLow of the three units under $PREV/ (once; a second --apply keeps the first record)
+  2. systemctl set-property   user.slice MemoryLow=4G · user-$uid.slice MemoryLow=4G · user@$uid.service MemoryLow=3G
+     (live and persistent; no daemon-reload, no restart of anything)
+  3. install $GUARD + lanes-oom-guard.service/.timer (every 60 s) and $CONF:
+     tmux servers and container inits -> -901, agents ($(if [ -r "$CONF" ]; then . "$CONF"; fi; echo "${agents:-claude codex}")) and zellij -> -501, inherited marks -> 0
+  --undo puts the recorded values back, clears the marks and removes the guard.
+PLAN
+}
+
+# ------------------------------------------------------------------------------------------------------ apply / undo
+apply() {
+    mkdir -p "$PREV" "${GUARD%/*}" "$UNITS"
+    units | while read -r unit val dir; do
+        # Record ONCE: a second --apply must not replace the real previous value with our own.
+        if [ ! -e "$PREV/$unit.MemoryLow" ]; then
+            now=$(systemctl show -p MemoryLow --value "$unit" </dev/null)
+            echo "${now:-0}" > "$PREV/$unit.MemoryLow"
+        fi
+        systemctl set-property "$unit" "MemoryLow=$val" </dev/null
+        echo "$unit: MemoryLow=$val (was $(first_line "$PREV/$unit.MemoryLow"))"
+    done
+
+    # Via a temp name + mv: the timer may exec the script at any moment, and root must never run half a file.
+    guard_src > "$GUARD.new"; chmod 755 "$GUARD.new"; mv "$GUARD.new" "$GUARD"
+    if [ ! -e "$CONF" ]; then   # kept on re-apply: the agent list is the one thing meant to be edited
+        cat > "$CONF" <<CONF_EOF
+# Read (sourced, sh syntax) by /usr/local/sbin/lanes-oom-guard. Written once by lanes/sudo/host-guard.sh --apply.
+# agents: exact comm strings (cat /proc/<pid>/comm, max 15 chars, no spaces) of the agent processes to protect.
+agents='claude codex'
+uid=$uid
+state_dir='$STATE'
+CONF_EOF
+    fi
+    cat > "$UNITS/lanes-oom-guard.service" <<'UNIT'
+[Unit]
+Description=lanes: keep tmux servers, agents and container inits out of the OOM killer's first picks
+
+[Service]
+Type=oneshot
+ExecStart=/usr/local/sbin/lanes-oom-guard
+UNIT
+    cat > "$UNITS/lanes-oom-guard.timer" <<'UNIT'
+[Unit]
+Description=lanes: run lanes-oom-guard every 60 s
+
+[Timer]
+OnBootSec=60
+OnUnitActiveSec=60
+AccuracySec=5
+
+[Install]
+WantedBy=timers.target
+UNIT
+    systemctl enable --now lanes-oom-guard.timer   # `enable` reloads the manager itself: the new units are seen
+    systemctl start lanes-oom-guard.service        # first pass now, so the verification below shows it
+    cat <<VERIFY
+
+Applied. Verify:
+  sudo sh $0
+      memory.low reads 4294967296 / 4294967296 / 3221225472; tmux servers and inits at -901, agents and zellij at -501
+  systemctl list-timers lanes-oom-guard.timer; journalctl -u lanes-oom-guard -n 5
+      next run within 60 s; the journal says "N protected, M inherited marks cleared" only when something changed
+  as $user:  lanes invariant check
+      no lane changed
+Undo: sudo sh $0 --undo
+VERIFY
+}
+
+undo() {
+    units | while read -r unit val dir; do
+        [ -e "$PREV/$unit.MemoryLow" ] || { echo "$unit: nothing recorded, left alone"; continue; }
+        was=$(first_line "$PREV/$unit.MemoryLow")
+        systemctl set-property "$unit" "MemoryLow=$was" </dev/null
+        rm -f "$PREV/$unit.MemoryLow"
+        echo "$unit: MemoryLow=$was restored"
+    done
+    systemctl disable --now lanes-oom-guard.timer 2>/dev/null || :
+    # Marks outlive the timer (and keep being inherited) unless they are cleared; ours are recognisable, so this is exact.
+    run_guard reset || :
+    rm -f "$GUARD" "$UNITS/lanes-oom-guard.service" "$UNITS/lanes-oom-guard.timer"
+    systemctl daemon-reload
+    echo "guard removed. $CONF is kept (your agent list); delete it by hand if you like."
+}
+
+case $mode in
+    '') status;;
+    --apply) apply;;
+    --undo) undo;;
+esac

package/payload/lanes/sudo/one-time-root.sh

@@ -0,0 +1,32 @@
+#!/bin/sh
+# Optional server admin setup: grant Tailscale Serve to the workspace account.
+# sudo sh sudo/one-time-root.sh [--user ACCOUNT] [--ssh-keepalive]
+set -eu
+user=${SUDO_USER:-} keepalive=0
+while [ "$#" -gt 0 ]; do
+    case "$1" in
+        --user) user=${2:?--user ACCOUNT}; shift ;;
+        --ssh-keepalive) keepalive=1 ;;
+        -h|--help) sed -n '2,3s/^# //p' "$0"; exit 0 ;;
+        *) echo "unknown option: $1" >&2; exit 2 ;;
+    esac
+    shift
+done
+[ "$(id -u)" = 0 ] || { echo 'run with sudo' >&2; exit 1; }
+case "$user" in ''|root|*[!A-Za-z0-9._-]*) echo 'specify the unprivileged workspace account with --user' >&2; exit 2 ;; esac
+id "$user" >/dev/null
+tailscale set --operator="$user"
+if [ "$keepalive" = 1 ]; then
+    conf=/etc/ssh/sshd_config.d/10-lanes.conf
+    if [ ! -e "$conf" ]; then
+        printf '# lanes: reap dead interactive clients\nClientAliveInterval 15\nClientAliveCountMax 3\n' > "$conf"
+        if sshd -t; then
+            systemctl reload ssh 2>/dev/null || systemctl reload sshd
+        else
+            rm -f "$conf"
+            echo 'sshd rejected the keepalive snippet; removed it.' >&2
+            exit 1
+        fi
+    fi
+fi
+printf 'Next, as %s: sh ~/.local/share/lanes/current/install/enable-phone.sh --local\n' "$user"

package/payload/lanes/systemd/lanes-ensure.service

@@ -0,0 +1,7 @@
+[Unit]
+Description=lanes: recreate any missing device view session (agents are never touched)
+
+[Service]
+Type=oneshot
+ExecStart="@REPO@/bin/lanes" ensure
+Slice=lanes.slice

package/payload/lanes/systemd/lanes-ensure.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=lanes ensure every minute
+
+[Timer]
+OnBootSec=45s
+OnUnitActiveSec=1min
+AccuracySec=5s
+
+[Install]
+WantedBy=timers.target

package/payload/lanes/systemd/lanes-gc.service

@@ -0,0 +1,7 @@
+[Unit]
+Description=lanes housekeeping (zmx logs never rotate; stale dynamic resolve files)
+
+[Service]
+Type=oneshot
+ExecStart="@REPO@/bin/lanes" gc
+Slice=lanes.slice

package/payload/lanes/systemd/lanes-gc.timer

@@ -0,0 +1,9 @@
+[Unit]
+Description=lanes housekeeping daily
+
+[Timer]
+OnBootSec=10min
+OnUnitActiveSec=1d
+
+[Install]
+WantedBy=timers.target

package/payload/lanes/systemd/lanes-guard.service

@@ -0,0 +1,8 @@
+[Unit]
+Description=lanes: keep build processes the preferred OOM victims in the workspace containers (raise only, /proc writes)
+
+[Service]
+Type=oneshot
+Slice=lanes.slice
+Nice=10
+ExecStart="@REPO@/bin/lanes" guard --once

package/payload/lanes/systemd/lanes-guard.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=lanes: run the OOM guard every minute (new builds start all the time; a raise costs a few /proc reads)
+
+[Timer]
+OnBootSec=90s
+OnUnitActiveSec=60s
+AccuracySec=10s
+
+[Install]
+WantedBy=timers.target

package/payload/lanes/systemd/lanes-mobile.service

@@ -0,0 +1,23 @@
+[Unit]
+Description=lanes: responsive phone frontend on loopback
+Requires=lanes-web.service
+After=lanes-web.service
+
+[Service]
+ExecStart="@CADDY@" run --config "@REPO@/web/Caddyfile" --adapter caddyfile
+ExecReload=/bin/kill -USR1 $MAINPID
+RuntimeDirectory=lanes-mobile
+Environment=XDG_CONFIG_HOME=%t/lanes-mobile/config
+Environment=XDG_DATA_HOME=%t/lanes-mobile/data
+Restart=on-failure
+RestartSec=3
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=read-only
+MemoryHigh=128M
+MemoryMax=256M
+Slice=lanes.slice
+
+[Install]
+WantedBy=default.target

package/payload/lanes/systemd/lanes-statusd.service

@@ -0,0 +1,15 @@
+[Unit]
+Description=lanes status daemon (observes lanes, never touches them)
+
+[Service]
+ExecStart=/usr/bin/python3 -S -E "@REPO@/libexec/statusd.py"
+Restart=always
+RestartSec=2
+Nice=5
+MemoryLow=96M
+MemoryHigh=192M
+MemoryMax=384M
+Slice=lanes.slice
+
+[Install]
+WantedBy=default.target

package/payload/lanes/systemd/lanes-sync.service

@@ -0,0 +1,10 @@
+[Unit]
+Description=lanes registry sync (read-only: rebuild registry.json from the repos' terminal registries)
+
+[Service]
+Type=oneshot
+ExecStart="@REPO@/bin/lanes" sync
+# A momentarily invalid registry keeps the previous lanes; a non-zero exit here is informational.
+SuccessExitStatus=1
+Nice=5
+Slice=lanes.slice

package/payload/lanes/systemd/lanes-sync.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=lanes registry sync every 2 minutes
+
+[Timer]
+OnBootSec=30s
+OnUnitActiveSec=2min
+AccuracySec=10s
+
+[Install]
+WantedBy=timers.target

package/payload/lanes/systemd/lanes-tmpreap.service

@@ -0,0 +1,11 @@
+[Unit]
+Description=lanes: remove dead temp trees from the containers' RAM-backed /tmp (dry-run until flags/tmpreap.armed exists)
+
+[Service]
+Type=oneshot
+ExecStart="@REPO@/bin/lanes" tmp reap
+# A oneshot has no start timeout by default: a run stuck on a thrashing host must not block the next hour's.
+TimeoutStartSec=30min
+Nice=19
+IOSchedulingClass=idle
+Slice=lanes.slice

package/payload/lanes/systemd/lanes-tmpreap.timer

@@ -0,0 +1,13 @@
+[Unit]
+Description=lanes tmp reap hourly
+
+[Timer]
+# Not enabled by install/host-install.sh: `systemctl --user enable --now lanes-tmpreap.timer`, by hand, after the first
+# real `lanes tmp plan` / `apply`. OnActiveSec, not OnBootSec: a boot-relative time is already in the past on a
+# running host, so enabling would start a walk at once.
+OnActiveSec=1h
+OnUnitActiveSec=1h
+AccuracySec=1min
+
+[Install]
+WantedBy=timers.target

package/payload/lanes/systemd/lanes-web.service

@@ -0,0 +1,13 @@
+[Unit]
+Description=lanes: zellij web server on loopback only (tailnet exposure is a separate, user-run Tailscale Serve step)
+
+[Service]
+ExecStart="@SHARE@/bin/zellij-0.45.1" --config-dir "@REPO@/zellij" --config "@REPO@/zellij/config.kdl" web --start --ip 127.0.0.1 --port 8082
+Restart=always
+RestartSec=5
+MemoryHigh=512M
+MemoryMax=1G
+Slice=lanes.slice
+
+[Install]
+WantedBy=default.target

package/payload/lanes/systemd/lanes.slice

@@ -0,0 +1,11 @@
+[Unit]
+Description=lanes: the harness (services and view sessions). Tiny, but it must be scheduled while the host thrashes
+
+[Slice]
+# Weight against its siblings under the user manager (needs the cpu controller delegated to user@; ignored otherwise).
+CPUWeight=10000
+# Protection from reclaim for the harness's ~1 GiB working set. It only becomes effective once root has given the
+# ancestors (user.slice -> user-<uid>.slice -> user@<uid>.service) a MemoryLow: sudo/host-guard.sh --apply. This host
+# mounts cgroup2 WITHOUT memory_recursiveprot, so the leaves below ask explicitly as well (scopes: bin/lanes
+# create_session; statusd: its unit file).
+MemoryLow=2G

package/payload/lanes/web/Caddyfile

@@ -0,0 +1,37 @@
+{
+	admin off
+	auto_https off
+}
+
+# The existing Zellij server owns authentication and both WebSocket channels.
+# This loopback-only frontend adds mobile assets without rebuilding the pinned binary.
+http://:8083 {
+	bind 127.0.0.1
+	root * "{$LANES_REPO}/web"
+	header {
+		X-Content-Type-Options nosniff
+		X-Frame-Options DENY
+		Referrer-Policy strict-origin-when-cross-origin
+		Content-Security-Policy "default-src 'self'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; connect-src 'self' ws: wss:; img-src 'self' data:"
+	}
+	handle_path /lanes-assets/* {
+		header Cache-Control "no-cache"
+		file_server
+	}
+	@backend path /assets/* /ws/* /command/* /info/* /session /session-list
+	handle @backend {
+		reverse_proxy 127.0.0.1:8082
+	}
+	@page {
+		method GET HEAD
+		path_regexp session ^/([A-Za-z0-9_.-]+)?$
+	}
+	handle @page {
+		rewrite * /index.html
+		header Cache-Control "no-store"
+		file_server
+	}
+	handle {
+		reverse_proxy 127.0.0.1:8082
+	}
+}

package/payload/lanes/web/README.md

@@ -0,0 +1,35 @@
+# Phone frontend
+
+The Lanes shell enhances the pinned Zellij 0.45.1 web client on phones. It uses that client's existing
+`window.__zjMobileUi`, `window.__zjSendControl`, `window.__zjSoftKbdCapture`, and `window.term` hooks.
+There is no separate auth system or command API. Workspace names are rendered as text, and navigation
+uses Zellij's authenticated `FocusPane` messages. Desktop browsers keep the upstream interface.
+
+The phone keyboard opens through a native tap on an input field. The bottom **Type here** field contains
+Zellij's original capture input in its closed shadow root, preserving its keyboard/IME handling. The client
+blocks programmatic focus on text editors and keeps `__zjSoftKbdEnabled` false, so upstream touch handlers,
+two-finger gestures, server `SetSoftKeyboard` messages and modal autofocus cannot summon it. Search and
+login inputs still focus normally when tapped. Keep this policy in place when upgrading the upstream client.
+
+`lanes-mobile.service` runs a separate, loopback-only Caddy on port 8083 with its admin API disabled.
+It does not change the system Caddy. Tailscale Serve forwards private HTTPS on 8443 to this frontend;
+the original Zellij service stays on 8082. Caddy must already be installed on the host.
+Run `sh install/enable-phone.sh --host lanes` from an installed client, or `--local` on the server.
+The [installation guide](../docs/INSTALL.md) covers Caddy, Tailscale operator permission and the selected SSH key.
+Service registration supplies `LANES_REPO` so Caddy serves the actual checkout from any installation path.
+
+`index.html` keeps the upstream asset integrity hashes. When upgrading Zellij, compare the HTML and
+window hooks against the new version before changing the pinned binary. The mobile JS and CSS have
+`no-cache` headers, and entry pages use `no-store`, so reopening the app picks up changes without
+clearing login cookies. There is no service worker caching terminal data or credentials.
+
+Layout uses the visual viewport and safe-area insets, with independent handling for portrait, landscape,
+keyboard-open and Home Screen views. The default terminal font is 16 px; the user's text-size choice
+is stored locally. Minimum touch targets are 44 px (workspace cards are 74 px). The lane picker in
+`libexec/sidebar.py` uses three terminal rows per lane on mobile. `tests/mobile_view.py` verifies
+the touch-to-lane path with isolated holders; sidebar unit tests cover the complete touch target.
+
+Validate on Safari/WebKit at 440 × 763 (iPhone 17 Pro Max with browser chrome), 440 × 956 (Home Screen),
+838 × 390 (landscape Safari), and smaller phone widths. Check login, workspace search and switching,
+lane selection, pane navigation, font controls, rotation and the visible viewport while the keyboard opens.
+Use disposable view sessions and revoke any temporary test token afterward.

package/payload/lanes/web/icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="192" height="192" viewBox="0 0 192 192">
+  <rect width="192" height="192" rx="42" fill="#101318"/>
+  <g fill="#b4e3bf"><rect x="44" y="44" width="104" height="24" rx="8"/><rect x="44" y="84" width="80" height="24" rx="8"/><rect x="44" y="124" width="56" height="24" rx="8"/></g>
+</svg>