@vibelord/lanes 1.1.0 → 1.2.0

package/payload/lanes/container/lane_core.py

@@ -0,0 +1,1140 @@
+"""lane_core — what the in-container lane contract shares: `lane`, `lane-mcp` (both under ~/.lz/bin) and, on the host,
+`lanes install-container`, which writes the agents' MCP entries through the same code (LNS-34).
+
+Python 3.9+ stdlib only (the host's floor; containers run 3.12). Nothing here prints: callers decide what a person
+sees, and `lane-mcp` may write nothing but protocol frames to its stdout.
+
+  * readers of the two host projections in ~/.lz: `registry.json` (`lanes sync`; DM-LANES-REGISTRY) and
+    `status.json` (`lanes-statusd`; DM-LANES-CONTAINER-STATUS). A newer `version`/`v` is refused (NewerVersion),
+    never half-read.
+  * one tmux runner: every client runs with `-N` (never start a server: MEASURED, tmux 3.4, `attach-session` on a
+    socket nobody serves starts one and leaves its socket file behind; DEF-1797), without a lane identity in its
+    environment (DEF-1559), with stdin closed (lane-mcp's stdin is its protocol stream) and bounded in time (exit
+    124 when tmux does not answer, 127 when it cannot start). Targets are `=<session>:` (a bare `=<session>` is
+    refused by send-keys and capture-pane). A text and its Enter are two clients ENTER_DELAY s apart (send_keys,
+    DEF-1803); the one client allowed to start a server (`lanes_new`) gets creation_env(), an allow-list (DEF-1802).
+  * whoami: $LANE_ID, else the pane's session (`display -p -t $TMUX_PANE '#S'` on $TMUX's socket) matched in the
+    registry, then among the container's unregistered sessions. Codex clears an MCP server's environment, so its
+    entry passes these through (`env_vars`, MCP_ENV_VARS); Claude Code's servers inherit them.
+  * the terminals.json minimal editor: strict JSON only, every byte outside the edited span kept, re-read before the
+    write (one retry when the file changed meanwhile), atomic replace; never the root `throttle` object, never a
+    terminal's `name`, never a reorder, never the last terminal. lane-mcp's write tools (LNS-35) and, on the host,
+    `session_actions.unregister_declared` (the sidebar's `u` on a declared lane) edit through it.
+  * the host's lane-id and recipe rules, ported so the container can predict what `lanes sync` will publish: `slug`,
+    `shown_key`, `lane_trace`, `canonical_recipe`, the id grammar (each pinned equal to its lanes_lib original by
+    test_lane_mcp_write.HostRules), and `declared_name`, which finds a registry lane's declared terminal in its file.
+  * the agents' MCP entries: `mcpServers.lanes` in ~/.claude.json and `[mcp_servers.lanes]` (command + env_vars) in
+    ~/.codex/config.toml, planned as a diff, written with a `.bak-<UTC>` copy, atomically and only when missing.
+"""
+import difflib
+import json
+import os
+import pwd
+import re
+import shlex
+import stat
+import subprocess
+import tempfile
+import time
+import unicodedata
+from pathlib import Path
+
+CONTAINER_HOME = '/home/coder'
+LZ = CONTAINER_HOME + '/.lz'
+LANE_RE = re.compile(r'[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}')   # host lanes_lib.IDENT, bounded
+STATUSES = ('working', 'needs_input', 'needs_approval', 'done', 'errored', 'shell', 'idle')   # agent_state.STATUSES
+NEEDS_YOU = ('needs_approval', 'errored', 'needs_input')   # the sidebar's "Needs you" section (sidebar.ATTENTION)
+HOOK_MAX_AGE = 3600       # statusd.SIDECAR_MAX_AGE: an older last event is no agent
+STATUS_FRESH = 60         # status.json `at` is renewed at least every 15 s (statusd.HEARTBEAT); older = not live
+READ_MAX = 16 << 20       # a projection bigger than this is not ours
+TMUX_TIMEOUT = 5
+IDENTITY = ('LANE_ID', 'LANE_WS', 'THROTTLE_TRACE')   # + a lanes/ ANTHROPIC_CUSTOM_HEADERS (identity_free)
+
+
+class LaneError(Exception):
+    """A refusal with a sentence a person (or an agent) can act on, and, where a caller branches on it, a machine
+    `code` (lane-mcp's write tools answer it as `refused`; the editors below name theirs)."""
+
+    def __init__(self, message, code=None):
+        super().__init__(message)
+        self.code = code
+
+
+class NewerVersion(LaneError):
+    """A projection written by a newer Lanes than this contract: refreshed by `lanes install-container`."""
+
+    def __init__(self, message):
+        super().__init__(message, 'contract_outdated')
+
+
+# ------------------------------------------------------------------------------------------------ reading files
+
+def read_regular(path, limit=READ_MAX):
+    """The bytes of a regular file, or None (missing, a symbolic link, not a regular file, unreadable). Opened
+    non-blocking and without following a link: a FIFO planted at the name can never hang a reader; a file bigger than
+    `limit` is not read whole (None)."""
+    try:
+        fd = os.open(str(path), os.O_RDONLY | os.O_NONBLOCK | getattr(os, 'O_NOFOLLOW', 0) | getattr(os, 'O_CLOEXEC', 0))
+    except OSError:
+        return None
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode) or info.st_size > limit:
+            return None
+        chunks, size = [], 0
+        while True:
+            chunk = os.read(fd, 1 << 16)
+            if not chunk:
+                return b''.join(chunks)
+            size += len(chunk)
+            if size > limit:
+                return None
+            chunks.append(chunk)
+    except OSError:
+        return None
+    finally:
+        os.close(fd)
+
+
+def read_json(path):
+    """A JSON document from a regular file, or None (missing, unreadable, not JSON)."""
+    data = read_regular(path)
+    if data is None:
+        return None
+    try:
+        return json.loads(data.decode('utf-8'))
+    except ValueError:
+        return None
+
+
+def registry_lanes(root):
+    """{lane id: entry} of <root>/registry.json — what `lanes sync` places in this container (declared and registered
+    lanes). {} when there is none yet (a zmx-only container needs none). A newer registry raises NewerVersion."""
+    data = read_json(Path(root) / 'registry.json')
+    if not isinstance(data, dict):
+        return {}
+    try:
+        version = int(data.get('version', 1))
+    except (TypeError, ValueError):
+        return {}
+    if version > 1:
+        raise NewerVersion('the registry is newer than this `lane` — on the host run: lanes install-container <container>')
+    lanes = data.get('lanes')
+    if not isinstance(lanes, dict):
+        return {}
+    return {key: value for key, value in lanes.items() if isinstance(value, dict) and LANE_RE.fullmatch(key)}
+
+
+def container_status(root, now=None):
+    """<root>/status.json, the slice of statusd's observation the host writes into this container:
+    {'available', 'why'?, 'at', 'age', 'fresh', 'lanes': {id: row}, 'unregistered': [row]}. `fresh` is False once
+    `at` is older than STATUS_FRESH (statusd renews it every 15 s while it runs). A newer `v` raises NewerVersion."""
+    now = time.time() if now is None else now
+    data = read_json(Path(root) / 'status.json')
+    if not isinstance(data, dict):
+        return {'available': False, 'why': 'no ~/.lz/status.json yet: the host\'s lanes-statusd writes it within a few '
+                'seconds of `lanes install-container` and `lanes sync`', 'at': None, 'age': None, 'fresh': False,
+                'lanes': {}, 'unregistered': []}
+    try:
+        version = int(data.get('v', 1))
+        at = float(data.get('at'))
+    except (TypeError, ValueError):
+        version, at = 1, None
+    if version > 1:
+        raise NewerVersion('~/.lz/status.json is newer than this contract — on the host run: '
+                           'lanes install-container <container>')
+    lanes = data.get('lanes') if isinstance(data.get('lanes'), dict) else {}
+    ghosts = [row for row in data.get('unregistered') or [] if isinstance(row, dict) and row.get('id')]
+    age = None if at is None else max(0, round(now - at, 1))
+    return {'available': True, 'at': at, 'age': age, 'fresh': age is not None and age <= STATUS_FRESH,
+            'lanes': {key: value for key, value in lanes.items() if isinstance(value, dict)}, 'unregistered': ghosts}
+
+
+def hook_agent(hooks_dir, name, proc=Path('/proc')):
+    """The lane's `lane-signal` sidecar (<hooks_dir>/<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((Path(hooks_dir) / 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:
+            text = (Path(proc) / str(pid) / 'stat').read_text()
+        except OSError:
+            return {}
+        if d.get('start') is not None:
+            fields = text.rsplit(')', 1)[-1].split()
+            if len(fields) < 20 or fields[19] != str(d['start']):
+                return {}
+    agent = {'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'}
+    if isinstance(d.get('name'), str) and d['name']:
+        agent['name'] = d['name']   # the agent's own note (lanes_signal), which the host shows as its task line
+    return agent
+
+
+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
+
+
+# ------------------------------------------------------------------------------------------------ the tmux runner
+
+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.
+    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_env(environ=None):
+    """The environment of every tmux client: the caller's, without a lane identity and without TMUX/TMUX_PANE."""
+    return identity_free(os.environ if environ is None else environ, drop=('TMUX', 'TMUX_PANE'))
+
+
+def tmux_argv(socket, *args):
+    """`tmux -N -L <socket> ARGS…` — -N: a client never starts a server (DEF-1797)."""
+    return ['tmux', '-N', '-L', socket, *args]
+
+
+def target(session):
+    """The exact session, its current window: `=<session>:` (a bare `=<session>` is refused by send-keys and
+    capture-pane with "can't find pane", MEASURED tmux 3.4)."""
+    return f'={session}:'
+
+
+def run_tmux(argv, timeout=None, env=None):
+    """One tmux client -> subprocess.CompletedProcess. Never raises: exit 124 when tmux did not answer within
+    `timeout` seconds (default TMUX_TIMEOUT), 127 when it could not be started. stdin is closed, stdout/stderr captured (bytes that are not
+    UTF-8 become U+FFFD: a pane's output never breaks the caller). `env` defaults to tmux_env() (creation_env() for
+    the one client that may start a server)."""
+    timeout = TMUX_TIMEOUT if timeout is None else timeout
+    try:
+        return subprocess.run(argv, capture_output=True, text=True, errors='replace', timeout=timeout,
+                              env=tmux_env() if env is None else env, stdin=subprocess.DEVNULL)
+    except subprocess.TimeoutExpired:
+        return subprocess.CompletedProcess(argv, 124, '', f'tmux did not answer within {timeout} s\n')
+    except OSError as error:
+        return subprocess.CompletedProcess(argv, 127, '', f'tmux could not start: {error.strerror or error}\n')
+
+
+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
+
+
+ENTER_DELAY = 0.5   # seconds between the typed text and its Enter (send_keys)
+
+
+def send_argvs(socket, session, text, enter=True):
+    """The tmux clients that type `text` literally into the session's active pane and then press Enter: the text,
+    then Enter as a SECOND client. One client (`send-keys -l -- TEXT ; send-keys Enter`) hands the program in the
+    pane the text and the CR in a single read (MEASURED, tmux 3.4: a raw-mode reader got b'please run the tests\\r' in
+    one chunk), and an agent's prompt reads a multi-character chunk as a paste, CR included, so the turn never starts
+    (DEF-1803). send_keys runs them ENTER_DELAY seconds apart."""
+    typed = tmux_argv(socket, 'send-keys', '-t', target(session), '-l', '--', tmux_text(text))
+    return [typed, tmux_argv(socket, 'send-keys', '-t', target(session), 'Enter')] if enter else [typed]
+
+
+def pause(seconds):
+    """time.sleep, named so a test can record the pause between a text and its Enter instead of waiting it out."""
+    time.sleep(seconds)
+
+
+def send_keys(socket, session, text, enter=True, run=None):
+    """Type `text` (send_argvs), wait ENTER_DELAY seconds, press Enter -> [CompletedProcess, …] of the clients that
+    ran: it stops at the first that fails, so one result that failed means nothing was typed, and a failed second
+    means the text was typed without its Enter. `run` is the caller's tmux runner (default run_tmux)."""
+    run = run or run_tmux
+    results = []
+    for argv in send_argvs(socket, session, text, enter):
+        if results:
+            pause(ENTER_DELAY)
+        results.append(run(argv))
+        if results[-1].returncode:
+            break
+    return results
+
+
+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_argv(socket, 'capture-pane', '-p', '-J', '-S', f'-{lines}' if lines else '-', '-t', target(session))
+    return argv + ['-e'] if vt else argv
+
+
+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' if rows else ''
+
+
+def new_session_argv(socket, session, cwd, lane_id, ws, command):
+    """The one tmux client lane-mcp runs WITHOUT -N (`lanes_new`): it creates the session, and starts the socket's
+    server when none runs. The lane's identity reaches the session only through these `-e` flags, the canonical
+    recipe's four (the client's own environment is creation_env(), an allow-list: whatever client starts a server
+    hands its environment to every later session there, DEF-1559, DEF-1802). `command` is one shell-command string,
+    run by the server's default shell like the recipe's command."""
+    trace = lane_trace(lane_id, ws)
+    if trace is None:
+        raise LaneError(f'invalid lane trace: lanes/{ws}/{lane_id}', 'invalid_name')
+    return ['tmux', '-L', socket, 'new-session', '-d', '-s', session, '-x', '100', '-y', '30', '-c', cwd,
+            '-e', f'LANE_ID={lane_id}', '-e', f'LANE_WS={ws}',
+            '-e', f'ANTHROPIC_CUSTOM_HEADERS=x-throttle-trace: {trace}', '-e', f'THROTTLE_TRACE={trace}', command]
+
+
+CREATION_ENV = ('HOME', 'USER', 'LOGNAME', 'PATH', 'LANG', 'LANGUAGE', 'TZ', 'TMUX_TMPDIR')   # and every LC_*
+CREATION_FIXED = {'TERM': 'xterm-256color', 'COLORTERM': 'truecolor'}   # session_actions.new_shell's two `-e`
+
+
+def creation_env(environ=None):
+    """The environment of the one client that may start a tmux server (`lanes_new`): an ALLOW-LIST, never the caller's
+    environment minus a deny-list (DEF-1802). The client that starts a socket's server hands its whole environment to
+    the server's global environment, and every later session there inherits it (DEF-1559). lane-mcp runs with the
+    AGENT's environment: under Claude Code that holds CLAUDECODE, CLAUDE_CODE_SESSION_ID, CLAUDE_CODE_ENTRYPOINT,
+    CLAUDE_CODE_MESSAGING_SOCKET/TOKEN, ANTHROPIC_API_KEY and ANTHROPIC_BASE_URL (MEASURED in a Claude Code MCP server's
+    /proc/<pid>/environ, 2026-10-06), none of which may reach the shells a person later opens on that board.
+
+    The host's twin, `session_actions.new_shell`, starts the same `lanes-shells-<ws>` server through `docker exec -e
+    TERM=xterm-256color -e COLORTERM=truecolor`, i.e. the container's own environment and nothing of the operator's
+    shell. This builds the nearest equivalent from inside: the account and locale names in CREATION_ENV, every `LC_*`,
+    TMUX_TMPDIR when set (the socket directory), a UTF-8 LANG where the caller has none (Codex clears an MCP server's
+    environment), HOME from the password database where the caller has none, and the host's TERM and COLORTERM. A login
+    shell in the new session reads the profiles (and ~/.lz/env.sh) itself; no lane identity is in the list, so
+    `ANTHROPIC_CUSTOM_HEADERS` — an operator's own included — never reaches the server either."""
+    environ = os.environ if environ is None else environ
+    env = {key: value for key, value in environ.items()
+           if value and (key in CREATION_ENV or (key.startswith('LC_') and re.fullmatch(r'LC_[A-Z]+', key)))}
+    env.setdefault('LANG', 'C.UTF-8')
+    if 'HOME' not in env:
+        try:
+            env['HOME'] = pwd.getpwuid(os.getuid()).pw_dir
+        except KeyError:
+            env['HOME'] = CONTAINER_HOME
+    env.update(CREATION_FIXED)
+    return env
+
+
+# ------------------------------------------------------------------------------------------------ the host's rules
+# Ports of lanes_lib's (the host's) rules, so a write tool in the container can predict what `lanes sync` will
+# publish. Each is pinned equal to its original by test_lane_mcp_write.HostRules; change both or neither.
+
+IDENT = re.compile(r'^[A-Za-z0-9_][A-Za-z0-9_.-]*\Z')          # lanes_lib.IDENT: ids, workspaces, sockets
+TMUX_SESSION = re.compile(r'^[A-Za-z0-9_][A-Za-z0-9_. -]*\Z')   # lanes_lib.TMUX_SESSION: a declarable session name
+SAFE_PATH = re.compile(r'^/[A-Za-z0-9_./-]+\Z')                 # lanes_lib.SAFE_PATH: a lane folder
+TRACE = re.compile(r'[A-Za-z0-9._/-]{1,256}')                   # lanes_lib.TRACE: the proxy's x-throttle-trace
+LANE_OPEN_COMMAND = 'exec ' + LZ + '/bin/lane open '            # cursor_sync.ENTRY: a terminal's uniform command
+SHELL_SOCKET = 'lanes-shells-'                                  # session_actions.shell_socket(<ws>): a board's shells
+NAME_MAX = 128                                                  # a lane name or display name, at most
+
+
+def slug(text):
+    """lanes_lib.slug: ASCII letters and digits of the NFKD form, every other run one `-`, lower case; `lane` when
+    nothing is left. A declared lane's id is `<ws>--<slug(prefix + terminal name)>` (lanes_lib.lane_id_for)."""
+    text = unicodedata.normalize('NFKD', text).encode('ascii', 'ignore').decode()
+    text = re.sub(r'[^A-Za-z0-9]+', '-', text).strip('-').lower()
+    return text or 'lane'
+
+
+def shown_key(value):
+    """lanes_lib._shown_key: a name as a row reads it (NFKC, invisible format characters dropped, whitespace runs
+    collapsed). Two names with one key are two rows nobody can tell apart."""
+    text = ''.join(ch for ch in unicodedata.normalize('NFKC', value) if unicodedata.category(ch) != 'Cf')
+    return ' '.join(text.split())
+
+
+def lane_trace(lane_id, ws):
+    """lanes_lib.lane_trace: `lanes/<ws>/<id>`, or None when the proxy would reject it."""
+    if not isinstance(ws, str) or not isinstance(lane_id, str):
+        return None
+    trace = f'lanes/{ws}/{lane_id}'
+    return trace if TRACE.fullmatch(trace) else None
+
+
+def canonical_recipe(lane_id, ws, socket, session, folder, cmd='bash -l'):
+    """lanes_lib.canonical_recipe: the create recipe that gives a new tmux lane its identity (LANE_ID, LANE_WS, the
+    lanes/<ws>/<id> trace as ANTHROPIC_CUSTOM_HEADERS and THROTTLE_TRACE) through `-e` flags; `new -A` attaches when
+    the session exists. LaneError where the host raises LanesError."""
+    trace = lane_trace(lane_id, ws)
+    if trace is None:
+        raise LaneError(f'Invalid lane trace: lanes/{ws}/{lane_id} (allowed: A-Z a-z 0-9 . _ - /, at most 256)',
+                        'invalid_name')
+    if not isinstance(socket, str) or not IDENT.match(socket):
+        raise LaneError(f'Invalid tmux socket: {socket!r}', 'invalid_session')
+    if not isinstance(session, str) or not TMUX_SESSION.match(session):
+        raise LaneError(f'Invalid tmux session: {session!r}', 'invalid_session')
+    if not isinstance(folder, str) or not folder.startswith('/'):
+        raise LaneError(f'Invalid lane folder: {folder!r}', 'invalid_cwd')
+    if not isinstance(cmd, str) or not cmd.strip():
+        raise LaneError('Invalid lane command', 'invalid_command')
+    header = shlex.quote(f'x-throttle-trace: {trace}')
+    return (f'tmux -L {shlex.quote(socket)} new -ADs {shlex.quote(session)} -c {shlex.quote(folder)} '
+            f'-e LANE_ID={lane_id} -e LANE_WS={ws} -e ANTHROPIC_CUSTOM_HEADERS={header} '
+            f'-e THROTTLE_TRACE={trace} {cmd}')
+
+
+def lane_name_problem(name):
+    """Why `name` cannot name a lane, or None: one line (no control character), no leading or trailing space, at most
+    NAME_MAX characters, valid UTF-8 (no lone surrogate), at least one letter or digit A–Z/0–9 (the id is made of
+    them: a name without any would get the id `<ws>--lane`)."""
+    if not isinstance(name, str) or not name:
+        return 'a name is needed'
+    if any(unicodedata.category(ch) in ('Cc', 'Cs') for ch in name):
+        return 'a name is one line of text: no control characters'
+    if name != name.strip():
+        return 'no leading or trailing spaces'
+    if len(name) > NAME_MAX:
+        return f'at most {NAME_MAX} characters'
+    if not shown_key(name):
+        return 'a name must read as something (not only invisible characters)'
+    if not re.search(r'[A-Za-z0-9]', unicodedata.normalize('NFKD', name).encode('ascii', 'ignore').decode()):
+        return 'a name needs at least one letter or digit A-Z/0-9: the lane id is made of them'
+    return None
+
+
+def _binding(entry):
+    """(socketName, sessionName) of a terminals.json binding object, else None."""
+    tmux = entry.get('tmux') if isinstance(entry, dict) else None
+    if not isinstance(tmux, dict):
+        return None
+    pair = (tmux.get('socketName'), tmux.get('sessionName'))
+    return pair if all(isinstance(part, str) and part for part in pair) else None
+
+
+def declared_name(doc, entry):
+    """The DECLARED terminal name (its `terminals[].name`) of a registry entry in its parsed terminals.json, or None.
+    First the `lanes.terminals` entry bound to the lane's tmux socket and session (`lanes cursor-sync` writes one per
+    terminal), then the root `throttle` block's binding, then the one terminal whose name ends the entry's
+    `registry_name` (prefix + declared name). None when none of these names exactly one terminal: a binding the host
+    keeps in the board's manifest (bindingOverrides/Recoveries) is not visible from here."""
+    try:
+        names = [name for name in _terminal_names(doc) if isinstance(name, str) and name]
+    except LaneError:
+        return None
+    target = tmux_target(entry)
+    if target:
+        blocks = (_lanes_terminals(doc) or {}, ((doc.get('throttle') or {}).get('terminals') or {}))
+        for block in blocks:
+            hits = [name for name in names if isinstance(block, dict) and _binding(block.get(name)) == target]
+            if len(hits) == 1:
+                return hits[0]
+    registry_name = entry.get('registry_name') if isinstance(entry, dict) else None
+    hits = [name for name in names if isinstance(registry_name, str) and registry_name.endswith(name)]
+    return hits[0] if len(hits) == 1 else None
+
+
+def source_prefix(doc, entries):
+    """The repository prefix a board puts before the declared names of one terminals.json (the manifest's `prefix`,
+    which the container never sees), learned from that board's lanes of the file: `registry_name` minus the declared
+    name. None unless every lane that can be matched agrees and at least one can."""
+    prefixes = set()
+    for entry in entries:
+        name = declared_name(doc, entry)
+        registry_name = entry.get('registry_name') or ''
+        if name and registry_name.endswith(name):
+            prefixes.add(registry_name[:len(registry_name) - len(name)])
+    return prefixes.pop() if len(prefixes) == 1 else None
+
+
+# ------------------------------------------------------------------------------------------------ whoami
+
+def lane_kind(entry):
+    """declared (a terminals.json lane) or registered (a session adopted with `lanes register`)."""
+    return 'registered' if entry.get('registered_session') else 'declared'
+
+
+def whoami(root, environ=None):
+    """Which lane this process runs in: {'lane', 'found_by', 'kind', 'entry' | 'session', 'why'?}.
+    $LANE_ID first (a canonical recipe's `-e`, or lane-run for a zmx lane); else the pane's session, asked of $TMUX's
+    socket (`display -p -t $TMUX_PANE '#S'`), matched by (socket name, session) in the registry, then among this
+    container's unregistered sessions (status.json). Not in a lane is an answer (`lane` null), not an error."""
+    environ = os.environ if environ is None else environ
+    lanes = registry_lanes(root)
+    lane = environ.get('LANE_ID') or ''
+    if LANE_RE.fullmatch(lane):
+        entry = lanes.get(lane)
+        return {'lane': lane, 'found_by': 'LANE_ID', 'kind': lane_kind(entry) if entry else None, 'entry': entry,
+                **({} if entry else {'why': f'LANE_ID={lane} is not in ~/.lz/registry.json (a zmx lane, or the '
+                                            'registry has not been synced since the lane was added)'})}
+    socket_path, pane = (environ.get('TMUX') or '').split(',', 1)[0], environ.get('TMUX_PANE') or ''
+    if not socket_path or not pane:
+        return {'lane': None, 'found_by': None, 'kind': None, 'entry': None,
+                'why': 'not inside a lane: this process has no LANE_ID and no TMUX/TMUX_PANE (an agent that clears '
+                       'its MCP servers\' environment must pass them: for Codex, `lane mcp install` writes the '
+                       '[mcp_servers.lanes] env_vars)'}
+    result = run_tmux(['tmux', '-N', '-S', socket_path, 'display', '-p', '-t', pane, '#S'])
+    session = result.stdout.strip() if result.returncode == 0 else ''
+    if not session:
+        return {'lane': None, 'found_by': None, 'kind': None, 'entry': None,
+                'why': f'tmux did not name this pane\'s session ({(result.stderr or "no answer").strip()})'}
+    socket = os.path.basename(socket_path)
+    for lane_id, entry in lanes.items():
+        if tmux_target(entry) == (socket, session):
+            return {'lane': lane_id, 'found_by': 'tmux', 'kind': lane_kind(entry), 'entry': entry}
+    for row in container_status(root)['unregistered']:
+        tmux = row.get('tmux') or {}
+        if (tmux.get('socket'), tmux.get('session')) == (socket, session):
+            return {'lane': row['id'], 'found_by': 'tmux', 'kind': 'unregistered', 'entry': None, 'session': row}
+    return {'lane': None, 'found_by': None, 'kind': None, 'entry': None, 'tmux': {'socket': socket, 'session': session},
+            'why': 'this tmux session is neither a registry lane nor an unregistered session statusd has seen'}
+
+
+# ------------------------------------------------------------------------------------------------ atomic files
+
+def atomic_replace(path, text, mode):
+    """Replace `path` with `text` (str) atomically: an O_EXCL temp file in the same directory, fsync, chmod, rename
+    over whatever the name holds."""
+    path = Path(path)
+    fd, tmp = tempfile.mkstemp(prefix='.' + path.name + '.', dir=str(path.parent))
+    try:
+        with os.fdopen(fd, 'w', encoding='utf-8') as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.chmod(tmp, mode)
+        os.replace(tmp, str(path))
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+EDIT_MAX = 64 << 20   # ~/.claude.json grows with Claude Code's project history
+
+
+def no_links(root, path):
+    """Refuse (LaneError) when a component of `path` below `root` is a symbolic link. The host edits the agents'
+    files inside a container's home volume: a link planted there resolves on the HOST (`~/.claude.json ->
+    /home/coder/.claude.json` would read, and copy into the container, the operator's own Claude configuration; the
+    DEF-1796 class)."""
+    path, root = Path(path), Path(root)
+    for depth in range(1, len(path.relative_to(root).parts) + 1):
+        part = root.joinpath(*path.relative_to(root).parts[:depth])
+        try:
+            if stat.S_ISLNK(os.lstat(str(part)).st_mode):
+                raise LaneError(f'{part} is a symbolic link — left alone', 'source_link')
+        except FileNotFoundError:
+            return
+
+
+def _snapshot(path, root=None):
+    """(identity, text or None) of a file: identity = (inode, size, mtime_ns, mode), None when it is missing. With
+    `root`, no component below it may be a symbolic link (no_links)."""
+    if root is not None:
+        no_links(root, path)
+    try:
+        info = os.lstat(str(path))
+    except FileNotFoundError:
+        return None, None
+    data = read_regular(path, EDIT_MAX)
+    if data is None:
+        raise LaneError(f'{path}: not a regular file of at most {EDIT_MAX >> 20} MiB this account can read — left alone',
+                        'source_unreadable')
+    try:
+        return (info.st_ino, info.st_size, info.st_mtime_ns, stat.S_IMODE(info.st_mode)), data.decode('utf-8')
+    except UnicodeDecodeError:
+        raise LaneError(f'{path}: not UTF-8 text — left alone', 'source_unreadable')
+
+
+def backup_name(path, now=None):
+    """<path>.bak-<UTC %Y%m%dT%H%M%SZ>, with -2, -3, … when that name is taken."""
+    path = Path(path)
+    stamp = time.strftime('%Y%m%dT%H%M%SZ', time.gmtime(now))
+    candidate, n = path.with_name(f'{path.name}.bak-{stamp}'), 2
+    while os.path.lexists(str(candidate)):
+        candidate, n = path.with_name(f'{path.name}.bak-{stamp}-{n}'), n + 1
+    return candidate
+
+
+def edit_file(path, transform, new_mode=0o600, backup=False, root=None):
+    """Apply `transform(text or None) -> new text` to `path` and write the result atomically -> (before, after,
+    backup path or None); before == after means nothing was written. Re-read before the write: when the file
+    changed while the edit was computed (another writer — Claude Code rewrites ~/.claude.json), the edit is computed
+    once more from the new bytes; a second change refuses (LaneError) and writes nothing. The mode of an existing
+    file is kept; a new one gets `new_mode`. With `backup`, the bytes the edit was computed from are kept beside it
+    first (same mode). With `root`, a symbolic link at or above the file (below `root`) refuses, checked on the read
+    and again just before the write."""
+    path = Path(path)
+    for attempt in (1, 2):
+        ident, before = _snapshot(path, root)
+        after = transform(before)
+        if after == before:
+            return before, after, None
+        if _snapshot(path, root) != (ident, before):
+            if attempt == 1:
+                continue
+            raise LaneError(f'{path} changed twice while it was being edited — nothing written; run it again',
+                           'edit_conflict')
+        mode = ident[3] if ident else new_mode
+        saved = None
+        if backup and before is not None:
+            saved = backup_name(path)
+            fd = os.open(str(saved), os.O_WRONLY | os.O_CREAT | os.O_EXCL, mode)
+            with os.fdopen(fd, 'w', encoding='utf-8') as handle:
+                handle.write(before)
+            os.chmod(str(saved), mode)
+        path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        if root is not None:
+            no_links(root, path)   # a directory this call created is checked once more before anything lands in it
+        atomic_replace(path, after, mode)
+        return before, after, saved
+    raise AssertionError('unreachable')
+
+
+# ------------------------------------------------------------------------------------------------ strict JSON spans
+
+def strict_json(text, what):
+    """json.loads that refuses what an edit could not keep exact: comments and trailing commas (not JSON at all),
+    NaN/Infinity, and a key given twice in one object (an edit would change one of them)."""
+    def pairs(items):
+        seen = set()
+        for key, _value in items:
+            if key in seen:
+                raise LaneError(f'{what}: the key {key!r} appears twice in one object — fix it by hand first',
+                                'source_invalid')
+            seen.add(key)
+        return dict(items)
+
+    def constant(name):
+        raise LaneError(f'{what}: {name} is not JSON', 'source_invalid')
+    try:
+        return json.loads(text, object_pairs_hook=pairs, parse_constant=constant)
+    except ValueError as error:
+        raise LaneError(f'{what} is not strict JSON ({error}) — comments and trailing commas included; fix it by '
+                        f'hand first', 'source_invalid')
+
+
+class Node:
+    """A JSON value's span in its text: [start, end). Objects keep `members` [(key, key start, Node)], arrays
+    `items` [Node]."""
+    __slots__ = ('kind', 'start', 'end', 'members', 'items')
+
+    def __init__(self, kind, start, end=None):
+        self.kind, self.start, self.end, self.members, self.items = kind, start, end, [], []
+
+    def get(self, key):
+        for name, _key_start, value in self.members:
+            if name == key:
+                return value
+        return None
+
+    def entries(self):
+        """[(start, end)] of the members (key through value) or items, in order."""
+        if self.kind == 'object':
+            return [(key_start, value.end) for _name, key_start, value in self.members]
+        return [(item.start, item.end) for item in self.items]
+
+
+_WS = ' \t\r\n'
+_SCALAR = re.compile(r'-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?|true|false|null')
+
+
+def _skip(text, i):
+    while i < len(text) and text[i] in _WS:
+        i += 1
+    return i
+
+
+def _string_end(text, i):
+    j = i + 1
+    while text[j] != '"':
+        j += 2 if text[j] == '\\' else 1
+    return j + 1
+
+
+def _node(text, i):
+    c = text[i]
+    if c in '{[':
+        node = Node('object' if c == '{' else 'array', i)
+        close = '}' if c == '{' else ']'
+        i = _skip(text, i + 1)
+        if text[i] == close:
+            node.end = i + 1
+            return node
+        while True:
+            if node.kind == 'object':
+                key_end = _string_end(text, i)
+                key = json.loads(text[i:key_end])
+                value = _node(text, _skip(text, _skip(text, key_end) + 1))
+                node.members.append((key, i, value))
+            else:
+                value = _node(text, i)
+                node.items.append(value)
+            i = _skip(text, value.end)
+            if text[i] == ',':
+                i = _skip(text, i + 1)
+                continue
+            node.end = i + 1
+            return node
+    if c == '"':
+        return Node('string', i, _string_end(text, i))
+    match = _SCALAR.match(text, i)
+    return Node('scalar', i, match.end())
+
+
+def scan(text):
+    """The span tree of a JSON text that strict_json accepted."""
+    return _node(text, _skip(text, 0))
+
+
+def _line_indent(text, pos):
+    start = text.rfind('\n', 0, pos) + 1
+    end = start
+    while end < len(text) and text[end] in ' \t':
+        end += 1
+    return text[start:end]
+
+
+def _file_unit(text, root):
+    """The indent step of a pretty-printed file (learned from the root's first member), None for a one-line file."""
+    if '\n' not in text.strip():
+        return None
+    entries = root.entries()
+    if entries:
+        sep = text[root.start + 1:entries[0][0]]
+        if '\n' in sep:
+            return sep.rsplit('\n', 1)[1] or '  '
+    return '  '
+
+
+def _render(value, indent, unit):
+    if unit is None:
+        return json.dumps(value, ensure_ascii=False)
+    return json.dumps(value, ensure_ascii=False, indent=unit).replace('\n', '\n' + indent)
+
+
+def _append(text, root, node, piece):
+    """`node` (an object or array span) with one more entry at its end, laid out like its existing entries.
+    `piece(indent, unit)` renders the entry ("key": value, or a value)."""
+    entries = node.entries()
+    close_indent = _line_indent(text, node.end - 1)
+    if not entries:
+        unit = _file_unit(text, root)
+        if unit is None:
+            return text[:node.start + 1] + piece('', None) + text[node.end - 1:]
+        indent = close_indent + unit
+        return text[:node.start + 1] + '\n' + indent + piece(indent, unit) + '\n' + close_indent + text[node.end - 1:]
+    last_start, last_end = entries[-1]
+    if len(entries) > 1:
+        sep = text[text.index(',', entries[-2][1]) + 1:last_start]
+    else:
+        sep = text[node.start + 1:last_start]
+    if '\n' in sep:
+        indent = sep.rsplit('\n', 1)[1]
+        unit = indent[len(close_indent):] if indent.startswith(close_indent) and len(indent) > len(close_indent) \
+            else (_file_unit(text, root) or '  ')
+    else:
+        indent, unit = '', None
+    return text[:last_end] + ',' + sep + piece(indent, unit) + text[last_end:]
+
+
+def _remove(text, node, index):
+    """`node` without its entry `index` and the separator that belonged to it."""
+    entries = node.entries()
+    start, end = entries[index]
+    if len(entries) == 1:
+        return text[:node.start + 1] + text[node.end - 1:]
+    if index < len(entries) - 1:
+        return text[:start] + text[entries[index + 1][0]:]
+    return text[:entries[index - 1][1]] + text[end:]
+
+
+def set_member(text, path, key, value):
+    """`text` with the member `key` of the object at `path` (keys from the root) set to `value`: its value span
+    replaced when the key exists, else one member appended. Every other byte stays."""
+    root = scan(text)
+    node = root
+    for step in path:
+        node = node.get(step) if node.kind == 'object' else None
+        if node is None or node.kind != 'object':
+            raise LaneError(f'no object at {".".join(path)}', 'source_invalid')
+    for name, key_start, current in node.members:
+        if name == key:
+            indent = _line_indent(text, key_start)
+            unit = _file_unit(text, root)
+            return text[:current.start] + _render(value, indent, unit) + text[current.end:]
+    rendered_key = json.dumps(key, ensure_ascii=False)
+    return _append(text, root, node, lambda indent, unit: f'{rendered_key}: {_render(value, indent, unit)}')
+
+
+def remove_member(text, path, key):
+    root = scan(text)
+    node = root
+    for step in path:
+        node = node.get(step)
+        if node is None or node.kind != 'object':
+            raise LaneError(f'no object at {".".join(path)}', 'source_invalid')
+    for index, (name, _key_start, _value) in enumerate(node.members):
+        if name == key:
+            return _remove(text, node, index)
+    return text
+
+
+# ------------------------------------------------------------------------------------------------ terminals.json
+
+TERMINALS_WHAT = '.vscode/terminals.json'
+DISPLAY_MAX = 128
+
+
+def _terminal_names(doc):
+    terminals = doc.get('terminals') if isinstance(doc, dict) else None
+    if not isinstance(terminals, list):
+        raise LaneError(f'{TERMINALS_WHAT} has no "terminals" list', 'source_invalid')
+    return [t.get('name') if isinstance(t, dict) else None for t in terminals]
+
+
+def _check_terminals(before, after, names):
+    """The editor's never-rules, checked on the parsed result whatever the edit was: the root `throttle` object and
+    every root key but `terminals`/`lanes` unchanged, the terminal names exactly `names` (no rename, no reorder) and
+    at least one terminal left."""
+    if _terminal_names(after) != names:
+        raise LaneError('refused: the edit would rename or reorder terminals', 'edit_refused')
+    if not names:
+        raise LaneError('refused: never the last terminal', 'last_terminal')
+    for key in set(before) | set(after):
+        if key not in ('terminals', 'lanes') and before.get(key) != after.get(key):
+            raise LaneError(f'refused: the edit would change the root {key!r} object', 'edit_refused')
+
+
+def _lanes_terminals(doc):
+    block = doc.get('lanes')
+    entries = block.get('terminals') if isinstance(block, dict) else None
+    return entries if isinstance(entries, dict) else None
+
+
+def terminals_set_display(text, name, display):
+    """terminals.json with `lanes.terminals[<name>].displayName` set to `display` (None removes it). The declared
+    `name` — what the lane id derives from — never changes (LNS-33: the host reads displayName leniently, the id
+    never moves)."""
+    doc = strict_json(text, TERMINALS_WHAT)
+    names = _terminal_names(doc)
+    if name not in names:
+        raise LaneError(f'{TERMINALS_WHAT} declares no terminal named {name!r}', 'not_declared_here')
+    entries = _lanes_terminals(doc)
+    if entries is None or not isinstance(entries.get(name), dict):
+        raise LaneError(f'{TERMINALS_WHAT} has no lanes.terminals entry for {name!r} — run `lanes cursor-sync '
+                        f'--write` on the host first', 'no_lanes_block')
+    if display is not None:
+        if not isinstance(display, str) or not display.strip() or re.search(r'[\x00-\x1f\x7f]', display) \
+                or len(display) > DISPLAY_MAX:
+            raise LaneError(f'invalid display name: one line of text, at most {DISPLAY_MAX} characters', 'invalid_name')
+        after = set_member(text, ['lanes', 'terminals', name], 'displayName', display)
+    else:
+        after = remove_member(text, ['lanes', 'terminals', name], 'displayName')
+    parsed = strict_json(after, TERMINALS_WHAT)
+    _check_terminals(doc, parsed, names)
+    if _lanes_terminals(parsed)[name].get('displayName') != display:
+        raise LaneError('refused: the edit did not land where it should', 'edit_refused')
+    return after
+
+
+def terminals_remove(text, name):
+    """terminals.json without the terminal `name`: its `terminals[]` item and its `lanes.terminals` entry. Never the
+    last terminal; the root `throttle` object (Throttle's annotations) is left exactly as it is."""
+    doc = strict_json(text, TERMINALS_WHAT)
+    names = _terminal_names(doc)
+    if names.count(name) != 1:
+        raise LaneError(f'{TERMINALS_WHAT} declares {names.count(name)} terminals named {name!r}; refusing',
+                        'not_declared_here' if not names.count(name) else 'source_invalid')
+    if len(names) == 1:
+        raise LaneError(f'{name!r} is the last terminal of {TERMINALS_WHAT}: never the last terminal', 'last_terminal')
+    root = scan(text)
+    after = _remove(text, root.get('terminals'), names.index(name))
+    if name in (_lanes_terminals(doc) or {}):
+        after = remove_member(after, ['lanes', 'terminals'], name)
+    parsed = strict_json(after, TERMINALS_WHAT)
+    _check_terminals(doc, parsed, [n for n in names if n != name])
+    if name in (_lanes_terminals(parsed) or {}):
+        raise LaneError('refused: the edit did not land where it should', 'edit_refused')
+    return after
+
+
+def terminals_add(text, terminal, entry=None):
+    """terminals.json with `terminal` (a VS Code terminal object with a new `name`) appended to `terminals[]` and,
+    when given, `entry` as its `lanes.terminals[<name>]` (the block must exist). Nothing is reordered. A binding the
+    file already holds — in `lanes.terminals` or the root `throttle` block, under any name — is refused
+    (`duplicate_binding`): two declarations of one session would make two lanes of it."""
+    doc = strict_json(text, TERMINALS_WHAT)
+    names = _terminal_names(doc)
+    name = terminal.get('name') if isinstance(terminal, dict) else None
+    if not isinstance(name, str) or not name.strip() or re.search(r'[\x00-\x1f\x7f]', name):
+        raise LaneError('a terminal needs a one-line name', 'invalid_name')
+    if name in names:
+        raise LaneError(f'{TERMINALS_WHAT} already declares {name!r}', 'duplicate_name')
+    pair = _binding(entry)
+    if pair:
+        for block in (_lanes_terminals(doc) or {}, ((doc.get('throttle') or {}).get('terminals') or {})):
+            held = [other for other, value in (block.items() if isinstance(block, dict) else ()) if _binding(value) == pair]
+            if held:
+                raise LaneError(f'{TERMINALS_WHAT} already binds tmux {pair[0]}/{pair[1]} (as {held[0]!r})',
+                                'duplicate_binding')
+    root = scan(text)
+    after = _append(text, root, root.get('terminals'), lambda indent, unit: _render(terminal, indent, unit))
+    if entry is not None:
+        if _lanes_terminals(doc) is None:
+            raise LaneError(f'{TERMINALS_WHAT} has no lanes block — run `lanes cursor-sync --write` on the host first',
+                            'no_lanes_block')
+        after = set_member(after, ['lanes', 'terminals'], name, entry)
+    parsed = strict_json(after, TERMINALS_WHAT)
+    _check_terminals(doc, parsed, names + [name])
+    return after
+
+
+# ------------------------------------------------------------------------------------------------ MCP entries
+
+MCP_NAME = 'lanes'
+MCP_COMMAND = LZ + '/bin/lane-mcp'
+MCP_ENTRY = {'command': MCP_COMMAND}
+MCP_AGENTS = ('claude', 'codex')
+MCP_FILES = {'claude': '.claude.json', 'codex': '.codex/config.toml'}
+TOML_HEADER = re.compile(r'''^[ \t]*\[[ \t]*mcp_servers[ \t]*\.[ \t]*(?:lanes|"lanes"|'lanes')[ \t]*\][ \t]*(?:#.*)?$''')
+# What Codex must hand lane-mcp. Codex starts a stdio MCP server with a CLEARED environment: its defaults (HOME,
+# LOGNAME, PATH, SHELL, USER, LANG, LC_ALL, TERM, TMPDIR, TZ) plus the names in the table's `env_vars` and the
+# table's own `env` (codex-rs rmcp-client `create_env_for_mcp_server`; MEASURED codex-cli 0.160.1, 2026-10-06: a
+# table without `env_vars` started its server with HOME, PATH and USER only, the same table with this list also with
+# all four). whoami reads LANE_ID, TMUX and TMUX_PANE; LANE_WS completes the lane identity the canonical recipe
+# stamps, so lane-mcp sees under Codex what it sees under Claude Code, which inherits its whole environment.
+MCP_ENV_VARS = ('LANE_ID', 'LANE_WS', 'TMUX', 'TMUX_PANE')
+
+
+def _ours(entry, command):
+    """An MCP entry that already starts this lane-mcp: our command, no arguments, stdio."""
+    return isinstance(entry, dict) and entry.get('command') == command and not entry.get('args') \
+        and entry.get('type', 'stdio') == 'stdio' and 'url' not in entry
+
+
+def _codex_passed(entry):
+    """The variable names a parsed Codex table passes through (`env_vars`: plain names, or {name, source} tables of
+    a local source)."""
+    names = entry.get('env_vars') if isinstance(entry, dict) else None
+    if not isinstance(names, list):
+        return []
+    return [item if isinstance(item, str) else item.get('name') for item in names
+            if isinstance(item, str) or (isinstance(item, dict) and isinstance(item.get('name'), str)
+                                         and item.get('source', 'local') == 'local')]
+
+
+def _codex_ours(entry, command):
+    """A Codex table that already starts this lane-mcp AND passes it every name in MCP_ENV_VARS (more are fine)."""
+    return _ours(entry, command) and set(MCP_ENV_VARS) <= set(_codex_passed(entry))
+
+
+def _an_older_ours(entry):
+    """An entry an earlier install wrote: a lane-mcp at another path (it is replaced)."""
+    return isinstance(entry, dict) and isinstance(entry.get('command'), str) \
+        and os.path.basename(entry['command']) == 'lane-mcp' and not entry.get('args') and 'url' not in entry
+
+
+def claude_mcp(text, command=MCP_COMMAND):
+    """~/.claude.json with `mcpServers.lanes = {"command": <command>}` -> (new text, why). The text is unchanged when
+    an equivalent entry exists; an entry of the same name that starts something else is never replaced (why says
+    so). The edit is the one member, inserted in the file's own layout; the result must parse back to the input plus
+    that member, else it is refused."""
+    entry = {'command': command}
+    if text is None or not text.strip():
+        return json.dumps({'mcpServers': {MCP_NAME: entry}}, indent=2) + '\n', None
+    doc = strict_json(text, '~/.claude.json')
+    if not isinstance(doc, dict):
+        return text, '~/.claude.json is not a JSON object — left alone'
+    servers = doc.get('mcpServers')
+    if servers is not None and not isinstance(servers, dict):
+        return text, 'mcpServers in ~/.claude.json is not an object — left alone'
+    current = (servers or {}).get(MCP_NAME)
+    if _ours(current, command):
+        return text, None
+    if current is not None and not _an_older_ours(current):
+        shown = current.get('command') if isinstance(current, dict) else current
+        return text, (f'mcpServers.{MCP_NAME} in ~/.claude.json is not the entry Lanes writes (command {shown!r}) — '
+                      'left alone (remove it to let Lanes add its own)')
+    if servers is None:
+        after = set_member(text, [], 'mcpServers', {MCP_NAME: entry})
+    else:
+        after = set_member(text, ['mcpServers'], MCP_NAME, entry)
+    expected = dict(doc)
+    expected['mcpServers'] = dict(servers or {}, **{MCP_NAME: entry})
+    if strict_json(after, '~/.claude.json') != expected:
+        return text, 'the entry could not be added without changing anything else — add it by hand'
+    return after, None
+
+
+def _toml_loads(text):
+    try:
+        import tomllib
+    except ImportError:   # Python < 3.11 on the host: the textual rules below still hold
+        return None
+    try:
+        return tomllib.loads(text)
+    except tomllib.TOMLDecodeError as error:
+        raise LaneError(f'~/.codex/config.toml is not valid TOML ({error}) — left alone')
+
+
+TOML_COMMAND = re.compile(r'''^[ \t]*command[ \t]*=[ \t]*"([^"\\]*)"[ \t]*(?:#.*)?$''')
+TOML_ENV_VARS_KEY = re.compile(r'''^[ \t]*(?:env_vars|"env_vars"|'env_vars')[ \t]*=''')
+_TOML_NAME = r'[ \t]*"[A-Za-z_][A-Za-z0-9_]*"[ \t]*'
+TOML_ENV_VARS = re.compile(rf'''^[ \t]*env_vars[ \t]*=[ \t]*\[((?:{_TOML_NAME},)*(?:{_TOML_NAME})?)[ \t]*\][ \t]*(?:#.*)?$''')
+
+
+def _env_vars_line(names):
+    return f'env_vars = {json.dumps(list(names))}'
+
+
+def codex_mcp(text, command=MCP_COMMAND):
+    """~/.codex/config.toml with a `[mcp_servers.lanes]` table whose `command` is <command> and whose `env_vars`
+    passes MCP_ENV_VARS -> (new text, why). A missing table is appended at the end (a new table header after
+    everything else changes no other key); an earlier install's table (a lane-mcp at another path, or `codex mcp
+    add`'s spelling: a command and no `env_vars`) gets its one `command` line replaced and/or the `env_vars` line
+    inserted right after it, or the missing names appended to its one-line `env_vars` list; a `lanes` server that
+    starts something else, one not written as its own `[mcp_servers.lanes]` table with one plain `command = "…"`
+    line, or one whose `env_vars` is not a one-line list of plain names, is left alone. The decision is read from
+    the text itself, so a host without tomllib (Python < 3.11) decides the same way for the forms it can read;
+    with tomllib the input must parse and the result must parse back to the input plus that table."""
+    line = f'command = {json.dumps(command)}'
+    if text is None or not text.strip():
+        return f'[mcp_servers.{MCP_NAME}]\n{line}\n{_env_vars_line(MCP_ENV_VARS)}\n', None
+    try:
+        parsed = _toml_loads(text)
+    except LaneError as error:
+        return text, str(error)
+    rows = text.splitlines(True)
+    headers = [i for i, row in enumerate(rows) if TOML_HEADER.match(row.rstrip('\r\n'))]
+    names = list(MCP_ENV_VARS)
+    if parsed is not None:
+        servers = parsed.get('mcp_servers')
+        current = servers.get(MCP_NAME) if isinstance(servers, dict) else None
+        if current is not None and _codex_ours(current, command):
+            return text, None
+    elif re.search(r'(?m)^[ \t]*(mcp_servers[ \t]*[.=]|\[[ \t]*mcp_servers[ \t]*\])', text):
+        return text, ('~/.codex/config.toml defines mcp_servers in a form this Python (no tomllib) cannot read '
+                      'safely — add the table by hand')
+    else:
+        current = {} if headers else None
+    if current is None and not headers:
+        after = text + ('' if text.endswith('\n') else '\n') + \
+            f'\n[mcp_servers.{MCP_NAME}]\n{line}\n{_env_vars_line(names)}\n'
+    else:
+        if len(headers) != 1:
+            return text, (f'mcp_servers.{MCP_NAME} in ~/.codex/config.toml is not written as one '
+                          f'[mcp_servers.{MCP_NAME}] table — left alone; fix it by hand')
+        start = headers[0] + 1
+        end = next((i for i in range(start, len(rows)) if rows[i].lstrip().startswith('[')), len(rows))
+        hits = [i for i in range(start, end) if re.match(r'[ \t]*command[ \t]*=', rows[i])]
+        found = TOML_COMMAND.match(rows[hits[0]].rstrip('\r\n')) if len(hits) == 1 else None
+        if not found:
+            return text, (f'[mcp_servers.{MCP_NAME}] in ~/.codex/config.toml has no single plain command line — '
+                          'left alone; fix it by hand')
+        if os.path.basename(found.group(1)) != 'lane-mcp' or (parsed is not None and not _an_older_ours(current)):
+            return text, (f'mcp_servers.{MCP_NAME} in ~/.codex/config.toml is not the entry Lanes writes (command '
+                          f'{found.group(1)!r}) — left alone (remove it to let Lanes add its own)')
+        passes = [i for i in range(start, end) if TOML_ENV_VARS_KEY.match(rows[i])]
+        listed = TOML_ENV_VARS.match(rows[passes[0]].rstrip('\r\n')) if len(passes) == 1 else None
+        if passes and not listed:
+            return text, (f'[mcp_servers.{MCP_NAME}] in ~/.codex/config.toml has an env_vars that is not one line '
+                          f'of plain names — left alone; make it pass {", ".join(MCP_ENV_VARS)} by hand')
+        have = re.findall(r'"([^"]*)"', listed.group(1)) if listed else None
+        if have is not None:
+            names = have + [name for name in MCP_ENV_VARS if name not in have]
+        if found.group(1) == command and have == names:
+            return text, None
+        at = hits[0]
+        ending = rows[at][len(rows[at].rstrip('\r\n')):]
+        rows[at] = line + ((ending or '\n') if have is None else ending)
+        if have is None:     # `codex mcp add`'s spelling, or an install from before the pass-through: one line more
+            rows.insert(at + 1, _env_vars_line(names) + ending)
+        elif have != names:
+            kept = rows[passes[0]]
+            rows[passes[0]] = _env_vars_line(names) + kept[len(kept.rstrip('\r\n')):]
+        after = ''.join(rows)
+    if parsed is not None:
+        expected = dict(parsed)
+        expected['mcp_servers'] = dict(parsed.get('mcp_servers') or {})
+        expected['mcp_servers'][MCP_NAME] = dict(current or {}, command=command, env_vars=names)
+        try:
+            ok = _toml_loads(after) == expected
+        except LaneError:
+            ok = False
+        if not ok:
+            return text, 'the table could not be added without changing anything else — add it by hand'
+    return after, None
+
+
+MCP_EDITORS = {'claude': claude_mcp, 'codex': codex_mcp}
+
+
+def mcp_plan(home, agents=MCP_AGENTS, command=MCP_COMMAND):
+    """[{agent, path, before, after, why}] for each agent's config under `home` (pure: reads only). `after == before`
+    with no `why` = already there; a `why` = left alone, with the reason."""
+    plan = []
+    for agent in agents:
+        path = Path(home) / MCP_FILES[agent]
+        try:
+            _ident, before = _snapshot(path, home)
+            after, why = MCP_EDITORS[agent](before, command)
+        except LaneError as error:
+            before = after = None
+            why = str(error)
+        plan.append({'agent': agent, 'path': path, 'before': before, 'after': after, 'why': why})
+    return plan
+
+
+def mcp_diff(item):
+    """The unified diff of one plan item ('' when there is nothing to change)."""
+    if item['why'] or item['after'] == item['before']:
+        return ''
+    before, after = item['before'] or '', item['after'] or ''
+    path = str(item['path'])
+    return ''.join(difflib.unified_diff(before.splitlines(True), after.splitlines(True), f'{path} (now)',
+                                        f'{path} (with the lanes MCP server)'))
+
+
+def mcp_apply(home, agents=MCP_AGENTS, command=MCP_COMMAND):
+    """Write each agent's entry where it is missing -> [{agent, path, status, backup, why}], status one of `added`,
+    `present`, `refused`. Each file is re-planned from its bytes at write time (edit_file: re-read before the
+    write, one retry), kept as <file>.bak-<UTC> first when it existed, replaced atomically with its own mode (a new
+    one 0600; a new ~/.codex is 0700). A symbolic link below `home` (the file, or ~/.codex) refuses that file.
+    Never raises for one file: the other still gets its entry."""
+    results = []
+    for agent in agents:
+        path = Path(home) / MCP_FILES[agent]
+        refusal = []
+
+        def transform(before, agent=agent, refusal=refusal):
+            after, why = MCP_EDITORS[agent](before, command)
+            del refusal[:]
+            if why:
+                refusal.append(why)
+            return after
+        try:
+            before, after, saved = edit_file(path, transform, new_mode=0o600, backup=True, root=home)
+        except (LaneError, OSError) as error:
+            results.append({'agent': agent, 'path': path, 'status': 'refused', 'backup': None,
+                            'why': str(error)})
+            continue
+        status = 'refused' if refusal else ('present' if before == after else 'added')
+        results.append({'agent': agent, 'path': path, 'status': status, 'backup': saved,
+                        'why': refusal[0] if refusal else None})
+    return results