@vibelord/lanes 1.3.0 → 1.5.0

package/payload/lanes/libexec/harness_grok.py

@@ -0,0 +1,742 @@
+"""Grok Build and grok-cli observers for agent{} (Lanes W12 Track B; spec
+docs/superpowers/specs/2026-10-15-lanes-harness-observers-design.md §4 and §5). Pure reads through the container root
+statusd already holds (`/proc/<container init pid>/root`): no subprocess, no write, nothing done at import.
+
+Grok Build (xai-org/grok-build 1.0.52, the official CLI; evidence memo
+docs/superpowers/specs/evidence/2026-10-15-grok-build-measurement.md) keeps its state under `$GROK_HOME`. Lanes runs it
+with `GROK_HOME=~/.grok-build` (GROK_HOME_DEFAULT): its installer otherwise replaces grok-cli's `~/.grok/bin/grok` with
+a symlink. Both CLIs run as comm `grok`; the binary tells them apart (`harness_of_exe`): Grok Build's is
+`$GROK_HOME/downloads/grok-linux-<arch>`, anything else named grok is grok-cli.
+
+`grok_sessions(root, panes, grok_home)` -> {pane key: verdict}, the dict `agent_state.merge` takes from a session file:
+{harness: 'grok', status, name, session_id, pid, since, source}, `source` 'grok-session-file' or 'grok-title'. Per pane:
+
+  1. The pane's process tree (pane pid and descendants to depth WALK_DEPTH, `/proc/<pid>/task/*/children` and `comm`)
+     names the Grok Build pid. No grok process in a tree read in full, under a Grok-shaped title: `shell` (the harness
+     ended, tmux kept the title it reset to `grok`). A tree that could not be read is unknown and never demotes.
+  2. `$GROK_HOME/active_sessions.json` (`[{session_id, pid, cwd, opened_at}]`, written by the TUI with its own pid [S])
+     joins that pid to a session. Entries whose pid is gone, is no longer `grok`, or started after `opened_at` (a
+     recycled pid) are ignored; two live entries for one pid (tabs) are ambiguous and fall back to the title.
+  3. `sessions/<URL-encoded cwd>/<session id>/events.jsonl` (schema 1.0, append-only [S]): its last TAIL_BYTES, whole
+     lines only, give the state (`events_status`): `turn_started`, `phase_changed` waiting_for_model | streaming_text |
+     streaming_reasoning | tool_execution, `permission_resolved` and the in-turn events -> working;
+     `phase_changed{permission_prompt}` / `permission_requested` -> needs_approval; `turn_ended.outcome` completed ->
+     needs_input (done when the pane's bell flag is set), error -> errored, cancelled | interrupted -> needs_input; no
+     turn yet -> idle. `summary.json` `generated_title` -> name.
+  4. Otherwise the pane title (`parse_grok_title`, OSC 0, on by default [S]): `⚠ Action Required - …` ->
+     needs_approval, a braille spinner -> working, `grok` / `<name> - grok` -> idle (done with the bell).
+
+Every file under `$GROK_HOME` is opened without following a link, every directory component O_NOFOLLOW (a container
+owns them): a symlinked GROK_HOME, session directory or file is refused, a FIFO is never opened blocking, and nothing
+larger than its bound is read (JSON_MAX; TAIL_BYTES of events.jsonl). A cwd whose encoded name exceeds 255 bytes is
+filed by Grok as `<slug>-<blake3>` (no stdlib blake3): its directory is found by the `.cwd` file Grok writes into it.
+
+Leader mode (`[cli] use_leader = true`, spec §4: out of scope): a socket `leader.sock` / `leader-*.sock` in GROK_HOME,
+or a live `active_sessions` entry for the pane grok's cwd whose pid is no pane's grok while the pane's own pid has
+none, publishes status UNKNOWN with a `note`. UNKNOWN is outside agent_state.STATUSES, so `agent_state.settle`
+publishes no agent{} for it; the observer never guesses a session it cannot join.
+
+The title blinks: with a permission pending and the pane unfocused, Grok drops the `⚠ Action Required` item for 0.5 s
+of every 1 s [S notifications/title.rs ACTION_REQUIRED_BLINK_DIVISOR]. After a sample that showed it, a busy title
+(spinner) without it is still needs_approval (`parse_grok_title(title, previous_title)`; `grok_sessions(...,
+titles=dict)` keeps the previous title per pane while it is prefixed); an idle title is not, since a permission is only
+pending inside a turn. Two samples a statusd cycle apart can both land in the hidden half: the session file's
+`permission_requested` is the primary approval signal and the title only its fallback (DEF-1982).
+
+Labels: [S] read from source (grok-build main 2bdd1d6a: xai-grok-active-sessions, xai-grok-session-events,
+xai-grok-config `encode_cwd_dirname`, notifications/title.rs); [D] the shipped user guide; [M] measured on this host.
+NOT measured: a logged-in session's active_sessions.json, events.jsonl, summary.json and busy/approval titles (no
+account existed); the fixtures are built from the [S] vocabulary and marked needs_operator_capture (DEF-1981).
+
+grok-cli (superagent-ai/grok-cli 1.1.7) emits nothing a host can read [M]: no title, no bell, and its `grok.db` holds
+no pid. GROK_CLI records what is known; its state reaches Lanes only through the hook sidecar `lane-signal` writes
+(hooks: W12 Track C), and it has no approval signal at all (DEF-1980). A pane whose only grok is grok-cli gets no
+verdict here.
+"""
+import calendar
+import json
+import os
+import posixpath
+import re
+import stat
+import types
+import urllib.parse
+
+HARNESS = 'grok'
+CLI_HARNESS = 'grok-cli'
+GROK_HOME_DEFAULT = '.grok-build'      # relative to the container home; an absolute GROK_HOME is taken as given
+CONTAINER_HOME = '/home/coder'
+COMM = 'grok'                          # /proc/<pid>/comm of both CLIs [M]
+EXE_DIR = 'downloads'                  # Grok Build's binary: $GROK_HOME/downloads/grok-linux-<arch> [M]
+EXE_PREFIX = 'grok-linux-'
+FLAVOUR_UNREADABLE = ''                # comm `grok`, /proc/<pid>/exe unreadable: Grok Build only if a session names it
+
+ACTIVE_SESSIONS = 'active_sessions.json'
+SESSIONS = 'sessions'
+EVENTS = 'events.jsonl'
+SUMMARY = 'summary.json'
+CWD_FILE = '.cwd'
+LEADER_SOCKET = re.compile(r'leader(-[A-Za-z0-9._-]+)?\.sock\Z')
+SESSION_ID = re.compile(r'[A-Za-z0-9][A-Za-z0-9._-]{0,127}\Z')
+
+TAIL_BYTES = 64 * 1024                 # the events.jsonl tail read per pane per cycle
+JSON_MAX = 256 * 1024                  # active_sessions.json, summary.json
+CWD_MAX = 4096
+DIRNAME_MAX = 255                      # Grok's MAX_DIRNAME_BYTES: a longer encoded cwd is a slug-hash name [S]
+SCAN_MAX = 256                         # slug-hash directories looked at for one long cwd
+WALK_DEPTH = 4
+WALK_MAX = 64                          # processes read per pane tree
+START_SLACK = 2                        # seconds: a pid that started later than opened_at + this is a recycled pid
+NAME_MAX = 120
+
+ACTION = '⚠ Action Required'
+SPINNER = frozenset('⠋⠙⠹⠸⠼⠴⠦⠧')   # TITLE_SPINNER [S]
+SEPARATOR = ' - '
+TITLE_END = 'grok'
+TITLE_BLINK_S = 0.5
+
+SOURCE_FILE = 'grok-session-file'
+SOURCE_TITLE = 'grok-title'
+UNKNOWN = 'unknown'
+VERDICT_KEYS = ('harness', 'status', 'name', 'session_id', 'pid', 'since', 'source')
+
+APPROVAL_PHASE = 'permission_prompt'
+WORKING_PHASES = frozenset(('waiting_for_model', 'streaming_text', 'streaming_reasoning', 'tool_execution'))
+IN_TURN = frozenset(('first_token', 'loop_started', 'tool_started', 'tool_completed', 'interjected'))
+OUTCOME = {'completed': 'needs_input', 'error': 'errored', 'cancelled': 'needs_input', 'interrupted': 'needs_input'}
+
+# grok-cli: what is known, nothing to observe. The hook events and the words they write are spec §5's; the hook
+# definitions themselves are Track C's (`lanes hooks install --agent grok-cli`).
+GROK_CLI = types.MappingProxyType({
+    'harness': CLI_HARNESS,
+    'package': 'superagent-ai/grok-cli',
+    'measured_version': '1.1.7',
+    'home': '.grok',
+    'settings': 'user-settings.json',
+    'install_marker': 'install.json',
+    'observed': (),
+    'hook_status': types.MappingProxyType({
+        'UserPromptSubmit': 'working', 'PreToolUse': 'working', 'PostToolUse': 'working',
+        'Stop': 'needs_input', 'StopFailure': 'errored', 'SessionEnd': 'shell'}),
+    'approval_signal': None,
+    'trace_header': None,
+})
+
+_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)
+_RFC3339 = re.compile(r'(\d{4})-(\d\d)-(\d\d)[Tt ](\d\d):(\d\d):(\d\d)(?:\.(\d+))?([Zz]|[+-]\d\d:?\d\d)\Z')
+
+
+# ------------------------------------------------------------------------------------------------ pure parsers
+
+def pane_key(row):
+    """The key `agent_state.merge` looks a pane up by: `<session>:<window id>.<pane id>`."""
+    return f"{row.get('session_name')}:{row.get('window_id')}.{row.get('pane_id')}"
+
+
+def harness_of_exe(exe):
+    """'grok' for Grok Build's binary (`…/downloads/grok-linux-<arch>`, also once replaced by an update, ` (deleted)`),
+    'grok-cli' for any other binary of a process named grok, None for no path."""
+    if not isinstance(exe, str) or not exe:
+        return None
+    path = exe[:-len(' (deleted)')] if exe.endswith(' (deleted)') else exe
+    parent, _slash, name = path.rpartition('/')
+    if name.startswith(EXE_PREFIX) and parent.rpartition('/')[2] == EXE_DIR:
+        return HARNESS
+    return CLI_HARNESS
+
+
+def encode_cwd_dirname(cwd):
+    """The directory Grok Build files an absolute cwd's sessions under (xai-grok-config `encode_cwd_dirname` [S]): the
+    cwd URL-encoded, every byte outside `A-Z a-z 0-9 - . _ ~` as upper-case %XX — the set `quote(safe='')` keeps.
+    None when that exceeds 255 bytes (Grok then uses `<slug>-<blake3 hex16>`) or the cwd is not absolute."""
+    if not isinstance(cwd, str) or not cwd.startswith('/'):
+        return None
+    try:
+        encoded = urllib.parse.quote(cwd, safe='')
+    except UnicodeError:
+        return None
+    return encoded if len(encoded) <= DIRNAME_MAX else None
+
+
+def parse_rfc3339(text):
+    """Epoch seconds (float) of an RFC 3339 stamp as chrono writes them (`2026-10-15T09:00:00.123Z`, nanoseconds in
+    active_sessions' `opened_at`), or None."""
+    match = _RFC3339.match(text) if isinstance(text, str) else None
+    if not match:
+        return None
+    year, month, day, hour, minute, second = (int(group) for group in match.groups()[:6])
+    if not (1 <= month <= 12 and 1 <= day <= 31 and hour < 24 and minute < 60 and second < 61):
+        return None
+    epoch = calendar.timegm((year, month, day, hour, minute, second, 0, 0, 0))
+    if match.group(7):
+        epoch += float('0.' + match.group(7))
+    zone = match.group(8)
+    if zone not in ('Z', 'z'):
+        digits = zone[1:].replace(':', '')
+        offset = int(digits[:2]) * 3600 + int(digits[2:]) * 60
+        epoch += -offset if zone[0] == '+' else offset
+    return epoch
+
+
+def _clean_title(title):
+    return title.strip() if isinstance(title, str) else ''
+
+
+def _title_parts(title):
+    """The ` - `-joined items of a Grok Build title, or None when it is not one (the `grok` item always ends it)."""
+    if title == TITLE_END:
+        return [TITLE_END]
+    if title.endswith(SEPARATOR + TITLE_END):
+        return title.split(SEPARATOR)
+    return None
+
+
+def _prefixed(title):
+    parts = _title_parts(_clean_title(title))
+    return bool(parts) and parts[0] == ACTION
+
+
+def parse_grok_title(title, previous_title=None):
+    """A Grok Build pane title -> {'harness': 'grok', 'status', 'name'}, or None for any other title. The default title
+    items are action-required, spinner, activity, session-name, grok, joined by ` - ` [S]: `⚠ Action Required` first ->
+    needs_approval; a braille spinner (followed by its activity) -> working; else idle (`grok`, `<name> - grok`). The
+    name is the session-name item. `previous_title` is the pane's previous sample: the prefix blinks while the pane is
+    unfocused, so after a prefixed sample a BUSY title without it is still needs_approval. A permission is only pending
+    inside a turn, and the spinner shows for the whole turn [S], so an idle title after the prefix is idle: the turn
+    ended."""
+    parts = _title_parts(_clean_title(title))
+    if parts is None:
+        return None
+    approval = parts[0] == ACTION
+    if approval:
+        parts = parts[1:]
+    busy = len(parts) > 1 and len(parts[0]) == 1 and parts[0] in SPINNER
+    name = SEPARATOR.join(parts[2:-1] if busy else parts[:-1])
+    if approval or (busy and _prefixed(previous_title)):
+        status = 'needs_approval'
+    else:
+        status = 'working' if busy else 'idle'
+    return {'harness': HARNESS, 'status': status, 'name': name}
+
+
+def parse_events(lines):
+    """The event dicts of events.jsonl lines (bytes); a line that is not one JSON object with a `type` is skipped."""
+    events = []
+    for line in lines:
+        try:
+            event = json.loads(line.decode('utf-8') if isinstance(line, bytes) else line)
+        except (UnicodeDecodeError, ValueError):
+            continue
+        if isinstance(event, dict) and isinstance(event.get('type'), str):
+            events.append(event)
+    return events
+
+
+def events_status(events, whole=True):
+    """{'status', 'since', 'outcome'} from events.jsonl's events in file order, or None when they say nothing.
+
+    The last state event wins: `turn_started` -> working; `phase_changed` permission_prompt -> needs_approval, another
+    phase -> working; `permission_requested` -> needs_approval, `permission_resolved` -> working; `turn_ended` by
+    `outcome` (OUTCOME; an unknown outcome still ends the turn: needs_input). The in-turn events (first_token,
+    loop_started, tool_started, tool_completed, interjected) mean working, except while an approval is pending (a
+    parallel tool's completion does not answer the prompt) or between turns. Every other event (MCP, goal, todo …) says
+    nothing. `since` is the epoch second of the event that began the status (kept while the status repeats), None
+    when its `ts` is unreadable; `outcome` the ending turn's outcome when the status came from `turn_ended`.
+
+    No state event at all: idle when `whole` (the file was read from its first byte — a session with no turn yet),
+    else None (the tail window holds none; the caller falls back to the title)."""
+    status = since = outcome = None
+    in_turn = None        # None: no turn boundary seen in this window
+    for event in events:
+        kind = event.get('type')
+        new, ended = None, None
+        if kind == 'turn_started':
+            in_turn, new = True, 'working'
+        elif kind == 'turn_ended':
+            in_turn = False
+            ended = event.get('outcome') if isinstance(event.get('outcome'), str) else ''
+            new = OUTCOME.get(ended, 'needs_input')
+        elif in_turn is False:
+            continue
+        elif kind == 'phase_changed':
+            new = 'needs_approval' if event.get('phase') == APPROVAL_PHASE else 'working'
+        elif kind == 'permission_requested':
+            new = 'needs_approval'
+        elif kind == 'permission_resolved':
+            new = 'working'
+        elif kind in IN_TURN:
+            new = None if status == 'needs_approval' else 'working'
+        if new is None:
+            continue
+        if new != status:
+            stamp = parse_rfc3339(event.get('ts'))
+            since = int(stamp) if stamp is not None else None
+        status, outcome = new, ended
+    if status is None:
+        return {'status': 'idle', 'since': None, 'outcome': None} if whole else None
+    return {'status': status, 'since': since, 'outcome': outcome}
+
+
+def parse_active_sessions(data):
+    """The well-formed entries of active_sessions.json (bytes): [{session_id, pid, cwd, opened_at (epoch or None)}].
+    Grok itself reads a corrupt file as empty [S]; so does this."""
+    try:
+        document = json.loads(data.decode('utf-8')) if data else []
+    except (UnicodeDecodeError, ValueError):
+        return []
+    entries = []
+    for item in document if isinstance(document, list) else ():
+        if not isinstance(item, dict):
+            continue
+        sid, pid, cwd = item.get('session_id'), item.get('pid'), item.get('cwd')
+        if (not isinstance(sid, str) or not SESSION_ID.match(sid) or isinstance(pid, bool) or not isinstance(pid, int)
+                or pid <= 0 or not isinstance(cwd, str)):
+            continue
+        entries.append({'session_id': sid, 'pid': pid, 'cwd': cwd, 'opened_at': parse_rfc3339(item.get('opened_at'))})
+    return entries
+
+
+def _printable(text):
+    if not isinstance(text, str):
+        return ''
+    return ''.join(ch for ch in text if ch.isprintable()).strip()[:NAME_MAX]
+
+
+def summary_title(data, session_id=None):
+    """summary.json's `generated_title` (bytes in), printable and at most NAME_MAX characters; '' when absent,
+    malformed, or the file's `info.id` names another session."""
+    try:
+        document = json.loads(data.decode('utf-8')) if data else None
+    except (UnicodeDecodeError, ValueError):
+        return ''
+    if not isinstance(document, dict):
+        return ''
+    info = document.get('info')
+    if session_id and isinstance(info, dict) and info.get('id') not in (None, session_id):
+        return ''
+    return _printable(document.get('generated_title'))
+
+
+# ------------------------------------------------------------------------------------------------ bounded reads
+
+def _leaf(name):
+    return isinstance(name, str) and bool(name) and '/' not in name and '\0' not in name and name not in ('.', '..')
+
+
+def _open_dir_at(dir_fd, parts):
+    """A new fd of dir_fd/<parts…>, every component a REAL directory opened O_NOFOLLOW: a symlink raises OSError, never
+    followed. `dir_fd` stays open; the caller closes the result."""
+    current = os.dup(dir_fd)
+    try:
+        for part in parts:
+            if not _leaf(part):
+                raise OSError(f'not one path component: {part!r}')
+            child = os.open(part, _DIR_FLAGS | os.O_NOFOLLOW, dir_fd=current)
+            os.close(current)
+            current = child
+    except BaseException:
+        os.close(current)
+        raise
+    return current
+
+
+def _read_at(fd, offset, count):
+    chunks, size = [], 0
+    while size < count:
+        chunk = os.pread(fd, count - size, offset + size)
+        if not chunk:
+            break
+        chunks.append(chunk)
+        size += len(chunk)
+    return b''.join(chunks)
+
+
+def read_regular_at(dir_fd, name, limit):
+    """The bytes of `name` in `dir_fd` when it is a regular file of at most `limit` bytes, else None (absent, a link, a
+    FIFO or device, bigger). Never follows a link, never blocks (O_NONBLOCK)."""
+    if dir_fd is None or not _leaf(name):
+        return None
+    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:
+            return None
+        data = _read_at(fd, 0, limit + 1)
+        return data if len(data) <= limit else None
+    except OSError:
+        return None
+    finally:
+        os.close(fd)
+
+
+def read_tail_lines(dir_fd, name, limit=TAIL_BYTES):
+    """(lines, whole) — the complete lines in the last `limit` bytes of `name` (newline stripped, empty lines dropped)
+    and whether the window reached the file's first byte. A first line cut by the window and a last line still being
+    written (no newline yet) are dropped, never parsed. An absent file is an empty one ([], True); a link, FIFO, device
+    or unreadable file is None. Never follows a link, never blocks."""
+    if dir_fd is None or not _leaf(name):
+        return None
+    try:
+        fd = os.open(name, _FILE_FLAGS, dir_fd=dir_fd)
+    except FileNotFoundError:
+        return [], True
+    except OSError:
+        return None
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode):
+            return None
+        size = info.st_size
+        start = max(0, size - limit)
+        if start:
+            data = _read_at(fd, start - 1, size - start + 1)
+            if data[:1] == b'\n':
+                data = data[1:]                       # the window starts exactly on a line
+            else:
+                cut = data.find(b'\n')
+                data = b'' if cut < 0 else data[cut + 1:]
+        else:
+            data = _read_at(fd, 0, size)
+    except OSError:
+        return None
+    finally:
+        os.close(fd)
+    if not data.endswith(b'\n'):
+        cut = data.rfind(b'\n')
+        data = b'' if cut < 0 else data[:cut + 1]
+    return [line for line in data.split(b'\n') if line.strip()], start == 0
+
+
+def _proc_text(proc_root, pid, name, limit=4096):
+    try:
+        with open(os.path.join(proc_root, str(pid), name), 'rb') as handle:
+            return handle.read(limit).decode('utf-8', 'replace')
+    except OSError:
+        return None
+
+
+def _proc_link(proc_root, pid, name):
+    try:
+        return os.readlink(os.path.join(proc_root, str(pid), name))
+    except OSError:
+        return None
+
+
+def _children(proc_root, pid):
+    """The child pids of `pid` from every /proc/<pid>/task/<tid>/children, or None when any read fails."""
+    task = os.path.join(proc_root, str(pid), 'task')
+    try:
+        tids = os.listdir(task)
+    except OSError:
+        return None
+    if not tids:
+        return None
+    kids = []
+    for tid in tids:
+        try:
+            with open(os.path.join(task, tid, 'children'), 'rb') as handle:
+                kids += [int(word) for word in handle.read().split() if word.isdigit()]
+        except (OSError, ValueError):
+            return None
+    return kids
+
+
+def grok_flavour(proc_root, pid):
+    """'grok' | 'grok-cli' for a process named grok, FLAVOUR_UNREADABLE when its exe link cannot be read, None when the
+    process is not named grok (or is gone)."""
+    comm = _proc_text(proc_root, pid, 'comm')
+    if comm is None or comm.strip() != COMM:
+        return None
+    exe = _proc_link(proc_root, pid, 'exe')
+    return FLAVOUR_UNREADABLE if exe is None else harness_of_exe(exe)
+
+
+def pane_grok_pids(proc_root, pane_pid, depth=WALK_DEPTH, limit=WALK_MAX):
+    """([(pid, flavour)], complete): the processes named grok in the pane's tree — the pane pid itself and its
+    descendants to `depth` levels, breadth first, at most `limit` processes, never below a grok. `complete` is False
+    when any read failed, the bound was hit or a process at the depth limit has children: "found none" then means
+    "could not tell", which never demotes a lane to `shell`."""
+    found, complete, seen = [], True, set()
+    queue = [(int(pane_pid), 0)]
+    while queue:
+        pid, level = queue.pop(0)
+        if pid in seen:
+            continue
+        if len(seen) >= limit:
+            complete = False
+            break
+        seen.add(pid)
+        comm = _proc_text(proc_root, pid, 'comm')
+        if comm is None:
+            complete = False
+            continue
+        if comm.strip() == COMM:
+            found.append((pid, grok_flavour(proc_root, pid) or FLAVOUR_UNREADABLE))
+            continue
+        kids = _children(proc_root, pid)
+        if kids is None:
+            complete = False
+        elif level >= depth:
+            complete = complete and not kids
+        else:
+            queue += [(kid, level + 1) for kid in kids]
+    return found, complete
+
+
+def _boot_time(proc_root):
+    try:
+        with open(os.path.join(proc_root, 'stat'), 'rb') as handle:
+            text = handle.read(1 << 16).decode('ascii', 'replace')
+    except OSError:
+        return None
+    match = re.search(r'^btime (\d+)$', text, re.M)
+    return int(match.group(1)) if match else None
+
+
+def _start_epoch(proc_root, pid, boot):
+    """The process's start in epoch seconds: /proc/<pid>/stat field 22 (clock ticks after boot) + btime, or None."""
+    text = _proc_text(proc_root, pid, 'stat')
+    try:
+        ticks = int(text.rsplit(')', 1)[1].split()[19])
+        hertz = os.sysconf('SC_CLK_TCK')
+    except (AttributeError, IndexError, ValueError, OSError):
+        return None
+    return boot + ticks / hertz
+
+
+# ------------------------------------------------------------------------------------------------ the observer
+
+class _GrokHome:
+    """One container's $GROK_HOME for one call, opened on first use: its directory fd, the live active_sessions entries
+    and the leader socket, each read at most once."""
+
+    def __init__(self, root, home, grok_home, proc_root):
+        self.root, self.proc_root = str(root), proc_root
+        path = grok_home if str(grok_home).startswith('/') else posixpath.join(str(home), str(grok_home))
+        parts = [part for part in path.split('/') if part]
+        self.parts = parts if parts and all(_leaf(part) for part in parts) else None
+        self.fd, self.opened, self._entries, self._leader = None, False, None, None
+
+    def dir(self):
+        if not self.opened:
+            self.opened = True
+            if self.parts is not None:
+                try:
+                    base = os.open(self.root, _DIR_FLAGS)
+                    try:
+                        self.fd = _open_dir_at(base, self.parts)
+                    finally:
+                        os.close(base)
+                except OSError:
+                    self.fd = None
+        return self.fd
+
+    def close(self):
+        if self.fd is not None:
+            os.close(self.fd)
+            self.fd = None
+
+    def leader(self):
+        """The name of a leader socket in GROK_HOME (a real socket, not a link to one), or ''."""
+        if self._leader is None:
+            self._leader = ''
+            fd = self.dir()
+            try:
+                names = sorted(os.listdir(fd)) if fd is not None else []
+            except OSError:
+                names = []
+            for name in names:
+                if LEADER_SOCKET.match(name):
+                    try:
+                        if stat.S_ISSOCK(os.stat(name, dir_fd=fd, follow_symlinks=False).st_mode):
+                            self._leader = name
+                            break
+                    except OSError:
+                        continue
+        return self._leader
+
+    def entries(self):
+        """The active_sessions entries whose pid still runs grok and started no later than the entry was opened."""
+        if self._entries is None:
+            boot = _boot_time(self.proc_root)
+            live = []
+            for entry in parse_active_sessions(read_regular_at(self.dir(), ACTIVE_SESSIONS, JSON_MAX)):
+                comm = _proc_text(self.proc_root, entry['pid'], 'comm')
+                if comm is None or comm.strip() != COMM:
+                    continue                                   # gone, or the pid is someone else's now
+                if boot is not None and entry['opened_at'] is not None:
+                    start = _start_epoch(self.proc_root, entry['pid'], boot)
+                    if start is not None and start > entry['opened_at'] + START_SLACK:
+                        continue                               # a grok started after the entry: a recycled pid
+                live.append(entry)
+            self._entries = live
+        return self._entries
+
+    def session_dir(self, cwd, session_id):
+        """A new fd of sessions/<encoded cwd>/<session id>, or None. A long cwd's slug-hash directory is the one whose
+        `.cwd` file holds the cwd (at most SCAN_MAX directories looked at)."""
+        fd = self.dir()
+        if fd is None or not SESSION_ID.match(session_id) or not isinstance(cwd, str) or not cwd.startswith('/'):
+            return None
+        encoded = encode_cwd_dirname(cwd)
+        try:
+            if encoded is not None:
+                return _open_dir_at(fd, (SESSIONS, encoded, session_id))
+            sessions = _open_dir_at(fd, (SESSIONS,))
+        except OSError:
+            return None
+        try:
+            names = [name for name in sorted(os.listdir(sessions)) if not name.startswith('%') and _leaf(name)]
+            for name in names[:SCAN_MAX]:
+                try:
+                    group = _open_dir_at(sessions, (name,))
+                except OSError:
+                    continue
+                try:
+                    recorded = read_regular_at(group, CWD_FILE, CWD_MAX)
+                    if recorded is not None and recorded.decode('utf-8', 'replace').strip() == cwd:
+                        try:
+                            return _open_dir_at(group, (session_id,))
+                        except OSError:
+                            return None
+                finally:
+                    os.close(group)
+        except OSError:
+            return None
+        finally:
+            os.close(sessions)
+        return None
+
+    def session(self, entry):
+        """(events_status dict, summary title) of one active session, or None when its files cannot be read or say
+        nothing."""
+        sfd = self.session_dir(entry['cwd'], entry['session_id'])
+        if sfd is None:
+            return None
+        try:
+            tail = read_tail_lines(sfd, EVENTS)
+            summary = read_regular_at(sfd, SUMMARY, JSON_MAX)
+        finally:
+            os.close(sfd)
+        if tail is None:
+            return None
+        state = events_status(parse_events(tail[0]), tail[1])
+        return None if state is None else (state, summary_title(summary, entry['session_id']))
+
+
+def _int(value):
+    try:
+        return int(value or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _command(row):
+    return str(row.get('pane_current_command') or '').strip().lstrip('-').rsplit('/', 1)[-1]
+
+
+def _rows(panes):
+    """(key, row) pairs from tmux pane rows, or from a mapping {pane key: pane pid | row}."""
+    if isinstance(panes, dict):
+        for key, value in panes.items():
+            yield str(key), (value if isinstance(value, dict) else {'pane_pid': value})
+    else:
+        for row in panes or ():
+            if isinstance(row, dict):
+                yield pane_key(row), row
+
+
+def _verdict(status, name, session_id, pid, since, source, **extra):
+    verdict = dict(zip(VERDICT_KEYS, (HARNESS, status, name, session_id, pid, since, source)))
+    verdict.update(extra)
+    return verdict
+
+
+def _from_title(parsed, pid, since, bell):
+    status = 'done' if parsed['status'] == 'idle' and bell else parsed['status']
+    return _verdict(status, parsed['name'], '', pid, since, SOURCE_TITLE)
+
+
+def _observe(home, row, parsed, procs, complete, pane_pids):
+    since = _int(row.get('window_activity'))
+    bell = row.get('window_bell_flag') == '1'
+    named = parsed['name'] if parsed else ''
+    builds = [pid for pid, flavour in procs if flavour == HARNESS]
+    unread = [pid for pid, flavour in procs if flavour == FLAVOUR_UNREADABLE]
+    if not procs:
+        if parsed is None:
+            return None
+        if complete:
+            return _verdict('shell', named, '', 0, since, SOURCE_TITLE)
+        return _from_title(parsed, 0, since, bell)
+    if not builds and not unread:
+        return None                                   # grok-cli only: nothing a host can read (GROK_CLI)
+    pid = (builds or unread)[0]
+    leader = home.leader()
+    if leader:
+        return _verdict(UNKNOWN, named, '', pid, since, SOURCE_FILE,
+                        note=f'leader mode: $GROK_HOME/{leader} exists; sessions are not joined to panes')
+    entries = home.entries()
+    mine = [entry for entry in entries if entry['pid'] == pid]
+    if not mine and builds:
+        cwd = _proc_link(home.proc_root, pid, 'cwd')
+        foreign = [entry for entry in entries if entry['pid'] not in pane_pids and cwd and entry['cwd'] == cwd]
+        if foreign:
+            return _verdict(UNKNOWN, named, '', pid, since, SOURCE_FILE,
+                            note=f"leader mode: active_sessions.json names pid {foreign[0]['pid']} for this cwd, "
+                                 f'not the pane grok {pid}')
+    if len(mine) == 1:
+        observed = home.session(mine[0])
+        if observed is not None:
+            state, title = observed
+            status = state['status']
+            if status == 'needs_input' and state['outcome'] == 'completed' and bell:
+                status = 'done'
+            when = state['since'] or _int(mine[0]['opened_at']) or since
+            return _verdict(status, title or named, mine[0]['session_id'], pid, when, SOURCE_FILE)
+    return _from_title(parsed, pid, since, bell) if parsed else None
+
+
+def grok_sessions(root, panes, grok_home=GROK_HOME_DEFAULT, *, home=CONTAINER_HOME, titles=None):
+    """{pane key: verdict} for the panes Grok Build runs in (or ended in), read through `root`, the container's root as
+    the host sees it (`/proc/<init pid>/root`; its /proc is `root/proc`, the container's pid namespace).
+
+    `panes` is the container's tmux pane rows (`session_name`, `window_id`, `pane_id`, `pane_pid`, and when present
+    `pane_title`, `window_bell_flag`, `window_activity`, `pane_current_command`, `harness`) or a mapping {pane key:
+    pane pid | row}. A row with a title is looked at only when the title is Grok's, tmux names `grok` its foreground
+    command, or the row's `harness` is 'grok'; a pid-only row always is. `grok_home` is relative to `home` unless
+    absolute. `titles`, when given, is the caller's memory between calls ({pane key: last title}, holding a pane only
+    while its title carries the Action Required prefix): the blink rule. One dict per container."""
+    proc_root = os.path.join(str(root), 'proc')
+    candidates = []
+    for key, row in _rows(panes):
+        has_title = 'pane_title' in row
+        title = row.get('pane_title')
+        parsed = parse_grok_title(title, titles.get(key) if titles is not None else None) if has_title else None
+        if titles is not None:
+            if _prefixed(title):
+                titles[key] = _clean_title(title)
+            else:
+                titles.pop(key, None)
+        if has_title and parsed is None and _command(row) != COMM and row.get('harness') != HARNESS:
+            continue
+        pid = _int(row.get('pane_pid'))
+        procs, complete = pane_grok_pids(proc_root, pid) if pid > 0 else ([], False)
+        candidates.append((key, row, parsed, procs, complete))
+    if not candidates:
+        return {}
+    pane_pids = {pid for *_head, procs, _complete in candidates for pid, flavour in procs if flavour != CLI_HARNESS}
+    grok = _GrokHome(root, home, grok_home, proc_root)
+    out = {}
+    try:
+        for key, row, parsed, procs, complete in candidates:
+            verdict = _observe(grok, row, parsed, procs, complete, pane_pids)
+            if verdict is not None:
+                out[key] = verdict
+    finally:
+        grok.close()
+    return out