@vibelord/lanes 1.0.0

package/payload/lanes/docs/HOST-GUARD.md

@@ -0,0 +1,108 @@
+# lanes — host guard (`sudo/host-guard.sh`)
+
+One small root script, run by hand. It exists because of 2026-09-19: ceobox thrashed (swap full, PSI memory ≈ 68 %),
+the ~1 GiB lanes harness and the ssh login path were swapped out with everything else, and the only thing standing
+between a container at its memory limit and a dead lane was the OOM killer's default choice.
+
+```
+sudo sh ./sudo/host-guard.sh            # read-only status + the plan of what --apply would do
+sudo sh ./sudo/host-guard.sh --apply
+sudo sh ./sudo/host-guard.sh --undo
+```
+
+It refuses to run when it is not root, when cgroup v2 is not mounted, or when `user-<uid>.slice` of the calling user
+(`SUDO_USER`, or explicit `--user ACCOUNT`) does not exist. It never restarts, stops or signals anything, never calls docker, and
+never runs or opens anything inside a container. Status: **not yet run on ceobox** — tested only against a fake
+`/proc` + cgroup tree on a Mac (see the end).
+
+The no-argument status shows: `MemoryLow` of the three units (systemd's view and the cgroup file), whether the cgroup2
+mount has `memory_recursiveprot`, PSI, per container `memory.current` / `max` / `high` / `swap.max` / `oom.group` /
+anon / shmem / `oom_kill` and the size and use of its `/tmp` (one `statfs` through `/proc/<init-pid>/root`, no
+nsenter), `oom_score_adj` per protected class, systemd-oomd's state, whether the guard timer is installed — and then
+the plan of what `--apply` would do.
+
+## What `--apply` does, and why each piece needs root
+
+| Piece | What | Why root |
+|---|---|---|
+| Memory envelope | `systemctl set-property` `user.slice MemoryLow=4G`, `user-<uid>.slice MemoryLow=4G`, `user@<uid>.service MemoryLow=3G`. Live and persistent (drop-ins under `/etc/systemd/system.control/`), no daemon-reload, nothing restarts. 4G covers the harness + the ssh sessions (`session-N.scope` sits beside `user@`, not under it); 3G of it is for the user manager, where statusd, the zellij servers and the viewers live. | These are system units. A user manager cannot protect itself: `memory.low` is capped by every ancestor, so the value has to be set from `user.slice` down, which only PID 1 does for root. |
+| `lanes-oom-guard` | `/usr/local/sbin/lanes-oom-guard` + `lanes-oom-guard.service/.timer`, every 60 s. Lowers `oom_score_adj` of tmux servers and container inits (−901), agents and zellij (−501). | *Lowering* an `oom_score_adj` needs `CAP_SYS_RESOURCE`; raising one does not (that is why Step 0.4 of the plan, +800 on builds, needs no root). |
+| Record | Previous `MemoryLow` values under `/var/lib/lanes-host-guard/prev/`, written once — a second `--apply` keeps the first record. | root-owned state for `--undo`. |
+
+`MemoryLow` protects from *future* reclaim; it does not swap anything back in. It only reaches the leaf cgroups when
+the cgroup2 mount has `memory_recursiveprot` (systemd's default; the status says yes/no and warns on no). And the
+envelope belongs to everything in the user's slice, not to lanes: protection is shared out by usage, so a large
+host-side process of the same user (the restic run) takes its share of it. It is a floor for the login path, not a
+reservation for the harness.
+
+### The OOM guard
+
+- **Where it looks:** `cgroup.procs` of every docker container cgroup (`system.slice/docker-*.scope`, or `docker/*` with
+  the cgroupfs driver; sub-cgroups included) and of the whole `user-<uid>.slice` (host zellij servers, any host tmux).
+- **What it matches:** the exact `comm` — `tmux: server` (tmux names itself so; clients are `tmux: client`), `zellij`,
+  and the agent list in `/etc/lanes-host-guard.conf` (`agents='claude codex'`; exact `/proc/<pid>/comm` strings as
+  verified in Step 0 — edit it if an agent runs as `node` or a version-named binary, but then every `node` is an
+  agent). Container inits come from `~/.local/state/lanes/containers/*.pid`, believed only when the pid is pid 1 of
+  its own pid namespace **and** in a docker cgroup (the files are written by the unprivileged server and can be stale).
+  Nothing else is ever given a protective value.
+- **Why −901 / −501 and not the plan's −900 / −500:** `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 value; 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 sets an *inherited* mark back to 0 — and the odd values are how the guard knows a
+  mark is its own (docker's own value is −500; nobody uses −501). A foreign value is never raised (a tmux server at
+  −1000 stays there) and never reset. A fresh child carries the mark for at most 60 s.
+- **Never −1000:** a cgroup in which nothing can be killed turns an OOM into a hang.
+- Cost: `sh`, one `find`+`cat` per cgroup tree, then builtin reads of two tiny `/proc` files per pid. No fork per pid.
+  It logs one line to the journal only when it changed something.
+
+## Verify
+
+```
+sudo sh ./sudo/host-guard.sh                  # memory.low 4294967296 / 4294967296 / 3221225472; marks by class
+systemctl list-timers lanes-oom-guard.timer         # next run within 60 s
+journalctl -u lanes-oom-guard -n 5                  # "N protected, M inherited marks cleared"
+lanes invariant check                               # as the workspace user: no lane changed
+```
+
+## Undo
+
+`sudo sh ./sudo/host-guard.sh --undo` sets the recorded `MemoryLow` values back (`set-property`, so a drop-in
+saying `MemoryLow=0` stays behind — it is inert), sets every −901 / −501 mark back to 0, disables and removes the
+timer, service and script, and reloads systemd. `/etc/lanes-host-guard.conf` is kept (your agent list).
+"Back to 0" is exact inside a container (docker's default); on the host, a process the user manager had started at
+100 / 200 ends at 0 — marginally *more* protected than before, and only until it restarts.
+
+## Deferred — by hand, and not code
+
+The plan defers two tighter limits until pressure recurs *after* `/tmp` has been emptied (Steps 1–2). They are
+deliberately **not** sub-commands of the root script: neither is needed now, and the first cannot be done from outside
+without running a container's binary as host root. What would otherwise be forgotten is here instead. Both need the
+status output first (it prints every number below, the init pid and the `docker-<id>.scope` name).
+
+| Measure | Only when | By hand | Back |
+|---|---|---|---|
+| Smaller tmpfs `/tmp` (96 → 64 → 32 G, one notch at a time) | `/tmp` is its own tmpfs and holds ≤ 60 % of the **new** size. The kernel itself refuses a size below current use (`EINVAL`), so a wrong number fails instead of destroying — but a cap close to use is `ENOSPC` for every writer in the container minutes later. It frees nothing; it only stops growth. | `nsenter -t <init-pid> -m mount -o remount,<the mount's current flags>,size=64G /tmp` — flags (`nosuid,nodev,noexec…`) from field 6 of the `/tmp` line in `/proc/<init-pid>/mountinfo`: not every `mount` keeps them on a remount. **Hazard:** `nsenter -m` also moves the root directory, so the `mount` that runs is the *container's* file, as host root and outside the container's confinement. Only for a container whose contents you trust as root. | the same command with the old size |
+| Container `memory.high` (e.g. 185 G under a 208 G `memory.max`) | `memory.current` ≤ 90 % **and** anon + shmem ≤ 80 % of the value. Above `memory.high` every allocation in the container is throttled into reclaim; with swap full that is not a kill but a freeze of all lanes. | `systemctl set-property --runtime docker-<id>.scope MemoryHigh=185G` — through systemd, which rewrites `memory.*` of its scopes from its own view at every daemon-reload (a raw `echo` into `memory.high` can silently disappear). | `MemoryHigh=infinity` |
+
+## NEVER
+
+- systemd-oomd on docker scopes or `system.slice` (it kills whole cgroups: every lane of a container at once).
+- `memory.oom.group=1` on a container (same effect, from the kernel).
+- `memory.max` below current usage — that is a live OOM sweep. `memory.high` only, and only through the check above.
+- `swapoff` under pressure.
+- Touching `/tmp/tmux-1000` (the lanes' sockets).
+- Restarting a container, docker, or `user@<uid>.service`.
+- `oom_score_adj` −1000 for everything.
+- Tightening anything before usage has dropped.
+
+## How it was tested
+
+Against a synthetic `/proc` + cgroup tree with `id` / `systemctl` / `stat` / `df` shims on `PATH`, under both `sh` and
+`dash` on macOS: refusals (not root, no cgroup v2, no user slice, unknown or surplus arguments); status writes nothing
+and calls nothing but `systemctl show` / `is-active`; `/tmp` via GNU `stat -f` and the `df` fallback; `--apply` order
+(parent first), record-once, atomic install, conf kept on re-apply; the guard's classification incl. inherited marks,
+foreign values (−1000, docker's −500, a build at +800), sub-cgroups, vanished pids and a stale pid file; `--undo`
+incl. clearing the marks, and that it is idempotent. The overrides that make this possible (`LANES_PROC_ROOT`,
+`LANES_CGROUP_ROOT`, `LANES_HG_DESTDIR`) do not survive sudo's `env_reset`.
+Not covered by any of that: real systemd, a real kernel, a real container — the first real run is the no-argument
+status, which changes nothing.

package/payload/lanes/docs/INSTALL.md

@@ -0,0 +1,192 @@
+# Install the complete Lanes setup
+
+The same `lanes/` directory installs either a desktop client or the workspace server. A deployment needs
+one server and one client installation per desktop. Safari uses the optional web services on the server.
+Configuration identifies your server and workspaces; credentials and generated runtime state stay outside Git.
+
+## 1. Prepare a workspace host
+
+Supported server: Linux x86_64, Python 3.9+, systemd user services, OpenSSH server, Docker, tmux, curl, tar,
+`sha256sum`, `infocmp` and `tic`. The pinned binaries in `holders.lock` are Linux x86_64 builds.
+Install missing packages using your distribution's package manager. The installer checks them before changing files.
+
+Run the server as an unprivileged workspace account with Docker access. Container homes must be mounted at
+`/home/coder` with UID 1000; the host account must be able to read the mounted files and reach those users'
+Unix sockets through `/proc`. This is the current container contract, including on a host provisioned without Coder.
+Containers need Bash, Python 3 and tmux. Use compatible tmux versions on the host and containers (tested with
+tmux 3.4): the host client attaches directly to the container server. Zmx is installed as an optional holder,
+not a migration of existing lanes.
+
+For services to stay available after logout, an administrator enables the account's user manager:
+
+```sh
+sudo loginctl enable-linger workspace   # replace workspace with the actual account
+```
+
+As that account, clone the repository and install:
+
+```sh
+git clone https://github.com/bwllaming/bw-tools.git
+cd bw-tools/lanes
+./install.sh --server --check
+./install.sh --server
+```
+
+`--server --no-start` installs files and units without contacting Docker or starting services. The normal install
+verifies archive checksums, installs the pinned binaries, registers this checkout's absolute paths, and enables
+`lanes-statusd`, `lanes-sync.timer`, `lanes-ensure.timer` and `lanes-gc.timer`. It creates an empty workspace catalog
+only if no configuration exists. Host protection, temporary-file deletion and web access remain opt-in.
+
+## 2. Configure workspaces and editor sync
+
+Start from the included configuration, then edit container names and repository paths:
+
+```sh
+mkdir -p ~/.config/lanes/workspaces
+cp -R workspaces.example/. ~/.config/lanes/workspaces/
+$EDITOR ~/.config/lanes/workspaces/catalog.json
+$EDITOR ~/.config/lanes/workspaces/workspaces.product.json
+$EDITOR ~/.config/lanes/workspaces/workspaces.research.json
+lanes install-container my-workspace-container
+lanes sync
+lanes doctor
+```
+
+Remove unused example boards from the catalog. A complete terminal registry is provided in
+[`workspaces.example/terminals.example.json`](../workspaces.example/terminals.example.json): adapt it to the
+repository's `.vscode/terminals.json` inside the container. Every terminal needs an explicit tmux socket/session
+binding; there is no guessed command parsing. See [the configuration reference](../workspaces.example/README.md).
+
+```sh
+lanes cursor-sync --diff           # preview editor commands and retained create recipes
+lanes cursor-sync --write          # apply with backups, after reviewing the preview
+lanes sync
+lanes attach laptop
+```
+
+A lane that has not started is shown as absent. Open its terminal in Cursor / VS Code, or run
+`/home/coder/.lz/bin/lane open product--shell` inside its container to create it from its recorded recipe.
+The viewer itself only attaches. `lanes cursor-commit --push` is a separate, explicit publishing action;
+it is not run by installation or automatic sync.
+
+## 3. Give clients a site profile
+
+Copy [`site/site.example.conf`](../site/site.example.conf) and fill in the server's reachable hostname,
+SSH account, and host-key alias. Put the server's public Ed25519 **host** key in a file named `known_hosts`
+next to that profile. Obtain it through a trusted administrator/session:
+
+```text
+workspace-server ssh-ed25519 <base64 public key from /etc/ssh/ssh_host_ed25519_key.pub>
+```
+
+The actual known_hosts line has three fields: alias, `ssh-ed25519`, and the base64 key. Never distribute
+`ssh_host_ed25519_key` (the private key). [Site instructions](../site/README.md) cover profiles and updates.
+The supplied `site/beyondwork/` profile is an explicit choice for the existing team server, not a default.
+
+On each Mac or Linux desktop, install from npm (members of the `@vibelord` npm organization; Node.js 18+):
+
+```sh
+npm login                                   # once per machine, or a read-only token in ~/.npmrc
+npx @vibelord/lanes --site beyondwork       # bundled team profile; or --site /path/to/site.conf
+```
+
+The package runs this same installer with the same options and exit codes; see
+[`npm/lanes/README.md`](../../npm/lanes/README.md). From a checkout instead:
+
+```sh
+git clone https://github.com/bwllaming/bw-tools.git
+cd bw-tools/lanes
+./install.sh --site /path/to/site.conf
+```
+
+OpenSSH is required. Install Ghostty for a dedicated window, or run `lanes-launch` in your existing terminal.
+Linux also supports Foot, plus optional Omarchy/Hyprland shortcuts. Tailscale is required when your profile uses
+a tailnet address. The installer installs its own configuration; your normal terminal remains usable.
+
+Authorize the printed public key in the server account's `~/.ssh/authorized_keys`. The client never edits that
+file remotely. Then `./install.sh --check` and `lanes-window`. Useful options:
+
+- `--device NAME`: independent view name; a stable per-machine name is the default.
+- `--key PATH`: choose an existing SSH private key; the key stays on the client.
+- `--no-desktop` / `--no-uploads`: omit those integrations.
+- `--link`: develop against the checkout instead of installing a client copy.
+- `--yes`: noninteractive installation; a newly created dedicated key has no passphrase.
+
+The site selection is saved in `~/.config/lanes/client-site.conf`. Subsequent installs and checks can omit `--site`.
+On macOS, the signed Lanes Helper app requests access to protected folders. Allow Downloads/Desktop/Documents
+as needed. The allowlist is separate from macOS permission; inspect it with `lanes-upload --allowed`.
+
+## 4. Optional Safari / Home Screen access
+
+Install Caddy and Tailscale on the server and enable Tailscale HTTPS for its tailnet. The web services use
+loopback ports **8082** (native Zellij) and **8083** (Lanes frontend); private HTTPS uses **8443**.
+Reserve those ports for Lanes on this host. Caddy runs as a separate user service with its admin API disabled.
+
+Once, a server administrator allows the workspace account to manage Tailscale Serve:
+
+```sh
+sudo sh sudo/one-time-root.sh --user workspace
+```
+
+This does not change SSH daemon settings unless `--ssh-keepalive` is explicitly supplied. Then, in your own
+interactive terminal, either run on the server:
+
+```sh
+sh install/enable-phone.sh --local
+```
+
+or run from an installed Mac/Linux client:
+
+```sh
+sh install/enable-phone.sh --host lanes
+```
+
+The remote path uses the installed checkout shortcut and the SSH key selected by the client installer;
+there is no password fallback or agent forwarding. It enables the services, prepares a separate `phone` view,
+starts private Tailscale Serve and prints a fresh token. Existing tokens remain valid.
+
+Connect Tailscale on the phone, open the printed URL in Safari, paste only the token value, then
+**Share → Add to Home Screen**. A token grants terminal access as the server account. Revoke a named token with:
+
+```sh
+~/.local/share/lanes/bin/zellij-0.45.1 web --revoke-token NAME
+```
+
+`sh install/enable-web.sh` starts only the loopback services and prints no token. The frontend and services
+run on the workspace host; a Mac does not need to stay awake for the phone to work.
+
+## 5. Updates, optional operations and removal
+
+A server installed with `npx @vibelord/lanes --server` runs from the staged tree `~/.local/share/lanes/pkg/<version>/`; updating is `npx @vibelord/lanes@latest --server`, and the previous versions a service may still run from are kept.
+
+Keep the server checkout at a stable location. To move it, run `./install.sh --server` from the new location:
+service definitions and `~/.local/share/lanes/current` are regenerated. Existing workspace configuration is preserved.
+Services get the explicit `LANES_SHARE` and `LANES_STATE` paths supplied at installation, or the defaults below;
+use the same overrides when reinstalling. `LANES_WORKSPACES` is also carried into the generated user services
+when supplied; the standard configuration directory is the simplest default.
+
+After updating server code, restart the status observer with `systemctl --user restart lanes-statusd.service`.
+If web service definitions or the pinned Zellij binary changed, restart `lanes-web` and `lanes-mobile` too;
+browser clients reconnect. Existing Zellij view sessions use their original layout until explicitly rebuilt.
+`lanes rebuild DEVICE` replaces only that device's view, never the underlying agent sessions.
+
+Normal paths:
+
+| Path | Contents |
+| --- | --- |
+| `~/.config/lanes/` | Site profile, client settings and server workspace configuration |
+| `~/.local/share/lanes/` | Client copy, pinned binaries, download cache, installed checkout link and npm-staged trees (`pkg/<version>/`) |
+| `~/.local/state/lanes/` | Host registry, device selections, status, upload handoff and housekeeping projections |
+| `~/.local/state/lanes-client/` | Client helper heartbeat and logs |
+| `/home/coder/.lz/` in each container | Lane helper, bindings and optional zmx metadata |
+
+`lanes pressure`, `lanes sockets check` and `lanes tmp plan` are inspection tools. Review
+[the runbook](RUNBOOK.md) before applying cleanup/repair; read [host protection](HOST-GUARD.md) before enabling
+its root guard. These operations are included in the package but are not an install-time requirement.
+
+Clients uninstall with `./install.sh --uninstall`; SSH keys, `~/Lanes Uploads`, and any server workspace
+configuration and state on the same account are kept.
+To stop the host services, disable `lanes-statusd.service`, `lanes-sync.timer`, `lanes-ensure.timer`,
+`lanes-gc.timer`, and any optional units you enabled. For the web endpoint, also run
+`tailscale serve --https=8443 off`. Keep the state and container lane data until you have decided which
+sessions to retain; no broad deletion command is part of uninstall.