@vibelord/lanes 1.1.1 → 1.3.0

package/payload/lanes/container/lane

@@ -11,7 +11,9 @@ a `holder: tmux` lane through its exact socket and session; any other id is a zm
                               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; a tmux lane never nests inside tmux)
-  lane send <id> [--no-enter] <text...>   type into the lane. tmux: literally, then Enter unless --no-enter.
+  lane send <id> [--no-enter] <text...>   type into the lane. tmux: literally, then Enter unless --no-enter
+                              (a second tmux client half a second later: an agent's prompt takes text+Enter in one
+                              burst as a paste)
                               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] [--all]    zmx lanes with holder metadata; --all adds the registry's tmux lanes with `alive`
@@ -21,6 +23,22 @@ a `holder: tmux` lane through its exact socket and session; any other id is a zm
                               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
+  lane publish <file> [--title T] [--for <login>] [--kind md|html|svg|file]
+                              put the file on the Lanes docs page from the lane this runs in ($LANE_ID, else the tmux
+                              pane): writes ~/.lz/state/publish/<lane>/<id>.json (the file's container path, hashed
+                              once) and prints {id, …, picked_up_by, expected_within_s} as JSON; the host's lanes-docsd
+                              takes it within ~5 s and writes <id>.receipt.json beside it (kind from the extension when
+                              --kind is left out; the file must be under /home/coder, at most 32 MiB)
+  lane mcp install [--agent claude|codex|all] [--write]
+                              add the Lanes MCP server (~/.lz/bin/lane-mcp) to ~/.claude.json (mcpServers.lanes) and
+                              ~/.codex/config.toml ([mcp_servers.lanes], with env_vars passing LANE_ID, LANE_WS, TMUX
+                              and TMUX_PANE: Codex clears a server's environment): prints the diff; --write applies
+                              it, keeping <file>.bak-<UTC> first; an entry that is already there is left alone (a
+                              Codex table missing those env_vars gains them), one named `lanes` that starts something
+                              else is never replaced (exit 1). New agent sessions load it
+
+Every tmux client these verbs start runs with -N (never starts a server), without a lane identity in its
+environment and bounded in time (lane_core.py, shipped beside this file).
 """
 import json
 import os
@@ -34,6 +52,10 @@ import sys
 import time
 from pathlib import Path
 
+sys.dont_write_bytecode = True   # ~/.lz/bin holds no __pycache__
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import lane_core as C  # noqa: E402  (shipped beside this file by `lanes install-container`)
+
 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}'
@@ -41,8 +63,9 @@ 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-1572)
 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
+STATUSES = C.STATUSES     # agent_state.STATUSES
+HOOK_MAX_AGE = C.HOOK_MAX_AGE
+TMUX_TIMEOUT = 15
 
 
 def zmx_env(extra=None):
@@ -161,49 +184,32 @@ def registry_entry(lane):
     return lanes[lane]
 
 
-IDENTITY = ('LANE_ID', 'LANE_WS', 'THROTTLE_TRACE')   # + a lanes/ ANTHROPIC_CUSTOM_HEADERS (identity_free)
-
-
-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-1559). 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."""
-    return {k: v for k, v in environ.items() if k not in drop and k not in IDENTITY
-            and not (k == 'ANTHROPIC_CUSTOM_HEADERS' and v.startswith('x-throttle-trace: lanes/'))}
+IDENTITY = C.IDENTITY      # + a lanes/ ANTHROPIC_CUSTOM_HEADERS (identity_free)
+# `environ` without any lane identity: whatever tmux client STARTS a socket's server hands its whole environment to
+# the server's GLOBAL environment (MEASURED, tmux 3.4: DEF-1559), so identity reaches a lane's shell ONLY through `-e`
+# in its create recipe (lanes_lib.canonical_recipe). lane_core.identity_free keeps an operator's own header.
+identity_free = C.identity_free
+tmux_target = C.tmux_target   # (socket, session) of a registry entry held by tmux, else None
 
 
 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))
+    """One tmux client (lane_core.run_tmux): no lane identity in its env, stdin closed, exit 124 after
+    TMUX_TIMEOUT s without an answer."""
+    return C.run_tmux(argv, timeout=TMUX_TIMEOUT)
 
 
 def tmux_cmd(socket, *args):
-    return tmux_run(['tmux', '-L', socket, *args])
+    """`tmux -N -L <socket> ARGS…`: -N, so no query or attach ever starts a server (DEF-1797)."""
+    return tmux_run(C.tmux_argv(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:
+        return C.registry_lanes(ROOT)
+    except C.NewerVersion:
         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):
@@ -220,33 +226,20 @@ def zmx_name(verb, lane):
     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
+# tmux's argv parser ends a command at ONE trailing `;` of ANY argument: the last `;` is written `\\;`. 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). Every argv carries -N. A text and its Enter are two clients
+# ENTER_DELAY s apart (lane_core.send_keys): in one client they reach the pane as one read, which an agent's prompt
+# takes as a paste (DEF-1803).
+tmux_text, send_argvs, capture_argv = C.tmux_text, C.send_argvs, C.capture_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)."""
+    """attach-session; with ignore-size while the lanes view shows the lane (the lanes view owns the size). -N: when
+    the session's server ended after the has-session check, the attach fails instead of starting an empty server
+    that leaves a socket file behind (MEASURED, tmux 3.4: DEF-1797)."""
     clients = tmux_cmd(socket, 'list-clients', '-t', f'={session}', '-F', '#{client_termname}').stdout.split()
-    argv = ['tmux', '-L', socket, 'attach-session']
+    argv = C.tmux_argv(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}']
@@ -254,34 +247,8 @@ def tmux_attach_argv(socket, 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'}
+    `agent_state.read_sidecar_dict` judges it (lane_core.hook_agent). A crashed agent's last word is never an agent."""
+    return C.hook_agent(HOOKS, name, PROC)
 
 
 def cmd_open(args):
@@ -343,19 +310,19 @@ def cmd_send(args):
     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
+        results = C.send_keys(socket, session, text, enter, run=tmux_run)
+        sys.stderr.write(''.join(result.stderr for result in results))
+        if len(results) == 2 and results[1].returncode:
+            sys.stderr.write('lane send: the text was typed; Enter was not pressed\n')
+        sys.exit(results[-1].returncode)
+    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'
+    return C.last_lines(text, lines) or '\n'
 
 
 def cmd_capture(args):
@@ -560,8 +527,96 @@ def cmd_gc(args):
     print(f'lane gc --sockets: {removed} unlinked, {kept} kept in {directory}')
 
 
+MCP_USAGE = 'usage: lane mcp install [--agent claude|codex|all] [--write]'
+
+
+def cmd_mcp(args):
+    """`lane mcp install`: the agents' MCP entries for lane-mcp in THIS home (lane_core.mcp_plan / mcp_apply — the
+    code `lanes install-container` runs from the host). A dry run (the diffs) unless --write. Exit 1 when a file was
+    left alone (not valid JSON/TOML, or a `lanes` entry that starts something else) or lane-mcp is not installed."""
+    if not args or args[0] != 'install':
+        sys.exit(MCP_USAGE)
+    agents, write, rest = C.MCP_AGENTS, False, list(args[1:])
+    while rest:
+        word = rest.pop(0)
+        if word == '--agent' and rest and rest[0] in ('claude', 'codex', 'all'):
+            pick = rest.pop(0)
+            agents = C.MCP_AGENTS if pick == 'all' else (pick,)
+        elif word == '--write':
+            write = True
+        else:
+            sys.exit(MCP_USAGE)
+    home = Path.home()
+    binary = ROOT / 'bin' / 'lane-mcp'
+    missing = not os.access(str(binary), os.X_OK)
+    if missing:
+        print(f'! {binary} is not installed — on the host run: lanes install-container <container>')
+    refused = False
+    for item in C.mcp_plan(home, agents):
+        if item['why']:
+            refused = True
+            print(f"! {item['path']}: {item['why']}")
+        elif item['after'] == item['before']:
+            print(f"{item['path']}: the lanes MCP server is already there")
+        else:
+            sys.stdout.write(C.mcp_diff(item))
+    if not write:
+        print('dry run: nothing written (add --write to apply)')
+        sys.exit(1 if refused or missing else 0)
+    if missing:
+        sys.exit('lane mcp install: nothing written — an entry would start a lane-mcp that is not there')
+    added = False
+    for result in C.mcp_apply(home, agents):
+        if result['status'] == 'refused':
+            refused = True
+            print(f"! {result['path']}: {result['why']} — nothing written")
+        elif result['status'] == 'added':
+            added = True
+            if result['backup']:
+                print(f"backup {result['backup']}")
+            print(f"wrote {result['path']}")
+    if added:
+        print('new Claude Code and Codex sessions load it (a running session keeps its tools)')
+    sys.exit(1 if refused else 0)
+
+
+PUBLISH_USAGE = 'usage: lane publish <file> [--title T] [--for <login>] [--kind md|html|svg|file]'
+
+
+def cmd_publish(args):
+    """`lane publish` (plan W10 W4): lane_core.publish from the lane this process runs in (lane_core.whoami: $LANE_ID,
+    else the tmux pane) for the file named relative to the working directory. Prints the answer as JSON on stdout
+    (what lanes_publish answers) and one line for a person on stderr. A refusal is one stderr line, exit 1."""
+    options, rest, path = {}, list(args), None
+    while rest:
+        word = rest.pop(0)
+        if word in ('--title', '--for', '--kind'):
+            if not rest or word in options:
+                sys.exit(PUBLISH_USAGE)
+            options[word] = rest.pop(0)
+        elif word.startswith('--') or path is not None:
+            sys.exit(PUBLISH_USAGE)
+        else:
+            path = word
+    if path is None:
+        sys.exit(PUBLISH_USAGE)
+    found = C.whoami(ROOT, os.environ)
+    if not found['lane']:
+        sys.exit(f"lane publish: {found.get('why') or 'not inside a lane'}")
+    try:
+        out = C.publish(ROOT, Path(os.environ.get('HOME') or Path.home()), os.path.abspath(path), found['lane'],
+                        title=options.get('--title'), for_login=options.get('--for'), kind=options.get('--kind'))
+    except C.LaneError as error:
+        sys.exit(f'lane publish: {error}')
+    out.update(picked_up_by=C.PUBLISH_PICKUP, expected_within_s=C.PUBLISH_LATENCY_S)
+    print(json.dumps(out, ensure_ascii=False, indent=1))
+    sys.stderr.write(f"lane publish: {out['path']} ({out['kind']}, {out['bytes']} bytes) -> request {out['id']} of "
+                     f"{out['lane']}; {C.PUBLISH_PICKUP} takes it within ~{C.PUBLISH_LATENCY_S} s and answers in "
+                     f"{out['receipt']}\n")
+
+
 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, 'gc': cmd_gc}
+            'status': cmd_status, 'kill': cmd_kill, 'gc': cmd_gc, 'mcp': cmd_mcp, 'publish': cmd_publish}
 
 if __name__ == '__main__':
     if len(sys.argv) < 2 or sys.argv[1] not in COMMANDS:

package/payload/lanes/container/lane-edit

@@ -0,0 +1,100 @@
+#!/bin/sh
+# lane-edit — the editor Ctrl-Alt-e opens in a workspace container (W9 E3, LNS-97). Installed at ~/.lz/bin/lane-edit
+# by `lanes install-container`, next to ~/.lz/vimrc. `lanes edit --focused` (W9 E2, bin/lanes edit_argv) picks the
+# lane's file on the host and starts this with no shell in between:
+#     docker exec -it -u coder -w <checkout root> -e TERM=xterm-256color -e COLORTERM=truecolor -e LANG=C.UTF-8
+#         -e LANES_EDITOR=<choice or empty> -e LANES_EDIT_LABEL=<label> <container> /home/coder/.lz/bin/lane-edit <path>
+# usage: lane-edit <file>
+#
+#   * umask 077 first, so anything the editor creates (a swap file, a backup copy) is this account's alone. A file
+#     written in place keeps its own mode and owner.
+#   * The editor: $LANES_EDITOR when it names a program on PATH — one word, a name or an absolute path, never a
+#     command line: no arguments, no shell — else the first of micro hx nvim vim vi on PATH. Lanes installs no
+#     editor; vi is the floor. A $LANES_EDITOR that names nothing is said on stderr, and the list decides.
+#   * vim and nvim — by name, or a vi that is vim behind a link (Debian's alternatives) — start with
+#     `-u ~/.lz/vimrc` when it is there: written in place, swap and backup files under ~/.lz/tmp/ (created here,
+#     0700) instead of beside the file in the checkout, no modelines, no added final newline, no viminfo.
+#   * One header line, `editing <label> · <directory> · <how to finish>` ($LANES_EDIT_LABEL, else the file's name;
+#     control characters dropped), then the editor replaces this shell: its exit status is lane-edit's, and
+#     quitting it closes the floating pane.
+#   * The file reaches the editor as one argv word; one that starts with `-` goes as ./<name>, never as an option.
+# Exit: the editor's status; 2 usage; 127 no editor on PATH. Both refusals wait for Enter on a terminal first, as
+# `lanes edit` does on the host: the pane (close_on_exit) would take the message with it.
+umask 077
+set -u
+
+hold() {  # the Edit pane closes the moment this exits: on a terminal, let a refusal be read first
+    if [ -t 0 ]; then
+        printf '\nPress Enter to close.' >&2
+        read -r _ || :
+    fi
+}
+
+if [ $# -ne 1 ] || [ -z "$1" ]; then
+    echo 'usage: lane-edit <file>' >&2
+    hold
+    exit 2
+fi
+file=$1
+case $file in -*) file=./$file ;; esac
+root=${HOME:-/home/coder}/.lz
+candidates='micro hx nvim vim vi'
+editor='' note='' vim=''
+
+clean() {  # $1 without control characters: a label or a directory never moves the cursor or retitles the terminal
+    printf '%s' "$1" | tr -d '\000-\037\177'
+}
+
+program() {  # the absolute path of the program $1 names on PATH; nothing for a builtin, function, folder or plain file
+    found=$(command -v -- "$1" 2>/dev/null) || return 1
+    case $found in
+        /*) [ -f "$found" ] && [ -x "$found" ] && printf '%s' "$found" ;;
+        *) return 1 ;;
+    esac
+}
+
+vim_named() {  # whether the basename of $1 is vim or nvim (vim.basic, vim.tiny, nvim.appimage too)
+    case ${1##*/} in vim | vim.* | nvim | nvim.*) return 0 ;; esac
+    return 1
+}
+
+if [ -n "${LANES_EDITOR:-}" ]; then
+    editor=$(program "$LANES_EDITOR") || editor=
+    if [ -z "$editor" ]; then
+        note="lane-edit: LANES_EDITOR=$(clean "$LANES_EDITOR") is not a program on PATH"
+    fi
+fi
+if [ -z "$editor" ]; then
+    for name in $candidates; do
+        editor=$(program "$name") && break
+        editor=
+    done
+    if [ -n "$note" ]; then
+        if [ -n "$editor" ]; then echo "$note; using ${editor##*/}" >&2; else echo "$note" >&2; fi
+    fi
+fi
+if [ -z "$editor" ]; then
+    echo "lane-edit: no editor on PATH: set LANES_EDITOR, or install one of $candidates in this container" >&2
+    hold
+    exit 127
+fi
+
+if vim_named "$editor" || vim_named "$(readlink -f "$editor" 2>/dev/null)"; then
+    vim=1
+fi
+case ${editor##*/} in
+    micro) finish='Ctrl-s, Ctrl-q to finish' ;;
+    vi | hx) finish=':wq to finish' ;;
+    *) if [ -n "$vim" ]; then finish=':wq to finish'; else finish='save and quit to finish'; fi ;;
+esac
+
+label=${LANES_EDIT_LABEL:-}
+[ -n "$label" ] || label=${1##*/}
+printf 'editing %s · %s · %s\n' "$(clean "$label")" "$(clean "$PWD")" "$finish"
+
+if [ -n "$vim" ] && [ -r "$root/vimrc" ]; then
+    mkdir -p "$root/tmp" 2>/dev/null
+    chmod 700 "$root/tmp" 2>/dev/null
+    exec "$editor" -u "$root/vimrc" "$file"
+fi
+exec "$editor" "$file"