@vibelord/lanes 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibelord/lanes",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Installer for Lanes: shared agent terminals over SSH with Zellij views, registry sync, uploads and a phone interface.",
   "license": "MIT",
   "type": "module",

package/payload/lanes/README.md

@@ -51,6 +51,12 @@ profile). Ghostty is recommended for a separate window; `lanes-launch` works in
 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.
 
+When an ended view was rebuilt on the server, the client probes that state and reconnects
+automatically. The probe's watchdog cancels and reaps its timer when the probe completes;
+a hung probe still times out. This avoids waiting for the watchdog's full ten seconds
+after a successful response. Existing installations receive the fix by re-running the
+client installer after updating their checkout.
+
 **Setting up a server:** on a Linux x86_64 Docker host, as the workspace account:
 
 ```sh
@@ -70,20 +76,35 @@ The installer starts an empty catalog safely; it does not assume anyone's contai
 | 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 |
+| Next or previous lane | Ctrl–Alt–Down / Up (the focused pane moves to the next / previous lane of its workspace; nothing is typed, the focus stays), or tap the sidebar |
+| Plain-ASCII glyphs, light or dark tokens | `lanes-window --ascii`, `lanes-window --light` / `--dark` (remembered per device in `devices/<device>.json`; a running sidebar picks it up within one tick) |
+| Lock the view (every key reaches the lane) | Ctrl–Alt–G, again to unlock; the bar shows LOCKED in red. Ctrl–G itself always reaches the lane (Claude Code's editor key) |
 | 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>` |
+| Read a markdown file a lane mentioned | Ctrl–Alt–M opens a floating **Preview** pane over the focused lane: the `.md` paths it printed in its last 300 lines that exist in its container (relative ones resolved against its working directory). One is shown at once; several give a numbered menu, newest first (Enter = the newest, `q` closes). Rendered by `glow` in the view's dark/light theme (the server installer adds a pinned glow unless the view server's PATH — `~/.local/share/lanes/bin`, the checkout's `bin`, `/usr/local/bin`, `/usr/bin`, `/bin` — already has one; a glow only in `~/.local/bin` or `~/go/bin` does not count), else `less -R`; `lanes doctor` names which (`preview renderer:`); quitting the pager closes the pane |
+| Create a persistent workspace shell | **+ New shell** under **Unregistered** (**New +** on the phone), or `+` in the sidebar |
+| Register an existing session | **+** beside an unregistered session, or select it and press `a`; choose a workspace |
+| See which agents need you | The sidebar sorts **Needs you** (◆ approval, ✗ error, ◇ waiting for a prompt), **Working** (▸) and **Done** (✓, until you open the lane) above the rest; the header counts them in the same glyphs (`◆1 ◇2 ▸6 ✓1`, zeros left out; `N lanes` when no lane runs an agent) |
+| Read a sidebar row | `▌` cursor · agent glyph · `›` the lane this pane shows (`²`/`³`: shown in pane 2/3) · the name (`·` per other viewer, `…` when clipped) · an **age column** on every row (agent turn, else last output: `45s`, ` 3m`, ` 2h`, ` 4d`; amber in **Needs you**) · stream glyph · one tail cell by priority (`?` not observed right now > `⚠` starving: producing output but no request for over 10 min, or a 429 > `↓` downgraded > `$` mostly paid — the economy cells need the opt-in economy poller; a dim `⚠`/`↓` is a frozen last-known figure, not a live alarm) · `×` close. `⋮ N more` ends a list that continues below |
+| End an unregistered session and its jobs | **×** beside the session, or select it and press `x`; confirm with `y` (any other key cancels) |
+| Every sidebar key | `?` replaces the list with the key sheet until the next key (that key only closes it). The footer legend says ` ⏎ open · / find · x close · ? keys`; prompts share one shape (` › close ‘name’? y/n`, ` › Rename: …█`, ` › Register ‘name’? y/n`) and a filter counts its matches (` /abc · 3 matches`) |
+| Jump to the next lane that needs you | `Tab` / `Shift-Tab` in the sidebar (cycles **Needs you** from the lane the pane shows; the pane title carries the counts and a lane that starts needing you raises one OSC 9 desktop notification — `LANES_NOTIFY=0` silences it) |
+| Other workspaces that need you | The row above the footer rule: ` ◆1 Worlds · ◇2 Code` (blank and absent when none; panes of 18 rows or more) |
+| What the fleet spends | With the opt-in economy poller ([RUNBOOK](docs/RUNBOOK.md#economy-projection-opt-in)) the same row is the fleet economy strip instead: ` $8.5k/16k 53% · F2 S1 · spill 76% · free 3/19` — overflow spend against the daily cap (amber at the alert level), new upstream 429s, this workspace's lanes by model tier (`F` fable, `O` opus, `S` sonnet, `H` haiku, `G` gpt), the pool's spill fraction, free accounts and the next 5 h reset, whole parts dropped from the end to fit; a leading `?` means the figures are frozen — the poller could not reach the daemon, or it stopped (no rewrite for over 3 min) |
+| Upload | Click the one-row upload strip above the footer (` ↑ uploads · click, then drop  (U)`) or press `U`, then drop anywhere on the window; or use `~/Lanes Uploads/<workspace>/`, or `lanes-upload <files>` |
 | Phone setup from a client | `sh install/enable-phone.sh --host lanes` |
+| Laptop or tablet browser view | `lanes web <device> --desktop [--token]` on the server, or `sh install/enable-phone.sh --host lanes --desktop <device>` ([guide](docs/INSTALL.md#laptop-and-tablet-browser)) |
+| Switch workspace or lane in a laptop browser | The **Lanes** chip (top right) opens the workspace and lane pickers |
 | 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.
+session reuses it; closing a view leaves it running. Registered lanes have no **×** control. See the
+[runbook](docs/RUNBOOK.md) for details.
+
+**Add to workspace** keeps the session running and moves it into the selected workspace's registered list.
+The picker offers workspaces using the same container. Registration keeps its name and open views, persists
+across sync/reconnects, and removes its close control. On a phone, tap the **+** and a workspace; no typing is needed.
 
 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
@@ -93,6 +114,21 @@ On macOS, allow **Lanes Helper** to read Downloads/Desktop/Documents when prompt
 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.
 
+### Legend
+
+Column 2 of every row says what the agent needs; column 33 says what the terminal is doing; the right edge says how
+long (agent since-time, or last output). Glyph then ASCII twin (`LANES_GLYPHS=ascii`):
+
+| Agent (column 2) | | Terminal (column 33) | | Marks |
+| --- | --- | --- | --- | --- |
+| `◆` `!` needs approval | `◇` `?` needs input | `●` `*` output in the last 20 s | `○` `o` quiet | `▌` `\|` cursor · `›` `=` viewing · `²` `2` / `³` `3` shown in viewport 2/3 |
+| `▸` `>` working | `✓` `v` done (until viewed) | `–` `-` no session right now | `!` `!` pane dead | `·` `.` viewers · `…` `~` clipped · `×` `x` close |
+| `✗` `X` errored | `_` `_` shell · `·` `.` idle | `✗` `x` container down | `?` `?` not observed · `·` `.` helper | `⋮` `:` more rows · `↑` `^` uploads · `↓` `v` drop now |
+
+Column 34 is one tail cell: `?` stale (last known state shown) > `⚠` `!` starving > `↓` `v` downgraded > `$` mostly
+paid. Colour is reinforcement, never the only signal; `LANES_COLOR=none` keeps every glyph. Full tables, tokens and
+modes: [`docs/DESIGN.md`](docs/DESIGN.md).
+
 ## Share with your team
 
 Throttle's **Shared lanes** console provides an SSO-protected, read-only overview
@@ -103,10 +139,18 @@ platform/Host version, configuration, access rules and output limits.
 ## Screenshots
 
 **Desktop:** workspace tabs, registered and unregistered lanes, and uploads alongside the active terminal.
+Captured before v2: the v2 sidebar shows attention sections, an agent glyph per row, the age column and a one-row
+upload strip (see [docs/DESIGN.md](docs/DESIGN.md)). It also adds one economy tail cell per lane (column 34: `?` >
+`⚠` > `↓` > `$`) and, with the opt-in economy poller, the fleet economy strip above the footer rule. The image is
+user-supplied and not regenerated.
 
 ![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.
+Captured before v2: the v2 sidebar shows attention sections, an agent glyph per row, the age column and a one-row
+upload strip (see [docs/DESIGN.md](docs/DESIGN.md)). On the phone the picker gives each lane three rows (name,
+status and age, the agent's task) without the upload strip, and view tabs gain the quick-key row; the image is not
+regenerated.
 
 <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">
 
@@ -119,6 +163,8 @@ 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.
+Sessions added through the picker are saved in the site's `registered-sessions.json` and included by sync.
+These registrations attach to existing sessions; they do not invent a restart command or edit editor terminal lists.
 See [workspace configuration](workspaces.example/README.md) and the [architecture](docs/ARCHITECTURE.md).
 
 ## What is included
@@ -150,3 +196,42 @@ 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).
+
+### Register a workspace once
+
+The host's site catalog (`LANES_WORKSPACES/catalog.json`, normally
+`~/.config/lanes/workspaces/catalog.json`) is the workspace authority. Add its
+manifest there and run `lanes sync`. The existing sync timer refreshes it every
+2 minutes; the ensure timer also reconciles known device sessions every minute.
+New desktop and phone tabs appear without rebuilding sessions or restarting
+agents. Changing a catalog title renames the existing tab using its workspace ID.
+Phone workspaces receive both their full-width picker and terminal tabs.
+When a device has no attached client, new tabs wait for its next connection and
+the next ensure tick (within a minute). This avoids empty background tabs in
+Zellij 0.45.1; existing workspace names can still update while disconnected.
+
+Fixed terminals on another host can use an optional `sshWorkspaces` entry:
+
+```json
+{
+  "id": "maintenance",
+  "title": "Maintenance",
+  "host": "maintenance-views",
+  "command": "/home/operator/.local/bin/workspace-session",
+  "layout": "lanes",
+  "position": "workspace",
+  "panes": [{"id": "fixes", "name": "Fixes"}]
+}
+```
+
+Put this object in the catalog's `sshWorkspaces` array. Configure the host SSH
+alias with its dedicated key and pinned host key. The command must attach to an
+existing persistent session. Lanes does not provision or terminate remote agents.
+`layout: "lanes"` uses the standard sidebar; `position: "before-host"` places a
+control workspace immediately before Host. Existing `split` layouts stay supported.
+Split workspaces can share an SSH host and helper when their pane IDs are distinct.
+An endpoint assigned to multiple split workspaces is ambiguous and refuses sync.
+
+While a viewer connects or reconnects, it shows a Syncing indicator and discards
+pending input. Mouse reporting is reset before and after the attach client, so
+queued escape sequences cannot become shell input during the connection wait.

package/payload/lanes/VERSION

@@ -1 +1 @@
-1.0.0
+1.0.2