okstra 0.160.0 → 0.161.0

package/docs/architecture.md

@@ -147,6 +147,7 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
 
 - [`prompts/lead/okstra-lead-contract.md`](../prompts/lead/okstra-lead-contract.md) is the runtime-neutral lifecycle core: phase boundaries, artifacts, convergence, report ownership, and persistence semantics.
 - `prompts/lead/adapters/claude-code.md`, `prompts/lead/adapters/codex.md`, `prompts/lead/adapters/antigravity.md`, and `prompts/lead/adapters/external.md` map the same semantic operations to one selected host runtime. The generated launch prompt exposes the core path plus exactly one adapter path.
+- `prompts/lead/adapters/cmux.md` is selected by environment rather than by runtime: when the run manifest's `terminalBackend` is `cmux-pane`, every lead runtime resolves to it and dispatches through `okstra team`, because okstra owns the worker panes on that path instead of the host. It overrides only the adapter and the dispatch mode; the lead's agent, role, and session accounting still come from its own runtime.
 - Runtime metadata and role assignments are persisted separately, but the lead provider is derived from the host: Claude Code maps to Claude, Codex maps to Codex, and Antigravity CLI maps to Antigravity. New runs persist `hostRuntime`, `leadAssignment`, and `workerAssignments[]`; each assignment records its provider, model, execution value, and resolved `native-session` or `cli-wrapper` runner. `lead-execution-prompt.md` is canonical, while `claude-execution-prompt.md` is a byte-identical compatibility alias for historical consumers.
 - Provider registry and front-door separation are implemented: the active Claude Code, Codex, or Antigravity host owns the native lead session, while non-host providers run through their registered CLI wrappers.
 - [`skills/okstra-setup/SKILL.md`](../skills/okstra-setup/SKILL.md) — **first-run bootstrap**. Runs `okstra install` and creates `project.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.160.0",
+  "version": "0.161.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.160.0",
-  "builtAt": "2026-08-08T09:56:46.059Z",
+  "package": "0.161.0",
+  "builtAt": "2026-08-08T16:14:31.788Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/lead/adapters/cmux.md

@@ -0,0 +1,67 @@
+# cmux Lead Runtime Adapter
+
+## Scope
+
+This adapter maps the neutral Okstra lead operations to a cmux session, where Okstra owns the worker panes regardless of which model is leading. Read it only when the rendered launch prompt selects it; the run manifest's `terminalBackend` is `cmux-pane` for exactly those runs.
+
+It replaces the per-runtime adapter, not the lead contract. Your own runtime still decides how you read files, ask the user, and record your session — this file only decides how workers are started, awaited, and reclaimed.
+
+## Capability declaration
+
+| Field | Value |
+|---|---|
+| `runtime` | environment-selected — any lead runtime resolves to this adapter under cmux |
+| `leadRoleLabel` | `Okstra lead` |
+| `userPromptMode` | `host-text` |
+| `workerDispatchBackend` | `cmux-pane` |
+| `initialPromptDeliveryMode` | `lazy-path-reference` |
+| `sessionAccounting` | unchanged — keep your own runtime's accounting |
+| `resumeMode` | `artifact-checkpoint` |
+| `teardownMode` | `pane-teardown` |
+| `leadEventSource` | `lead-events-jsonl` |
+
+## Semantic operation mapping
+
+| Operation | Mapping |
+|---|---|
+| `read_artifacts` | Read the manifest-provided paths through the current host's file or shell interface. |
+| `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
+| `prompt_user` | Ask through the host text/question interface and require an explicit approval or clarification response. |
+| `dispatch_worker` | Run `okstra team dispatch --project-root <root> --run-manifest <path>`; use `--dry-run` first when the core requires a dispatch preview. |
+| `await_workers` | Run `okstra team await --project-root <root> --run-manifest <path>` through the host's asynchronous shell facility. |
+| `redispatch_worker` | Create the core-specified fresh jobs file and dispatch it with a new `dispatchKind`; never reuse a live worker conversation. |
+| `shutdown_workers` | Run `okstra team teardown --project-root <root> --run-manifest <path>` only after the user-approved cleanup gate. |
+| `record_lead_event` | Append the required structured event to the manifest-provided `leadEventsPath`; emit the matching user-facing `PROGRESS:` line. |
+| `collect_usage` | Collect artifact/CLI-log-backed usage through the existing Okstra token-usage path; never substitute another runtime's session log. |
+
+## Pane placement is not yours to compute
+
+Okstra creates, sizes, labels, and closes every worker pane. Do not issue terminal-multiplexer commands of any kind — not to place a worker, not to resize the lead, not to reclaim a finished round. Pane geometry depends on the display, and a lead that recomputes it per run gets it wrong differently on every host.
+
+Concretely: you never choose a split direction, a pane width, a surface id, or a title. `okstra team dispatch` does all of it and records what it created.
+
+## Watching a worker is not the same as judging it
+
+Workers run beside you, so you can read their screens. That is a diagnostic channel and nothing more.
+
+- A worker is finished when its dispatch record reaches a terminal status and its required Result Paths exist. Nothing you see on a screen changes that verdict.
+- Never parse a pane's contents into a result. Terminal output is a rendered grid — wrapped to the pane's width, with history truncated — so a path or a number read off it may be silently incomplete.
+- Never send input to a running worker. Workers are one-shot sessions whose prompt is already delivered; retries and re-verification always create a fresh session, and interrupting a live worker contaminates exactly the context that rule protects.
+
+Use the screen to tell "still working" from "stuck", and to see at a glance which worker failed. Use the artifacts for everything else.
+
+## cmux dispatch details
+
+- For convergence reverify, consume the persisted round plan exactly. This adapter may map and transport each returned batch, but it cannot change batch membership and does not classify findings or branch on task type, provider, or model identity.
+- Do not invoke Claude Code team tools or `okstra codex-dispatch`. Under cmux every lead dispatches through `okstra team`, including a Claude Code lead.
+- Worker completion is valid only from `workerDispatches[]`, terminal status sidecars, and required Result Paths. Pane creation alone is not completion.
+- Reverify uses a fresh jobs file at `runs/<task-type>/state/reverify-jobs-r<N>-<task-type>-<seq>.json`, sets `dispatchKind: "reverify-r<N>"`, and dispatches with `okstra team dispatch --project-root <root> --run-manifest <path> --dispatch-kind reverify-r<N> --jobs-file <jobs-file>`.
+- Report-writer uses a fresh one-job jobs file with `dispatchKind: "report-writer"` and the same schema, then dispatches through `okstra team dispatch --project-root <root> --run-manifest <path> --jobs-file <jobs-file>`.
+- Every reverify or report-writer jobs file carries `workerId`, `provider`, `role`, `modelExecutionValue`, `promptPath`, `resultPath`, `workerResultPath`, and `completionPaths`. For reverify, set `role` to `worker-reverify-r<N>` for the pane title. The report-writer completion paths include both data.json and the worker-results audit file.
+- After either dispatch, run `okstra team await --project-root <root> --run-manifest <path>` before evaluating terminal status or completion paths.
+
+## Completion, cleanup, and resume
+
+- Await through `okstra team await`; raw Result Path polling is forbidden for this backend.
+- Reclaim each round's panes at the round boundary through `okstra team teardown`, before the next round's dispatch. Finished workers leave their panes behind on purpose — the screen survives the process so you can still read a failure — so an unreclaimed round keeps shrinking the space the next one gets.
+- Resume from run artifacts and lead-events checkpoints. After usage collection, persistence, and the core user-approval gate, run `okstra team teardown --project-root <root> --run-manifest <path>` and tear down only Okstra-owned panes recorded for the run.

package/runtime/python/okstra_ctl/cmux.py

@@ -0,0 +1,531 @@
+"""cmux command helpers for okstra-owned worker surfaces.
+
+The tmux sibling of this module is `tmux.py`. cmux is a GUI app, so there is no
+detached-server equivalent here — every surface okstra creates lands in the
+workspace the user is already looking at.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Sequence
+
+PING_OK = "PONG"
+
+# cmux answers over a local unix socket, so a probe that has not returned in a
+# few seconds means the app is wedged or gone — not that it is being slow.
+PROBE_TIMEOUT_SECONDS = 5
+
+# A login shell sources the user's whole rc chain, which can be slow on a
+# developer machine, so this gets far more room than a socket probe.
+LOGIN_SHELL_TIMEOUT_SECONDS = 15
+
+# cmux plants a per-surface directory of CLI shims on PATH; every entry under it
+# re-enters cmux's own agent wrapper instead of the real CLI.
+SHIM_DIR_MARKER = "cmux-cli-shims"
+
+# Workers fill two columns and then grow downward. A third column would cost
+# width, and width is the dimension a horizontal split cannot give back.
+GRID_COLUMNS = 2
+
+# Measured against a Claude Code worker: 67 columns renders losslessly, 33 drops
+# content off the right edge. Below this floor okstra stacks a tab instead of
+# splitting, because an unreadable pane costs the lead its view of that worker.
+WORKER_MIN_COLUMNS = 60
+
+# What the lead keeps for itself once workers arrive.
+LEAD_TARGET_COLUMNS = 80
+
+# Sidebar entries are keyed by source so tools do not overwrite each other's.
+SIDEBAR_SOURCE = "okstra"
+
+
+def cmux_cli_path() -> str:
+    """Absolute path to the cmux CLI, or "" when cmux is not installed.
+
+    The bundled CLI wins over PATH: cmux documents the /usr/local/bin/cmux
+    symlink as a manual step, so a working install may leave PATH untouched.
+    """
+    bundled = os.environ.get("CMUX_BUNDLED_CLI_PATH", "")
+    if bundled and os.access(bundled, os.X_OK):
+        return bundled
+    return shutil.which("cmux") or ""
+
+
+def run_cmux(
+    args: Sequence[str], *, timeout: int = PROBE_TIMEOUT_SECONDS
+) -> subprocess.CompletedProcess[str]:
+    cli = cmux_cli_path()
+    if not cli:
+        raise FileNotFoundError(
+            "cmux CLI not found: CMUX_BUNDLED_CLI_PATH unset and no cmux on PATH"
+        )
+    return subprocess.run(
+        [cli, *args],
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        check=False,
+    )
+
+
+def cmux_available() -> bool:
+    """True only when okstra can drive cmux *and* knows where the lead sits.
+
+    Being able to drive cmux is not sufficient. Workers attach to the lead's
+    workspace, so a run whose lead location is unresolvable would open panes on
+    a screen nobody is watching; degrading to the blocking wrapper is the better
+    failure. Nested tmux is exactly that case — see `resolve_lead_workspace`.
+    """
+    if not cmux_cli_path():
+        return False
+    # Cheapest discriminator first: no workspace in the environment means this
+    # is not a cmux-hosted session, and the probes below would only confirm that
+    # the app happens to be installed.
+    if not _lead_workspace_env():
+        return False
+    if not _ping_answers():
+        return False
+    return bool(resolve_lead_workspace())
+
+
+def resolve_lead_workspace() -> str:
+    """The lead's workspace UUID, or "" when it cannot be resolved.
+
+    The UUID is read from the environment rather than from `identify`, whose
+    refs are positional and shift as surfaces open and close. `identify` is
+    consulted only to prove the environment is current: a tmux server freezes
+    the CMUX_* block it was launched with, so those variables can outlive the
+    surface they name.
+    """
+    workspace = _lead_workspace_env()
+    if not workspace:
+        return ""
+    if not identify_caller():
+        return ""
+    return workspace
+
+
+def _lead_workspace_env() -> str:
+    return os.environ.get("CMUX_WORKSPACE_ID", "").strip()
+
+
+@dataclass(frozen=True)
+class PaneGeometry:
+    """One pane as `pane.list` reports it.
+
+    `columns` and `rows` come straight from cmux rather than being derived from
+    the container frame, so a display with a different cell size needs no
+    conversion here.
+    """
+
+    pane_id: str
+    surface_ids: tuple[str, ...]
+    columns: int
+    rows: int
+    x: int
+    y: int
+    cell_width_points: int
+    ref: str = ""
+    selected_surface_id: str = ""
+
+
+@dataclass(frozen=True)
+class Placement:
+    """Where the next worker goes: split `pane_id`, or stack a tab into it."""
+
+    pane_id: str
+    direction: str
+    stack_as_tab: bool
+
+
+def plan_worker_placement(
+    panes: Sequence[PaneGeometry], *, lead_pane_id: str, min_columns: int
+) -> Placement:
+    """Pick the next worker slot from the workspace's current geometry.
+
+    Stateless by design: okstra records surface UUIDs, never a layout, so a
+    resumed or crashed run cannot carry a layout model that no longer matches
+    the screen. Every dispatch re-reads the panes and derives the next slot.
+    """
+    workers = [pane for pane in panes if pane.pane_id != lead_pane_id]
+    if not workers:
+        return Placement(pane_id=lead_pane_id, direction="right", stack_as_tab=False)
+
+    columns = _panes_by_column(workers)
+    if len(columns) < GRID_COLUMNS:
+        return _widen_the_grid(workers, min_columns=min_columns)
+    return _extend_the_shortest_column(columns)
+
+
+def lead_shrink_points(lead: PaneGeometry, *, target_columns: int) -> int:
+    """How far to push the lead's right border, in the points `pane.resize` takes.
+
+    The API's `amount` is points, not cells — measured at this pane's own
+    `cell_width_points`, so passing a column count shrinks by an eighth of the
+    intent on a typical display.
+    """
+    surplus = lead.columns - target_columns
+    if surplus <= 0:
+        return 0
+    return surplus * lead.cell_width_points
+
+
+def _widen_the_grid(
+    workers: Sequence[PaneGeometry], *, min_columns: int
+) -> Placement:
+    rightmost = max(workers, key=lambda pane: pane.x)
+    if rightmost.columns // GRID_COLUMNS >= min_columns:
+        return Placement(pane_id=rightmost.pane_id, direction="right", stack_as_tab=False)
+    roomiest = min(workers, key=lambda pane: (len(pane.surface_ids), pane.x))
+    return Placement(pane_id=roomiest.pane_id, direction="", stack_as_tab=True)
+
+
+def _extend_the_shortest_column(
+    columns: dict[int, list[PaneGeometry]]
+) -> Placement:
+    shortest = min(columns.values(), key=lambda group: (len(group), group[0].x))
+    bottom = max(shortest, key=lambda pane: pane.y)
+    return Placement(pane_id=bottom.pane_id, direction="down", stack_as_tab=False)
+
+
+def _panes_by_column(
+    workers: Sequence[PaneGeometry],
+) -> dict[int, list[PaneGeometry]]:
+    columns: dict[int, list[PaneGeometry]] = {}
+    for pane in workers:
+        columns.setdefault(pane.x, []).append(pane)
+    return columns
+
+
+def shim_free_login_path() -> str:
+    """The user's login PATH with cmux's per-surface CLI shims removed.
+
+    A cmux pane execs its command through `login … bash --noprofile --norc`, so
+    none of the user's shell rc runs and PATH is cmux's own short list. What that
+    list does hold is a shim directory bound to the new surface, where `claude`
+    and `codex` are wrappers into cmux's agent lifecycle rather than the real
+    CLIs — and where a provider cmux does not know has no entry at all, which is
+    a plain exit 127 inside the worker wrapper.
+
+    Restoring the login shell's PATH and dropping the shim entries gives the
+    wrapper what it would see in an ordinary terminal, which is what its own
+    `command -v <cli>` check expects. Nothing here is provider-specific, so
+    adding a provider does not touch this path.
+    """
+    entries = _login_shell_path().split(os.pathsep)
+    return os.pathsep.join(
+        entry for entry in entries if entry and SHIM_DIR_MARKER not in entry
+    )
+
+
+def worker_command_line(
+    *, cwd: Path, argv: Sequence[str], path_value: str
+) -> str:
+    """The single shell line a cmux pane execs to run one worker.
+
+    Every part is shell-quoted. PATH entries routinely contain spaces — macOS
+    ships `/Applications/VMware Fusion.app/Contents/Public` on any machine with
+    VMware — and an unquoted assignment stops at the first space, then hands the
+    remainder to the shell as a command name.
+
+    The `cd` is part of the command because neither `new-split` nor
+    `respawn-pane` accepts a working directory the way `tmux split-window -c`
+    does.
+    """
+    return (
+        f"cd {shlex.quote(str(cwd))} && "
+        f"PATH={shlex.quote(path_value)} exec {shlex.join(argv)}"
+    )
+
+
+def list_panes(workspace: str) -> list[PaneGeometry]:
+    payload = rpc("pane.list", {"workspace_id": workspace})
+    return [_pane_geometry(entry) for entry in payload.get("panes", [])]
+
+
+def spawn_worker_surface(
+    *, workspace: str, cwd: Path, command: Sequence[str], title: str
+) -> str:
+    """Start one worker beside the lead and return its surface UUID.
+
+    The UUID is what okstra records and later closes by. Positional refs cannot
+    serve that purpose: cmux renumbers them as surfaces open and close, so a
+    close by ref can land on a pane okstra never created.
+    """
+    panes = list_panes(workspace)
+    lead = _lead_pane(panes)
+    placement = plan_worker_placement(
+        panes, lead_pane_id=lead.pane_id, min_columns=WORKER_MIN_COLUMNS
+    )
+    target = _pane_by_id(panes, placement.pane_id)
+    surface_uuid = _open_worker_surface(workspace, placement, target)
+    run_cmux(["rename-tab", "--surface", surface_uuid, "--title", title])
+    _exec_worker(surface_uuid, cwd=cwd, command=command)
+    _shrink_lead_pane(workspace)
+    return surface_uuid
+
+
+def close_surface(surface_uuid: str) -> None:
+    """Close an okstra-created surface, killing whatever still runs inside it."""
+    try:
+        run_cmux(["close-surface", "--surface", surface_uuid])
+    except (OSError, subprocess.SubprocessError):
+        return
+
+
+def capture_surface(surface_uuid: str, *, last_lines: int = 200) -> str:
+    """What the worker's screen shows — for the lead to look at, never to parse.
+
+    cmux hands back a rendered grid: wrapped to the pane's width with a finite
+    history, so a path or a count read off it can be silently truncated.
+    """
+    try:
+        result = run_cmux(
+            [
+                "capture-pane",
+                "--surface",
+                surface_uuid,
+                "--scrollback",
+                "--lines",
+                str(last_lines),
+            ]
+        )
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    return result.stdout if result.returncode == 0 else ""
+
+
+def sidebar_log(workspace: str, message: str, *, level: str = "info") -> None:
+    """Append one line to the workspace sidebar's log."""
+    _sidebar_call(
+        workspace,
+        ["log", "--workspace", workspace, "--level", level,
+         "--source", SIDEBAR_SOURCE, "--", message],
+    )
+
+
+def sidebar_notify(workspace: str, *, title: str, body: str) -> None:
+    """Raise a notification, which badges the tab even from another workspace."""
+    _sidebar_call(
+        workspace,
+        ["notify", "--workspace", workspace, "--title", title, "--body", body],
+    )
+
+
+def sidebar_progress(workspace: str, done: int, total: int, *, label: str) -> None:
+    """Show `done`/`total` as the sidebar's progress bar.
+
+    An empty roster reports nothing rather than zero percent: no workers is not
+    the same claim as no progress.
+    """
+    if total <= 0:
+        return
+    fraction = min(1.0, done / total)
+    _sidebar_call(
+        workspace,
+        ["set-progress", str(round(fraction, 2)), "--workspace", workspace,
+         "--label", label],
+    )
+
+
+def _sidebar_call(workspace: str, args: Sequence[str]) -> None:
+    """Best-effort sidebar write.
+
+    The sidebar is a view of the run, not part of it, so a wedged or closed cmux
+    must never take a dispatch down. The workspace is always explicit: letting
+    cmux choose would drop one run's noise into whichever workspace happens to
+    be focused, which on a machine running two okstra tasks is the other one.
+    """
+    if not workspace:
+        return
+    try:
+        run_cmux(args)
+    except (OSError, subprocess.SubprocessError):
+        return
+
+
+def rpc(method: str, params: dict[str, Any]) -> dict[str, Any]:
+    """Call a cmux rpc method.
+
+    The rpc surface is used rather than the same-named CLI verbs wherever both
+    exist, because the CLI swallows failures — `resize-pane` reports success on
+    a rejected resize, while `pane.resize` returns the reason.
+    """
+    result = run_cmux(["rpc", method, json.dumps(params)])
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or f"cmux {method} failed")
+    try:
+        payload = json.loads(result.stdout)
+    except ValueError as exc:
+        raise RuntimeError(f"cmux {method} returned non-JSON output") from exc
+    return payload if isinstance(payload, dict) else {}
+
+
+def _open_worker_surface(
+    workspace: str, placement: Placement, target: PaneGeometry
+) -> str:
+    before = _surface_ids(workspace)
+    _create_surface(workspace, placement, target)
+    new_ids = _surface_ids(workspace) - before
+    if len(new_ids) != 1:
+        raise RuntimeError(
+            f"cmux opened {len(new_ids)} surfaces where exactly one was expected"
+        )
+    return new_ids.pop()
+
+
+def _surface_ids(workspace: str) -> set[str]:
+    """Every surface UUID in the workspace.
+
+    The new surface is identified by diffing this set rather than by translating
+    the `OK surface:N` echo, because `list-pane-surfaces` reports only the
+    focused pane unless given a `--pane`, and the new pane is not focused.
+    """
+    return {
+        surface_id
+        for pane in list_panes(workspace)
+        for surface_id in pane.surface_ids
+    }
+
+
+def _create_surface(
+    workspace: str, placement: Placement, target: PaneGeometry
+) -> None:
+    if placement.stack_as_tab:
+        created = run_cmux(
+            ["new-surface", "--workspace", workspace, "--pane", target.pane_id]
+        )
+    else:
+        created = run_cmux(
+            [
+                "new-split",
+                placement.direction,
+                "--workspace",
+                workspace,
+                "--surface",
+                target.selected_surface_id or target.surface_ids[0],
+            ]
+        )
+    if created.returncode != 0:
+        raise RuntimeError(created.stderr.strip() or "cmux could not open a pane")
+
+
+def _exec_worker(surface_uuid: str, *, cwd: Path, command: Sequence[str]) -> None:
+    line = worker_command_line(
+        cwd=cwd, argv=command, path_value=shim_free_login_path()
+    )
+    started = run_cmux(["respawn-pane", "--surface", surface_uuid, "--command", line])
+    if started.returncode != 0:
+        raise RuntimeError(started.stderr.strip() or "cmux could not start the worker")
+
+
+def _shrink_lead_pane(workspace: str) -> None:
+    """Give the lead's width to the workers by pushing its right border left.
+
+    The lead cannot shrink itself: `pane.resize` moves the named pane's border,
+    so asking the leftmost pane to move `left` fails with no adjacent border and
+    `right` widens it. The neighbour on its right carries the request instead.
+    """
+    panes = list_panes(workspace)
+    lead = _lead_pane(panes)
+    amount = lead_shrink_points(lead, target_columns=LEAD_TARGET_COLUMNS)
+    if amount <= 0:
+        return
+    neighbours = [pane for pane in panes if pane.x > lead.x]
+    if not neighbours:
+        return
+    rpc(
+        "pane.resize",
+        {
+            "workspace_id": workspace,
+            "pane_id": min(neighbours, key=lambda pane: pane.x).pane_id,
+            "direction": "left",
+            "amount": amount,
+        },
+    )
+
+
+def _lead_pane(panes: Sequence[PaneGeometry]) -> PaneGeometry:
+    caller_pane_ref = identify_caller().get("pane_ref", "")
+    for pane in panes:
+        if caller_pane_ref and pane.ref == caller_pane_ref:
+            return pane
+    raise RuntimeError("cmux could not locate the lead's pane in its workspace")
+
+
+def _pane_by_id(panes: Sequence[PaneGeometry], pane_id: str) -> PaneGeometry:
+    for pane in panes:
+        if pane.pane_id == pane_id:
+            return pane
+    raise RuntimeError(f"cmux pane {pane_id} disappeared while placing a worker")
+
+
+def _pane_geometry(entry: dict[str, Any]) -> PaneGeometry:
+    frame = entry.get("pixel_frame") or {}
+    return PaneGeometry(
+        pane_id=str(entry.get("id", "")),
+        surface_ids=tuple(str(s) for s in entry.get("surface_ids") or ()),
+        columns=int(entry.get("columns", 0)),
+        rows=int(entry.get("rows", 0)),
+        x=int(frame.get("x", 0)),
+        y=int(frame.get("y", 0)),
+        cell_width_points=int(entry.get("cell_width_points", 0)),
+        ref=str(entry.get("ref", "")),
+        selected_surface_id=str(entry.get("selected_surface_id", "")),
+    )
+
+
+def _login_shell_path() -> str:
+    """PATH as the user's own login shell resolves it.
+
+    Falls back to the inherited PATH: a worker started with a shim-filtered
+    inherited PATH is still better than one started with cmux's bare list.
+    """
+    shell = os.environ.get("SHELL", "") or "/bin/sh"
+    try:
+        result = subprocess.run(
+            [shell, "-lc", 'printf %s "$PATH"'],
+            capture_output=True,
+            text=True,
+            timeout=LOGIN_SHELL_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return os.environ.get("PATH", "")
+    if result.returncode != 0 or not result.stdout.strip():
+        return os.environ.get("PATH", "")
+    return result.stdout.strip()
+
+
+def identify_caller() -> dict[str, Any]:
+    """The caller's ref bundle, or {} when cmux cannot resolve it.
+
+    `identify` exits 0 even for an id it cannot resolve, so the exit code says
+    nothing; a null `caller` is the only signal that the lookup failed.
+    """
+    try:
+        result = run_cmux(["identify"])
+    except (OSError, subprocess.SubprocessError):
+        return {}
+    if result.returncode != 0:
+        return {}
+    try:
+        payload = json.loads(result.stdout)
+    except ValueError:
+        return {}
+    caller = payload.get("caller")
+    return caller if isinstance(caller, dict) else {}
+
+
+def _ping_answers() -> bool:
+    try:
+        result = run_cmux(["ping"])
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return result.returncode == 0 and result.stdout.strip() == PING_OK

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -10,9 +10,11 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Mapping, Sequence
 
+from . import cmux
 from . import tmux
 from .dispatch_state import (
     BACKEND_CLI_WRAPPER,
+    BACKEND_CMUX_PANE,
     BACKEND_MIXED,
     BACKEND_TMUX_PANE,
     DispatchError,
@@ -185,11 +187,19 @@ def build_dispatch_plan(
 
 def dispatch_plan(plan: DispatchPlan, *, wait: bool = True) -> int:
     if wait:
-        if any(job.backend == BACKEND_TMUX_PANE for job in plan.jobs):
+        pane_backends = sorted(
+            {
+                job.backend
+                for job in plan.jobs
+                if job.backend in (BACKEND_TMUX_PANE, BACKEND_CMUX_PANE)
+            }
+        )
+        if pane_backends:
             raise DispatchError(
-                "wait=True dispatch does not support tmux-pane workers: "
-                "the per-job blocking loop would serialize panes instead of "
-                "running them concurrently; dispatch tmux panes with wait=False"
+                f"wait=True dispatch does not support {'/'.join(pane_backends)} "
+                "workers: the per-job blocking loop would serialize panes "
+                "instead of running them concurrently; dispatch panes with "
+                "wait=False"
             )
         _set_dispatch_mode(plan.team_state_path, _dispatch_mode(plan.jobs))
         for job in plan.jobs:
@@ -427,9 +437,29 @@ def _start_job(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
         return _run_cli_wrapper(plan, job, "")
     if job.backend == BACKEND_TMUX_PANE:
         return _start_tmux_or_degrade(plan, job)
+    if job.backend == BACKEND_CMUX_PANE:
+        return _start_cmux_or_degrade(plan, job)
     raise DispatchError(f"unsupported worker backend: {job.backend}")
 
 
+def _start_cmux_or_degrade(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
+    workspace = cmux.resolve_lead_workspace()
+    if not workspace:
+        return _run_cli_wrapper(plan, job, BACKEND_CMUX_PANE)
+    try:
+        surface_id = cmux.spawn_worker_surface(
+            workspace=workspace,
+            cwd=plan.project_root,
+            command=job.command,
+            title=f"{job.worker_id}-worker",
+        )
+    except (RuntimeError, OSError, subprocess.SubprocessError):
+        return _run_cli_wrapper(plan, job, BACKEND_CMUX_PANE)
+    return WorkerHandle(
+        job, surface_id, None, status_path_for_prompt(job.prompt_path), ""
+    )
+
+
 def _start_tmux_or_degrade(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
     lead_pane = tmux.resolve_caller_pane()
     if not lead_pane:
@@ -561,7 +591,7 @@ def _dispatch_record(
 
 
 def _liveness_mode(backend: str) -> str:
-    if backend in (BACKEND_CLI_WRAPPER, BACKEND_TMUX_PANE):
+    if backend in (BACKEND_CLI_WRAPPER, BACKEND_TMUX_PANE, BACKEND_CMUX_PANE):
         return LIVENESS_WRAPPER_STATUS
     return LIVENESS_AUDIT_HEARTBEAT
 
@@ -615,7 +645,44 @@ def _skip_reasons(
     return {w: "skipped by worker dispatch default: worker is not supported by this dispatcher" for w in _string_list(manifest.get("recommendedWorkers")) if w not in set(selected) and w not in supported}
 
 
+_SIDEBAR_LEVELS = {
+    "worker-dispatched": "progress",
+    "worker-result-collected": "success",
+    "worker-retry-scheduled": "warning",
+    "worker-failed": "error",
+}
+
+
+def _relay_to_sidebar(plan: DispatchPlan, event_type: str, details: Mapping[str, Any]) -> None:
+    """Mirror a dispatch event onto the cmux sidebar.
+
+    A long run is mostly silence, and the sidebar is the one surface still
+    visible after the user scrolls away or switches workspaces. A failed worker
+    additionally raises a notification, because that is the event whose cost
+    grows the longer it goes unnoticed.
+    """
+    # The plan's backend, not the manifest field it was resolved from: a job
+    # that degraded to the blocking wrapper is still part of a cmux run, and
+    # that degradation is exactly what the sidebar should keep showing.
+    if plan.default_backend != BACKEND_CMUX_PANE:
+        return
+    workspace = cmux.resolve_lead_workspace()
+    worker_id = str(details.get("workerId", "") or "worker")
+    cmux.sidebar_log(
+        workspace,
+        f"{worker_id}: {event_type.removeprefix('worker-')}",
+        level=_SIDEBAR_LEVELS.get(event_type, "info"),
+    )
+    if event_type == "worker-failed":
+        cmux.sidebar_notify(
+            workspace,
+            title=f"okstra — {_require_string(plan.manifest, 'taskType')}",
+            body=f"{worker_id} failed: {details.get('reason', 'no reason recorded')}",
+        )
+
+
 def _append_event(plan: DispatchPlan, event_type: str, details: Mapping[str, Any]) -> None:
+    _relay_to_sidebar(plan, event_type, details)
     append_lead_event(
         plan.lead_events_path,
         LeadEvent(

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -24,6 +24,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Callable, Mapping, Sequence
 
+from . import cmux
 from .worker_prompt_contract import (
     PromptRecord,
     validate_initial_prompt_records,
@@ -32,8 +33,23 @@ from .worker_prompt_contract import (
 
 BACKEND_CLI_WRAPPER = "cli-wrapper"
 BACKEND_TMUX_PANE = "tmux-pane"
+BACKEND_CMUX_PANE = "cmux-pane"
 BACKEND_MIXED = "mixed"
 
+
+def detect_terminal_backend() -> str:
+    """Which pane backend this run gets. Called once, by prepare.
+
+    cmux wins wherever it is usable: the only thing a tmux session buys a lead
+    is Claude Code's AgentTeam, and the cmux path deliberately does not use it.
+    Everywhere else this answers `tmux-pane`, which is what every run got before
+    cmux existed. The answer is written to the run manifest and read back from
+    there — consumers must not re-detect, or two phases of one run can disagree.
+    """
+    if cmux.cmux_available():
+        return BACKEND_CMUX_PANE
+    return BACKEND_TMUX_PANE
+
 # `livenessMode` picks which artifact answers "is this worker still alive": the
 # in-process worker's audit sidecar heartbeat, or the CLI wrapper's status
 # sidecar. Both dispatchers write it and `worker_liveness` reads it, so the

package/runtime/python/okstra_ctl/lead_runtime.py

@@ -1,7 +1,7 @@
 """Lead runtime metadata shared by render and prepare paths."""
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 
 
 @dataclass(frozen=True)
@@ -24,9 +24,14 @@ class LeadRuntimeInfo:
         }
 
 
-ALLOWED_LEAD_RUNTIMES = ("claude-code", "codex", "antigravity", "external")
 ARTIFACT_ONLY_LEAD_RUNTIMES = frozenset({"codex", "antigravity", "external"})
 
+# Not a lead runtime — an adapter selected by the environment, so it is absent
+# from ALLOWED_LEAD_RUNTIMES and from _LEAD_RUNTIMES on purpose. `--lead-runtime
+# cmux` is not a thing a user can ask for; see `with_cmux_dispatch`.
+CMUX_ADAPTER_NAME = "cmux"
+CMUX_ADAPTER_RELATIVE_PATH = "lead/adapters/cmux.md"
+
 _LEAD_RUNTIMES = {
     "claude-code": LeadRuntimeInfo(
         runtime="claude-code",
@@ -75,6 +80,11 @@ _LEAD_RUNTIMES = {
 }
 
 
+# Derived rather than restated: a hand-written copy of the registry's own keys
+# is a list that can disagree with the thing it describes.
+ALLOWED_LEAD_RUNTIMES = tuple(_LEAD_RUNTIMES)
+
+
 def lead_runtime_info(runtime: str) -> LeadRuntimeInfo:
     try:
         return _LEAD_RUNTIMES[runtime]
@@ -85,3 +95,21 @@ def lead_runtime_info(runtime: str) -> LeadRuntimeInfo:
 
 def is_artifact_only_runtime(runtime: str) -> bool:
     return runtime in ARTIFACT_ONLY_LEAD_RUNTIMES
+
+
+def with_cmux_dispatch(info: LeadRuntimeInfo) -> LeadRuntimeInfo:
+    """The same lead, minus the two fields cmux takes over.
+
+    On the cmux path okstra owns the worker panes rather than the host, so
+    "which adapter" and "does this lead dispatch or only render" stop depending
+    on who the lead is — they are the same for every runtime. Overriding the two
+    fields keeps that answer in one adapter file rather than repeating it in
+    four. Everything else (agent, label, role, session accounting) still
+    describes the lead itself and is left untouched.
+    """
+    return replace(
+        info,
+        adapter_name=CMUX_ADAPTER_NAME,
+        adapter_dispatch_mode="team",
+        adapter_contract_relative_path=CMUX_ADAPTER_RELATIVE_PATH,
+    )

package/runtime/python/okstra_ctl/render.py

@@ -31,7 +31,8 @@ from okstra_project.dirs import TASK_MANIFEST_FILENAME, OKSTRA_DIR_NAME, project
 from . import fix_cycles
 from .analysis_inputs import ANALYSIS_TASK_TYPES
 from .paths import okstra_home
-from .lead_runtime import lead_runtime_info
+from .dispatch_state import BACKEND_CMUX_PANE
+from .lead_runtime import lead_runtime_info, with_cmux_dispatch
 from .models import UnknownProviderError, provider_ids, provider_spec
 from .runner_resolution import native_provider_for_host
 from .path_hints import compact_active_run_context, hydrate_run_context
@@ -80,7 +81,10 @@ def _lead_runtime(ctx: dict) -> str:
 
 
 def _lead_info(ctx: dict):
-    return lead_runtime_info(_lead_runtime(ctx))
+    info = lead_runtime_info(_lead_runtime(ctx))
+    if ctx.get("TERMINAL_BACKEND") == BACKEND_CMUX_PANE:
+        return with_cmux_dispatch(info)
+    return info
 
 
 def _lead_agent(ctx: dict) -> str:
@@ -1444,6 +1448,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "hostRuntime": ctx.get("HOST_RUNTIME", "") or _lead_runtime(ctx),
         "leadRuntime": _lead_runtime(ctx),
         "leadRuntimeRequest": ctx.get("LEAD_RUNTIME_REQUEST", "") or _lead_runtime(ctx),
+        "terminalBackend": ctx.get("TERMINAL_BACKEND", ""),
         "runtimeResolution": _runtime_resolution(ctx),
         "leadAssignment": _lead_assignment(ctx),
         "workerAssignments": _worker_assignments(ctx),

package/runtime/python/okstra_ctl/run.py

@@ -96,6 +96,7 @@ from .render import (
 )
 from okstra_project.dirs import okstra_home
 
+from .dispatch_state import BACKEND_CMUX_PANE, detect_terminal_backend
 from .run_context import (
     compute_and_write_run_context,
     refresh_run_context_snapshot,
@@ -2394,7 +2395,17 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         json.loads(runtime_resolution_json or "{}")
     except json.JSONDecodeError as exc:
         raise PrepareError(f"invalid --runtime-resolution-json: {exc}") from exc
-    if lead_runtime != "claude-code" and not inp.render_only:
+    # Probed once here and reused below, so the gate and the manifest cannot
+    # disagree about which backend this run is on.
+    terminal_backend = detect_terminal_backend()
+    # Outside cmux only claude-code has a dispatch backend of its own. Under
+    # cmux okstra owns the panes for every lead, so the render-only restriction
+    # no longer applies to any runtime.
+    if (
+        lead_runtime != "claude-code"
+        and terminal_backend != BACKEND_CMUX_PANE
+        and not inp.render_only
+    ):
         raise PrepareError(
             f"lead runtime `{lead_runtime}` is currently render-only; "
             "use --render-only until a dispatch backend is enabled for this lead runtime."
@@ -2495,6 +2506,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     )
 
     ctx.update({
+        "TERMINAL_BACKEND": terminal_backend,
         "EXECUTOR_WORKTREE_PATH": worktree.path,
         "EXECUTOR_WORKTREE_BRANCH": worktree.branch,
         "EXECUTOR_WORKTREE_BASE_REF": worktree.base_ref,

package/runtime/python/okstra_ctl/team.py

@@ -1,4 +1,9 @@
-"""Neutral okstra team CLI for external tmux-pane worker dispatch."""
+"""Neutral okstra team CLI for pane-backed worker dispatch.
+
+Outside cmux this is the external lead's door onto tmux panes. Under cmux it
+is every lead's door onto cmux surfaces, because okstra owns the panes there
+rather than the host. Which backend a run uses is read from its run manifest.
+"""
 from __future__ import annotations
 
 import argparse
@@ -7,8 +12,10 @@ import sys
 from pathlib import Path
 from typing import Any, Mapping, Sequence
 
+from . import cmux
 from . import tmux
 from .dispatch_core import (
+    BACKEND_CMUX_PANE,
     BACKEND_TMUX_PANE,
     DispatchError,
     DispatchPlan,
@@ -51,7 +58,7 @@ def _parser() -> argparse.ArgumentParser:
 
 
 def _add_dispatch_parser(sub) -> None:
-    parser = sub.add_parser("dispatch", help="dispatch tmux-pane workers")
+    parser = sub.add_parser("dispatch", help="dispatch pane-backed workers")
     _add_run_args(parser)
     parser.add_argument("--workers", default="")
     parser.add_argument("--jobs-file", default="")
@@ -61,7 +68,7 @@ def _add_dispatch_parser(sub) -> None:
 
 
 def _add_await_parser(sub) -> None:
-    parser = sub.add_parser("await", help="wait for tmux-pane workers")
+    parser = sub.add_parser("await", help="wait for pane-backed workers")
     _add_run_args(parser)
     parser.add_argument("--poll-interval-seconds", type=int, default=5)
     parser.add_argument("--timeout-seconds", type=int, default=None)
@@ -70,7 +77,7 @@ def _add_await_parser(sub) -> None:
 
 
 def _add_teardown_parser(sub) -> None:
-    parser = sub.add_parser("teardown", help="kill tmux-pane workers")
+    parser = sub.add_parser("teardown", help="reclaim this run's worker panes")
     _add_run_args(parser)
     parser.add_argument("--dry-run", action="store_true")
     parser.add_argument("--json", action="store_true")
@@ -94,8 +101,8 @@ def _dispatch(args) -> int:
         okstra_bin=Path(args.okstra_bin),
         requested_workers=requested,
         idle_timeout_seconds=args.idle_timeout_seconds,
-        required_lead_runtime="external",
-        default_backend=BACKEND_TMUX_PANE,
+        required_lead_runtime=None if _is_cmux_run(manifest) else "external",
+        default_backend=_manifest_backend(manifest),
         supported_worker_wrappers=_SUPPORTED_WRAPPERS,
         unsupported_worker_label="external lead",
         dispatch_kind=args.dispatch_kind,
@@ -133,13 +140,13 @@ def _teardown(args) -> int:
     team_state_path = _resolve_project_path(project_root, _require_string(manifest, "teamStatePath"))
     team_state = _load_json(team_state_path, "team-state")
     run_dir = _resolve_project_path(project_root, _require_string(manifest, "runDirectoryPath"))
-    lead_pane = tmux.resolve_caller_pane()
-    panes = _teardown_panes(team_state, run_dir, lead_pane)
+    panes = _reclaimable_panes(manifest, team_state, run_dir)
     if args.dry_run:
         _emit_teardown(args.json, panes)
         return 0
+    reclaim = cmux.close_surface if _is_cmux_run(manifest) else tmux.kill_pane
     for pane in panes:
-        tmux.kill_pane(pane["paneId"])
+        reclaim(pane["paneId"])
     _mark_teardown_errors(team_state_path)
     _emit_teardown(args.json, panes)
     return 0
@@ -158,7 +165,7 @@ def _plan_for_existing(
         lead_events_path=_resolve_project_path(root, _require_string(manifest, "leadEventsPath")),
         manifest=manifest,
         jobs=(),
-        default_backend=BACKEND_TMUX_PANE,
+        default_backend=_manifest_backend(manifest),
     )
 
 
@@ -174,12 +181,25 @@ def _await_payload(plan: DispatchPlan, completed: bool) -> dict[str, Any]:
     }
 
 
-def _teardown_panes(team_state: Mapping[str, Any], run_dir: Path, lead_pane: str) -> list[dict[str, str]]:
+def _reclaimable_panes(
+    manifest: Mapping[str, Any], team_state: Mapping[str, Any], run_dir: Path
+) -> list[dict[str, str]]:
+    """Everything this run owns and may close.
+
+    Under cmux the recorded ids are the whole list. There is no per-pane tag API
+    to sweep with, and scanning by title would be worse than nothing: cmux labels
+    its own agent surfaces with the same glyph okstra's tmux cleanup treats as a
+    teammate marker, so a sweep could close the lead. Only surfaces okstra
+    created are recorded, so only those can be closed.
+    """
     seen: set[str] = set()
     panes: list[dict[str, str]] = []
     for record in team_state.get("workerDispatches", []):
         if isinstance(record, dict):
             _append_pane(panes, seen, str(record.get("paneId", "")), "worker")
+    if _is_cmux_run(manifest):
+        return panes
+    lead_pane = tmux.resolve_caller_pane()
     for pane in tmux.list_run_panes(run_dir, lead_pane=lead_pane):
         _append_pane(panes, seen, pane.pane_id, pane.kind)
     return panes
@@ -208,10 +228,29 @@ def _emit_teardown(as_json: bool, panes: list[dict[str, str]]) -> None:
         print(f"{pane['paneId']}\t{pane['kind']}")
 
 
+def _manifest_backend(manifest: Mapping[str, Any]) -> str:
+    """The backend prepare recorded for this run.
+
+    Deliberately not a flag on this command: the manifest already answers it,
+    and a flag would be a second answer free to disagree. A manifest written
+    before the field existed reads as tmux, which is what those runs used.
+    """
+    return str(manifest.get("terminalBackend") or "") or BACKEND_TMUX_PANE
+
+
+def _is_cmux_run(manifest: Mapping[str, Any]) -> bool:
+    return _manifest_backend(manifest) == BACKEND_CMUX_PANE
+
+
 def _validate_external_manifest(manifest: Mapping[str, Any]) -> None:
     runtime = manifest.get("leadRuntime")
     if runtime == "external":
         return
+    if _is_cmux_run(manifest):
+        # Under cmux okstra owns the panes for every lead, so this command is no
+        # longer the external lead's private door and the advice below no longer
+        # applies — there is nowhere else for a codex or Claude Code lead to go.
+        return
     if runtime == "codex":
         raise DispatchError("use okstra codex-dispatch for leadRuntime=codex")
     if runtime == "claude-code":

package/runtime/validators/validate-workflow.sh

@@ -39,6 +39,12 @@ SECONDARY_BRIEF_FILENAME="validation-brief-secondary.md"
 export OKSTRA_SKIP_INSTALL_CHECK="${OKSTRA_SKIP_INSTALL_CHECK:-1}"
 export OKSTRA_CTL_SKIP_RECONCILE="${OKSTRA_CTL_SKIP_RECONCILE:-1}"
 export OKSTRA_CTL_SKIP_BACKFILL="${OKSTRA_CTL_SKIP_BACKFILL:-1}"
+# Same reason as the three above: the synthetic run must render the same way on
+# every machine. cmux outranks tmux when present, so a maintainer running this
+# from inside cmux would otherwise get the cmux adapter and a lead-session
+# requirement this fixture never simulates. The cmux path has its own coverage
+# in tests/run/test_cmux*.py and tests/contract/test_validate_session_conformance.py.
+export CMUX_WORKSPACE_ID=""
 
 # shellcheck source=lib/common.sh
 source "$SCRIPT_DIR/lib/common.sh"

package/runtime/validators/validate_session_conformance.py

@@ -112,9 +112,19 @@ _ENTRY_GUARD_READS = (
     ),
 )
 
+# 환경으로 선택되는 어댑터라 lead 의 런타임이 이 파일을 가르쳐 주지 않는다.
+# 읽지 않은 lead 는 자기 런타임이 아는 방식 — cmux 경로에서는 okstra 가 소유한
+# 디스패치를 host 네이티브로 가로채는 방식 — 으로 되돌아간다.
+CMUX_ADAPTER_BASENAME = "cmux.md"
+CMUX_ADAPTER_NAME = "cmux"
+_CMUX_ADAPTER_CITE = "prompts/lead/adapters/cmux.md"
+
 # Read 증거는 basename 으로 거른다 — 절대 경로는 레이어(repo / runtime / 설치본)
 # 마다 다르지만 basename 은 동일하다. 목록이 갈리지 않도록 기대치에서 파생한다.
-_ENTRY_GUARD_BASENAMES = tuple(row.basename for row in _ENTRY_GUARD_READS)
+_TRACKED_READ_BASENAMES = (
+    *(row.basename for row in _ENTRY_GUARD_READS),
+    CMUX_ADAPTER_BASENAME,
+)
 
 
 @dataclass
@@ -208,7 +218,7 @@ def _scan_one_jsonl(
                         progress.append((ts, m.group("phase"), line))
                 elif block.get("type") == "tool_use" and block.get("name") == "Read":
                     base = Path(str((block.get("input") or {}).get("file_path") or "")).name
-                    if base in _ENTRY_GUARD_BASENAMES:
+                    if base in _TRACKED_READ_BASENAMES:
                         reads.setdefault(base, []).append(ts)
     return progress, reads, agent_name
 
@@ -334,7 +344,7 @@ def _sidecar_read_from_event(event) -> tuple[str, str] | None:
     if not isinstance(basename, str) or not basename:
         raw_path = details.get("path") or details.get("filePath")
         basename = Path(str(raw_path or "")).name
-    if basename not in _ENTRY_GUARD_BASENAMES:
+    if basename not in _TRACKED_READ_BASENAMES:
         return None
     return (basename, event.timestamp)
 
@@ -752,6 +762,29 @@ def _instruction_set_dir(run_dir: Path, suffix: str | None, project_root: Path)
     return path if path.is_dir() else None
 
 
+def _check_cmux_adapter_read(
+    evidence: _LeadEvidence, team_state: dict, errors: list[str]
+) -> None:
+    """검사 4 — cmux 어댑터 읽음. 모든 task-type 에 적용된다.
+
+    다른 어댑터는 lead 의 런타임이 고르지만 이것은 환경이 고른다. 그래서 읽지
+    않은 lead 에게는 이 경로가 존재한다는 사실 자체가 닿지 않고, 자기 런타임이
+    아는 host 네이티브 디스패치로 되돌아간다 — cmux 경로에서 okstra 가 소유한
+    바로 그 일이다."""
+    adapter = team_state.get("leadAdapter")
+    name = str(adapter.get("name", "")).strip() if isinstance(adapter, dict) else ""
+    if name != CMUX_ADAPTER_NAME:
+        return
+    if evidence.sidecar_reads.get(CMUX_ADAPTER_BASENAME):
+        return
+    errors.append(
+        f"cmux adapter: no `Read` of `{CMUX_ADAPTER_BASENAME}` found in the "
+        "selected adapter evidence source within this run's window — the cmux "
+        "adapter is selected by environment, not by lead runtime, so it MUST be "
+        f"read before dispatch ({_CMUX_ADAPTER_CITE})."
+    )
+
+
 def _check_implementation_entry_guard(
     evidence: _LeadEvidence, errors: list[str], instruction_set: Path | None
 ) -> None:
@@ -837,6 +870,7 @@ def validate_session_conformance(
         result.errors.append(error)
         return result
     _check_progress_checkpoints(evidence, team_state, run_dir, suffix, result.errors)
+    _check_cmux_adapter_read(evidence, team_state, result.errors)
     if task_type == "implementation":
         _check_implementation_entry_guard(
             evidence,