@vibelord/lanes 1.0.0 → 1.0.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):
@@ -148,9 +161,127 @@ 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-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."""
+    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/'))}
+
+
+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 = {k: v for k, v in os.environ.items() if k != 'TMUX'}
-    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):
@@ -159,7 +290,10 @@ def cmd_open(args):
     entry = registry_entry(args[0])
     if os.environ.get('TMUX') and '--force' not in args:
         sys.exit(f"lane open: already inside tmux — refusing to nest. The lane is: {json.dumps(entry.get('tmux') or entry.get('zmx'))}")
-    env = {k: v for k, v in os.environ.items() if k not in ('TMUX', 'TMUX_PANE')}
+    # 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-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']
         if alive(name):
@@ -167,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())
@@ -188,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.
@@ -195,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 = {}
@@ -226,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:
@@ -259,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:

package/payload/lanes/container/lane-signal

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""lane-signal <status> [--event NAME] [--harness claude|codex] [PAYLOAD] — the hook target of Claude Code and Codex
+inside a workspace container. Writes ~/.lz/state/hooks/<lane id>.json (atomic replace), which the host's
+lanes-statusd reads through /proc/<container init pid>/root and publishes as the lane's `agent{}` (source `hook`).
+
+The sidecar has its own directory because `lane-run`, the root process of every zmx-held lane, writes its
+`{phase, exit, at, pid}` record to ~/.lz/state/<zmx name>.json and exports LANE_ID=<zmx name> to the agent: a
+sidecar at state/<lane id>.json would overwrite that record for the agent's whole life (DEF-1436). Nothing but
+this script writes state/hooks/, and lane-run never writes there.
+
+    {"v":1, "lane":"<id>", "harness":"claude|codex", "status":"<agent{} vocabulary>", "since":<epoch the status
+     began>, "at":<epoch of this event>, "event":"<hook event>", "pid":<agent pid>, "start":"<its starttime>",
+     "session":"<session/thread id or ''>"}
+
+It never fails the agent and never speaks: every path exits 0 and nothing reaches stdout or stderr (a Claude Code
+UserPromptSubmit/SessionStart hook's stdout becomes model context). An unresolvable lane, a status outside the
+vocabulary or an unwritable state directory are silent no-ops.
+
+Lane id: $LANE_ID — exported in a tmux lane only by a canonical/`--identity` recipe's `-e` flags (Task 7, DEF-1478;
+`lane open` never exports it), and in a zmx-held lane by `lane-run` as the zmx session name (which is NOT the
+`<ws>--z-<name>` id lanes-statusd publishes for it, so statusd does not join that sidecar to the zmx lane yet:
+DEF-1437) — else the pane's tmux session (`tmux -S ${TMUX%%,*} display -p -t $TMUX_PANE '#S'`) looked up by (socket
+name, session) in ~/.lz/registry.json, the projection `lanes sync` writes.
+
+Agent pid: the parent process, or that parent's parent when the parent is a shell (Claude Code runs a hook command
+through a shell, which may fork it rather than exec it; a pid that dies with the shell would read as a dead agent).
+Session id: `session_id` of the hook's JSON on stdin, `thread-id` of a JSON PAYLOAD argument (Codex `notify` passes
+its JSON as the last argument), else $CLAUDE_SESSION_ID / $CODEX_THREAD_ID. Stdin is read only when it is not a
+terminal and for at most STDIN_WAIT seconds: a stdin that never closes cannot hang the hook.
+
+Same status as the file already holds (same session) keeps `since` and advances `at`; a new status starts `since`.
+"""
+import json
+import os
+import re
+import select
+import subprocess
+import sys
+import time
+
+STATUSES = ('working', 'needs_input', 'needs_approval', 'done', 'errored', 'shell', 'idle')   # agent_state.STATUSES
+LANE_ID = re.compile(r'[A-Za-z0-9][A-Za-z0-9_.-]{0,127}')
+SHELLS = {'sh', 'dash', 'bash', 'zsh', 'ksh', 'fish'}
+STDIN_WAIT = 0.5
+STDIN_MAX = 1 << 20
+
+
+def options(argv):
+    status, event, harness, payload = (argv[0] if argv else ''), '', '', ''
+    rest = argv[1:]
+    while rest:
+        word = rest.pop(0)
+        if word == '--event' and rest:
+            event = rest.pop(0)
+        elif word == '--harness' and rest:
+            harness = rest.pop(0)
+        elif word.startswith('{'):
+            payload = word
+    return status, event[:64], harness[:16], payload
+
+
+def lane_id(root):
+    found = os.environ.get('LANE_ID', '')
+    if not found and os.environ.get('TMUX') and os.environ.get('TMUX_PANE'):
+        sock = os.environ['TMUX'].split(',', 1)[0]
+        try:
+            done = subprocess.run(['tmux', '-S', sock, 'display', '-p', '-t', os.environ['TMUX_PANE'], '#S'],
+                                  stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=1)
+            session = done.stdout.strip() if done.returncode == 0 else ''
+            lanes = json.load(open(os.path.join(root, 'registry.json'))).get('lanes') or {}
+        except (OSError, ValueError, subprocess.SubprocessError, AttributeError):
+            return ''
+        name = os.path.basename(sock)
+        for key, lane in lanes.items():
+            tmux = (lane or {}).get('tmux') or {}
+            if session and tmux.get('socket') == name and tmux.get('session') == session:
+                found = key
+                break
+    return found if LANE_ID.fullmatch(found or '') else ''
+
+
+def stat_fields(pid):
+    """Fields after `comm` of /proc/<pid>/stat (state is [0], ppid [1], starttime [19]) and the comm itself."""
+    with open(f'/proc/{pid}/stat') as handle:
+        text = handle.read()
+    comm = text[text.index('(') + 1:text.rindex(')')]
+    return comm, text.rsplit(')', 1)[1].split()
+
+
+def agent():
+    pid = os.getppid()
+    try:
+        comm, fields = stat_fields(pid)
+        if comm in SHELLS and int(fields[1]) > 1:
+            pid = int(fields[1])
+            comm, fields = stat_fields(pid)
+        return pid, fields[19]
+    except (OSError, ValueError, IndexError):
+        return pid, None
+
+
+def stdin_session():
+    try:
+        if os.isatty(0):
+            return ''
+    except OSError:
+        return ''
+    data, deadline = b'', time.monotonic() + STDIN_WAIT
+    try:
+        while len(data) < STDIN_MAX:
+            left = deadline - time.monotonic()
+            if left <= 0 or not select.select([0], [], [], left)[0]:
+                break
+            chunk = os.read(0, 65536)
+            if not chunk:
+                break
+            data += chunk
+        doc = json.loads(data.decode('utf-8', 'replace')) if data.strip() else {}
+    except (OSError, ValueError):
+        return ''
+    return str(doc.get('session_id') or '') if isinstance(doc, dict) else ''
+
+
+def main(argv):
+    status, event, harness, payload = options(argv)
+    if status not in STATUSES:
+        return
+    root = os.environ.get('LANE_ROOT') or os.path.join(os.path.expanduser('~'), '.lz')
+    lane = lane_id(root)
+    if not lane:
+        return
+    session = stdin_session()
+    if not session and payload:
+        try:
+            doc = json.loads(payload)
+            session = str(doc.get('thread-id') or doc.get('session_id') or '') if isinstance(doc, dict) else ''
+        except ValueError:
+            session = ''
+    session = session or os.environ.get('CLAUDE_SESSION_ID') or os.environ.get('CODEX_THREAD_ID') or ''
+    harness = harness or os.environ.get('LANE_HARNESS') or ('claude' if os.environ.get('CLAUDE_CODE_ENTRYPOINT')
+                                                            else 'codex')
+    pid, start = agent()
+    now = int(time.time())
+    state = os.path.join(root, 'state', 'hooks')   # never state/<id>.json: lane-run's phase record (DEF-1436)
+    path = os.path.join(state, f'{lane}.json')
+    try:
+        old = json.load(open(path))
+    except (OSError, ValueError):
+        old = None
+    session, since = session[:128], now
+    if (isinstance(old, dict) and old.get('v') == 1 and old.get('status') == status
+            and (not session or old.get('session') == session) and isinstance(old.get('since'), int)):
+        since, session = old['since'], session or str(old.get('session') or '')
+    doc = {'v': 1, 'lane': lane, 'harness': harness, 'status': status, 'since': since, 'at': now, 'event': event,
+           'pid': pid, 'start': start, 'session': session}
+    os.makedirs(state, exist_ok=True)
+    tmp = os.path.join(state, f'.{lane}.json.{os.getpid()}.tmp')
+    try:
+        with open(tmp, 'w') as handle:
+            handle.write(json.dumps(doc, separators=(',', ':')) + '\n')
+        os.replace(tmp, path)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+
+
+if __name__ == '__main__':
+    try:
+        sys.stdout = sys.stderr = open(os.devnull, 'w')
+        main(sys.argv[1:])
+    except BaseException:   # noqa: BLE001 - a hook must never fail the agent: every outcome is exit 0
+        pass
+    os._exit(0)