@vibelord/lanes 1.0.1 → 1.0.2

package/payload/lanes/client/ghostty/common.conf

@@ -20,3 +20,6 @@ copy-on-select = clipboard
 mouse-shift-capture = never
 scrollback-limit = 10000000
 link-url = true
+
+# OSC 9 from the lanes sidebar (a lane that needs you) becomes a macOS notification when this window is not focused.
+desktop-notifications = true

package/payload/lanes/client/ghostty/lanes-palette-light.conf

@@ -0,0 +1,25 @@
+# BEGIN lanes tokens (generated by libexec/tokens.py --ghostty-light; 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.
+background = #f3f5f2
+foreground = #17241b
+cursor-color = #2f6b45
+selection-background = #d5ded6
+selection-foreground = #17241b
+palette = 0=#3b4a42
+palette = 1=#b7322a
+palette = 2=#1b7142
+palette = 3=#8a5a00
+palette = 4=#2456a8
+palette = 5=#7a3fb8
+palette = 6=#0f7b7b
+palette = 7=#56616d
+palette = 8=#5f6d66
+palette = 9=#c2332a
+palette = 10=#1b7a38
+palette = 11=#8f5a00
+palette = 12=#2860c4
+palette = 13=#8a4dc8
+palette = 14=#0f7272
+palette = 15=#17241b
+# END lanes tokens

package/payload/lanes/client/ghostty/lanes-palette.conf

@@ -0,0 +1,25 @@
+# BEGIN lanes tokens (generated by libexec/tokens.py --ghostty-dark; 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.
+background = #101318
+foreground = #edf1f5
+cursor-color = #b4e3bf
+selection-background = #2c333d
+selection-foreground = #edf1f5
+palette = 0=#7d8896
+palette = 1=#f28b7d
+palette = 2=#6fd39a
+palette = 3=#e5b84a
+palette = 4=#7fb3f2
+palette = 5=#c9a6ff
+palette = 6=#6fd6d0
+palette = 7=#9ca7b5
+palette = 8=#8a95a3
+palette = 9=#ff9d96
+palette = 10=#8fe0a3
+palette = 11=#f7cf7f
+palette = 12=#a5cbff
+palette = 13=#dcc6ff
+palette = 14=#9ae6e0
+palette = 15=#edf1f5
+# END lanes tokens

package/payload/lanes/client/ghostty/omarchy.conf

@@ -1,6 +1,7 @@
 # Omarchy / Hyprland specifics for the lanes window (Ghostty GTK, dedicated instance).
-# Look & feel is inherited from ~/.config/ghostty/config (Omarchy's default: theme include, JetBrainsMono Nerd
-# Font, shift+enter as CSI-u, control+insert / shift+insert copy & paste), so Omarchy theme switches follow.
+# Look & feel is inherited from ~/.config/ghostty/config (Omarchy's default: theme include, the Omarchy default font —
+# a Nerd Font is not required by lanes, every glyph is plain Unicode; shift+enter as CSI-u, control+insert /
+# shift+insert copy & paste), so Omarchy theme switches follow.
 # Do NOT include the theme file here as well: Ghostty reports a second include of the same file as
 # "config-file …: cycle detected" and opens its configuration-errors window.
 

package/payload/lanes/client/lanes-launch

@@ -3,6 +3,7 @@
 #   lanes-launch [device]        attach this terminal to the device's view session (default: see below)
 #   lanes-launch <workspace>     same, and bring that workspace's tab to the front (e.g. `coder-launch worlds`)
 #   lanes-launch <device> --viewports N   a wide view session: N (2-3) viewports side by side per workspace
+#   lanes-launch <device> [--ascii] [--theme dark|light|auto] [--glyphs M] [--color C]   the device's look (lanes attach)
 #   lanes-launch lane <lane-id>  attach straight to ONE lane, no multiplexer in between
 #   lanes-launch ls              list lanes with live status
 #   lanes-launch --helper <device> [--service | --while-pid PID]   run only the upload helper
@@ -41,11 +42,25 @@ case "${1:-}" in
     lane)
         [ -n "${2:-}" ] || { echo 'usage: lanes-launch lane <lane-id>' >&2; exit 64; }
         mode=open target=$2 ;;
-    -h|--help) sed -n '2,11p' "$0"; exit 0 ;;
+    -h|--help) sed -n '2,12p' "$0"; exit 0 ;;
     *) mode=attach target=${1:-$(default_device)} ;;
 esac
-if [ "$mode" = attach ] && [ "${2:-}" = --viewports ]; then
-    case "${3:-}" in 1|2|3) extra="--viewports $3" ;; *) echo '--viewports takes 1, 2 or 3' >&2; exit 64 ;; esac
+if [ "$mode" = attach ] && [ $# -gt 1 ]; then
+    # Options after the device go to `lanes attach`. They are spliced into the remote command line, so only this closed
+    # vocabulary passes: a bad value refuses before any connection, an unknown option is said out loud and dropped.
+    shift
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --viewports) case "${2:-}" in 1|2|3) extra="$extra --viewports $2"; shift ;; *) echo '--viewports takes 1, 2 or 3' >&2; exit 64 ;; esac ;;
+            --ascii) extra="$extra --ascii" ;;
+            --theme) case "${2:-}" in dark|light|auto) extra="$extra --theme $2"; shift ;; *) echo '--theme takes dark, light or auto' >&2; exit 64 ;; esac ;;
+            --glyphs) case "${2:-}" in unicode|ascii|emoji) extra="$extra --glyphs $2"; shift ;; *) echo '--glyphs takes unicode, ascii or emoji' >&2; exit 64 ;; esac ;;
+            --color) case "${2:-}" in truecolor|16|none) extra="$extra --color $2"; shift ;; *) echo '--color takes truecolor, 16 or none' >&2; exit 64 ;; esac ;;
+            *) echo "lanes-launch: ignoring unknown option $1" >&2 ;;
+        esac
+        shift
+    done
+    extra=${extra# }
 fi
 case "$target" in ''|-*|*[!A-Za-z0-9_.-]*) echo "invalid name: $target" >&2; exit 64 ;; esac
 client="$(hostname -s 2>/dev/null || echo client)-$$"

package/payload/lanes/client/lanes-window

@@ -1,7 +1,9 @@
 #!/bin/sh
-# Open the lanes window in its own terminal instance. usage: lanes-window [suffix]
+# Open the lanes window in its own terminal instance. usage: lanes-window [--ascii] [--light|--dark] [suffix]
 #   suffix: an independent view session "<device>-<suffix>" (second monitor / other half of an ultrawide).
 #   w2 / w3: a WIDE view session with 2 / 3 viewports side by side per workspace (for a full-width window).
+#   --ascii / --light / --dark: the cockpit's look for this device (`lanes attach … --ascii|--theme`), remembered on
+#   the server in devices/<device>.json and picked up by a running sidebar and its status screens.
 # macOS: Ghostty. Linux: Ghostty when installed, otherwise Foot with the same window class.
 set -u
 config=${XDG_CONFIG_HOME:-$HOME/.config}/lanes
@@ -9,11 +11,25 @@ launch=$HOME/.local/bin/lanes-launch
 class=org.omarchy.lanes
 device=
 file=$config/ghostty.conf
+look=
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --ascii) look="$look --ascii"; shift ;;
+        --light|--dark) look="$look --theme ${1#--}"; shift ;;
+        *) break ;;
+    esac
+done
 if [ -n "${1:-}" ]; then
     case "$1" in *[!A-Za-z0-9_.-]*) echo 'invalid suffix' >&2; exit 64 ;; esac
     device="$(head -n 1 "$config/device")-$1"
     case "$1" in w2) device="$device --viewports 2" ;; w3) device="$device --viewports 3" ;; esac
     file=$config/ghostty.$1.conf
+elif [ -n "$look" ]; then
+    device=$(head -n 1 "$config/device")
+    file=$config/ghostty.look.conf
+fi
+if [ -n "$device" ]; then
+    device="$device$look"
     sed "s|^command = .*|command = $launch $device|" "$config/ghostty.conf" > "$file"
 fi
 case "$(uname -s)" in

package/payload/lanes/container/env.sh

@@ -14,7 +14,7 @@
 # (<ws>--<slug>), LANE_WS (<ws>), THROTTLE_TRACE and ANTHROPIC_CUSTOM_HEADERS ('x-throttle-trace: lanes/<ws>/<id>';
 # trace charset [A-Za-z0-9._-/], at most 256). Never export them from a profile or a client: the client that starts
 # a shared board socket's tmux server copies its env into the server's GLOBAL env, which every later session there
-# without its own -e inherits (DEF-1422) — so `lane open` strips them. A running lane gains its identity only when it
+# without its own -e inherits (DEF-1478) — so `lane open` strips them. A running lane gains its identity only when it
 # is next created by a recipe carrying -e; a legacy recipe without -e gives none (`lanes cursor-sync --identity`).
 if [ -z "${LANES_TMP_OPTOUT+set}" ] && [ -d "${LANES_TMP_DIR:-/home/coder/.tmp}" ] \
         && [ -w "${LANES_TMP_DIR:-/home/coder/.tmp}" ] && [ -x "${LANES_TMP_DIR:-/home/coder/.tmp}" ]; then

package/payload/lanes/container/hooks/claude-settings.json

@@ -0,0 +1,10 @@
+{"hooks": {
+  "UserPromptSubmit": [{"hooks": [{"type": "command", "command": "~/.lz/bin/lane-signal working --event UserPromptSubmit --harness claude", "timeout": 2}]}],
+  "PostToolUse": [{"hooks": [{"type": "command", "command": "~/.lz/bin/lane-signal working --event PostToolUse --harness claude", "timeout": 2}]}],
+  "Stop": [{"hooks": [{"type": "command", "command": "~/.lz/bin/lane-signal needs_input --event Stop --harness claude", "timeout": 2}]}],
+  "Notification": [{"matcher": "permission_prompt", "hooks": [{"type": "command", "command": "~/.lz/bin/lane-signal needs_approval --event Notification --harness claude", "timeout": 2}]},
+                   {"matcher": "idle_prompt", "hooks": [{"type": "command", "command": "~/.lz/bin/lane-signal needs_input --event Notification --harness claude", "timeout": 2}]}],
+  "PermissionRequest": [{"hooks": [{"type": "command", "command": "~/.lz/bin/lane-signal needs_approval --event PermissionRequest --harness claude", "timeout": 2}]}],
+  "SessionEnd": [{"hooks": [{"type": "command", "command": "~/.lz/bin/lane-signal shell --event SessionEnd --harness claude", "timeout": 2}]}],
+  "StopFailure": [{"hooks": [{"type": "command", "command": "~/.lz/bin/lane-signal errored --event StopFailure --harness claude", "timeout": 2}]}]
+}}

package/payload/lanes/container/hooks/codex-hooks.json

@@ -0,0 +1,22 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {"matcher": null, "hooks": [{"type": "command", "command": "~/.lz/bin/lane-signal idle --event SessionStart --harness codex", "timeout": 2}]}
+    ],
+    "UserPromptSubmit": [
+      {"matcher": null, "hooks": [{"type": "command", "command": "~/.lz/bin/lane-signal working --event UserPromptSubmit --harness codex", "timeout": 2}]}
+    ],
+    "PostToolUse": [
+      {"matcher": null, "hooks": [{"type": "command", "command": "~/.lz/bin/lane-signal working --event PostToolUse --harness codex", "timeout": 2}]}
+    ],
+    "PermissionRequest": [
+      {"matcher": null, "hooks": [{"type": "command", "command": "~/.lz/bin/lane-signal needs_approval --event PermissionRequest --harness codex", "timeout": 2}]}
+    ],
+    "Stop": [
+      {"matcher": null, "hooks": [{"type": "command", "command": "~/.lz/bin/lane-signal done --event Stop --harness codex", "timeout": 2}]}
+    ],
+    "SessionEnd": [
+      {"matcher": null, "hooks": [{"type": "command", "command": "~/.lz/bin/lane-signal shell --event SessionEnd --harness codex", "timeout": 2}]}
+    ]
+  }
+}

package/payload/lanes/container/lane

@@ -1,25 +1,34 @@
 #!/usr/bin/env python3
 """lane — the in-container lane contract (Python 3 stdlib). Installed at /home/coder/.lz/bin/lane.
 
-A lane is one long-lived agent terminal, held by a per-lane zmx daemon (byte pass-through + instant
-re-attach). Viewers, orchestrators and the web harness use ONLY these verbs, so the holder stays swappable.
+A lane is one long-lived agent terminal, held by a tmux session (the lanes registry's `holder: tmux` lanes, named in
+~/.lz/registry.json) or by a per-lane zmx daemon (`lane new`). Viewers, orchestrators and the web harness use ONLY
+these verbs, so the holder stays swappable: every verb below resolves the id in ~/.lz/registry.json first and drives
+a `holder: tmux` lane through its exact socket and session; any other id is a zmx lane, as before.
 
-  lane new <id> [--ws W] [--title T] [--cwd DIR] [--icon I] [--color C] -- <command...>
+  lane new <id> [--ws W] [--title T] [--cwd DIR] [--icon I] [--color C] -- <command...>     (zmx only)
   lane open <lane-id>         the uniform entry point for editors (Cursor / VS Code terminals.json): attach to the
                               lane; if it does not exist, run its recorded create recipe. Never nests inside tmux.
                               While the lanes view shows the lane, attach with ignore-size (the lanes view owns the size).
-  lane attach <id>            attach this terminal (never creates)
-  lane send <id> <text...>    type into the lane (use $'\\r' for Enter)
+  lane attach <id>            attach this terminal (never creates; a tmux lane never nests inside tmux)
+  lane send <id> [--no-enter] <text...>   type into the lane. tmux: literally, then Enter unless --no-enter.
+                              zmx: the bytes as given, never an Enter of its own (use $'\\r')
   lane capture <id> [--lines N] [--vt]   print scrollback (plain text, or VT with --vt)
-  lane ls [--json]            lanes with holder metadata
-  lane status <id>            JSON: running?, last exit of the agent command, meta
-  lane kill <id>              stop the lane (the ONLY verb that ends an agent)
+  lane ls [--json] [--all]    zmx lanes with holder metadata; --all adds the registry's tmux lanes with `alive`
+                              (the default listing stays zmx-only: Throttle Studio reads every row of it as zmx)
+  lane status <id>            JSON: alive/running?, the hook agent (`lane-signal`), meta; exit 1 when not running
+  lane kill <id> --yes [--force]   stop the lane (the ONLY verb that ends an agent); refuses while the lane's
+                              hook sidecar says the agent is `working` unless --force
+  lane gc --sockets           unlink this container's tmux socket files that tmux is refused on (ECONNREFUSED: no
+                              server listens); prints each unlinked path. A live, empty or silent server keeps its file
 """
 import json
 import os
 import pty
 import re
 import select
+import socket
+import stat
 import subprocess
 import sys
 import time
@@ -29,7 +38,11 @@ ROOT = Path(os.environ.get('LANE_ROOT', '/home/coder/.lz'))
 VERSION = os.environ.get('LANE_ZMX_VERSION', '0.8.1')
 ZMX = ROOT / 'bin' / f'zmx-{VERSION}'
 SOCKETS, META, STATE = ROOT / 's', ROOT / 'meta', ROOT / 'state'
+HOOKS = STATE / 'hooks'   # lane-signal's sidecars (never lane-run's phase records one directory up, DEF-1436)
+PROC = Path('/proc')      # this container's pid namespace: the hook's agent pid is checked here
 IDENT = re.compile(r'^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$')
+STATUSES = ('working', 'needs_input', 'needs_approval', 'done', 'errored', 'shell', 'idle')   # agent_state.STATUSES
+HOOK_MAX_AGE = 3600       # statusd.SIDECAR_MAX_AGE: an older last event is no agent
 
 
 def zmx_env(extra=None):
@@ -154,7 +167,7 @@ IDENTITY = ('LANE_ID', 'LANE_WS', 'THROTTLE_TRACE')   # + a lanes/ ANTHROPIC_CUS
 def identity_free(environ, drop=('TMUX',)):
     """`environ` without any lane identity (lanes/docs/ARCHITECTURE.md "Lane identity"). Whatever tmux client STARTS
     a socket's server hands its whole environment to the server's GLOBAL environment, and every later session on
-    that socket created without its own `-e` inherits it (MEASURED, tmux 3.4: DEF-1422). Board sockets are shared by
+    that socket created without its own `-e` inherits it (MEASURED, tmux 3.4: DEF-1478). Board sockets are shared by
     many lanes, so a lane identity in the env of anything that may start one would be stamped on unrelated lanes.
     Identity therefore reaches a lane's shell ONLY through `-e` in its create recipe (lanes_lib.canonical_recipe).
     An operator's own ANTHROPIC_CUSTOM_HEADERS that is not a lane trace is theirs and stays."""
@@ -162,9 +175,113 @@ def identity_free(environ, drop=('TMUX',)):
             and not (k == 'ANTHROPIC_CUSTOM_HEADERS' and v.startswith('x-throttle-trace: lanes/'))}
 
 
+def tmux_run(argv):
+    """One tmux client, never carrying a lane identity (it could be the client that starts a shared board server)."""
+    return subprocess.run(argv, capture_output=True, text=True, timeout=15, env=identity_free(os.environ))
+
+
 def tmux_cmd(socket, *args):
-    env = identity_free(os.environ)
-    return subprocess.run(['tmux', '-L', socket, *args], capture_output=True, text=True, timeout=15, env=env)
+    return tmux_run(['tmux', '-L', socket, *args])
+
+
+def registry_lanes(verb):
+    """{lane id: entry} of ~/.lz/registry.json; {} when there is none (a zmx-only container needs none). A newer
+    registry is refused, as `lane open` refuses it."""
+    try:
+        data = json.loads((ROOT / 'registry.json').read_text())
+        lanes = data['lanes']
+    except (OSError, ValueError, KeyError, TypeError):
+        return {}
+    if int(data.get('version', 1)) > 1:
+        sys.exit(f'lane {verb}: the registry is newer than this `lane` — on the host run: lanes install-container <container>')
+    return lanes if isinstance(lanes, dict) else {}
+
+
+def tmux_target(entry):
+    """(socket, session) of a registry entry held by tmux, else None."""
+    if not isinstance(entry, dict) or entry.get('holder') != 'tmux':
+        return None
+    tmux = entry.get('tmux') or {}
+    socket, session = tmux.get('socket'), tmux.get('session')
+    return (str(socket), str(session)) if socket and session else None
+
+
+def tmux_lane(verb, lane):
+    """(entry, socket, session) when the registry holds `lane` as a tmux lane, else None (a zmx lane)."""
+    entry = registry_lanes(verb).get(lane)
+    target = tmux_target(entry)
+    return (entry, *target) if target else None
+
+
+def zmx_name(verb, lane):
+    """The zmx session of `lane`: the registry's `zmx.name` for a registry zmx lane, else the id itself (`lane new`)."""
+    entry = registry_lanes(verb).get(lane)
+    name = ((entry or {}).get('zmx') or {}).get('name') if isinstance(entry, dict) and entry.get('holder') == 'zmx' else None
+    return name if isinstance(name, str) and IDENT.match(name) else lane
+
+
+def tmux_text(text):
+    """tmux's argv parser ends a command at ONE trailing `;` of ANY argument and turns a trailing `\\;` into `;`
+    (MEASURED, tmux 3.4: `send-keys -l -- 'echo a;'` types `echo a`). Writing that last `;` as `\\;` types the text
+    exactly, a trailing `\\;` included."""
+    return text[:-1] + '\\;' if text.endswith(';') else text
+
+
+def send_argv(socket, session, text, enter=True):
+    """Type `text` literally into the session's active pane, then Enter — one tmux client, `;`-separated. The target
+    is `=<session>:` (exact session, its current window): a bare `=<session>` is refused by send-keys and
+    capture-pane with "can't find pane" (MEASURED, tmux 3.4)."""
+    target = f'={session}:'
+    argv = ['tmux', '-L', socket, 'send-keys', '-t', target, '-l', '--', tmux_text(text)]
+    return argv + [';', 'send-keys', '-t', target, 'Enter'] if enter else argv
+
+
+def capture_argv(socket, session, lines, vt=False):
+    """Joined scrollback of the session's active pane: the last `lines` history lines plus the screen (`-S -N`; the
+    caller keeps the last N non-blank lines), or all of it (`-S -`); `--vt` keeps the escape sequences (`-e`)."""
+    argv = ['tmux', '-L', socket, 'capture-pane', '-p', '-J', '-S', f'-{lines}' if lines else '-', '-t', f'={session}:']
+    return argv + ['-e'] if vt else argv
+
+
+def tmux_attach_argv(socket, session):
+    """attach-session; with ignore-size while the lanes view shows the lane (the lanes view owns the size)."""
+    clients = tmux_cmd(socket, 'list-clients', '-t', f'={session}', '-F', '#{client_termname}').stdout.split()
+    argv = ['tmux', '-L', socket, 'attach-session']
+    if VIEWER_TERM in clients:
+        argv += ['-f', 'ignore-size']   # the lanes view is showing this lane: never resize it from here
+    return argv + ['-t', f'={session}']
+
+
+def hook_agent(name):
+    """The lane's `lane-signal` sidecar (~/.lz/state/hooks/<name>.json) as an agent dict, or {} — judged as the host's
+    `agent_state.read_sidecar_dict` judges it: ours (`v` 1, a vocabulary word), a last event (`at`, else `since`)
+    within HOOK_MAX_AGE, and a recorded agent pid still alive in this container (and the same process when the
+    writer recorded its `start`). A crashed agent's last word is never an agent."""
+    try:
+        d = json.loads((HOOKS / f'{name}.json').read_text())
+    except (OSError, ValueError):
+        return {}
+    if not isinstance(d, dict) or d.get('v') != 1 or d.get('status') not in STATUSES:
+        return {}
+    try:
+        since = int(d.get('since') or 0)
+        at = int(d.get('at') or since)
+        pid = int(d.get('pid') or 0)
+    except (TypeError, ValueError):
+        return {}
+    if since <= 0 or time.time() - at > HOOK_MAX_AGE:
+        return {}
+    if pid > 0:
+        try:
+            stat = (PROC / str(pid) / 'stat').read_text()
+        except OSError:
+            return {}
+        if d.get('start') is not None:
+            fields = stat.rsplit(')', 1)[-1].split()
+            if len(fields) < 20 or fields[19] != str(d['start']):
+                return {}
+    return {'harness': str(d.get('harness') or ''), 'status': d['status'], 'since': since, 'at': at,
+            'event': str(d.get('event') or ''), 'session': str(d.get('session') or ''), 'pid': pid, 'source': 'hook'}
 
 
 def cmd_open(args):
@@ -175,7 +292,7 @@ def cmd_open(args):
         sys.exit(f"lane open: already inside tmux — refusing to nest. The lane is: {json.dumps(entry.get('tmux') or entry.get('zmx'))}")
     # Nothing `lane open` execs carries a lane identity — neither this lane's nor one inherited from ANOTHER lane (an
     # editor terminal started inside a lane): the recipe may be the first client on a shared board socket and would
-    # hand it to every later session there (DEF-1422). The canonical recipe's own `-e` flags give the identity.
+    # hand it to every later session there (DEF-1478). The canonical recipe's own `-e` flags give the identity.
     env = identity_free(os.environ, drop=('TMUX', 'TMUX_PANE'))
     if entry.get('holder') == 'zmx':
         name = entry['zmx']['name']
@@ -184,11 +301,7 @@ def cmd_open(args):
     else:
         socket, session = entry['tmux']['socket'], entry['tmux']['session']
         if tmux_cmd(socket, 'has-session', '-t', f'={session}').returncode == 0:
-            clients = tmux_cmd(socket, 'list-clients', '-t', f'={session}', '-F', '#{client_termname}').stdout.split()
-            argv = ['tmux', '-L', socket, 'attach-session']
-            if VIEWER_TERM in clients:
-                argv += ['-f', 'ignore-size']   # the lanes view is showing this lane: never resize it from here
-            os.execvpe('tmux', argv + ['-t', f'={session}'], env)
+            os.execvpe('tmux', tmux_attach_argv(socket, session), env)
     # The lane does not exist: run the recipe the repository recorded for it (it creates AND attaches).
     recipe = entry.get('create')
     folder = entry.get('folder') or str(Path.home())
@@ -205,6 +318,15 @@ def cmd_open(args):
 
 def cmd_attach(args):
     name = lane_id(args[0] if args else '')
+    held = tmux_lane('attach', name)
+    if held:
+        _, socket, session = held
+        if os.environ.get('TMUX'):
+            sys.exit(f'lane attach: already inside tmux — refusing to nest. The lane is: {socket} {session}')
+        if tmux_cmd(socket, 'has-session', '-t', f'={session}').returncode != 0:
+            sys.exit(f'lane attach: {name} is not running (never created implicitly; `lane open {name}` runs its recipe)')
+        os.execvpe('tmux', tmux_attach_argv(socket, session), identity_free(os.environ, drop=('TMUX', 'TMUX_PANE')))
+    name = zmx_name('attach', name)
     if not alive(name):
         sys.exit(f'lane attach: {name} is not running (never created implicitly)')
     # Clean environment on purpose: with ZMX_SESSION set, zmx would SWITCH the calling session instead of attaching.
@@ -212,23 +334,51 @@ def cmd_attach(args):
 
 
 def cmd_send(args):
+    enter = '--no-enter' not in args[:2]   # an option only before the text: a later `--no-enter` is text
+    if not enter:
+        args = list(args)
+        args.remove('--no-enter')
     name = lane_id(args[0] if args else '')
-    result = zmx('send', name, ' '.join(args[1:]))
+    text = ' '.join(args[1:])
+    held = tmux_lane('send', name)
+    if held:
+        _, socket, session = held
+        result = tmux_run(send_argv(socket, session, text, enter))
+    else:
+        result = zmx('send', zmx_name('send', name), text)   # zmx: the bytes as given, never an Enter of its own
     sys.stderr.write(result.stderr)
     sys.exit(result.returncode)
 
 
+def last_lines(text, lines):
+    """The last `lines` lines that end in something: a tmux capture ends with the screen's unused blank rows."""
+    rows = text.splitlines()
+    while rows and not rows[-1].strip():
+        rows.pop()
+    return '\n'.join(rows[-lines:]) + '\n'
+
+
 def cmd_capture(args):
     lines = int(option(args, '--lines', '0') or 0)
     flags = ['--vt'] if '--vt' in args else []
     name = lane_id(next((a for a in args if not a.startswith('--')), ''))
-    text = zmx('history', name, *flags).stdout
+    held = tmux_lane('capture', name)
+    if held:
+        _, socket, session = held
+        result = tmux_run(capture_argv(socket, session, lines, vt=bool(flags)))
+        if result.returncode:
+            sys.stderr.write(result.stderr)
+            sys.exit(result.returncode)
+        sys.stdout.write(last_lines(result.stdout, lines) if lines else result.stdout)
+        return
+    text = zmx('history', zmx_name('capture', name), *flags).stdout
     if lines:
         text = '\n'.join(text.splitlines()[-lines:]) + '\n'
     sys.stdout.write(text)
 
 
 def describe():
+    """The zmx lanes, one row each — the `lane ls --json` shape Throttle Studio reads as zmx lanes (lane_cli.rs)."""
     rows = []
     for name, fields in sorted(sessions().items()):
         meta = {}
@@ -243,31 +393,87 @@ def describe():
             pass
         rows.append({'id': name, 'holder': 'zmx', 'pid': int(fields.get('pid', 0)), 'clients': int(fields.get('clients', 0)),
                      'ws': meta.get('ws', ''), 'title': meta.get('title', name), 'cwd': meta.get('cwd', ''),
-                     'icon': meta.get('icon', ''), 'color': meta.get('color', ''), 'agent': state})
+                     'icon': meta.get('icon', ''), 'color': meta.get('color', ''), 'agent': state, 'alive': True})
+    return rows
+
+
+def tmux_row(lane, entry, socket, session, alive_now):
+    """A tmux lane: registry facts, `alive` from its server, `agent` from its hook sidecar ({} without one)."""
+    return {'id': lane, 'holder': 'tmux', 'ws': entry.get('ws') or '', 'title': entry.get('name') or lane,
+            'tmux': {'socket': socket, 'session': session}, 'alive': alive_now, 'agent': hook_agent(lane)}
+
+
+def tmux_rows():
+    """Every registry tmux lane, `alive` from ONE list-sessions per socket (a has-session per lane would be one tmux
+    client per lane; a socket whose server is not running lists nothing, so its lanes are not alive)."""
+    rows, listed = [], {}
+    for lane, entry in sorted(registry_lanes('ls').items()):
+        target = tmux_target(entry)
+        if not target or not IDENT.match(lane):
+            continue
+        socket, session = target
+        if socket not in listed:
+            result = tmux_cmd(socket, 'list-sessions', '-F', '#{session_name}')
+            listed[socket] = set(result.stdout.splitlines()) if result.returncode == 0 else set()
+        rows.append(tmux_row(lane, entry, socket, session, session in listed[socket]))
     return rows
 
 
 def cmd_ls(args):
-    rows = describe()
+    # The default listing stays zmx-only: Throttle Studio reads EVERY `lane ls --json` row as a zmx lane, so tmux rows
+    # there would publish each registry tmux lane a second time. --all is the opt-in for people and scripts.
+    if '--all' in args:
+        try:
+            rows = describe()
+        except OSError:   # no zmx binary in this root: no zmx lane can run here; the tmux lanes still list
+            rows = []
+        rows += tmux_rows()
+    else:
+        rows = describe()   # unchanged: a missing zmx stays an error for the listing Studio reads
     if '--json' in args:
         print(json.dumps(rows, ensure_ascii=False, indent=1))
         return
     for row in rows:
+        if row['holder'] == 'tmux':
+            agent = row['agent'].get('status', '-')
+            print(f"{row['id']:<40} {row['ws']:<18} {'alive' if row['alive'] else 'dead':<9} {agent:<8} {row['title']}")
+            continue
         agent = row['agent'].get('phase', '?')
         print(f"{row['id']:<40} {row['ws']:<18} clients={row['clients']} {agent:<8} {row['title']}")
 
 
 def cmd_status(args):
     name = lane_id(args[0] if args else '')
-    row = next((r for r in describe() if r['id'] == name), None)
+    held = tmux_lane('status', name)
+    if held:
+        entry, socket, session = held
+        alive_now = tmux_cmd(socket, 'has-session', '-t', f'={session}').returncode == 0
+        print(json.dumps(tmux_row(name, entry, socket, session, alive_now), ensure_ascii=False, indent=1))
+        sys.exit(0 if alive_now else 1)
+    zname = zmx_name('status', name)
+    row = next((r for r in describe() if r['id'] == zname), None)
+    if row:
+        row['hook'] = hook_agent(zname)   # lane-run's phase record stays `agent` (DEF-1436)
     print(json.dumps(row or {'id': name, 'running': False}, ensure_ascii=False, indent=1))
     sys.exit(0 if row else 1)
 
 
 def cmd_kill(args):
-    name = lane_id(args[0] if args else '')
-    result = zmx('kill', name)
-    for path in (META / f'{name}.json', STATE / f'{name}.json'):
+    name = lane_id(next((a for a in args if not a.startswith('--')), ''))
+    if '--yes' not in args:
+        sys.exit(f'lane kill: this ends the agent in {name} — confirm with --yes')
+    held = tmux_lane('kill', name)
+    target = name if held else zmx_name('kill', name)
+    if hook_agent(target).get('status') == 'working' and '--force' not in args:
+        sys.exit(f'lane kill: agent is working in {name} (its lane-signal hook says so); use --force')
+    if held:
+        _, socket, session = held
+        result = tmux_cmd(socket, 'kill-session', '-t', f'={session}')
+        stale = (HOOKS / f'{name}.json',) if result.returncode == 0 else ()
+    else:
+        result = zmx('kill', target)
+        stale = (META / f'{target}.json', STATE / f'{target}.json', HOOKS / f'{target}.json')
+    for path in stale:
         try:
             path.unlink()
         except OSError:
@@ -276,8 +482,86 @@ def cmd_kill(args):
     sys.exit(result.returncode)
 
 
+GC_USAGE = 'usage: lane gc --sockets   (unlink the tmux socket files in this container that no server listens on)'
+GC_PROBE_TIMEOUT = 5
+
+
+def tmux_socket_dir():
+    """Where this container's tmux servers put their sockets: $TMUX_TMPDIR (else /tmp) / tmux-<uid>, as tmux does."""
+    return Path(os.environ.get('TMUX_TMPDIR') or '/tmp') / f'tmux-{os.getuid()}'
+
+
+def socket_refused(path):
+    """True only when connecting to the AF_UNIX socket file `path` fails with ECONNREFUSED (the file is there, nobody
+    listens: its server is gone). Anything else — a server that accepts, EACCES, ENOENT (gone meanwhile), a timeout,
+    a path too long for sun_path — is False: keep the file."""
+    probe = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    probe.settimeout(GC_PROBE_TIMEOUT)
+    try:
+        probe.connect(str(path))
+    except ConnectionRefusedError:
+        return True
+    except OSError:
+        return False
+    finally:
+        probe.close()
+    return False
+
+
+def cmd_gc(args):
+    """`lane gc --sockets` (plan Task 18), explicit and in the container only — the host merely reports (`lanes
+    doctor`; the RUNBOOK NEVER rule). For each SOCKET file in tmux's directory one `tmux -N -S <path> list-sessions`
+    (-N: never start a server; no lane identity in its env): only a file tmux is REFUSED on (ECONNREFUSED — nobody
+    listens, its server is gone) is unlinked, and only if it is still the very file that was probed (a new server may
+    have taken the path meanwhile). A server that answers — even with no session — or that does not answer in time
+    keeps its file: a busy server is not a dead one. Prints each unlinked path.
+
+    Refusal is read from the errno, never from tmux's prose: tmux 3.4 words ECONNREFUSED as `no server running on
+    <path>` and uses `error connecting to <path> (<strerror>)` only for OTHER errnos (measured 2026-10-04: EACCES →
+    `(Permission denied)`, ENOENT → `(No such file or directory)`), so a 'connection refused' text match never fired
+    (DEF-1459). When tmux fails, `socket_refused` connects to the same path once and only ConnectionRefusedError
+    counts."""
+    if args != ['--sockets']:
+        sys.exit(GC_USAGE)
+    directory = tmux_socket_dir()
+    try:
+        entries = sorted(directory.iterdir())
+    except OSError as error:
+        print(f'lane gc --sockets: {directory}: {error.strerror or error} — nothing to do')
+        return
+    removed = kept = 0
+    for path in entries:
+        try:
+            before = path.lstat()
+        except OSError:
+            continue
+        if not stat.S_ISSOCK(before.st_mode):
+            continue
+        try:
+            result = subprocess.run(['tmux', '-N', '-S', str(path), 'list-sessions'], capture_output=True, text=True,
+                                    timeout=GC_PROBE_TIMEOUT, env=identity_free(os.environ))
+        except subprocess.TimeoutExpired:
+            print(f'kept {path}: no answer in {GC_PROBE_TIMEOUT} s')
+            kept += 1
+            continue
+        if result.returncode == 0 or not socket_refused(path):
+            kept += 1
+            continue
+        try:
+            after = path.lstat()
+        except OSError:
+            continue       # gone meanwhile: nothing to remove
+        if (after.st_dev, after.st_ino, after.st_ctime_ns) != (before.st_dev, before.st_ino, before.st_ctime_ns):
+            kept += 1      # another server bound the path after the probe: not the file tmux was refused on
+            continue
+        path.unlink()
+        print(f'unlinked {path}')
+        removed += 1
+    print(f'lane gc --sockets: {removed} unlinked, {kept} kept in {directory}')
+
+
 COMMANDS = {'new': cmd_new, 'open': cmd_open, 'attach': cmd_attach, 'send': cmd_send, 'capture': cmd_capture, 'ls': cmd_ls,
-            'status': cmd_status, 'kill': cmd_kill}
+            'status': cmd_status, 'kill': cmd_kill, 'gc': cmd_gc}
 
 if __name__ == '__main__':
     if len(sys.argv) < 2 or sys.argv[1] not in COMMANDS: