@polderlabs/bizar-omp 0.8.1 → 0.9.0

package/README.md

@@ -1,79 +1,35 @@
 <div align="center">
-  <img src="docs/assets/bizar-omp-banner.svg" alt="BizarHarness OMP: autonomous engineering with evidence in the loop" width="100%" />
+  <img src="docs/assets/bizar-omp-banner.svg" alt="BizarOMP — native workflow, evidence, and session control for oh-my-pi" width="100%" />
 
   <p>
-    <a href="https://www.npmjs.com/package/@polderlabs/bizar-omp"><img src="https://img.shields.io/npm/v/%40polderlabs%2Fbizar-omp?style=flat-square&color=0f766e&label=npm" alt="npm version" /></a>
-    <a href="https://github.com/PolderLabs/BizarHarness-OMP/releases"><img src="https://img.shields.io/github/v/release/PolderLabs/BizarHarness-OMP?style=flat-square&color=2563eb&label=release" alt="latest GitHub release" /></a>
-    <img src="https://img.shields.io/badge/OMP-18.4.8-2563eb?style=flat-square" alt="OMP 18.4.8" />
-    <img src="https://img.shields.io/badge/Node.js-22%2B-18181b?style=flat-square&logo=nodedotjs&logoColor=5fa04e" alt="Node.js 22 or newer" />
-    <img src="https://img.shields.io/badge/Bun-1.3.14%2B-18181b?style=flat-square&logo=bun&logoColor=fbf0df" alt="Bun 1.3.14 or newer" />
-    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-18181b?style=flat-square" alt="MIT license" /></a>
+    <a href="https://www.npmjs.com/package/@polderlabs/bizar-omp"><img src="https://img.shields.io/npm/v/%40polderlabs%2Fbizar-omp?style=flat-square&label=npm&color=cf0d77" alt="npm version" /></a>
+    <a href="https://github.com/PolderLabs/BizarHarness-OMP/releases/latest"><img src="https://img.shields.io/github/v/release/PolderLabs/BizarHarness-OMP?style=flat-square&label=release&color=0a6ed1" alt="latest GitHub release" /></a>
+    <img src="https://img.shields.io/badge/OMP-18.6.1-232833?style=flat-square" alt="OMP 18.6.1 qualified baseline" />
+    <img src="https://img.shields.io/badge/Node.js-22%2B-232833?style=flat-square&logo=nodedotjs&logoColor=ffffff" alt="Node.js 22 or newer" />
+    <img src="https://img.shields.io/badge/Bun-1.3.14%2B-232833?style=flat-square&logo=bun&logoColor=ffffff" alt="Bun 1.3.14 or newer" />
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-232833?style=flat-square" alt="MIT license" /></a>
   </p>
 
-  <p><strong>Native engineering workflows for oh-my-pi.</strong><br />
-  Plan the work, keep sessions alive, verify the result, and inspect the proof.</p>
+  <p><strong>Native workflow, evidence, and session control for <a href="https://github.com/can1357/oh-my-pi">oh-my-pi</a>.</strong></p>
 </div>
 
-> [!IMPORTANT]
-> BizarHarness OMP is an extension for [oh-my-pi](https://github.com/can1357/oh-my-pi), not a second agent runtime. OMP still owns models, credentials, tools, task execution, sessions, and conversation state.
-
-## Start here
-
-Choose the path that matches what you are trying to do:
-
-| Your goal | Run this | What it gives you |
-| --- | --- | --- |
-| Set up the complete experience | `npx --yes @polderlabs/bizar-omp setup` | `omb`, `bizar-omp`, the OMP extension, native agents, skills, rules, prompts, tools, and model roles |
-| Preview setup before changing anything | `npx --yes @polderlabs/bizar-omp setup --dry-run` | A report of the plugin and missing settings the installer would add |
-| Start one durable engineering session | `omb` | OMP inside a Bizar-owned tmux host, with reconnect support |
-| Switch between projects and sessions | `omb agents` | The full session hub and new-session picker |
-| Watch sessions in a browser | `omb dashboard --open` | A local, loopback-only dashboard with a single-use link |
-| Stop or restart everything Bizar owns | `omb stop` / `omb restart` | Bizar sessions, the daemon, and the tray, with a per-resource report |
-| Update an installed Bizar command | `omb update` | The latest global `omb` package and, when OMP is available, its enabled plugin |
-| Install only the OMP extension | `omp plugin install @polderlabs/bizar-omp` | Extension discovery without installing the `omb` and `bizar-omp` shell commands |
-
-The shortest useful path is:
-
-```sh
-npx --yes @polderlabs/bizar-omp setup
-omb
-```
-
-The setup command is safe to preview and safe to run again. It preserves credentials, provider choices, approval policies, explicit `false` or empty settings, and project overrides. It proposes only settings that are absent.
-
-## How Bizar fits into OMP
-
-<img src="docs/assets/bizar-omp-workflow.svg" alt="Bizar OMP workflow: plan, run, verify, integrate" width="100%" />
-
-Bizar adds the engineering contract around an OMP session:
+BizarOMP extends OMP with durable operator sessions, explicit engineering workflows, specialist roles, verification evidence, a local browser control plane, and an integrated Android companion. It is designed for long-running agentic engineering work where the result needs to be inspectable and the runtime needs to remain under operator control.
 
-| You need | Bizar adds |
-| --- | --- |
-| A proportionate process | Focused, bounded, and full workflow tiers selected from scope and risk |
-| Durable work | `omb` sessions in tmux, or psmux on Windows, with reconnect and a cross-project hub |
-| Specialist help | Native roles for planning, research, implementation, review, security, verification, architecture, and documentation |
-| A stronger finish line | Acceptance criteria, host-observed checks, fresh evidence, review decisions, and serialized integration admission |
-| A readable operator view | OMP's native Advisor, visible agents, session activity, a local dashboard, and inspectable projections |
-
-The ownership boundary is deliberate:
-
-| OMP owns | Bizar owns |
-| --- | --- |
-| Models, providers, credentials, tools, task execution, session files, and conversation state | Workflow intent, acceptance, evidence freshness, candidate lineage, resource ownership, review policy, and integration admission |
-
-Bizar does not replace OMP's task system, add a parallel scheduler, or provide a Claude Code, MCP, or background-daemon compatibility layer.
+> [!IMPORTANT]
+> BizarOMP is not a second agent runtime. OMP remains the authority for models, providers, credentials, tools, task execution, session files, conversation state, and native agent behavior. Bizar adds workflow policy, evidence, resource ownership, session supervision, and integration gates around that runtime.
 
-## Install
+## Quick start
 
 ### Requirements
 
-- Node.js 22 or newer
-- Bun 1.3.14 or newer
-- OMP 18.4.8 on `PATH`
-- OMP 18.4.4, 18.4.2, 18.4.1, 18.3.2, 18.3.0, 18.2.11, 18.2.8, 18.2.7, 18.2.6, 18.2.5, 18.2.4 remain regression-qualified
-- tmux on Linux and macOS, or [psmux](https://github.com/psmux/psmux) on Windows for durable sessions
+| Component | Requirement |
+| --- | --- |
+| Node.js | 22 or newer |
+| Bun | 1.3.14 or newer |
+| OMP | 18.6.1 qualified baseline |
+| Durable terminal sessions | `tmux` on Linux/macOS or `psmux` on Windows |
 
-Check the host before installing:
+Check the host:
 
 ```sh
 node --version
@@ -81,374 +37,369 @@ bun --version
 omp --version
 ```
 
-### Full installation
-
-This is the supported path for a complete Bizar OMP setup:
+Install the complete BizarOMP experience:
 
 ```sh
 npx --yes @polderlabs/bizar-omp setup
+omb
 ```
 
-The installer:
+The setup command installs the `omb` and `bizar-omp` commands, registers the OMP extension, installs the Bizar agents and assets, and applies only the missing Bizar-owned defaults. Existing credentials, provider choices, project overrides, approval policy, explicit `false` values, and unrelated model-role configuration are preserved.
 
-1. Installs the exact Bizar package version globally, providing `omb` and `bizar-omp`.
-2. Registers and enables that same version through OMP's plugin manager.
-3. Installs the extension, eight specialist agents, skills, rules, prompts, tools, and model roles.
-4. Makes the Bizar Orchestrator the default conversation and enables OMP's native Advisor.
-5. Adds only absent compatibility settings for background work, visible agents, and readable output.
-6. Writes a recoverable receipt for settings it changed and reads the result back.
-
-For a reproducible install, pin the version:
+Preview the installation first:
 
 ```sh
-npx --yes @polderlabs/bizar-omp@0.7.3 setup
+npx --yes @polderlabs/bizar-omp setup --dry-run
 ```
 
-For a named OMP profile or a non-standard OMP binary:
+For a reproducible install of the latest published release:
 
 ```sh
-npx --yes @polderlabs/bizar-omp setup --profile bizar
-npx --yes @polderlabs/bizar-omp setup --omp /path/to/omp
+npx --yes @polderlabs/bizar-omp@0.9.0 setup
 ```
 
-Preview or script the same operation:
+If you only want the native OMP extension:
 
 ```sh
-npx --yes @polderlabs/bizar-omp setup --dry-run
-npx --yes @polderlabs/bizar-omp setup --json
+omp plugin install @polderlabs/bizar-omp
 ```
 
-The interactive installer shows detected versions, each phase, settings it will add, the recovery receipt, and the next commands. `--json` produces machine-readable output for shell automation.
+That extension-only path does not install `omb` on `PATH`.
 
-To update an installed global `omb` command to the latest published release:
+## What BizarOMP adds
 
-```sh
-omb update
-```
-
-Use `omb update --check` to inspect versions without changing anything, or `omb update --dry-run` to preview the package and plugin refresh. The global command is updated even when OMP is not available; the plugin refresh is skipped until OMP is installed. `omb update` never installs or upgrades the OMP runtime. Use `omp update` explicitly for that operation. Plugin refresh uses the new Bizar package’s qualification guard and refuses an unqualified host before changing native settings.
+| Surface | What it adds |
+| --- | --- |
+| Durable runtime | Persistent OMP sessions hosted through `omb` with reconnect, ownership tracking, and cross-project discovery |
+| Engineering workflow | Focused, bounded, and full workflow tiers with explicit objectives, acceptance criteria, review policy, and stop conditions |
+| Evidence | Candidate-bound verification records, freshness checks, inspectable blockers, and serialized integration admission |
+| Specialist agents | Native OMP roles for architecture, planning, research, implementation, review, security, verification, and documentation |
+| Operator interfaces | Terminal hub, local browser dashboard, daemon, optional tray, machine-readable session inventory, and runtime controls |
+| Mobile control | Integrated Android client and host bridge for paired remote control without moving provider credentials off the host |
+| Model-role management | Bizar role mappings built on OMP's native model catalog and role system rather than a parallel model router |
 
-### Extension-only installation
+## Architecture
 
-Use this when you already manage `omb` separately or only need the OMP extension:
+BizarOMP deliberately separates runtime ownership from workflow ownership.
 
-```sh
-omp plugin install @polderlabs/bizar-omp
+```text
+Terminal / Browser / Android
+          │
+          ▼
+┌─────────────────────────────┐
+│ Bizar operator layer        │
+│ omb · hub · dashboard       │
+│ mobile host · workflow      │
+│ evidence · admission        │
+└──────────────┬──────────────┘
+               │ native extension / RPC / Collab
+               ▼
+┌─────────────────────────────┐
+│ oh-my-pi                    │
+│ sessions · models · tools   │
+│ agents · providers · auth   │
+│ task lifecycle · journals   │
+└──────────────┬──────────────┘
+               │
+               ▼
+     Host filesystem / tools
 ```
 
-This does not install `omb` or `bizar-omp` on `PATH`. For checkout development, link the package instead:
+| OMP owns | BizarOMP owns |
+| --- | --- |
+| Model registry and selection | Workflow intent and tiering |
+| Provider credentials and authentication | Acceptance and evidence policy |
+| Native tools and task execution | Candidate lineage and freshness |
+| Conversation/session state | Bizar-owned session supervision |
+| Agent lifecycle and native isolation | Integration admission and resource ownership |
+| Approval and project policy | Operator projections, dashboard, and mobile control surfaces |
 
-```sh
-omp plugin link /path/to/bizaromp
-```
+This boundary is a core design constraint. Bizar does not emulate OMP's task loop, shadow its credential store, or introduce a second scheduler.
 
-### Check, repair, or remove
+## Engineering workflow
 
-```sh
-bizar-omp install-doctor
-omp plugin list
-omp plugin doctor
-```
+<img src="docs/assets/bizar-omp-workflow.svg" alt="BizarOMP workflow: plan, run, verify, integrate" width="100%" />
 
-`install-doctor` reports the active plugin, receipt state, settings drift, and the policies Bizar left under OMP's control. Uninstall only the Bizar integration with:
+The main OMP conversation acts as the Bizar orchestrator. Give it the outcome and constraints; Bizar selects the smallest workflow tier that can safely prove the change.
 
-```sh
-bizar-omp uninstall
-```
+| Tier | Intended scope | Typical proof |
+| --- | --- | --- |
+| Focused | Small, local, understood changes | Targeted check, diff review, smoke test |
+| Bounded | Contained behavior changes and small features | Explicit acceptance plus focused tests |
+| Full | Security, migrations, concurrency, architecture, cross-cutting work | Planning, isolated implementation, review, fresh evidence, serialized integration |
 
-Install and uninstall share an owner lease. After an interrupted installer exits,
-`bizar-omp uninstall` can recover the abandoned lease and restore its recorded
-changes. A live owner blocks concurrent transactions; on Linux, process start
-time also distinguishes reused PIDs. Legacy plain `.bizar-install.lock` files
-have no owner identity and remain blocked for manual inspection.
+The tier is based on effect scope and risk rather than how difficult the reasoning feels. A small credential or concurrency change can require the full path; a complex but isolated investigation can remain bounded.
 
-Uninstall restores a setting only when it still contains the value Bizar applied. If you changed that value later, Bizar preserves your change. Remove the global shell commands separately when needed:
+Start and inspect a managed workflow inside OMP:
 
-```sh
-npm uninstall --global @polderlabs/bizar-omp
+```text
+/bizar run <objective>
+/bizar status
+/bizar evidence
+/bizar inspect
+/bizar recipe <objective>
+/bizar capabilities
+/bizar cancel [reason]
 ```
 
-## Your first durable session
+The corresponding LLM tools include `bizar_workflow`, `bizar_verify`, `bizar_evidence`, `bizar_integrate`, `bizar_inspect`, `bizar_recipe_preview`, `bizar_capabilities`, and `bizar_apply_model_roles`.
+
+A stale check, changed candidate, unresolved blocker, or unknown native capability is not silently converted into success.
 
-### 1. Start OMP through `omb`
+## Durable sessions with `omb`
 
-The extension registers `/bizar` with `init`, `run`, `status`, `next`, `cancel`, `evidence`, `inspect`, and `model-roles` subcommands, plus `/bizar-dashboard` and `/bizar-models` as direct commands. `/bizar-models preview` shows the live plan without writing settings; `/bizar-models` hands the live catalog and a deterministic baseline to the active agent and persists only the approved distribution while preserving non-Bizar roles and the configured global/project storage scope. OmniRoute route combos can resolve in OMP's catalog without having an executable backend. Bizar therefore excludes these opaque selectors from automatic role assignment, reports gateway 404 (no executable targets) separately from 429 (rate limit or quota), and never switches to another route automatically. Check the combo's eligible targets and limits in OmniRoute; use a concrete model selector when execution is required. Start with `/bizar run <objective>`; the LLM tools are `bizar_workflow`, `bizar_verify`, `bizar_evidence`, `bizar_integrate`, `bizar_recipe_preview`, `bizar_inspect`, `bizar_capabilities`, and `bizar_apply_model_roles`.
+`omb` is the operator entry point. Unknown `omb` arguments are passed through to OMP, so normal OMP usage remains available: `omb --resume` reopens a conversation and `omb --export` writes a handoff, and both are OMP's own options rather than `omb`'s.
 
 ```sh
 omb
+omb "fix the failing test"
+omb --resume
 ```
 
-`omb` starts OMP inside a Bizar-owned tmux session from the first process. Closing the terminal client detaches from the session; it does not stop the host or its background agents. Run `omb` again in the same directory to reconnect to the most recently active live session.
+When durable hosting is available, `omb` starts OMP inside a Bizar-owned multiplexer session. Closing the terminal detaches the client without terminating the host. Running `omb` again in the same project reconnects to the most relevant live session.
 
-OMB starts OMP in its normal project and profile session directory, so both entry points discover and write the same native JSONL, including when OMP atomically rewrites it during compaction. The extension holds an ownership lease while a journal is open and refuses a resume that would create a second writer. The extension keeps a private Bizar-to-OMP identity binding for dashboard history and rename safety; deleting an OMB session removes the native journal from OMP discovery and leaves a Bizar tombstone.
-
-Use a task-specific session when you want an explicit name:
+Create or select explicit sessions:
 
 ```sh
 omb new "Investigate the API timeout"
 omb --session api-retries
 ```
 
-`omp` remains the direct OMP command. Use it when you do not need durable tmux or psmux behavior.
-
-### 2. Ask for work in the main conversation
+OMP still writes its native journal. Bizar tracks the mapping and enforces one active writer for the same owned conversation so reconnect, dashboard, and mobile control do not silently create competing writers.
 
-The main conversation is the Bizar Orchestrator. Give it the outcome and constraints in plain language. It selects the smallest workflow tier that fits the work:
+### Session hub
 
-| Tier | Good fit | Typical proof |
-| --- | --- | --- |
-| Focused | A typo, small documentation edit, or narrow local fix | Targeted check, diff review, or smoke test |
-| Bounded | A contained behavior change or small feature | Acceptance criteria and focused tests |
-| Full | Security, architecture, migrations, concurrency, or cross-cutting work | Planning, isolation, review, fresh evidence, and serialized integration |
+```sh
+omb agents
+omb a
+omb agents --new
+omb hub
+```
 
-The tier follows what a change can break — effect scope, ambiguity, trust boundary, reversibility, file count, and whether the cause is known — not how hard the reasoning is. A subtle two-file fix can use a stronger model and still stay focused; a credential, migration, concurrency or irreversible change forces the full tier regardless of which model runs it. A tier can escalate when the scope or risk changes, and a focused request still gets validation.
+The hub provides:
 
-Recipes propose the minimum sufficient proof for the changed scope and say why each check was kept or deferred. Host verification reuses a fresh passing record for the same check, target tree and admitted CheckSpec instead of re-running it, and a per-run validation budget refuses a check that would overrun the wall clock it was meant to be bounded by.
+- current-directory and all-project scopes;
+- active, stopped, and combined session filters;
+- attach, continue, rename, delete, refresh, settings, and new-session actions;
+- recursive project discovery from a configured project root;
+- privacy-safe activity summaries derived from Bizar's session view;
+- optional mouse input and tray integration.
 
-### 3. Inspect the work
+The session state reflects journal activity and host liveness rather than tmux attachment alone. A detached session can continue to be `working`.
 
-Inside OMP, these commands expose the workflow state and proof:
+For scripts and integrations:
 
-```text
-/bizar run <objective>       Start a bounded workflow
-/bizar status                 Show the active workflow state
-/bizar evidence               List recorded checks and evidence
-/bizar inspect                Explain blockers and evidence lineage
-/bizar recipe <objective>     Preview an inspectable recipe
-/bizar capabilities          Show native qualification boundaries
-/bizar cancel [reason]        Cancel the active workflow
+```sh
+omb sessions --json
+omb help sessions
 ```
 
-The tools behind these commands keep completion tied to fresh, host-observed checks. A stale check, changed candidate, missing review, or unknown native capability remains a blocker instead of being silently treated as success.
+## Browser dashboard
 
-Useful model and dashboard commands are also available:
+Start or open the local dashboard:
 
-```text
-/bizar-models                 Ask the agent to distribute OMP's models across Bizar roles
-/bizar-models preview         Show the live catalog's deterministic baseline without writing settings
-/bizar-models health          Validate configured role selectors
-/bizar-dashboard              Print a single-use local dashboard link
-/bizar-dashboard open         Open the dashboard in the default browser
-/bizar-dashboard stop         Stop the dashboard daemon
+```sh
+omb dashboard
+omb dashboard --open
+omb dashboard --json
 ```
 
-`/bizar-models` reads OMP's authenticated model catalog locally, reports what changed since the last observation, and hands the catalog, the current mapping, and a deterministic baseline to the active agent, which decides the distribution and persists it through the native `bizar_apply_model_roles` tool. That tool validates every selector against the live catalog and writes the whole mapping or nothing, preserving unrelated roles; a host without agent messaging applies the baseline itself. It does not promise a particular provider, model family, price, or quality level.
-
-Ordinary session startup leaves OMP's persistent model roles, tags and cycle
-order unchanged. Setup and explicit model-role assignment own those changes.
-Main-orchestrator activation requires OMP's native main-agent identity and
-session ID; task children and depth-zero clones cannot activate it. Hosts that
-cannot expose that identity refuse activation.
+The dashboard is a self-contained local operator UI backed by the Bizar daemon. It provides session selection, structured conversation history, bounded live console capture, prompt sending, terminal attach, lifecycle controls, model/thinking/permission defaults for newly created sessions, and OMP/provider settings surfaces.
 
-Command reports are longer than a status line can show, so the complete text is appended to `.bizar-omp/run.log` in the project the command ran in, as one JSON line per run with its timestamp, command event, and last session entry. The status line shows the fitted summary.
+Security properties are intentionally narrow:
 
-## The `omb agents` hub
+- the dashboard binds to `127.0.0.1`;
+- access uses a single-use code with a short expiry;
+- the exchanged token stays in browser session memory;
+- provider secrets remain write-only;
+- session-list payloads exclude environment values, raw prompts, pane commands, process IDs, credentials, and terminal history;
+- console capture is authenticated, bounded, and control-sequence stripped;
+- mutations are serialized and ownership-checked.
 
-Open the session switcher from any project:
+Daemon lifecycle:
 
 ```sh
-omb agents
-omb agents --new    # open the new-session picker immediately
-omb hub             # alias for omb agents
+omb daemon start
+omb daemon status
+omb daemon restart
+omb daemon stop
 ```
 
-By default the hub shows the sessions of the current directory, including sessions whose host has stopped. Press `Tab` to switch to every project, and again to return. Press `f` to cycle the state filter between `Active`, `Stopped`, and `Both`. It includes:
+If daemon ownership cannot be verified, Bizar reports that state as unknown and refuses unsafe takeover rather than treating an uncertain lock as stopped.
 
-- A `Cwd`/`All` scope row and an `Active`/`Stopped`/`Both` state row in the header, and matching filters in the plain-text view.
-- One full-width, workspace-grouped session list with a compact selected-session strip.
-- Attach, continue, rename, delete, refresh, settings, help, and reconnect controls.
-- A new-session selector opened with `n`.
-- Recursive search inside the configured Project directory root, parent navigation, recent paths, autocomplete, and direct absolute paths.
-- Optional task text and an explicit session name.
-- Privacy-safe activity summaries derived from the session journal. Prompts, thinking text, shell commands, tool output, credentials, and raw terminal history are not rendered.
-- Optional native tray controls for opening the hub, creating a session, attaching a named session, stopping the daemon, and quitting the tray.
+## Android companion
 
-### Hub controls
+The integrated mobile workspace lives in [mobile/](mobile/README.md). It contains:
 
-| Key | Action |
-| --- | --- |
-| `Tab` | Switch the list between this directory (`Cwd`) and every project (`All`) |
-| `f` | Cycle the state filter between `Active`, `Stopped`, and `Both` |
-| `Enter` | Attach to the selected live session, or continue a stopped one by restarting its host |
-| `n` | Open the full new-session menu |
-| `e` | Rename the selected session inline |
-| `d` | Delete the selected Bizar session |
-| `s` | Open settings |
-| `r` | Refresh without moving selection or scroll |
-| `?` | Open help |
-| `q` | Exit the hub |
+- `apps/mobile` — React Native Android client;
+- `packages/host` — loopback host bridge supervising the installed OMP runtime;
+- `packages/protocol` — versioned shared transport and capability contracts.
 
-Mouse clicks select sessions and a second click opens a live one. Mouse scrolling moves through the session list while the hub is open. The hub enables terminal SGR mouse reporting only for its own lifetime. Mouse behavior inside an attached OMP session follows the session's OMP and multiplexer settings.
+The architecture keeps OMP on the user's machine:
 
-To configure project discovery, open `s`, select `Project directory root`, press `Enter`, enter a path such as `~/projects`, and save. Use `Agents view scope` to make `Cwd` or `All` the opening view; the choice is shared by every hub window. Use `Sessions shown` to keep only active sessions, only stopped ones, or both; stopped sessions are shown by default so a conversation whose host exited stays reachable. Pressing `Enter` on a stopped session restarts a host bound to that exact conversation and attaches to it. Deleting a session also tombstones its native journal so a recent history entry cannot reappear as an unopenable session; deleting an already unhosted row removes that stale history entry.
-
-### Session states
-
-| State | Meaning |
-| --- | --- |
-| `working` | The journal shows unfinished work. |
-| `waiting` | The agent finished its turn and is waiting for input, whether or not a client is attached. |
-| `connected` | A client is attached and no structured activity has been journaled yet. |
-| `disconnected` | The host is live and unattached, and the journal gives no evidence either way. |
-| `stopped` | No host is observed and the journal is silent. |
-
-State follows journal activity and host liveness, not tmux attachment alone. A detached session can remain `working`. Activity that stops advancing is marked `stalled`; old journal data is marked `stale`.
-
-### Optional tray
+```text
+Android app
+   │ HTTPS + authenticated WebSocket
+   ▼
+Cloudflare edge
+   │ outbound Cloudflare Tunnel
+   ▼
+127.0.0.1 Bizar mobile host
+   │ supervised JSONL / native control
+   ▼
+installed OMP
+```
 
-Enable the tray from hub Settings or use:
+Pair a device:
 
 ```sh
-omb tray start
-omb tray status
-omb tray stop
+omb pair
 ```
 
-The native tray backend is available on supported Linux, macOS, and Windows hosts. Unsupported desktop environments keep the terminal hub and daemon available.
+Mobile uses the same desktop OMB session inventory. Existing desktop-owned sessions are controlled through the qualified native paths rather than by opening the same OMP journal with a second writer.
 
-## Browser dashboard and daemon
+Anonymous Cloudflare Quick Tunnels are supported as ephemeral development endpoints. Named tunnels and custom hostnames are the persistent mode. Provider credentials stay on the host.
 
-The daemon keeps a session snapshot fresh independently of a terminal client. The dashboard binds to loopback and uses a single-use access code that expires after five minutes.
-
-If daemon ownership cannot be verified, status reports `UNKNOWN` and retains
-the lock. Start, shutdown signaling, and mobile management refuse that uncertain
-owner. Inspect `omb daemon status` and establish that the recorded process has
-stopped before repairing or quarantining its lock; an unknown state does not
-mean the daemon is stopped.
+Mobile source-development commands:
 
 ```sh
-omb daemon start
-omb daemon status
-omb daemon restart
-omb daemon stop
+omb mobile workspace install
+omb mobile workspace check
+omb mobile app start
+omb mobile app android
+omb mobile app android:release
 ```
 
-Open the dashboard:
+The mobile workspace has its own pnpm lockfile and is intentionally excluded from the npm package's `files` allowlist. See [mobile/README.md](mobile/README.md) for architecture, security boundaries, and build requirements.
 
-```sh
-omb dashboard          # print the local URL
-omb dashboard --open   # print and open it in the default browser
-omb dashboard --json   # emit { url, port, pid, code }
-omb dashboard stop     # stop the daemon; tmux sessions keep running
-```
+## Native agents and model roles
 
-The dashboard is organized around the active session. Choose a workspace session, read its live tmux console, and send a message from the composer with **Ctrl Enter**. Console output refreshes automatically without pulling you back to the bottom when you scroll up. **Open terminal** remains available for full-screen OMP interaction.
+Bizar installs native specialist definitions rather than inventing a private worker protocol.
 
-Custom provider edits are serialized. A busy editor or a detected external
-`models.yml` change returns a conflict; reload before retrying. Provider keys
-remain write-only, and updates preserve existing YAML comments and unrelated
-metadata. External editors do not share Bizar's lease, so avoid overlapping
-native/manual file edits with dashboard updates.
+| Specialist | Purpose |
+| --- | --- |
+| Architect | System boundaries, interfaces, and cross-cutting design |
+| Planner | Scope, dependencies, sequencing, and acceptance |
+| Researcher | Evidence-grounded investigation |
+| Implementer | Focused implementation in the assigned workspace |
+| Reviewer | Independent correctness review |
+| Security reviewer | Threat- and trust-boundary review |
+| Verifier | Reproducible validation and evidence |
+| Documentation | User and maintainer documentation |
 
-Create, rename, attach, and stop actions stay alongside the selected session. The new-session dialog lets you choose an available OMP model, thinking level, and permission mode. Dashboard settings can save those three choices as defaults for future dashboard-created sessions, alongside the shared project-root, auto-attach, mouse-forwarding, stopped-session, and tray preferences. Existing sessions keep the runtime they were launched with.
+Concrete models remain an OMP concern. Bizar role mappings are selectors over OMP's live catalog and preserve operator-owned roles and settings.
 
-Permission choices map directly to OMP: **Always ask** auto-approves read-only tools, **Allow workspace writes** also auto-approves workspace writes, and **Auto approve all** uses OMP's `yolo` approval mode. OMP policy may still prompt or block an operation. Attach uses a terminal emulator from `PATH`; set `BIZAR_TERMINAL` to override detection. If no emulator is available, the dashboard returns the exact attach command.
+Useful commands:
 
-The dashboard does not fetch a remote frontend. It serves one self-contained page, binds to `127.0.0.1`, and keeps the exchanged token in browser session memory. `omb dashboard --open` replaces an incompatible resident daemon before opening the page, so an upgrade cannot leave stale dashboard styling or scripts running. The session-list payload excludes credentials, environment values, pane commands, process ids, prompts, and terminal history. Opening a session console makes a separate authenticated request for a bounded, control-sequence-stripped capture of that exact Bizar-owned tmux pane; composer input is length-limited and sent literally to that pane.
+```text
+/bizar-models
+/bizar-models preview
+/bizar-models health
+```
 
-## Stopping and restarting the runtime
+`/bizar-models preview` shows the proposed mapping without writing settings. Applying a mapping validates selectors against OMP's live catalog and writes the Bizar mapping atomically rather than partially mutating it.
 
-`omb stop` is the single teardown path for everything Bizar owns: Bizar-named tmux sessions, the daemon, and the tray. With no target flag it stops all three, and stopping something that is not running is a success rather than an error.
+## `omb` command reference
 
-```sh
-omb stop                    # sessions, daemon, and tray
-omb stop --all              # sessions and services (the default)
-omb stop --sessions         # only Bizar-owned tmux sessions
-omb stop --session ADDRESS  # one session, repeatable: Bizar name, session id,
-                            # or the digest its name carries
-omb stop --idle             # only sessions with no client and no work in flight
-omb stop --daemon           # only the daemon (alias: --dashboard)
-omb stop --tray             # only the tray
-omb stop --force            # also stop sessions a client is attached to
-omb stop --dry-run          # report what would stop without stopping it
-omb stop --json             # { command, dryRun, stopped, started, skipped,
-                            #   planned, failed, resources }
+```text
+omb help
+omb help <command>
+omb help --json
 ```
 
-Every `omb stop` row reports what happened to that resource — `stopped`, `skipped` with the reason, `planned` for a dry run, or `failed` — and states `stopped` as a boolean as well, so a reader that only asks whether a resource is now stopped does not have to know the action vocabulary.
+| Command | Purpose |
+| --- | --- |
+| `omb [omp args]` | Run or attach OMP with durable Bizar session handling |
+| `omb agents` / `omb a` | Interactive cross-project session hub |
+| `omb sessions` / `omb s` | Session inventory, including machine-readable output |
+| `omb dashboard` | Start/open the local browser dashboard |
+| `omb daemon` | Manage the detached loopback daemon |
+| `omb tray` | Manage the optional native tray |
+| `omb pair` | Pair the Android companion with this host |
+| `omb mobile` | Manage mobile host and source workspace operations |
+| `omb stop` | Stop selected or all Bizar-owned runtime resources |
+| `omb restart` | Restart the Bizar runtime services |
+| `omb update` | Update the global Bizar package and enabled OMP plugin |
+| `omb help` | Show command help and the public dispatch surface |
 
-Only Bizar-owned sessions are ever candidates, `omb stop` never stops the session it is running inside, and an address that does not name exactly one session is refused with exit code 2 before anything is stopped. A Bizar name that is not running is a success with a `not found` row, so the same command twice is safe.
+Use `omb help <command>` for the authoritative options of each command instead of relying on copied flag lists in external notes.
 
-Target flags are additive, except that `--all` together with `--session NAME` narrows the session selection to the sessions named while the daemon and the tray are still stopped. The daemon and the tray are signalled only while the recorded lock's PID is verified to still be that process, so a lock that cannot be verified is skipped with a reason instead of signalled.
+## Update, diagnose, and remove
 
-A session is reported `stopped` only when its absence is proven: a `kill-session` the multiplexer refused, or a refusal that could not be confirmed by listing the sessions, is reported as `failed` rather than as a stop that did not happen. A multiplexer that is not installed, or that has no server running, stops nothing and reports success.
+Inspect the installation:
 
 ```sh
-omb restart                 # stop the runtime, then start the daemon and tray
-omb restart --force         # also stop sessions a client is attached to
-omb restart --dry-run       # report the plan without stopping or starting
-omb restart --json          # { command, dryRun, stopped, started, skipped,
-                            #   planned, failed, resources, url }
+bizar-omp install-doctor
+omp plugin list
+omp plugin doctor
 ```
 
-`omb restart` always stops the whole runtime first, so `omb stop` owns the target flags: `--all`, `--sessions`, `--session NAME`, `--daemon`, `--dashboard`, `--tray`, and `--idle` are all refused with an error that points at `omb stop` and exit code 2. It starts the daemon, starts the tray only when the tray is enabled in hub settings, and prints a fresh single-use dashboard link. Agent sessions are not relaunched: their journals are kept, so `omb` in a project or the hub brings a session back.
-
-`omb restart` reports exactly one row per resource — each Bizar-owned tmux session, the daemon, the tray, and the dashboard. A row's `state` is the state observed before the command acted, and its `action` is what the restart did with that resource overall: `started` when the resource was stopped and started again (reason `stopped, then started`), `stopped` when it ended stopped (a session, or a tray that settings no longer run), `skipped` when there was nothing to do, and `failed` on a failure. A stop that failed leaves that resource's row `failed` even when the resource was started again, and the exit code is nonzero; the daemon and the tray are still started, so the runtime is left usable.
-
-`omb restart --dry-run` uses the same one-row-per-resource shape, including the dashboard row, with action `planned` and reason `stop, then start`; a tray that settings do not enable is `skipped` instead. In `--json`, `url` is always present: the freshly minted dashboard access link, or `null` when no link was minted, which is a dry run or a dashboard that failed to start.
-
-`omb help` lists the commands, and `omb help <command>` prints that command's own usage; `--help` works on every command too.
+Check or update Bizar:
 
 ```sh
-omb help            # every command
-omb help stop       # one command's usage
-omb help --json     # { commands: [{ name, names, summary, usage }] }
+omb update --check
+omb update --dry-run
+omb update
 ```
 
-`omb --help` and `omb -h` are omb's own tokens and print omb's table; use `omp --help` for OMP's own help. `--session ADDRESS`, `--session-id ADDRESS`, and `--new` are omb's launcher options and are consumed before OMP sees them; anything else `omb` does not recognise is passed through to OMP, so `omb --resume` and `omb "fix the failing test"` keep their OMP meaning.
-
-## Native roles and assets
+`omb update` updates Bizar itself. It does not silently upgrade OMP; use OMP's own update path for the runtime.
 
-Installation registers visible `bizar_*` roles without replacing operator-owned mappings. The default package includes:
+Remove the Bizar integration:
 
-- Bizar Orchestrator and Advisor integration.
-- Specialist agents for architecture, planning, research, implementation, review, security, verification, and documentation.
-- The `bizar-omp` orientation and workflow skills.
-- Native rules, prompts, tools, evidence schemas, and the OMP-native development reference skill.
+```sh
+bizar-omp uninstall
+npm uninstall --global @polderlabs/bizar-omp
+```
 
-The role names are selectors, not guarantees of speed, cost, provider, or model quality. Inspect the resolved OMP catalog when those properties matter.
+Install/uninstall operations use an owner lease and a recovery receipt. Bizar only restores a setting when it still matches the value Bizar previously applied; later operator edits are preserved.
 
 ## Safety and ownership boundaries
 
-- Bizar is trusted in-process extension code. OMP extensions and shell commands are not an OS sandbox.
-- Credentials, API keys, `.env` contents, and private control links are excluded from logs, commits, and evidence bundles.
-- OMP keeps ownership of credentials, providers, model selections, approval policies, tool policies, and project overrides.
-- Managed worker changes stay isolated and require explicit parent integration. Bizar never silently applies worker patches.
-- Git worktree cleanup is preview-first, ownership-aware, and non-forced. Ignored or uncertain content blocks cleanup.
-- A journal has at most one writer. A host that resumes a different conversation probes the target for a competing writer, then moves its own generation binding and journal manifest together; if either cannot be written, the host is left deliberately unrecoverable rather than still bound to the conversation it left, and a dead pane refuses to respawn instead of resuming the wrong one. The probe is point-in-time — OMP emits no cancellation event for a switch that does not commit, so ownership is re-established on the confirmed switch rather than held across that gap.
-- The agents hub never presents an unanswered multiplexer scan as an empty session list. A refused scan keeps the last confirmed rows and marks the view degraded; a refused scan at startup is reported rather than opening an empty hub.
-- Managed-workflow refusals name the run, its phase, and the cancel that releases it. A run left mid-flight otherwise blocks every `task` call and every non-allowlisted tool for the rest of the session with no in-band way out.
-- Install only in projects and environments you trust. Review `setup --dry-run` and `bizar-omp install-doctor` before making changes.
+BizarOMP is infrastructure around an agent runtime, so its boundaries are explicit:
 
-### Qualification boundary
+- Bizar extension code is trusted in-process code. It is not an operating-system sandbox.
+- OMP remains the source of truth for providers, credentials, models, approval policy, tools, and conversation state.
+- Managed worker output is not silently integrated. Candidate identity, evidence, and admission state remain explicit.
+- Verification evidence is tied to the candidate it observed; changed candidates invalidate stale proof.
+- Bizar-owned Git cleanup is non-forced and ownership-aware. Uncertain or ignored content blocks automatic cleanup.
+- Session journals are single-writer resources. Unknown ownership blocks mutation instead of being guessed away.
+- Dashboard and mobile projections intentionally expose less than the local terminal runtime.
+- Credentials, API keys, `.env` contents, and private control links are excluded from normal workflow logs and evidence bundles.
+- Mobile remote control does not move provider secrets to the phone.
+- Unsupported native execution paths are reported as capability boundaries rather than being presented as universally managed.
 
-The 0.6.7 release ships the `omb a` alias for the agents view, an interactive Ink progress panel for `omb update`, and a live Server-Sent Events chat stream with connection status in the dashboard, published on [npm](https://www.npmjs.com/package/@polderlabs/bizar-omp) and available as a [GitHub release](https://github.com/PolderLabs/BizarHarness-OMP/releases/tag/v0.6.7).
-
-The release does not claim OS sandboxing, provider model quality, universal native task or eval interception, automatic cleanup of an unqualified native isolation backend, or Claude Code/AO compatibility. See the [support matrix](docs/releases/support-matrix.md) for the current boundary.
+Read [docs/releases/support-matrix.md](docs/releases/support-matrix.md) for the current qualification boundary.
 
 ## Compatibility
 
-| Component | Qualified baseline |
+Current source-tree package: `@polderlabs/bizar-omp@0.8.1`. Latest published release: [0.8.1](https://github.com/PolderLabs/BizarHarness-OMP/releases/tag/v0.8.1).
+
+| Component | Qualified state |
 | --- | --- |
-| OMP | 18.4.8 at release commit `717f97f4d22b3d65c4a4eef6a744255d46f4d1a6`; 18.4.4, 18.4.2, 18.4.1, 18.3.2, 18.3.0, 18.2.11, 18.2.8, 18.2.7, 18.2.6, 18.2.5, and 18.2.4 remain regression-qualified |
-| Node.js | 22.x and 24.x |
-| Bun | 1.3.14 compatibility job |
-| Package | `@polderlabs/bizar-omp@0.7.3` |
+| BizarOMP source | 0.8.1 |
+| Latest published release | 0.8.1 |
+| OMP | 18.6.1 at release commit `2a2c6dcbbb558c0f8145f67f28b3370984f2bf60` |
+| OMP regression baseline | 18.4.4 remains regression-qualified in the current support matrix |
+| OMP accepted versions | 18.2.4, 18.2.5, 18.2.6, 18.2.7, 18.2.8, 18.2.11, 18.3.0, 18.3.2, 18.4.1, 18.4.2, 18.4.4 and 18.4.8 remain qualified alongside the 18.6.1 baseline |
+| Node.js | 22.x and 24.x in CI |
+| Bun | 1.3.14 compatibility job; package requires >= 1.3.14 |
+| Durable session backend | tmux on Linux/macOS; psmux on Windows |
+| License | MIT |
+
+The compatibility receipt is committed at [compatibility-receipt.json](compatibility-receipt.json). Upstream OMP changes require a new contract run and compatibility baseline; Bizar does not broaden a version range to hide an unqualified runtime.
 
-Upstream OMP changes require a new compatibility baseline and contract run. The package does not widen a version range to hide an unqualified runtime.
+## Development
 
-## Development and verification
+Install dependencies and run the canonical repository gate:
 
 ```sh
 npm ci
 make check
 ```
 
-`make check` is the canonical contributor gate: typecheck, tests, package verification, generated documentation checks, and secret scanning. It builds the tree **once** and hands that build to the tests and the package/receipt checks, so a gate run no longer compiles the same unchanged sources three times. A content-addressed build stamp means a tree that has not changed since the last build costs no compile at all.
+`make check` covers typechecking, tests, package verification, generated-document checks, and secret scanning.
 
-Each step still builds for itself when run on its own, so nothing loses a precondition:
-
-`make verify` is the same gate under its alias. Build the package directly with:
+Individual package checks:
 
 ```sh
 npm run build
@@ -456,53 +407,48 @@ npm run verify:package
 npm run pack:check
 ```
 
-The native OMP qualification needs the OMP source package. When it is available:
+OMP source qualification, when the target OMP source package is available:
 
 ```sh
 npm run verify:omp
 npm run verify:omp:registry
 ```
 
-### Mobile app and host
-
-The Android app, shared protocol, and mobile host are maintained together in the
-isolated [mobile workspace](https://github.com/PolderLabs/BizarHarness-OMP/tree/main/mobile/README.md).
-Its pnpm lockfile and build
-configuration stay separate from Bizar's npm package so React Native tooling
-does not affect the CLI package or its release contents.
-
-Mobile development commands require pnpm 11 and the Android SDK/JDK for device
-builds. They are intended for a Bizar source checkout. The host implementation
-is an internal module and all operator commands are under `omb mobile`.
-Bizar installs `omb` as the operator command and leaves `omp` as the native OMP
-executable. Older installations that wrapped `omp` are restored during the next
-Bizar install.
-
-From the Bizar repository root, mobile workspace operations are also under
-`omb mobile`:
+The Android workspace is intentionally isolated from the npm package and uses pnpm 11 plus the Android SDK/JDK for device builds:
 
 ```sh
 omb mobile workspace install
 omb mobile workspace check
-omb mobile app start
 ```
 
-For a device build, set up the Android SDK and JDK as described in the mobile
-guide, then run `omb mobile app android` for a debug install or
-`omb mobile app android:release` for a standalone APK. Build the internal host
-with `omb mobile build`, then use `omb pair`, `omb mobile devices` or
-`omb mobile tunnel` from the same checkout. Pairing and the mobile gateway are
-supervised by the OMB daemon.
-
-`omb mobile sessions claims --json` reports unreadable claim records and exits
-nonzero when the inventory cannot be trusted. Such records block ownership
-changes until repaired or quarantined after the previous writer is confirmed
-stopped. Device-registry writes are serialized; retry a busy operation after the
-current writer finishes. Uncertain mutation receipts or interrupted recovery
-operations require local inspection before repair. See the
-[audit recovery notes](docs/security/project-audit-2026-10-01.md#recovery-and-release).
-
-Release notes and compatibility records live in [`docs/releases/`](docs/releases/). See [CONTRIBUTING.md](CONTRIBUTING.md) for branch conventions, release tags, and trusted publishing.
+## Repository map
+
+| Path | Purpose |
+| --- | --- |
+| [src/](src/) | Extension, workflow engine, evidence, OMP integration, CLI, daemon, dashboard, and runtime code |
+| [agents/](agents/) | Native Bizar specialist definitions |
+| [skills/](skills/) | Bizar and OMP-native agent skills |
+| [rules/](rules/) | Runtime and workflow rules |
+| [prompts/](prompts/) | Prompt assets used by the extension |
+| [schemas/](schemas/) | Typed evidence and workflow schemas |
+| [tests/](tests/) | Unit, integration, contract, runtime, ownership, dashboard, and compatibility tests |
+| [mobile/](mobile/) | Android app, mobile host, shared protocol, docs, and mobile test suites |
+| [docs/](docs/) | Architecture, compatibility, development, security, decisions, and release records |
+| [audits/](audits/) | Structured historical repository audits and evidence |
+| [compatibility-receipt.json](compatibility-receipt.json) | Current source/runtime qualification receipt |
+
+## Documentation
+
+Start with these references:
+
+- [DESIGN.md](DESIGN.md) — dashboard/mobile product and interface contract.
+- [CONTRIBUTING.md](CONTRIBUTING.md) — contributor workflow and release conventions.
+- [docs/releases/support-matrix.md](docs/releases/support-matrix.md) — current qualification boundary.
+- [docs/releases/0.8.0.md](docs/releases/0.8.0.md) — latest published release note.
+- [docs/compatibility/](docs/compatibility/) — OMP compatibility records.
+- [docs/security/](docs/security/) — security reviews, recovery notes, and threat-oriented audits.
+- [mobile/README.md](mobile/README.md) — mobile architecture, pairing, transport, and development.
+- [AGENTS.md](AGENTS.md) — repository instructions for development agents.
 
 ## License