@vibelord/lanes 1.0.1 → 1.0.3

package/payload/lanes/libexec/tokens.py

@@ -1,7 +1,8 @@
 #!/usr/bin/env python3
-"""The Lanes design tokens: ONE table, rendered four ways. The sidebar imports `sgr_table`; `--kdl`, `--css`, `--sh`
-and `--md` write the Zellij theme, the phone CSS, the viewer's shell variables and the docs table between markers;
-`--check` fails when any committed block differs. Spec: docs/superpowers/specs/2026-10-03-lanes-cockpit-design.md.
+"""The Lanes design tokens: ONE table, rendered seven ways. The sidebar imports `sgr_table`; `--kdl`, `--css`, `--sh`,
+`--md`, `--js` and `--ghostty-dark|--ghostty-light` write the Zellij theme, the phone CSS, the viewer's shell variables,
+the docs table, the phone's terminal palette and the optional Ghostty palette files between markers; `--check` fails
+when any committed block differs. Spec: docs/superpowers/specs/2026-10-03-lanes-cockpit-design.md.
 No third-party code; importable with no side effects."""
 import difflib
 import os
@@ -215,10 +216,40 @@ def render_md():
     return '\n'.join(rows) + '\n'
 
 
-RENDERERS = {'kdl': render_kdl, 'css': render_css, 'sh': render_sh, 'md': render_md}
-TARGETS = {'kdl': 'zellij/config.kdl', 'css': 'web/mobile.css', 'sh': 'libexec/tokens.sh', 'md': 'docs/DESIGN.md'}
+def render_js():
+    """The phone's xterm.js slots for BOTH variants. Zellij's web_client.theme is one server-wide (dark) palette that
+    arrives in the HTTP boot config and that SetConfig re-sends on every config reload, assigned wholesale; mobile.js
+    applies these on attach and re-applies them after each SetConfig (spec §6.3; DEF-1413). 495 B against mobile.js's
+    3072 B allowance (measured 2026-10-04)."""
+    body = ', '.join(f"{v}: [{', '.join(repr(c) for c in PALETTE16[v])}]" for v in ('dark', 'light'))
+    return ('// BEGIN lanes tokens (generated by libexec/tokens.py --js; do not edit by hand)\n'
+            f'  const LANES_ANSI = {{{body}}};\n  // END lanes tokens\n')
+
+
+def render_ghostty(variant):
+    """The optional Ghostty palette (spec §7; `install.sh --client --palette`): colours only — never font, theme,
+    padding or cursor style, the everyday config keeps those. Valid both as an included config file and as a Ghostty
+    theme file, so install.sh can include the dark one directly or pair both through `theme = light:…,dark:…`."""
+    t, p = TOKENS[variant], PALETTE16[variant]
+    lines = [f'# BEGIN lanes tokens (generated by libexec/tokens.py --ghostty-{variant}; do not edit by hand)',
+             '# Optional: the cockpit palette regardless of your everyday Ghostty theme (install.sh --client --palette).',
+             '# Slots 1-4 are the four tones, so 16-colour mode here equals truecolor mode. No font, padding or cursor keys.',
+             f'background = {t["surface"]}', f'foreground = {t["ink"]}', f'cursor-color = {t["accent"]}',
+             f'selection-background = {t["line"]}', f'selection-foreground = {t["ink"]}']
+    lines += [f'palette = {i}={c}' for i, c in enumerate(p)]
+    lines.append('# END lanes tokens')
+    return '\n'.join(lines) + '\n'
+
+
+RENDERERS = {'kdl': render_kdl, 'css': render_css, 'sh': render_sh, 'md': render_md, 'js': render_js,
+             'ghostty-dark': lambda: render_ghostty('dark'), 'ghostty-light': lambda: render_ghostty('light')}
+TARGETS = {'kdl': 'zellij/config.kdl', 'css': 'web/mobile.css', 'sh': 'libexec/tokens.sh', 'md': 'docs/DESIGN.md',
+           'js': 'web/mobile.js', 'ghostty-dark': 'client/ghostty/lanes-palette.conf',
+           'ghostty-light': 'client/ghostty/lanes-palette-light.conf'}
 MARKERS = {'kdl': ('// BEGIN lanes tokens', '// END lanes tokens'), 'css': ('/* BEGIN lanes tokens', '/* END lanes tokens */'),
-           'sh': ('# BEGIN lanes tokens', '# END lanes tokens'), 'md': ('<!-- BEGIN lanes tokens', '<!-- END lanes tokens -->')}
+           'sh': ('# BEGIN lanes tokens', '# END lanes tokens'), 'md': ('<!-- BEGIN lanes tokens', '<!-- END lanes tokens -->'),
+           'js': ('// BEGIN lanes tokens', '// END lanes tokens'),
+           'ghostty-dark': ('# BEGIN lanes tokens', '# END lanes tokens'), 'ghostty-light': ('# BEGIN lanes tokens', '# END lanes tokens')}
 
 
 def render(kind):
@@ -270,7 +301,7 @@ def main(argv):
         return 0
     kind = argv[0].lstrip('-') if argv else ''
     if kind not in RENDERERS:
-        sys.exit('usage: tokens.py --kdl|--css|--sh|--md|--check|--write')
+        sys.exit('usage: tokens.py --kdl|--css|--sh|--md|--js|--ghostty-dark|--ghostty-light|--check|--write')
     sys.stdout.write(render(kind))
     return 0
 

package/payload/lanes/libexec/view.sh

@@ -58,12 +58,22 @@ reset_terminal() {
     printf '\033[?1049l\033[?1000l\033[?1002l\033[?1003l\033[?1006l\033[?2004l\033[<u\033[0m\033[?25h\033[2J\033[3J\033[H'
 }
 
+# The 16-colour SGR literals of the design tokens (libexec/tokens.py --sh): sourced once, printf only, no fork.
+# They hold `\033[…m` as text, so they go into printf's FORMAT (which turns `\033` into ESC), never into a %s argument.
+# shellcheck source=libexec/tokens.sh
+. "$repo/libexec/tokens.sh"
+
 # status_screen <title> <text> <dim line> [<lead>]: a lead, when given, is the bold headline above the title.
+# The lead glyph follows the sidebar's published glyph mode ($STATE/clients/<device>.glyphs, written by sidebar.py from
+# devices/<device>.json) and is read on EVERY call with the builtin read, no fork: this runs exactly when the host may be
+# too slow for one, and `lanes attach DEVICE --ascii` against a live session must reach the next screen without a restart.
 status_screen() {
     reset_terminal
-    if [ -n "${4:-}" ]; then printf '\n  \033[1m%s\033[0m\n\n  %s\n' "$4" "$1"
-    else printf '\n  \033[1m%s\033[0m\n' "$1"; fi
-    printf '\n  %s\n\n  \033[2m%s\033[0m\n' "$2" "$3"
+    glyphs=unicode; { IFS= read -r glyphs < "$state/clients/$device.glyphs"; } 2>/dev/null || :
+    lead_glyph='⚠'; [ "$glyphs" != ascii ] || lead_glyph='!'
+    if [ -n "${4:-}" ]; then printf "\n  ${LZ_BOLD}%s %s${LZ_RESET}\n\n  %s\n" "$lead_glyph" "$4" "$1"
+    else printf "\n  ${LZ_BOLD}%s${LZ_RESET}\n" "$1"; fi
+    printf "\n  %s\n\n  ${LZ_DIM}%s${LZ_RESET}\n" "$2" "$3"
 }
 
 # Is the socket of the lane just shown still there? Then only this VIEWER ended: a lane lives in its holder's server

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

@@ -0,0 +1,20 @@
+[Unit]
+Description=lanes economy projection (opt-in: GETs the Throttle daemon's loopback /status and /sessions, writes economy.json)
+After=lanes-statusd.service
+
+# No installer enables this unit. It reads the production daemon's control port, so switching it on is an operator
+# action: systemctl --user enable --now lanes-economy.service (RUNBOOK "Economy projection (opt-in)").
+# It runs on the HOST, not in the daemon's container: point LANES_THROTTLE_CONTAINER at that container for the log,
+# and use LANES_THROTTLE_CONTROL=none unless the control port is reachable from the host (RUNBOOK, DEF-1525).
+[Service]
+ExecStart=/usr/bin/python3 -S -E "@REPO@/libexec/economy_poll.py" --interval 10
+Restart=on-failure
+RestartSec=10
+Nice=10
+NoNewPrivileges=true
+MemoryHigh=96M
+MemoryMax=192M
+Slice=lanes.slice
+
+[Install]
+WantedBy=default.target

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

@@ -0,0 +1,19 @@
+[Unit]
+Description=lanes push notifications (opt-in: POSTs needs-you transitions from status.json to an ntfy topic)
+After=lanes-statusd.service
+
+# No installer enables this unit. It sends lane names and agent tasks to the ntfy server in
+# ~/.config/lanes/notify.conf (LANES_NOTIFY_CONF), so switching it on is an operator action:
+# systemctl --user enable --now lanes-notify.service (RUNBOOK "Push notifications (opt-in)").
+[Service]
+ExecStart=/usr/bin/python3 -S -E "@REPO@/libexec/notify.py" --interval 3
+Restart=on-failure
+RestartSec=10
+Nice=10
+NoNewPrivileges=true
+MemoryHigh=48M
+MemoryMax=96M
+Slice=lanes.slice
+
+[Install]
+WantedBy=default.target

package/payload/lanes/systemd/lanes-studio-host-enrol.service

@@ -0,0 +1,11 @@
+[Unit]
+Description=lanes: adopt a deploy receipt or registration key for the co-located Studio Host, then start it
+Documentation=https://github.com/bwllaming/bw-tools/blob/main/lanes/docs/SHARING.md
+
+[Service]
+Type=oneshot
+# Acts only on something NEW (an unadopted receipt, a key not tried in the last hour, a fresh enrolment the Host
+# has not started with); otherwise one log line and exit 0. Never restarts a Host that refused the same enrolment.
+ExecStart=/bin/sh "@REPO@/install/enable-studio-host.sh" --retry
+Nice=5
+Slice=lanes.slice

package/payload/lanes/systemd/lanes-studio-host-enrol.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=lanes: retry the co-located Studio Host's enrolment every 5 minutes (opt-in, enabled by enable-studio-host.sh)
+
+[Timer]
+OnActiveSec=1min
+OnUnitActiveSec=5min
+AccuracySec=30s
+
+[Install]
+WantedBy=timers.target

package/payload/lanes/systemd/lanes-studio-host.service

@@ -0,0 +1,37 @@
+[Unit]
+Description=lanes: Throttle Studio Host co-located on this lanes server (opt-in: install/enable-studio-host.sh)
+Documentation=https://github.com/bwllaming/bw-tools/blob/main/lanes/docs/SHARING.md
+# The Host reads the harness's status.json; it starts after the observer and asks for it, but does not die with it.
+After=lanes-statusd.service
+Wants=lanes-statusd.service
+
+[Service]
+Type=simple
+# The binary is the installer-selected, sha256-verified link (`lanes studio-host install`, holders.lock).
+# The config the installer wrote, in lanes-server mode (design §8.10 C2): %h/.config/…, or under $XDG_CONFIG_HOME
+# when the installing account set one. services.py ALWAYS pins XDG_CONFIG_HOME/XDG_DATA_HOME above (the installer's,
+# else %h/.config and %h/.local/share), so the user manager's own environment never moves the credential.
+ExecStart="@THROTTLE_RC@" studio host --config "@STUDIO_HOST_CONFIG@"
+Restart=on-failure
+# 2 s growing to 60 s, as `throttle-rc studio service` renders it. RestartSteps=/RestartMaxDelaySec= need
+# systemd 254; an older manager ignores them with a warning, keeps RestartSec=2, and its start limit stops a loop.
+RestartSec=2
+RestartSteps=5
+RestartMaxDelaySec=60
+# Exit 3 is the Host's TYPED refusal (not enrolled yet, revoked, another Host holds the lock). Restarting into it
+# fixes nothing, so it is a clean stop. Waiting for enrolment is exactly this state: lanes-studio-host-enrol.timer
+# starts the unit again once a deploy receipt or a registration key has enrolled the machine.
+SuccessExitStatus=3
+# The Host's graceful stop (detach every channel, then `stopped`) runs on SIGINT.
+KillSignal=SIGINT
+# The Host only, never the cgroup: tmux clients it attached stay with their lanes; it reaps its own on a clean stop.
+KillMode=process
+TimeoutStopSec=20
+# Deliberately no NoNewPrivileges= (design §8.9): it is inherited for life by anything the Host's children start.
+Nice=5
+MemoryHigh=512M
+MemoryMax=1G
+Slice=lanes.slice
+
+[Install]
+WantedBy=default.target

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

@@ -4,6 +4,9 @@ Description=lanes registry sync (read-only: rebuild registry.json from the repos
 [Service]
 Type=oneshot
 ExecStart="@REPO@/bin/lanes" sync
+# Bounded: one `docker inspect` (20 s) plus the registry reads. A sync wedged on a hung docker or volume is
+# stopped here instead of holding the oneshot (and every later timer tick) forever.
+TimeoutStartSec=120
 # A momentarily invalid registry keeps the previous lanes; a non-zero exit here is informational.
 SuccessExitStatus=1
 Nice=5

package/payload/lanes/web/README.md

@@ -11,8 +11,9 @@ workspace sheet as a left panel, and set `zellij:mobile-ui` to `on` when it is u
 user agent). Desktop browsers (fine pointer) get only a **Lanes** chip and an overlay bar with workspace and lane
 pickers (`laneBarModel`, from the `MobileState` sent to every web client). The laptop/tablet code and styles live in
 `browser.js`/`browser.css`, which `mobile.js` appends only on a tablet or desktop (a phone never downloads them), so
-the phone's `mobile.js`/`mobile.css` budget (spec §8) stays with the phone. The chip cancels `mousedown` and
-refocuses the terminal, so the keys stay the terminal's. On a tablet, `browser.js` also undoes the client's per-load single-pane start once
+a phone downloads only the two files that spec §8 budgets (measured figures under Bundle budget below). The chip
+cancels `mousedown` and refocuses the terminal, so the keys stay the terminal's. On a tablet, `browser.js` also
+undoes the client's per-load single-pane start once
 (`laneFullRender`, the client's own `SetMobileRenderPreferences {single_pane: false, fit: true}`), so a desktop
 view's sidebar shows beside its lanes. `tests/web/activation.test.mjs` (`node --test`) pins the activation matrix,
 the picker model and that render preference; `tests/unit/test_web_view.py` pins the size budgets and runs that
@@ -25,6 +26,14 @@ Zellij's original capture input in its closed shadow root, preserving its keyboa
 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.
+The guard is installed before Zellij's first terminal or login modal: otherwise Zellij refocuses a hidden input on
+touchstart, touchend, click and server `SetSoftKeyboard` messages. The **Type here** field keeps the original input
+and its event handlers inside the closed shadow root (including its protection from password-manager extensions) and
+makes it a real, tappable field instead of a 1 px invisible focus target; keystrokes appear in the terminal and its
+internal padding/history stays invisible. Upstream cancels `pointerdown` on the extra keys, which also suppresses
+their touch click in Safari, so the shell cancels `mousedown` instead: typing focus is kept while the native click
+still activates CTRL, the arrows and the other keys. The shell attaches only once server state has arrived — resizing
+before the control socket opens makes 0.45.1 throw `InvalidStateError` and leaves the server with the old size.
 
 `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;
@@ -41,8 +50,78 @@ clearing login cookies. There is no service worker caching terminal data or cred
 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.
+`libexec/sidebar.py` uses three terminal rows per lane on mobile: name, state and age, the agent's task.
+`tests/mobile_view.py` verifies the touch-to-lane path with isolated holders; sidebar unit tests cover the
+complete touch target.
+
+Every byte the shell sends to a terminal goes through `__zjSendControl({type: 'Write', bytes})`
+(`sendToTerminal`); there is no focus-and-type fallback, since the focus guard above would make it type nowhere.
+The lane filter bar sends `Esc /` and the query as UTF-8 (`TextEncoder`), dropping control bytes and DEL.
+Attention counts come from the picker sidebar's pane title (`WS · ◆1 ◇2 ▸6`, written by the sidebar as OSC 2):
+`parseCounts` (also `window.__lanesParseCounts`) feeds the picker subtitle, `document.title`, the Lanes button's
+`data-count` and the workspace cards, inside the existing `refresh()` / `renderCards()` — no fetch, file or timer.
+Until plan Task 26 (2026-10-04) this reader was inert (DEF-1531): `bin/lanes` `mobile_workspace_tab` gave the
+picker pane a fixed `name="Lanes"`, and Zellij reports a pane's layout name instead of its OSC 2 title, so
+`pickerTitle()` read `Lanes`, `parseCounts` returned null and the shell showed no counts ("Choose a lane to continue").
+Task 26 dropped that `name=` (pinned by `tests/unit/test_layout.py`) for sessions laid out since: an existing
+phone device keeps the old picker pane until `lanes rebuild <device>` (`upgrade-session` never re-lays-out a tab;
+`lanes doctor` names such a device). Whether the OSC 2 title now reaches
+`panes[].title` is still unchecked in a browser (no WebKit pass has run; fallback: the counts stay in the
+sidebar header). The quick-key row (`⏎ y n Esc ^C ↑ ↓`, `.lanes-quick`) shows on view
+tabs only; `refresh()` sets `--lanes-quick` (48 px or 0), which the terminal height subtracts. `n` and `^C` send
+only when `pointerup.timeStamp − pointerdown.timeStamp ≥ 400` (no `setTimeout`); the buttons cancel `mousedown`
+so a tap never moves focus.
+
+Colour (spec §6.3; the operator legend, token table and phone mockup are in [`docs/DESIGN.md`](../docs/DESIGN.md)):
+`mobile.css` uses only the generated `--lanes-*` tokens (legacy names such as `--lanes-bg` stay
+as aliases for one release); `test_web` rejects any colour literal outside the generated block. The terminal palette
+is the phone's own, because Zellij's `web_client.theme` is one server-wide dark palette (DEF-1413): `lanesTheme()`
+builds xterm.js's theme from the CSS tokens (`getComputedStyle(root)`) and the sixteen `LANES_ANSI` slots, which
+`libexec/tokens.py --js` generates into `mobile.js` (never hand-edited). It is applied at three points, all event
+driven: (1) on attach, after `build(); applyFont();`; (2) on every `data-zj-theme` change, through one
+`MutationObserver` on `<html>` (upstream's theme toggle only flips that attribute); (3) after every `SetConfig`, by
+chaining `window.__zjSyncInactiveCursorStyle`, which the pinned `app.js` calls in its `SetConfig` handler right after
+assigning the server theme wholesale (`SetConfig` is sent on each config-file reload). The handler then runs
+`applyTerminalBackground`, which writes the dark background inline on `<body>` and `#terminal`; the stylesheet's
+`!important` `--lanes-surface` rule for those two elements outranks it in either variant. An SRI bump of `app.js`
+re-opens this contract: re-read `startWsControl` and `installSoftKeyboardCapture` before accepting it.
+`index.html` carries one `theme-color` per colour scheme. Bundle budget (spec §8, `test_web.test_bundle_growth`):
+`mobile.css` ≤ 18 982 B and `mobile.js` ≤ 22 174 B; the caps are never raised — the rules sit one per line and the
+explanations live here rather than in the shipped files. MEASURED 2026-10-04 with `wc -c` after LNS-31 (plan Task
+31) met Tasks 13/28: `mobile.js` 21 964 B (23 268 B before its comments moved to Code notes below) and `mobile.css`
+18 945 B. A laptop or tablet also fetches `browser.js` (3 641 B) and `browser.css` (1 947 B); `test_web_view` pins
+that download at `LAPTOP_TABLET_JS_RATCHET` and `LAPTOP_TABLET_CSS_CAP` (DEF-1569).
+
+## Code notes
+
+`mobile.js` carries no explanations (the spec §8 budget above); each note is keyed to the code it explains, in file
+order.
+
+- The file: the Lanes browser shell (phone, tablet, desktop) over the pinned Zellij 0.45.1 client's window hooks.
+- `root.dataset.lanesShell = mode`: read by `browser.js` for the desktop bar and the tablet's full rendering.
+- `if (mode !== 'phone')`: appends the laptop/tablet extras (`browser.css`, `browser.js`); a phone never fetches them.
+- `if (mode === 'tablet')`: iPad Safari's user agent is a desktop one, so the shell asks for the client's mobile UI
+  (`zellij:mobile-ui` set to `on`); a stored `off` stays.
+- The `HTMLElement.prototype.focus` guard: only a native tap on an input may open the keyboard; it is installed before
+  upstream's first terminal or modal.
+- `viewport()`: browser toolbars alone must not mean keyboard mode (`occluded` needs more than 120 px hidden). Zellij's
+  input is in a closed shadow root, so `document.activeElement` is its host; `__zjSoftKbdCapture.isFocused` is read
+  first.
+- `buildTypingField()`: upstream's capture input stays in its closed shadow root and becomes the real, tappable field.
+- `GLYPHS` / `parseCounts()`: counts from the picker sidebar's OSC 2 pane title (spec §6.4).
+- `build()`, the `.zj-mobile-modbar` keys: cancel `mousedown`, not `pointerdown` (upstream's `pointerdown` cancel kills
+  Safari's touch click on the extra keys).
+- `buildQuickRow()` (spec §6.5): `n` and `^C` send after a 400 ms hold, measured from event timestamps with no timer;
+  nothing takes focus.
+- `clearLaneFilter()`: the lone `Esc` leaves the sidebar's filter mode.
+- `lanesTheme()`: the shell's own terminal palette for both variants (spec §6.3, DEF-1413).
+- `connect()`: waits for server state, because an earlier resize throws `InvalidStateError` in 0.45.1. `applyTheme` is
+  re-applied after every `SetConfig` (the client calls the chained `__zjSyncInactiveCursorStyle` hook) and on the theme
+  toggle.
+- The `zellij:soft-keyboard-visibility` listener: rotation also shrinks the viewport, so the shell sends
+  `SoftKeyboardVisibilityChanged` itself to correct upstream's height-only keyboard heuristic.
+- `awaitingClient` (the one `setInterval`, 200 ms, cleared once attached): upstream installs its window hooks just after
+  appending its mobile root.
 
 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,

package/payload/lanes/web/index.html

@@ -4,7 +4,8 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
-    <meta name="theme-color" content="#101318" />
+    <meta name="theme-color" content="#101318" media="(prefers-color-scheme: dark)" />
+    <meta name="theme-color" content="#f3f5f2" media="(prefers-color-scheme: light)" />
     <meta name="apple-mobile-web-app-capable" content="yes" />
     <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
     <meta name="apple-mobile-web-app-title" content="Lanes" />