@vibelord/lanes 1.5.0 → 1.6.0

package/payload/lanes/libexec/harness_muse.py

@@ -0,0 +1,531 @@
+"""Muse Code observer for agent{} (Lanes W13; spec
+docs/superpowers/specs/2026-10-16-lanes-harness-observers-muse-zcode-design.md §3). Pure reads through the container
+root statusd already holds (`/proc/<container init pid>/root`): no subprocess, no write, nothing done at import. Meta's
+terms forbid reverse engineering the binary: every fact below was read from the files and processes a normal run makes
+(`muse --provider echo` in a scratch HOME) or from the read-session skill Muse ships.
+
+Muse Code (Meta, `muse` 1.4.10-R6427.1) runs as ONE process: the launcher `~/.local/bin/muse` (a script) execs
+`~/.local/bin/muse-bin-<version>`, whose comm is the 15-byte cut `muse-bin-1.4.10` [M]. Per session it keeps:
+
+  * the event log `${XDG_DATA_HOME:-~/.local/share}/muse/sessions/YYYY/MM/DD/<session id>/session.jsonl` [D read-session
+    SKILL.md, M]: one JSON record per line, `recorded_at` in epoch MICROseconds, `payload_type` naming the record. The
+    records read here: `runtime.session` with `payload.kind` `run` and `payload.event.kind` `started` (a turn opens; its
+    `prompt` is the person's text — CUSTOMER CONTENT, never read into a verdict), the in-run kinds (model_*, assistant_*,
+    task_stream_linked, context_block_*, … and `payload.kind` `task` records), `terminal` with `terminal` completed |
+    failed | cancelled (the turn ends), `run_retracted` (a cancelled turn's prompt restored); `session.name.changed`
+    (`payload.new_name`, the session's name: automatic, two words such as `ash-megrez`, or the person's /rename);
+    `session.started`; and `session.end` when the process exits [M]. A `task failed` record also appears INSIDE a
+    completed turn (an internal task, MEASURED 2026-10-16): only the run's `terminal` says how a turn ended.
+  * `.session.lock` beside it, held OPEN by the live process (two fds) and holding `pid=<pid>\\nhost=<host>` [M]: the
+    pid <-> session join (`lock_session`, at most FD_MAX fd links read). Fallback: the live registry
+    `…/muse/runtime/muse/sessions/<session id>.json` {session_id, session_name, workspace_label,
+    process_generation_hint: "pid=<pid>", …}, deleted when the process exits [M] (`registry_session`).
+  * The pane title [M]: `⠙ <workspace basename>` (a braille spinner) while a turn runs, `<workspace basename>` between
+    turns, a single space when it exits. Muse rings NO bell [M], so nothing here (and nothing in agent_state.merge for a
+    Muse pane) turns a verdict into `done` by the bell.
+
+`muse_sessions(root, panes, home)` -> {pane key: verdict}, the dict `agent_state.merge` takes from a session file:
+{harness: 'muse', status, name, session_id, pid, since, source: 'muse-session-file', event}. `session_status` maps the
+log's tail (its last TAIL_BYTES, whole lines only): `started` -> working (since: the turn's start); in-run records ->
+working; `terminal` completed / cancelled -> needs_input, failed -> errored; `run_retracted` -> needs_input; no turn in
+a log read from its first byte -> idle; `session.end` -> no claim (the process exited; the title and the process walk
+decide). A log whose newest record and file are older than STALE makes no claim either.
+
+NOT measured (needs_operator_capture, DEF-2057): the records an approval leaves. Muse 1.4.10 runs in an Auto-review
+permission mode by default (its footer says so, and a session directory gains `approval-review/`); a turn that waits
+for the person was not captured. APPROVAL_ASKED / APPROVAL_ANSWERED are a conservative guess at the kind names that
+reads `needs_approval` only for a record whose kind says it, never for any other; the hooks' PermissionRequest /
+Notification (`lanes hooks install --agent muse`) are the primary approval signal.
+
+Every directory is opened without following a link (a container owns them), a FIFO is never opened blocking, and
+nothing larger than its bound is read.
+"""
+import json
+import os
+import re
+import stat
+import time
+
+HARNESS = 'muse'
+CONTAINER_HOME = '/home/coder'
+DATA_HOME = ('.local', 'share', 'muse')        # ${XDG_DATA_HOME:-~/.local/share}/muse, the default
+SESSIONS = 'sessions'
+REGISTRY = ('runtime', 'muse', 'sessions')     # under DATA_HOME: one <session id>.json per live process
+LOG = 'session.jsonl'
+LOCK = '.session.lock'
+SUBAGENT = 'subagent'                          # sessions/…/<id>/subagent/<child id>/ — a child's own log, never a pane's
+
+TAIL_BYTES = 64 << 10      # session.jsonl read from its end per pane per cycle (MEASURED: 113 KB after one echo turn)
+# The session's automatic name is written near the log's start (MEASURED over 13 echo sessions: at byte 13 440–21 730),
+# so after one turn it is no longer in the tail: when the tail names none, the first HEAD_BYTES are read for it.
+HEAD_BYTES = 32 << 10
+JSON_MAX = 64 << 10        # a registry file (MEASURED: 235 B)
+LOCK_MAX = 256             # .session.lock (MEASURED: 21 B, `pid=<pid>\nhost=<host>\n`)
+FD_MAX = 512               # fd links read per Muse process for the lock (MEASURED: 47 open fds)
+REGISTRY_MAX = 256         # registry files looked at per container per cycle
+DAY_DIRS = 31              # newest sessions/YYYY/MM/DD directories searched for a registry session id
+STALE = 3600               # seconds: an older session makes no claim
+NAME_MAX = 120
+
+SPINNER = frozenset('⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏')   # MEASURED in the title: ⠙ ⠸ ⠼ ⠦ ⠧ (the rest of the braille set Muse may draw)
+SHELL_TITLES = frozenset(('', 'bash', 'sh', 'zsh', 'fish'))
+SOURCE_FILE = 'muse-session-file'
+SOURCE_TITLE = 'muse-title'
+TERMINAL = {'completed': 'needs_input', 'cancelled': 'needs_input', 'failed': 'errored'}
+HOOK_KINDS = frozenset(('hook_run_started', 'hook_run_terminal'))   # a hook's run, before and after a turn: not a turn
+# The person's prompt accepted: the turn opens here, before its UserPromptSubmit hook and its `run started` (MEASURED:
+# 1 s apart with a 1 s hook). The record carries the prompt's text (customer content): only its type is read.
+INTENT = 'runtime.user_intent.accepted'
+# [U] needs_operator_capture (DEF-2057): no approval was captured; these read `needs_approval` only for a kind that
+# names an approval or permission being asked, and clear it on one that names the answer (or the turn's end).
+APPROVAL_ASKED = re.compile(r'(?:^|[._])(?:approval|permission)[._](?:requested|pending|required|prompted|prompt)\Z')
+APPROVAL_ANSWERED = re.compile(
+    r'(?:^|[._])(?:approval|permission)[._](?:resolved|granted|denied|decided|answered|approved|rejected)\Z')
+SESSION_ID = re.compile(r'[0-9A-Za-z][0-9A-Za-z_-]{7,127}\Z')
+DAY_PART = (re.compile(r'\d{4}\Z'), re.compile(r'\d{2}\Z'), re.compile(r'\d{2}\Z'))
+HINT = re.compile(r'pid=(\d+)\Z')
+LOCK_PID = re.compile(rb'(?m)^pid=(\d+)\s*$')
+
+_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)
+
+
+# ------------------------------------------------------------------------------------------------ pure parsers
+
+def parse_muse_title(title):
+    """A Muse pane title -> {'harness': 'muse', 'status', 'name'}, or None (no title, a shell's, the exit's single
+    space). `⠙ <workspace>` (a braille spinner, a space, the workspace's name) -> working; any other title -> idle, its
+    text the name. Called only for a pane whose OBSERVED harness is muse: Codex draws a spinner too."""
+    text = title.strip() if isinstance(title, str) else ''
+    if text in SHELL_TITLES:
+        return None
+    if text[0] in SPINNER and (len(text) == 1 or text[1] == ' '):
+        return {'harness': HARNESS, 'status': 'working', 'name': _printable(text[1:])}
+    return {'harness': HARNESS, 'status': 'idle', 'name': _printable(text)}
+
+
+def _printable(text):
+    if not isinstance(text, str):
+        return ''
+    return ''.join(ch for ch in text if ch.isprintable()).strip()[:NAME_MAX]
+
+
+def parse_records(lines):
+    """The record dicts of session.jsonl lines (bytes or str); a line that is not one JSON object is skipped."""
+    records = []
+    for line in lines:
+        try:
+            record = json.loads(line.decode('utf-8') if isinstance(line, bytes) else line)
+        except (UnicodeDecodeError, ValueError):
+            continue
+        if isinstance(record, dict):
+            records.append(record)
+    return records
+
+
+def _seconds(record):
+    """Epoch seconds of a record's `recorded_at` (epoch MICROseconds), or None."""
+    value = record.get('recorded_at')
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value <= 0:
+        return None
+    return int(value // 1_000_000)
+
+
+def _event(record):
+    """(payload kind, event kind) of a `runtime.session` record, else (None, None)."""
+    payload = record.get('payload')
+    if record.get('payload_type') != 'runtime.session' or not isinstance(payload, dict):
+        return None, None
+    event = payload.get('event')
+    kind = event.get('kind') if isinstance(event, dict) else None
+    return payload.get('kind'), (kind if isinstance(kind, str) else None)
+
+
+def session_status(records, whole=True):
+    """{'status', 'since', 'event', 'name', 'ended', 'activity'} of one session from its log's records in file order,
+    or None when they say nothing about a turn (the tail window holds none; the caller falls back to the title).
+
+    `ended`: the last session boundary is `session.end` (a later `session.started` clears it). `name`: the last
+    `session.name.changed` new_name. `activity`: the newest `recorded_at`, epoch seconds (None when no record has one).
+    The status — the last turn boundary wins: the prompt accepted (INTENT) or run `started` -> working (since: the
+    first of them); a run `terminal` by its
+    `terminal` (TERMINAL; an unknown word still ends the turn: needs_input); `run_retracted` -> needs_input. Inside a
+    turn, a record that names an approval being asked (APPROVAL_ASKED, needs_operator_capture) -> needs_approval until
+    one names its answer (APPROVAL_ANSWERED) or the turn ends; any other in-run record (`runtime.session` of kind `run`
+    or `task`, but not a hook's run, HOOK_KINDS) is working, and when the window starts mid-turn (no boundary seen, not
+    the whole file) it alone says working. No turn in a whole file: idle (a session nobody has asked anything yet).
+    Never reads `prompt` or any text of a record: only kinds, names and times."""
+    status = since = event = None
+    name, ended, activity = '', False, None
+    in_turn = None            # None: no turn boundary seen in this window
+    asking = False
+    for record in records:
+        at = _seconds(record)
+        if at is not None:
+            activity = at if activity is None else max(activity, at)
+        kind = record.get('payload_type')
+        payload = record.get('payload') if isinstance(record.get('payload'), dict) else {}
+        if kind == 'session.end':
+            ended = True
+            continue
+        if kind == 'session.started':
+            ended = False
+            continue
+        if kind == 'session.name.changed':
+            found = _printable(payload.get('new_name'))
+            if found:
+                name = found
+            continue
+        group, word = _event(record)
+        new = None
+        if kind == INTENT or (group == 'run' and word == 'started'):
+            if in_turn is not True:
+                asking = False
+            in_turn, new = True, ('needs_approval' if asking else 'working')
+        elif group == 'run' and word == 'terminal':
+            in_turn, asking = False, False
+            result = payload['event'].get('terminal')
+            new = TERMINAL.get(result, 'needs_input') if isinstance(result, str) else 'needs_input'
+        elif group == 'run' and word == 'run_retracted':
+            in_turn, asking, new = False, False, 'needs_input'
+        elif in_turn is False or (in_turn is None and whole):
+            continue          # between turns (a hook, a resource sample) or before the first: says nothing
+        elif word and APPROVAL_ASKED.search(word):
+            asking, new = True, 'needs_approval'
+        elif word and APPROVAL_ANSWERED.search(word):
+            asking, new = False, 'working'
+        elif group in ('run', 'task') and word not in HOOK_KINDS:
+            new = None if asking else 'working'
+        if new is None:
+            continue
+        if new != status:
+            since, event = at, (word or kind)
+        status = new
+    if status is None and whole:
+        status, event = 'idle', 'session.started'
+    if status is None:
+        return None if not (ended or name) else {'status': None, 'since': None, 'event': None, 'name': name,
+                                                 'ended': ended, 'activity': activity}
+    return {'status': status, 'since': since, 'event': event, 'name': name, 'ended': ended, 'activity': activity}
+
+
+def parse_registry(data):
+    """(session id, pid) of a runtime registry file's bytes, or None: `session_id` and `process_generation_hint`
+    `pid=<pid>` [M]."""
+    try:
+        doc = json.loads(data.decode('utf-8')) if data else None
+    except (UnicodeDecodeError, ValueError):
+        return None
+    if not isinstance(doc, dict):
+        return None
+    sid, hint = doc.get('session_id'), doc.get('process_generation_hint')
+    found = HINT.match(hint) if isinstance(hint, str) else None
+    if not isinstance(sid, str) or not SESSION_ID.match(sid) or not found:
+        return None
+    return sid, int(found.group(1))
+
+
+def lock_parts(link):
+    """The container path components of a session directory from an fd link to its `.session.lock`, or None: the
+    link must end `…/sessions/YYYY/MM/DD/<session id>/.session.lock` (a subagent's lock is not the pane's session)."""
+    if not isinstance(link, str) or not link.startswith('/') or not link.endswith('/' + LOCK):
+        return None
+    parts = [part for part in link.split('/') if part]
+    if len(parts) < 6 or not all(_leaf(part) for part in parts):
+        return None
+    day, sid = parts[-5:-2], parts[-2]
+    if parts[-6] != SESSIONS or not SESSION_ID.match(sid) or not all(p.match(d) for p, d in zip(DAY_PART, day)):
+        return None
+    return parts[:-1]
+
+
+# ------------------------------------------------------------------------------------------------ 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."""
+    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 _pread_all(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."""
+    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 = _pread_all(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=None):
+    """(lines, whole, mtime) — the complete lines in the last `limit` bytes of `name`, whether the window reached the
+    file's first byte, and the file's mtime — or None (absent, a link, a FIFO, unreadable). A first line cut by the
+    window and a last line still being written are dropped, never parsed."""
+    limit = TAIL_BYTES if limit is None else limit
+    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):
+            return None
+        size = info.st_size
+        start = max(0, size - limit)
+        if start:
+            data = _pread_all(fd, start - 1, size - start + 1)
+            if data[:1] == b'\n':
+                data = data[1:]
+            else:
+                cut = data.find(b'\n')
+                data = b'' if cut < 0 else data[cut + 1:]
+        else:
+            data = _pread_all(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, info.st_mtime
+
+
+def read_head_lines(dir_fd, name, limit=None):
+    """The complete lines in the first `limit` (default HEAD_BYTES) bytes of `name` (a last line cut by the window
+    dropped), or None."""
+    limit = HEAD_BYTES if limit is None else limit
+    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:
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            return None
+        data = _pread_all(fd, 0, limit)
+    except OSError:
+        return None
+    finally:
+        os.close(fd)
+    cut = data.rfind(b'\n')
+    return [line for line in data[:cut + 1].split(b'\n') if line.strip()] if cut >= 0 else []
+
+
+def head_name(lines):
+    """The last `session.name.changed` name among records (the head of a log), or ''."""
+    found = ''
+    for record in parse_records(lines or ()):
+        payload = record.get('payload')
+        if record.get('payload_type') == 'session.name.changed' and isinstance(payload, dict):
+            found = _printable(payload.get('new_name')) or found
+    return found
+
+
+def _proc_link(proc_root, pid, name):
+    try:
+        return os.readlink(os.path.join(proc_root, str(pid), name))
+    except OSError:
+        return None
+
+
+def lock_session(proc_root, pid, limit=None):
+    """The container path components of the session directory whose `.session.lock` process `pid` holds open (its fd
+    links, the lowest `limit` — default FD_MAX — read), or None."""
+    limit = FD_MAX if limit is None else limit
+    fd_dir = os.path.join(proc_root, str(int(pid)), 'fd')
+    try:
+        names = os.listdir(fd_dir)
+    except OSError:
+        return None
+    for name in sorted((n for n in names if n.isdigit()), key=int)[:limit]:
+        parts = lock_parts(_proc_link(proc_root, pid, os.path.join('fd', name)))
+        if parts:
+            return parts
+    return None
+
+
+def _lock_pid(session_fd):
+    """The pid `.session.lock` names, or None when it names none (an older Muse, an unreadable file)."""
+    data = read_regular_at(session_fd, LOCK, LOCK_MAX)
+    found = LOCK_PID.search(data) if data else None
+    return int(found.group(1)) if found else None
+
+
+# ------------------------------------------------------------------------------------------------ the observer
+
+class _MuseHome:
+    """One container's Muse data directory for one call: the root fd, the registry (read at most once)."""
+
+    def __init__(self, root, home):
+        self.root = str(root)
+        self.home = [part for part in str(home).split('/') if part]
+        self._registry = None
+
+    def _open(self, parts):
+        base = os.open(self.root, _DIR_FLAGS)
+        try:
+            return _open_dir_at(base, parts)
+        finally:
+            os.close(base)
+
+    def registry(self):
+        """{pid: session id} of the live registry's files (at most REGISTRY_MAX)."""
+        if self._registry is None:
+            self._registry = {}
+            try:
+                fd = self._open(self.home + list(DATA_HOME) + list(REGISTRY))
+            except OSError:
+                return self._registry
+            try:
+                names = sorted(n for n in os.listdir(fd) if n.endswith('.json'))[:REGISTRY_MAX]
+                for name in names:
+                    found = parse_registry(read_regular_at(fd, name, JSON_MAX))
+                    if found and found[1] not in self._registry:
+                        self._registry[found[1]] = found[0]
+            except OSError:
+                pass
+            finally:
+                os.close(fd)
+        return self._registry
+
+    def session_dir(self, parts):
+        try:
+            return self._open(parts)
+        except OSError:
+            return None
+
+    def find_session(self, session_id):
+        """A new fd of sessions/YYYY/MM/DD/<session id> in the default data directory (the newest DAY_DIRS days), or
+        None."""
+        try:
+            top = self._open(self.home + list(DATA_HOME) + [SESSIONS])
+        except OSError:
+            return None
+        try:
+            days = []
+            for year in sorted((n for n in os.listdir(top) if DAY_PART[0].match(n)), reverse=True):
+                for month in sorted((n for n in _listdir_at(top, (year,)) if DAY_PART[1].match(n)), reverse=True):
+                    for day in sorted((n for n in _listdir_at(top, (year, month)) if DAY_PART[2].match(n)),
+                                      reverse=True):
+                        days.append((year, month, day))
+                        if len(days) >= DAY_DIRS:
+                            break
+                    if len(days) >= DAY_DIRS:
+                        break
+                if len(days) >= DAY_DIRS:
+                    break
+            for day in days:
+                try:
+                    return _open_dir_at(top, day + (session_id,))
+                except OSError:
+                    continue
+        except OSError:
+            return None
+        finally:
+            os.close(top)
+        return None
+
+
+def _listdir_at(fd, parts):
+    try:
+        sub = _open_dir_at(fd, parts)
+    except OSError:
+        return []
+    try:
+        return os.listdir(sub)
+    except OSError:
+        return []
+    finally:
+        os.close(sub)
+
+
+def observe(muse, proc_root, pid, now):
+    """The verdict for one Muse process, or None (no session joined, none readable, stale, ended, or saying nothing)."""
+    parts = lock_session(proc_root, pid)
+    session_fd = muse.session_dir(parts) if parts else None
+    session_id = parts[-1] if parts else None
+    if session_fd is None:
+        session_id = muse.registry().get(int(pid))
+        session_fd = muse.find_session(session_id) if session_id else None
+    if session_fd is None:
+        return None
+    try:
+        holder = _lock_pid(session_fd)
+        if holder is not None and holder != int(pid):
+            return None                       # the lock names another process: not this pane's session
+        tail = read_tail_lines(session_fd, LOG)
+        found = session_status(parse_records(tail[0]), tail[1]) if tail is not None else None
+        if found is not None and not found['name'] and not tail[1]:
+            found['name'] = head_name(read_head_lines(session_fd, LOG))
+    finally:
+        os.close(session_fd)
+    if found is None or found['ended'] or found['status'] is None:
+        return None
+    mtime = tail[2]
+    activity = max(stamp for stamp in (found['activity'], mtime) if stamp is not None)
+    if now - activity > STALE:
+        return None
+    return {'harness': HARNESS, 'status': found['status'], 'name': found['name'], 'session_id': session_id,
+            'pid': int(pid), 'since': found['since'] or 0, 'source': SOURCE_FILE, 'event': found['event']}
+
+
+def muse_sessions(root, panes, *, home=CONTAINER_HOME, now=None):
+    """{pane key: verdict} for the panes Muse Code runs in. `root` is the container's root as the host sees it
+    (`/proc/<init pid>/root`; its /proc is `root/proc`, the container's pid namespace), `panes` {pane key: the pane's
+    Muse pid} (statusd: the panes whose harness walk found `muse`), `home` the container home whose default data
+    directory holds the registry. One read per pane: the process's fd links to its `.session.lock`, else the registry's
+    `process_generation_hint`; then the session log's tail."""
+    now = time.time() if now is None else now
+    proc_root = os.path.join(str(root), 'proc')
+    muse = _MuseHome(root, home)
+    out = {}
+    for key, pid in (panes or {}).items():
+        try:
+            pid = int(pid)
+        except (TypeError, ValueError):
+            continue
+        if pid <= 0:
+            continue
+        verdict = observe(muse, proc_root, pid, now)
+        if verdict is not None:
+            out[str(key)] = verdict
+    return out

package/payload/lanes/libexec/lanes_lib.py

@@ -1384,7 +1384,8 @@ def canonical_recipe(lane_id, ws, socket, session, folder, cmd='bash -l'):
     """The one create recipe that gives a new tmux lane its identity: LANE_ID / LANE_WS for scripts and hooks, the
     lanes/<ws>/<id> trace for Throttle (ANTHROPIC_CUSTOM_HEADERS for Claude Code, KIMI_CODE_CUSTOM_HEADERS for Kimi
     Code, which blanks the Anthropic one, LANES_TRACE for Grok Build's `env_http_headers`, THROTTLE_TRACE for the
-    rest) and GROK_HOME (Grok Build's home, never grok-cli's ~/.grok; W12). `tmux new -A` attaches when the session
+    rest, and (W13) MUSE_CUSTOM_HEADERS for Muse Code, measured but undocumented by Meta) and GROK_HOME (Grok Build's
+    home, never grok-cli's ~/.grok; W12). `tmux new -A` attaches when the session
     already exists, so the env lands only on a real create — never through `set-environment`, which would leak into
     unrelated windows. `cmd` is a shell command string, appended as is."""
     trace = lane_trace(lane_id, ws)
@@ -1400,7 +1401,7 @@ def canonical_recipe(lane_id, ws, socket, session, folder, cmd='bash -l'):
     return (f'tmux -L {shlex.quote(socket)} new -ADs {shlex.quote(session)} -c {shlex.quote(folder)} '
             f'-e LANE_ID={lane_id} -e LANE_WS={ws} -e ANTHROPIC_CUSTOM_HEADERS={header} '
             f'-e THROTTLE_TRACE={trace} -e KIMI_CODE_CUSTOM_HEADERS={header} -e LANES_TRACE={trace} '
-            f'-e GROK_HOME={CONTAINER_HOME}/.grok-build {cmd}')
+            f'-e GROK_HOME={CONTAINER_HOME}/.grok-build -e MUSE_CUSTOM_HEADERS={header} {cmd}')
 
 
 # What `lane open` gets when it runs a lane's recorded `create` for a lane that does not exist (plan Task 18; the

package/payload/lanes/libexec/sidebar.py

@@ -312,21 +312,24 @@ def load_economy(doc):
 # Pinned above the upload strip: Throttle in one line, an availability bar per provider, the host and its top
 # containers — from status.json's `fleet` and `throttle` objects ONLY (statusd publishes both, spec §2.1/§2.2), so the
 # block costs no stat, read or fork of the sidebar's own on a tick. A pane of FLEET_FULL rows or more draws a rule and
-# six rows (W12 added the Kimi row: FLEET_FULL 24 -> 25, so the body a full block leaves keeps its W11 floor), one of
+# six rows (W12 added the Kimi row: FLEET_FULL 24 -> 25, so the body a full block leaves keeps its W11 floor; W13 the
+# Muse Code and Z.ai rows: eight rows, FLEET_FULL 25 -> 27), one of
 # FLEET_SHORT..FLEET_FULL − 1 rows three (Throttle, the worse provider, the host), a shorter one none; `i` folds it to
 # one line (`look.fleet_collapsed` in the owner's profile). The lane list scrolls in the rest.
 FLEET_SCHEMA = 1                # the `v` of both objects this reader understands (absent = 1; another is ignored)
-FLEET_FULL, FLEET_SHORT = 25, 18
+FLEET_FULL, FLEET_SHORT = 27, 18
 # Own-clock floors beneath the publishers' `stale` flags (DEF-1528's rule, as ECONOMY_STALE): statusd writes `fleet`
 # every 10 s (a 12 s cycle at its slowest) and the pulse `throttle.at` at least every 60 s, which statusd flags past
 # 60 s; a status.json that stopped changing (statusd frozen) still turns the block stale here.
 FLEET_STALE_S, PULSE_STALE_S = 60, 90
 BAR_CELLS = 10
 # The pulse's pools, in row order, and the row's word: the vendor (W12, spec 2026-10-15 §6: Kimi Code's pool is
-# `kimi`, its vendor Moonshot AI). No grok row until Throttle has an xAI pool (the 2026-10-14 xAI pool review's gates).
-PROVIDERS = (('claude', 'anthropic'), ('codex', 'openai'), ('kimi', 'moonshot'))
-# The pools whose overflow is money (fleet_money): Kimi has no paid overflow lane, so a kimi figure is never shown —
-# the pulse records it as nulls (throttle-pulse MONEY_POOLS), and this reader would not show one if it did not.
+# `kimi`, its vendor Moonshot AI; W13: Throttle's native `muse-code` pool, vendor Meta, and `zai`, vendor Z.ai). No grok
+# row until Throttle has an xAI pool (the 2026-10-14 xAI pool review's gates).
+PROVIDERS = (('claude', 'anthropic'), ('codex', 'openai'), ('kimi', 'moonshot'), ('muse-code', 'meta'),
+             ('zai', 'z.ai'))
+# The pools whose overflow is money (fleet_money): Kimi, Muse Code and Z.ai have no paid overflow lane, so their figure is
+# never shown — the pulse records it as nulls (throttle-pulse MONEY_POOLS), and this reader would not show one if it did not.
 MONEY_POOLS = ('claude', 'codex')
 LABEL_CELLS = 9                 # the label field of the Throttle and provider rows (`anthropic`), then one blank
 # `429 +N`: how much the pools' upstream_429_total grew over the last SURGE_S seconds of pulse samples this sidebar

package/payload/lanes/libexec/statusd.py

@@ -97,7 +97,8 @@ PULSE_REARM_TIMEOUT = 10
 DAEMON_REFRESH = 300    # site.conf is re-read this often for LANES_THROTTLE_CONTAINER (CONTAINER_REFRESH)
 PULSE_BIN = ('home', 'coder', '.lz', 'bin')
 PULSE_PROGRAM = 'throttle-pulse'
-PULSE_POOLS = ('claude', 'codex', 'kimi')   # throttle-pulse POOLS (W12 adds kimi; its overflow is always null)
+# throttle-pulse POOLS (W12 adds kimi, W13 muse-code and zai; their overflow is always null)
+PULSE_POOLS = ('claude', 'codex', 'kimi', 'muse-code', 'zai')
 PULSE_COUNTS = ('configured', 'usable', 'cooling', 'exhausted', 'benched', 'auth_failed')
 PULSE_OVERFLOW = ('spend_today_usd', 'budget_usd', 'fraction', 'alert_level_pct')
 PULSE_PHASE = re.compile(r'[a-z][a-z0-9_-]{0,31}\Z', re.ASCII)
@@ -348,14 +349,15 @@ def agent_signals(containers, sessions_by_server, now=None):
     """The per-container inputs `agent_state.merge` needs, read ONCE per container per cycle through the
     container's root as the host sees it (`/proc/<init pid>/root`), so liveness is judged in the container's pid
     namespace and nothing is spawned. -> {container: {'claude': claude_by_pane, 'kimi': kimi_by_pane,
-    'grok': grok_by_pane}}.
+    'grok': grok_by_pane, 'muse': muse_by_pane}}.
 
     Sets `harness` (and `harness_pid` when one was found) on every session row whose harness could be observed, in
     place (W12, spec §2: `agent_state.HarnessCache` over `harness_walk` — the pane's process tree in the container's
     /proc); the Kimi Code observer (`agent_state.kimi_sessions`) reads only for the panes found running `kimi`, and the
     Grok Build observer (`agent_state.grok_sessions` -> `harness_grok.grok_sessions`) gets the ROWS of the panes found
     running `grok`, ending in a bare shell, or running a grok whose exe could not be read (GROK_OBSERVED), with the
-    container's GROK_TITLES memory.
+    container's GROK_TITLES memory. W13: the Muse Code observer (`agent_state.muse_sessions` ->
+    `harness_muse.muse_sessions`) reads only for the panes found running `muse`, by their Muse pid.
 
     Also sets `pane_has_child` on the session rows that need it, in place: only a pane whose title Codex wrote
     (`parse_codex_title`, gated by the observed harness) over a bare-shell foreground can be a harness that ended into
@@ -378,10 +380,10 @@ def agent_signals(containers, sessions_by_server, now=None):
         except Exception as error:
             log(f'agents {container}', error)
             claude = {}
-        signals[container] = mine = {'claude': claude, 'kimi': {}, 'grok': {}}
+        signals[container] = mine = {'claude': claude, 'kimi': {}, 'grok': {}, 'muse': {}}
         panes = [pane for (owner, _socket), sessions in sessions_by_server.items() if owner == container
                  for pane in sessions.values() if str(pane.get('pane_pid') or '').isdigit()]
-        observers = {'kimi': {}, 'grok': {}}
+        observers = {'kimi': {}, 'grok': {}, 'muse': {}}
         for pane in panes:
             try:
                 harness, harness_pid = HARNESS_CACHE.harness(root / 'proc', int(pane['pane_pid']))
@@ -396,6 +398,8 @@ def agent_signals(containers, sessions_by_server, now=None):
                 pane['harness_pid'] = harness_pid
             if harness == 'kimi' and harness_pid:
                 observers['kimi'][AS.pane_key(pane)] = harness_pid
+            elif harness == 'muse' and harness_pid:
+                observers['muse'][AS.pane_key(pane)] = harness_pid
             elif harness in GROK_OBSERVED or (harness == 'unknown' and harness_pid):
                 observers['grok'][AS.pane_key(pane)] = pane
         if observers['kimi']:
@@ -403,6 +407,11 @@ def agent_signals(containers, sessions_by_server, now=None):
                 mine['kimi'] = AS.kimi_sessions(root, observers['kimi'], now, home)
             except Exception as error:
                 log(f'kimi {container}', error)
+        if observers['muse']:
+            try:
+                mine['muse'] = AS.muse_sessions(root, observers['muse'], home=L.CONTAINER_HOME, now=now)
+            except Exception as error:
+                log(f'muse {container}', error)
         if observers['grok']:
             titles = GROK_TITLES.setdefault(str(root), {})
             titled.add(str(root))
@@ -435,7 +444,8 @@ def agent_signals(containers, sessions_by_server, now=None):
 
 def merged(pane, signals, sidecar):
     """`agent_state.merge` of one pane over its container's `agent_signals` and its lane's hook sidecar."""
-    return AS.merge(pane, signals.get('claude', {}), sidecar, signals.get('kimi', {}), signals.get('grok', {}))
+    return AS.merge(pane, signals.get('claude', {}), sidecar, signals.get('kimi', {}), signals.get('grok', {}),
+                    signals.get('muse', {}))
 
 
 SIDECAR_MAX_AGE = 3600   # a hook sidecar whose last event is older than this loses to the live signals