@vibelord/lanes 1.3.0 → 1.5.0

package/payload/lanes/bin/lanes

@@ -82,12 +82,19 @@
                                  is gone, its board is hidden). Asked for, never automatic: `lanes-launch here` runs it
                                  for the client's own device
   lanes onboard <login> --container <name> [--workspace <id> --repo <path> [--title T]]
-                [--write] [--no-mcp]
+                [--write] [--no-mcp] [--step kimi-notify|grok-build]...
                                  provision a user's container and agents in one verb. Dry-run by default (every diff and
                                  command it would run). It first checks the container (read-only docker inspect: an
                                  unknown one stops the run before anything is written); --write then applies, in order:
                                  the board (`workspaces add`, when --workspace is given), install-container,
-                                 `hooks install --write` for claude and codex, `throttle setup --install-clients`
+                                 (--step grok-build first: see below) `hooks install --write` for claude and codex,
+                                 then for kimi, grok (Grok Build) and
+                                 grok-cli where that harness's home (~/.kimi-code, ~/.grok-build, ~/.grok) is in the
+                                 container (else `skipped`); two steps run only when named: --step kimi-notify (Kimi's
+                                 tui.toml notification_condition = "always": the bell on every turn end) and --step
+                                 grok-build (Grok Build installed under GROK_HOME=~/.grok-build by the stable-channel
+                                 recipe, never ~/.grok; the channel publishes no checksum, so the receipt records the
+                                 download's size and sha256 as unverified), `throttle setup --install-clients`
                                  inside the container as uid 1000 when it has a CONFIGURED throttle (else the manual
                                  step is printed: a first setup needs a person on a terminal; the laptop-pool step too
                                  when site.conf names LANES_THROTTLE_REMOTE_URL), sync,
@@ -192,15 +199,34 @@
                                  (additive; installs no agent hook and no editor: lane-edit runs $LANES_EDITOR or the
                                  first of micro hx nvim vim vi there) and add the Lanes MCP server to the agents'
                                  configs: mcpServers.lanes in ~/.claude.json and [mcp_servers.lanes] in
-                                 ~/.codex/config.toml, both starting /home/coder/.lz/bin/lane-mcp — only where missing,
+                                 ~/.codex/config.toml, and where Kimi Code, Grok Build or grok-cli is installed
+                                 ~/.kimi-code/mcp.json, ~/.grok-build/config.toml (a `# >>> lanes mcp >>>` block) or
+                                 ~/.grok/user-settings.json (mcp.servers id lanes), all starting
+                                 /home/coder/.lz/bin/lane-mcp — only where missing,
                                  the file kept as <file>.bak-<UTC> first, atomic (a `lanes` entry that starts something
                                  else is left alone, exit 1; on a uid split nothing is written there, exit 1). --no-mcp
                                  leaves out lane-mcp and the entries (lane-edit and its vimrc still ship) and removes
-                                 nothing an earlier install wrote. In the container: lane mcp install
-  lanes hooks install --agent claude|codex (--container <name> | --home <dir>) [--dry-run | --write]
+                                 nothing an earlier install wrote. In the container: lane mcp install. The Throttle
+                                 pulse (throttle-pulse) ships to every container; in the daemon's container only
+                                 (site.conf LANES_THROTTLE_CONTAINER, else the registry's Throttle Monitor container)
+                                 its loop is started, once: `docker exec -d -u 1000 -e HOME=/home/coder <name> tmux -L
+                                 lanes-pulse new -d -s pulse ~/.lz/bin/throttle-pulse --loop` (nothing when that
+                                 session already runs; exit 1 when docker refused the start)
+  lanes throttle adopt-token <container>
+                                 the operator's opt-in to the pulse's burn and money lines: copy env.ANTHROPIC_API_KEY
+                                 of the container's own ~/.claude/settings.json — the LOCAL Throttle client bearer, it
+                                 must start `throttle_` — into its ~/.lz/throttle-token (0600, by rename), read and
+                                 written through /proc/<init>/root without following a link. Prints `adopted` or the
+                                 refusal, never the value. Exit 1 when refused
+  lanes hooks install --agent claude|codex|kimi|grok|grok-cli (--container <name> | --home <dir>) [--dry-run | --write]
                                  merge the lane-signal hooks into that home's ~/.claude/settings.json or ~/.codex/hooks.json
-                                 (+ a top-level Codex notify when none is set); prints the diff, writes only with --write
-                                 (backup kept). Opt-in, per container; Codex still asks you to trust new hooks.
+                                 (+ a top-level Codex notify when none is set), ~/.kimi-code/config.toml (a `# >>> lanes
+                                 hooks >>>` block of [[hooks]]), Grok Build's ~/.grok-build/hooks/lanes.json and
+                                 ~/.grok-build/config.toml (blocks: [compat.claude] hooks/mcps = false, [ui.notifications]
+                                 bel always, [model."grok-4.6"/"grok-4.5"] env_http_headers from LANES_TRACE) or
+                                 grok-cli's ~/.grok/user-settings.json `hooks`; prints the diff (credential values shown
+                                 as …), writes only with --write (backup kept; nothing outside a block is rewritten).
+                                 Opt-in, per container; Codex still asks you to trust new hooks.
                                  --write into a --container whose home the agent could not read from this account (uid
                                  not 1000, or a home volume not owned by 1000) is refused with the reason
   lanes invariant save|check     snapshot / verify every live pane's pid and window size
@@ -360,6 +386,7 @@
 """
 import contextlib
 import json
+import math
 import os
 import posixpath
 import pwd
@@ -1185,7 +1212,15 @@ def hook_env(home):
 
 INSTALL_CONTAINER_USAGE = 'usage: lanes install-container <name> [--no-mcp]'
 # lane_core.py first: `lane` imports it, so no moment has a new `lane` beside an old (or no) lane_core.py.
-CONTRACT_FILES = ('lane_core.py', 'lane-mcp', 'lane', 'lane-run', 'lane-signal', 'lane-edit')
+CONTRACT_FILES = ('lane_core.py', 'lane-mcp', 'lane', 'lane-run', 'lane-signal', 'lane-edit', 'throttle-pulse')
+# The Throttle pulse (W11): installed everywhere, its loop started only in the daemon's container. As uid 1000 with
+# the container home as HOME, whatever user the image defaults to: it writes ~/.lz/state/throttle.json, which
+# lanes-statusd reads, and reads ~/.lz/throttle-token, which only the container's own user may read (0600).
+PULSE_BIN = L.CONTAINER_HOME + '/.lz/bin/throttle-pulse'
+PULSE_TMUX = ('tmux', '-L', 'lanes-pulse')
+PULSE_SESSION = 'pulse'
+PULSE_DOCKER_S = 20
+THROTTLE_MONITOR = 'tools--throttle-monitor'
 
 
 def lane_core():
@@ -1285,8 +1320,8 @@ def cmd_install_container(args):
     # user (0700), never here.
     install_file(L.REPO / 'container/vimrc', root / 'vimrc')
     # The hook DEFINITIONS travel with the contract for reference; no hook is installed here — that is the opt-in,
-    # per-container `lanes hooks install --agent claude|codex --container <name> --write` (RUNBOOK).
-    for source in sorted((L.REPO / 'container/hooks').glob('*.json')):
+    # per-container `lanes hooks install --agent claude|codex|kimi|grok|grok-cli --container <name> --write` (RUNBOOK).
+    for source in sorted([*(L.REPO / 'container/hooks').glob('*.json'), *(L.REPO / 'container/hooks').glob('*.toml')]):
         install_file(source, root / 'hooks' / source.name)
     env_file = L.REPO / 'container/env.sh'   # TMPDIR off the RAM-backed /tmp; only NEW shells and agents read it
     if env_file.exists():
@@ -1301,21 +1336,142 @@ def cmd_install_container(args):
     if link.is_symlink() or link.exists():
         link.unlink()
     link.symlink_to(root)
-    print(f"installed {root}/bin/{{lane,lane_core.py,lane-run,lane-signal,lane-edit{'' if no_mcp else ',lane-mcp'},zmx-*}}, "
+    print(f"installed {root}/bin/{{lane,lane_core.py,lane-run,lane-signal,lane-edit,throttle-pulse"
+          f"{'' if no_mcp else ',lane-mcp'},zmx-*}}, "
           f'{root}/VERSION, {root}/vimrc, {root}/hooks/' + (f' and {root}/env.sh' if env_file.exists() else '')
           + f'; host link {link} -> {root}')
+    pulse = start_pulse(container)
     if no_mcp:
         print('--no-mcp: lane-mcp and the agents\' MCP entries left out (anything an earlier install wrote is kept)')
+        return pulse
+    return install_mcp_entries(home) or pulse
+
+
+def throttle_container():
+    """(container, where it was named) of the Throttle daemon's container, or (None, None): site.conf's
+    LANES_THROTTLE_CONTAINER, else the container of the registry's Throttle Monitor tool (`lanes sync` names the one
+    that hosts most boards' monitor)."""
+    named = site_profile().get('LANES_THROTTLE_CONTAINER')
+    if named and L.IDENT.match(named):
+        return named, 'site.conf LANES_THROTTLE_CONTAINER'
+    registry = L.read_json(L.STATE / 'registry.json', {})
+    for tool in (registry.get('tools') if isinstance(registry, dict) else None) or []:
+        if isinstance(tool, dict) and tool.get('id') == THROTTLE_MONITOR and L.IDENT.match(str(tool.get('container'))):
+            return tool['container'], f'the registry\'s {THROTTLE_MONITOR}'
+    return None, None
+
+
+def pulse_argv(container, *tmux):
+    """`docker exec` of the pulse's tmux server in `container` as uid 1000, argv only (no shell anywhere)."""
+    detach = ['-d'] if tmux[:1] == ('new',) else []
+    return ['docker', 'exec', *detach, '-u', str(L.CONTAINER_UID), '-e', f'HOME={L.CONTAINER_HOME}', container,
+            *PULSE_TMUX, *tmux]
+
+
+def start_pulse(container):
+    """Start the Throttle pulse's loop in `container` when it is the daemon's container (throttle_container) and no
+    `pulse` session runs on the `lanes-pulse` tmux socket there -> exit code (1 only when docker refused the start).
+    Any other container gets the file only."""
+    daemon, named_by = throttle_container()
+    if container != daemon:
+        why = f'the daemon runs in {daemon} ({named_by})' if daemon else \
+            'no daemon container is known (site.conf LANES_THROTTLE_CONTAINER, or a board with a Throttle monitor)'
+        print(f'throttle pulse: installed, not started here — {why}')
         return 0
-    return install_mcp_entries(home)
+    rc, _out, _err = L.run_bounded(pulse_argv(container, 'has-session', '-t', f'={PULSE_SESSION}'), PULSE_DOCKER_S)
+    if rc == 0:
+        print(f'throttle pulse: already running in {container} (tmux -L lanes-pulse, session {PULSE_SESSION})')
+        return 0
+    rc, _out, err = L.run_bounded(pulse_argv(container, 'new', '-d', '-s', PULSE_SESSION, PULSE_BIN, '--loop'),
+                                  PULSE_DOCKER_S)
+    if rc != 0:
+        last = next((line.strip() for line in reversed(err.splitlines()) if line.strip()), '')
+        why = f'no answer within {PULSE_DOCKER_S} s' if rc is None else f'exit {rc}'
+        print(f'! throttle pulse: not started in {container} ({why}' + (f': {last[:160]}' if last else '') + ')')
+        return 1
+    print(f'throttle pulse: started in {container} ({named_by}): tmux -L lanes-pulse, session {PULSE_SESSION}; '
+          'it writes ~/.lz/state/throttle.json every 10 s')
+    return 0
+
+
+THROTTLE_USAGE = 'usage: lanes throttle adopt-token <container>'
+THROTTLE_TOKEN = re.compile(r'throttle_[A-Za-z0-9_-]{8,512}')
+SETTINGS_MAX = 1 << 20
+
+
+def cmd_throttle(args):
+    """`lanes throttle adopt-token <container>`: the operator's opt-in to the pulse's tokened reads. Copies
+    env.ANTHROPIC_API_KEY of the container's own ~/.claude/settings.json — the local Throttle client bearer
+    `throttle setup --install-clients` put there, never a provider credential: it must look like `throttle_…` — into
+    ~/.lz/throttle-token (0600, by rename), both read and written through /proc/<container init>/root without
+    following a link. Never prints the value, not even in a refusal."""
+    if len(args) != 2 or args[0] != 'adopt-token' or args[1].startswith('-'):
+        raise L.LanesError(THROTTLE_USAGE)
+    container = args[1]
+    if not L.IDENT.match(container):
+        raise L.LanesError(f'Invalid container name: {container!r}')
+    info = L.container_info(container)
+    if not info.get('running') or not info.get('pid'):
+        raise L.LanesError(f'{container} is not running: nothing adopted')
+    split = uid_split(info['home']) if info.get('home') else None
+    if split:
+        raise L.LanesError(f'{split}: the pulse (uid {L.CONTAINER_UID}) could not read a token this account writes — '
+                           'nothing adopted')
+    root = f"{L.proc_root()}/{int(info['pid'])}/root"
+    home = L.CONTAINER_HOME.strip('/').split('/')
+    try:
+        fd = L.open_real_dir(root, [*home, '.claude'])
+    except OSError:
+        raise L.LanesError(f'{container}: no ~/.claude directory (a real one, not a link): nothing adopted') from None
+    try:
+        data = L.read_regular_at(fd, 'settings.json', SETTINGS_MAX)
+    finally:
+        os.close(fd)
+    if data is None:
+        raise L.LanesError(f'{container}: ~/.claude/settings.json is not a regular file of at most 1 MiB: '
+                           'nothing adopted')
+    try:
+        settings = json.loads(data)
+    except ValueError:
+        raise L.LanesError(f'{container}: ~/.claude/settings.json is not JSON: nothing adopted') from None
+    env = settings.get('env') if isinstance(settings, dict) else None
+    value = env.get('ANTHROPIC_API_KEY') if isinstance(env, dict) else None
+    if not isinstance(value, str) or not THROTTLE_TOKEN.fullmatch(value):
+        raise L.LanesError(f'{container}: env.ANTHROPIC_API_KEY in ~/.claude/settings.json is not a local Throttle '
+                           'client token (throttle_…): nothing adopted — run `throttle setup --install-clients` in '
+                           'the container first')
+    try:
+        fd = L.open_real_dir(root, [*home, '.lz'])
+    except OSError:
+        raise L.LanesError(f'{container}: no ~/.lz directory (a real one): run `lanes install-container '
+                           f'{container}` first — nothing adopted') from None
+    try:
+        changed = L.atomic_write_if_changed_at(fd, 'throttle-token', value + '\n', 0o600)
+    finally:
+        os.close(fd)
+    print(f'adopted: {container} ~/.lz/throttle-token (0600)' + ('' if changed else ', unchanged')
+          + '; the pulse reads it on its next cycle')
+    return 0
 
 
 HOOK_TARGETS = {'claude': ('claude-settings.json', '.claude/settings.json'),
-                'codex': ('codex-hooks.json', '.codex/hooks.json')}
-HOOKS_USAGE = ('usage: lanes hooks install --agent claude|codex (--container <name> | --home <dir>) '
+                'codex': ('codex-hooks.json', '.codex/hooks.json'),
+                'kimi': ('kimi-hooks.toml', '.kimi-code/config.toml'),
+                'grok': ('grok-hooks.json', '.grok-build/hooks/lanes.json'),
+                'grok-cli': ('grok-cli-hooks.json', '.grok/user-settings.json')}
+# The other file an install changes: Codex's top-level notify; Grok Build's config.toml blocks (W12).
+HOOK_EXTRA = {'codex': ('.codex/config.toml',), 'grok': ('.grok-build/config.toml',)}
+# W12: a harness whose home is not a directory in the container is not installed there; `lanes onboard` skips it.
+HOOK_HOMES = {'kimi': '.kimi-code', 'grok': '.grok-build', 'grok-cli': '.grok'}
+HOOKS_USAGE = ('usage: lanes hooks install --agent claude|codex|kimi|grok|grok-cli (--container <name> | --home <dir>) '
                '[--dry-run | --write]')
 
 
+def hook_files(agent):
+    """The container-home-relative files `lanes hooks install --agent <agent>` may change."""
+    return (HOOK_TARGETS[agent][1],) + HOOK_EXTRA.get(agent, ())
+
+
 def render_hooks(agent):
     """The shipped hook definitions with `~/` spelled as the container home: the command reaches lane-signal whether
     or not the harness runs it through a shell that expands `~`."""
@@ -1377,16 +1533,236 @@ def codex_notify(text):
             + json.dumps(argv) + '\n' + text)
 
 
+SECRET_LINE = re.compile(r'^(\s*"?[A-Za-z0-9_.-]*(?:key|token|secret|password|credential)[A-Za-z0-9_.-]*"?\s*[:=]\s*)'
+                         r'(.+?)(,?)$', re.I)
+
+
+def redact_line(line):
+    """A diff line whose key names a key, token, secret, password or credential, with its value shown as `…`: the
+    agents' files hold credentials (grok-cli's `apiKey`, Claude's `env.ANTHROPIC_API_KEY`), and a dry run's diff is
+    printed — and the onboarding printout pasted into tickets."""
+    body = line.rstrip('\n')
+    found = SECRET_LINE.match(body[1:]) if body[:1] in (' ', '+', '-') else None
+    if not found:
+        return line
+    return body[0] + found.group(1) + '"…"' + found.group(3) + line[len(body):]
+
+
 def show_change(path, before, after):
     import difflib
     if before == after:
         print(f'{path}: no change')
         return False
-    sys.stdout.writelines(difflib.unified_diff(before.splitlines(True), after.splitlines(True),
-                                               f'{path} (now)', f'{path} (with lanes hooks)'))
+    sys.stdout.writelines(redact_line(line) for line in difflib.unified_diff(
+        before.splitlines(True), after.splitlines(True), f'{path} (now)', f'{path} (with lanes hooks)'))
     return True
 
 
+# ------------------------------------------------------------------- W12: Kimi Code, Grok Build and grok-cli hooks
+# Each file is changed through lane_core.edit_file: re-read before the write, `<file>.bak-<UTC>` first, atomic, never
+# through a symbolic link below the container home. A TOML file gets ONE marker block (lane_core.toml_block); nothing
+# outside it is rewritten. A refusal is raised to the operator as LanesError before anything is written.
+
+GROK_CONFIG_BODY = ('[compat.claude]\n'
+                    "# Claude Code's hooks (lane-signal --harness claude) and MCP entry must not run inside Grok Build\n"
+                    'hooks = false\n'
+                    'mcps = false\n'
+                    '\n'
+                    '[ui.notifications]\n'
+                    "# a BEL on every turn end, approval and error, focused or not: the pane's window_bell_flag\n"
+                    'condition = "always"\n'
+                    'method = "bel"\n'
+                    'events = ["turn_complete", "approval_required", "task_complete", "agent_error"]\n')
+GROK_CONFIG_VALUES = {'compat': {'claude': {'hooks': False, 'mcps': False}},
+                      'ui': {'notifications': {'condition': 'always', 'method': 'bel',
+                                               'events': ['turn_complete', 'approval_required', 'task_complete',
+                                                          'agent_error']}}}
+# The lanes trace on Grok Build's inference requests: each built-in model gains an env-sourced header (an override of a
+# built-in keeps its other fields; the value is read from $LANES_TRACE when the client is built, never stored).
+GROK_TRACE_MODELS = ('grok-4.6', 'grok-4.5')
+GROK_TRACE_HEADERS = {'x-throttle-trace': 'LANES_TRACE'}
+
+
+def _lane_error(error):
+    return L.LanesError(str(error))
+
+
+def kimi_hooks_block():
+    """The body of the shipped kimi-hooks.toml (between its marker lines), `~/` spelled as the container home."""
+    rows = (L.REPO / 'container/hooks/kimi-hooks.toml').read_text().splitlines(True)
+    return ''.join(rows[1:-1]).replace('"~/', f'"{L.CONTAINER_HOME}/')
+
+
+def _ours_hook(item):
+    return isinstance(item, dict) and '/.lz/bin/lane-signal' in str(item.get('command') or '')
+
+
+def _toml_multiset(items):
+    return sorted(json.dumps(item, sort_keys=True) for item in items)
+
+
+def kimi_config(text):
+    """~/.kimi-code/config.toml with the lanes `[[hooks]]` block (kimi-hooks.toml) — Kimi Code reads hooks only from
+    $KIMI_CODE_HOME/config.toml (`[[hooks]]` {event, matcher?, command, timeout?}, a strict schema; MEASURED in the
+    2.1.1 binary, 2026-10-15). The `.kimi-code` no-touch doctrine of the session registry concerns the device identity
+    files, not this block. A `hooks` that is not an array of tables refuses; another writer's `[[hooks]]` stay."""
+    core, what = lane_core(), '~/.kimi-code/config.toml'
+    try:
+        before = core._toml_loads(text or '', what)
+        rest_text = core.without_block(text, 'hooks')
+        after = core.toml_block(text, 'hooks', kimi_hooks_block(), core._lanes_command)
+    except core.LaneError as error:
+        raise _lane_error(f'{what}: {error}') from None
+    if before is None:   # no tomllib: the forms a textual rule can read
+        if re.search(r'(?m)^[ \t]*hooks[ \t]*[=.]|^[ \t]*\[[ \t]*hooks[ \t]*\]', rest_text):
+            raise L.LanesError(f'{what} defines `hooks` other than as [[hooks]] tables — left alone; fix it by hand')
+        return after
+    hooks = before.get('hooks', [])
+    if not isinstance(hooks, list) or not all(isinstance(item, dict) for item in hooks):
+        raise L.LanesError(f'{what}: "hooks" is not an array of tables ([[hooks]]) — left alone; fix it by hand')
+    try:
+        parsed = core._toml_loads(after, what)
+    except core.LaneError:
+        parsed = None
+    expected = [item for item in hooks if not _ours_hook(item)] + core._toml_loads(kimi_hooks_block(), what)['hooks']
+    if parsed is None or {k: v for k, v in parsed.items() if k != 'hooks'} != \
+            {k: v for k, v in before.items() if k != 'hooks'} or \
+            _toml_multiset(parsed.get('hooks', [])) != _toml_multiset(expected):
+        raise L.LanesError(f'{what}: the hooks block could not be written without changing anything else — add it by '
+                           'hand from ~/.lz/hooks/kimi-hooks.toml')
+    return after
+
+
+def grok_hooks_file(_text):
+    """$GROK_HOME/hooks/lanes.json: the whole file is Lanes' (grok-hooks.json, Claude Code's JSON shape, which Grok
+    Build reads from every $GROK_HOME/hooks/*.json)."""
+    return json.dumps(render_hooks('grok'), indent=2, ensure_ascii=False) + '\n'
+
+
+def _deep(doc, *keys):
+    for key in keys:
+        doc = doc.get(key) if isinstance(doc, dict) else None
+    return doc
+
+
+def grok_config(text):
+    """$GROK_HOME/config.toml with the lanes `hooks` block (GROK_CONFIG_BODY: `[compat.claude] hooks = false, mcps =
+    false` — Grok Build otherwise also runs Claude Code's hooks and MCP servers from ~/.claude*, which say `--harness
+    claude` — and `[ui.notifications]`: a BEL on every listed event, focused or not) and the `trace` block (each
+    GROK_TRACE_MODELS `[model."<id>"] env_http_headers`, except a model the file configures outside the block, which
+    is the person's: named instead). A `[compat.claude]` or `[ui.notifications]` of the person's refuses (TOML defines
+    a table once): set those keys there by hand."""
+    core, what = lane_core(), '~/.grok-build/config.toml'
+    try:
+        before = core._toml_loads(text or '', what)
+        rest_text = core.without_block(core.without_block(text, 'hooks'), 'trace')
+        rest = core._toml_loads(rest_text, what)
+    except core.LaneError as error:
+        raise _lane_error(f'{what}: {error}') from None
+    if rest is not None:
+        mine = [name for name, keys in (('[compat.claude]', ('compat', 'claude')),
+                                        ('[ui.notifications]', ('ui', 'notifications')))
+                if _deep(rest, *keys) is not None]
+        free = [model for model in GROK_TRACE_MODELS if _deep(rest, 'model', model) is None]
+    else:   # no tomllib: what a textual rule can see
+        mine = [name for name, word in (('[compat.claude]', 'compat'), ('[ui.notifications]', 'notifications'))
+                if re.search(rf'(?m)^[ \t]*[^#\n]*\b{word}\b', rest_text)]
+        free = [model for model in GROK_TRACE_MODELS if model not in rest_text]
+    if mine:
+        raise L.LanesError(f'{what} already has {" and ".join(mine)} of its own — left alone; set `[compat.claude] '
+                           'hooks = false, mcps = false` and `[ui.notifications] condition = "always", method = "bel"` '
+                           'there by hand')
+    for model in GROK_TRACE_MODELS:
+        if model not in free:
+            print(f'! {what}: [model."{model}"] is configured outside the lanes block — add env_http_headers = '
+                  '{ "x-throttle-trace" = "LANES_TRACE" } to it by hand for the lanes trace')
+    trace = ''.join(f'[model."{model}"]\nenv_http_headers = {{ "x-throttle-trace" = "LANES_TRACE" }}\n'
+                    for model in free)
+    tables = ('[compat.claude]', '[ui.notifications]', *(f'[model."{model}"]' for model in GROK_TRACE_MODELS))
+
+    def ours(table):
+        return table.split('\n', 1)[0].strip() in tables
+    try:
+        after = core.toml_block(text, 'hooks', GROK_CONFIG_BODY, ours)
+        if trace:
+            after = core.toml_block(after, 'trace', trace, ours)
+        else:
+            after = core.without_block(after, 'trace')
+    except core.LaneError as error:
+        raise _lane_error(f'{what}: {error}') from None
+    if before is not None:
+        expected = json.loads(json.dumps(rest))
+        for key, value in GROK_CONFIG_VALUES.items():
+            expected[key] = dict(expected.get(key) or {}, **value)
+        for model in free:
+            expected['model'] = dict(expected.get('model') or {}, **{model: {'env_http_headers': dict(GROK_TRACE_HEADERS)}})
+        try:
+            ok = core._toml_loads(after, what) == expected
+        except core.LaneError:
+            ok = False
+        if not ok:
+            raise L.LanesError(f'{what}: the lanes blocks could not be written without changing anything else — set '
+                               'the keys by hand (RUNBOOK "Agent hooks")')
+    return after
+
+
+def grok_cli_settings(text):
+    """grok-cli's ~/.grok/user-settings.json with the lane-signal groups merged into its top-level `hooks` (Claude
+    Code's shape; grok-cli matches a `matcher` as an exact string and runs every command through `sh -c` with its own
+    environment, MEASURED in the 1.1.7 binary's source, 2026-10-15) — that one member edited, every other byte kept (the
+    file holds grok-cli's apiKey); the result must parse back to the input with that member."""
+    core, what = lane_core(), '~/.grok/user-settings.json'
+    ours = render_hooks('grok-cli')
+    if text is None or not text.strip():
+        return json.dumps(ours, indent=2, ensure_ascii=False) + '\n'
+    try:
+        doc = core.strict_json(text, what)
+    except core.LaneError as error:
+        raise _lane_error(error) from None
+    if not isinstance(doc, dict):
+        raise L.LanesError(f'{what}: not a JSON object — refusing to rewrite it')
+    merged = merge_hooks(doc, ours)['hooks']
+    if merged == doc.get('hooks'):
+        return text
+    after = core.set_member(text, [], 'hooks', merged)
+    if core.strict_json(after, what) != dict(doc, hooks=merged):
+        raise L.LanesError(f'{what}: the hooks could not be merged without changing anything else — add them by hand')
+    return after
+
+
+HOOK_EDITORS = {'kimi': (('.kimi-code/config.toml', kimi_config),),
+                'grok': (('.grok-build/hooks/lanes.json', grok_hooks_file), ('.grok-build/config.toml', grok_config)),
+                'grok-cli': (('.grok/user-settings.json', grok_cli_settings),)}
+
+
+def install_edits(home, edits, write):
+    """Show each file's change (a diff, or `no change`) and, with `write`, apply them through lane_core.edit_file ->
+    the changed paths. A refusal of any file (LanesError) is raised before anything is written."""
+    core, planned = lane_core(), []
+    for rel, transform in edits:
+        path = home / rel
+        try:
+            _ident, before = core._snapshot(path, home)
+        except core.LaneError as error:
+            raise _lane_error(error) from None
+        after = transform(before)
+        if show_change(path, before or '', after):
+            planned.append((path, transform))
+    if not write:
+        return []
+    changed = []
+    for path, transform in planned:
+        try:
+            _before, _after, saved = core.edit_file(path, transform, new_mode=0o600, backup=True, root=home)
+        except core.LaneError as error:
+            raise _lane_error(error) from None
+        if saved:
+            print(f'backup {saved}')
+        print(f'wrote {path}')
+        changed.append(path)
+    return changed
+
+
 def write_with_backup(path, before, after):
     """Atomic replace, the previous bytes kept beside it first. `before` is what the diff was computed from."""
     if path.exists():
@@ -1402,6 +1778,9 @@ def write_with_backup(path, before, after):
 def cmd_hooks(args):
     """`lanes hooks install`: merge the lane-signal hook definitions into ONE container home's agent config. Dry run
     (the printed diff) unless --write; never touches Codex's hook trust (`[hooks.state]` is Codex's own decision).
+    W12: kimi (a block in ~/.kimi-code/config.toml), grok (Grok Build: $GROK_HOME/hooks/lanes.json and blocks in
+    $GROK_HOME/config.toml, GROK_HOME = ~/.grok-build) and grok-cli (`hooks` in ~/.grok/user-settings.json), through
+    HOOK_EDITORS (`.bak-<UTC>` backups, no symbolic link followed).
     A --container target on a uid split (`uid_split`: this account or the home volume's owner is not the container
     uid) is refused with --write — the agent could not read the 0600 file this account would create — and warned in a
     dry run (DEF-1727). `--home <dir>` is for trying the merge on a copy, not an agent's home, and is not checked."""
@@ -1433,6 +1812,18 @@ def cmd_hooks(args):
     if split and opts.get('--write'):
         raise L.LanesError(f"{split}: the agent (uid {L.CONTAINER_UID}) could not read what this account would write "
                            f"into {home} — nothing written; run it from a host account with uid {L.CONTAINER_UID}")
+    if agent in HOOK_EDITORS:
+        install_edits(home, HOOK_EDITORS[agent], bool(opts.get('--write')))
+        if not opts.get('--write'):
+            if split:
+                print(f'⚠ {split}: --write refuses here (run it from a host account with uid {L.CONTAINER_UID})')
+            print('dry run: nothing written (add --write to apply)')
+        return 0
+    for rel in hook_files(agent):   # DEF-1998: the host never reads or writes through a link the container planted
+        try:
+            lane_core().no_links(home, home / rel)
+        except lane_core().LaneError as error:
+            raise _lane_error(f'{error}: nothing written') from None
     target = home / HOOK_TARGETS[agent][1]
     before = target.read_text() if target.exists() else ''
     try:
@@ -2351,7 +2742,9 @@ def cmd_workspaces(args):
 # ------------------------------------------------------------------- onboard
 
 ONBOARD_USAGE = ('usage: lanes onboard <login> --container <name> [--workspace <id> --repo <path> [--title T]] '
-                 '[--write] [--no-mcp]')
+                 '[--write] [--no-mcp] [--step kimi-notify|grok-build]...')
+ONBOARD_OPTIONAL = ('kimi-notify', 'grok-build')   # steps that run only when named with --step (W12)
+HARNESS_NAMES = {'kimi': 'Kimi Code', 'grok': 'Grok Build', 'grok-cli': 'grok-cli'}
 # The receipt's status vocabulary. A dry run reports planned, unchanged, skipped, manual or failed, and `ok` for the
 # read-only `inspect` of the container; `manual` names a step a person still has to take (printed with the exact command);
 # `warn` is a step that ran and reported a problem that does not stop onboarding (the doctor's verdict, a board with
@@ -2372,7 +2765,7 @@ THROTTLE_PROBE = ('if ! command -v throttle >/dev/null; then echo absent; '
 THROTTLE_SETUP = 'throttle setup --install-clients'
 THROTTLE_PROBE_TIMEOUT = 20
 THROTTLE_TIMEOUT = 120
-SITE_LINE = re.compile(r'^(LANES_[A-Z_]+)=([A-Za-z0-9_.:@/-]*)$')   # also what `lanes client-config` hands out
+SITE_LINE = L.SITE_LINE   # also what `lanes client-config` hands out
 
 
 def onboard_step(name, status, detail=''):
@@ -2394,13 +2787,10 @@ def uid_split(home):
     return None
 
 
-def site_profile():
-    """This server's site facts: the LANES_* KEY=VALUE lines of ~/.config/lanes/site.conf (read, never executed)."""
-    try:
-        text = (Path.home() / '.config/lanes/site.conf').read_text()
-    except OSError:
-        return {}
-    return dict(match.groups() for match in map(SITE_LINE.match, text.splitlines()) if match)
+def site_profile(home=None):
+    """This server's site facts: the LANES_* KEY=VALUE lines of ~/.config/lanes/site.conf (read, never executed;
+    L.site_conf, `home` for a test's)."""
+    return L.site_conf(home)
 
 
 def provision_throttle(container, site, write=True):
@@ -2465,13 +2855,134 @@ def provision_laptop(steps, site):
     return steps
 
 
+# ------------------------------------------------------------------- W12 optional onboard steps
+
+KIMI_NOTIFY_LINE = 'notification_condition = "always"'
+KIMI_NOTIFY_TABLE = re.compile(r'^[ \t]*\[[ \t]*notifications[ \t]*\][ \t]*(?:#.*)?$')
+KIMI_NOTIFY_KEY = re.compile(r'^([ \t]*)notification_condition[ \t]*=[ \t]*("[^"\\]*"|\'[^\']*\')[ \t]*(#.*)?$')
+
+
+def kimi_notify(text):
+    """~/.kimi-code/tui.toml with `[notifications] notification_condition = "always"` (operator-approved per container,
+    `lanes onboard --step kimi-notify`): Kimi Code then rings the terminal bell on every turn end, focused or not, and
+    tmux sets the pane's window_bell_flag. Kimi Code's own default tui.toml already HAS a `[notifications]` table
+    (`enabled = true`, `notification_condition = "unfocused"`; MEASURED in the 2.1.1 binary, 2026-10-15), and TOML defines
+    a table once, so that table's key is edited in place (its old value kept in a comment); only a file without the
+    table gets the marker block `notify`."""
+    core, what = lane_core(), '~/.kimi-code/tui.toml'
+    body = '[notifications]\n' + KIMI_NOTIFY_LINE + '\n'
+    if text is None or not text.strip():
+        return core.toml_block(None, 'notify', body)
+    try:
+        before = core._toml_loads(text, what)
+        rest = core.without_block(text, 'notify')
+        rows = text.splitlines(True)
+        _rows, first, last = core._block_rows(text, 'notify')
+    except core.LaneError as error:
+        raise _lane_error(f'{what}: {error}') from None
+    headers = [i for i, row in enumerate(rows) if KIMI_NOTIFY_TABLE.match(row.rstrip('\r\n'))
+               and (first is None or not first < i < last)]
+    if first is not None and not headers:
+        after = core.toml_block(text, 'notify', body)
+    elif len(headers) == 1:
+        start = headers[0] + 1
+        end = next((i for i in range(start, len(rows)) if rows[i].lstrip().startswith('[')), len(rows))
+        keys = [i for i in range(start, end) if KIMI_NOTIFY_KEY.match(rows[i].rstrip('\r\n'))]
+        if len(keys) > 1 or any(re.match(r'[ \t]*notification_condition[ \t]*=', rows[i]) and i not in keys
+                                for i in range(start, end)):
+            raise L.LanesError(f'{what}: [notifications] has a notification_condition this edit cannot read — set it '
+                               'to "always" by hand')
+        if keys:
+            row = rows[keys[0]]
+            found = KIMI_NOTIFY_KEY.match(row.rstrip('\r\n'))
+            if found.group(2).strip('"\'') == 'always':
+                return text
+            ending = row[len(row.rstrip('\r\n')):] or '\n'
+            rows[keys[0]] = (f'{found.group(1)}{KIMI_NOTIFY_LINE}  # lanes onboard --step kimi-notify (was '
+                             f'{found.group(2)})' + ending)
+        else:
+            rows.insert(start, KIMI_NOTIFY_LINE + '  # lanes onboard --step kimi-notify\n')
+        after = ''.join(rows)
+    elif headers:
+        raise L.LanesError(f'{what}: [notifications] appears {len(headers)} times — fix the file by hand')
+    elif re.search(r'(?m)^[ \t]*notifications[ \t]*[=.]', rest):
+        raise L.LanesError(f'{what}: notifications is not written as a [notifications] table — set '
+                           'notification_condition = "always" by hand')
+    else:
+        after = core.toml_block(text, 'notify', body)
+    if before is not None:
+        expected = json.loads(json.dumps(before))
+        expected['notifications'] = dict(expected.get('notifications') or {}, notification_condition='always')
+        try:
+            ok = core._toml_loads(after, what) == expected
+        except core.LaneError:
+            ok = False
+        if not ok:
+            raise L.LanesError(f'{what}: notification_condition could not be set without changing anything else — '
+                               'set it to "always" by hand')
+    return after
+
+
+# `lanes onboard --step grok-build`: Grok Build installed under GROK_HOME=~/.grok-build inside the container, as uid
+# 1000, by the measured recipe (evidence 2026-10-15 "Container install recipe", derived from x.ai's install.sh): the
+# stable channel's version, the zstd artifact (else the plain one), the binary at downloads/grok-linux-x86_64 and the
+# relative link bin/grok (so the pane's command and comm stay `grok`), `[cli] installer = "internal"`. It never writes
+# ~/.grok (grok-cli's: Grok Build's own installer would replace grok-cli's bin/grok there), edits no shell rc file and
+# links nothing into ~/.local/bin. The channel publishes no checksum (no GitHub release assets; MEASURED 2026-10-15), so
+# the download cannot be verified: the step prints and records its size and sha256 as UNVERIFIED, and it runs only
+# when the operator names it (`--step grok-build`).
+GROK_BUILD_TIMEOUT = 900
+GROK_BUILD_RECIPE = (
+    'set -eu; G="$HOME/.grok-build"; '
+    '[ "$(uname -m)" = x86_64 ] || { echo "grok-build: only linux x86_64 builds exist, this is $(uname -m)" >&2; exit 3; }; '
+    'V=$(curl -fsSL https://x.ai/cli/stable); '
+    'case "$V" in ""|*[!0-9.]*) echo "grok-build: the stable channel answered no version" >&2; exit 3;; esac; '
+    'mkdir -p "$G/downloads" "$G/bin"; P="$G/downloads/.grok-linux-x86_64.part"; rm -f "$P" "$P.zst"; '
+    'if command -v zstd >/dev/null 2>&1 && curl -fsSL -o "$P.zst" "https://x.ai/cli/grok-$V-linux-x86_64.zst"; '
+    'then zstd -q -dc "$P.zst" > "$P"; rm -f "$P.zst"; '
+    'else rm -f "$P.zst"; curl -fsSL -o "$P" "https://x.ai/cli/grok-$V-linux-x86_64"; fi; '
+    'chmod 755 "$P"; mv -f "$P" "$G/downloads/grok-linux-x86_64"; '
+    'ln -sfn ../downloads/grok-linux-x86_64 "$G/bin/grok"; '
+    '[ -e "$G/config.toml" ] || printf \'[cli]\\ninstaller = "internal"\\n\' > "$G/config.toml"; '
+    'R=$(GROK_HOME="$G" "$G/bin/grok" --version 2>/dev/null | head -n 1); '
+    'echo "grok-build version=$V bytes=$(wc -c < "$G/downloads/grok-linux-x86_64") '
+    'sha256=$(sha256sum "$G/downloads/grok-linux-x86_64" | cut -d" " -f1) runs=$R"')
+GROK_BUILD_LINE = re.compile(r'^grok-build version=([0-9.]+) bytes=(\d+) sha256=([0-9a-f]{64}) runs=(.*)$')
+
+
+def provision_grok_build(container, write):
+    """The `grok-build` onboard step -> (status, detail). A dry run prints the command; --write runs it (bounded,
+    GROK_BUILD_TIMEOUT) and reports the installed version with the download's size and sha256, marked unverified."""
+    uid = str(L.CONTAINER_UID)
+    argv = ['docker', 'exec', '-u', uid, container, 'sh', '-lc', GROK_BUILD_RECIPE]
+    shown = f"docker exec -u {uid} {container} sh -lc '<GROK_BUILD_RECIPE>' (GROK_HOME=~/.grok-build)"
+    if not write:
+        print(f'would run: {shown}')
+        return 'planned', 'Grok Build into ~/.grok-build (stable channel; the download is unverified: no checksum)'
+    rc, out, err = L.run_bounded(argv, GROK_BUILD_TIMEOUT)
+    found = next((GROK_BUILD_LINE.match(line.strip()) for line in reversed(out.splitlines())
+                  if GROK_BUILD_LINE.match(line.strip())), None)
+    if rc != 0 or not found:
+        last = next((line.strip() for line in reversed((err or '').splitlines()) if line.strip()), '')
+        reason = f'no answer within {GROK_BUILD_TIMEOUT} s' if rc is None else f'exit {rc}'
+        print(f'✗ grok-build: {reason}' + (f' ({last[:160]})' if last else ''))
+        return 'failed', f'{reason}: Grok Build not installed in {container}' + (f' ({last[:160]})' if last else '')
+    version, size, digest, runs = found.groups()
+    detail = (f'Grok Build {version} in ~/.grok-build (bin/grok -> downloads/grok-linux-x86_64; {runs or "no --version"}'
+              f') — download UNVERIFIED (the stable channel publishes no checksum): {size} bytes, sha256 {digest}')
+    print(f'⚠ grok-build: {detail}')
+    return 'warn', detail
+
+
 def onboard_args(args):
     if not args or args[0].startswith('-'):
         raise L.LanesError(ONBOARD_USAGE)
     opts, rest = {}, list(args[1:])
     while rest:
         word = rest.pop(0)
-        if word in ('--container', '--workspace', '--repo', '--title') and rest and word not in opts:
+        if word == '--step' and rest and rest[0] in ONBOARD_OPTIONAL:
+            opts.setdefault('--step', []).append(rest.pop(0))
+        elif word in ('--container', '--workspace', '--repo', '--title') and rest and word not in opts:
             opts[word] = rest.pop(0)
         elif word in ('--write', '--no-mcp'):
             opts[word] = True
@@ -2613,10 +3124,20 @@ def cmd_onboard(args):
                    if lane_core().read_regular(path, lane_core().EDIT_MAX) != mcp_before.get(path)]
         return ('changed', ', '.join(changed)) if changed else ('unchanged', files)
 
+    def installed(agent):
+        """None when `agent` is installed in the container (its home is a real directory), else why not."""
+        rel = HOOK_HOMES.get(agent)
+        if rel is None or (home() / rel).is_dir() and not (home() / rel).is_symlink():
+            return None
+        return f'no ~/{rel} in the container: {HARNESS_NAMES[agent]} is not installed there'
+
     def hooks_step(agent):
         def step():
             target = home()
-            files = [target / HOOK_TARGETS[agent][1]] + ([target / '.codex/config.toml'] if agent == 'codex' else [])
+            missing = installed(agent)
+            if missing:
+                return 'skipped', missing + (' (--step grok-build installs it)' if agent == 'grok' else '')
+            files = [target / rel for rel in hook_files(agent)]
             before = [path.read_bytes() if path.exists() else None for path in files]
             cmd_hooks(['install', '--agent', agent, '--container', container, '--write' if write else '--dry-run'])
             if not write:
@@ -2626,6 +3147,24 @@ def cmd_onboard(args):
             return ('changed', ', '.join(changed)) if changed else ('unchanged', str(files[0]))
         return step
 
+    def kimi_notify_step():
+        if 'kimi-notify' not in opts.get('--step', []):
+            return 'skipped', 'optional: --step kimi-notify (Kimi Code rings the bell on every turn end, focused or not)'
+        missing = installed('kimi')
+        if missing:
+            return 'skipped', missing
+        path = home() / '.kimi-code/tui.toml'
+        before = path.read_bytes() if path.exists() else None
+        install_edits(home(), (('.kimi-code/tui.toml', kimi_notify),), write)
+        if not write:
+            return 'planned', str(path)
+        return ('changed' if (path.read_bytes() if path.exists() else None) != before else 'unchanged'), str(path)
+
+    def grok_build_step():
+        if 'grok-build' not in opts.get('--step', []):
+            return 'skipped', 'optional: --step grok-build (installs Grok Build into ~/.grok-build)'
+        return provision_grok_build(container, write)
+
     def sync_step():
         if not write:
             print('would run: lanes sync')
@@ -2679,9 +3218,13 @@ def cmd_onboard(args):
 
     print(f"lanes onboard {login} -> container {container}" + (f', board {board}' if board else '')
           + ('' if write else ' (dry run)'))
-    plan = [('inspect', inspect_step, True), ('board', board_step, True), ('contract', contract_step, True),
+    # grok-build (opt-in) runs before the contract, so install-container's MCP entries and hooks-grok find its home in
+    # the same run.
+    plan = [('inspect', inspect_step, True), ('board', board_step, True), ('grok-build', grok_build_step, False),
+            ('contract', contract_step, True),
             ('lane-mcp', mcp_step, False), ('hooks-claude', hooks_step('claude'), False),
-            ('hooks-codex', hooks_step('codex'), False),
+            ('hooks-codex', hooks_step('codex'), False), ('hooks-kimi', hooks_step('kimi'), False),
+            ('kimi-notify', kimi_notify_step, False), ('hooks-grok', hooks_step('grok'), False), ('hooks-grok-cli', hooks_step('grok-cli'), False),
             ('throttle', lambda: provision_throttle(container, site, write), False),
             ('sync', sync_step, False), ('cursor-sync', cursor_step, False), ('resync', resync_step, False),
             ('doctor', doctor_step, False)]
@@ -2697,7 +3240,8 @@ def cmd_onboard(args):
     for key, value in (('login', login), ('container', container), ('workspace', board or '-')):
         print(f'{key + ":":<14}{value}')
     for step in steps:
-        print(f"{step['name'] + ':':<14}{step['status']:<10} {step['detail']}")
+        print(f"{step['name'] + ':':<14}" + ('' if len(step['name']) < 13 else ' ')   # hooks-grok-cli: 15 wide
+              + f"{step['status']:<10} {step['detail']}")
     if write:
         print(f"{'receipt:':<14}{onboard_receipt(login, container, board, steps)}")
     else:
@@ -4240,6 +4784,213 @@ def docs_doctor(home=None, probe=None):
             docs_mermaid_line(home), docs_age_line()]
 
 
+# ------------------------------------------------------------------ doctor: the fleet and the Throttle pulse (W11)
+# Four lines (W12 added the pools line) from what statusd published (spec
+# docs/superpowers/specs/2026-10-11-lanes-fleet-dashboard-design.md §2, §4): status.json's `throttle` (the
+# container-side pulse's ~/.lz/state/throttle.json as statusd copied it, with `stale`) and `fleet` (host and top
+# containers, OTel names as keys), and site.conf's LANES_FLEET_DASHBOARD_URL. doctor reads files only: it never asks the
+# daemon, never starts the pulse and never runs docker. A missing pulse, a daemon that does not answer and a stale fleet
+# are warnings (⚠), never a ✗: Lanes runs without Throttle and without them. The pulse rewrites its file at least every
+# 60 s, but on a 10 s loop with `at` truncated to the second a healthy one is routinely read 60–84 s after its `at`:
+# statusd calls it stale past 90 s (statusd.PULSE_STALE_S, DEF-1941), and doctor's own clock uses the same bound, so the
+# two never disagree about a healthy pulse.
+PULSE_FRESH_S = 90
+# The pulse's pools in its order (statusd.PULSE_POOLS, the throttle-pulse POOLS; W12 added kimi), named by the
+# `throttle pools:` line. A pool the pulse did not report says `?`: a pulse from before 1.5.0, or a daemon from before
+# its Kimi pool (`/pools/kimi/ready` answers 404 there).
+PULSE_POOLS = ('claude', 'codex', 'kimi')
+FLEET_FRESH_S = 60          # statusd republishes `fleet` every FLEET_INTERVAL (10 s) unless the host is critical
+THROTTLE_MONITOR = 'tools--throttle-monitor'
+FLEET_DASHBOARD_KEY = 'LANES_FLEET_DASHBOARD_URL'
+# The dashboard link (spec §1, §3): https only, a DNS host name, an optional port and a plain path — what an OSC 8 link
+# and a browser may be handed without escaping. No user part (no credential in a URL), no query or fragment (site.conf
+# lines carry neither: SITE_LINE refuses `?`, `#`, `=` and `&`). Accepted when an operator writes it into the server's
+# ~/.config/lanes/site.conf; no Lanes code path ever writes it (test_server_cli.FleetDashboardUrl pins both).
+FLEET_DASHBOARD_URL = re.compile(r'https://(?=[^/:]{1,253}(?::|/|\Z))[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?'
+                                 r'(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*'
+                                 r'(?::(?P<port>[0-9]{1,5}))?(?:/[A-Za-z0-9._~/-]*)?\Z', re.ASCII)
+
+
+def fleet_dashboard_url(home=None):
+    """site.conf's LANES_FLEET_DASHBOARD_URL -> (url, problem). (None, None): unset — the state until an authenticated
+    Grafana deployment exists; (url, None): accepted; (None, why): written but refused (not https, a user part, a port
+    out of range, a character outside the plain set), so nothing links to it. The last line naming the key wins, as in
+    site_profile; a line SITE_LINE does not admit (a `?` in it, a space) is judged here too rather than read as unset."""
+    try:
+        text = ((Path(home) if home is not None else Path.home()) / '.config/lanes/site.conf').read_text()
+    except (OSError, UnicodeDecodeError):
+        return None, None
+    values = [line.split('=', 1)[1].strip() for line in text.splitlines()
+              if line.startswith(FLEET_DASHBOARD_KEY + '=')]
+    if not values or not values[-1]:
+        return None, None
+    value = values[-1]
+    if not value.startswith('https://'):
+        return None, 'not an https URL'
+    match = FLEET_DASHBOARD_URL.match(value)
+    if not match:
+        return None, 'not a plain https://host[:port][/path] URL (no user part, query, fragment or space)'
+    if match.group('port') is not None and not 0 < int(match.group('port')) < 65536:
+        return None, 'port out of range'
+    return value, None
+
+
+def throttle_container(registry=None, home=None):
+    """(container, where it was named) of the Throttle daemon's container (and so the pulse's, spec §2.1), or (None,
+    None): site.conf's LANES_THROTTLE_CONTAINER (site_profile, `home` for a test's), else the container of the
+    registry's Throttle Monitor tab (`tools--throttle-monitor`; `registry` None reads <state>/registry.json). A name
+    that is not an identifier names nothing. install-container (which starts the pulse), doctor and the update's
+    re-ship (update.daemon_container) all read the setting from site.conf, so they name the same container."""
+    named = site_profile(home).get('LANES_THROTTLE_CONTAINER')
+    if named and L.IDENT.fullmatch(named):
+        return named, 'site.conf LANES_THROTTLE_CONTAINER'
+    if registry is None:
+        registry = L.read_json(L.STATE / 'registry.json', {})
+    for tool in (registry.get('tools') if isinstance(registry, dict) else None) or ():
+        if isinstance(tool, dict) and tool.get('id') == THROTTLE_MONITOR and isinstance(tool.get('container'), str) \
+                and L.IDENT.fullmatch(tool['container']):
+            return tool['container'], f"the registry's {THROTTLE_MONITOR}"
+    return None, None
+
+
+def age_shown(seconds):
+    seconds = max(0, int(seconds))
+    if seconds < 120:
+        return f'{seconds} s'
+    return f'{seconds // 60} min' if seconds < 7200 else f'{seconds // 3600} h'
+
+
+def number(value):
+    """A finite JSON number, else None (a bool, a string, NaN or an infinity a hand-edited file could hold)."""
+    return value if isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value) else None
+
+
+def pulse_line(throttle, container, now):
+    """The pulse: its age by `at`, the container it runs in, whether the daemon answered and whether it holds the
+    opt-in bearer (money and burn lines need it; `lanes throttle adopt-token <c>` is the operator's step)."""
+    where = (f'container {container}' if container else
+             'no daemon container: site.conf LANES_THROTTLE_CONTAINER unset and no Throttle tab')
+    adopt = f'lanes throttle adopt-token {container}' if container else 'lanes throttle adopt-token <container>'
+    at = number((throttle or {}).get('at')) if isinstance(throttle, dict) else None
+    if at is None:
+        start = (f'lanes install-container {container} starts it in the daemon\'s container' if container else
+                 'name the daemon\'s container with LANES_THROTTLE_CONTAINER in ~/.config/lanes/site.conf, then lanes '
+                 'install-container <container>')
+        return '⚠', f'throttle pulse: none in status.json ({where}) — {start}'
+    age = now - at
+    up = throttle.get('up') is True
+    error = throttle.get('error')
+    daemon = 'daemon up' if up else 'daemon down' + (f' ({plain(error)[:80]})' if isinstance(error, str) and error else '')
+    tokened = throttle.get('tokened') is True
+    text = (f'throttle pulse: {age_shown(age)} old ({where}), {daemon}, tokened: {"yes" if tokened else "no"}'
+            + ('' if tokened else f' — {adopt}'))
+    if throttle.get('stale') is True or age > PULSE_FRESH_S:
+        rearm = f'lanes install-container {container}' if container else 'lanes install-container <container>'
+        return '⚠', text + f'; stale: the pulse stopped (statusd re-arms it at most every 10 min, or {rearm})'
+    return ('✓' if up else '⚠'), text
+
+
+def pools_line(throttle):
+    """The pools the pulse reports, usable of configured: `throttle pools: claude 12/19 · codex 3/5 · kimi 5/8 usable`.
+    A pool with nothing configured is `0/0` (a daemon with no Kimi account), one the pulse did not report `?`. A `⚠`
+    when a configured pool has no usable account (the sidebar's attention tone); otherwise information. The pulse
+    line above says how old these figures are."""
+    pools = throttle.get('pools') if isinstance(throttle, dict) else None
+    if not isinstance(pools, dict) or number(throttle.get('at')) is None:
+        return '', 'throttle pools: none in status.json'
+
+    def count(value):
+        return value if isinstance(value, int) and not isinstance(value, bool) and value >= 0 else None
+    parts, empty = [], []
+    for pool in PULSE_POOLS:
+        row = pools.get(pool) if isinstance(pools.get(pool), dict) else {}
+        configured, usable = count(row.get('configured')), count(row.get('usable'))
+        if configured is None:
+            parts.append(f'{pool} ?')
+            continue
+        usable = min(usable or 0, configured)
+        parts.append(f'{pool} {usable}/{configured}')
+        if configured and not usable:
+            empty.append(pool)
+    text = 'throttle pools: ' + ' · '.join(parts) + ' usable'
+    if empty:
+        return '⚠', text + f" — no usable account in {', '.join(empty)}"
+    return '', text
+
+
+def fleet_line(fleet, containers, now):
+    """The host: cpu and memory utilization, the highest PSI avg10, and how many workspace containers run."""
+    containers = containers if isinstance(containers, dict) else {}
+    running = sum(1 for info in containers.values() if isinstance(info, dict) and info.get('running'))
+    if not isinstance(fleet, dict) or number(fleet.get('at')) is None:
+        return '⚠', (f'fleet: not in status.json (containers {running}) — a statusd from before 1.4.0 '
+                     '(systemctl --user restart lanes-statusd.service)')
+
+    def percent(value):
+        value = number(value)
+        return '?' if value is None else f'{round(value * 100)}%'
+    pressure = fleet.get('system.pressure') if isinstance(fleet.get('system.pressure'), dict) else {}
+    psi = [value for value in map(number, pressure.values()) if value is not None]
+    text = (f"fleet: cpu {percent(fleet.get('system.cpu.utilization'))} · "
+            f"mem {percent(fleet.get('system.memory.utilization'))} · "
+            f"psi {f'{round(max(psi))}%' if psi else '?'} · containers {running}")
+    age = now - fleet['at']
+    if fleet.get('stale') is True or age > FLEET_FRESH_S:
+        return '⚠', text + f' — stale ({age_shown(age)} old: statusd skips it while the host is critical)'
+    return '', text
+
+
+def dashboard_line(home=None):
+    url, problem = fleet_dashboard_url(home)
+    if problem:
+        return '⚠', f'fleet dashboard: {FLEET_DASHBOARD_KEY} ignored — {problem}; nothing links to it'
+    if url is None:
+        return '', f'fleet dashboard: {FLEET_DASHBOARD_KEY} unset'
+    return '', f'fleet dashboard: {url}'
+
+
+def fleet_doctor(status, registry, home=None, now=None):
+    """`lanes doctor`'s W11 lines -> [(mark, text)] (✓ | ⚠ | '' information; never ✗), in this order: the Throttle
+    pulse, its pools (W12: claude, codex, kimi), the fleet, the dashboard link. Read-only: status.json (already
+    read), the registry, site.conf."""
+    now = time.time() if now is None else now
+    status = status if isinstance(status, dict) else {}
+    container, _named_by = throttle_container(registry, home)
+    return [pulse_line(status.get('throttle'), container, now),
+            pools_line(status.get('throttle')),
+            fleet_line(status.get('fleet'), status.get('containers'), now),
+            dashboard_line(home)]
+
+
+# ------------------------------------------------------------------ doctor: the harness mix (W12)
+# `agent.harness` is an observed fact since W12 (spec
+# docs/superpowers/specs/2026-10-15-lanes-harness-observers-design.md §2): statusd reads it from the pane's process
+# tree. doctor counts what status.json carries — every lane row with an `agent` object, by its harness — and names each
+# value of the spec's enum, `unknown` (and any value outside the enum, such as an empty harness from a statusd before
+# W12) only when some lane has it. A row without `agent` (no signal names an agent there) is not counted. Information
+# only, never a ✗.
+HARNESSES = ('claude', 'codex', 'kimi', 'grok', 'grok-cli', 'shell')
+
+
+def harness_line(status):
+    """`lanes: claude 50 · codex 20 · kimi 3 · grok 0 · grok-cli 0 · shell 0` from status.json's lane rows. `shell`
+    counts an agent{} that names it, which statusd's merge never writes (a pane whose harness ended is published under
+    that harness's name with status `shell`, DM-LANES-STATUS): the slot reads 0 unless a foreign sidecar says so."""
+    counts, unknown = dict.fromkeys(HARNESSES, 0), 0
+    lanes = status.get('lanes') if isinstance(status, dict) else None
+    for row in lanes.values() if isinstance(lanes, dict) else ():
+        agent = row.get('agent') if isinstance(row, dict) else None
+        if not isinstance(agent, dict):
+            continue
+        harness = agent.get('harness')
+        if isinstance(harness, str) and harness in counts:
+            counts[harness] += 1
+        else:
+            unknown += 1
+    return '', ('lanes: ' + ' · '.join(f'{name} {n}' for name, n in counts.items())
+                + (f' · unknown {unknown}' if unknown else ''))
+
+
 # ------------------------------------------------------------------ doctor: the release that runs (W9 V3, LNS-85)
 # `lanes version` says which tree each process last started from; doctor judges it, with the reference `lanes version`
 # uses (the tree the `current` link names; this tree when there is none). A run record outlives its process, so only a
@@ -4569,6 +5320,8 @@ def cmd_doctor(_args):
     # 'unknown' / stale = statusd could not OBSERVE the lane (its tmux server did not answer): not the same as gone.
     check(not states.get('missing') and not states.get('unknown') and not stale, 'all registry lanes observed and present',
           str(states) + (f'; {stale} shown with their last known state (tmux server did not answer)' if stale else ''))
+    # The harness mix (W12): which agent each lane runs, as statusd observed it; information only.
+    print(f'  {harness_line(status)[1]}')
     # One bounded process-table sweep serves both checks; the cgroup of the few tmux servers is a plain file read.
     rc, table, _err = L.run_bounded(['ps', '-eo', 'pid=,comm=,args='], 10)
     coexist = (L.STATE / 'flags/coexist').exists()
@@ -4626,6 +5379,12 @@ def cmd_doctor(_args):
             print(f'{mark or " "} {text}')
         else:
             check(mark == '✓', text)
+    # The fleet and the Throttle pulse (W11): what statusd published and site.conf's dashboard link; never a ✗.
+    for mark, text in fleet_doctor(status, registry):
+        if mark in ('⚠', ''):
+            print(f'{mark or " "} {text}')
+        else:
+            check(mark == '✓', text)
     # The release that runs (W9 V3): `current`, the run records against the one process-table sweep above, the
     # device layouts, the units.
     for mark, text in release_doctor(table if rc == 0 else None):
@@ -5304,7 +6063,7 @@ COMMANDS = {'rebuilt': cmd_rebuilt, 'hello': cmd_hello, 'client-config': cmd_cli
             'prepare': cmd_prepare, 'web': cmd_web, 'attach': cmd_attach, 'rebuild': cmd_rebuild, 'ensure': cmd_ensure, 'invariant': cmd_invariant,
             'doctor': cmd_doctor, 'pressure': cmd_pressure, 'sockets': cmd_sockets, 'tmp': cmd_tmp,
             'guard': cmd_guard, 'rename': cmd_rename, 'register': cmd_register, 'unregister': cmd_unregister,
-            'hooks': cmd_hooks, 'economy': cmd_economy,
+            'hooks': cmd_hooks, 'economy': cmd_economy, 'throttle': cmd_throttle,
             'preview': cmd_preview, 'edit': cmd_edit, 'device': cmd_device, 'next': cmd_next, 'prev': cmd_prev,
             'sidebar-key': cmd_sidebar_key, 'studio-host': cmd_studio_host,
             'keys': cmd_keys, 'invite': cmd_invite, 'enrol': cmd_enrol, 'offboard': cmd_offboard,