@vibelord/lanes 1.3.0 → 1.5.1

package/payload/lanes/libexec/agent_state.py

@@ -27,9 +27,35 @@ child_liveness(): a per-pane read of /proc/<pid>/task/*/children (this kernel ex
 MEASURED 2026-10-04 on 6.8.0-106-generic), falling back to one child_parents() /proc walk only when that read
 fails; a pid whose liveness could not be determined gets no `pane_has_child` key (unknown never demotes).
 pane_current_command stays a secondary hint (a non-shell pane root such as node is the harness itself, child or not).
+
+W12 (spec `docs/superpowers/specs/2026-10-15-lanes-harness-observers-design.md` §2/§3): WHICH harness a pane runs is an
+OBSERVED fact, no longer a side effect of parsing its title. `harness_walk` reads the pane's process tree in the
+container's /proc (the `pane_has_child` reads, depth <= 4, breadth first) and takes the first `comm` in HARNESS_COMMS.
+MEASURED 2026-10-15 on this workspace: Claude Code = `bash` -> `claude`; Codex = `bash` -> `node` (the npm wrapper) ->
+`codex` (the native binary), so Codex is found one level down; Kimi Code 2.1.1 = `bash` -> `kimi-code` (exe
+`~/.kimi-code/bin/kimi`, its /proc/<pid>/cwd equal to its session's state.json `cwd`). Grok Build and grok-cli both run
+as `comm` `grok` and are told apart by /proc/<pid>/exe (evidence `2026-10-15-grok-build-measurement.md`); native Claude
+Code before 2.1.299 runs with its version as `comm` (`2.1.295`, MEASURED 2026-10-15) and is named by its exe (DEF-1993).
+Grok Build's own files are read by libexec/harness_grok.py (Track B) through `grok_sessions`, one contract. The Codex
+title rule then runs only where Codex can be: before W12 any title of two or more words was read as Codex idle, so a
+Kimi lane (static title `check the code and logs for thro`) was published `codex / idle` (DEF-1970).
+
+Kimi Code keeps its state in files (`kimi_sessions`): `~/.kimi-code/sessions/wd_<name>_<sha256(root)[:12]>/
+session_<uuid>/state.json` and the session's event log `agents/main/wire.jsonl`. MEASURED 2026-10-15 over the 24
+sessions of this workspace (Kimi Code 2.1.1, protocol of state.json `version` 2): every event carries `time` in epoch
+ms; a turn is `agent.turn.started` + `turn.prompt` ... `context.append_loop_event` (step.begin / tool.call /
+tool.result / step.end / content.part) and `llm.request` ... `turn.ended{reason}` (completed 35, cancelled 9, failed 4)
+then, after the turn's `agent.message.appended` dump, `agent.turn.ended{outcome: done}`; an approval is
+`interaction.request{kind: approval}` answered by `interaction.resolved` of the same id (a `question` is the other kind,
+and a cancelled turn can leave either unanswered); state.json drops `lastTurnReason` when a turn starts and sets it
+(`completed|failed|cancelled`) when one ends.
 """
+import importlib.util
 import json
 import os
+import stat
+import sys
+import time
 from pathlib import Path
 
 SPINNER = set('⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠁⠂⠄⡀⢀⠠⠐⠈')
@@ -48,6 +74,37 @@ RANK = {'needs': 3, 'working': 2, 'done': 1, None: 0}
 DWELL = {'needs': 8, 'working': 5, 'done': 5, None: 0}
 GONE_DWELL = 5
 
+# W12 harness identity (spec §2). The comm (/proc/<pid>/comm, at most 15 bytes) of each harness, and what it is called.
+HARNESS_COMMS = {'claude': 'claude', 'codex': 'codex', 'kimi': 'kimi', 'kimi-code': 'kimi', 'grok': 'grok'}
+AGENT_HARNESSES = ('claude', 'codex', 'kimi', 'grok', 'grok-cli')
+HARNESSES = AGENT_HARNESSES + ('shell', 'unknown')   # the published `agent.harness` enum (DM-LANES-STATUS)
+HARNESS_DEPTH = 4       # levels below the pane's root process walked for a harness
+HARNESS_FANOUT = 64     # processes examined per pane at most: a fork bomb under a pane costs a bounded read
+# Grok Build's /proc/<pid>/exe is `$GROK_HOME/downloads/grok-linux-<arch>` (harness_grok.harness_of_exe, the same rule);
+# any other process named grok is grok-cli.
+GROK_BUILD_DIR, GROK_BUILD_PREFIX = 'downloads', 'grok-linux-'
+# Native Claude Code runs `~/.local/share/claude/versions/<version>`; before 2.1.299 that file name, the version, was its
+# comm (MEASURED 2026-10-15: `2.1.295`), so a process whose exe holds this is Claude Code whatever its comm (DEF-1993;
+# lane-signal's and lane_core's CLAUDE_EXE, the same rule).
+CLAUDE_EXE = '/claude/versions/'
+
+# W12 Kimi Code observer (spec §3).
+KIMI_SESSIONS = ('.kimi-code', 'sessions')   # under the container home
+KIMI_STALE = 3600        # a session whose newest event or state write is older than this makes no claim
+KIMI_TAIL = 64 << 10     # bytes of agents/main/wire.jsonl read from its end (whole lines only)
+KIMI_STATE_MAX = 256 << 10   # a bigger state.json is not read (MEASURED 2026-10-15: the largest of 24 is 41 KB)
+KIMI_MAX_WORKDIRS = 256
+KIMI_MAX_SESSIONS = 2048  # session directories looked at (one stat each) per container per cycle at most
+KIMI_NAME_MAX = 120      # state.json `title` is the session's first prompt, cut: the published `name` is cut again
+KIMI_ENDED = {'completed': 'needs_input', 'cancelled': 'needs_input', 'failed': 'errored'}
+# W12 Grok Build observer (spec §4; libexec/harness_grok.py): Lanes runs Grok Build under GROK_HOME=~/.grok-build, a
+# directory name relative to the container home (harness_grok.GROK_HOME_DEFAULT and CONTAINER_HOME, the same values).
+GROK_HOME = '.grok-build'
+CONTAINER_HOME = '/home/coder'
+GROK_UNKNOWN = 'unknown'   # the Grok observer's word for a pane it sees but cannot join (leader mode): no agent{}
+_DIR_FLAGS = os.O_RDONLY | os.O_DIRECTORY | getattr(os, 'O_CLOEXEC', 0)
+_FILE_FLAGS = os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | getattr(os, 'O_CLOEXEC', 0)
+
 
 def pane_has_child(proc_root, pid):
     """Does `pid` have any child process? Reads every /proc/<pid>/task/<tid>/children (a child is listed under
@@ -111,6 +168,147 @@ def child_liveness(proc_root, pids):
     return out
 
 
+def children_of(proc_root, pid):
+    """The child pids of `pid` (every /proc/<pid>/task/<tid>/children, as `pane_has_child` reads them) as a frozenset,
+    or None when any of those reads fails — unknown, never "no children"."""
+    task = Path(proc_root, str(pid), 'task')
+    try:
+        tids = os.listdir(task)
+    except OSError:
+        return None
+    if not tids:
+        return None
+    kids = set()
+    for tid in tids:
+        try:
+            words = Path(task, tid, 'children').read_text().split()
+        except OSError:
+            return None
+        kids.update(int(word) for word in words if word.isdigit())
+    return frozenset(kids)
+
+
+def _comm(proc_root, pid):
+    try:
+        return Path(proc_root, str(pid), 'comm').read_text().strip() or None
+    except OSError:
+        return None
+
+
+def _exe(proc_root, pid):
+    """/proc/<pid>/exe without an auto-update's ` (deleted)` suffix, or None when it cannot be read."""
+    try:
+        exe = os.readlink(Path(proc_root, str(pid), 'exe'))
+    except OSError:
+        return None
+    return exe[:-len(' (deleted)')] if exe.endswith(' (deleted)') else exe
+
+
+def _named(proc_root, pid, comm):
+    """The harness a process whose comm is in HARNESS_COMMS runs. `grok` is Grok Build when /proc/<pid>/exe is
+    `…/downloads/grok-linux-<arch>` (harness_grok.harness_of_exe's rule), grok-cli for any other file; an unreadable
+    exe is `unknown`, never a guess (statusd still hands that pane to the Grok observer, which names it Grok Build only
+    when active_sessions.json names its pid)."""
+    harness = HARNESS_COMMS[comm]
+    if harness != 'grok':
+        return harness
+    exe = _exe(proc_root, pid)
+    if exe is None:
+        return 'unknown'
+    parent, _slash, name = exe.rpartition('/')
+    return 'grok' if name.startswith(GROK_BUILD_PREFIX) and parent.rpartition('/')[2] == GROK_BUILD_DIR else 'grok-cli'
+
+
+def _harness_of(proc_root, pid, comm):
+    """The harness process `pid` (whose comm is `comm`) is, or None: a comm in HARNESS_COMMS (`_named`), else — for a
+    process that is not a shell — native Claude Code by its executable (CLAUDE_EXE, DEF-1993). A shell's exe is its
+    shell, so shells cost no readlink."""
+    if comm in HARNESS_COMMS:
+        return _named(proc_root, pid, comm)
+    if comm is None or comm.lstrip('-') in SHELL_COMMANDS:
+        return None
+    exe = _exe(proc_root, pid)
+    return 'claude' if exe is not None and CLAUDE_EXE in exe else None
+
+
+def harness_walk(proc_root, pid, kids=None):
+    """(harness, harness pid) of the pane whose root process is `pid`, read in `proc_root` (the container's /proc as
+    the host sees it). Breadth first from the root itself down HARNESS_DEPTH levels of children, the first process
+    whose comm is in HARNESS_COMMS names it (`_named`), so a harness that runs another as a tool is still the lane's
+    harness. A process whose comm is not a harness's but whose executable is a native Claude Code file (CLAUDE_EXE:
+    before 2.1.299 its comm was its version) is Claude Code (`_harness_of`, DEF-1993). No harness found: `shell` when
+    every process read is a shell (SHELL_COMMANDS) and the tree ended within the depth, else `unknown` (another
+    program, a comm or children read that failed, the depth or HARNESS_FANOUT cut) with harness pid 0. (None, 0) when
+    the root's own children cannot be read: the harness was not observed at all. `kids` = the root's children when the
+    caller has read them already (`HarnessCache`)."""
+    kids = children_of(proc_root, pid) if kids is None else kids
+    if kids is None:
+        return None, 0
+    comm = _comm(proc_root, pid)
+    found = _harness_of(proc_root, pid, comm)
+    if found:
+        return found, int(pid)
+    only_shells = comm is not None and comm.lstrip('-') in SHELL_COMMANDS
+    level, seen = sorted(kids), 0
+    for _depth in range(HARNESS_DEPTH):
+        below = []
+        for child in level:
+            seen += 1
+            if seen > HARNESS_FANOUT:
+                return 'unknown', 0
+            name = _comm(proc_root, child)
+            found = _harness_of(proc_root, child, name)
+            if found:
+                return found, child
+            if name is None or name.lstrip('-') not in SHELL_COMMANDS:
+                only_shells = False
+            grand = children_of(proc_root, child)
+            if grand is None:
+                only_shells = False
+            else:
+                below.extend(sorted(grand))
+        level = below
+        if not level:
+            break
+    return ('shell' if only_shells and not level else 'unknown'), 0
+
+
+class HarnessCache:
+    """statusd's per-pane memory of `harness_walk`, keyed by (proc root, pane pid): each cycle reads the pane's own
+    children and the comm of the harness it found; the tree is walked again when that child set changed, when that
+    process exited or its comm is no longer the one it had when it was found (an exec in place — compared as the comm
+    itself, so a native Claude Code named by its version, whose comm is no HARNESS_COMMS key, is re-walked too), or
+    when the last answer was not a harness (`shell`/`unknown` are never kept: a wrapper such as Codex's `node` starts
+    its harness one level down without changing the pane's own children). `prune` drops the panes a cycle did not
+    see."""
+
+    def __init__(self):
+        self.entries = {}
+        self.walks = 0   # how many trees were walked (the tests' view of a cache hit)
+
+    def harness(self, proc_root, pid):
+        key = (str(proc_root), int(pid))
+        kids = children_of(proc_root, pid)
+        if kids is None:
+            self.entries.pop(key, None)
+            return None, 0
+        hit = self.entries.get(key)
+        if hit and hit[0] == kids and hit[3] is not None and _comm(proc_root, hit[2]) == hit[3]:
+            return hit[1], hit[2]
+        self.walks += 1
+        harness, harness_pid = harness_walk(proc_root, pid, kids)
+        comm = _comm(proc_root, harness_pid) if harness_pid else None
+        if harness in AGENT_HARNESSES and harness_pid and comm is not None:
+            self.entries[key] = (kids, harness, harness_pid, comm)
+        else:
+            self.entries.pop(key, None)
+        return harness, harness_pid
+
+    def prune(self, keep):
+        for key in set(self.entries) - set(keep):
+            del self.entries[key]
+
+
 def _harness_ended(pane_row):
     """True only when the row says the pane's root process has NO child (`pane_has_child is False`) and the
     foreground is a bare shell: the harness exited into that shell, whatever title it left behind. A live
@@ -138,8 +336,15 @@ def _same_process(proc_root, pid, proc_start):
         return False
 
 
-def parse_codex_title(title):
-    """A Codex pane title -> {'harness','status','name'}, or None for a shell / non-agent title."""
+def parse_codex_title(title, harness=None):
+    """A Codex pane title -> {'harness','status','name'}, or None for a shell / non-agent title. `harness` is the pane's
+    OBSERVED harness (`harness_walk`): a pane running another harness (claude, kimi, grok, grok-cli) is never Codex's.
+    On a Codex pane any title is Codex's (a task line: idle); on a pane running something else (`unknown`) only the two
+    shapes nothing else draws — `[ ! ] Action Required` and a braille spinner — are; on a bare shell (`shell`, a title
+    tmux kept after Codex exited) and where the harness could not be observed (None) also Codex's idle `<task> | <dir>`.
+    The pre-W12 catch-all, "any title of two or more words is Codex idle", is gone (DEF-1970)."""
+    if harness not in (None, 'codex', 'unknown', 'shell'):
+        return None
     t = (title or '').strip()
     head = t.split('|')[0]
     if t in SHELL_TITLES or (': ' in head and head.startswith(('coder@', 'root@'))):
@@ -151,7 +356,7 @@ def parse_codex_title(title):
         return {'harness': 'codex', 'status': 'working', 'name': t[1:].split('|')[0].strip()}
     if t.startswith('✳'):
         return None   # Claude's static title: presence only; the session file carries the state
-    if '|' in t or len(t.split()) >= 2:
+    if harness == 'codex' or (harness != 'unknown' and '|' in t):
         return {'harness': 'codex', 'status': 'idle', 'name': head.strip()}
     return None
 
@@ -229,30 +434,417 @@ def read_sidecar_dict(d, now, max_age, proc_root=None):
             'pid': pid, 'source': 'hook', 'event': str(d.get('event') or '')}
 
 
-def merge(pane_row, claude_by_pane, sidecar):
-    """Precedence: hook sidecar (event-driven, both harnesses) > Claude session file > Codex title > bell.
+def pane_key(pane_row):
+    """`<session>:@<win>.%<pane>`, the key Claude's session files name a pane by and every per-pane index here uses."""
+    return f"{pane_row.get('session_name')}:{pane_row.get('window_id')}.{pane_row.get('pane_id')}"
+
+
+def _open_at(dir_fd, parts):
+    """fd of <dir_fd>/<parts…>, every component a REAL directory opened with O_NOFOLLOW (a symlink is OSError, never
+    followed: through /proc/<pid>/root an absolute link would resolve against the HOST's root). `dir_fd` stays open;
+    the caller closes the returned fd. The `lanes_lib.open_real_dir` rule, kept here so agent_state imports nothing of
+    Lanes."""
+    fd = None
+    try:
+        for part in parts:
+            if not part or '/' in part or part in ('.', '..'):
+                raise OSError(f'not one directory entry: {part!r}')
+            child = os.open(part, _DIR_FLAGS | os.O_NOFOLLOW, dir_fd=dir_fd if fd is None else fd)
+            if fd is not None:
+                os.close(fd)
+            fd = child
+    except BaseException:
+        if fd is not None:
+            os.close(fd)
+        raise
+    return fd
+
+
+def _mtime_at(dir_fd, name):
+    """The mtime of `name` in `dir_fd` when it is a regular file (not followed), else None."""
+    try:
+        info = os.stat(name, dir_fd=dir_fd, follow_symlinks=False)
+    except OSError:
+        return None
+    return info.st_mtime if stat.S_ISREG(info.st_mode) else None
+
+
+def _read_at(dir_fd, name, limit, tail=False):
+    """(bytes, whole) of `name` in `dir_fd` when it is a regular file, never a link (O_NOFOLLOW) and never blocking on a
+    FIFO (O_NONBLOCK), else None. Whole file: refused (None) above `limit` bytes. `tail`: its last `limit` bytes, read
+    from one byte earlier so the caller can tell a cut first line from a whole one (`wire_events`); `whole` is True
+    when that is the entire file."""
+    try:
+        fd = os.open(name, _FILE_FLAGS, dir_fd=dir_fd)
+    except OSError:
+        return None
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode) or (info.st_size > limit and not tail):
+            return None
+        start = max(0, info.st_size - limit - 1) if tail else 0
+        if start:
+            os.lseek(fd, start, os.SEEK_SET)
+        want = limit + 1
+        chunks, size = [], 0
+        while size < want:
+            chunk = os.read(fd, want - size)
+            if not chunk:
+                break
+            chunks.append(chunk)
+            size += len(chunk)
+        data = b''.join(chunks)
+        if not tail and len(data) > limit:
+            return None   # grew past the bound between fstat and read
+        return data, start == 0
+    except OSError:
+        return None
+    finally:
+        os.close(fd)
+
+
+def wire_events(data, whole):
+    """The events (JSON objects, file order) on the WHOLE lines of a wire.jsonl read: a tail that does not start at the
+    file's start loses everything up to its first newline (a cut line — or, when the byte before the window was a
+    newline, an empty one), and the text after the last newline is a line still being written. A line that is not a
+    JSON object is skipped."""
+    lines = data.split(b'\n')
+    lines = lines[:-1] if whole else lines[1:-1]
+    out = []
+    for line in lines:
+        try:
+            event = json.loads(line)
+        except ValueError:
+            continue
+        if isinstance(event, dict):
+            out.append(event)
+    return out
+
+
+def _ms(value):
+    """Epoch seconds from an epoch-ms field, or None."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value <= 0:
+        return None
+    return int(value // 1000)
+
+
+def kimi_status(state, events, whole=False):
+    """{'status', 'since', 'event'} of one Kimi Code session from its state.json (`state`, a dict) and the events of
+    its agents/main/wire.jsonl tail in file order (`wire_events`; `whole` = the tail is the entire file), or None.
+
+    Spec §3, as MEASURED (module docstring): `agent.turn.started` / `turn.prompt` open a turn -> working (since: the
+    turn's start); inside an open turn `context.append_loop_event` (tool.call among them), `llm.request` and
+    `turn.steer` keep it working (and are working on their own when the tail starts mid-turn); an
+    `interaction.request{kind: approval}` with no `interaction.resolved` of its id -> needs_approval (any other kind —
+    `question` — -> needs_input, a person is asked either way); `turn.ended{reason}` completed/cancelled ->
+    needs_input, failed -> errored; `agent.turn.ended{outcome}` the same (done -> needs_input) unless `turn.ended`
+    already ended that turn, and an end of a turn older than the one open is ignored; a turn start or end drops any
+    request left unanswered (a cancelled turn leaves its question so). With no such event in the tail: a whole file
+    without a turn is a session nobody has asked anything (idle); else state.json decides — `lastTurnReason` as
+    `turn.ended`'s reason, none (Kimi drops it when a turn starts) with a `lastPrompt` -> working, none without -> idle.
+    `since` is epoch seconds (the ms `time` floored), 0 when the event carried none."""
+    status = since = event = None
+    pending = {}
+    open_turn = None
+    ended = set()
+    turns = False
+    for item in events:
+        kind = item.get('type')
+        at = _ms(item.get('time'))
+        turn = item.get('turnId')
+        turn = None if turn is None or isinstance(turn, (dict, list)) else str(turn)
+        if kind in ('agent.turn.started', 'turn.prompt'):
+            turns = True
+            if status != 'working' or (turn is not None and open_turn is not None and turn != open_turn):
+                since, event = at, kind
+            status = 'working'
+            open_turn = turn if turn is not None else open_turn
+            pending.clear()
+        elif kind in ('context.append_loop_event', 'llm.request', 'turn.steer'):
+            turns = True
+            if status is None:
+                status, since, event = 'working', at, kind
+        elif kind == 'interaction.request':
+            turns = True
+            if item.get('id') is not None:
+                pending[str(item['id'])] = (str(item.get('kind') or ''), at)
+        elif kind == 'interaction.resolved':
+            pending.pop(str(item.get('id')), None)
+        elif kind in ('turn.ended', 'agent.turn.ended'):
+            turns = True
+            if turn is not None and ((open_turn is not None and turn != open_turn)
+                                     or (kind == 'agent.turn.ended' and turn in ended)):
+                continue
+            if kind == 'turn.ended':
+                word = KIMI_ENDED.get(item.get('reason'), 'needs_input')
+                if turn is not None:
+                    ended.add(turn)
+            else:
+                word = 'errored' if item.get('outcome') in ('failed', 'error', 'errored') else 'needs_input'
+            status, since, event = word, at, kind
+            open_turn = None
+            pending.clear()
+    if pending:
+        approvals = [at for asked, at in pending.values() if asked == 'approval']
+        asked = approvals or [at for _kind, at in pending.values()]
+        stamps = [at for at in asked if at]
+        return {'status': 'needs_approval' if approvals else 'needs_input', 'since': min(stamps) if stamps else 0,
+                'event': 'interaction.request'}
+    if status:
+        return {'status': status, 'since': since or 0, 'event': event}
+    updated = _ms(state.get('updatedAt')) or 0
+    reason = state.get('lastTurnReason')
+    if whole and not turns:
+        word = 'idle'
+    elif isinstance(reason, str) and reason:
+        word = KIMI_ENDED.get(reason, 'needs_input')
+    else:
+        word = 'working' if state.get('lastPrompt') else 'idle'
+    return {'status': word, 'since': updated, 'event': 'state.json'}
+
+
+def _kimi_session(workdir_fd, name, cwds, now):
+    """(activity, cwd, verdict without pid) of one `session_<uuid>` directory whose state.json `cwd` is in `cwds`, or
+    None: not ours, unreadable, or stale — neither file written within KIMI_STALE (two stats, nothing read) or its
+    newest content time (state.json `updatedAt`, the last event's `time`) older than that."""
+    try:
+        session_fd = os.open(name, _DIR_FLAGS | os.O_NOFOLLOW, dir_fd=workdir_fd)
+    except OSError:
+        return None
+    main_fd = None
+    try:
+        try:
+            main_fd = _open_at(session_fd, ('agents', 'main'))
+        except OSError:
+            main_fd = None
+        stamps = [m for m in (_mtime_at(session_fd, 'state.json'),
+                              _mtime_at(main_fd, 'wire.jsonl') if main_fd is not None else None) if m]
+        if not stamps or now - max(stamps) > KIMI_STALE:
+            return None
+        got = _read_at(session_fd, 'state.json', KIMI_STATE_MAX)
+        if not got:
+            return None
+        try:
+            state = json.loads(got[0])
+        except ValueError:
+            return None
+        if not isinstance(state, dict) or state.get('archived') is True:
+            return None
+        cwd = state.get('cwd')
+        if not isinstance(cwd, str) or cwd not in cwds:
+            return None
+        events, whole = [], False
+        tail = _read_at(main_fd, 'wire.jsonl', KIMI_TAIL, tail=True) if main_fd is not None else None
+        if tail:
+            events, whole = wire_events(*tail), tail[1]
+        times = [t for t in [_ms(state.get('updatedAt'))] + [_ms(e.get('time')) for e in events[-1:]] if t]
+        activity = max(times) if times else max(stamps)
+        if now - activity > KIMI_STALE:
+            return None
+        found = kimi_status(state, events, whole)
+        sid = str(state.get('id') or name)
+        title = state.get('title')
+        verdict = {'harness': 'kimi', 'status': found['status'],
+                   'name': title[:KIMI_NAME_MAX] if isinstance(title, str) else '',
+                   'session_id': sid[len('session_'):] if sid.startswith('session_') else sid,
+                   'since': found['since'], 'source': 'kimi-session-file', 'event': found['event']}
+        return activity, cwd, verdict
+    finally:
+        if main_fd is not None:
+            os.close(main_fd)
+        os.close(session_fd)
+
+
+def kimi_sessions(root, panes, now=None, home=('home', 'coder')):
+    """{pane key: agent verdict} for the panes running Kimi Code. `root` is the container's root as the host sees it
+    (`/proc/<init pid>/root`), `panes` {pane key: the pane's kimi pid} (statusd: the panes whose `harness_walk` found
+    `kimi`). Spec §3: a pane's kimi pid is joined to the session whose state.json `cwd` equals /proc/<pid>/cwd (read in
+    the container's /proc), the newest by activity (`_kimi_session`) when several are fresh; two kimi panes in one cwd
+    are AMBIGUOUS — neither is claimed, both fall back to the hooks, the title and the bell (DEF-1971). Every directory
+    from `home` down to `agents/main` is opened without following a link, every file read is bounded (state.json at
+    most KIMI_STATE_MAX bytes, wire.jsonl's last KIMI_TAIL), at most KIMI_MAX_WORKDIRS × KIMI_MAX_SESSIONS directories
+    are looked at, and a stale session (> KIMI_STALE) makes no claim. Verdict: {harness: kimi, status, name (state
+    title, cut), session_id (the session uuid), pid, since, source: kimi-session-file, event (the wire event that
+    decided, or `state.json`)}."""
+    now = time.time() if now is None else now
+    cwd_of = {}
+    for key, pid in (panes or {}).items():
+        try:
+            cwd_of[key] = os.readlink(Path(root, 'proc', str(int(pid)), 'cwd'))
+        except (OSError, ValueError, TypeError):
+            continue
+    by_cwd = {}
+    for key, cwd in cwd_of.items():
+        by_cwd.setdefault(cwd, []).append(key)
+    wanted = {cwd: keys[0] for cwd, keys in by_cwd.items() if len(keys) == 1}
+    if not wanted:
+        return {}
+    try:
+        root_fd = os.open(str(root), _DIR_FLAGS)
+    except OSError:
+        return {}
+    try:
+        top = _open_at(root_fd, tuple(home) + KIMI_SESSIONS)
+    except OSError:
+        return {}
+    finally:
+        os.close(root_fd)
+    best = {}
+    try:
+        budget = KIMI_MAX_SESSIONS
+        try:
+            workdirs = sorted(n for n in os.listdir(top) if n.startswith('wd_'))[:KIMI_MAX_WORKDIRS]
+        except OSError:
+            workdirs = []
+        for workdir in workdirs:
+            try:
+                workdir_fd = os.open(workdir, _DIR_FLAGS | os.O_NOFOLLOW, dir_fd=top)
+            except OSError:
+                continue
+            try:
+                try:
+                    names = sorted(n for n in os.listdir(workdir_fd) if n.startswith('session_'))
+                except OSError:
+                    names = []
+                for name in names:
+                    if budget <= 0:
+                        break
+                    budget -= 1
+                    found = _kimi_session(workdir_fd, name, wanted, now)
+                    if found and (found[1] not in best or found[0] > best[found[1]][0]):
+                        best[found[1]] = found
+            finally:
+                os.close(workdir_fd)
+    finally:
+        os.close(top)
+    out = {}
+    for cwd, (_activity, _cwd, verdict) in best.items():
+        key = wanted[cwd]
+        out[key] = dict(verdict, pid=int(panes[key]))
+    return out
+
+
+def _harness_grok():
+    """libexec/harness_grok.py (W12 Track B) when it ships, else None: LOOKED UP, not assumed, and imported only at the
+    call, so it may import this module."""
+    module = sys.modules.get('harness_grok')
+    if module is None:
+        if importlib.util.find_spec('harness_grok') is None:
+            return None
+        import harness_grok as module
+    return module
+
+
+def grok_sessions(root, panes, grok_home=GROK_HOME, *, home=CONTAINER_HOME, titles=None):
+    """The Grok Build observer: `harness_grok.grok_sessions(root, panes, grok_home, home=home, titles=titles)` ->
+    {pane key: verdict}, or {} when the module does not ship. ONE contract, Track B's: `root` the container's root as the
+    host sees it, `panes` {pane key: the pane's tmux row} (statusd passes the rows it walked, so the observer has the
+    title, the bell and the observed `harness`; a bare pane pid works too), `grok_home` relative to `home` unless
+    absolute, `titles` the caller's memory between calls (statusd.GROK_TITLES: the blinking `⚠ Action Required`
+    prefix). An error inside the module is the caller's to log — statusd does. Kept: verdicts whose status is a
+    vocabulary word, and the observer's GROK_UNKNOWN (leader mode: a Grok Build it sees but cannot join to a session),
+    which `merge` publishes as no agent{} rather than a guess."""
+    if not panes:
+        return {}
+    module = _harness_grok()
+    if module is None:
+        return {}
+    got = module.grok_sessions(root, panes, grok_home, home=home, titles=titles)
+    if not isinstance(got, dict):
+        return {}
+    return {key: dict(verdict) for key, verdict in got.items()
+            if isinstance(verdict, dict) and (verdict.get('status') in STATUSES or verdict.get('status') == GROK_UNKNOWN)}
+
+
+def grok_title(pane_row, bell, since):
+    """merge's Grok title rung for a pane observed running Grok Build that no observer claimed:
+    `harness_grok.parse_grok_title` of its title (`⚠ Action Required …` needs_approval, a braille spinner working,
+    `grok` / `<name> - grok` idle — done with the bell), shaped as the observer's own title verdict (`source:
+    grok-title`), or None (no module, not a Grok title). Without the observer's title memory a blinking prefix is read
+    as it is this cycle."""
+    module = _harness_grok()
+    parse = getattr(module, 'parse_grok_title', None) if module is not None else None
+    parsed = parse(pane_row.get('pane_title')) if parse is not None else None
+    if not isinstance(parsed, dict) or parsed.get('status') not in STATUSES:
+        return None
+    try:
+        pid = int(pane_row.get('harness_pid') or 0)
+    except (TypeError, ValueError):
+        pid = 0
+    status = 'done' if parsed['status'] == 'idle' and bell else parsed['status']
+    return {'harness': 'grok', 'status': status, 'name': str(parsed.get('name') or ''), 'session_id': '',
+            'pid': max(pid, 0), 'since': since, 'source': 'grok-title'}
+
+
+def merge(pane_row, claude_by_pane, sidecar, kimi_by_pane=None, grok_by_pane=None):
+    """Precedence: hook sidecar (event-driven, every harness) > Claude session file > Kimi session file > Grok observer
+    (`grok_sessions`: its session file, else the title with its blink memory) > the Grok title (`grok_title`, a pane
+    observed as `grok` nothing above claimed) > Codex title > the observed harness itself > the bell.
     Any Codex title — idle, spinner or Action Required, bell or not — over a bare-shell pane whose shell has no
     child process (`pane_has_child is False`, statusd's row key) publishes `shell`: the harness ended and tmux kept
     its last title, so no ghost idle/done/working/needs_approval. Unknown liveness leaves the title in charge.
-    Returns None when nothing says an agent is here — the sidebar then draws a plain shell."""
+
+    W12: `pane_row['harness']` is the pane's OBSERVED harness (statusd, `HarnessCache`; absent = not observed). It gates
+    the Codex title (`parse_codex_title`) and, when it names a harness, is the verdict's `harness` whatever the signal
+    said (a Claude-installed hook firing inside another harness says `claude`). The Kimi observer's `needs_input` with
+    the window bell set is `done` — a turn ended and the harness rang — except a question still asked of the person
+    (`event: interaction.request`); the Grok observer's verdicts carry its own bell rule (only a completed turn or an
+    idle title is `done`) and are taken as they come. The Grok observer's GROK_UNKNOWN (leader mode: its Grok Build runs a session it
+    cannot join to the pane) publishes no agent{}: nothing below may guess one. Last rung: a pane whose observed harness
+    nothing above claimed is that harness, `idle`, `done` with the bell (`source: process`, `pid` the harness pid statusd
+    found). Returns None when nothing says an agent is here — the sidebar then draws a plain shell."""
+    observed = pane_row.get('harness')
+    verdict = _verdict(pane_row, claude_by_pane, sidecar, kimi_by_pane or {}, grok_by_pane or {}, observed)
+    if verdict is not None and observed in AGENT_HARNESSES:
+        verdict['harness'] = observed
+    return verdict
+
+
+def _verdict(pane_row, claude_by_pane, sidecar, kimi_by_pane, grok_by_pane, observed):
     if sidecar and sidecar.get('status') in STATUSES:
         return dict(sidecar, source=sidecar.get('source') or 'hook')
-    key = f"{pane_row.get('session_name')}:{pane_row.get('window_id')}.{pane_row.get('pane_id')}"
+    key = pane_key(pane_row)
     if key in claude_by_pane:
         return dict(claude_by_pane[key])
-    title = parse_codex_title(pane_row.get('pane_title'))
     bell = pane_row.get('window_bell_flag') == '1'
+    # The Kimi observer leaves the bell to merge; the Grok observer applies it itself (harness_grok: only a completed
+    # turn or an idle title is `done` — a cancelled or interrupted turn stays needs_input, spec §4).
+    for index, rings in ((kimi_by_pane, True), (grok_by_pane, False)):
+        found = index.get(key)
+        if isinstance(found, dict) and found.get('status') == GROK_UNKNOWN:
+            return None   # seen, not joinable (Grok's leader mode): no guess below
+        if isinstance(found, dict) and found.get('status') in STATUSES:
+            found = dict(found)
+            if rings and found['status'] == 'needs_input' and bell and found.get('event') != 'interaction.request':
+                found['status'] = 'done'
+            return found
+    try:
+        activity = int(pane_row.get('window_activity') or 0)
+    except ValueError:
+        activity = 0
+    if observed == 'grok':
+        found = grok_title(pane_row, bell, activity)
+        if found:
+            return found
+    title = parse_codex_title(pane_row.get('pane_title'), observed)
     if title:
         if _harness_ended(pane_row):
             title['status'] = 'shell'   # stale title on a childless shell: the harness ended, no ghost of any kind
         elif title['status'] == 'idle' and bell:
             title['status'] = 'done'
         title['source'] = 'title'
-        try:
-            title['since'] = int(pane_row.get('window_activity') or 0)
-        except ValueError:
-            title['since'] = 0
+        title['since'] = activity
         return title
+    if observed in AGENT_HARNESSES:
+        found = {'harness': observed, 'status': 'done' if bell else 'idle', 'name': '', 'source': 'process',
+                 'since': activity}
+        try:
+            harness_pid = int(pane_row.get('harness_pid') or 0)
+        except (TypeError, ValueError):
+            harness_pid = 0
+        if harness_pid > 0:
+            found['pid'] = harness_pid
+        return found
     return None