@vibelord/lanes 1.2.0 → 1.5.0

package/payload/lanes/container/lane_core.py

@@ -24,7 +24,17 @@ sees, and `lane-mcp` may write nothing but protocol frames to its stdout.
     `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.
+    ~/.codex/config.toml — and (W12) `mcpServers.lanes` in ~/.kimi-code/mcp.json, a `# >>> lanes mcp >>>` block with
+    `[mcp_servers.lanes]` in Grok Build's ~/.grok-build/config.toml and the `lanes` item of grok-cli's `mcp.servers` in
+    ~/.grok/user-settings.json, those three where the harness's home exists — planned as a diff, written with a
+    `.bak-<UTC>` copy, atomically and only when missing. TOML marker blocks (toml_block) are shared with the host's
+    `lanes hooks install`.
+  * the harness of a process (W12): process_harness / parent_harness over /proc (comm, the grok exe split, a native
+    Claude Code file), and whoami's fallback to the agent's own /proc environ (parent_environ) for a harness that strips
+    its MCP servers' environment (grok-cli).
+  * publish requests (plan W10 W4): `publish` writes ~/.lz/state/publish/<lane>/<id>.json for `lane publish` and
+    lane-mcp's `lanes_publish` (the file hashed once, the id in docs_store's grammar: `new_publish_id`), and
+    `latest_receipt` reads the `<id>.receipt.json` the host's lanes-docsd writes back (`lanes_status`'s `published`).
 """
 import difflib
 import json
@@ -48,7 +58,9 @@ HOOK_MAX_AGE = 3600       # statusd.SIDECAR_MAX_AGE: an older last event is no a
 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)
+IDENTITY = ('LANE_ID', 'LANE_WS', 'THROTTLE_TRACE', 'LANES_TRACE')   # + our trace headers and GROK_HOME (identity_free)
+TRACE_HEADERS = ('ANTHROPIC_CUSTOM_HEADERS', 'KIMI_CODE_CUSTOM_HEADERS')   # ours: 'x-throttle-trace: lanes/<ws>/<id>'
+GROK_HOME = CONTAINER_HOME + '/.grok-build'   # Grok Build's home in a lane, never grok-cli's ~/.grok (DM-LANES-GROK-HOME)
 
 
 class LaneError(Exception):
@@ -201,9 +213,11 @@ def identity_free(environ, drop=('TMUX',)):
     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."""
+    An operator's own ANTHROPIC_CUSTOM_HEADERS / KIMI_CODE_CUSTOM_HEADERS that is not a lane trace is theirs and stays,
+    and so is a GROK_HOME that is not the one the recipe stamps (W12)."""
     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/'))}
+            and not (k in TRACE_HEADERS and v.startswith('x-throttle-trace: lanes/'))
+            and not (k == 'GROK_HOME' and v == GROK_HOME)}
 
 
 def tmux_env(environ=None):
@@ -295,7 +309,7 @@ def last_lines(text, lines):
 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
+    recipe's seven (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)
@@ -303,7 +317,9 @@ def new_session_argv(socket, session, cwd, lane_id, ws, command):
         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]
+            '-e', f'ANTHROPIC_CUSTOM_HEADERS=x-throttle-trace: {trace}', '-e', f'THROTTLE_TRACE={trace}',
+            '-e', f'KIMI_CODE_CUSTOM_HEADERS=x-throttle-trace: {trace}', '-e', f'LANES_TRACE={trace}',
+            '-e', f'GROK_HOME={GROK_HOME}', command]
 
 
 CREATION_ENV = ('HOME', 'USER', 'LOGNAME', 'PATH', 'LANG', 'LANGUAGE', 'TZ', 'TMUX_TMPDIR')   # and every LC_*
@@ -376,8 +392,9 @@ def lane_trace(lane_id, ws):
 
 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."""
+    lanes/<ws>/<id> trace as ANTHROPIC_CUSTOM_HEADERS, THROTTLE_TRACE, KIMI_CODE_CUSTOM_HEADERS and LANES_TRACE, and
+    GROK_HOME) 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)',
@@ -393,7 +410,8 @@ def canonical_recipe(lane_id, ws, socket, session, folder, cmd='bash -l'):
     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}')
+            f'-e THROTTLE_TRACE={trace} -e KIMI_CODE_CUSTOM_HEADERS={header} -e LANES_TRACE={trace} '
+            f'-e GROK_HOME={GROK_HOME} {cmd}')
 
 
 def lane_name_problem(name):
@@ -466,17 +484,101 @@ def lane_kind(entry):
     return 'registered' if entry.get('registered_session') else 'declared'
 
 
-def whoami(root, environ=None):
+# The harnesses a process tree can name (W12; lane-signal's HARNESS_COMMS and parent chain, pinned equal by
+# test_lane_core). A `grok` is Grok Build when its executable is $GROK_HOME/downloads/grok-linux-x86_64, else grok-cli.
+HARNESS_COMMS = {'claude': 'claude', 'codex': 'codex', 'kimi': 'kimi', 'kimi-code': 'kimi', 'grok': 'grok'}
+HARNESSES = ('claude', 'codex', 'kimi', 'grok', 'grok-cli', 'unknown')
+GROK_BUILD_EXE = '/downloads/grok-linux-x86_64'
+CLAUDE_EXE = '/claude/versions/'   # native Claude Code before 2.1.299 kept its file's name, the version, as comm (MEASURED)
+PARENT_DEPTH = 8
+ENVIRON_MAX = 1 << 20     # /proc/<pid>/environ read at most this far (the kernel caps an environment far below it)
+WHOAMI_VARS = ('LANE_ID', 'LANE_WS', 'TMUX', 'TMUX_PANE')   # what whoami reads (MCP_ENV_VARS passes the same)
+
+
+def _stat(proc, pid):
+    """(comm, ppid) of /proc/<pid>/stat, or None."""
+    data = read_regular(Path(proc) / str(pid) / 'stat', 1 << 16)
+    if data is None:
+        return None
+    text = data.decode('utf-8', 'replace')
+    try:
+        return text[text.index('(') + 1:text.rindex(')')], int(text.rsplit(')', 1)[1].split()[1])
+    except (ValueError, IndexError):
+        return None
+
+
+def _exe(proc, pid):
+    try:
+        return os.readlink(str(Path(proc) / str(pid) / 'exe')).removesuffix(' (deleted)')
+    except OSError:
+        return ''
+
+
+def process_harness(proc, pid):
+    """The harness process `pid` is, or None: its comm in HARNESS_COMMS (a `grok` split by /proc/<pid>/exe), else a
+    native Claude Code file (CLAUDE_EXE) as its executable."""
+    found = _stat(proc, pid)
+    if not found:
+        return None
+    harness = HARNESS_COMMS.get(found[0])
+    if harness == 'grok':
+        return 'grok' if _exe(proc, pid).endswith(GROK_BUILD_EXE) else 'grok-cli'
+    return harness or ('claude' if CLAUDE_EXE in _exe(proc, pid) else None)
+
+
+def parent_harness(proc, pid):
+    """The harness of `pid` or the first of its ancestors that is one (at most PARENT_DEPTH processes), else None."""
+    for _step in range(PARENT_DEPTH):
+        if not isinstance(pid, int) or pid <= 1:
+            return None
+        harness = process_harness(proc, pid)
+        if harness:
+            return harness
+        found = _stat(proc, pid)
+        pid = found[1] if found else 0
+    return None
+
+
+def parent_environ(proc, pid, names=WHOAMI_VARS):
+    """{name: value} of `names` in /proc/<pid>/environ when `pid` is a known harness (HARNESS_COMMS) — {} otherwise.
+    The read is bounded (ENVIRON_MAX) and never follows a link; entries are NUL-split, and one that is not UTF-8 or
+    holds no `=` is skipped. The whoami fallback for an agent that hands its MCP servers a stripped environment
+    (grok-cli, W12 DEF-1992): its own environment, set by the lane's recipe, still names the lane."""
+    if not isinstance(pid, int) or pid <= 1 or not process_harness(proc, pid):
+        return {}
+    data = read_regular(Path(proc) / str(pid) / 'environ', ENVIRON_MAX)
+    found = {}
+    for item in (data or b'').split(b'\0'):
+        key, sep, value = item.partition(b'=')
+        try:
+            key, value = key.decode('utf-8'), value.decode('utf-8')
+        except UnicodeDecodeError:
+            continue
+        if sep and key in names and value and key not in found:
+            found[key] = value
+    return found
+
+
+def whoami(root, environ=None, proc=Path('/proc'), parent=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."""
+    container's unregistered sessions (status.json). Not in a lane is an answer (`lane` null), not an error.
+    `parent` (lane-mcp passes its own parent, the agent, when it reads its own environment): when `environ` holds
+    neither LANE_ID nor TMUX/TMUX_PANE, the ones the parent's /proc environ holds stand in — only when the parent is a
+    known harness (parent_environ; grok-cli strips its MCP servers' environment, DEF-1992); `found_by` then says
+    `parent:LANE_ID` / `parent:tmux`."""
     environ = os.environ if environ is None else environ
+    via = ''
+    if parent is not None and not environ.get('LANE_ID') and not (environ.get('TMUX') and environ.get('TMUX_PANE')):
+        inherited = parent_environ(proc, parent)
+        if inherited.get('LANE_ID') or (inherited.get('TMUX') and inherited.get('TMUX_PANE')):
+            environ, via = dict(environ, **inherited), 'parent:'
     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,
+        return {'lane': lane, 'found_by': via + '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 ''
@@ -493,11 +595,12 @@ def whoami(root, environ=None):
     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}
+            return {'lane': lane_id, 'found_by': via + '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': row['id'], 'found_by': via + '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'}
 
@@ -910,8 +1013,13 @@ def terminals_add(text, terminal, entry=None):
 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'}
+MCP_AGENTS = ('claude', 'codex', 'kimi', 'grok', 'grok-cli')
+MCP_FILES = {'claude': '.claude.json', 'codex': '.codex/config.toml', 'kimi': '.kimi-code/mcp.json',
+             'grok': '.grok-build/config.toml', 'grok-cli': '.grok/user-settings.json'}
+# W12: claude and codex get their entry in every home; kimi, grok (Grok Build, GROK_HOME) and grok-cli only where their
+# home directory already is a real directory (the harness is installed there), unless named (`--agent`).
+MCP_ALWAYS = ('claude', 'codex')
+MCP_HOMES = {'kimi': '.kimi-code', 'grok': '.grok-build', 'grok-cli': '.grok'}
 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
@@ -950,26 +1058,24 @@ def _an_older_ours(entry):
         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."""
+def _json_mcp(text, command, what):
+    """`what` (a JSON file in Claude Code's `mcpServers` shape) with `mcpServers.lanes = {"command": <command>}` ->
+    (new text, why): claude_mcp and kimi_mcp."""
     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')
+    doc = strict_json(text, what)
     if not isinstance(doc, dict):
-        return text, '~/.claude.json is not a JSON object — left alone'
+        return text, f'{what} 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'
+        return text, f'mcpServers in {what} 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}) — '
+        return text, (f'mcpServers.{MCP_NAME} in {what} 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})
@@ -977,12 +1083,27 @@ def claude_mcp(text, command=MCP_COMMAND):
         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:
+    if strict_json(after, what) != expected:
         return text, 'the entry could not be added without changing anything else — add it by hand'
     return after, None
 
 
-def _toml_loads(text):
+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."""
+    return _json_mcp(text, command, '~/.claude.json')
+
+
+def kimi_mcp(text, command=MCP_COMMAND):
+    """~/.kimi-code/mcp.json (Kimi Code's user MCP file, `resolveKimiHome()/mcp.json`; MEASURED in the 2.1.1 binary,
+    2026-10-15: a JSON object whose `mcpServers` object maps a name to a server) the way claude_mcp edits
+    ~/.claude.json. Kimi Code starts a stdio server with its own environment, so the lane's variables arrive."""
+    return _json_mcp(text, command, '~/.kimi-code/mcp.json')
+
+
+def _toml_loads(text, what='~/.codex/config.toml'):
     try:
         import tomllib
     except ImportError:   # Python < 3.11 on the host: the textual rules below still hold
@@ -990,7 +1111,7 @@ def _toml_loads(text):
     try:
         return tomllib.loads(text)
     except tomllib.TOMLDecodeError as error:
-        raise LaneError(f'~/.codex/config.toml is not valid TOML ({error}) — left alone')
+        raise LaneError(f'{what} is not valid TOML ({error}) — left alone')
 
 
 TOML_COMMAND = re.compile(r'''^[ \t]*command[ \t]*=[ \t]*"([^"\\]*)"[ \t]*(?:#.*)?$''')
@@ -1082,14 +1203,206 @@ def codex_mcp(text, command=MCP_COMMAND):
     return after, None
 
 
-MCP_EDITORS = {'claude': claude_mcp, 'codex': codex_mcp}
+# ------------------------------------------------------------------------------------------------ TOML marker blocks
+# W12: what Lanes adds to a TOML file another program owns (Kimi Code's config.toml and tui.toml, Grok Build's
+# config.toml) is ONE block between `# >>> lanes <name> >>>` and `# <<< lanes <name> <<<` lines: appended at the end the
+# first time, replaced in place after that; nothing outside the markers is ever rewritten. A table another writer put
+# INSIDE the block (a toml_edit writer such as Throttle's Kimi adapter appends its `[[hooks]]` after the last table,
+# which can be ours) is kept, moved just below the end marker; anything else inside the markers that is not a table,
+# and markers that are not one ordered pair, refuse the file.
+
+BLOCK_BEGIN = '# >>> lanes {name} >>>'
+BLOCK_END = '# <<< lanes {name} <<<'
+_TOML_TABLE = re.compile(r'^[ \t]*\[')
+
+
+def _block_rows(text, name):
+    """(rows, begin index, end index) of the block `name` in `text`; (rows, None, None) when it has none. LaneError
+    when its markers are not exactly one ordered pair."""
+    begin, end = BLOCK_BEGIN.format(name=name), BLOCK_END.format(name=name)
+    rows = (text or '').splitlines(True)
+    marks = [(i, row.strip()) for i, row in enumerate(rows) if row.strip() in (begin, end)]
+    if not marks:
+        return rows, None, None
+    if [mark for _i, mark in marks] != [begin, end]:
+        raise LaneError(f'the `{begin}` … `{end}` lines are not one pair — fix the file by hand', 'source_invalid')
+    return rows, marks[0][0], marks[1][0]
+
+
+def without_block(text, name):
+    """`text` without the block `name` (its markers and every line between them): what the file says apart from us."""
+    rows, first, last = _block_rows(text, name)
+    return text or '' if first is None else ''.join(rows[:first] + rows[last + 1:])
+
+
+def toml_block(text, name, body, ours=lambda table: True):
+    """`text` with the block `name` holding exactly `body` (whole lines) -> new text. `ours(table text)` says whether a
+    table found inside an existing block is ours (replaced by `body`) or another writer's (kept, moved below the
+    block). LaneError for a key or value inside the block that belongs to no table, or for broken markers."""
+    begin, end = BLOCK_BEGIN.format(name=name), BLOCK_END.format(name=name)
+    block = f'{begin}\n{body}{end}\n'
+    if text is None or not text.strip():
+        return block
+    rows, first, last = _block_rows(text, name)
+    if first is None:
+        return text + ('' if text.endswith('\n') else '\n') + '\n' + block
+    tables = []
+    for row in rows[first + 1:last]:
+        if _TOML_TABLE.match(row):
+            tables.append([row])
+        elif tables:
+            tables[-1].append(row)
+        elif row.strip() and not row.lstrip().startswith('#'):
+            raise LaneError(f'the lanes {name} block holds a line outside any table ({row.strip()[:60]!r}) — fix the '
+                            'file by hand', 'source_invalid')
+    moved = ''.join(''.join(table) for table in tables if not ours(''.join(table)))
+    return ''.join(rows[:first]) + block + moved + ''.join(rows[last + 1:])
+
+
+def _lanes_command(table):
+    """A table of a lanes block that is ours: it starts lane-mcp or runs lane-signal."""
+    return '/.lz/bin/lane-signal' in table or '/.lz/bin/lane-mcp' in table
+
+
+def grok_mcp(text, command=MCP_COMMAND):
+    """Grok Build's $GROK_HOME/config.toml (~/.grok-build/config.toml in a lane, DM-LANES-GROK-HOME) with a
+    `[mcp_servers.lanes]` table that starts <command> -> (new text, why). Written as the marker block `mcp`
+    (toml_block) rather than through `grok mcp add` (the same table; the binary need not be there, and the file edit is
+    what a test can check). Grok Build starts a stdio server with its own environment plus GROK_SESSION_ID (MEASURED in
+    its source, evidence 2026-10-15 §5), so no `env` is needed. A `lanes` server defined outside the block is present
+    when it starts this command with no args, else left alone. The input must parse (tomllib) and the result must parse
+    to the input plus that table; without tomllib any `mcp_servers` outside the block refuses."""
+    what = '~/.grok-build/config.toml'
+    body = f'[mcp_servers.{MCP_NAME}]\ncommand = {json.dumps(command)}\n'
+    try:
+        parsed = _toml_loads(text or '', what)
+        outside = without_block(text, 'mcp')
+        rest = _toml_loads(outside, what)
+    except LaneError as error:
+        return text, str(error)
+    if rest is None:
+        if re.search(r'(?m)^[ \t]*\[*[ \t]*mcp_servers\b|^[ \t]*mcp_servers[ \t]*[.=]', outside):
+            return text, (f'{what} defines mcp_servers in a form this Python (no tomllib) cannot read safely — add '
+                          f'the [mcp_servers.{MCP_NAME}] table by hand')
+    else:
+        servers = rest.get('mcp_servers')
+        if servers is not None and not isinstance(servers, dict):
+            return text, f'mcp_servers in {what} is not a table — left alone'
+        current = (servers or {}).get(MCP_NAME)
+        if current is not None:
+            if _ours(current, command) and parsed == rest:
+                return text, None
+            shown = current.get('command') if isinstance(current, dict) else current
+            return text, (f'mcp_servers.{MCP_NAME} in {what} is not the entry Lanes writes (command {shown!r}) — '
+                          'left alone (remove it to let Lanes add its own)')
+    try:
+        after = toml_block(text, 'mcp', body, _lanes_command)
+    except LaneError as error:
+        return text, f'{what}: {error}'
+    if rest is not None:
+        expected = dict(rest, mcp_servers=dict(rest.get('mcp_servers') or {}, **{MCP_NAME: {'command': command}}))
+        try:
+            ok = _toml_loads(after, what) == 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
+
+
+def _grok_cli_ours(entry, command):
+    """A grok-cli server entry that already starts this lane-mcp: id `lanes`, stdio, our command, no args (its
+    `enabled`, `label` and `env` are the person's to change: a disabled entry stays disabled)."""
+    return isinstance(entry, dict) and entry.get('id') == MCP_NAME and entry.get('command') == command \
+        and not entry.get('args') and entry.get('transport') == 'stdio' and 'url' not in entry
+
+
+def append_item(text, path, value):
+    """`text` with `value` appended to the array at `path` (keys from the root), laid out like its items."""
+    root = scan(text)
+    node = root
+    for step in path:
+        node = node.get(step) if node.kind == 'object' else None
+        if node is None:
+            raise LaneError(f'no array at {".".join(path)}', 'source_invalid')
+    if node.kind != 'array':
+        raise LaneError(f'no array at {".".join(path)}', 'source_invalid')
+    return _append(text, root, node, lambda indent, unit: _render(value, indent, unit))
+
+
+def grok_cli_mcp(text, command=MCP_COMMAND):
+    """grok-cli's ~/.grok/user-settings.json (os.homedir()/.grok, whatever GROK_HOME says; MEASURED in the 1.1.7
+    binary's source, 2026-10-15: `mcp.servers` is an array of {id, label, enabled, transport, command, args, env, cwd},
+    each stdio server started as `grok-cli-<id>` with ONLY HOME, LOGNAME, PATH, SHELL, TERM and USER of grok-cli's
+    environment plus the entry's `env`) with one server `lanes` -> (new text, why). The entry's `env` is `{}`: a file
+    every lane shares can carry no lane's identity, and nothing secret goes in it; lane-mcp names its lane through
+    whoami's parent fallback (grok-cli's own environment, DEF-1992). The file holds grok-cli's `apiKey`: the edit is the
+    one member or item, every other byte kept, and the result must parse back to the input plus that entry."""
+    what = '~/.grok/user-settings.json'
+    entry = {'id': MCP_NAME, 'label': 'Lanes', 'enabled': True, 'transport': 'stdio', 'command': command, 'args': [],
+             'env': {}}
+    if text is None or not text.strip():
+        return json.dumps({'mcp': {'servers': [entry]}}, indent=2) + '\n', None
+    doc = strict_json(text, what)
+    if not isinstance(doc, dict):
+        return text, f'{what} is not a JSON object — left alone'
+    mcp = doc.get('mcp')
+    servers = mcp.get('servers') if isinstance(mcp, dict) else None
+    if (mcp is not None and not isinstance(mcp, dict)) or (servers is not None and not isinstance(servers, list)):
+        return text, f'mcp.servers in {what} is not an array — left alone'
+    named = [i for i, item in enumerate(servers or []) if isinstance(item, dict) and item.get('id') == MCP_NAME]
+    if len(named) > 1:
+        return text, f'{what} lists the server id {MCP_NAME!r} twice — left alone; fix it by hand'
+    expected = dict(doc)
+    if named:
+        current = servers[named[0]]
+        if _grok_cli_ours(current, command):
+            return text, None
+        if not _an_older_ours(current):
+            return text, (f'the mcp server {MCP_NAME!r} in {what} is not the entry Lanes writes (command '
+                          f'{current.get("command")!r}) — left alone (remove it to let Lanes add its own)')
+        item = scan(text).get('mcp').get('servers').items[named[0]]
+        root = scan(text)
+        after = text[:item.start] + _render(entry, _line_indent(text, item.start), _file_unit(text, root)) \
+            + text[item.end:]
+        expected['mcp'] = dict(mcp, servers=[entry if i == named[0] else s for i, s in enumerate(servers)])
+    elif mcp is None:
+        after = set_member(text, [], 'mcp', {'servers': [entry]})
+        expected['mcp'] = {'servers': [entry]}
+    elif servers is None:
+        after = set_member(text, ['mcp'], 'servers', [entry])
+        expected['mcp'] = dict(mcp, servers=[entry])
+    else:
+        after = append_item(text, ['mcp', 'servers'], entry)
+        expected['mcp'] = dict(mcp, servers=list(servers) + [entry])
+    if strict_json(after, what) != expected:
+        return text, 'the entry could not be added without changing anything else — add it by hand'
+    return after, None
 
 
-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."""
+MCP_EDITORS = {'claude': claude_mcp, 'codex': codex_mcp, 'kimi': kimi_mcp, 'grok': grok_mcp, 'grok-cli': grok_cli_mcp}
+
+
+def mcp_agents(home):
+    """The agents whose entry an install writes by default: MCP_ALWAYS, plus each of kimi, grok and grok-cli whose
+    home directory (MCP_HOMES) is a real directory under `home` — never a link (the host writes through the volume)."""
+    found = list(MCP_ALWAYS)
+    for agent in MCP_AGENTS:
+        if agent not in found:
+            try:
+                info = os.lstat(str(Path(home) / MCP_HOMES[agent]))
+            except OSError:
+                continue
+            if stat.S_ISDIR(info.st_mode):
+                found.append(agent)
+    return tuple(found)
+
+
+def mcp_plan(home, agents=None, command=MCP_COMMAND):
+    """[{agent, path, before, after, why}] for each agent's config under `home` (pure: reads only); `agents` defaults
+    to mcp_agents(home). `after == before` with no `why` = already there; a `why` = left alone, with the reason."""
     plan = []
-    for agent in agents:
+    for agent in (mcp_agents(home) if agents is None else agents):
         path = Path(home) / MCP_FILES[agent]
         try:
             _ident, before = _snapshot(path, home)
@@ -1111,14 +1424,14 @@ def mcp_diff(item):
                                         f'{path} (with the lanes MCP server)'))
 
 
-def mcp_apply(home, agents=MCP_AGENTS, command=MCP_COMMAND):
+def mcp_apply(home, agents=None, 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."""
+    Never raises for one file: the other still gets its entry. `agents` defaults to mcp_agents(home)."""
     results = []
-    for agent in agents:
+    for agent in (mcp_agents(home) if agents is None else agents):
         path = Path(home) / MCP_FILES[agent]
         refusal = []
 
@@ -1138,3 +1451,178 @@ def mcp_apply(home, agents=MCP_AGENTS, command=MCP_COMMAND):
         results.append({'agent': agent, 'path': path, 'status': status, 'backup': saved,
                         'why': refusal[0] if refusal else None})
     return results
+
+
+# ------------------------------------------------------------------------------------------------ publishing (W10 W4)
+# `lane publish <file>` and lane-mcp's `lanes_publish` put a file of this container on the Lanes docs page. Nothing here
+# copies the file anywhere: the request names it, and the host's lanes-docsd reads it through /proc/<container init>/root
+# on its own 5 s cycle (it trusts nothing in the request: the path is resolved inside the container again, the bytes
+# hashed again), stores it in the docs store and writes `<id>.receipt.json` back beside the request, which it removes.
+#
+#   ~/.lz/state/publish/<lane id>/<id>.json           the request (DM-LANES-PUBLISH-REQUEST): {v: 1, path, title, kind,
+#                                                     claimed_sha256, mime, bytes, for}, `path` the file's absolute path
+#                                                     in this container with every link resolved
+#   ~/.lz/state/publish/<lane id>/<id>.receipt.json   the host's answer (DM-LANES-PUBLISH-RECEIPT): {v: 1, id, request,
+#                                                     sha256, bytes, url, at, outcome: ok|refused, reason?}
+
+PUBLISH_KINDS = ('md', 'html', 'svg', 'file')   # docs_store.KINDS without `upload` (a person's upload is the host's)
+PUBLISH_MAX = 32 << 20                          # docsd.PUBLISH_LIMIT: a larger file is refused here and on the host
+PUBLISH_PICKUP = 'lanes-docsd'                  # what takes a request (docsd.Pickup)
+PUBLISH_LATENCY_S = 5                           # docsd.PICKUP_INTERVAL: one pick-up cycle
+PUBLISH_DIR = ('state', 'publish')              # under ~/.lz
+PUBLISH_ID = re.compile(r'[a-z0-9]{10,20}')     # docs_store.ID_RE
+RECEIPT_SUFFIX = '.receipt.json'
+TITLE_MAX = 200                                 # docs_store.MAX_TITLE
+LOGIN_MAX = 254                                 # members.MAX_LOGIN
+ID_TIME = '0123456789abcdefghijklmnopqrstuvwxyz'   # docs_store.BASE36: epoch seconds, zero-padded to 6
+ID_RANDOM = 'abcdefghijklmnopqrstuvwxyz234567'     # docs_store.BASE32: 6 random characters
+KIND_BY_SUFFIX = {'.md': 'md', '.markdown': 'md', '.html': 'html', '.htm': 'html', '.svg': 'svg'}
+MIME_BY_SUFFIX = {'.md': 'text/markdown', '.markdown': 'text/markdown', '.html': 'text/html', '.htm': 'text/html',
+                  '.svg': 'image/svg+xml', '.txt': 'text/plain', '.json': 'application/json', '.csv': 'text/csv',
+                  '.pdf': 'application/pdf', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+                  '.gif': 'image/gif', '.webp': 'image/webp'}   # = libexec/docs_store.MIME_BY_SUFFIX (DEF-1920)
+REFUSED_TEXT = frozenset(('Cc', 'Cf', 'Cs', 'Co', 'Cn', 'Zl', 'Zp'))   # members.REFUSED_CATEGORIES
+
+
+def new_publish_id(now=None):
+    """A request id in docs_store's grammar (`new_id`: base36 epoch seconds zero-padded to 6, then 6 random base32),
+    pinned equal to it by test_lane_publish. The container cannot import the host's store."""
+    import secrets
+    seconds, digits = int(time.time() if now is None else now), ''
+    while True:
+        seconds, rest = divmod(seconds, 36)
+        digits = ID_TIME[rest] + digits
+        if not seconds:
+            break
+    return digits.rjust(6, '0') + ''.join(secrets.choice(ID_RANDOM) for _ in range(6))
+
+
+def publish_kind(path, kind=None):
+    """`kind` when given (one of PUBLISH_KINDS), else from the file name: .md/.markdown md, .html/.htm html, .svg svg,
+    anything else file. LaneError `invalid_kind`."""
+    if kind is None or kind == '':
+        return KIND_BY_SUFFIX.get(os.path.splitext(str(path))[1].lower(), 'file')
+    if kind not in PUBLISH_KINDS:
+        raise LaneError(f'kind {kind!r} is not one of {", ".join(PUBLISH_KINDS)}', 'invalid_kind')
+    return kind
+
+
+def _one_line(value, what, limit, blanks, code):
+    """`value` when it is one printable line of at most `limit` characters without outer blanks (members._text's rule;
+    `blanks`: inner spaces allowed), else LaneError `code`. The host checks it again."""
+    if (not isinstance(value, str) or not value or len(value) > limit or value != value.strip()
+            or any(unicodedata.category(char) in REFUSED_TEXT for char in value)
+            or (not blanks and any(char.isspace() for char in value))):
+        raise LaneError(f'{what} is one line of at most {limit} printable characters'
+                        + ('' if blanks else ' without blanks'), code)
+    return value
+
+
+def publish_dir(root, lane):
+    return Path(root).joinpath(*PUBLISH_DIR, lane)
+
+
+def publish(root, home, path, lane, title=None, for_login=None, kind=None, now=None):
+    """Write a publish request for the file at `path` (as this process reaches it) from `lane` -> {id, lane, path,
+    kind, title, for, bytes, sha256, request, receipt}: `path` the file's container path, `request`/`receipt` the
+    container paths of the request and of the receipt lanes-docsd writes. `root` is ~/.lz and `home` /home/coder as
+    this process reaches them (themselves in a container, test directories otherwise).
+
+    The file must resolve (os.path.realpath) inside `home` to a regular file of at most PUBLISH_MAX bytes; it is read
+    once, never through a link at its last component and never blocking on a FIFO, to hash it (`claimed_sha256`, which
+    the host compares with its own). Refusals (LaneError): `not_in_lane`, `invalid_title`, `invalid_for`,
+    `invalid_kind`, `outside_home`, `not_a_file`, `too_large`. The request is replaced atomically (0644); nothing else
+    is written."""
+    import hashlib
+    import mimetypes
+    if not isinstance(lane, str) or not LANE_RE.fullmatch(lane):
+        raise LaneError('this agent runs in no lane to publish from', 'not_in_lane')
+    title = None if title in (None, '') else _one_line(title, 'a title', TITLE_MAX, True, 'invalid_title')
+    for_login = None if for_login in (None, '') else _one_line(for_login, 'a login', LOGIN_MAX, False, 'invalid_for')
+    base = os.path.realpath(str(home))
+    real = os.path.realpath(str(path))
+    if not real.startswith(base.rstrip(os.sep) + os.sep):
+        raise LaneError(f'{path} is not a file under {CONTAINER_HOME} (with every link resolved): only this '
+                        'container\'s home can be published', 'outside_home')
+    kind = publish_kind(real, kind)
+    try:
+        fd = os.open(real, os.O_RDONLY | os.O_NONBLOCK | getattr(os, 'O_NOFOLLOW', 0) | getattr(os, 'O_CLOEXEC', 0))
+    except OSError as error:
+        raise LaneError(f'{path}: {error.strerror or "cannot be opened"}', 'not_a_file') from None
+    digest, size = hashlib.sha256(), 0
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode):
+            raise LaneError(f'{path} is not a regular file', 'not_a_file')
+        if info.st_size > PUBLISH_MAX:
+            raise LaneError(f'{path} is larger than {PUBLISH_MAX >> 20} MiB', 'too_large')
+        while True:
+            chunk = os.read(fd, 1 << 16)
+            if not chunk:
+                break
+            size += len(chunk)
+            if size > PUBLISH_MAX:
+                raise LaneError(f'{path} is larger than {PUBLISH_MAX >> 20} MiB', 'too_large')
+            digest.update(chunk)
+    finally:
+        os.close(fd)
+    container = CONTAINER_HOME + '/' + os.path.relpath(real, base).replace(os.sep, '/')
+    name = os.path.basename(real)
+    # The same table as libexec/docs_store.MIME_BY_SUFFIX: Python's built-in map gained `.md` only in 3.12, so the
+    # request's `mime` must not depend on the interpreter (the host compares nothing on it, but receipts carry it).
+    mime, encoding = MIME_BY_SUFFIX.get(os.path.splitext(name)[1].lower()), None
+    if not mime:
+        mime, encoding = mimetypes.MimeTypes().guess_type(name)   # the built-in table, as the host's
+    request = {'v': 1, 'path': container, 'title': title, 'kind': kind, 'claimed_sha256': digest.hexdigest(),
+               'mime': mime if mime and not encoding else 'application/octet-stream', 'bytes': size, 'for': for_login}
+    directory = publish_dir(root, lane)
+    directory.mkdir(parents=True, exist_ok=True)
+    for _ in range(16):
+        request_id = new_publish_id(now)
+        if not any(os.path.lexists(str(directory / (request_id + suffix))) for suffix in ('.json', RECEIPT_SUFFIX)):
+            break
+    else:
+        raise LaneError('could not mint a free request id', 'refused')
+    atomic_replace(directory / f'{request_id}.json', json.dumps(request, ensure_ascii=False, indent=1) + '\n', 0o644)
+    where = LZ + '/' + '/'.join(PUBLISH_DIR) + f'/{lane}/{request_id}'
+    return {'id': request_id, 'lane': lane, 'path': container, 'kind': kind, 'title': title, 'for': for_login,
+            'bytes': size, 'sha256': request['claimed_sha256'], 'request': where + '.json',
+            'receipt': where + RECEIPT_SUFFIX}
+
+
+def latest_receipt(root, lane):
+    """The newest receipt lanes-docsd wrote back for `lane` (~/.lz/state/publish/<lane>/<id>.receipt.json; the latest
+    `at` — whole seconds —, then the file written last, then the id) as lanes_status shows it -> {id, url, at,
+    outcome, request, reason?}, or None (no receipt yet, or none that reads as one). Each file is read as a regular
+    file only (read_regular: no link, no FIFO)."""
+    if not isinstance(lane, str) or not LANE_RE.fullmatch(lane):
+        return None
+    directory = publish_dir(root, lane)
+    try:
+        names = os.listdir(str(directory))
+    except OSError:
+        return None
+    best = None
+    for name in names:
+        request_id = name[:-len(RECEIPT_SUFFIX)] if name.endswith(RECEIPT_SUFFIX) else ''
+        if not PUBLISH_ID.fullmatch(request_id):
+            continue
+        receipt = read_json(directory / name)
+        if not (isinstance(receipt, dict) and receipt.get('v') == 1 and isinstance(receipt.get('at'), str)
+                and receipt.get('outcome') in ('ok', 'refused')):
+            continue
+        try:
+            written = os.stat(str(directory / name), follow_symlinks=False).st_mtime_ns
+        except OSError:
+            continue
+        key = (receipt['at'], written, request_id)
+        if best is None or key > best[0]:
+            best = (key, request_id, receipt)
+    if best is None:
+        return None
+    _key, request_id, receipt = best
+    out = {'id': receipt.get('id'), 'url': receipt.get('url'), 'at': receipt['at'], 'outcome': receipt['outcome'],
+           'request': request_id}
+    if receipt['outcome'] == 'refused':
+        out['reason'] = receipt.get('reason')
+    return out