@vibelord/lanes 1.1.0 → 1.2.0

package/payload/lanes/container/lane-mcp

@@ -0,0 +1,1091 @@
+#!/usr/bin/env python3
+"""lane-mcp — the Lanes Agent API inside a workspace container: an MCP server on stdin/stdout (LNS-34/35, wire v1).
+Installed at /home/coder/.lz/bin/lane-mcp by `lanes install-container`; Claude Code and Codex start it from
+`mcpServers.lanes` in ~/.claude.json and `[mcp_servers.lanes]` in ~/.codex/config.toml (`lane mcp install`).
+
+  usage: lane-mcp            (speaks MCP on stdin/stdout; nothing else to run by hand)
+
+Protocol: newline-delimited JSON-RPC 2.0, one message per line (no batches). `initialize` answers the client's
+protocolVersion when it is one of 2025-06-18, 2025-03-26 or 2024-11-05, else 2025-06-18; then
+`notifications/initialized`, `ping`, `tools/list` (a fixed order, JSON Schema inputs, annotations) and
+`tools/call`. Only `initialize` and `ping` are answered before `initialize`. An unknown method is -32601, an unknown
+tool -32602; a tool that cannot do its job answers `isError: true` with the reason as text, so the agent can act on
+it. Stdout carries nothing but protocol frames: the real fd 1 is kept for them and fd 1 itself points at /dev/null
+before anything runs, so neither a stray print nor a child process can corrupt the stream. One line per request
+goes to ~/.lz/s/logs/lane-mcp.log (methods, tool names, lane ids, outcomes and refusal codes, durations; never a
+capture's text, a sent text or a note), rotated to .1 past 1 MiB.
+
+Read tools (the lanes of THIS container: what ~/.lz/registry.json and ~/.lz/status.json hold):
+  lanes_whoami                 which lane this agent runs in ($LANE_ID, else its tmux pane's session)
+  lanes_list [workspace] [needs_you] [agent]   every lane here with its state and agent
+  lanes_status <lane>          one lane in full: registry facts, observed state, agent, tmux liveness, hook sidecar
+  lanes_capture <lane> [lines] the last N (1–500, default 100) non-blank lines of that lane's screen and scrollback
+
+Write tools (LNS-35). Each answers JSON: on success what changed, what picks it up (`picked_up_by`) and when
+(`expected_within_s`); on a refusal `isError: true` with {refused: <machine code>, why, human: what a person can do
+instead}. The declaration tools edit a repository's .vscode/terminals.json through lane_core's minimal editor (one
+span, re-read before the atomic write, never the root `throttle` object, never a rename or reorder, never the last
+terminal); `lanes sync` publishes the change (lanes-statusd starts one within ~15 s of the edit).
+  lanes_register <name> [session] [repo]   declare an unregistered tmux session (the caller's, or a named one) as a lane
+  lanes_unregister <lane>      remove a declared lane's terminal; its session keeps running (an unregistered session)
+  lanes_rename <lane> <display_name>   the lane's displayName in terminals.json; the id never changes
+  lanes_new <name> [cwd] [command] [workspace] [repo]   declare a lane on lanes-shells-<ws> and start its session
+  lanes_send <lane> <text> [enter] [force]   type printable text (then, half a second later, Enter) into a lane here
+  lanes_signal <status> [note]  report this agent's own status (and a one-line note) through lane-signal; the report
+                               stands until the agent's next tool call, prompt or permission prompt, and the end of
+                               its turn keeps it (lane-signal's EXPLICIT rule)
+Human-only by omission (no tool exists): ending or closing a lane, interrupting it (C-c or any key that is not
+printable text), opening or attaching one, uploads, the host's sync/gc/ensure, renaming a tmux session, and any
+edit of an adopted (`lanes register`ed, `--x-`) session — those stay with a person on the boards or the host.
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+import traceback
+import unicodedata
+from pathlib import Path
+
+sys.dont_write_bytecode = True   # ~/.lz/bin holds no __pycache__
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import lane_core as C  # noqa: E402
+
+PROTOCOLS = ('2025-06-18', '2025-03-26', '2024-11-05')   # the first is the one offered to an unknown version
+WIRE = 1
+LINE_MAX = 4 << 20
+LOG_MAX = 1 << 20
+CAPTURE_DEFAULT, CAPTURE_MAX = 100, 500
+TEXT_MAX = 256 << 10
+PARSE_ERROR, INVALID_REQUEST, METHOD_NOT_FOUND, INVALID_PARAMS, INTERNAL_ERROR = -32700, -32600, -32601, -32602, -32603
+NOT_INITIALIZED = -32002
+LOG_HINT = '~/.lz/s/logs/lane-mcp.log'
+SEND_MAX = 4000           # characters lanes_send types in one call
+NOTE_MAX = 120            # lane-signal's NOTE_MAX
+PATH_MAX, COMMAND_MAX = 1024, 1024
+# When a write reaches the boards. A terminals.json edit: lanes-statusd checks the files its registry names every
+# cycle (3 s) and starts ONE `lanes sync` at most every 10 s (statusd.hot_sync), which then publishes; the timer's
+# own sync runs every 2 minutes regardless. A hook sidecar: read on the next statusd cycle (3 s, slower under
+# memory pressure) and published with it.
+SYNC_LATENCY_S, STATUS_LATENCY_S = 15, 5
+SYNC_PICKUP = 'lanes sync'
+STATUS_PICKUP = 'lanes-statusd'
+SESSION_VARS = ('CLAUDE_CODE_SESSION_ID', 'CODEX_THREAD_ID')   # the agent's session id, when its env carries one
+# How long a lanes_signal report holds against the agent's own hooks (lane-signal's EXPLICIT rule, DEF-1801).
+SIGNAL_STANDS = ('your next tool call, a new prompt, a permission prompt, a failed turn or the session\'s end; the end '
+                 'of your turn keeps it')
+SIGNAL_WORKING = 'the end of your turn (the note stays while you keep working)'
+
+INSTRUCTIONS = ('Lanes tools for the workspace container this agent runs in. A lane is one long-lived agent terminal '
+                '(a tmux session) shown on the Lanes boards. lanes_whoami names your own lane; lanes_list shows every '
+                'lane in this container with its observed state and agent (needs_you: true lists the lanes waiting '
+                'for a person); lanes_status gives one lane in full; lanes_capture reads the last lines of another '
+                'lane\'s screen. Write tools: lanes_register declares an unregistered tmux session as a lane, '
+                'lanes_unregister removes a declared lane (its session keeps running), lanes_rename sets a lane\'s '
+                'display name, lanes_new declares and starts a new lane, lanes_send types text into a lane (refused '
+                'while its agent is working or waiting for an approval unless force: true), lanes_signal reports '
+                'your own status with a short note. Every write answers what changed, what picks it up and when; a '
+                'refusal answers a machine code and what a person can do instead. Ending, interrupting or attaching '
+                'a lane is a person\'s call: no tool does it.')
+
+ID_PATTERN = '^[A-Za-z0-9_][A-Za-z0-9_.-]*$'
+LANE_ARG = {'type': 'string', 'pattern': ID_PATTERN, 'maxLength': 128,
+            'description': 'A lane id as lanes_list shows it, e.g. "bw-tools--lanes-zellij".'}
+READ_ONLY = {'readOnlyHint': True, 'destructiveHint': False, 'idempotentHint': True, 'openWorldHint': False}
+
+
+def _tool(name, title, description, properties, required=(), hints=READ_ONLY):
+    schema = {'type': 'object', 'properties': properties, 'additionalProperties': False}
+    if required:
+        schema['required'] = list(required)
+    return {'name': name, 'title': title, 'description': description, 'inputSchema': schema,
+            'annotations': {'title': title, **hints}}
+
+
+def _writes(destructive, idempotent):
+    """A write tool's hints. A tool that creates something (register, new, send) is never marked idempotent: a
+    repeat is refused or acts again, never answered the same."""
+    return {'readOnlyHint': False, 'destructiveHint': destructive, 'idempotentHint': idempotent,
+            'openWorldHint': False}
+
+
+NAME_ARG = {'type': 'string', 'minLength': 1, 'maxLength': C.NAME_MAX,
+            'description': 'The lane\'s name as the boards show it, one line, with at least one letter or digit '
+                           'A-Z/0-9 (the lane id is <workspace>--<its slug>).'}
+REPO_ARG = {'type': 'string', 'pattern': ID_PATTERN, 'maxLength': 128,
+            'description': 'The repository id (lanes_status shows a lane\'s `repo`) whose .vscode/terminals.json '
+                           'gets the lane, when the board has more than one.'}
+
+
+TOOLS = (
+    _tool('lanes_whoami', 'Which lane am I in',
+          'Name the lane this agent runs in: its id, board (workspace), display name, kind (declared in a repository\'s '
+          '.vscode/terminals.json, registered with `lanes register`, or an unregistered session) and tmux target. '
+          'Found from $LANE_ID, else from this process\'s tmux pane. `lane` is null outside a lane, with the reason.',
+          {}),
+    _tool('lanes_list', 'List the lanes in this container',
+          'Every lane in this workspace container — declared, registered and unregistered tmux sessions — with its '
+          'observed state (active, quiet, dead, absent, missing, unknown) and its agent (harness, status such as '
+          'working, needs_input, needs_approval, done, errored). `status.fresh` says whether the host\'s observation '
+          'is live (renewed within 60 s).',
+          {'workspace': {'type': 'string', 'pattern': '^[A-Za-z0-9_][A-Za-z0-9_.-]*$', 'maxLength': 128,
+                         'description': 'Only the lanes of this board (workspace id).'},
+           'needs_you': {'type': 'boolean',
+                         'description': 'true: only lanes whose agent waits for a person (needs_approval, errored, '
+                                        'needs_input — the boards\' "Needs you" section).'},
+           'agent': {'type': 'string', 'enum': ['any', 'none', 'claude', 'codex'],
+                     'description': 'any: lanes with an agent; none: lanes without one; claude / codex: that harness.'}}),
+    _tool('lanes_status', 'Show one lane',
+          'One lane in full: the registry facts (board, display name, kind, tmux socket and session, the declaring '
+          'terminals.json and repository), the host\'s observation (state, agent, attached clients, viewers, last '
+          'activity, size, stale), whether its tmux session is alive now (null when tmux did not answer) and its '
+          'lane-signal hook sidecar.',
+          {'lane': LANE_ARG}, required=('lane',)),
+    _tool('lanes_capture', 'Read a lane\'s screen',
+          'The last `lines` non-blank lines of a tmux lane\'s screen and scrollback, as plain text (wrapped lines '
+          'joined, no escape sequences). Any lane of this container can be read; nothing is typed into it.',
+          {'lane': LANE_ARG,
+           'lines': {'type': 'integer', 'minimum': 1, 'maximum': CAPTURE_MAX, 'default': CAPTURE_DEFAULT,
+                     'description': f'How many lines, 1–{CAPTURE_MAX} (default {CAPTURE_DEFAULT}).'}},
+          required=('lane',)),
+    _tool('lanes_register', 'Register a session as a lane',
+          'Declare an unregistered tmux session of this container — the one this agent runs in, or `session` — '
+          'as a lane: one terminal appended to its board\'s .vscode/terminals.json (command `lane open <id>`, the '
+          'exact tmux binding, the canonical create recipe). Nothing is started, stopped or renamed. Answers the '
+          'lane id `lanes sync` will give it. Refused for a session that is already a lane (declared, or adopted '
+          'on the host), a name or id another lane uses, and a board with several repositories unless `repo` '
+          'names one.',
+          {'name': NAME_ARG,
+           'session': dict(LANE_ARG, description='The unregistered session, by its lane id as lanes_list shows it '
+                                                 '(kind "unregistered"); default: the session this agent runs in.'),
+           'repo': REPO_ARG},
+          required=('name',), hints=_writes(False, False)),
+    _tool('lanes_unregister', 'Unregister a declared lane',
+          'Remove a declared lane\'s terminal from its .vscode/terminals.json (its `terminals[]` item and its '
+          '`lanes.terminals` entry). The tmux session keeps running and shows again as an unregistered session; '
+          'nothing is killed. Refused for the last terminal of a file, an adopted session (kept on the host) and a '
+          'lane whose declaration is not in a file this container holds.',
+          {'lane': LANE_ARG}, required=('lane',), hints=_writes(True, True)),
+    _tool('lanes_rename', 'Rename a lane',
+          'Set a declared lane\'s display name: `lanes.terminals[<terminal>].displayName` in its terminals.json. '
+          'The lane id never changes. The display name equal to the lane\'s title removes it. A name another lane '
+          'of the board shows is refused (the board would drop it); a display name the host sets for the lane '
+          '(its workspace manifest) still wins and is reported.',
+          {'lane': LANE_ARG, 'display_name': dict(NAME_ARG, description='The new display name, one line.')},
+          required=('lane', 'display_name'), hints=_writes(False, True)),
+    _tool('lanes_new', 'Start a new lane',
+          'Declare a new lane in a board\'s .vscode/terminals.json — a tmux session on the board\'s shell socket '
+          '`lanes-shells-<workspace>` with the canonical create recipe — and start that session (detached, '
+          '100x30) with the lane\'s identity (LANE_ID, LANE_WS, the Throttle trace). The workspace defaults to this '
+          'agent\'s own board, the folder to the repository\'s.',
+          {'name': NAME_ARG,
+           'cwd': {'type': 'string', 'minLength': 1, 'maxLength': PATH_MAX,
+                   'description': 'The working directory: an absolute path under /home/coder (letters, digits, '
+                                  '_ . / - only); default: the repository folder.'},
+           'command': {'type': 'string', 'minLength': 1, 'maxLength': COMMAND_MAX,
+                       'description': 'The shell command the lane runs, e.g. "claude"; default: "bash -l".'},
+           'workspace': {'type': 'string', 'pattern': ID_PATTERN, 'maxLength': 128,
+                         'description': 'The board (workspace id); default: this agent\'s own.'},
+           'repo': REPO_ARG},
+          required=('name',), hints=_writes(False, False)),
+    _tool('lanes_send', 'Type into a lane',
+          'Type `text` literally into a lane of this container (its tmux session\'s active pane), then Enter unless '
+          '`enter` is false. Printable text only: no control characters, so no key a person would use to '
+          'interrupt. Refused while the lane\'s agent is working or waiting for an approval, unless `force` is '
+          'true.',
+          {'lane': LANE_ARG,
+           'text': {'type': 'string', 'minLength': 1, 'maxLength': SEND_MAX,
+                    'description': f'The text to type: printable, one line, at most {SEND_MAX} characters.'},
+           'enter': {'type': 'boolean', 'default': True, 'description': 'Press Enter after the text (default true).'},
+           'force': {'type': 'boolean', 'default': False,
+                     'description': 'Type even while the lane\'s agent is working or waiting for an approval.'}},
+          required=('lane', 'text'), hints=_writes(True, False)),
+    _tool('lanes_signal', 'Report my own status',
+          'Report this agent\'s own status on the Lanes boards through lane-signal (the hook sidecar the host reads), '
+          'with an optional one-line note shown as the lane\'s task line. Only this agent\'s own lane. The report '
+          'stands until your next tool call, a new prompt, a permission prompt, a failed turn or the session\'s end; '
+          'the end of your turn keeps it (a working report ends there). So report needs_input, done or errored as '
+          'the last thing you do before you end your turn.',
+          {'status': {'type': 'string', 'enum': list(C.STATUSES),
+                      'description': 'working, needs_input, needs_approval, done, errored, shell or idle.'},
+           'note': {'type': 'string', 'maxLength': NOTE_MAX,
+                    'description': f'What you are doing, one line of at most {NOTE_MAX} characters; "" clears it. '
+                                   'Kept while the report stands or its status repeats.'}},
+          required=('status',), hints=_writes(False, True)),
+)
+TOOL_BY_NAME = {tool['name']: tool for tool in TOOLS}
+WRITE_TOOLS = frozenset(tool['name'] for tool in TOOLS if not tool['annotations']['readOnlyHint'])
+
+
+class RpcError(Exception):
+    def __init__(self, code, message):
+        super().__init__(message)
+        self.code, self.message = code, message
+
+
+class ToolError(Exception):
+    """A tool that cannot do its job: answered as `isError: true` content, never as a protocol error."""
+
+
+# What a person can do instead, per refusal code (a raise site may say it more precisely).
+HUMAN = {
+    'invalid_arguments': 'Correct the arguments: tools/list gives this tool\'s input schema.',
+    'contract_outdated': 'A person runs `lanes install-container <container>` on the host.',
+    'not_in_lane': 'Run it from inside a lane, or name the lane or session (lanes_list shows them).',
+    'not_in_container': 'lanes_list shows the lanes of this container; a lane of another container is out of reach '
+                        'from here.',
+    'adopted_lane': 'An adopted session is kept on the host (registered-sessions.json): a person renames it there '
+                    '(`lanes rename <id> <name>`, or R in the sidebar) or removes it there.',
+    'already_declared': 'It is already a lane: lanes_rename names it, lanes_unregister removes it.',
+    'unregistered': 'It is not a lane yet: lanes_register declares it (a person can also close it on the board).',
+    'no_source': 'A person adds a repository with a .vscode/terminals.json to that board on the host (its '
+                 'workspaces.<board>.json), or declares the terminal by hand.',
+    'ambiguous_source': 'Pass `repo`: one of the repositories named in `repos`.',
+    'ambiguous_workspace': 'Pass `workspace`: one of the boards named in `workspaces`.',
+    'source_missing': 'A person checks the repository on the host (`lanes doctor` names a board whose terminals.json '
+                      'cannot be read).',
+    'source_invalid': 'A person fixes the file by hand (strict JSON: no comments, trailing commas or repeated keys), '
+                      'then try again.',
+    'source_unreadable': 'A person checks the file: it must be a regular UTF-8 file this account can read.',
+    'source_link': 'The file or a directory above it is a symbolic link: a person edits the file it points at.',
+    'edit_conflict': 'Another writer changed the file twice meanwhile: try again.',
+    'edit_refused': 'The edit would have changed more than its own entry: a person edits the file by hand.',
+    'no_lanes_block': 'A person runs `lanes cursor-sync --write` on the host (it adds the lanes block), then try '
+                      'again.',
+    'not_declared_here': 'Its declaration is not in a file this container holds (the host may keep its binding in the '
+                         'board\'s workspace manifest): a person changes it on the host.',
+    'unknown_prefix': 'A person runs `lanes sync` on the host, then try again.',
+    'last_terminal': 'A terminals.json keeps at least one terminal: a person edits the file, or the board, on the '
+                     'host.',
+    'duplicate_name': 'Pick another name: lanes_list shows the names in use.',
+    'duplicate_binding': 'That tmux session is declared already: lanes_list shows it, or `lanes sync` will.',
+    'slug_collision': 'Pick a name whose letters and digits differ from that lane\'s: the id is made of them.',
+    'invalid_name': 'A name is one line of at most 128 characters with at least one letter or digit A-Z/0-9.',
+    'invalid_session': 'The tmux session name holds characters a lane cannot be declared with: a person renames the '
+                       'session (letters, digits, _ . - and spaces) first.',
+    'invalid_cwd': 'Pass an existing directory under /home/coder (letters, digits, _ . / - only).',
+    'invalid_command': 'Pass one line of printable text.',
+    'invalid_text': 'Send printable text only (no newline, tab or escape): interrupting a lane or pressing other keys '
+                    'is a person\'s call.',
+    'invalid_note': 'A note is one line of printable text.',
+    'agent_working': 'Wait until lanes_status shows its agent is no longer working, or pass force: true. Interrupting '
+                     'it is a person\'s call.',
+    'agent_needs_approval': 'A person answers its approval prompt. Pass force: true only to type an answer you were '
+                            'asked to give.',
+    'not_tmux': 'A zmx lane takes `~/.lz/bin/lane send <id> <text>`.',
+    'session_gone': 'The tmux session is not running: lanes_list shows the live sessions.',
+    'session_exists': 'Pick another name: a tmux session with that name already runs on that socket.',
+    'tmux_unanswered': 'tmux did not answer in time: try again in a moment.',
+    'tmux_failed': 'lanes_status says whether the lane is running.',
+    'signal_not_written': 'A person checks the lane-signal install (`lanes install-container <container>` on the '
+                          'host).',
+    'refused': 'A person takes it from here.',
+}
+
+
+class Refusal(ToolError):
+    """A write tool's refusal: `isError: true` with {refused: <code>, why, human, …extra}. Nothing was changed
+    unless `extra` says so (`changed`)."""
+
+    def __init__(self, code, why, human=None, **extra):
+        super().__init__(why)
+        self.code, self.why = code, why
+        self.human = human or HUMAN.get(code) or HUMAN['refused']
+        self.extra = extra
+
+    @classmethod
+    def of(cls, error):
+        """A lane_core.LaneError (or a plain ToolError) as a refusal, by its code."""
+        if isinstance(error, Refusal):
+            return error
+        return cls(getattr(error, 'code', None) or 'refused', str(error))
+
+    def payload(self):
+        return {'refused': self.code, 'why': self.why, 'human': self.human, **self.extra}
+
+
+def refuse(code, why, human=None, **extra):
+    raise Refusal(code, why, human, **extra)
+
+
+class Log:
+    """Append-only lines in ~/.lz/s/logs/lane-mcp.log; a log that cannot be written is silence, never a failure."""
+
+    def __init__(self, path):
+        self.path = Path(path) if path else None
+        if not self.path:
+            return
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            if self.path.stat().st_size > LOG_MAX:
+                os.replace(str(self.path), str(self.path) + '.1')
+        except FileNotFoundError:
+            pass
+        except OSError:
+            self.path = None
+
+    def write(self, text, trace=None):
+        """One line; control characters in `text` (it may quote a client's method name) are escaped, so a request
+        can never forge a log line. `trace`, our own traceback, follows it as is."""
+        if not self.path:
+            return
+        text = re.sub(r'[\x00-\x1f\x7f]', lambda match: f'\\x{ord(match.group()):02x}', text)
+        try:
+            with open(self.path, 'a', encoding='utf-8', errors='replace') as handle:
+                handle.write(f'{time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())} [{os.getpid()}] {text}\n'
+                             + (trace or ''))
+        except OSError:
+            pass
+
+
+def validate(schema, arguments):
+    """The problems of `arguments` against one of our input schemas (the subset they use), as sentences."""
+    problems, properties = [], schema.get('properties', {})
+    for key in schema.get('required', []):
+        if key not in arguments:
+            problems.append(f'missing required argument "{key}"')
+    for key, value in arguments.items():
+        spec = properties.get(key)
+        if spec is None:
+            problems.append(f'unknown argument "{key}" (this tool takes: {", ".join(properties) or "nothing"})')
+        elif spec['type'] == 'string':
+            if not isinstance(value, str):
+                problems.append(f'"{key}" must be a string')
+            elif 'enum' in spec and value not in spec['enum']:
+                problems.append(f'"{key}" must be one of {", ".join(spec["enum"])}')
+            elif 'pattern' in spec and (len(value) > spec['maxLength'] or not C.LANE_RE.fullmatch(value)):
+                problems.append(f'"{key}" is not an id (letters, digits, _ . -; at most {spec["maxLength"]})')
+            elif len(value) < spec.get('minLength', 0):
+                problems.append(f'"{key}" must not be empty')
+            elif len(value) > spec.get('maxLength', len(value)):
+                problems.append(f'"{key}" is longer than {spec["maxLength"]} characters')
+        elif spec['type'] == 'boolean' and not isinstance(value, bool):
+            problems.append(f'"{key}" must be true or false')
+        elif spec['type'] == 'integer':
+            if not isinstance(value, int) or isinstance(value, bool):
+                problems.append(f'"{key}" must be an integer')
+            elif not spec['minimum'] <= value <= spec['maximum']:
+                problems.append(f'"{key}" must be between {spec["minimum"]} and {spec["maximum"]}')
+    return problems
+
+
+def freshness(status):
+    """The observation's age as a tool reports it."""
+    if not status['available']:
+        return {'available': False, 'why': status['why']}
+    return {'available': True, 'at': status['at'], 'age_s': status['age'], 'fresh': status['fresh']}
+
+
+def agent_summary(agent):
+    """The agent of a lanes_list row: harness, status, task name and since — what a list needs."""
+    if not isinstance(agent, dict) or not agent.get('status'):
+        return None
+    return {key: agent[key] for key in ('harness', 'status', 'name', 'since') if agent.get(key) is not None}
+
+
+OBSERVED = ('attached', 'viewers', 'activity', 'size', 'stale')
+
+
+class Server:
+    def __init__(self, root, environ=None, log=None, proc=Path('/proc'), home=None, signal=None):
+        self.root, self.proc = Path(root), proc
+        # The container's /home/coder as this process sees it: itself in a container (root ~/.lz), the volume a test
+        # builds otherwise. Every container path a write tool reads or writes goes through local().
+        self.home = Path(home) if home else self.root.parent
+        self.signal = Path(signal) if signal else Path(__file__).resolve().parent / 'lane-signal'
+        self.environ = os.environ if environ is None else environ
+        self.log = log or Log(None)
+        self.protocol = None
+        self.client = ''
+        version = C.read_regular(self.root / 'VERSION', 64)
+        self.version = (version or b'').decode('utf-8', 'replace').strip() or 'unknown'
+
+    # ---------------------------------------------------------------------------------------------- framing
+    def serve(self, rfile, wfile):
+        """Answer every line of `rfile` on `wfile` until EOF -> exit code 0."""
+        self.log.write(f'start lane-mcp {self.version} wire {WIRE} root {self.root}')
+        try:
+            while True:
+                raw = rfile.readline(LINE_MAX + 1)
+                if not raw:
+                    break
+                if len(raw) > LINE_MAX and not raw.endswith(b'\n'):
+                    while raw and not raw.endswith(b'\n'):   # the rest of the oversized line
+                        raw = rfile.readline(LINE_MAX)
+                    response = self.error(None, PARSE_ERROR, f'Parse error: a message longer than {LINE_MAX} bytes')
+                else:
+                    response = self.handle_line(raw)
+                if response is not None:
+                    self.send(wfile, response)
+        except BrokenPipeError:
+            self.log.write('stdout closed: exit')
+            return 0
+        self.log.write('stdin closed: exit')
+        return 0
+
+    @staticmethod
+    def send(wfile, message):
+        try:
+            data = json.dumps(message, ensure_ascii=False, separators=(',', ':')).encode('utf-8')
+        except UnicodeEncodeError:   # a lone surrogate echoed from the request: escape everything instead
+            data = json.dumps(message, separators=(',', ':')).encode('ascii')
+        wfile.write(data + b'\n')
+        wfile.flush()
+
+    @staticmethod
+    def error(request_id, code, message):
+        return {'jsonrpc': '2.0', 'id': request_id, 'error': {'code': code, 'message': message}}
+
+    def handle_line(self, raw):
+        """One frame -> the response to write, or None (a notification, a client response, a blank line)."""
+        raw = raw.strip()
+        if not raw:
+            return None
+        try:
+            message = json.loads(raw.decode('utf-8'))
+        except (UnicodeDecodeError, ValueError):
+            self.log.write('parse error')
+            return self.error(None, PARSE_ERROR, 'Parse error: a line that is not one JSON value')
+        if isinstance(message, list):
+            return self.error(None, INVALID_REQUEST, 'Invalid Request: batches are not supported')
+        request_id = message.get('id') if isinstance(message, dict) else None
+        if isinstance(request_id, bool) or not isinstance(request_id, (str, int, type(None))):
+            request_id = None
+        if not isinstance(message, dict) or message.get('jsonrpc') != '2.0':
+            return self.error(request_id, INVALID_REQUEST, 'Invalid Request: not a JSON-RPC 2.0 message')
+        if 'method' not in message:
+            return None   # a response to a request we never send
+        method = message['method']
+        if not isinstance(method, str):
+            return self.error(request_id, INVALID_REQUEST, 'Invalid Request: method must be a string')
+        params = message.get('params')
+        if 'id' not in message:
+            self.notification(method)
+            return None
+        if message['id'] is None or request_id is None:
+            return self.error(None, INVALID_REQUEST, 'Invalid Request: id must be a string or an integer')
+        if params is not None and not isinstance(params, dict):
+            return self.error(request_id, INVALID_PARAMS, 'Invalid params: params must be an object')
+        started = time.monotonic()
+        try:
+            result = self.request(method, params or {})
+        except RpcError as error:
+            self.log.write(f'{method} id={request_id!r} error {error.code} {error.message}')
+            return self.error(request_id, error.code, error.message)
+        except Exception:   # a defect here must not end the session: the agent gets an error, the log the trace
+            self.log.write(f'{method} id={request_id!r} internal error', trace=traceback.format_exc())
+            return self.error(request_id, INTERNAL_ERROR, f'Internal error (see {LOG_HINT})')
+        if method != 'tools/call':
+            self.log.write(f'{method} id={request_id!r} ok {time.monotonic() - started:.3f}s')
+        return {'jsonrpc': '2.0', 'id': request_id, 'result': result}
+
+    def notification(self, method):
+        if method == 'notifications/initialized':
+            self.log.write('initialized')
+        elif method != 'notifications/cancelled':
+            self.log.write(f'notification {method} ignored')
+
+    def request(self, method, params):
+        if method == 'initialize':
+            return self.initialize(params)
+        if method == 'ping':
+            return {}
+        if self.protocol is None:
+            raise RpcError(NOT_INITIALIZED, 'Server not initialized: send initialize first')
+        if method == 'tools/list':
+            return {'tools': json.loads(json.dumps(TOOLS))}
+        if method == 'tools/call':
+            return self.call(params)
+        raise RpcError(METHOD_NOT_FOUND, f'Method not found: {method}')
+
+    def initialize(self, params):
+        requested = params.get('protocolVersion')
+        self.protocol = requested if requested in PROTOCOLS else PROTOCOLS[0]
+        client = params.get('clientInfo') if isinstance(params.get('clientInfo'), dict) else {}
+        self.client = str(client.get('name') or '')[:64]
+        self.log.write(f'initialize client={str(client.get("name"))[:64]!r} {str(client.get("version"))[:32]!r} '
+                       f'asked={str(requested)[:32]!r} protocol={self.protocol}')
+        return {'protocolVersion': self.protocol, 'capabilities': {'tools': {'listChanged': False}},
+                'serverInfo': {'name': 'lanes', 'version': self.version}, 'instructions': INSTRUCTIONS}
+
+    # ---------------------------------------------------------------------------------------------- tools
+    def call(self, params):
+        name, arguments = params.get('name'), params.get('arguments')
+        if not isinstance(name, str) or name not in TOOL_BY_NAME:
+            raise RpcError(INVALID_PARAMS, f'Unknown tool: {name!r} (tools/list names them)')
+        started, lane, code = time.monotonic(), None, None
+        writes = name in WRITE_TOOLS
+        try:
+            if arguments is None:
+                arguments = {}
+            if not isinstance(arguments, dict):
+                raise ToolError('arguments must be an object')
+            lane = arguments.get('lane') if C.LANE_RE.fullmatch(str(arguments.get('lane') or '')) else None
+            problems = validate(TOOL_BY_NAME[name]['inputSchema'], arguments)
+            if problems:
+                raise ToolError('; '.join(problems))
+            payload, error = getattr(self, 'tool_' + name[len('lanes_'):])(arguments), False
+            if writes and isinstance(payload, dict):
+                lane = payload.get('lane') or payload.get('lane_id') or lane
+        except (ToolError, C.LaneError) as refusal:
+            if writes:   # a write tool always answers JSON: a refusal is {refused, why, human}
+                if isinstance(refusal, C.LaneError):
+                    refusal = Refusal.of(refusal)
+                elif not isinstance(refusal, Refusal):   # a plain ToolError: the arguments, outside the schema
+                    refusal = Refusal('invalid_arguments', str(refusal))
+                code = refusal.code
+                payload = refusal.payload()
+            else:
+                payload = str(refusal)
+            error = True
+        except Exception:
+            self.log.write(f'tools/call {name} internal error', trace=traceback.format_exc())
+            payload, error = f'internal error in {name} (see {LOG_HINT})', True
+            if writes:
+                code, payload = 'internal_error', {'refused': 'internal_error', 'why': payload,
+                                                   'human': f'A person reads {LOG_HINT}.'}
+        outcome = (f'isError refused={code}' if code else 'isError') if error else 'ok'
+        self.log.write(f'tools/call {name}' + (f' lane={lane}' if lane else '')
+                       + f' {outcome} {time.monotonic() - started:.3f}s')
+        text = payload if isinstance(payload, str) else json.dumps(payload, ensure_ascii=False, indent=1)
+        return {'content': [{'type': 'text', 'text': text}], 'isError': error}
+
+    def tool_whoami(self, _arguments):
+        found = C.whoami(self.root, self.environ)
+        out = {'lane': found['lane'], 'found_by': found['found_by'], 'kind': found['kind']}
+        entry, session = found.get('entry'), found.get('session')
+        if entry:
+            out.update(self.facts(entry))
+        elif session:
+            out.update({'workspace': session.get('workspace'), 'name': session.get('name'), 'holder': 'tmux',
+                        'tmux': session.get('tmux'), 'boards': session.get('boards')})
+        if found.get('tmux'):
+            out['tmux'] = found['tmux']
+        if found.get('why'):
+            out['why'] = found['why']
+        return out
+
+    @staticmethod
+    def facts(entry):
+        """The registry facts of a lane (DM-LANES-REGISTRY's in-container entry), in a fixed order."""
+        return {'workspace': entry.get('ws'), 'name': entry.get('name'), 'holder': entry.get('holder'),
+                'tmux': entry.get('tmux'), 'container': entry.get('container'), 'source': entry.get('source'),
+                'repo': entry.get('repo'), 'registry_name': entry.get('registry_name'), 'folder': entry.get('folder')}
+
+    def lanes(self):
+        """(registry lanes, the container's status) — the two projections every tool reads."""
+        return C.registry_lanes(self.root), C.container_status(self.root)
+
+    def tool_list(self, arguments):
+        lanes, status = self.lanes()
+        rows = []
+        for lane_id, entry in lanes.items():
+            observed = status['lanes'].get(lane_id) or {}
+            rows.append({'id': lane_id, 'name': entry.get('name') or lane_id, 'workspace': entry.get('ws'),
+                         'kind': C.lane_kind(entry), 'holder': entry.get('holder'),
+                         'state': observed.get('state', 'unknown'), 'agent': agent_summary(observed.get('agent')),
+                         **{key: observed[key] for key in OBSERVED if key in observed}, '_boards': [entry.get('ws')]})
+        for ghost in status['unregistered']:
+            observed = status['lanes'].get(ghost['id']) or {}
+            rows.append({'id': ghost['id'], 'name': ghost.get('name') or ghost['id'], 'workspace': ghost.get('workspace'),
+                         'kind': 'unregistered', 'holder': 'tmux', 'state': observed.get('state', 'unknown'),
+                         'agent': agent_summary(observed.get('agent')),
+                         **{key: observed[key] for key in OBSERVED if key in observed},
+                         '_boards': list(ghost.get('boards') or [ghost.get('workspace')])})
+        workspaces = sorted({board for row in rows for board in row['_boards'] if board})
+        want_ws, want_agent = arguments.get('workspace'), arguments.get('agent')
+        picked = []
+        for row in rows:
+            boards = row.pop('_boards')
+            agent = row['agent']
+            if want_ws and want_ws not in boards:
+                continue
+            if arguments.get('needs_you') and (not agent or agent.get('status') not in C.NEEDS_YOU):
+                continue
+            if want_agent == 'any' and not agent or want_agent == 'none' and agent:
+                continue
+            if want_agent in ('claude', 'codex') and (not agent or agent.get('harness') != want_agent):
+                continue
+            picked.append(row)
+        container = next((entry.get('container') for entry in lanes.values() if entry.get('container')), None)
+        return {'container': container, 'status': freshness(status), 'workspaces': workspaces, 'count': len(picked),
+                'lanes': picked}
+
+    def find(self, lane):
+        """(registry entry or None, unregistered row or None, status) of a lane id; ToolError when this container
+        holds no such lane."""
+        lanes, status = self.lanes()
+        entry = lanes.get(lane)
+        ghost = None if entry else next((row for row in status['unregistered'] if row['id'] == lane), None)
+        if not entry and not ghost:
+            raise ToolError(f'no lane {lane!r} in this container — lanes_list shows the lanes it holds')
+        return entry, ghost, status
+
+    def tool_status(self, arguments):
+        lane = arguments['lane']
+        entry, ghost, status = self.find(lane)
+        observed = status['lanes'].get(lane) or {}
+        if entry:
+            out = {'id': lane, 'kind': C.lane_kind(entry), **self.facts(entry)}
+            target = C.tmux_target(entry)
+        else:
+            tmux = ghost.get('tmux') or {}
+            out = {'id': lane, 'kind': 'unregistered', 'workspace': ghost.get('workspace'), 'name': ghost.get('name'),
+                   'holder': 'tmux', 'tmux': tmux, 'boards': ghost.get('boards'), 'identity': ghost.get('identity')}
+            target = (tmux['socket'], tmux['session']) if tmux.get('socket') and tmux.get('session') else None
+        out['state'] = observed.get('state', 'unknown')
+        out['agent'] = observed.get('agent') if isinstance(observed.get('agent'), dict) else None
+        out.update({key: observed[key] for key in OBSERVED if key in observed})
+        alive = None
+        if target:
+            code = C.run_tmux(C.tmux_argv(target[0], 'has-session', '-t', f'={target[1]}')).returncode
+            alive = None if code in (124, 127) else code == 0
+        out['alive'] = alive
+        out['hook'] = C.hook_agent(self.root / 'state' / 'hooks', lane, self.proc) or None
+        out['status'] = freshness(status)
+        return out
+
+    def tool_capture(self, arguments):
+        lane, lines = arguments['lane'], arguments.get('lines', CAPTURE_DEFAULT)
+        entry, ghost, _status = self.find(lane)
+        if entry:
+            target = C.tmux_target(entry)
+            if not target:
+                raise ToolError(f'{lane} is held by {entry.get("holder")}, not tmux — read it with '
+                                f'`~/.lz/bin/lane capture {lane}`')
+        else:
+            tmux = ghost.get('tmux') or {}
+            if not (tmux.get('socket') and tmux.get('session')):
+                raise ToolError(f'{lane} has no tmux target in ~/.lz/status.json')
+            target = (tmux['socket'], tmux['session'])
+        result = C.run_tmux(C.capture_argv(target[0], target[1], lines))
+        if result.returncode != 0:
+            why = (result.stderr or '').strip().splitlines()
+            raise ToolError(f'{lane}: {why[0] if why else f"tmux exit {result.returncode}"} — lanes_status says '
+                            f'whether it is running')
+        text = C.last_lines(result.stdout, lines)
+        if len(text) > TEXT_MAX:
+            text = text[-TEXT_MAX:]
+            text = '[… earlier output omitted]\n' + text[text.find('\n') + 1:]
+        return text
+
+    # ---------------------------------------------------------------------------------------------- write helpers
+    def local(self, path):
+        """A container path under /home/coder as this process reaches it (self.home + the rest); ValueError for any
+        other path."""
+        text = str(path)
+        if not (text + '/').startswith(C.CONTAINER_HOME + '/') or '..' in text.split('/'):
+            raise ValueError(f'{text} is not under {C.CONTAINER_HOME}')
+        rest = text[len(C.CONTAINER_HOME) + 1:]
+        return self.home / rest if rest else self.home
+
+    def find_write(self, lane):
+        """(registry entry or None, unregistered row or None, status) of a lane of THIS container; refused
+        `not_in_container` otherwise — every write reaches this container's lanes only."""
+        lanes, status = self.lanes()
+        entry = lanes.get(lane)
+        ghost = None if entry else next((row for row in status['unregistered'] if row['id'] == lane), None)
+        if not entry and not ghost:
+            refuse('not_in_container', f'no lane {lane!r} in this container')
+        return entry, ghost, status
+
+    @staticmethod
+    def declared(lanes):
+        """{lane id: entry} of the lanes a terminals.json declares (an adopted session names none)."""
+        return {key: entry for key, entry in lanes.items()
+                if entry.get('source') and not entry.get('registered_session')}
+
+    @staticmethod
+    def refuse_lane(lane_id, entry):
+        """A session that is a lane already: adopted on the host, or declared."""
+        if entry.get('registered_session'):
+            refuse('adopted_lane', f'{lane_id} was adopted on the host (registered-sessions.json): an agent never edits '
+                                   'an adopted session', lane=lane_id)
+        refuse('already_declared', f'{lane_id} is declared already ({entry.get("source") or "a terminals.json"})',
+               lane=lane_id)
+
+    def declared_target(self, lane, entry):
+        """(path, doc, terminal name) of a declared lane's terminal in its terminals.json, or a refusal."""
+        if entry.get('registered_session'):
+            self.refuse_lane(lane, entry)
+        if not entry.get('source'):
+            refuse('not_declared_here', f'{lane} names no terminals.json')
+        path, _text, doc = self.read_source(entry['source'])
+        name = C.declared_name(doc, entry)
+        if name is None:
+            refuse('not_declared_here', f'{entry["source"]} declares no terminal this container can match to {lane} '
+                                        '(by its tmux binding or its name)')
+        return path, doc, name
+
+    def read_source(self, source):
+        """(local path, text, parsed document) of a terminals.json named by its container path."""
+        try:
+            path = self.local(source)
+        except ValueError as error:
+            refuse('not_declared_here', str(error))
+        if not os.path.lexists(str(path)):
+            refuse('source_missing', f'{source} does not exist in this container')
+        _ident, text = C._snapshot(path)
+        return path, text, C.strict_json(text, source)
+
+    @staticmethod
+    def edit_source(path, source, transform):
+        """lane_core.edit_file with a terminals.json transform -> (before, after). The file is the repository's own
+        (git is its history), so no backup is kept; its mode is."""
+        def guarded(text):
+            if text is None:
+                raise C.LaneError(f'{source} disappeared while it was being edited', 'source_missing')
+            return transform(text)
+        before, after, _backup = C.edit_file(path, guarded)
+        return before, after
+
+    def plan(self, lanes, status, boards, repo, name, prefer):
+        """Where a new declaration named `name` goes and the id `lanes sync` will give it: the one terminals.json of
+        `boards` (narrowed by `repo`) in this container, the prefix each board that reads that file puts before its
+        names, and per board the predicted id `<ws>--<slug(prefix + name)>`. Refuses a name or id the board already
+        uses: a row reading the same (the host would refuse the board, or drop another lane's display name) or an id
+        `build_registry` would have to suffix (`-2`: the new lane could take an existing lane's id)."""
+        declared = self.declared(lanes)
+        on_boards = [entry for entry in declared.values() if entry.get('ws') in boards]
+        candidates = [entry for entry in on_boards if not repo or entry.get('repo') == repo]
+        sources = sorted({entry['source'] for entry in candidates})
+        repos = sorted({str(entry.get('repo')) for entry in on_boards})
+        where = ', '.join(sorted(board for board in boards if board)) or 'none'
+        if not sources:
+            refuse('no_source', f'no repository {"named " + repr(repo) + " " if repo else ""}declares lanes of board '
+                                f'{where} in this container', repos=repos)
+        if len(sources) > 1:
+            refuse('ambiguous_source', f'board {where} has {len(sources)} repositories in this container '
+                                       f'({", ".join(repos)}): which terminals.json gets the lane?', repos=repos)
+        source = sources[0]
+        path, _text, doc = self.read_source(source)
+        by_ws = {}
+        for entry in declared.values():
+            if entry['source'] == source:
+                by_ws.setdefault(entry.get('ws'), []).append(entry)
+        taken = set(lanes) | {row['id'] for row in status['unregistered']}
+        ids = {}
+        for ws, entries in sorted(by_ws.items()):
+            prefix = C.source_prefix(doc, entries)
+            if prefix is None:
+                refuse('unknown_prefix', f'cannot tell which prefix board {ws} puts before the names in {source}')
+            title = prefix + name
+            key = C.shown_key(title)
+            for other_id, other in lanes.items():
+                if other.get('ws') == ws and key in {C.shown_key(str(other.get(field) or ''))
+                                                     for field in ('name', 'registry_name')}:
+                    refuse('duplicate_name', f'{title!r} is the name of {other_id} on board {ws}', lane=other_id)
+            lane_id = f'{ws}--{C.slug(title)}'
+            twins = re.compile(re.escape(lane_id) + r'(?:-[0-9]+)?')
+            clash = sorted(other for other in taken if twins.fullmatch(other)) + sorted(
+                other for other, entry in declared.items() if entry.get('ws') == ws and entry.get('registry_name')
+                and f'{ws}--{C.slug(entry["registry_name"])}' == lane_id)
+            if clash:
+                refuse('slug_collision', f'{title!r} makes the lane id {lane_id}, which {clash[0]} holds or is named '
+                                         'from', lane_id=lane_id, lane=clash[0])
+            ids[ws] = lane_id
+        ws = prefer if prefer in ids else sorted(ids)[0]
+        return {'source': source, 'path': path, 'ws': ws, 'lane_id': ids[ws], 'ids': ids,
+                'repo': next((entry.get('repo') for entry in by_ws[ws] if entry.get('repo')), None),
+                'folder': next((entry.get('folder') for entry in by_ws[ws] if entry.get('folder')), None)
+                or C.CONTAINER_HOME}
+
+    @staticmethod
+    def session_state(socket, session):
+        """has-session (with -N) -> True (running), False (not running, or no server), or a refusal when tmux did
+        not answer."""
+        result = C.run_tmux(C.tmux_argv(socket, 'has-session', '-t', f'={session}'))
+        if result.returncode in (124, 127):
+            refuse('tmux_unanswered', (result.stderr or '').strip() or f'tmux exit {result.returncode}')
+        return result.returncode == 0
+
+    def check_cwd(self, cwd):
+        """An existing directory under /home/coder, spelled as a lane folder may be -> its normalized path."""
+        if not C.SAFE_PATH.match(cwd) or '..' in cwd.split('/'):
+            refuse('invalid_cwd', f'{cwd!r}: an absolute path of letters, digits, _ . / - only')
+        cwd = os.path.normpath(cwd)
+        if not (cwd + '/').startswith(C.CONTAINER_HOME + '/'):
+            refuse('invalid_cwd', f'{cwd} is outside {C.CONTAINER_HOME}')
+        local = self.local(cwd)
+        if not local.is_dir():
+            refuse('invalid_cwd', f'{cwd} is not an existing directory')
+        real, home = os.path.realpath(str(local)), os.path.realpath(str(self.home))
+        if real != home and not real.startswith(home + os.sep):
+            refuse('invalid_cwd', f'{cwd} leads outside {C.CONTAINER_HOME} (a symbolic link)')
+        return cwd
+
+    @staticmethod
+    def unprintable(text):
+        """The control characters (and lone surrogates) of `text`, as U+XXXX."""
+        return sorted({f'U+{ord(ch):04X}' for ch in text if unicodedata.category(ch) in ('Cc', 'Cs')})
+
+    # ---------------------------------------------------------------------------------------------- write tools
+    def tool_register(self, arguments):
+        name = arguments['name']
+        problem = C.lane_name_problem(name)
+        if problem:
+            refuse('invalid_name', f'{name!r}: {problem}')
+        lanes, status = self.lanes()
+        if arguments.get('session'):
+            wanted = arguments['session']
+            ghost = next((row for row in status['unregistered'] if row['id'] == wanted), None)
+            if ghost is None:
+                if wanted in lanes:
+                    self.refuse_lane(wanted, lanes[wanted])
+                refuse('not_in_container', f'no unregistered session {wanted!r} in this container')
+        else:
+            found = C.whoami(self.root, self.environ)
+            ghost = found.get('session') if found['kind'] == 'unregistered' else None
+            if ghost is None:
+                if found.get('entry'):
+                    self.refuse_lane(found['lane'], found['entry'])
+                if found['lane']:
+                    refuse('not_tmux', f'{found["lane"]} is no tmux session of this container\'s status '
+                                       f'({found.get("why") or "not listed"})')
+                refuse('not_in_lane', found.get('why') or 'this agent runs in no lane',
+                       'Run it from inside an unregistered tmux session, or pass `session` (lanes_list shows the '
+                       'unregistered ones).')
+        tmux = ghost.get('tmux') if isinstance(ghost.get('tmux'), dict) else {}
+        socket, session = tmux.get('socket'), tmux.get('session')
+        if not (isinstance(socket, str) and C.IDENT.match(socket) and isinstance(session, str)
+                and C.TMUX_SESSION.match(session)):
+            refuse('invalid_session', f'the tmux session {socket!r}/{session!r} cannot be declared as a lane')
+        for lane_id, entry in lanes.items():
+            if C.tmux_target(entry) == (socket, session):
+                self.refuse_lane(lane_id, entry)
+        boards = [board for board in (ghost.get('boards') or [ghost.get('workspace')]) if board]
+        plan = self.plan(lanes, status, boards, arguments.get('repo'), name, ghost.get('workspace'))
+        if not self.session_state(socket, session):
+            refuse('session_gone', f'the tmux session {socket}/{session} is not running')
+        lane_id = plan['lane_id']
+        recipe = C.canonical_recipe(lane_id, plan['ws'], socket, session, plan['folder'])
+        terminal = {'name': name, 'command': C.LANE_OPEN_COMMAND + lane_id}
+        entry = {'id': lane_id, 'holder': 'tmux', 'tmux': {'socketName': socket, 'sessionName': session},
+                 'create': recipe}
+        self.edit_source(plan['path'], plan['source'], lambda text: C.terminals_add(text, terminal, entry))
+        out = {'lane_id': lane_id, 'workspace': plan['ws'], 'name': name, 'source': plan['source'],
+               'repo': plan['repo'], 'tmux': {'socket': socket, 'session': session}, 'was': ghost.get('id'),
+               'changed': f'{plan["source"]}: appended the terminal {name!r} (command `lane open {lane_id}`) and its '
+                          f'lanes.terminals entry (tmux {socket}/{session}, the canonical create recipe); the '
+                          'session itself is untouched',
+               'picked_up_by': SYNC_PICKUP, 'expected_within_s': SYNC_LATENCY_S}
+        if len(plan['ids']) > 1:   # one terminals.json read by several boards: the lane shows on each
+            out['also'] = {ws: other for ws, other in plan['ids'].items() if ws != plan['ws']}
+        return out
+
+    def tool_unregister(self, arguments):
+        lane = arguments['lane']
+        entry, ghost, _status = self.find_write(lane)
+        if ghost:
+            refuse('unregistered', f'{lane} is an unregistered session: there is no declaration to remove',
+                   'Nothing to unregister. A person closes the session on the board if it should end.')
+        path, _doc, name = self.declared_target(lane, entry)
+        self.edit_source(path, entry['source'], lambda text: C.terminals_remove(text, name))
+        target = C.tmux_target(entry)
+        return {'lane': lane, 'removed': name, 'source': entry['source'], 'repo': entry.get('repo'),
+                'tmux': {'socket': target[0], 'session': target[1]} if target else None,
+                'changed': f'{entry["source"]}: removed the terminal {name!r} and its lanes.terminals entry',
+                'session': 'keeps running: nothing was stopped; it shows as an unregistered session once lanes sync '
+                           'drops the declaration',
+                'picked_up_by': SYNC_PICKUP, 'expected_within_s': SYNC_LATENCY_S}
+
+    def tool_rename(self, arguments):
+        lane, display = arguments['lane'], arguments['display_name']
+        if self.unprintable(display) or display != display.strip() or not C.shown_key(display):
+            refuse('invalid_name', f'{display!r}: a display name is one line of visible text, without leading or '
+                                   'trailing spaces', 'Pass one line of visible text.')
+        entry, ghost, _status = self.find_write(lane)
+        if ghost:
+            refuse('unregistered', f'{lane} is an unregistered session: only a declared lane has a display name here',
+                   'Declare it first: lanes_register (its name is the display name). A person can also rename it on '
+                   'the board (R).')
+        if entry.get('registered_session'):
+            self.refuse_lane(lane, entry)
+        key = C.shown_key(display)
+        for other_id, other in self.lanes()[0].items():
+            if other_id != lane and other.get('ws') == entry.get('ws') and key in {
+                    C.shown_key(str(other.get(field) or '')) for field in ('name', 'registry_name')}:
+                refuse('duplicate_name', f'{display!r} is the name of {other_id} on board {entry.get("ws")}: the board '
+                                         'would drop it', lane=other_id)
+        path, doc, name = self.declared_target(lane, entry)
+        title = entry.get('registry_name')
+        target = None if display == title else display
+        current = ((C._lanes_terminals(doc) or {}).get(name) or {}).get('displayName')
+        before, after = self.edit_source(path, entry['source'],
+                                         lambda text: C.terminals_set_display(text, name, target))
+        if before == after:
+            changed = 'nothing: that is its display name already'
+        elif target is None:
+            changed = f'{entry["source"]}: removed lanes.terminals[{name!r}].displayName (the lane shows its title)'
+        else:
+            changed = f'{entry["source"]}: lanes.terminals[{name!r}].displayName = {display!r}'
+        out = {'lane': lane, 'display_name': display, 'terminal': name, 'source': entry['source'], 'changed': changed,
+               'picked_up_by': SYNC_PICKUP, 'expected_within_s': SYNC_LATENCY_S}
+        shown = entry.get('name')
+        if shown not in (title, current, None):   # what the board shows comes from neither layer of the file
+            out['host_override'] = shown
+            out['note'] = (f'the host names this lane {shown!r} (its workspace manifest, which wins): the boards keep '
+                           'showing that until a person clears it there')
+        return out
+
+    def tool_new(self, arguments):
+        name = arguments['name']
+        problem = C.lane_name_problem(name)
+        if problem:
+            refuse('invalid_name', f'{name!r}: {problem}')
+        command = arguments.get('command') or 'bash -l'
+        if self.unprintable(command) or not command.strip():
+            refuse('invalid_command', f'the command holds {", ".join(self.unprintable(command)) or "nothing"}')
+        lanes, status = self.lanes()
+        ws = arguments.get('workspace')
+        if not ws:
+            found = C.whoami(self.root, self.environ)
+            ws = (found.get('entry') or {}).get('ws') or (found.get('session') or {}).get('workspace')
+            if not ws:
+                boards = sorted({entry.get('ws') for entry in self.declared(lanes).values() if entry.get('ws')})
+                if len(boards) != 1:
+                    refuse('ambiguous_workspace', f'this agent runs in no lane, and this container holds the lanes of '
+                                                  f'{len(boards)} boards', workspaces=boards)
+                ws = boards[0]
+        socket, session = C.SHELL_SOCKET + ws, C.slug(name)[:40]
+        plan = self.plan(lanes, status, [ws], arguments.get('repo'), name, ws)
+        cwd = self.check_cwd(arguments.get('cwd') or plan['folder'])
+        for lane_id, entry in lanes.items():
+            if C.tmux_target(entry) == (socket, session):
+                refuse('duplicate_binding', f'{lane_id} is declared on tmux {socket}/{session} already', lane=lane_id)
+        if self.session_state(socket, session):
+            refuse('session_exists', f'a tmux session {session!r} runs on {socket} already')
+        lane_id = plan['lane_id']
+        recipe = C.canonical_recipe(lane_id, ws, socket, session, cwd, command)
+        terminal = {'name': name, 'command': C.LANE_OPEN_COMMAND + lane_id}
+        entry = {'id': lane_id, 'holder': 'tmux', 'tmux': {'socketName': socket, 'sessionName': session},
+                 'create': recipe}
+        self.edit_source(plan['path'], plan['source'], lambda text: C.terminals_add(text, terminal, entry))
+        changed = (f'{plan["source"]}: appended the terminal {name!r} and its lanes.terminals entry (tmux '
+                   f'{socket}/{session}, the canonical create recipe)')
+        started = C.run_tmux(C.new_session_argv(socket, session, cwd, lane_id, ws, command), env=C.creation_env())
+        if started.returncode != 0:
+            why = (started.stderr or '').strip().splitlines()
+            refuse('tmux_failed', f'declared, but tmux did not start the session: '
+                                  f'{why[0] if why else "exit " + str(started.returncode)}',
+                   f'The lane is declared: opening it on a board, or `~/.lz/bin/lane open {lane_id}` once lanes sync '
+                   'has run, starts it from its recipe.', changed=changed, lane_id=lane_id,
+                   picked_up_by=SYNC_PICKUP, expected_within_s=SYNC_LATENCY_S)
+        out = {'lane_id': lane_id, 'workspace': ws, 'name': name, 'source': plan['source'], 'repo': plan['repo'],
+               'tmux': {'socket': socket, 'session': session}, 'cwd': cwd, 'command': command,
+               'changed': changed + f'; started tmux session {session!r} on {socket} in {cwd}',
+               'picked_up_by': SYNC_PICKUP, 'expected_within_s': SYNC_LATENCY_S}
+        if len(plan['ids']) > 1:
+            out['also'] = {board: other for board, other in plan['ids'].items() if board != ws}
+        return out
+
+    def tool_send(self, arguments):
+        lane, text = arguments['lane'], arguments['text']
+        enter, force = arguments.get('enter', True), arguments.get('force', False)
+        bad = self.unprintable(text)
+        if bad:
+            refuse('invalid_text', f'the text holds {", ".join(bad)}: lanes_send types printable text only')
+        entry, ghost, status = self.find_write(lane)
+        if entry:
+            target = C.tmux_target(entry)
+            if not target:
+                refuse('not_tmux', f'{lane} is held by {entry.get("holder")}, not tmux')
+        else:
+            tmux = ghost.get('tmux') if isinstance(ghost.get('tmux'), dict) else {}
+            if not (tmux.get('socket') and tmux.get('session')):
+                refuse('not_tmux', f'{lane} has no tmux target in ~/.lz/status.json')
+            target = (tmux['socket'], tmux['session'])
+        if not force:
+            observed = (status['lanes'].get(lane) or {}).get('agent')
+            hook = C.hook_agent(self.root / 'state' / 'hooks', lane, self.proc)
+            for said_by, agent in (('the host\'s observation', observed), ('its lane-signal hook', hook)):
+                state = agent.get('status') if isinstance(agent, dict) else None
+                if state == 'working':
+                    refuse('agent_working', f'{lane}\'s agent is working ({said_by}): text typed now lands in the '
+                                            'middle of its turn')
+                if state == 'needs_approval':
+                    refuse('agent_needs_approval', f'{lane}\'s agent waits for an approval ({said_by}): typed text '
+                                                   'would answer its prompt')
+        results = C.send_keys(target[0], target[1], text, enter)
+        result = results[-1]
+        if result.returncode:
+            why = (result.stderr or '').strip().splitlines()
+            why = why[0] if why else 'tmux exit ' + str(result.returncode)
+            if len(results) == 2:   # the text went in; its Enter did not
+                refuse('tmux_unanswered' if result.returncode in (124, 127) else 'tmux_failed',
+                       f'{lane}: typed the text, but Enter was not pressed: {why}',
+                       'The text waits at the lane\'s prompt: a person presses Enter there, or clears it.',
+                       changed=f'typed {len(text)} characters into {lane}, without Enter')
+            refuse('tmux_unanswered' if result.returncode in (124, 127) else 'tmux_failed',
+                   f'{lane}: {why} — nothing was typed')
+        return {'lane': lane, 'typed': len(text), 'enter': enter, 'forced': bool(force),
+                'changed': f'typed {len(text)} characters{" and Enter" if enter else ""} into {lane}',
+                'picked_up_by': 'the program in the lane\'s active pane', 'expected_within_s': 0}
+
+    def tool_signal(self, arguments):
+        word, note = arguments['status'], arguments.get('note')
+        if note is not None and self.unprintable(note):
+            refuse('invalid_note', f'the note holds {", ".join(self.unprintable(note))}')
+        found = C.whoami(self.root, self.environ)
+        lane = found['lane']
+        if not lane:
+            refuse('not_in_lane', found.get('why') or 'this agent runs in no lane',
+                   'lanes_signal reports the lane this agent runs in: start the agent inside a lane (for Codex, '
+                   '`lane mcp install` passes the lane\'s variables to this server).')
+        client = self.client.lower()
+        harness = ('claude' if 'claude' in client else 'codex' if 'codex' in client
+                   else 'claude' if self.environ.get('CLAUDE_CODE_ENTRYPOINT') else '')
+        # The agent is this server's parent (Claude Code and Codex start it directly): lane-signal records ITS pid,
+        # so the host's liveness check follows the agent, not this process.
+        argv = [sys.executable, str(self.signal), word, '--event', 'lanes_signal', '--agent-pid', str(os.getppid())]
+        argv += ['--harness', harness] if harness else []
+        argv += ['--note', note] if note is not None else []
+        env = {'PATH': os.environ.get('PATH') or '/usr/bin:/bin', 'HOME': str(self.home), 'LANG': 'C.UTF-8',
+               'LANE_ROOT': str(self.root), 'LANE_ID': lane}
+        # The agent's session, so the sidecar names the session its own hooks name (their stdin's `session_id`):
+        # Claude Code gives its MCP servers CLAUDE_CODE_SESSION_ID (MEASURED 2026-10-06 in a server's environ; it
+        # equals the session's transcript id). lane-signal matches a report to the agent's hooks by the agent's pid and
+        # starttime first (Codex clears a server's environment; a /clear gives the agent a new session), then by this
+        # session (DEF-1801).
+        env.update({key: self.environ[key] for key in SESSION_VARS if self.environ.get(key)})
+        started = int(time.time())
+        try:
+            subprocess.run(argv, env=env, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+                           stderr=subprocess.DEVNULL, timeout=10)
+        except (OSError, subprocess.SubprocessError) as error:
+            refuse('signal_not_written', f'lane-signal did not run: {error}')
+        side = C.read_json(self.root / 'state' / 'hooks' / f'{lane}.json')
+        if not (isinstance(side, dict) and side.get('status') == word and side.get('event') == 'lanes_signal'
+                and isinstance(side.get('at'), int) and side['at'] >= started):
+            refuse('signal_not_written', f'lane-signal wrote no sidecar for {lane} (~/.lz/state/hooks/{lane}.json)')
+        return {'lane': lane, 'status': word, 'since': side.get('since'), 'note': side.get('name') or None,
+                'changed': f'~/.lz/state/hooks/{lane}.json: status {word}'
+                           + (', note set' if side.get('name') else ', no note'),
+                'stands_until': SIGNAL_STANDS if word != 'working' else SIGNAL_WORKING,
+                'picked_up_by': STATUS_PICKUP, 'expected_within_s': STATUS_LATENCY_S}
+
+
+def main(argv):
+    if argv:
+        if argv[0] in ('-h', '--help'):
+            sys.stderr.write(__doc__)
+            return 0
+        sys.stderr.write('usage: lane-mcp   (an MCP server on stdin/stdout, started by the agent from its MCP config; '
+                         'lane mcp install adds it)\n')
+        return 2
+    root = Path(os.environ.get('LANE_ROOT') or C.LZ)
+    log = Log(root / 's' / 'logs' / 'lane-mcp.log')
+    out = os.fdopen(os.dup(1), 'wb', buffering=0)   # the protocol stream: frames only
+    try:
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, 1)
+        os.close(devnull)
+    except OSError:
+        pass
+    sys.stdout = sys.stderr   # a print() can never reach the protocol stream
+    return Server(root, log=log).serve(sys.stdin.buffer, out)
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))