feat(herdr): run og inside a terminal multiplexer

README.md

@@ -153,6 +153,7 @@ tested distro). Native Windows — PowerShell, cmd, Git Bash — is not supporte
 | `ngrok` | only for `og start tunneled` on the default provider: a public URL so you can drive a run from outside your network. A *reserved domain* keeps invite links and session cookies working across restarts. |
 | `ssh` | only for `og start tunneled --use tunnl.gg`: that provider *is* an ssh reverse tunnel, so there is nothing to install on macOS, Linux or Windows 10+. No account either. |
 | `qrencode` | prints the tunnel URL as a QR block |
+| `herdr` | only for `og start herdr`: runs the orchestrator inside [herdr](https://herdr.dev/), one space per session with each delegated worker as a tab. Without it `og start herdr` says so and starts normally; nothing else changes. |
 
 **At least one coding CLI.** Run `./install.sh --check` to see what you have.
 
@@ -279,6 +280,50 @@ recovered exactly that way. See
 
 ---
 
+## Supported terminal multiplexers
+
+`og start <mux>` runs the orchestrator inside a terminal multiplexer: one space
+per Omnigent session, each delegated worker a tab inside it, and — where the
+backend supports it — live agent-status badges. **og is fully usable without
+one.** The multiplexer is a view, never the runtime.
+
+`installer/registry.json` is the catalog here too, but be clear what a row
+buys: **detection and listing only.** The backend code still has to exist per
+multiplexer, exactly as an agent row needs a harness plugin behind it.
+
+| Multiplexer | Session → | Worker → | Agent status | Status |
+|---|---|---|---|---|
+| [herdr](https://herdr.dev/) | workspace ("space") | tab | **yes** — live badges | verified against 0.9.3 |
+| tmux | session | window | no — window names only | not built |
+
+The **Agent status** column is the honest part. The backend contract is
+capability-based, not lowest-common-denominator: *create, close, run, focus,
+rename* are required of every backend, and *report agent state* is optional.
+herdr has it, which is what puts `working` / `blocked` / `idle` beside each
+agent in its sidebar. tmux has no equivalent, so a tmux backend would give you
+named windows and nothing more — useful, materially less.
+
+> **A naming hazard, if tmux is ever built.** tmux is already a **required**
+> dependency (see [Requirements](#requirements)): Omnigent runs every native
+> agent terminal inside its own private tmux server. A user-facing `og start
+> tmux` would make the word mean two things in one tool — the invisible
+> substrate agents already run in, and a window manager you look at. There is no
+> technical conflict (separate servers, separate sockets), but it is a
+> documentation hazard exactly where a reader is most likely to be confused.
+
+Without a multiplexer installed, `og start herdr` warns and starts normally:
+
+```
+! herdr not found on PATH — starting without it.
+  Install it from https://herdr.dev/ and re-run to use spaces.
+```
+
+See [docs/HERDR.md](docs/HERDR.md) for what the herdr backend does and the
+measured limits it works within, and [docs/MUX-LAUNCHER.md](docs/MUX-LAUNCHER.md)
+for the launcher and `og agents`.
+
+---
+
 ## Install
 
 Clone it wherever you keep repos — nothing depends on the location, and the

conftest.py

@@ -1,8 +1,48 @@
 import sys
 from pathlib import Path
 
+import pytest
+
 # og_install.py is a script, not a package (see AGENTS.md's "AI-driven install"
 # section — it's meant to be run via `python3 installer/og_install.py`, not
 # imported as `og.installer`), so tests import it directly off sys.path
 # instead of relying on a src-layout package install.
 sys.path.insert(0, str(Path(__file__).parent / "installer"))
+
+
+@pytest.fixture(autouse=True)
+def _hermetic_pythonpath(monkeypatch):
+    """Strip PYTHONPATH from every test, because og itself puts it there.
+
+    `bin/og` (see the host-daemon launch, ~line 1046) deliberately exports
+    `PYTHONPATH=$OG_POLICY_PATH${PYTHONPATH:+:$PYTHONPATH}` so the daemon can
+    import omnigent_local_policies even if the installer's .pth went stale.
+    That is intentional and stays. But the daemon spawns everything else --
+    including the coding agents it runs -- and they all inherit the value. So
+    anyone who runs pytest from inside an og-managed session is executing the
+    suite with PYTHONPATH=~/.omnigent/policies set.
+
+    That is not cosmetic. PYTHONPATH entries land on sys.path *before* any
+    site-packages .pth gets appended, so the developer's real policies module
+    shadows whatever the test just wrote. The concrete symptom, measured on
+    this machine: `install_pth`'s verification subprocess (og_install.py,
+    ~line 2625) imported the real 22.6 KB ~/.omnigent/policies/
+    omnigent_local_policies.py instead of the fixture's stand-in, that file
+    does `from omnigent.policies.builtins import orchestration`, the test's
+    fake venv has no `omnigent` installed, so the import raised
+    ModuleNotFoundError and `die()` turned it into SystemExit(1). Two tests
+    failed. CI passed, because CI has no ~/.omnigent and no PYTHONPATH -- so
+    this only ever breaks for a developer who has actually installed og,
+    i.e. exactly the people most likely to run the suite.
+
+    Worse than red: on such a machine the .pth tests could pass for the wrong
+    reason, with the import they are verifying resolving through PYTHONPATH
+    rather than through the .pth under test. Deleting this fixture makes the
+    suite non-hermetic, not merely flaky.
+
+    Suite-wide rather than scoped to the two known failures: any test that
+    spawns a subprocess is exposed to the same contamination whether or not
+    it fails today. `monkeypatch` restores the original value at teardown, so
+    nothing leaks into a later test or out of the run.
+    """
+    monkeypatch.delenv("PYTHONPATH", raising=False)