@vibelord/lanes 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Beyond Work
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @vibelord/lanes
+
+npm distribution of [Lanes](../../lanes/README.md): shared agent terminals over SSH with Zellij workspace views,
+registry sync, uploads and a phone interface. The package carries the committed `lanes/` tree and runs its own
+`install.sh`; every option and exit code of that installer applies unchanged.
+
+The package is **restricted** to the `@vibelord` npm organization.
+
+## Install on a new Mac or Linux machine
+
+Requirements: Node.js 18+ (for npm only), OpenSSH, and a route to the server (Tailscale for the Beyond Work profile).
+
+```sh
+npm login --scope=@vibelord            # once per machine: an @vibelord member account
+npx @vibelord/lanes --site beyondwork  # install or update the client
+lanes-window                           # open the desktop view
+```
+
+Instead of `npm login`, a machine can use a **read-only** npm token (npmjs.com → Access Tokens → Granular,
+read-only, scoped to `@vibelord/lanes`):
+
+```sh
+printf '//registry.npmjs.org/:_authToken=%s\n' "$LANES_READ_TOKEN" >> ~/.npmrc
+```
+
+Never put the organization's publish token on an installing machine.
+
+Exit status is the installer's: `0` ready · `3` installed, but this machine's SSH key is not yet authorized on
+the server (send the printed **public** key to the admin, then run `npx @vibelord/lanes --check`) · `4` installed,
+but the server is unreachable (Tailscale?) · `1` error.
+
+Other sites pass their own profile: `npx @vibelord/lanes --site /path/to/site.conf`.
+
+## Server
+
+On the Linux x86_64 workspace host, as the workspace account:
+
+```sh
+npx @vibelord/lanes --server --check
+npx @vibelord/lanes --server
+```
+
+## What the wrapper does
+
+`lanes-install` copies the bundled tree to `~/.local/share/lanes/pkg/<version>/` (`$LANES_PKG_ROOT` overrides the
+parent) and runs `install.sh` from there. The server's systemd user units and `~/.local/share/lanes/current` name
+that stable path, never the npx cache. An identical tree is reused; the newest three versions and any version the
+server still runs from are kept.
+
+| Option | Effect |
+| --- | --- |
+| `--site NAME` | a bundled profile (`beyondwork`); a value with `/` or `.conf` is your own file |
+| `--stage-only` | stage the tree and print its path, run nothing |
+| `--version` | print the package version |
+| `--wrapper-help` | wrapper help only |
+
+Update: re-run `npx @vibelord/lanes@latest` with the same options. Remove the client: `npx @vibelord/lanes --uninstall`.
+
+## Maintainers
+
+The package version equals `lanes/VERSION`; bump both together. `prepack` builds `payload/` from `git ls-files lanes`
+(tests excluded) and refuses uncommitted `lanes/` changes.
+
+```sh
+cd npm/lanes && npm test
+scripts/publish.sh --dry-run    # then without --dry-run
+```
+
+`publish.sh` reads the publish token from the main checkout's `.env.local` (`NPMJS2` by default; override with
+`LANES_NPM_ENV_FILE` / `LANES_NPM_TOKEN_KEY`) and hands it to npm through the environment only.

package/bin/lanes-install.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+
+// npm transport for the Lanes installer.
+//
+// The package carries the committed `lanes/` tree (payload/lanes) plus a manifest written at pack time. This
+// wrapper copies that tree to a STABLE, versioned directory and runs its own `install.sh` from there:
+//
+//   ~/.local/share/lanes/pkg/<version>/     (or $LANES_PKG_ROOT/<version>)
+//
+// A stable path matters for the server: `install/services.py` writes the resolved checkout path into the
+// systemd user units and links ~/.local/share/lanes/current to it, so the tree must outlive the npx cache.
+// Clients copy their commands out of the tree, so for them the location is incidental.
+//
+// Nothing here touches SSH, keys or services itself — install.sh keeps that authority, its options and its
+// exit codes (0 ready · 3 key not yet authorized · 4 server unreachable · 1 error).
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { installArgs, platformError, prunable, splitArgs } from '../lib/plan.mjs';
+
+const packageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const payload = path.join(packageDir, 'payload');
+const STAMP = '.lanes-package.json';
+
+function fail(message, code = 1) {
+  process.stderr.write(`lanes-install: ${message}\n`);
+  process.exit(code);
+}
+
+function readManifest() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(payload, 'manifest.json'), 'utf8'));
+  } catch (error) {
+    fail(`this package has no payload (${error.code || error.message}); reinstall @vibelord/lanes`);
+  }
+  return null;
+}
+
+function pkgRoot() {
+  if (process.env.LANES_PKG_ROOT) return path.resolve(process.env.LANES_PKG_ROOT);
+  const data = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local/share');
+  return path.join(data, 'lanes', 'pkg');
+}
+
+function stampOf(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, STAMP), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Copy payload/lanes to <root>/<version> atomically; an identical tree (same digest) is reused as is.
+function stage(manifest) {
+  const root = pkgRoot();
+  const target = path.join(root, manifest.version);
+  if (stampOf(target)?.digest === manifest.digest) return target;
+  fs.mkdirSync(root, { recursive: true, mode: 0o755 });
+  const staging = fs.mkdtempSync(path.join(root, `.staging-${manifest.version}-`));
+  try {
+    fs.cpSync(path.join(payload, 'lanes'), staging, { recursive: true });
+    // npm does not promise to keep executable bits inside a tarball: the manifest does.
+    for (const file of manifest.executables) fs.chmodSync(path.join(staging, file), 0o755);
+    fs.chmodSync(staging, 0o755);
+    fs.writeFileSync(path.join(staging, STAMP), `${JSON.stringify({
+      name: manifest.name, version: manifest.version, digest: manifest.digest, commit: manifest.commit,
+      staged_at: new Date().toISOString(),
+    }, null, 1)}\n`);
+    if (fs.existsSync(target)) {
+      // Same version, different bytes (a local rebuild): move the old tree aside, never write into it.
+      const aside = `${target}.replaced-${process.pid}`;
+      fs.renameSync(target, aside);
+      fs.renameSync(staging, target);
+      fs.rmSync(aside, { recursive: true, force: true });
+    } else {
+      fs.renameSync(staging, target);
+    }
+  } catch (error) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+  prune(root, target);
+  return target;
+}
+
+function prune(root, target) {
+  const inUse = new Set([target]);
+  const data = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local/share');
+  try {
+    inUse.add(fs.realpathSync(path.join(data, 'lanes', 'current')));   // what the server units point at
+  } catch { /* no server install */ }
+  const entries = [];
+  for (const name of fs.readdirSync(root)) {
+    const dir = path.join(root, name);
+    if (name.startsWith('.') || !stampOf(dir)) continue;   // only trees this wrapper staged
+    entries.push({ path: dir, mtimeMs: fs.statSync(dir).mtimeMs });
+  }
+  for (const dir of prunable(entries, inUse)) fs.rmSync(dir, { recursive: true, force: true });
+}
+
+function usage(manifest) {
+  process.stdout.write(`@vibelord/lanes ${manifest.version} — installs Lanes from this package
+
+  npx @vibelord/lanes --site beyondwork        install or update the client (macOS / Linux)
+  npx @vibelord/lanes --check                  verify SSH path, key and server; changes nothing
+  npx @vibelord/lanes --server                 install or update the Linux workspace server
+  npx @vibelord/lanes --uninstall              remove what the client installer added
+
+Wrapper options
+  --stage-only     copy the bundled tree to ${path.join(pkgRoot(), manifest.version)} and print its path
+  --version        print the package version
+  --wrapper-help   this text
+
+Bundled site profiles: ${manifest.sites.join(', ') || 'none'} (or --site /path/to/site.conf)
+Every other option goes to install.sh; its own help follows.
+
+`);
+}
+
+function main() {
+  const platform = platformError(process.platform);
+  if (platform) fail(platform);
+  const manifest = readManifest();
+  const { own, passthrough } = splitArgs(process.argv.slice(2));
+  if (own.has('--version')) {
+    process.stdout.write(`${manifest.version}\n`);
+    return 0;
+  }
+  let staged;
+  try {
+    staged = stage(manifest);
+  } catch (error) {
+    fail(`could not stage the Lanes tree under ${pkgRoot()}: ${error.message}`);
+  }
+  if (own.has('--stage-only')) {
+    process.stdout.write(`${staged}\n`);
+    return 0;
+  }
+  const help = own.has('--wrapper-help') || passthrough.includes('--help') || passthrough.includes('-h');
+  if (help) usage(manifest);
+  if (own.has('--wrapper-help')) return 0;
+  let args;
+  try {
+    args = installArgs(passthrough, staged, manifest.sites);
+  } catch (error) {
+    fail(error.message);
+  }
+  // Run through the staged path (not the npx cache), so install.sh resolves its checkout to the stable tree.
+  const result = spawnSync('sh', [path.join(staged, 'install.sh'), ...args], { stdio: 'inherit', cwd: staged });
+  if (result.error) fail(`could not run install.sh: ${result.error.message}`);
+  return result.status ?? 1;
+}
+
+process.exit(main());

package/lib/plan.mjs

@@ -0,0 +1,65 @@
+// Pure helpers for the `lanes-install` wrapper, kept apart from the filesystem so they are unit-testable.
+//
+// The wrapper never re-implements the installer: it stages the bundled `lanes/` tree at a stable path and runs
+// that tree's own `install.sh`. These functions decide only the platform gate, the wrapper's own flags and how
+// the passthrough arguments are rewritten.
+
+export const SUPPORTED_PLATFORMS = ['darwin', 'linux'];
+
+export function platformError(platform) {
+  return SUPPORTED_PLATFORMS.includes(platform)
+    ? null
+    : `lanes supports macOS and Linux only (this is ${platform}); on Windows use WSL`;
+}
+
+// Wrapper-owned flags. Everything else is passed to install.sh unchanged.
+const OWN_FLAGS = new Set(['--stage-only', '--version', '--wrapper-help']);
+
+export function splitArgs(argv) {
+  const own = new Set();
+  const passthrough = [];
+  for (const arg of argv) {
+    if (OWN_FLAGS.has(arg)) own.add(arg);
+    else passthrough.push(arg);
+  }
+  return { own, passthrough };
+}
+
+// Rewrite install.sh arguments for a staged tree:
+//   * `--site NAME` names a profile bundled under lanes/site/NAME/ (a value with a `/` or ending in `.conf` stays a
+//     path the user owns);
+//   * `--server` must be install.sh's FIRST argument (it dispatches on $1 only).
+export function installArgs(passthrough, stagedDir, sites) {
+  const out = [];
+  let server = false;
+  for (let i = 0; i < passthrough.length; i += 1) {
+    const arg = passthrough[i];
+    if (arg === '--server') {
+      server = true;
+      continue;
+    }
+    if (arg === '--site' && i + 1 < passthrough.length) {
+      out.push(arg, resolveSite(passthrough[i + 1], stagedDir, sites));
+      i += 1;
+      continue;
+    }
+    out.push(arg);
+  }
+  return server ? ['--server', ...out] : out;
+}
+
+export function resolveSite(value, stagedDir, sites) {
+  if (value.includes('/') || value.endsWith('.conf')) return value;
+  if (!sites.includes(value)) {
+    const known = sites.length ? sites.join(', ') : 'none';
+    throw new Error(`unknown site profile '${value}' (bundled: ${known}); or pass --site /path/to/site.conf`);
+  }
+  return `${stagedDir}/site/${value}/site.conf`;
+}
+
+// Which staged version directories to delete: keep the newest `keep` (by mtime) and anything still in use.
+// Server user units name the resolved staged path, so a version a running service came from is kept.
+export function prunable(entries, inUse, keep = 3) {
+  const sorted = [...entries].sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return sorted.slice(keep).filter((entry) => !inUse.has(entry.path)).map((entry) => entry.path);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@vibelord/lanes",
+  "version": "1.0.0",
+  "description": "Installer for Lanes: shared agent terminals over SSH with Zellij views, registry sync, uploads and a phone interface.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "lanes-install": "bin/lanes-install.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "payload/",
+    "README.md",
+    "LICENSE"
+  ],
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build-payload.mjs",
+    "prepack": "node scripts/build-payload.mjs",
+    "test": "node --test"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bwllaming/bw-tools.git",
+    "directory": "npm/lanes"
+  }
+}

package/payload/lanes/README.md

@@ -0,0 +1,152 @@
+# Lanes
+
+One setup for shared agent terminals: Zellij panes and workspace tabs, live lane status, registry sync,
+Cursor / VS Code integration, uploads, desktop launchers, and a phone interface. The complete implementation
+and its tests live in this folder.
+
+Each device gets its own view of the same long-running terminals. Closing a view or losing a connection
+leaves those terminals running in their workspace containers.
+
+```text
+Mac / Linux terminal ── SSH ───────┐
+                                 ├─ Linux workspace host ── container tmux sessions
+Safari / Home Screen ── HTTPS ────┘      Zellij views            agent lanes
+                                       registry + status
+```
+
+## Quick start
+
+**New Mac or Linux machine, from npm** (members of the `@vibelord` npm organization; Node.js 18+ for npm only):
+
+```sh
+npm login                                 # once per machine
+npx @vibelord/lanes --site beyondwork     # install or update; no clone needed
+lanes-window
+```
+
+The package runs the same installer with the same options and exit codes; see [`npm/lanes`](../npm/lanes/README.md).
+
+**From a checkout:** clone the repository once on each machine that needs it:
+
+```sh
+git clone https://github.com/bwllaming/bw-tools.git
+cd bw-tools/lanes
+```
+
+**Joining an existing server:** get its site file and public host key from the administrator, then run:
+
+```sh
+./install.sh --site /path/to/site.conf
+lanes-window
+```
+
+Beyond Work's existing deployment has an explicit profile:
+
+```sh
+./install.sh --site site/beyondwork/site.conf
+```
+
+The client works on macOS and Linux. It needs OpenSSH and a route to the server (Tailscale for the supplied
+profile). Ghostty is recommended for a separate window; `lanes-launch` works in an existing terminal.
+The installer uses an existing SSH key or creates a dedicated one. An administrator authorizes its **public**
+key on the server. Re-run `./install.sh --check` after authorization. Your selected site is remembered.
+
+**Setting up a server:** on a Linux x86_64 Docker host, as the workspace account:
+
+```sh
+./install.sh --server --check
+./install.sh --server
+```
+
+Then configure the workspace catalog and install the container helper. Follow the
+[installation guide](docs/INSTALL.md) for prerequisites, a complete example, phone access, upgrades and removal.
+The installer starts an empty catalog safely; it does not assume anyone's containers, projects or login name.
+
+## Daily use
+
+| Action | Command or control |
+| --- | --- |
+| Open desktop view | `lanes-window` or the Lanes app; `lanes-launch` inside any terminal |
+| Independent second view | `lanes-window 2` |
+| Two or three panes per workspace | `lanes-window w2` / `lanes-window w3` |
+| Switch workspace | Ctrl–Alt–Left / Right |
+| Next or previous lane | Ctrl–Alt–Down / Up, or tap the sidebar |
+| Search lanes | Ctrl–Alt–/ |
+| Select a lane for pane 2 or 3 | `2` / `3` in the sidebar of a wide view |
+| Open one lane directly | `lanes-launch lane <lane-id>`; find IDs with `lanes-launch ls` |
+| Create a persistent workspace shell | **New +** under **Unregistered**, or `+` in the sidebar |
+| End an unregistered session and its jobs | **×** beside the session, or select it and press `x` |
+| Upload | Drop onto the sidebar upload box, use `~/Lanes Uploads/<workspace>/`, or `lanes-upload <files>` |
+| Phone setup from a client | `sh install/enable-phone.sh --host lanes` |
+| Detach | Close the window; the agents keep running |
+
+Unregistered sessions also appear when they use shared or previously unlisted tmux servers. Reopening a
+session reuses it; closing a view leaves it running. Registered lanes have no **×** control. Older plain
+Docker shells labelled **Legacy** are tracked and closable, but a lost Docker connection cannot be reopened;
+new shells support reconnection. See the [runbook](docs/RUNBOOK.md) for the transition details.
+
+On iPhone, open the printed private HTTPS URL in Safari and choose **Share → Add to Home Screen**.
+The interface provides Workspaces, Lanes and Panes controls, safe areas, portrait/landscape layout and adjustable
+terminal text. The keyboard opens when you tap **Type here** or another input; swipes and updates leave it closed.
+
+On macOS, allow **Lanes Helper** to read Downloads/Desktop/Documents when prompted. Upload progress and original
+errors are retained; an active large transfer is not cut off by a total-duration timeout. Files are read only
+from allowed folders and land in the selected workspace's `uploads/` directory.
+
+## Share with your team
+
+Throttle's **Shared lanes** console provides an SSO-protected, read-only overview
+of selected workspaces. Admins enable publishers by user or team; owners select
+workspaces and recipients. See [sharing setup](docs/SHARING.md) for the required
+platform/Host version, configuration, access rules and output limits.
+
+## Screenshots
+
+**Desktop:** workspace tabs, registered and unregistered lanes, and uploads alongside the active terminal.
+
+![Lanes desktop workspace with a lane sidebar, unregistered sessions, upload box, and workspace tabs](docs/images/desktop.png)
+
+**iPhone in Safari:** the lane picker and touch controls for workspaces, panes, and explicit text input.
+
+<img src="docs/images/iphone.png" alt="Lanes on iPhone in Safari, showing the lane picker and Workspaces, Lanes, Panes, and Type here controls" width="360">
+
+## How sync works
+
+The workspace catalog says which repositories belong to each tab. `lanes sync` reads their
+`.vscode/terminals.json` files every two minutes and publishes the host registry and container bindings.
+It retains the previous lanes if a repository's registry is temporarily invalid.
+
+`lanes cursor-sync --diff` previews editor integration. `lanes cursor-sync --write` backs up and normalizes
+terminal commands to `lane open <id>`, retaining each original create recipe. Cursor and Lanes then attach
+to the same terminal. Registry sync does not copy repositories between machines or automatically create agents.
+See [workspace configuration](workspaces.example/README.md) and the [architecture](docs/ARCHITECTURE.md).
+
+## What is included
+
+| Folder | Responsibility |
+| --- | --- |
+| `install.sh`, `install/` | Client/server installation, service registration and web setup |
+| `client/` | Reconnecting SSH launcher, windows, upload helper, macOS apps and Omarchy integration |
+| `bin/`, `libexec/` | Registry/editor sync, layouts, sidebar, status, uploads, health and housekeeping |
+| `holders/`, `container/` | Guarded attachment and the in-container `lane` contract |
+| `zellij/`, `systemd/` | Keybindings, device views and user-service templates |
+| `web/` | Responsive Safari frontend over the pinned native Zellij client |
+| `site/`, `workspaces.example/` | Deployment profiles and editable configuration examples |
+| `sudo/` | Optional administrator setup and host protection, applied explicitly |
+| `tests/` | Unit tests plus isolated host/container integration suites |
+| `docs/` | [Install](docs/INSTALL.md), [architecture](docs/ARCHITECTURE.md), [operations](docs/RUNBOOK.md), [host guard](docs/HOST-GUARD.md) |
+
+## Update and verify
+
+After `git pull`, clients re-run `./install.sh`; servers re-run `./install.sh --server` from their installed
+checkout. The server installer resolves the checkout's actual path, including `bw-tools/lanes`; no `~/lanes`
+clone is required. It preserves configured workspaces and existing agent sessions.
+
+```sh
+./install.sh --check                       # client connectivity
+./install.sh --server --check              # server prerequisites
+python3 -m unittest discover -s tests/unit # no Docker or live server needed
+```
+
+For integration tests and browser verification, see [tests/README.md](tests/README.md).
+For recovery, service updates and troubleshooting, see the [runbook](docs/RUNBOOK.md).

package/payload/lanes/VERSION

@@ -0,0 +1 @@
+1.0.0