✨ feat(cli): Add Hermes setup installer

- Offer the trusted vendor installer from the Hermes setup menu
- Refresh ~/.local/bin so configuration can continue without restarting

.gitattributes

@@ -1,2 +1,9 @@
 # Treat the AppIcon bundle's contents as binary and never merge them.
 web/electron/icons/AppIcon.icon/** binary -merge
+
+# Protobuf bindings regenerated by scripts/gen_routing_pb2.py from the .proto
+# schema. Mark them generated so review/code-quality tooling skips them (ruff
+# and mypy already exclude them in pyproject.toml); the protoc output isn't
+# hand-editable, so its unused-import/global artifacts are expected.
+omnigent/api/**/*_pb2.py linguist-generated=true
+omnigent/api/**/*_pb2.pyi linguist-generated=true

.github/MAINTAINER

@@ -21,3 +21,4 @@ shivam5
 TomeHirata
 xq-yin
 hzub
+zhengwin

.github/agents/doc-drafter/config.yaml

@@ -91,7 +91,9 @@ prompt: |
   Read `DIFF_FILE` (with `sys_os_read`) carefully — it is your source of truth.
   Pull exact facts (flags, defaults, harness ids, CLI names, config keys) from the
   diff itself. Never invent a fact; if the diff doesn't settle something a doc must
-  state, flag it for manual review rather than guessing.
+  state, flag it for manual review rather than guessing. Note whether the PR
+  **adds**, **changes**, or **removes/deprecates** a user-facing feature — that
+  decides whether you add, edit, or delete docs (Step 3).
 
   ## Step 2 — Inspect the live site and decide placement
   This is why you have the whole site checked out. Read
@@ -116,7 +118,23 @@ prompt: |
   ## Step 3 — Write the edit (scoped, grounded, in-style)
   Make the change. Editing an existing `page.mdx` in place is best when one fits;
   otherwise create the new page and wire it into the nav. Keep the change scoped
-  to what this PR introduced. Be accurate and concise — no marketing fluff.
+  to what this PR introduced, changed, or removed. Be accurate and concise — no
+  marketing fluff.
+
+  When the PR **removes or deprecates** a user-facing feature, the docs must
+  shrink to match — treat this as first-class as adding docs, never as a no-op:
+  - **Feature removed**: delete the now-untrue content. If a whole page documented
+    only that feature, delete the `page.mdx` (with `sys_os_shell` `git rm`) AND
+    remove its entry from the `SECTIONS` array in
+    `components/DocsSidebarFull.js`. If it was one section of a larger page, cut
+    that section and any references, table rows, or links pointing at it. Leave
+    no dangling nav entry or cross-link to a page you deleted.
+  - **Feature deprecated (not yet gone)**: keep the page but mark it deprecated in
+    the site's usual style and state the replacement/removal timeline if the diff
+    gives one; don't delete prematurely.
+  Ground the removal in the diff: only delete docs for what the PR actually
+  removed. If you're unsure whether a doc references the removed feature elsewhere
+  on the site, flag it under "Manual review needed" rather than guessing.
 
   Match the site's conventions by mirroring a real file:
   - **Existing page**: preserve its `pageMeta(...)` frontmatter and JSX component
@@ -141,10 +159,17 @@ prompt: |
   the affected `<img>` (MDX supports JSX comments; the build is unaffected).
 
   ## Output contract (your final assistant text)
-  After a line containing exactly `<!-- DOC_DRAFT_SUMMARY -->`, emit:
-  - `## Changes documented` — one bullet per file you created or edited (pages and
-    `components/DocsSidebarFull.js`): `path — what changed`. If you made no edits,
-    write `_No edits made._` and explain under the next section.
+  On the line IMMEDIATELY BEFORE `<!-- DOC_DRAFT_SUMMARY -->`, emit a single
+  `DOC_PR_TITLE:` line — a concise, imperative summary of what the docs now cover,
+  grounded in the diff (e.g. `DOC_PR_TITLE: document SMALLINT enum-column storage`).
+  Keep it under 60 characters, no trailing period, and do NOT prefix it with
+  `docs:` (the workflow adds that). This becomes the docs PR title.
+
+  Then, after a line containing exactly `<!-- DOC_DRAFT_SUMMARY -->`, emit:
+  - `## Changes documented` — one bullet per file you created, edited, or deleted
+    (pages and `components/DocsSidebarFull.js`): `path — what changed` (say
+    "deleted" / "removed section" for removals). If you made no edits, write
+    `_No edits made._` and explain under the next section.
   - `## Manual review needed` — a checklist: `- [ ] <doc path or area> — <why>`.
     Use this for things you genuinely cannot do well: stale screenshots/GIFs (you
     can't regenerate binaries), or a placement decision you're truly unsure about.

.github/agents/feature-blog-drafter/config.yaml

@@ -0,0 +1,139 @@
+# feature-blog-drafter — drafts ONE feature-blog post on omnigent-site for a
+# feature the feature-blog-scout selected as blog-worthy at release cut.
+#
+# Like doc-drafter, it gets a checkout of the omnigent-site repo as its working
+# tree, so it inspects the REAL site (existing blog posts + conventions) to match
+# the house style, then writes the post in place. It can also read the omnigent
+# code checkout to confirm facts (commands, flags, docs paths) before writing. It
+# is a single agent (no sub-agents) for simplicity and speed.
+#
+# Run headlessly by .github/workflows/feature-blog.yml with cwd = the omnigent-site
+# checkout:  omnigent run .github/agents/feature-blog-drafter -p "<context>" --no-session
+# The agent ONLY writes the new post MDX in the site checkout and prints a summary;
+# the workflow commits, pushes, and opens the DRAFT PR.
+
+spec_version: 1
+name: feature-blog-drafter
+description: >-
+  Drafts a single feature-blog post on omnigent-site for a scout-selected
+  feature. Inspects the live site to match conventions, confirms facts against
+  the omnigent code, writes a short one-screen post following the 5-part
+  skeleton, and marks the mandatory demo for a human. Writes blog prose only —
+  never product code — and never commits or pushes (the workflow does that).
+
+executor:
+  type: omnigent
+  config:
+    harness: claude-sdk
+
+async: true
+cancellable: true
+
+# os_env runs unsandboxed (sandbox: none) — the same posture as doc-drafter.
+# The drafter sits in a STRONG trust position: it runs only on ALREADY-RELEASED
+# history; the only secret in its env is LLM_API_KEY; the omnigent-site
+# write-token is minted by the workflow AFTER it finishes. Honest residual risk
+# (same as doc-drafter / polly-review): with network allowed and LLM_API_KEY in
+# env, an injection hidden in the input could drive an outbound exfil request; a
+# network-denying sandbox is the real mitigation but is not used for the CI
+# fragility reason documented in doc-drafter/config.yaml, so we accept the same
+# residual risk. cwd is the workspace root (holds the material files the drafter
+# reads and the omnigent-site checkout it writes).
+os_env:
+  type: caller_process
+  cwd: .
+  sandbox:
+    type: none
+
+# Same blast_radius guardrail as the rest of the project: catastrophic commands
+# denied; ordinary git reads run without an ASK (headless can't approve).
+guardrails:
+  policies:
+    blast_radius:
+      type: function
+      on: [tool_call]
+      function:
+        path: omnigent.inner.nessie.policies.blast_radius
+        arguments:
+          gate_pushes: false
+
+prompt: |
+  You are the Omnigent feature-blog drafter. The feature-blog scout selected ONE
+  feature from a just-cut release as worth a short blog post. Your job: write
+  that post into the omnigent-site blog. You author blog prose (MDX) only — you
+  NEVER write product source code or tests, and you NEVER edit anything in the
+  omnigent code repo.
+
+  ## Inputs (in the run prompt)
+  - `SITE_REPO` — absolute path to the omnigent-site checkout. It is your ONLY
+    WRITE target — write the new post there.
+  - `HEADLINE`, `SLUG`, `CATEGORY` — the scout's selection for this feature.
+  - `DATE` — the release date (YYYY-MM-DD) for the post frontmatter.
+  - `MATERIAL_FILE` — a path (in your current directory) to a file holding the
+    contributing PRs' changelog entries and, when available, their diffs. **Read
+    it first with `sys_os_read`** — it is your ONLY source of truth for what the
+    feature does, its commands, and its flags. (It is a file, not inline, because
+    a large diff would exceed the command-line length limit.)
+  Do not fetch external resources. Ground every fact in `MATERIAL_FILE`.
+
+  ## Step 1 — Understand the feature
+  Read `MATERIAL_FILE` (with `sys_os_read`) carefully. Pull exact facts — the CLI
+  command(s), flags, harness ids, config keys — from it. Never invent a fact; if
+  it doesn't settle something the post must state (e.g. the exact command), omit
+  that detail rather than guess. You may read the omnigent code checkout to
+  confirm a command or a docs path.
+
+  ## Step 2 — Inspect the live site and match conventions
+  This is why you have the whole site checked out. Before writing, read an
+  existing post under `app/blog/` (or, if none exists yet, a sibling MDX page such
+  as `app/releases/<version>/page.mdx`) and copy its frontmatter shape and JSX
+  conventions EXACTLY — the import lines, the metadata/frontmatter helper, and the
+  body structure. Find where blog posts are indexed/registered (an index page or
+  a nav array) and wire the new post in the same way the existing ones are.
+
+  ## Step 3 — Write the post (short, one-screen, in-style)
+  Create `app/blog/<SLUG>/page.mdx` (adjust to match the site's actual blog path
+  convention if it differs). Follow this 5-part skeleton — keep the whole post to
+  roughly one screen; it is a changelog-blog entry, NOT a long-form article:
+
+  1. **What's new + who it's for** — the benefit `HEADLINE` as the title/H1, plus
+     a one-line "who it's for". Frontmatter carries `date: DATE`,
+     `category: CATEGORY`, and `author: "omnigent"` (default; a human may
+     overwrite it during review).
+  2. **The problem it solves** — 2–3 sentences. Benefit before mechanism: lead
+     with the user outcome, then the how. Keep our wedge as the through-line
+     (Omnigent is the orchestration layer over many agents, any device, with
+     governance) — imply it, don't sloganeer.
+  3. **Demo** — you CANNOT produce the screenshot/recording. Emit EXACTLY this
+     marker where the demo belongs, with a one-line suggestion of what to show:
+     `<!-- DEMO REQUIRED: 15–30s recording or light/dark screenshot pair, realistic data. No sanitized mockups. Suggested: <what to show> -->`
+  4. **How to use** — a copy-pasteable fenced command block (only commands/flags
+     grounded in `MATERIAL_FILE`) and a link to the relevant docs page.
+  5. **What's next** — an optional one-line forward look ONLY if the material
+     supports it; otherwise omit the line. Do NOT write the closing CTA / star
+     ask — the workflow appends a fixed footer.
+
+  Do not add a hero image — leave any `heroArt` frontmatter blank for a human.
+  Be accurate and concise — no marketing fluff. Ground every fact in the
+  material; if unsure, omit it and note it under "Manual review needed".
+
+  ## Output contract (your final assistant text)
+  On the line IMMEDIATELY BEFORE `<!-- BLOG_DRAFT_SUMMARY -->`, emit a single
+  `BLOG_PR_TITLE:` line — a concise, imperative summary grounded in the feature
+  (e.g. `BLOG_PR_TITLE: add feature blog for side-by-side harness sessions`).
+  Keep it under 60 characters, no trailing period, and do NOT prefix it with
+  `blog:` (the workflow adds that). This becomes the blog PR title.
+
+  Then, after a line containing exactly `<!-- BLOG_DRAFT_SUMMARY -->`, emit:
+  - `## Post drafted` — the path of the post file you created, plus any index /
+    nav file you edited: `path — what changed`.
+  - `## Manual review needed` — a checklist: `- [ ] <item> — <why>`. Always
+    include the mandatory demo line (the `<!-- DEMO REQUIRED -->` marker you left)
+    and the hero art + author byline as items a human must complete before merge.
+    Add any fact you had to omit for lack of grounding.
+  Then STOP. Do NOT `git commit`, push, or open a PR — the workflow does that.
+  Leave your edits in SITE_REPO's working tree and print the summary.
+
+  ## Act in the same turn you announce
+  Never end a turn after only saying what you will do — emit the tool calls that
+  perform it in the same turn.

.github/agents/feature-blog-scout/config.yaml

@@ -0,0 +1,119 @@
+# feature-blog-scout — decides which of a release's features (if any) are big
+# enough to warrant a feature-blog post, used by feature-blog.yml at release cut.
+#
+# Given the same PR-range material draft-release-notes.yml already harvests (the
+# per-PR list + the mechanical notes), it selects 0–N features worth a blog post,
+# ranked strongest-first, and emits them as a JSON block. It has NO tools and NO
+# sub-agents: it selects from the material it is handed, so a run is fast, cheap,
+# and can't hang. The feature-blog.yml workflow parses its output and runs the
+# feature-blog-drafter once per selected feature.
+#
+# Run headlessly:  omnigent run .github/agents/feature-blog-scout -p "<pr material>" --no-session
+#
+# Security posture (mirrors doc-classifier / release-notes-drafter): runs only on
+# ALREADY-RELEASED history (every PR was maintainer-reviewed + merged), on the
+# trusted default branch, with LLM_API_KEY the only secret in env. The
+# omnigent-site write-token is minted by the workflow AFTER this agent finishes.
+# Its input is author-written PR text (a prose injection surface) — the workflow
+# secret-scans stdout and redacts artifacts, and every post is a human-reviewed
+# DRAFT PR.
+
+spec_version: 1
+name: feature-blog-scout
+description: >-
+  Selects which features from a release's merged PRs (if any) are big enough to
+  warrant a feature-blog post. Applies a signal-based bar, caps at the top 2–3,
+  and emits a ranked BLOG_CANDIDATES JSON block (often empty). No tools, no
+  sub-agents — a pure selection turn.
+
+executor:
+  type: omnigent
+  config:
+    harness: claude-sdk
+
+prompt: |
+  You are the Omnigent feature-blog scout. A new version has just been cut. You
+  are given the list of pull requests merged since the previous release — each
+  with its number, title, type tag, and (when the author filled it in) the
+  one-line changelog entry — plus a MECHANICAL DRAFT that groups them into
+  Major-features / Breaking / Bug-fixes buckets. Your job: pick the features (if
+  any) big enough to be worth a short feature-blog post, and rank them.
+
+  Most releases produce ZERO — that is the expected, correct outcome for a
+  release of internal work, fixes, and small additions. Only select a feature
+  when it clearly clears the bar below.
+
+  ## The bar
+  A feature is "big enough" only if it hits **at least 2 of these 4 signals** —
+  all about the *nature* of the change (the number of PRs is NOT a signal: a big
+  feature can land in one clean PR, and a pile of PRs is often churn):
+
+  1. **New user-facing capability or surface** — a new command, mode, UI
+     surface, integration (harness / model provider / MCP tool / sandbox /
+     deploy target), not a tweak to an existing one.
+  2. **Changes a workflow** — it gives the user a *new way to do something* and
+     has a "how to use it" story; not "faster / fixed X".
+  3. **Demonstrable "why it matters"** — you can state the problem it solves in
+     2–3 sentences AND picture a 15–30s demo of it in use with realistic data.
+  4. **Fits our wedge** — orchestration over many agents, any device, with
+     governance. We are the layer *above* individual agents; competitors sell
+     one agent. Multi-agent / cross-harness / cross-device / governance features
+     fit; table-stakes single-agent features do not.
+
+  ## Hard exclusion filter (never select, regardless of signals)
+  Pure bug fixes, performance, refactors, dependency bumps, CI / build / test /
+  tooling, security fixes or hardening (never advertise these), docs-only
+  changes, and single small flag additions. Anything still behind an
+  off-by-default flag or otherwise not user-visible yet.
+
+  ## Selecting and ranking
+  - Judge readiness from the range: only select a feature that has landed and is
+    complete enough to demo this release. Skip anything half-landed or spread too
+    thin to show.
+  - Collapse related PRs into ONE feature (as release notes do) — a feature is a
+    theme, not a PR.
+  - **Cap: the top 2–3, ranked strongest-first.** Even if more clear the bar,
+    return at most 3.
+  - **Final self-check per candidate — drop it if it fails:** can you picture the
+    15–30s demo, and does a benefit headline beat naming the mechanism? (Signal 3
+    and this check are the same demo test — apply it as a filter and as a veto.)
+  - When in doubt, leave it out. A missed post is cheaper than a weak one.
+
+  ## Writing each candidate
+  - `headline`: a benefit headline, NOT a feature name — lead with the user
+    outcome ("Run Claude Code and Codex side-by-side in one session"), not the
+    mechanism ("multi-harness sessions").
+  - `slug`: short, kebab-case, url-safe, derived from the headline.
+  - `category`: a short tag for scannability (e.g. `Multi-harness`,
+    `Governance`, `Web UI`, `Models`, `Deploy`), inferred from the change.
+  - `why_worthy`: one sentence — why this clears the bar.
+  - `signals`: the signal numbers it hits, e.g. `[1, 2, 4]`.
+  - `pr_refs`: the contributing PR numbers you were actually given, e.g.
+    `[1304, 1312]`. Never cite a PR not in the input.
+
+  ## Security
+  You are running in CI with access to secrets. Never echo secrets, tokens, or
+  credentials, and never make outbound network calls.
+
+  ## Output (STRICT)
+  Emit ONLY the following block and nothing else — no preamble. On the common
+  no-blog release, emit an empty array:
+
+  <!-- BLOG_CANDIDATES -->
+  [
+    {
+      "headline": "Run Claude Code and Codex side-by-side in one session",
+      "slug": "claude-code-codex-side-by-side",
+      "category": "Multi-harness",
+      "why_worthy": "New cross-harness workflow that lets you review one agent's work with another.",
+      "signals": [1, 2, 4],
+      "pr_refs": [1304, 1312]
+    }
+  ]
+  <!-- /BLOG_CANDIDATES -->
+
+  (Emit `[]` between the markers when nothing clears the bar.)
+
+  ## Act in the same turn you announce
+  Never end a turn after only saying what you will do — produce the
+  BLOG_CANDIDATES block in the same turn.

.github/areas.json

@@ -24,7 +24,7 @@
     "                 - 'web/' before 'web/electron/' and 'web/ios/'",
     "                 - 'omnigent/inner/' before every 'omnigent/inner/<harness>_'.",
     "  owners     - candidate reviewers/assignees. Must be maintainers in",
-    "               .github/MAINTAINER. 2+ each. Edit these freely: the",
+    "               .github/MAINTAINER. 2+ each incl. owners_paused. Edit these freely: the",
     "               reviewer-logic tests run against a frozen fixture",
     "               (auto-assign-reviewer.fixture.json), so ownership changes here",
     "               do not churn them. areas.test.js validates this file (every",
@@ -181,7 +181,9 @@
         "omnigent/policies/"
       ],
       "owners": [
-        "TomeHirata",
+        "TomeHirata"
+      ],
+      "owners_paused": [
         "ckcuslife-source"
       ]
     },

.github/scripts/homebrew/generate_formula.py

@@ -0,0 +1,421 @@
+#!/usr/bin/env python3
+"""Generate the `omnigent` Homebrew formula for a released PyPI version.
+
+Splices the volatile parts of `Formula/omnigent.rb` — the stable `url`/`sha256`
+and every dependency `resource` stanza — into the hand-tuned template
+(`omnigent.rb.template`). The structural parts (desc, depends_on, install, test)
+are owned by the template; this script owns the bits that change every release.
+
+Resolution: `uv pip compile` computes the exact transitive closure of
+`omnigent[<extras>]==<version>` for each target platform (macOS arm + intel by
+default — the brew tap's `brew test-bot` matrix). The per-platform closures are
+unioned; for each package we then fetch the sdist URL + sha256 from the PyPI JSON
+API and emit a `resource` stanza. Packages with no sdist (e.g. `cel-expr-python`,
+which is Bazel-built and has no PyPI sdist) are skipped — omnigent degrades
+gracefully without them, matching the hand-tuned formula.
+
+Excluded from `resource` generation (provided by the brewed Python environment,
+NOT built as virtualenv resources — keep in sync with the template's
+`depends_on ... => :no_linkage` and the brewed packages' transitive build deps
+like cffi/pycparser, which need libffi that this formula doesn't depend on):
+``omnigent`` (the stable url itself) and ``certifi, cryptography, pydantic,
+pydantic-core, rpds-py, cffi, pycparser``.
+
+Run by `.github/workflows/homebrew-tap-pr.yml` on `release: published`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+# Default brew build matrix: macOS Apple Silicon + Intel (the tap's
+# `brew test-bot` runs on macos-15 / macos-15-intel / macos-26). The union of the
+# two closures captures platform-marker deps needed on either arch. Add
+# `x86_64-unknown-linux-gnu` here if the tap re-enables Linux builds.
+DEFAULT_PLATFORMS = ["aarch64-apple-darwin", "x86_64-apple-darwin"]
+# Extras bundled as resources. The base install already pulls the Claude and
+# OpenAI Agents harnesses; this adds the opt-in `cursor` harness (pure-Python
+# sdist). antigravity is NOT bundled — no sdist (platform wheels only), no
+# Intel-macOS build; `pip install omnigent[antigravity]` instead.
+DEFAULT_EXTRAS = ["cursor"]
+# Resolve for the brewed Python so `requires-python` markers match the formula's
+# `python@3.14` (and the `virtualenv_create(libexec, "python3.14")` in install).
+DEFAULT_PYTHON_VERSION = "3.14"
+DEFAULT_INDEX_URL = "https://pypi.org/simple"
+PYPI_JSON_API = "https://pypi.org/pypi"
+
+# Packages provided by the brewed Python environment (system site-packages),
+# not built as virtualenv resources. `cffi`/`pycparser` are listed because cffi
+# builds against libffi (not a dep of this formula) — they come from the brewed
+# `cryptography`/`cffi` formulae instead. See module docstring.
+BREWED_EXCLUSIONS = {
+    "certifi",
+    "cryptography",
+    "pydantic",
+    "pydantic-core",
+    "rpds-py",
+    "cffi",
+    "pycparser",
+}
+# omnigent is the stable `url` itself, so it's never a resource.
+SELF_EXCLUSIONS = {"omnigent"}
+
+_PLACEHOLDERS = (
+    "__OMNIGENT_URL__",
+    "__OMNIGENT_SHA256__",
+    "__RESOURCES__",
+)
+
+
+def normalize_name(name: str) -> str:
+    """PEP 503 normalized project name (lowercase, runs of [-_.] -> -)."""
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def _http_get_json(url: str, retries: int = 5, timeout: int = 30) -> dict:
+    """GET a JSON document with simple retry/backoff."""
+    last_err: Exception | None = None
+    for attempt in range(retries):
+        try:
+            req = urllib.request.Request(url, headers={"Accept": "application/json"})
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return json.load(resp)
+        except urllib.error.HTTPError as e:
+            last_err = e
+            # 404 is a hard "not on PyPI" — don't retry into a 5-minute wait.
+            if e.code == 404:
+                raise
+        except (urllib.error.URLError, TimeoutError, ConnectionError) as e:
+            last_err = e
+        time.sleep(2**attempt)
+    raise RuntimeError(f"fetch failed for {url}: {last_err}")
+
+
+def pypi_release_files(name: str, version: str, api_base: str = PYPI_JSON_API) -> list[dict]:
+    """Return the `urls` list for a (name, version) release from the PyPI JSON API.
+
+    `api_base` defaults to the public PyPI JSON API; point it at a mirror's
+    `/pypi` (via `--pypi-api` / `--proxy`) to fetch sdist URLs + sha256 through
+    a proxy. Download URLs fetched from a mirror are then host-rewritten to
+    `files.pythonhosted.org` (see `rewrite_url`) so the formula pins public URLs.
+    """
+    data = _http_get_json(f"{api_base}/{normalize_name(name)}/{version}/json")
+    return data.get("urls", [])
+
+
+def pick_sdist(files: list[dict]) -> tuple[str, str] | None:
+    """Pick the sdist (url, sha256). Prefer .tar.gz; take the only sdist if one."""
+    sdists = [f for f in files if f.get("packagetype") == "sdist"]
+    if not sdists:
+        return None
+    for f in sdists:
+        if f["url"].endswith(".tar.gz"):
+            return f["url"], f["digests"]["sha256"]
+    f = sdists[0]
+    return f["url"], f["digests"]["sha256"]
+
+
+def rewrite_url(url: str, rewrites: list[tuple[str, str]]) -> str:
+    """Apply `from -> to` substitutions to a download URL, in order.
+
+    Used to turn an internal PyPI proxy's download URLs back into public
+    `files.pythonhosted.org` URLs so the formula pins installable public URLs
+    even when resolution + metadata fetch went through the proxy (the proxy
+    mirrors PyPI's `/packages/<2>/<2>/<hash>/file` path verbatim, only the host
+    differs; the sha256 is the file's content hash, so it's valid for the public
+    URL too).
+    """
+    for old, new in rewrites:
+        url = url.replace(old, new)
+    return url
+
+
+def resource_stanza(name: str, url: str, sha256: str, indent: int = 2) -> str:
+    """A `resource "<name>" do … end` stanza, class-body indented."""
+    pad = " " * indent
+    return f'{pad}resource "{name}" do\n{pad}  url "{url}"\n{pad}  sha256 "{sha256}"\n{pad}end'
+
+
+def resolve_closure(
+    version: str,
+    platforms: list[str],
+    extras: list[str],
+    python_version: str,
+    index_url: str,
+    uv: str,
+) -> dict[str, str]:
+    """Union of `uv pip compile` resolutions per platform -> {name: version}.
+
+    Runs `uv pip compile` with `--no-config` (ignore the repo's uv.toml cooldown,
+    which would block the just-released version) against the public index. If a
+    package resolves to different versions across platforms, the highest PEP 440
+    version wins and a warning is printed (rare for sdists).
+    """
+    extras_spec = f"[{','.join(extras)}]" if extras else ""
+    requirement = f"omnigent{extras_spec}=={version}"
+    closure: dict[str, str] = {}
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmp = Path(tmpdir)
+        (tmp / "req.in").write_text(requirement + "\n")
+        for plat in platforms:
+            out = tmp / f"req.{plat.replace('-', '_')}.out"
+            cmd = [
+                uv,
+                "pip",
+                "compile",
+                "--no-config",
+                "--no-header",
+                "--no-annotate",
+                "--python-version",
+                python_version,
+                "--python-platform",
+                plat,
+                "--default-index",
+                index_url,
+                str(tmp / "req.in"),
+                "-o",
+                str(out),
+            ]
+            # Surface uv's output on failure instead of swallowing it — a
+            # resolution failure (version conflict, a dep with no Python 3.14
+            # distribution, a requires-python cap, or no network to PyPI) is
+            # otherwise undebuggable. Raise a RuntimeError (one clean line) rather
+            # than letting CalledProcessError dump the full subprocess traceback.
+            proc = subprocess.run(cmd, capture_output=True, text=True)
+            if proc.returncode != 0:
+                detail = (proc.stderr or proc.stdout or "(no output)").strip()
+                raise RuntimeError(
+                    f"`uv pip compile` failed for {plat} (python {python_version}); "
+                    f"requirement: {requirement}\n{detail}"
+                )
+            for line in out.read_text().splitlines():
+                line = line.strip()
+                if not line or line.startswith("#") or "==" not in line:
+                    continue
+                name, ver = line.split("==", 1)
+                # uv strips extras and markers by default, but defend against
+                # `name[extra]==ver` (take the bare name before '[') and against
+                # a trailing ` ; marker` on the version.
+                name = name.split("[", 1)[0].strip()
+                name = normalize_name(name)
+                ver = ver.split(";", 1)[0].strip()
+                if name in closure and closure[name] != ver:
+                    kept = max(closure[name], ver, key=_pep440_key)
+                    print(
+                        f"::warning::{name} resolved to {closure[name]} on one "
+                        f"platform and {ver} on {plat}; keeping {kept}.",
+                        file=sys.stderr,
+                    )
+                    ver = kept
+                closure[name] = ver
+    return closure
+
+
+def _pep440_key(version: str):
+    """A best-effort PEP 440 sort key for picking the max of two versions."""
+    nums = re.findall(r"\d+", version)
+    return tuple(int(n) for n in nums)
+
+
+def render_template(template: str, url: str, sha256: str, resources: str) -> str:
+    # Catch a drifted template up front: every placeholder must be present before
+    # we substitute, and none must remain after (the latter is belt-and-suspenders
+    # since str.replace removes all occurrences, but it guards against a future
+    # placeholder that contains regex-special chars or partial overlaps).
+    missing = [p for p in _PLACEHOLDERS if p not in template]
+    if missing:
+        raise RuntimeError(f"template missing placeholder(s): {missing}")
+    out = template
+    out = out.replace("__OMNIGENT_URL__", url)
+    out = out.replace("__OMNIGENT_SHA256__", sha256)
+    out = out.replace("__RESOURCES__", resources)
+    leftover = [p for p in _PLACEHOLDERS if p in out]
+    if leftover:
+        raise RuntimeError(f"template placeholders left unsubstituted: {leftover}")
+    return out
+
+
+def generate(
+    version: str,
+    template_path: Path,
+    platforms: list[str],
+    extras: list[str],
+    python_version: str,
+    index_url: str,
+    uv: str,
+    exclude: set[str],
+    api_base: str = PYPI_JSON_API,
+    url_rewrites: list[tuple[str, str]] | None = None,
+) -> str:
+    template = template_path.read_text()
+
+    # Defensive: accept a leading `v` even though the workflow strips it.
+    if version.startswith("v"):
+        version = version[1:]
+
+    extras_spec = f"[{','.join(extras)}]" if extras else ""
+    print(
+        f"Resolving omnigent{extras_spec}=={version} for {', '.join(platforms)} "
+        f"(python {python_version})…",
+        file=sys.stderr,
+    )
+    closure = resolve_closure(version, platforms, extras, python_version, index_url, uv)
+    print(f"Resolved {len(closure)} packages.", file=sys.stderr)
+
+    rewrites = url_rewrites or []
+    if rewrites:
+        print(f"URL rewrites: {rewrites}", file=sys.stderr)
+
+    # Stable sdist for omnigent itself.
+    omnigent_files = pypi_release_files("omnigent", version, api_base)
+    sdist = pick_sdist(omnigent_files)
+    if not sdist:
+        raise RuntimeError(
+            f"omnigent=={version} has no sdist on PyPI — cannot set the stable url."
+        )
+    stable_url, stable_sha = sdist
+    stable_url = rewrite_url(stable_url, rewrites)
+    print(f"omnigent {version}: {stable_url}", file=sys.stderr)
+
+    # Every resolved package (other than omnigent itself and the brewed set) ->
+    # a sdist resource stanza. `exclude` is the caller-supplied set (CLI --exclude);
+    # it augments the built-in brewed set and the always-excluded self package.
+    excluded = BREWED_EXCLUSIONS | exclude | SELF_EXCLUSIONS
+    resources: list[tuple[str, str, str]] = []
+    for name, ver in sorted(closure.items()):
+        if name in excluded:
+            continue
+        files = pypi_release_files(name, ver, api_base)
+        sdist = pick_sdist(files)
+        if not sdist:
+            # No sdist (e.g. cel-expr-python, Bazel-built) — skip. omnigent
+            # degrades gracefully without it, matching the hand-tuned formula.
+            print(
+                f"::warning::{name}=={ver} has no sdist on PyPI — skipping (no resource).",
+                file=sys.stderr,
+            )
+            continue
+        resources.append((name, rewrite_url(sdist[0], rewrites), sdist[1]))
+
+    # No trailing newline: the template's blank lines frame the resource block.
+    resources_str = "\n".join(resource_stanza(n, u, s) for n, u, s in resources)
+
+    return render_template(template, stable_url, stable_sha, resources_str)
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    ap.add_argument(
+        "--version", required=True, help="Released version (e.g. 0.3.0), no leading 'v'."
+    )
+    ap.add_argument(
+        "--template",
+        type=Path,
+        default=Path(__file__).with_name("omnigent.rb.template"),
+        help="Path to the formula template.",
+    )
+    ap.add_argument(
+        "--out",
+        type=Path,
+        default=Path("Formula/omnigent.rb"),
+        help="Where to write the rendered formula.",
+    )
+    ap.add_argument(
+        "--python-platform",
+        action="append",
+        default=None,
+        help="uv target platform (repeatable). Default: macOS arm + intel.",
+    )
+    ap.add_argument(
+        "--extra",
+        action="append",
+        default=None,
+        help="Extras to bundle (repeatable). Default: cursor.",
+    )
+    ap.add_argument(
+        "--python-version",
+        default=DEFAULT_PYTHON_VERSION,
+        help=f"uv --python-version (default {DEFAULT_PYTHON_VERSION}).",
+    )
+    ap.add_argument(
+        "--index-url",
+        default=None,
+        help="PyPI simple index URL for `uv pip compile` (default https://pypi.org/simple; "
+        "--proxy presets this).",
+    )
+    ap.add_argument(
+        "--pypi-api",
+        default=None,
+        help="PyPI JSON API base for sdist URL/sha256 fetch (default https://pypi.org/pypi; "
+        "--proxy presets this).",
+    )
+    ap.add_argument(
+        "--url-rewrite",
+        nargs=2,
+        action="append",
+        default=None,
+        metavar=("FROM", "TO"),
+        help="Rewrite FROM->TO in download URLs (repeatable). For proxy mirrors: "
+        "rewrites the mirror host back to files.pythonhosted.org.",
+    )
+    ap.add_argument(
+        "--proxy",
+        default=None,
+        metavar="HOST",
+        help="Convenience preset for an internal PyPI mirror host (e.g. "
+        "pypi-proxy.cloud.databricks.com): sets --index-url to https://HOST/simple, "
+        "--pypi-api to https://HOST/pypi, and rewrites HOST -> files.pythonhosted.org "
+        "in download URLs. Explicit --index-url/--pypi-api/--url-rewrite override.",
+    )
+    ap.add_argument(
+        "--exclude",
+        action="append",
+        default=None,
+        help="Package name to exclude from resources (repeatable; "
+        "added to the built-in brewed set).",
+    )
+    ap.add_argument("--uv", default="uv", help="uv binary path.")
+    args = ap.parse_args(argv)
+
+    # --proxy HOST presets the index, the JSON API, and a host rewrite so a
+    # local run behind an internal mirror produces a formula with public
+    # files.pythonhosted.org URLs (the mirror serves the same /packages/<..>/
+    # path, only the host differs). Explicit flags override the preset.
+    proxy = args.proxy
+    index_url = args.index_url or (f"https://{proxy}/simple" if proxy else DEFAULT_INDEX_URL)
+    api_base = args.pypi_api or (f"https://{proxy}/pypi" if proxy else PYPI_JSON_API)
+    url_rewrites = [tuple(r) for r in (args.url_rewrite or [])]
+    if proxy and (proxy, "files.pythonhosted.org") not in url_rewrites:
+        url_rewrites.insert(0, (proxy, "files.pythonhosted.org"))
+
+    formula = generate(
+        version=args.version,
+        template_path=args.template,
+        platforms=args.python_platform or DEFAULT_PLATFORMS,
+        extras=args.extra or DEFAULT_EXTRAS,
+        python_version=args.python_version,
+        index_url=index_url,
+        uv=args.uv,
+        exclude={normalize_name(n) for n in (args.exclude or [])},
+        api_base=api_base,
+        url_rewrites=url_rewrites,
+    )
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text(formula)
+    print(f"Wrote {args.out} ({len(formula)} bytes).", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

.github/scripts/homebrew/omnigent.rb.template

@@ -0,0 +1,83 @@
+# Homebrew formula TEMPLATE for the Omnigent CLI (`omnigent` / `omni`).
+#
+# The volatile parts of this formula are regenerated on every release by
+# `generate_formula.py` (run from `.github/workflows/homebrew-tap-pr.yml`) and
+# spliced into this file via three placeholders that live ONLY in the class body
+# below — keep them out of this comment or the splicer will mangle it:
+#   * the stable `url` / `sha256` lines  -> the released omnigent sdist on PyPI
+#   * the per-dependency `resource` stanzas (one per PyPI sdist in the closure)
+#
+# Edit the hand-tuned STRUCTURAL parts here (desc, depends_on, install, test).
+# Edit the dependency set in omnigent-ai/omnigent's `pyproject.toml`
+# (`[project.dependencies]` and the bundled `cursor` extra).
+# When you change the brewed `depends_on ... => :no_linkage` set, also update the
+# `BREWED_EXCLUSIONS` in `generate_formula.py` so those packages are emitted as
+# resources (or not) to match.
+#
+# `bottle do … end` and `revision` are deliberately NOT here: Homebrew's
+# `brew pr-pull` adds the bottle block after `brew test-bot` builds it, and
+# bumps `revision` on each rebuild. A new version starts at revision 0
+# (omitted).
+class Omnigent < Formula
+  include Language::Python::Virtualenv
+
+  desc "Meta-harness for AI agents"
+  homepage "https://github.com/omnigent-ai/omnigent"
+  url "__OMNIGENT_URL__"
+  sha256 "__OMNIGENT_SHA256__"
+  license "Apache-2.0"
+
+  # The Rust toolchain builds jiter and watchfiles from source.
+  depends_on "pkgconf" => :build
+  depends_on "rust" => :build
+  # certifi, cryptography, pydantic (which bundles pydantic-core), and rpds-py
+  # are provided by Homebrew formulae rather than built as virtualenv resources.
+  # The compiled ones would otherwise need a Rust/C build, and their transitive
+  # deps (cffi, pycparser) come along for free. The virtualenv is created with
+  # system site-packages, so it imports them from the brewed python. :no_linkage
+  # because they are Python imports, not libraries this formula links against.
+  depends_on "certifi" => :no_linkage
+  depends_on "cryptography" => :no_linkage
+  depends_on "libyaml"
+  depends_on "pydantic" => :no_linkage
+  depends_on "python@3.14"
+  depends_on "rpds-py" => :no_linkage
+  depends_on "tmux"
+
+__RESOURCES__
+
+  def install
+    venv = virtualenv_create(libexec, "python3.14")
+
+    # The Rust extensions (jiter, watchfiles) must leave Mach-O header padding so
+    # Homebrew can rewrite their install names to the Cellar path during
+    # relocation (macOS only; the flag breaks Linux ld).
+    ENV.append_to_rustflags "-C link-args=-Wl,-headerpad_max_install_names" if OS.mac?
+
+    # argon2-cffi-bindings' sdist ships an unprocessed .git_archival.txt that the
+    # (build-isolated, latest) setuptools-scm parses instead of falling back to
+    # PKG-INFO, so version detection fails. Pin the version it should report.
+    ENV["SETUPTOOLS_SCM_PRETEND_VERSION_FOR_ARGON2_CFFI_BINDINGS"] =
+      resource("argon2-cffi-bindings").version.to_s
+
+    venv.pip_install resources
+
+    venv.pip_install_and_link buildpath
+
+    bin.install_symlink libexec/"bin/omnigent", libexec/"bin/omni"
+
+    %w[omnigent omni].each do |cmd|
+      generate_completions_from_executable(libexec/"bin/#{cmd}",
+                                           base_name: cmd, shell_parameter_format: :click)
+    end
+  end
+
+  test do
+    system bin/"omnigent", "--help"
+
+    # certifi, cryptography, pydantic (with pydantic-core), and rpds-py are
+    # provided by Homebrew formulae and imported from the brewed python through
+    # the virtualenv's system site-packages; confirm they resolve in the venv.
+    system libexec/"bin/python", "-c", "import certifi, cryptography, pydantic, rpds"
+  end
+end

.github/scripts/merge-ready/required.sh

@@ -7,7 +7,9 @@
 # Generated file -- do not hand-edit; it is replaced wholesale on every sync.
 
 REQUIRED=(
+  "DCO"
   "Pre-commit checks"
+  "Docker build"
   "Pytest (runtime-harnesses)"
   "Pytest (runtime-policies)"
   "Pytest (runtime-core)"
@@ -20,6 +22,8 @@ REQUIRED=(
   "Pytest (server-responses)"
   "Pytest (server-rest)"
   "Pytest (spec-llms)"
+  "Pytest (runner-app)"
+  "Pytest (stores)"
   "Pytest (misc)"
   "Pytest (databricks)"
   "E2E Tests (shard 0/4)"
@@ -35,6 +39,7 @@ REQUIRED=(
 )
 
 ALLOW_SKIP=(
+  "Docker build"
   "Pytest (runtime-harnesses)"
   "Pytest (runtime-policies)"
   "Pytest (runtime-core)"
@@ -47,6 +52,8 @@ ALLOW_SKIP=(
   "Pytest (server-responses)"
   "Pytest (server-rest)"
   "Pytest (spec-llms)"
+  "Pytest (runner-app)"
+  "Pytest (stores)"
   "Pytest (misc)"
   "Pytest (databricks)"
   "E2E Tests (shard 0/4)"
@@ -69,6 +76,7 @@ is_allow_skip() { printf '%s\n' "${ALLOW_SKIP[@]}" | grep -qxF "$1"; }
 # workflow is still queued or re-running.
 workflow_for() {
   case "$1" in
+    "Docker build")          echo "Docker build" ;;
     "Pytest ("*)             echo "CI" ;;
     "E2E Tests (shard "*)    echo "E2E Tests" ;;
     "E2E UI Tests (shard "*) echo "E2E UI Tests" ;;

.github/scripts/rotation.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Daily Discord-watch rotation reminder.
+
+Reads an explicit dated schedule (rotation_schedule.json) plus a name ->
+slack_id/timezone roster (rotation_roster.json), finds today's assignee, and
+pings them in Slack on the morning of *their* local timezone.
+
+The GitHub Actions workflow wakes at a couple of fixed UTC times (one per
+timezone's morning). On each run the day's assignee is pinged only if it's
+currently morning where they live; if not, the run for their timezone's
+morning handles them. Our timezones are far enough apart that only one is ever
+in its morning at a time, so at most one person is pinged per run. Dates not
+present in the schedule get no ping.
+
+Set SLACK_WEBHOOK_URL to post for real. Leave it unset for a dry run that just
+prints what it would do — handy for testing the schedule without Slack.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import os
+import pathlib
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from zoneinfo import ZoneInfo
+
+# Data files live alongside this script so they can be edited (swaps,
+# holidays, extending the schedule) without touching the logic here.
+ROSTER_PATH = pathlib.Path(__file__).with_name("rotation_roster.json")
+SCHEDULE_PATH = pathlib.Path(__file__).with_name("rotation_schedule.json")
+
+# Each cron run is one timezone's morning scan: we ping today's assignee only
+# if it's currently morning where they are. A run that's morning in SF is night
+# in Singapore and vice versa, so at most one timezone matches per run. Morning
+# is a band rather than an exact hour, which absorbs both daylight saving and
+# GitHub's frequently-delayed cron schedule — a run that fires a few hours late
+# still counts as that person's morning. The band starts at 05:00 (not
+# midnight) so a delayed *other* timezone's cron spilling past local midnight
+# isn't mistaken for this timezone's morning, which would double-ping.
+MORNING_START_HOUR = 5
+MORNING_END_HOUR = 12
+
+
+@dataclass(frozen=True)
+class Person:
+    name: str  # display name; matches the names used in the schedule
+    slack_id: str  # Slack member ID, e.g. "U01ABC2DEF" (NOT the display name)
+    tz: str  # IANA timezone name, e.g. "America/Los_Angeles"
+
+
+def load_roster(roster_path: pathlib.Path = ROSTER_PATH) -> dict[str, Person]:
+    """Load the name -> Person mapping from JSON."""
+    roster = json.loads(roster_path.read_text())
+    return {
+        name: Person(name=name, slack_id=entry["slack_id"], tz=entry["tz"])
+        for name, entry in roster["people"].items()
+    }
+
+
+def load_schedule(
+    schedule_path: pathlib.Path = SCHEDULE_PATH,
+) -> dict[datetime.date, str]:
+    """Load the date -> assignee-name mapping from JSON."""
+    doc = json.loads(schedule_path.read_text())
+    return {datetime.date.fromisoformat(row["date"]): row["name"] for row in doc["schedule"]}
+
+
+ROSTER: dict[str, Person] = load_roster()
+SCHEDULE: dict[datetime.date, str] = load_schedule()
+
+
+def assignee_for(local_date: datetime.date) -> Person | None:
+    """The person scheduled for a given date, or None if the date isn't listed."""
+    name = SCHEDULE.get(local_date)
+    if name is None:
+        return None
+    return ROSTER.get(name)
+
+
+def whose_turn_now(now_utc: datetime.datetime) -> Person | None:
+    """Return the person to ping right now, or None if it isn't anyone's morning.
+
+    Each person is evaluated in their own timezone: it must currently be morning
+    (05:00–11:59) there, and today's schedule entry must name them. Since our
+    timezones are far enough apart that only one is ever in its morning at a
+    time, at most one person matches. A person missed by a late/early run is
+    picked up by the next run that lands in their morning.
+    """
+    for person in ROSTER.values():
+        local = now_utc.astimezone(ZoneInfo(person.tz))
+        if not (MORNING_START_HOUR <= local.hour < MORNING_END_HOUR):
+            continue
+        if assignee_for(local.date()) == person:
+            return person
+    return None
+
+
+class SlackPostError(RuntimeError):
+    """Raised when the Slack POST fails, without exposing the webhook URL."""
+
+
+def post_to_slack(webhook_url: str, person: Person) -> None:
+    text = (
+        f"<@{person.slack_id}> you're on *Discord watch* today \U0001f440 "
+        f"— please keep an eye on the channel."
+    )
+    payload = json.dumps({"text": text}).encode()
+    req = urllib.request.Request(
+        webhook_url,
+        data=payload,
+        headers={"Content-Type": "application/json"},
+    )
+    # Catch and re-raise without the URL: urllib errors stringify the full
+    # webhook URL, which must never reach the Actions log or error output.
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            resp.read()
+    except urllib.error.HTTPError as exc:
+        raise SlackPostError(f"Slack returned HTTP {exc.code} {exc.reason}") from None
+    except urllib.error.URLError as exc:
+        raise SlackPostError(f"could not reach Slack: {exc.reason}") from None
+
+
+def _report_todays_assignees(now_utc: datetime.datetime) -> None:
+    """Log who's on watch for each timezone's current local date.
+
+    Runs regardless of the morning window so a manual run is always
+    informative, even outside anyone's ping window.
+    """
+    for tz in sorted({p.tz for p in ROSTER.values()}):
+        local = now_utc.astimezone(ZoneInfo(tz))
+        person = assignee_for(local.date())
+        who = person.name if person else "nobody (no schedule entry)"
+        print(f"  {tz}: {local:%Y-%m-%d %a} -> {who}")
+
+
+def main() -> None:
+    now_utc = datetime.datetime.now(datetime.timezone.utc)
+
+    print(f"Today's watch by timezone (as of {now_utc:%Y-%m-%d %H:%M UTC}):")
+    _report_todays_assignees(now_utc)
+
+    person = whose_turn_now(now_utc)
+
+    if person is None:
+        print(f"{now_utc:%Y-%m-%d %H:%M UTC}: nobody's on watch right now, nothing to do.")
+        return
+
+    local = now_utc.astimezone(ZoneInfo(person.tz))
+    webhook_url = os.environ.get("SLACK_WEBHOOK_URL")
+    if not webhook_url:
+        print(
+            f"[dry run] Would ping {person.name} ({person.slack_id}) "
+            f"— it's {local:%Y-%m-%d %H:%M} in {person.tz}. "
+            f"Set SLACK_WEBHOOK_URL to post for real."
+        )
+        return
+
+    post_to_slack(webhook_url, person)
+    print(f"Pinged {person.name} ({person.slack_id}) at {local:%Y-%m-%d %H:%M %Z}.")
+
+
+if __name__ == "__main__":
+    main()

.github/scripts/rotation_maintain.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Maintain the Discord-watch schedule: prune elapsed dates, extend the horizon.
+
+Keeps rotation_schedule.json a rolling window of upcoming weekdays. On each run
+it drops rows before today and appends new weekday rows — continuing the
+rotation order from wherever the schedule currently ends — until the schedule
+reaches HORIZON_DAYS ahead. Idempotent: running it twice in a row is a no-op
+once the horizon is full, and a missed run just gets caught up on the next one.
+
+Manual edits (swaps, holiday coverage) on future dates are preserved — pruning
+only removes past dates, and extension only appends beyond the current last
+date, so it never rewrites a row a human changed.
+
+Run with --check to exit non-zero when the file would change (no write), for a
+dry run in CI. Otherwise it rewrites the file in place.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import pathlib
+
+ROSTER_PATH = pathlib.Path(__file__).with_name("rotation_roster.json")
+SCHEDULE_PATH = pathlib.Path(__file__).with_name("rotation_schedule.json")
+
+# Keep the schedule filled this many days into the future.
+HORIZON_DAYS = 90
+
+
+def _roster_order(roster_path: pathlib.Path) -> list[str]:
+    """Rotation order = the order names appear in the roster JSON."""
+    roster = json.loads(roster_path.read_text())
+    return list(roster["people"].keys())
+
+
+def _next_weekday(date: datetime.date) -> datetime.date:
+    """The next Mon–Fri strictly after date."""
+    nxt = date + datetime.timedelta(days=1)
+    while nxt.weekday() >= 5:  # 5=Sat, 6=Sun
+        nxt += datetime.timedelta(days=1)
+    return nxt
+
+
+def maintain(
+    schedule_doc: dict,
+    order: list[str],
+    today: datetime.date,
+    horizon_days: int = HORIZON_DAYS,
+) -> dict:
+    """Return a new schedule doc with past dates pruned and horizon extended."""
+    rows = schedule_doc.get("schedule", [])
+
+    # Prune elapsed dates (keep today onward).
+    kept = [r for r in rows if datetime.date.fromisoformat(r["date"]) >= today]
+    kept.sort(key=lambda r: r["date"])
+
+    # Figure out where to resume the rotation.
+    if kept:
+        last_date = datetime.date.fromisoformat(kept[-1]["date"])
+        last_idx = order.index(kept[-1]["name"]) if kept[-1]["name"] in order else -1
+    else:
+        # Empty (or fully elapsed) schedule: start today, at the top of the order.
+        last_date = today - datetime.timedelta(days=1)
+        last_idx = -1
+
+    horizon = today + datetime.timedelta(days=horizon_days)
+    date = _next_weekday(last_date) if kept else _first_weekday_on_or_after(today)
+    idx = last_idx
+    while date <= horizon:
+        idx = (idx + 1) % len(order)
+        kept.append({"date": date.isoformat(), "name": order[idx]})
+        date = _next_weekday(date)
+
+    new_doc = dict(schedule_doc)
+    new_doc["schedule"] = kept
+    return new_doc
+
+
+def _first_weekday_on_or_after(date: datetime.date) -> datetime.date:
+    while date.weekday() >= 5:
+        date += datetime.timedelta(days=1)
+    return date
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="exit non-zero if the file would change; do not write",
+    )
+    parser.add_argument(
+        "--today",
+        type=datetime.date.fromisoformat,
+        default=datetime.date.today(),
+        help="override today's date (ISO), for testing",
+    )
+    args = parser.parse_args()
+
+    doc = json.loads(SCHEDULE_PATH.read_text())
+    order = _roster_order(ROSTER_PATH)
+    new_doc = maintain(doc, order, args.today)
+
+    old_text = SCHEDULE_PATH.read_text()
+    new_text = json.dumps(new_doc, indent=2) + "\n"
+
+    if old_text == new_text:
+        print("Schedule already current; no change.")
+        return 0
+
+    old_n = len(doc.get("schedule", []))
+    new_n = len(new_doc["schedule"])
+    print(
+        f"Schedule updated: {old_n} -> {new_n} rows (through {new_doc['schedule'][-1]['date']})."
+    )
+
+    if args.check:
+        print("(--check) not writing.")
+        return 1
+
+    SCHEDULE_PATH.write_text(new_text)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.github/scripts/rotation_roster.json

@@ -0,0 +1,30 @@
+{
+  "_readme": [
+    "Discord-watch roster: the name -> Slack member ID + timezone mapping.",
+    "Read by .github/scripts/rotation.py; the day-to-day schedule lives",
+    "separately in rotation_schedule.json (a flat list of {date, name}).",
+    "",
+    "Fields per person (keyed by display name, which the schedule references):",
+    "  slack_id - Slack member ID (profile -> More -> Copy member ID), e.g.",
+    "             'U01ABC2DEF'. NOT the @display-name; only the member ID",
+    "             actually notifies the person.",
+    "  tz       - IANA timezone; the person is pinged on the morning of this",
+    "             zone. Currently 'America/Los_Angeles' or 'Asia/Singapore'.",
+    "",
+    "It is .json (not .yaml) on purpose: the CI runner has no PyYAML, so JSON",
+    "is read natively by the stdlib (matches .github/areas.json)."
+  ],
+  "people": {
+    "Aravind Segu": { "slack_id": "U01A12R8NUR", "tz": "America/Los_Angeles" },
+    "Bryan Qiu": { "slack_id": "U05KA5T983Y", "tz": "America/Los_Angeles" },
+    "Daniel Lok": { "slack_id": "U060CNWNHSQ", "tz": "Asia/Singapore" },
+    "Dhruv Gupta": { "slack_id": "U0A76097E1F", "tz": "America/Los_Angeles" },
+    "Edwin He": { "slack_id": "U077B1V6WQJ", "tz": "America/Los_Angeles" },
+    "Pat Sukprasert": { "slack_id": "U05HRKWFY81", "tz": "Asia/Singapore" },
+    "Sabhya Chhabria": { "slack_id": "U07A1KQDXAB", "tz": "America/Los_Angeles" },
+    "Serena Ruan": { "slack_id": "U0571L5KNLR", "tz": "Asia/Singapore" },
+    "Shivam Mittal": { "slack_id": "U09FZKX9S6B", "tz": "America/Los_Angeles" },
+    "Tomu Hirata": { "slack_id": "U07TX4PR5MZ", "tz": "Asia/Singapore" },
+    "Zeyi (Rice) Fan": { "slack_id": "U09L5HT4CH0", "tz": "America/Los_Angeles" }
+  }
+}

.github/scripts/rotation_schedule.json

@@ -0,0 +1,292 @@
+{
+  "_readme": [
+    "Discord-watch schedule. Read by .github/scripts/rotation.py.",
+    "",
+    "One row per assigned weekday, in date order. On each run the bot finds the",
+    "row whose date is today (in the assignee timezone) and pings that person on",
+    "the morning of their timezone. Dates not listed here get no ping, so keep",
+    "this topped up \u2014 extend it before it runs out.",
+    "",
+    "To swap or cover a holiday, just edit the name on the affected date(s).",
+    "name must match an entry in rotation_roster.json (which holds the",
+    "name -> slack_id + timezone mapping)."
+  ],
+  "schedule": [
+    {
+      "date": "2026-07-14",
+      "name": "Edwin He"
+    },
+    {
+      "date": "2026-07-15",
+      "name": "Pat Sukprasert"
+    },
+    {
+      "date": "2026-07-16",
+      "name": "Sabhya Chhabria"
+    },
+    {
+      "date": "2026-07-17",
+      "name": "Serena Ruan"
+    },
+    {
+      "date": "2026-07-20",
+      "name": "Shivam Mittal"
+    },
+    {
+      "date": "2026-07-21",
+      "name": "Tomu Hirata"
+    },
+    {
+      "date": "2026-07-22",
+      "name": "Zeyi (Rice) Fan"
+    },
+    {
+      "date": "2026-07-23",
+      "name": "Aravind Segu"
+    },
+    {
+      "date": "2026-07-24",
+      "name": "Bryan Qiu"
+    },
+    {
+      "date": "2026-07-27",
+      "name": "Daniel Lok"
+    },
+    {
+      "date": "2026-07-28",
+      "name": "Dhruv Gupta"
+    },
+    {
+      "date": "2026-07-29",
+      "name": "Edwin He"
+    },
+    {
+      "date": "2026-07-30",
+      "name": "Pat Sukprasert"
+    },
+    {
+      "date": "2026-07-31",
+      "name": "Sabhya Chhabria"
+    },
+    {
+      "date": "2026-08-03",
+      "name": "Serena Ruan"
+    },
+    {
+      "date": "2026-08-04",
+      "name": "Shivam Mittal"
+    },
+    {
+      "date": "2026-08-05",
+      "name": "Tomu Hirata"
+    },
+    {
+      "date": "2026-08-06",
+      "name": "Zeyi (Rice) Fan"
+    },
+    {
+      "date": "2026-08-07",
+      "name": "Aravind Segu"
+    },
+    {
+      "date": "2026-08-10",
+      "name": "Bryan Qiu"
+    },
+    {
+      "date": "2026-08-11",
+      "name": "Daniel Lok"
+    },
+    {
+      "date": "2026-08-12",
+      "name": "Dhruv Gupta"
+    },
+    {
+      "date": "2026-08-13",
+      "name": "Edwin He"
+    },
+    {
+      "date": "2026-08-14",
+      "name": "Pat Sukprasert"
+    },
+    {
+      "date": "2026-08-17",
+      "name": "Sabhya Chhabria"
+    },
+    {
+      "date": "2026-08-18",
+      "name": "Serena Ruan"
+    },
+    {
+      "date": "2026-08-19",
+      "name": "Shivam Mittal"
+    },
+    {
+      "date": "2026-08-20",
+      "name": "Tomu Hirata"
+    },
+    {
+      "date": "2026-08-21",
+      "name": "Zeyi (Rice) Fan"
+    },
+    {
+      "date": "2026-08-24",
+      "name": "Aravind Segu"
+    },
+    {
+      "date": "2026-08-25",
+      "name": "Bryan Qiu"
+    },
+    {
+      "date": "2026-08-26",
+      "name": "Daniel Lok"
+    },
+    {
+      "date": "2026-08-27",
+      "name": "Dhruv Gupta"
+    },
+    {
+      "date": "2026-08-28",
+      "name": "Edwin He"
+    },
+    {
+      "date": "2026-08-31",
+      "name": "Pat Sukprasert"
+    },
+    {
+      "date": "2026-09-01",
+      "name": "Sabhya Chhabria"
+    },
+    {
+      "date": "2026-09-02",
+      "name": "Serena Ruan"
+    },
+    {
+      "date": "2026-09-03",
+      "name": "Shivam Mittal"
+    },
+    {
+      "date": "2026-09-04",
+      "name": "Tomu Hirata"
+    },
+    {
+      "date": "2026-09-07",
+      "name": "Zeyi (Rice) Fan"
+    },
+    {
+      "date": "2026-09-08",
+      "name": "Aravind Segu"
+    },
+    {
+      "date": "2026-09-09",
+      "name": "Bryan Qiu"
+    },
+    {
+      "date": "2026-09-10",
+      "name": "Daniel Lok"
+    },
+    {
+      "date": "2026-09-11",
+      "name": "Dhruv Gupta"
+    },
+    {
+      "date": "2026-09-14",
+      "name": "Edwin He"
+    },
+    {
+      "date": "2026-09-15",
+      "name": "Pat Sukprasert"
+    },
+    {
+      "date": "2026-09-16",
+      "name": "Sabhya Chhabria"
+    },
+    {
+      "date": "2026-09-17",
+      "name": "Serena Ruan"
+    },
+    {
+      "date": "2026-09-18",
+      "name": "Shivam Mittal"
+    },
+    {
+      "date": "2026-09-21",
+      "name": "Tomu Hirata"
+    },
+    {
+      "date": "2026-09-22",
+      "name": "Zeyi (Rice) Fan"
+    },
+    {
+      "date": "2026-09-23",
+      "name": "Aravind Segu"
+    },
+    {
+      "date": "2026-09-24",
+      "name": "Bryan Qiu"
+    },
+    {
+      "date": "2026-09-25",
+      "name": "Daniel Lok"
+    },
+    {
+      "date": "2026-09-28",
+      "name": "Dhruv Gupta"
+    },
+    {
+      "date": "2026-09-29",
+      "name": "Edwin He"
+    },
+    {
+      "date": "2026-09-30",
+      "name": "Pat Sukprasert"
+    },
+    {
+      "date": "2026-10-01",
+      "name": "Sabhya Chhabria"
+    },
+    {
+      "date": "2026-10-02",
+      "name": "Serena Ruan"
+    },
+    {
+      "date": "2026-10-05",
+      "name": "Shivam Mittal"
+    },
+    {
+      "date": "2026-10-06",
+      "name": "Tomu Hirata"
+    },
+    {
+      "date": "2026-10-07",
+      "name": "Zeyi (Rice) Fan"
+    },
+    {
+      "date": "2026-10-08",
+      "name": "Aravind Segu"
+    },
+    {
+      "date": "2026-10-09",
+      "name": "Bryan Qiu"
+    },
+    {
+      "date": "2026-10-12",
+      "name": "Daniel Lok"
+    },
+    {
+      "date": "2026-10-13",
+      "name": "Dhruv Gupta"
+    },
+    {
+      "date": "2026-10-14",
+      "name": "Edwin He"
+    },
+    {
+      "date": "2026-10-15",
+      "name": "Pat Sukprasert"
+    },
+    {
+      "date": "2026-10-16",
+      "name": "Sabhya Chhabria"
+    }
+  ]
+}

.github/workflows/areas.test.js

@@ -32,9 +32,10 @@ for (const a of areas)
 for (const a of areas)
   assert(`area ${a.key} label ${a.label} is a real comp:*`, ALLOWED_LABELS.has(a.label));
 
-// Every area has >= 2 owners (the 2+ codeowner requirement).
+// Every area has >= 2 owners (the 2+ codeowner requirement). Paused owners
+// still count -- pausing someone must not force adding a new active owner.
 for (const a of areas) {
-  const n = (a.owners || []).length;
+  const n = (a.owners || []).length + (a.owners_paused || []).length;
   assert(`area ${a.key} has >= 2 owners`, n >= 2, `${n} owner(s)`);
 }
 

.github/workflows/benchmark-pr.yml

@@ -0,0 +1,177 @@
+name: Benchmark (PR)
+
+# Runs a lightweight SQLite benchmark when a PR touches migration files or
+# store-layer code and compares against the latest nightly benchmark artifact
+# as a baseline. Posts results as a PR comment and blocks the PR if a
+# regression is detected.
+#
+# Only runs on PRs to the main repo (not forks without secrets). Skips
+# comparison if no nightly baseline artifact is available — the benchmark still
+# runs and reports results, it just won't block.
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - "omnigent/db/migrations/**"
+      - "omnigent/stores/**"
+      - ".github/workflows/benchmark-pr.yml"
+
+permissions:
+  contents: read
+  pull-requests: write
+
+env:
+  OMNIGENT_SKIP_WEB_UI: "true"
+  UV_INDEX_URL: https://pypi.org/simple
+  PIP_INDEX_URL: https://pypi.org/simple
+
+concurrency:
+  group: benchmark-pr-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  benchmark-pr:
+    name: Benchmark regression check (sqlite)
+    if: github.repository == 'omnigent-ai/omnigent' && !github.event.pull_request.draft
+    runs-on: ubuntu-latest
+    timeout-minutes: 40
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version-file: ".python-version"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v3
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev --extra databricks
+
+      # Use the same corpus size as the nightly so baseline numbers are
+      # directly comparable. Cache the seeded DB on the schema head + seed
+      # script hash to avoid re-seeding on every push (same contract as
+      # benchmark.yml).
+      - name: Resolve seed cache key
+        id: seedkey
+        run: |
+          HEAD="$(uv run --no-sync dev/benchmarks/omnigent/seed.py --print-head)"
+          echo "key=benchdb-sqlite-${HEAD}-5000x200-${{ hashFiles('dev/benchmarks/omnigent/seed.py') }}" \
+            >> "$GITHUB_OUTPUT"
+
+      - name: Restore seeded SQLite corpus
+        id: seedcache
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v4
+        with:
+          path: bench.db
+          key: ${{ steps.seedkey.outputs.key }}
+
+      - name: Seed SQLite corpus
+        if: steps.seedcache.outputs.cache-hit != 'true'
+        run: |
+          uv run --no-sync dev/benchmarks/omnigent/seed.py \
+            --database-uri "sqlite:///bench.db" \
+            --sessions 5000 --items-per-session 200
+
+      - name: Run benchmark (candidate)
+        run: |
+          uv run --no-sync dev/benchmarks/omnigent/run.py \
+            --database-uri "sqlite:///bench.db" \
+            --iterations 100 \
+            --runs 3 \
+            --output candidate.json
+
+      - name: Download latest nightly baseline (sqlite)
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set +e
+          RUN_ID=$(gh api \
+            "repos/${GITHUB_REPOSITORY}/actions/workflows/benchmark.yml/runs?status=success&branch=main&per_page=10" \
+            --jq '.workflow_runs[0].id // empty')
+          if [ -z "$RUN_ID" ]; then
+            echo "No successful nightly benchmark run found — skipping comparison."
+            echo "BASELINE_FOUND=false" >> "$GITHUB_ENV"
+            exit 0
+          fi
+          ARTIFACT_ID=$(gh api \
+            "repos/${GITHUB_REPOSITORY}/actions/runs/${RUN_ID}/artifacts" \
+            --jq '.artifacts[] | select(.name | startswith("benchmark-results-sqlite-")) | .id' \
+            | head -1)
+          if [ -z "$ARTIFACT_ID" ]; then
+            echo "No sqlite artifact found on run ${RUN_ID} — skipping comparison."
+            echo "BASELINE_FOUND=false" >> "$GITHUB_ENV"
+            exit 0
+          fi
+          gh api \
+            "repos/${GITHUB_REPOSITORY}/actions/artifacts/${ARTIFACT_ID}/zip" \
+            > baseline.zip && \
+          unzip -q baseline.zip -d baseline_dir && \
+          mv baseline_dir/*.json baseline.json && \
+          echo "BASELINE_FOUND=true" >> "$GITHUB_ENV" || \
+          (echo "BASELINE_FOUND=false" >> "$GITHUB_ENV"; echo "Artifact download failed — skipping comparison.")
+
+      - name: Compare baseline vs candidate
+        if: env.BASELINE_FOUND == 'true'
+        id: compare
+        run: |
+          set +e
+          uv run --no-sync dev/benchmarks/omnigent/compare.py \
+            --baseline baseline.json \
+            --candidate candidate.json \
+            --backend sqlite \
+            --threshold 1.0 \
+            --output-markdown comparison.md
+          echo "EXIT_CODE=$?" >> "$GITHUB_ENV"
+
+      - name: Build PR comment body
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          {
+            echo "<!-- benchmark-pr-comment -->"
+            echo "## Benchmark results (SQLite, PR #${{ github.event.pull_request.number }})"
+            echo ""
+            echo "Commit: \`${{ github.event.pull_request.head.sha }}\`"
+            echo ""
+            if [ "$BASELINE_FOUND" = "true" ]; then
+              cat comparison.md
+            else
+              echo "No nightly baseline artifact found — comparison skipped."
+              echo ""
+              echo "Candidate results recorded in \`candidate.json\` artifact."
+            fi
+          } > comment_body.md
+
+      - name: Post PR comment
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh pr comment "${{ github.event.pull_request.number }}" \
+            --edit-last \
+            --body-file comment_body.md || \
+          gh pr comment "${{ github.event.pull_request.number }}" \
+            --body-file comment_body.md
+
+      - name: Upload candidate results
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: always()
+        with:
+          name: benchmark-results-sqlite-pr-${{ github.event.pull_request.number }}-${{ github.run_id }}
+          path: candidate.json
+          retention-days: 30
+          if-no-files-found: warn
+
+      - name: Fail on regression
+        if: env.BASELINE_FOUND == 'true' && env.EXIT_CODE == '1'
+        run: |
+          echo "Benchmark regression detected. See the PR comment for details."
+          exit 1

.github/workflows/benchmark.yml

@@ -0,0 +1,191 @@
+name: Benchmark
+
+# Nightly run of the HTTP user-journey performance benchmark
+# (dev/benchmarks/omnigent). Seeds a sizeable corpus, boots a real server
+# against it, drives the journeys, and uploads the JSON report as an artifact.
+# Runs a backend matrix — SQLite (in-process) and Postgres (a service
+# container, matching prod's Lakebase/Postgres round-trip + pooling profile).
+# A workspace Databricks notebook pulls these artifacts via the GitHub API into
+# a Delta table for the trend dashboard (see dev/benchmarks/omnigent/README.md)
+# — so this workflow only produces artifacts; it never touches Databricks.
+#
+# Scheduled -> runs on the trusted default branch with the repo GITHUB_TOKEN;
+# it reads no PR-authored code. Also dispatchable for an ad-hoc run.
+
+on:
+  schedule:
+    - cron: "37 7 * * *" # 07:37 UTC nightly (off-peak, off the :00 mark)
+  workflow_dispatch:
+    inputs:
+      checkout_sha:
+        description: "Commit SHA to benchmark (blank = branch HEAD)"
+        required: false
+        default: ""
+      iterations:
+        description: "Requests per run"
+        required: false
+        default: "100"
+      runs:
+        description: "Timed runs per journey"
+        required: false
+        default: "3"
+      sessions:
+        description: "Seeded sessions"
+        required: false
+        default: "5000"
+      items_per_session:
+        description: "Seeded items per session"
+        required: false
+        default: "200"
+
+permissions:
+  contents: read
+
+env:
+  # No web SPA build during `uv sync` (setup.py _build_web_ui): this job never
+  # serves the bundle, and the build otherwise times out on public npm.
+  OMNIGENT_SKIP_WEB_UI: "true"
+  UV_INDEX_URL: https://pypi.org/simple
+  PIP_INDEX_URL: https://pypi.org/simple
+  ITERATIONS: ${{ github.event_name == 'workflow_dispatch' && inputs.iterations || '100' }}
+  RUNS: ${{ github.event_name == 'workflow_dispatch' && inputs.runs || '3' }}
+  SESSIONS: ${{ github.event_name == 'workflow_dispatch' && inputs.sessions || '5000' }}
+  ITEMS: ${{ github.event_name == 'workflow_dispatch' && inputs.items_per_session || '200' }}
+
+concurrency:
+  # Never cancel a scheduled run mid-flight (each is a distinct data point).
+  # Manual dispatches get a per-run group (unique run_id) so repeated ad-hoc
+  # runs — even on the same ref and same pinned sha — never cancel each other.
+  group: benchmark-${{ github.event_name }}-${{ github.ref }}-${{ github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'workflow_dispatch' }}
+
+jobs:
+  benchmark:
+    name: Run benchmark (${{ matrix.backend }})
+    if: github.repository == 'omnigent-ai/omnigent'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        backend: [sqlite, postgres, mysql]
+    services:
+      # The Postgres and MySQL services are defined unconditionally (GitHub
+      # Actions has no per-matrix-value service gating); each leg connects only
+      # to its own backend and ignores the others. postgres:16 mirrors
+      # Lakebase's major version; mysql:8.0 matches the stores-mysql CI lane.
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: bench
+          POSTGRES_DB: benchdb
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_ROOT_PASSWORD: bench
+          MYSQL_DATABASE: benchdb
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd "mysqladmin ping -h 127.0.0.1 -u root -pbench"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+          # Pin the benchmarked code to a specific commit when dispatched with
+          # checkout_sha; the workflow definition still comes from the trusted
+          # dispatch ref. Blank falls back to the ref's HEAD (schedule/default).
+          ref: ${{ inputs.checkout_sha || github.sha }}
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version-file: ".python-version"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v3
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        # `databricks` extra carries psycopg[binary] for the Postgres backend.
+        run: uv sync --extra dev --extra databricks
+
+      - name: Install MySQL driver
+        # mysqlclient (mysql+mysqldb://) needs the system client library and is
+        # not in any extra, so install it only on the mysql leg. Matches the
+        # stores-mysql lane in ci.yml.
+        if: matrix.backend == 'mysql'
+        run: |
+          sudo apt-get update -qq && sudo apt-get install -y -q libmysqlclient-dev
+          uv pip install mysqlclient
+
+      # Resolve the DB URI + a stable seed-cache key for this backend. The
+      # cache key binds the DB schema head + seed.py contents + corpus config,
+      # so a schema change or seed edit busts the cache and forces a reseed —
+      # the "you changed the schema, refresh the seed" contract (SQLite only;
+      # the Postgres/MySQL services are fresh each run so their DB is never
+      # cached).
+      - name: Resolve DB target
+        id: db
+        run: |
+          HEAD="$(uv run --no-sync dev/benchmarks/omnigent/seed.py --print-head)"
+          if [[ "${{ matrix.backend }}" == "postgres" ]]; then
+            echo "uri=postgresql+psycopg://postgres:bench@localhost:5432/benchdb" >> "$GITHUB_OUTPUT"
+            echo "cache_path=" >> "$GITHUB_OUTPUT"
+          elif [[ "${{ matrix.backend }}" == "mysql" ]]; then
+            echo "uri=mysql+mysqldb://root:bench@127.0.0.1:3306/benchdb" >> "$GITHUB_OUTPUT"
+            echo "cache_path=" >> "$GITHUB_OUTPUT"
+          else
+            echo "uri=sqlite:///$PWD/bench.db" >> "$GITHUB_OUTPUT"
+            echo "cache_path=bench.db" >> "$GITHUB_OUTPUT"
+          fi
+          echo "cache_key=benchdb-${{ matrix.backend }}-$HEAD-${SESSIONS}x${ITEMS}-${{ hashFiles('dev/benchmarks/omnigent/seed.py') }}" >> "$GITHUB_OUTPUT"
+
+      # Reuse a previously-seeded SQLite corpus when schema + seed + config are
+      # unchanged. No-op for the server-backed legs (empty path).
+      - name: Restore seeded SQLite corpus
+        if: matrix.backend == 'sqlite'
+        id: seedcache
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v4
+        with:
+          path: ${{ steps.db.outputs.cache_path }}
+          key: ${{ steps.db.outputs.cache_key }}
+
+      - name: Seed corpus
+        # The fresh-service backends (postgres, mysql) always seed; SQLite seeds
+        # only on a cache miss. seed.py is itself idempotent, so a stray hit is
+        # harmless.
+        if: matrix.backend != 'sqlite' || steps.seedcache.outputs.cache-hit != 'true'
+        run: |
+          uv run --no-sync dev/benchmarks/omnigent/seed.py \
+            --database-uri "${{ steps.db.outputs.uri }}" \
+            --sessions "$SESSIONS" --items-per-session "$ITEMS"
+
+      - name: Run benchmark
+        run: |
+          uv run --no-sync dev/benchmarks/omnigent/run.py \
+            --database-uri "${{ steps.db.outputs.uri }}" \
+            --iterations "$ITERATIONS" \
+            --runs "$RUNS" \
+            --output "benchmark-results-${{ matrix.backend }}.json"
+
+      - name: Upload benchmark results
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: always()
+        with:
+          name: benchmark-results-${{ matrix.backend }}-${{ github.run_id }}
+          path: benchmark-results-${{ matrix.backend }}.json
+          retention-days: 90
+          if-no-files-found: warn

.github/workflows/bump-version.yml

@@ -12,9 +12,11 @@ name: Bump Version
 # this workflow wraps it with `uv lock`, a consistency check, and an
 # auto-opened PR.
 #
-# NOTE: the PR is created with GITHUB_TOKEN, so by GitHub policy it does
-# NOT trigger other workflows (CI won't auto-run on it). Push an empty
-# commit or re-open the PR to kick CI, or swap in a PAT if that matters.
+# NOTE: when the omnigent-ci App is configured (vars.OMNIGENT_BOT_APP_ID),
+# the branch is pushed and the PR opened with a short-lived App token, so CI
+# runs on the bump PR automatically. Without it (e.g. in forks) the
+# GITHUB_TOKEN fallback applies and, by GitHub policy, CI does NOT auto-run —
+# re-open the PR or push to it to kick CI.
 
 on:
   workflow_dispatch:
@@ -87,9 +89,21 @@ jobs:
       - name: Verify all locations agree
         run: uv run --no-project --python 3.12 --with packaging python scripts/update_versions.py check
 
+      # A bump PR pushed by the App identity gets CI runs; a GITHUB_TOKEN push
+      # would not (GitHub suppresses events from GITHUB_TOKEN-authored pushes).
+      - name: Mint App token (omnigent)
+        id: app-token
+        if: vars.OMNIGENT_BOT_APP_ID != ''
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ vars.OMNIGENT_BOT_APP_ID }}
+          private-key: ${{ secrets.OMNIGENT_BOT_APP_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: omnigent
+
       - name: Open bump PR
         env:
-          GH_TOKEN: ${{ github.token }}
+          GH_TOKEN: ${{ steps.app-token.outputs.token || github.token }}
           MODE: ${{ github.event.inputs.mode }}
           NEW_VERSION: ${{ github.event.inputs.new_version }}
           BASE: ${{ github.event.inputs.base_branch }}
@@ -109,6 +123,9 @@ jobs:
             exit 0
           fi
           git commit -s -m "Bump version to ${resolved}"
+          # Push with the same token that opens the PR (see the App-token
+          # note above); the checkout's persisted credential is GITHUB_TOKEN.
+          git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
           git push --force-with-lease origin "$branch"
 
           existing="$(gh pr list --head "$branch" --base "$BASE" --json number --jq '.[0].number')"
@@ -124,4 +141,4 @@ jobs:
 
           Rewrote \`[project].version\` and sibling \`==\` pins across all three packages (\`pyproject.toml\`, \`sdks/python-client\`, \`sdks/ui\`), the runtime \`VERSION\` constant in \`omnigent/version.py\`, and regenerated \`uv.lock\`.
 
-          Generated by \`scripts/update_versions.py\`. CI does not auto-trigger on GITHUB_TOKEN PRs — re-open or push to run it."
+          Generated by \`scripts/update_versions.py\`. Opened via the omnigent-ci App when configured (CI runs automatically); on the GITHUB_TOKEN fallback, re-open or push to kick CI."

.github/workflows/ci.yml

@@ -2,20 +2,24 @@ name: CI
 
 # Unit-test pytest matrix on every non-draft PR and on push to main. Tests are
 # split across directory-based matrix groups (runtime-*, server-*, inner-rest,
-# tools, repl-sdk, spec-llms, misc) so slow files don't bottleneck one runner;
-# the slowest groups use `--dist=worksteal` to fan tests out within a file. The
-# `misc` group is a catch-all so new top-level tests/<dir>/ are picked up
-# automatically. Draft PRs are skipped (ready_for_review re-fires the workflow).
+# tools, repl-sdk, spec-llms, runner-app, stores, misc) so slow files don't
+# bottleneck one runner; the slowest groups use `--dist=worksteal` to fan tests
+# out within a file. The `misc` group is a catch-all so new top-level
+# tests/<dir>/ are picked up automatically (it ignores the dirs that have their
+# own group). Draft PRs are skipped (ready_for_review re-fires the workflow).
 # A `coverage-report` job combines per-shard coverage for code-coverage.yml.
 
 on:
   pull_request:
     types: [opened, synchronize, reopened, ready_for_review]
-    paths-ignore: ['web/**', 'tests/e2e_ui/**']
+    paths-ignore: ['web/**', 'tests/e2e_ui/**', 'CHANGELOG.md']
   push:
     branches:
       - main
-    paths-ignore: ['web/**', 'tests/e2e_ui/**']
+      # Release branches: release.yml's green-CI gate reads check runs off the
+      # branch head, so cherry-picks and release-bump commits must run CI.
+      - 'release/v[0-9]*'
+    paths-ignore: ['web/**', 'tests/e2e_ui/**', 'CHANGELOG.md']
 
 permissions:
   contents: read
@@ -94,7 +98,21 @@ jobs:
           - group: integration-mock
             paths: tests/integration
             workers: "0"
+          # Carved out of misc: runner + stores were ~68% of misc's cpu and
+          # under loadfile a single 500s+ file (test_app_sessions_native) pinned
+          # one worker and set the whole misc wall time. worksteal fans each
+          # dir's tests across workers (biggest single test is ~40s / ~5s, so
+          # the floor drops from ~500s to ~100s). Both dirs' conftests are
+          # function-scoped, so splitting a file across workers is safe.
+          - group: runner-app
+            paths: tests/runner
+            dist: worksteal
+          - group: stores
+            paths: tests/stores
+            dist: worksteal
           # Catch-all so new top-level tests/<dir>/ are covered automatically.
+          # worksteal keeps the biggest remaining file (the benchmark smoke
+          # test, ~58s) from re-pinning one worker as this catch-all grows.
           - group: misc
             paths: >-
               tests
@@ -112,6 +130,9 @@ jobs:
               --ignore=tests/spec
               --ignore=tests/llms
               --ignore=tests/codex_parity
+              --ignore=tests/runner
+              --ignore=tests/stores
+            dist: worksteal
           # Databricks-coupled tests (Lakebase token engine, psycopg). This is
           # the only lane that installs the `databricks` extra; the
           # @pytest.mark.databricks marker keeps these tests off the lean lanes
@@ -204,6 +225,100 @@ jobs:
           retention-days: 14
           include-hidden-files: true  # the per-shard .coverage.<group> dotfile
 
+  stores-postgres:
+    name: Pytest (stores-postgres)
+    needs: gate
+    if: ${{ !github.event.pull_request.draft }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: omnigent
+          POSTGRES_DB: omnigent_root
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+        with:
+          python-version-file: ".python-version"
+      - uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --locked --extra all --extra dev --extra databricks
+      - name: Run store + DB tests against PostgreSQL
+        env:
+          OMNIGENT_TEST_DB_URI: postgresql+psycopg://postgres:omnigent@localhost:5432/omnigent_root
+        run: |
+          uv run pytest tests/stores tests/db \
+            -m "not databricks" \
+            -n 4 \
+            --dist=loadfile \
+            --timeout=300 \
+            --junitxml=artifacts/pytest-stores-postgres.xml
+      - if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+        with:
+          name: pytest-stores-postgres-${{ github.run_id }}
+          path: artifacts/
+          retention-days: 14
+
+  stores-mysql:
+    name: Pytest (stores-mysql)
+    needs: gate
+    if: ${{ !github.event.pull_request.draft }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    services:
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_ROOT_PASSWORD: omnigent
+          MYSQL_DATABASE: omnigent_root
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd "mysqladmin ping -h 127.0.0.1 -u root -pomnigent"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+        with:
+          python-version-file: ".python-version"
+      - uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a
+        with:
+          enable-cache: true
+      - name: Install system MySQL client library
+        run: sudo apt-get update -qq && sudo apt-get install -y -q libmysqlclient-dev
+      - name: Install dependencies
+        run: uv sync --locked --extra all --extra dev --extra databricks && uv pip install mysqlclient
+      - name: Run store + DB tests against MySQL
+        env:
+          OMNIGENT_TEST_DB_URI: mysql+mysqldb://root:omnigent@127.0.0.1:3306/omnigent_root
+        run: |
+          uv run pytest tests/stores tests/db \
+            -m "not databricks" \
+            -n 4 \
+            --dist=loadfile \
+            --timeout=300 \
+            --junitxml=artifacts/pytest-stores-mysql.xml
+      - if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+        with:
+          name: pytest-stores-mysql-${{ github.run_id }}
+          path: artifacts/
+          retention-days: 14
+
   codex-parity:
     name: Pytest (codex-parity)
     needs: gate

.github/workflows/discord-watch-rotation-maintain.yml

@@ -0,0 +1,54 @@
+name: Discord watch rotation - maintain schedule
+
+# Monthly housekeeping for rotation_schedule.json: prune elapsed dates and
+# extend the horizon ~3 months out. Opens a PR rather than pushing to main, so
+# the change is reviewable and no write to a protected branch is needed.
+on:
+  schedule:
+    - cron: "0 8 1 * *" # 08:00 UTC on the 1st of each month
+  workflow_dispatch: {} # manual "Run workflow" button
+
+# Needs to push a branch and open a PR; no other write scope.
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: discord-watch-rotation-maintain
+  cancel-in-progress: false
+
+jobs:
+  extend:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - name: Update schedule
+        id: update
+        run: |
+          if python3 .github/scripts/rotation_maintain.py; then
+            if git diff --quiet -- .github/scripts/rotation_schedule.json; then
+              echo "changed=false" >> "$GITHUB_OUTPUT"
+            else
+              echo "changed=true" >> "$GITHUB_OUTPUT"
+            fi
+          else
+            echo "Schedule maintenance failed" >&2
+            exit 1
+          fi
+      - name: Open PR
+        if: steps.update.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          branch="rotation-schedule-$(date -u +%Y%m%d)"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$branch"
+          git add .github/scripts/rotation_schedule.json
+          git commit -m "chore(ci): extend Discord watch rotation schedule"
+          git push -u origin "$branch"
+          gh pr create \
+            --base main \
+            --head "$branch" \
+            --title "chore(ci): extend Discord watch rotation schedule" \
+            --body "Automated monthly housekeeping: pruned elapsed dates and extended \`rotation_schedule.json\` ~3 months out. Generated by the discord-watch-rotation-maintain workflow."

.github/workflows/discord-watch-rotation.yml

@@ -0,0 +1,32 @@
+name: Discord watch rotation
+
+# Wakes up only at the UTC times that are ~08:00 in an assignee's timezone.
+# Note: a single fixed UTC time can't track San Francisco's daylight saving,
+# so the SF ping lands at 08:00 in summer (PDT) and 07:00 in winter (PST).
+on:
+  schedule:
+    - cron: "0 0 * * *" # 08:00 Asia/Singapore (UTC+8, no daylight saving)
+    - cron: "0 15 * * *" # 08:00 SF in summer (PDT); 07:00 in winter (PST)
+  workflow_dispatch: {} # manual "Run workflow" button for testing
+
+# Only needs to check out the repo; nothing is written back.
+permissions:
+  contents: read
+
+# Avoid overlapping runs if one is slow.
+concurrency:
+  group: discord-watch-rotation
+  cancel-in-progress: false
+
+jobs:
+  ping:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12" # for zoneinfo in the stdlib
+      - name: Send rotation ping
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+        run: python .github/scripts/rotation.py

.github/workflows/doc-sync.yml

@@ -598,6 +598,22 @@ jobs:
           m = re.search(r"<!--\s*DOC_DRAFT_SUMMARY\s*-->", raw)
           summary = raw[m.end():].strip() if m else "_(drafter produced edits but no summary)_"
 
+          # Title the docs PR after the DOCS change, not the source PR number (which
+          # already appears in the body). Prefer the drafter's DOC_PR_TITLE line; fall
+          # back to the source PR title, then to the old "document #N" form. LLM output
+          # is untrusted, so sanitize: first line only, strip control chars, collapse
+          # whitespace, drop a stray leading "docs:" (added below), and cap length.
+          mt = re.search(r"^\s*DOC_PR_TITLE:\s*(.+?)\s*$", raw, re.MULTILINE)
+          # Collapse whitespace (incl. tabs) to single spaces FIRST, so a stray tab
+          # separates words rather than being stripped and joining them, then drop
+          # any remaining non-whitespace control chars.
+          draft_title = re.sub(r"\s+", " ", mt.group(1) if mt else "").strip()
+          draft_title = re.sub(r"[\x00-\x1f\x7f]", "", draft_title)
+          draft_title = re.sub(r"^docs:\s*", "", draft_title, flags=re.IGNORECASE).strip()[:60].strip()
+          pr_title = f"docs: {draft_title or title or f'document {code}#{pr}'}"
+          pathlib.Path("/tmp/site_pr_title.txt").write_text(pr_title)
+          print(f"pr_title={pr_title!r}")
+
           # Tag the maintainer who MERGED the PR — the author may be an outside
           # contributor with no site access, but a maintainer always merges. Fall back
           # to the author when there's no usable merger (e.g. a manual run on an
@@ -644,6 +660,10 @@ jobs:
         run: |
           set -euo pipefail
           BRANCH="auto/docs/pr-${PR_NUMBER}"
+          # Descriptive PR/commit title from the sitepr step (drafter's DOC_PR_TITLE,
+          # else the source PR title, else "docs: document #N"). The PR number lives
+          # in the body, so it's kept out of the title.
+          PR_TITLE="$(cat /tmp/site_pr_title.txt)"
           git config user.name  "omnigent-ci[bot]"
           git config user.email "294685417+omnigent-ci[bot]@users.noreply.github.com"
           # Credentials are NOT persisted in .git/config (so the unsandboxed drafter
@@ -686,7 +706,7 @@ jobs:
 
           git checkout -B "$BRANCH"
           git add -A
-          git commit -m "docs: document ${CODE_REPO}#${PR_NUMBER}"
+          git commit -m "$PR_TITLE"
           # --force is safe here: the guard above ensured the branch carries only
           # bot commits.
           git push --force "$PUSH_URL" "$BRANCH"
@@ -705,12 +725,13 @@ jobs:
             # --add-label backfills PRs opened before the label existed; it's a no-op
             # when already present.
             gh pr edit "$EXISTING" --repo "$SITE_REPO_SLUG" \
+              --title "$PR_TITLE" \
               --add-label "automated-docs" --add-label "$VERSION_LABEL" \
               --body-file /tmp/site_pr_body.md || true
             echo "Updated site PR #$EXISTING."
           else
             if gh pr create --repo "$SITE_REPO_SLUG" --base "$DOCS_BRANCH" --head "$BRANCH" \
-                --title "docs: document ${CODE_REPO}#${PR_NUMBER}" \
+                --title "$PR_TITLE" \
                 --label automated-docs --label "$VERSION_LABEL" --body-file /tmp/site_pr_body.md; then
               EXISTING="$(gh pr list --repo "$SITE_REPO_SLUG" --head "$BRANCH" --state open \
                   --json number --jq '.[0].number // empty' 2>/dev/null || true)"

.github/workflows/docker-build.yml

@@ -0,0 +1,81 @@
+# Build-only Docker check for PRs. Compensates for retiring per-commit main
+# publishes (oss-publish-images.yml now builds on tags + nightly only): a broken
+# Dockerfile / lockfile / frontend build would otherwise not surface until the
+# nightly rebuild or a release. Builds the server image single-arch (linux/amd64)
+# with the GHA layer cache and runs a `omnigent --help` CLI smoke. It never pushes.
+#
+# Scope: the server target exercises the shared builder stage (Python deps +
+# web SPA build) that all four published variants inherit, so it catches the
+# common breakage without paying for the host/openshell/kubernetes variants or
+# the emulated arm64 leg.
+#
+# Blocking merge-gate check: "Docker build" is in the REQUIRED list in
+# .github/scripts/merge-ready/required.sh. Because of the paths filter below it
+# can legitimately be absent (a PR touching nothing in the image), so it is also
+# in ALLOW_SKIP with a workflow_for() arm, and this workflow's name is in
+# merge-ready.yml's workflow_run list so the gate re-evaluates when it completes.
+name: Docker build
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    # Only build when something that lands in the image changes. Mirrors the
+    # publish workflow's former push paths (web/** IS included here — the image
+    # bakes the SPA, so a web-only PR can still break the build).
+    paths:
+      - 'deploy/docker/Dockerfile'
+      - 'deploy/docker/entrypoint.py'
+      - 'omnigent/**'
+      - 'web/**'
+      - 'sdks/**'
+      - 'pyproject.toml'
+      - 'setup.py'
+      - 'uv.lock'
+      - 'web/package-lock.json'
+      - '.github/workflows/docker-build.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docker-build-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  # Security precondition gate (security-gate.yml): untrusted PRs wait for the
+  # scan before the build runs on their code; trusted authors pass through.
+  gate:
+    uses: ./.github/workflows/security-gate.yml
+
+  build:
+    name: Docker build
+    needs: gate
+    # Draft PRs skip the build (ready_for_review re-fires the workflow), matching
+    # the pytest job in ci.yml.
+    if: ${{ !github.event.pull_request.draft }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
+
+      # Single-arch (amd64) build, no push. load: true imports the result into
+      # the runner's Docker so the smoke step below can run it. Shares the same
+      # type=gha cache the publish workflow writes, so warm PRs reuse layers.
+      - name: Build server image (amd64, no push)
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf  # v7.2.0
+        with:
+          context: .
+          file: deploy/docker/Dockerfile
+          push: false
+          load: true
+          tags: omnigent-server:pr-${{ github.event.pull_request.number || github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: false
+
+      - name: CLI smoke
+        run: docker run --rm omnigent-server:pr-${{ github.event.pull_request.number || github.sha }} omnigent --help

.github/workflows/draft-release-notes.yml

@@ -409,13 +409,38 @@ jobs:
           RELEASE_ID: ${{ steps.release.outputs.release_id }}
         run: |
           set -euo pipefail
+          # Always end the notes with the community thanks. The AI drafter curates
+          # freely (and can drop a hand-added line), so this is appended here rather
+          # than via the prompt — every release, AI-drafted or mechanical fallback,
+          # gets it. Idempotent, and placed just before the trailing "Full Changelog:"
+          # link to match the layout of prior releases.
+          python3 - <<'PYEOF'
+          import pathlib
+          NOTE = (
+              "### 💜 Thanks to our community\n\n"
+              "This release was shaped by the people who filed issues, opened PRs, and "
+              "talked through feature requests with us on our Discord! Thank you for "
+              "building omnigent with us, keep the bug reports, ideas and contributions "
+              "coming :)"
+          )
+          path = pathlib.Path("/tmp/release_notes.md")
+          text = path.read_text(encoding="utf-8").rstrip("\n")
+          if "Thanks to our community" not in text:
+              idx = text.find("\nFull Changelog:")
+              if idx != -1:
+                  head, tail = text[:idx].rstrip("\n"), text[idx:].lstrip("\n")
+                  text = f"{head}\n\n{NOTE}\n\n{tail}"
+              else:
+                  text = f"{text}\n\n{NOTE}"
+              path.write_text(text + "\n", encoding="utf-8")
+          PYEOF
           # github-release.yml seeds only a short placeholder body (no
           # auto-generated notes), so replace it wholesale with the curated notes.
           # Edit by release ID: a draft release can't be addressed by tag (the
           # get/edit-by-tag REST endpoint 404s until the release is published).
           gh api --method PATCH "repos/${SOURCE_REPO}/releases/${RELEASE_ID}" \
             --field body=@/tmp/release_notes.md > /dev/null
-          echo "Enriched the ${TAG} release draft with curated notes." \
+          echo "Enriched the ${TAG} release draft with curated notes + community note." \
             | tee -a "$GITHUB_STEP_SUMMARY"
 
       # ::add-mask:: redacts rendered logs, not artifact files — scrub the key

.github/workflows/e2e-ui.yml

@@ -18,6 +18,7 @@ on:
     # Security Gate via rerun-security-gate.yml, so label churn need not re-run
     # the heavy Playwright suite. (#399 added these for the gate; superseded.)
     types: [opened, synchronize, reopened, ready_for_review]
+    paths-ignore: ['CHANGELOG.md']
   schedule:
     - cron: "0 9 * * *"
   workflow_dispatch:

.github/workflows/e2e.yml

@@ -23,7 +23,7 @@ on:
     # (rerun-security-gate-run.yml falls back to this trigger). The concurrency
     # group key isolates label events so they never cancel a code-push run.
     types: [opened, synchronize, reopened, ready_for_review, labeled, unlabeled]
-    paths-ignore: ['web/**', 'tests/e2e_ui/**']
+    paths-ignore: ['web/**', 'tests/e2e_ui/**', 'CHANGELOG.md']
   workflow_dispatch:
     inputs:
       branch:

.github/workflows/electron-build.yml

@@ -0,0 +1,88 @@
+name: Electron Build
+
+# Manually-triggered build of the Electron desktop shell (web/electron) for
+# Linux and Windows. Each platform packages on its own native runner —
+# electron-builder does not reliably cross-compile installers — and uploads the
+# installers as downloadable workflow artifacts. Unsigned: no signing creds are
+# wired here, so `CSC_IDENTITY_AUTO_DISCOVERY=false` forces an unsigned build
+# rather than failing when a cert is absent. No publishing / release upload.
+#
+# Run it from the Actions tab (Run workflow). macOS is intentionally omitted —
+# its signed/notarized build lives elsewhere.
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Branch, tag, or SHA to build."
+        required: false
+        default: ""
+
+permissions:
+  contents: read
+
+concurrency:
+  # One build per ref: back-to-back manual dispatches on the same ref queue
+  # instead of running concurrently (keyed on ref only — including run_id would
+  # make every run its own group, defeating the serialization).
+  group: electron-build-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build (${{ matrix.platform }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      # Keep building the other platform even if one fails, so a Windows-only
+      # break still yields the Linux installers (and vice versa).
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            platform: linux
+            build-script: build:linux
+          - os: windows-latest
+            platform: win
+            build-script: build:win
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          ref: ${{ github.event.inputs.ref || github.ref }}
+
+      - name: Set up Node
+        uses: ./.github/actions/setup-node
+        with:
+          # Node 22.x per web/electron/README.md ("Prerequisites").
+          node-version: "22"
+          cache-dependency-path: web/electron/package-lock.json
+
+      - name: Install dependencies
+        working-directory: web/electron
+        run: npm ci --no-audit --no-fund
+
+      - name: Build ${{ matrix.platform }} app
+        working-directory: web/electron
+        env:
+          # No signing credentials in CI: force an unsigned build instead of
+          # letting electron-builder fail hunting for a certificate.
+          CSC_IDENTITY_AUTO_DISCOVERY: "false"
+          # electron-builder downloads Electron/tooling from GitHub; the token
+          # lifts the anonymous rate limit that otherwise flakes downloads.
+          GH_TOKEN: ${{ github.token }}
+        run: npm run ${{ matrix.build-script }} -- --publish never
+
+      - name: Upload installers
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: omnigent-desktop-${{ matrix.platform }}
+          # Ship only the distributables, not electron-builder's unpacked
+          # intermediates (dist/linux-unpacked, dist/win-unpacked, blockmaps).
+          path: |
+            web/electron/dist/*.AppImage
+            web/electron/dist/*.deb
+            web/electron/dist/*.exe
+          if-no-files-found: error
+          retention-days: 14

.github/workflows/feature-blog.yml

@@ -0,0 +1,590 @@
+name: Draft feature blogs
+
+# At release CUT (a vX.Y.Z tag is pushed → the "GitHub Release" workflow creates
+# the draft), look over the release's features and DRAFT a feature-blog post on
+# omnigent-site for each one big enough to warrant it — usually none. Blog drafts
+# land alongside the release-notes draft (draft-release-notes.yml, same trigger)
+# so a maintainer reviews both together.
+#
+# Two agents, both running on already-released history from the trusted default
+# branch:
+#   1. feature-blog-scout   — no tools; picks 0–N blog-worthy features (ranked,
+#      capped at 3) from the same PR-range material draft-release-notes.yml
+#      harvests. Most releases → [].
+#   2. feature-blog-drafter — file access; writes one post per selected feature
+#      into an omnigent-site checkout. The workflow opens a DRAFT PR per post.
+#
+# Why `workflow_run` (not extending github-release.yml): that workflow runs NO
+# project code, only `gh release create`, so a malicious tagged commit can't
+# execute anything. We keep that guarantee by running the heavy work (LLM + git
+# harvest) here, from the trusted default branch (workflow_run always does), never
+# from the tagged commit. Same posture as draft-release-notes.yml.
+#
+# The LLM machinery (creds gate, Claude Code CLI, provider config, secret-scan,
+# token-minted-after-agents, artifact redaction) mirrors draft-release-notes.yml.
+# The output is always a DRAFT PR — the mandatory demo (a real recording/
+# screenshot) and hero art / byline are added by a human before merge.
+
+on:
+  workflow_run:
+    workflows: ["GitHub Release"]
+    types: [completed]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag to draft blogs for, e.g. v0.3.0
+        required: true
+        type: string
+      base:
+        description: >-
+          Optional range-start override (tag/branch/sha). Needed when `tag` is
+          not a final vX.Y.Z. Providing it makes the run a preview unless
+          dry_run=false.
+        required: false
+        type: string
+      dry_run:
+        description: >-
+          Preview only:
+          auto (default) - preview for dev/rc tags, real PRs for final versions;
+          true - run the scout/drafter, print output, don't open PRs;
+          false - open real DRAFT PRs.
+        required: false
+        type: choice
+        options: [auto, "true", "false"]
+        default: auto
+
+permissions:
+  contents: read
+
+concurrency:
+  group: feature-blog-${{ github.event.workflow_run.head_branch || inputs.tag }}
+  cancel-in-progress: false
+
+env:
+  SOURCE_REPO: omnigent-ai/omnigent
+  OMNIGENT_SKIP_WEB_UI: "true"
+  UV_INDEX_URL: https://pypi.org/simple
+  PIP_INDEX_URL: https://pypi.org/simple
+
+jobs:
+  draft:
+    name: Scout features and draft blogs
+    if: >-
+      github.repository == 'omnigent-ai/omnigent' &&
+      (github.event_name == 'workflow_dispatch' ||
+       github.event.workflow_run.conclusion == 'success')
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      # --- Resolve the tag and decide whether to proceed (no code run yet) ---
+      - name: Resolve tag and guard
+        id: guard
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          # On tag push, workflow_run.head_branch is the tag name (v0.3.0).
+          RUN_BRANCH: ${{ github.event.workflow_run.head_branch }}
+          INPUT_TAG: ${{ inputs.tag }}
+          INPUT_BASE: ${{ inputs.base }}
+          INPUT_DRY_RUN: ${{ inputs.dry_run }}
+        run: |
+          set -euo pipefail
+          tag="${INPUT_TAG:-$RUN_BRANCH}"
+          base="${INPUT_BASE:-}"
+          proceed=false; dry_run=false
+
+          # Does the tag look like a final release (vX.Y.Z, not rc/dev/alpha/beta)?
+          is_version=true
+          case "$tag" in
+            v[0-9]*.[0-9]*.[0-9]*) ;;
+            *) is_version=false ;;
+          esac
+          case "$tag" in
+            *rc*|*dev*|*a[0-9]*|*b[0-9]*) is_version=false ;;
+          esac
+
+          if [ "$EVENT_NAME" = "workflow_run" ]; then
+            # Real release cut: strict — only a final version tag proceeds.
+            [ "$is_version" = "true" ] && proceed=true
+          else
+            # Manual dispatch: proceed for a final version tag OR when a base
+            # override is given (arbitrary-ref preview/real run).
+            if [ "$is_version" = "true" ] || [ -n "$base" ]; then
+              proceed=true
+            fi
+            case "$INPUT_DRY_RUN" in
+              true)  dry_run=true ;;
+              false) dry_run=false ;;
+              *)     if [ "$is_version" != "true" ] || [ -n "$base" ]; then dry_run=true; fi ;;
+            esac
+          fi
+
+          echo "tag=${tag}" >> "$GITHUB_OUTPUT"
+          echo "base=${base}" >> "$GITHUB_OUTPUT"
+          echo "proceed=${proceed}" >> "$GITHUB_OUTPUT"
+          echo "dry_run=${dry_run}" >> "$GITHUB_OUTPUT"
+          echo "Resolved tag=${tag} base=${base:-<none>} proceed=${proceed} dry_run=${dry_run}" \
+            | tee -a "$GITHUB_STEP_SUMMARY"
+
+      # Trusted default branch, full history + tags for the range computation.
+      - name: Checkout omnigent (main)
+        if: steps.guard.outputs.proceed == 'true'
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: main
+          fetch-depth: 0
+          fetch-tags: true
+          persist-credentials: false
+
+      - name: Set up Python
+        if: steps.guard.outputs.proceed == 'true'
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.11"
+
+      # --- Credentials gate: no LLM key → nothing to draft, exit cleanly ---
+      - name: Check LLM credentials
+        id: creds
+        if: steps.guard.outputs.proceed == 'true'
+        env:
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+        run: |
+          if [ -z "${LLM_API_KEY:-}" ]; then
+            echo "::warning::No LLM credentials — skipping feature-blog drafting."
+            echo "available=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "::add-mask::${LLM_API_KEY}"
+            echo "available=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      # --- Harvest the same PR-range material as draft-release-notes.yml ---
+      - name: Harvest PR material
+        id: harvest
+        if: steps.guard.outputs.proceed == 'true' && steps.creds.outputs.available == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.guard.outputs.tag }}
+          BASE: ${{ steps.guard.outputs.base }}
+        run: |
+          set -euo pipefail
+          python3 -m pip install --quiet --disable-pip-version-check packaging
+          args=(--tag "$TAG" --repo "$SOURCE_REPO"
+                --draft-notes-out /tmp/mechanical_notes.md
+                --pr-list-out /tmp/pr_list.txt
+                --no-changelog-update)
+          [ -n "${BASE:-}" ] && args+=(--base "$BASE")
+          python3 .github/scripts/changelog/generate.py "${args[@]}"
+
+      - name: Set up uv
+        if: steps.guard.outputs.proceed == 'true' && steps.creds.outputs.available == 'true'
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+
+      - name: Cache virtualenv
+        if: steps.guard.outputs.proceed == 'true' && steps.creds.outputs.available == 'true'
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-${{ hashFiles('.python-version') }}-${{ hashFiles('uv.lock') }}
+
+      - name: Install dependencies
+        if: steps.guard.outputs.proceed == 'true' && steps.creds.outputs.available == 'true'
+        run: uv sync --extra all --extra dev
+
+      - name: Install Claude Code CLI
+        if: steps.guard.outputs.proceed == 'true' && steps.creds.outputs.available == 'true'
+        env:
+          NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
+        run: |
+          mkdir -p "${GITHUB_WORKSPACE}/.cc-cli" && cd "${GITHUB_WORKSPACE}/.cc-cli"
+          npm install --ignore-scripts --no-audit --no-fund @anthropic-ai/claude-code@2.1.170
+          node node_modules/@anthropic-ai/claude-code/install.cjs
+          echo "${GITHUB_WORKSPACE}/.cc-cli/node_modules/.bin" >> "$GITHUB_PATH"
+
+      - name: Write Omnigent provider config
+        if: steps.guard.outputs.proceed == 'true' && steps.creds.outputs.available == 'true'
+        env:
+          GATEWAY_BASE_URL: ${{ secrets.GATEWAY_BASE_URL }}
+        run: |
+          mkdir -p "$HOME/.omnigent"
+          python3 -c "
+          import pathlib, os, json
+          gw = os.environ['GATEWAY_BASE_URL']
+          cfg = {'providers': {'databricks-gateway': {
+              'kind': 'gateway', 'default': ['anthropic'],
+              'anthropic': {
+                  'base_url': gw + '/anthropic',
+                  'api_key_ref': 'env:LLM_API_KEY',
+                  'models': {'default': 'databricks-claude-opus-4-8'},
+              }}}}
+          pathlib.Path.home().joinpath('.omnigent', 'config.yaml').write_text(json.dumps(cfg, indent=2))
+          "
+
+      # --- 1) Scout: which features (if any) are blog-worthy? ---
+      - name: Build scout prompt
+        if: steps.guard.outputs.proceed == 'true' && steps.creds.outputs.available == 'true'
+        env:
+          TAG: ${{ steps.guard.outputs.tag }}
+        run: |
+          set -euo pipefail
+          python3 -u <<'PYEOF'
+          import os, pathlib
+          tag = os.environ["TAG"]
+          # `omnigent run -p` passes the whole prompt as one argv string, capped at
+          # ~128 KiB on Linux. Cap the PR list well under that.
+          MAX = 100_000
+          pr_list = pathlib.Path("/tmp/pr_list.txt").read_text(encoding="utf-8", errors="replace")
+          mech = pathlib.Path("/tmp/mechanical_notes.md").read_text(encoding="utf-8", errors="replace")
+          truncated = len(pr_list) > MAX
+          pr_list = pr_list[:MAX]
+          note = ("\n> NOTE: the PR list was truncated — select from what's visible.\n"
+                  if truncated else "")
+          prompt = f"""Select the blog-worthy features (if any) from {tag}.
+          {note}
+          ## Merged PRs (number, title, and author changelog entries)
+          {pr_list}
+
+          ## Mechanical draft (features grouped into sections — raw material)
+          {mech}
+
+          Produce the BLOG_CANDIDATES block per your instructions."""
+          pathlib.Path("/tmp/scout_prompt.txt").write_text(prompt)
+          PYEOF
+
+      - name: Run feature-blog scout
+        id: scout
+        if: steps.guard.outputs.proceed == 'true' && steps.creds.outputs.available == 'true'
+        env:
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+        run: |
+          set -euo pipefail
+          prompt="$(cat /tmp/scout_prompt.txt)"
+          uv run --project "${GITHUB_WORKSPACE}" omnigent run \
+            "${GITHUB_WORKSPACE}/.github/agents/feature-blog-scout" \
+            -p "$prompt" --no-session \
+            2>scout-stderr.log | tee /tmp/scout_out.txt \
+            || { echo "::warning::scout exited non-zero — treating as no candidates"; cat scout-stderr.log; }
+
+      - name: Scan scout output for secrets
+        if: steps.scout.outcome == 'success'
+        env:
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+        run: |
+          set -euo pipefail
+          if [ -n "${LLM_API_KEY:-}" ] && grep -qF "$LLM_API_KEY" /tmp/scout_out.txt 2>/dev/null; then
+            echo "::error::Scout output contains LLM_API_KEY — aborting."
+            exit 1
+          fi
+
+      - name: Parse candidates
+        id: candidates
+        if: steps.guard.outputs.proceed == 'true' && steps.creds.outputs.available == 'true'
+        run: |
+          set -euo pipefail
+          python3 -u <<'PYEOF'
+          import json, os, pathlib, re
+          raw = pathlib.Path("/tmp/scout_out.txt").read_text(encoding="utf-8", errors="replace") \
+              if pathlib.Path("/tmp/scout_out.txt").is_file() else ""
+          m = re.search(r"<!--\s*BLOG_CANDIDATES\s*-->(.*?)<!--\s*/BLOG_CANDIDATES\s*-->", raw, re.DOTALL)
+          parsed = []
+          if m:
+              try:
+                  obj = json.loads(m.group(1).strip())
+                  if isinstance(obj, list):
+                      parsed = obj
+              except json.JSONDecodeError as e:
+                  print(f"::warning::Could not parse BLOG_CANDIDATES JSON — treating as none: {e}")
+
+          # The scout is an LLM fed author-written PR prose (an injection surface),
+          # so validate its output before any value becomes a path, branch name, or
+          # PR fetch. `slug` becomes a filesystem path and git branch → must be a
+          # strict kebab-case token (blocks `../`, slashes, spaces). `pr_refs` must
+          # intersect the PRs we actually harvested (blocks arbitrary `gh pr diff`).
+          harvested = set(int(n) for n in re.findall(r"(?m)^#(\d+):",
+              pathlib.Path("/tmp/pr_list.txt").read_text(encoding="utf-8", errors="replace")))
+          slug_re = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+          cands = []
+          for c in parsed:
+              if not isinstance(c, dict):
+                  continue
+              slug = str(c.get("slug", ""))
+              if not slug_re.match(slug) or len(slug) > 80:
+                  print(f"::warning::Dropping candidate with invalid slug {slug!r}.")
+                  continue
+              refs = []
+              for r in c.get("pr_refs", []):
+                  try:
+                      n = int(r)
+                  except (TypeError, ValueError):
+                      continue
+                  if n in harvested:
+                      refs.append(n)
+              if not refs:
+                  print(f"::warning::Dropping candidate {slug!r} — no pr_refs in the harvested range.")
+                  continue
+              c["slug"] = slug
+              c["pr_refs"] = refs
+              cands.append(c)
+
+          # Cap at 3 defensively (the scout is instructed to, but enforce it here).
+          cands = cands[:3]
+          pathlib.Path("/tmp/candidates.json").write_text(json.dumps(cands))
+          out = os.environ["GITHUB_OUTPUT"]
+          with open(out, "a") as f:
+              f.write(f"count={len(cands)}\n")
+          summary = os.environ.get("GITHUB_STEP_SUMMARY")
+          if summary:
+              with open(summary, "a") as f:
+                  if cands:
+                      f.write(f"## {len(cands)} blog candidate(s)\n")
+                      for c in cands:
+                          f.write(f"- **{c.get('headline','?')}** "
+                                  f"(`{c.get('slug','?')}`, {c.get('category','?')}) — "
+                                  f"{c.get('why_worthy','')}\n")
+                  else:
+                      f.write("## No blog-worthy features this release.\n")
+          print(f"Parsed {len(cands)} candidate(s).")
+          PYEOF
+
+      # --- 2) Draft one post per candidate into an omnigent-site checkout ---
+      # Checked out WITHOUT a write token — the drafter runs first; the token is
+      # minted only after all agents finish, then used to push.
+      - name: Checkout omnigent-site (draft target)
+        if: steps.guard.outputs.proceed == 'true' && steps.creds.outputs.available == 'true' && steps.candidates.outputs.count != '0'
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          repository: omnigent-ai/omnigent-site
+          ref: main
+          path: site
+          persist-credentials: false
+
+      - name: Draft posts
+        id: draftposts
+        if: steps.guard.outputs.proceed == 'true' && steps.creds.outputs.available == 'true' && steps.candidates.outputs.count != '0'
+        env:
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.guard.outputs.tag }}
+        run: |
+          set -euo pipefail
+          SITE="${GITHUB_WORKSPACE}/site"
+          VERSION="${TAG#v}"
+          # Release date = the tag's commit date in the omnigent checkout (workspace
+          # root, full history + tags), NOT the site checkout's last-commit date.
+          DATE="$(git -C "${GITHUB_WORKSPACE}" log -1 --format=%cs "$TAG" 2>/dev/null || git -C "${GITHUB_WORKSPACE}" log -1 --format=%cs)"
+
+          # Build a per-feature material file (contributing PRs' entries + diffs),
+          # commit each post to its own LOCAL branch (no push, no token needed).
+          git -C "$SITE" config user.name "omnigent-ci[bot]"
+          git -C "$SITE" config user.email "294685417+omnigent-ci[bot]@users.noreply.github.com"
+
+          count=$(python3 -c "import json;print(len(json.load(open('/tmp/candidates.json'))))")
+          : > /tmp/drafted_branches.txt
+          for i in $(seq 0 $((count - 1))); do
+            slug=$(python3 -c "import json;print(json.load(open('/tmp/candidates.json'))[$i]['slug'])")
+            headline=$(python3 -c "import json;print(json.load(open('/tmp/candidates.json'))[$i]['headline'])")
+            category=$(python3 -c "import json;print(json.load(open('/tmp/candidates.json'))[$i].get('category',''))")
+
+            # Assemble the per-feature material: changelog entries for the
+            # candidate's PRs plus each PR's diff (capped). Quoted heredoc so the
+            # markdown code fences aren't shell-evaluated — index and repo come in
+            # via env (CAND_INDEX / SOURCE_REPO), never interpolated into the body.
+            CAND_INDEX="$i" python3 -u <<'PYEOF'
+          import json, os, pathlib, subprocess
+          repo = os.environ["SOURCE_REPO"]
+          idx = int(os.environ["CAND_INDEX"])
+          cand = json.load(open("/tmp/candidates.json"))[idx]
+          refs = [int(r) for r in cand.get("pr_refs", [])]
+          pr_list = pathlib.Path("/tmp/pr_list.txt").read_text(encoding="utf-8", errors="replace")
+          fence = "```"
+          parts = [f"# Feature: {cand.get('headline','')}", "",
+                   f"Contributing PRs: {refs}", "",
+                   "## Changelog entries (from the release harvest)", pr_list, "",
+                   "## PR diffs"]
+          BUDGET = 60_000
+          for pr in refs:
+              try:
+                  diff = subprocess.run(
+                      ["gh", "pr", "diff", str(pr), "--repo", repo],
+                      capture_output=True, text=True, timeout=60).stdout
+              except Exception as e:
+                  diff = f"(diff unavailable: {e})"
+              parts += [f"### PR #{pr}", f"{fence}diff", diff[:BUDGET], fence]
+          pathlib.Path(f"/tmp/material_{idx}.txt").write_text("\n".join(parts))
+          PYEOF
+
+            # Start each candidate from a pristine tree: a prior candidate that
+            # failed AFTER writing its post would otherwise leave an untracked
+            # file that `switch -C` preserves and the next `add -A` would sweep
+            # into the wrong PR.
+            git -C "$SITE" reset --hard >/dev/null
+            git -C "$SITE" clean -fdx >/dev/null
+            branch="auto/blog/${VERSION}-${slug}"
+            git -C "$SITE" switch -C "$branch" origin/main
+
+            prompt="SITE_REPO=${SITE}
+          HEADLINE=${headline}
+          SLUG=${slug}
+          CATEGORY=${category}
+          DATE=${DATE}
+          MATERIAL_FILE=/tmp/material_${i}.txt
+
+          Draft the feature-blog post per your instructions."
+
+            # cwd = workspace root: the drafter reads MATERIAL_FILE (/tmp) and
+            # writes into SITE_REPO. Capture the exit status without aborting so
+            # the secret-scan below runs regardless of whether the drafter failed
+            # (tee already wrote its stdout to the file either way).
+            drafter_rc=0
+            uv run --project "${GITHUB_WORKSPACE}" omnigent run \
+              "${GITHUB_WORKSPACE}/.github/agents/feature-blog-drafter" \
+              -p "$prompt" --no-session \
+              2>>drafter-stderr.log | tee "/tmp/drafter_out_${i}.txt" || drafter_rc=$?
+
+            # Secret-scan the drafter output BEFORE it feeds the PR body, and
+            # fail-closed EVEN ON drafter failure — the drafter runs with
+            # LLM_API_KEY in env and its stdout is embedded in the PR description,
+            # so a hit must abort the whole step (artifact redaction runs only
+            # after PRs are open, too late to un-leak it).
+            if [ -n "${LLM_API_KEY:-}" ] && grep -qF "$LLM_API_KEY" "/tmp/drafter_out_${i}.txt" 2>/dev/null; then
+              echo "::error::Drafter output for ${slug} contains LLM_API_KEY — aborting."
+              exit 1
+            fi
+
+            if [ "$drafter_rc" -ne 0 ]; then
+              echo "::warning::drafter failed for ${slug} — skipping"
+              continue
+            fi
+
+            if [ -z "$(git -C "$SITE" status --porcelain)" ]; then
+              echo "::warning::drafter produced no edits for ${slug} — skipping"
+              continue
+            fi
+
+            # Also scan the drafted files (they get committed + pushed) for the
+            # key. --untracked covers the newly-created post, which git grep would
+            # otherwise skip.
+            if [ -n "${LLM_API_KEY:-}" ] && git -C "$SITE" grep --untracked -qF "$LLM_API_KEY" 2>/dev/null; then
+              echo "::error::Drafted content for ${slug} contains LLM_API_KEY — aborting."
+              exit 1
+            fi
+
+            # Append the fixed CTA footer to the drafted post (LLM never writes it).
+            # The post is a new, untracked file — find it via status (git diff
+            # can't see untracked paths). Porcelain lines are "XY path"; take the
+            # path field of the first added/modified page.mdx.
+            post="$(git -C "$SITE" status --porcelain | grep -m1 'page.mdx' | awk '{print $NF}' || true)"
+            if [ -n "$post" ]; then
+              printf '\n---\n\n**Enjoying Omnigent?** If this is useful to you, [give us a star on GitHub ⭐](https://github.com/omnigent-ai/omnigent). Come say hi on [Discord](https://discord.gg/omnigent), or [download the latest release](https://omnigent.ai/download).\n' \
+                >> "${SITE}/${post}"
+            fi
+
+            title=$(sed -n 's/^BLOG_PR_TITLE:[[:space:]]*//p' "/tmp/drafter_out_${i}.txt" | head -n1)
+            [ -z "$title" ] && title="add feature blog: ${headline}"
+
+            git -C "$SITE" add -A
+            git -C "$SITE" commit -m "blog: ${title}"
+            printf '%s\t%s\t%s\n' "$branch" "$title" "$i" >> /tmp/drafted_branches.txt
+          done
+
+          n=$(wc -l < /tmp/drafted_branches.txt | tr -d ' ')
+          echo "drafted=${n}" >> "$GITHUB_OUTPUT"
+          echo "Drafted ${n} post(s)." | tee -a "$GITHUB_STEP_SUMMARY"
+
+      # --- 3) Mint the write-token — ONLY now, after the agents have run ---
+      - name: Mint App token (omnigent-site)
+        id: app-token
+        if: steps.guard.outputs.proceed == 'true' && steps.guard.outputs.dry_run != 'true' && steps.draftposts.outcome == 'success' && steps.draftposts.outputs.drafted != '' && steps.draftposts.outputs.drafted != '0' && vars.OMNIGENT_BOT_APP_ID != ''
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ vars.OMNIGENT_BOT_APP_ID }}
+          private-key: ${{ secrets.OMNIGENT_BOT_APP_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: omnigent-site
+
+      # Make a misconfigured run (posts drafted but no App to push them) loud, so
+      # it isn't mistaken for a clean "no candidates" outcome.
+      - name: Warn if drafts can't be published
+        if: steps.guard.outputs.proceed == 'true' && steps.guard.outputs.dry_run != 'true' && steps.draftposts.outcome == 'success' && steps.draftposts.outputs.drafted != '' && steps.draftposts.outputs.drafted != '0' && steps.app-token.outputs.token == ''
+        run: |
+          echo "::warning::Drafted ${{ steps.draftposts.outputs.drafted }} post(s) but no omnigent-site App token (OMNIGENT_BOT_APP_ID unset?) — no PRs opened; drafts discarded." \
+            | tee -a "$GITHUB_STEP_SUMMARY"
+
+      # --- 4) Push each drafted branch and open a DRAFT PR ---
+      - name: Open draft PRs (omnigent-site)
+        if: steps.guard.outputs.proceed == 'true' && steps.guard.outputs.dry_run != 'true' && steps.draftposts.outcome == 'success' && steps.draftposts.outputs.drafted != '' && steps.draftposts.outputs.drafted != '0' && steps.app-token.outputs.token != ''
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          SITE_TOKEN: ${{ steps.app-token.outputs.token }}
+          TAG: ${{ steps.guard.outputs.tag }}
+        run: |
+          set -euo pipefail
+          SITE="${GITHUB_WORKSPACE}/site"
+          SITE_REPO="${GITHUB_REPOSITORY_OWNER}/omnigent-site"
+          PUSH_URL="https://x-access-token:${SITE_TOKEN}@github.com/${SITE_REPO}.git"
+
+          # Ensure the triage label exists (gh pr create --label fails if absent).
+          # Idempotent: a no-op when it already exists.
+          gh label create automated-blog --repo "$SITE_REPO" \
+            --color 5319e7 --description "Auto-drafted feature-blog post" 2>/dev/null || true
+
+          while IFS=$'\t' read -r branch title idx; do
+            [ -z "$branch" ] && continue
+            git -C "$SITE" push --force "$PUSH_URL" "$branch"
+
+            if [ -n "$(gh pr list --repo "$SITE_REPO" --head "$branch" --state open --json number --jq '.[].number')" ]; then
+              echo "Draft PR already open for ${branch} — force-push updated it." \
+                | tee -a "$GITHUB_STEP_SUMMARY"
+              continue
+            fi
+
+            summary="$(sed -n '/<!-- BLOG_DRAFT_SUMMARY -->/,$p' "/tmp/drafter_out_${idx}.txt" | tail -n +2 || true)"
+            body="$(printf 'Drafts a feature-blog post for **%s**, selected by `feature-blog-scout` at the %s release cut.\n\n> **This is a DRAFT.** Before merging, a human must: record the mandatory demo (replace the `DEMO REQUIRED` marker), add hero art, set the author byline, and do a final voice pass.\n\n%s\n\nGenerated by omnigent `.github/workflows/feature-blog.yml`.' "$title" "$TAG" "$summary")"
+            gh pr create \
+              --repo "$SITE_REPO" \
+              --base main \
+              --head "$branch" \
+              --draft \
+              --title "blog: ${title}" \
+              --body "$body" \
+              --label automated-blog
+          done < /tmp/drafted_branches.txt
+
+      # ::add-mask:: redacts rendered logs, not artifact files — scrub the key
+      # from artifacts (incl. unscanned stderr) before upload.
+      - name: Redact secrets from artifacts
+        if: always() && steps.guard.outputs.proceed == 'true' && steps.creds.outputs.available == 'true'
+        env:
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+        run: |
+          set -euo pipefail
+          [ -n "${LLM_API_KEY:-}" ] || exit 0
+          python3 - <<'PYEOF'
+          import os, glob, pathlib
+          key = os.environ.get("LLM_API_KEY", "")
+          files = ["scout-stderr.log", "drafter-stderr.log", "/tmp/scout_out.txt",
+                   "/tmp/scout_prompt.txt"]
+          files += glob.glob("/tmp/drafter_out_*.txt") + glob.glob("/tmp/material_*.txt")
+          for f in files:
+              p = pathlib.Path(f)
+              if not p.is_file() or not key:
+                  continue
+              t = p.read_text(encoding="utf-8", errors="replace")
+              if key in t:
+                  p.write_text(t.replace(key, "***REDACTED***"), encoding="utf-8")
+                  print(f"redacted key from {f}")
+          PYEOF
+
+      - name: Upload logs on failure
+        if: always() && steps.guard.outputs.proceed == 'true'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: feature-blog-${{ steps.guard.outputs.tag }}-${{ github.run_id }}
+          path: |
+            scout-stderr.log
+            drafter-stderr.log
+            /tmp/scout_out.txt
+            /tmp/candidates.json
+            /tmp/drafter_out_*.txt
+          retention-days: 7
+          if-no-files-found: ignore

.github/workflows/finalize-release.yml

@@ -0,0 +1,206 @@
+# Publish a FINAL release's GitHub draft as Latest — the last release step,
+# run after the prod PyPI publish succeeded and the draft notes are curated
+# (designs/RELEASE-AUTOMATION.md).
+#
+# Deterministic gates first (all fail with actionable links):
+#   * the tag is a final vX.Y.Z with an unpublished draft release,
+#   * PyPI serves all three lockstep packages at the version (never advertise
+#     a release that isn't installable),
+#   * the auto/changelog/vX.Y.Z CHANGELOG PR isn't sitting open,
+#   * the docs sweep: no open PRs against omnigent-site's X.Y-docs staging
+#     branch (every doc staged this cycle is reviewed + merged/closed).
+#
+# The publish job binds the `publish-release` environment (one-time setup:
+# create it in repo settings with required reviewers). Approving it is the
+# human attestation "I reviewed the draft notes". The publish itself uses the
+# App token — GITHUB_TOKEN-published releases emit no `release: published`
+# event, and publish-changelog.yml + update-homebrew.yml hang off it — and
+# sets make_latest explicitly, which API publishes don't do on their own.
+#
+# rc tags never finalize: their drafts deliberately stay unpublished.
+name: Finalize release
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Final release tag to publish as Latest, e.g. v0.6.0."
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: finalize-release-${{ inputs.tag }}
+  cancel-in-progress: false
+
+jobs:
+  # Maintainer-only, same gate as release.yml.
+  authorize:
+    if: github.repository == 'omnigent-ai/omnigent'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Require admin/maintain role
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ACTOR: ${{ github.actor }}
+        run: |
+          set -euo pipefail
+          role="$(gh api "repos/${GITHUB_REPOSITORY}/collaborators/${ACTOR}/permission" --jq .role_name)"
+          case "$role" in
+            admin|maintain)
+              echo "Dispatcher ${ACTOR} has role ${role} — authorized." | tee -a "$GITHUB_STEP_SUMMARY" ;;
+            *)
+              echo "::error::Release workflows require the admin or maintain role (dispatcher ${ACTOR} has '${role}')."
+              exit 1 ;;
+          esac
+
+  checks:
+    needs: authorize
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      release_id: ${{ steps.draft.outputs.release_id }}
+      already_published: ${{ steps.draft.outputs.already_published }}
+    steps:
+      - name: Require a final vX.Y.Z tag
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          if ! [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::${TAG} is not a final vX.Y.Z tag — rc/dev/alpha/beta releases never finalize."
+            exit 1
+          fi
+
+      # Drafts are invisible to read-only tokens and unaddressable by tag
+      # (the get-by-tag endpoint 404s on drafts) — resolve by listing with the
+      # App token, same as draft-release-notes.yml. Scoped to BOTH repos: an
+      # installation token cannot reach outside its grant, and the docs sweep
+      # below queries omnigent-site.
+      - name: Mint App token (omnigent + omnigent-site)
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ vars.OMNIGENT_BOT_APP_ID }}
+          private-key: ${{ secrets.OMNIGENT_BOT_APP_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: omnigent,omnigent-site
+
+      - name: Resolve the draft release
+        id: draft
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          match="$(gh api "repos/${GITHUB_REPOSITORY}/releases" --paginate \
+            --jq 'map(select(.tag_name == env.TAG)) | first // empty')"
+          if [ -z "$match" ]; then
+            echo "::error::No GitHub release found for ${TAG}. Did the tag push run github-release.yml?"
+            exit 1
+          fi
+          is_draft="$(printf '%s' "$match" | jq -r '.draft')"
+          release_id="$(printf '%s' "$match" | jq -r '.id')"
+          already_published=false
+          if [ "$is_draft" != "true" ]; then
+            already_published=true
+            echo "Release ${TAG} is already published — nothing to do (idempotent no-op)." \
+              | tee -a "$GITHUB_STEP_SUMMARY"
+          fi
+          {
+            echo "release_id=${release_id}"
+            echo "already_published=${already_published}"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Assert PyPI serves all three packages
+        if: steps.draft.outputs.already_published != 'true'
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          version="${TAG#v}"
+          for pkg in omnigent omnigent-client omnigent-ui-sdk; do
+            if ! curl -fsS "https://pypi.org/pypi/${pkg}/${version}/json" >/dev/null; then
+              echo "::error::${pkg}==${version} is not on PyPI — run the secure-repo publish first (never advertise an uninstallable release)."
+              exit 1
+            fi
+            echo "PyPI OK: ${pkg}==${version}"
+          done
+
+      - name: Assert the CHANGELOG PR is not open
+        if: steps.draft.outputs.already_published != 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          open_pr="$(gh pr list --repo "$GITHUB_REPOSITORY" --head "auto/changelog/${TAG}" \
+            --state open --json url --jq '.[0].url // empty')"
+          if [ -n "$open_pr" ]; then
+            echo "::error::The CHANGELOG PR for ${TAG} is still open — merge it first: ${open_pr}"
+            exit 1
+          fi
+          echo "CHANGELOG PR for ${TAG}: merged or not needed."
+
+      - name: Docs sweep — no open PRs against the X.Y-docs staging branch
+        if: steps.draft.outputs.already_published != 'true'
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          TAG: ${{ inputs.tag }}
+          SITE_REPO: ${{ github.repository_owner }}/omnigent-site
+        run: |
+          set -euo pipefail
+          version="${TAG#v}"
+          docs_branch="${version%.*}-docs"
+          open="$(gh pr list --repo "$SITE_REPO" --base "$docs_branch" --state open \
+            --json url,title --jq '.[] | "- \(.url)  \(.title)"')"
+          if [ -n "$open" ]; then
+            {
+              echo "## Docs sweep failed for ${TAG}"
+              echo ""
+              echo "Open PRs still target \`${docs_branch}\` on ${SITE_REPO} — review and merge/close them, then re-dispatch:"
+              echo "$open"
+            } | tee -a "$GITHUB_STEP_SUMMARY"
+            echo "::error::Open doc PRs still target ${docs_branch} — see the run summary."
+            exit 1
+          fi
+          echo "Docs sweep clean: no open PRs against ${docs_branch}." | tee -a "$GITHUB_STEP_SUMMARY"
+
+  # Approving this environment attests "I reviewed the curated draft notes".
+  publish:
+    needs: [authorize, checks]
+    if: needs.checks.outputs.already_published != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    environment: publish-release
+    steps:
+      - name: Mint App token (omnigent)
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ vars.OMNIGENT_BOT_APP_ID }}
+          private-key: ${{ secrets.OMNIGENT_BOT_APP_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: omnigent
+
+      - name: Publish the draft as Latest
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          TAG: ${{ inputs.tag }}
+          RELEASE_ID: ${{ needs.checks.outputs.release_id }}
+        run: |
+          set -euo pipefail
+          # Edit by id (drafts 404 by tag). -F sends real booleans; make_latest
+          # must be explicit — API publishes don't set it.
+          gh api --method PATCH "repos/${GITHUB_REPOSITORY}/releases/${RELEASE_ID}" \
+            -F draft=false -f make_latest=true > /dev/null
+          {
+            echo "## Published ${TAG} as Latest"
+            echo ""
+            echo "The \`release: published\` event now fires (App-token publish):"
+            echo "- **publish-changelog.yml** opens the omnigent-site release-post PR and the docs-publish PR — review and merge both."
+            echo "- **update-homebrew.yml** opens the homebrew-tap bump PR — review the resource diff, then apply the \`pr-pull\` label."
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/homebrew-tap-pr.yml

@@ -0,0 +1,200 @@
+name: Homebrew tap PR
+
+# When a final GitHub Release is PUBLISHED, open a PR to
+# omnigent-ai/homebrew-tap bumping the `omnigent` formula to the released
+# version. The PR regenerates the stable `url`/`sha256` and every dependency
+# `resource` stanza from the PyPI dependency tree of the just-published
+# `omnigent==X.Y.Z` (resolved with `uv pip compile` for the tap's macOS
+# arm/intel build matrix), splices them into the hand-tuned template at
+# `.github/scripts/homebrew/omnigent.rb.template`, and pushes a branch for
+# review. The tap's own `brew test-bot` then builds the bottles; a maintainer
+# labels the PR `pr-pull` so the tap's `brew pr-pull` workflow commits the
+# `bottle do` block and merges (see the tap's `.github/workflows/`).
+#
+# We trigger on `release: published` (not the tag push) for the same reason as
+# publish-changelog.yml: that's the moment the version is installable from PyPI
+# — the secure-release repo publishes to PyPI before the GitHub Release goes
+# public (see RELEASING.md), so the sdist we pin the formula to actually exists.
+#
+# Cross-repo writes can't use the workflow's own GITHUB_TOKEN (scoped to this
+# repo), so we mint a short-lived token from the omnigent-ci GitHub App scoped to
+# homebrew-tap — the same App used by publish-changelog.yml / doc-sync.yml. One
+# prerequisite: the omnigent-ci App must be installed on omnigent-ai/homebrew-tap
+# with contents:write + pull-requests:write.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Final release tag to (re)open the tap PR for, e.g. v0.3.0
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+# Serialize per tag so two triggers can't race the same formula PR.
+concurrency:
+  group: homebrew-tap-pr-${{ github.event.release.tag_name || inputs.tag }}
+  cancel-in-progress: false
+
+jobs:
+  resolve:
+    name: Resolve release tag
+    runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.r.outputs.tag }}
+      version: ${{ steps.r.outputs.version }}
+      is_final: ${{ steps.r.outputs.is_final }}
+    steps:
+      - name: Resolve tag, version, and finality
+        id: r
+        env:
+          EVENT_TAG: ${{ github.event.release.tag_name }}
+          INPUT_TAG: ${{ inputs.tag }}
+          PRERELEASE: ${{ github.event.release.prerelease }}
+        run: |
+          set -euo pipefail
+          tag="${INPUT_TAG:-$EVENT_TAG}"
+          echo "tag=${tag}" >> "$GITHUB_OUTPUT"
+          echo "version=${tag#v}" >> "$GITHUB_OUTPUT"
+          is_final=true
+          # Only final vX.Y.Z tags; exclude rc/dev/alpha/beta and the event's
+          # prerelease flag (homebrew users get stable releases from the tap).
+          case "$tag" in
+            v[0-9]*.[0-9]*.[0-9]*) ;;
+            *) is_final=false ;;
+          esac
+          case "$tag" in
+            *rc*|*dev*|*a[0-9]*|*b[0-9]*) is_final=false ;;
+          esac
+          if [ "${PRERELEASE}" = "true" ]; then is_final=false; fi
+          echo "is_final=${is_final}" >> "$GITHUB_OUTPUT"
+          echo "Resolved tag=${tag} is_final=${is_final}" | tee -a "$GITHUB_STEP_SUMMARY"
+
+  pr:
+    name: Open homebrew-tap formula PR
+    needs: resolve
+    runs-on: ubuntu-latest
+    # Canonical repo only — forks/mirrors have no PyPI release or the App token.
+    if: needs.resolve.outputs.is_final == 'true' && github.repository == 'omnigent-ai/omnigent'
+    env:
+      TAG: ${{ needs.resolve.outputs.tag }}
+      VERSION: ${{ needs.resolve.outputs.version }}
+      TAP_REPO: ${{ github.repository_owner }}/homebrew-tap
+      BRANCH: auto/formula/${{ needs.resolve.outputs.tag }}
+    steps:
+      - name: Checkout omnigent (template + generator)
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: false
+
+      - name: Wait for the released sdist to land on PyPI
+        # The GitHub Release is published after the prod PyPI publish, but the
+        # secure-release publish can lag a few minutes; poll so a slightly-early
+        # release (or a rerun right at publish time) doesn't fail the whole job.
+        run: |
+          set -euo pipefail
+          python3 - "$VERSION" <<'PY'
+          import json, sys, time, urllib.request
+          ver = sys.argv[1]
+          url = f"https://pypi.org/pypi/omnigent/{ver}/json"
+          deadline = time.time() + 15 * 60
+          while time.time() < deadline:
+              try:
+                  with urllib.request.urlopen(url, timeout=20) as r:
+                      data = json.load(r)
+                  if any(f.get("packagetype") == "sdist" for f in data.get("urls", [])):
+                      print(f"omnigent=={ver} sdist is on PyPI.")
+                      sys.exit(0)
+              except Exception as e:
+                  print(f"waiting for {url}: {e}")
+              time.sleep(30)
+          print(f"::error::omnigent=={ver} sdist not found on PyPI after 15m")
+          sys.exit(1)
+          PY
+
+      - name: Generate the formula
+        run: |
+          set -euo pipefail
+          python3 .github/scripts/homebrew/generate_formula.py \
+            --version "$VERSION" \
+            --template .github/scripts/homebrew/omnigent.rb.template \
+            --out /tmp/omnigent.rb
+          {
+            echo "### Generated \`Formula/omnigent.rb\` for $TAG"
+            echo '```ruby'
+            cat /tmp/omnigent.rb
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Mint homebrew-tap App token
+        id: app-token
+        if: vars.OMNIGENT_BOT_APP_ID != ''
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ vars.OMNIGENT_BOT_APP_ID }}
+          private-key: ${{ secrets.OMNIGENT_BOT_APP_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: homebrew-tap
+
+      - name: Checkout homebrew-tap (PR target)
+        if: steps.app-token.outputs.token != ''
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          repository: ${{ env.TAP_REPO }}
+          token: ${{ steps.app-token.outputs.token }}
+          path: tap
+
+      - name: Open or update the formula PR
+        if: steps.app-token.outputs.token != ''
+        working-directory: tap
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          set -euo pipefail
+          mkdir -p Formula
+          cp /tmp/omnigent.rb Formula/omnigent.rb
+
+          if [ -z "$(git status --porcelain -- Formula/omnigent.rb)" ]; then
+            echo "Formula already at $TAG — nothing to do." | tee -a "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+
+          git config user.name "omnigent-ci[bot]"
+          git config user.email "294685417+omnigent-ci[bot]@users.noreply.github.com"
+          git switch -C "$BRANCH"
+          git add Formula/omnigent.rb
+          git commit -m "omnigent $VERSION"
+          git push --force origin "$BRANCH"
+
+          if [ -n "$(gh pr list --repo "$TAP_REPO" --head "$BRANCH" --state open --json number --jq '.[].number')" ]; then
+            echo "Formula PR already open for $BRANCH — force-push updated it." \
+              | tee -a "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+
+          body="$(printf 'Bumps the **omnigent** formula to **%s**.\n\nRegenerates the stable `url`/`sha256` and every `resource` stanza from the PyPI dependency tree of `omnigent==%s` (resolved with `uv pip compile` for macOS arm + intel), spliced into the hand-tuned template in `omnigent-ai/omnigent` (`.github/scripts/homebrew/omnigent.rb.template`). The structural parts (`depends_on`, `install`, `test`) are unchanged.\n\nOnce `brew test-bot` builds the bottles, label this PR **`pr-pull`** so the tap'"'"'s `brew pr-pull` workflow commits the `bottle do` block and merges.\n\nGenerated by `omnigent-ai/omnigent` `.github/workflows/homebrew-tap-pr.yml` on the **%s** release.' "$VERSION" "$VERSION" "$TAG")"
+          gh pr create \
+            --repo "$TAP_REPO" \
+            --base main \
+            --head "$BRANCH" \
+            --title "omnigent $VERSION" \
+            --body "$body"
+
+      - name: Note skipped (no App token)
+        if: steps.app-token.outputs.token == ''
+        run: |
+          echo "::warning::OMNIGENT_BOT_APP_ID/KEY missing, or the omnigent-ci App isn't installed on $TAP_REPO with contents:write + pull-requests:write. The formula was generated (see the job summary) but the PR was not opened."
+          echo "### Homebrew tap PR skipped" >> "$GITHUB_STEP_SUMMARY"
+          echo "The omnigent-ci App token couldn't be minted — install the App on \`$TAP_REPO\` with contents:write + pull-requests:write and rerun." >> "$GITHUB_STEP_SUMMARY"

.github/workflows/lint.yml

@@ -11,6 +11,9 @@ on:
   push:
     branches:
       - main
+      # Release branches: release.yml's green-CI gate reads check runs off the
+      # branch head, so cherry-picks and release-bump commits must run checks.
+      - 'release/v[0-9]*'
 
 permissions:
   contents: read
@@ -125,3 +128,26 @@ jobs:
       - name: Type-check web
         working-directory: web
         run: npm run type-check
+
+  # The three packages release in lockstep (identical versions + `==` sibling
+  # pins). Assert agreement on every change so drift from a bad merge or
+  # cherry-pick — however it happened — is caught before it reaches a release.
+  version-lockstep:
+    name: Version lockstep check
+    needs: gate
+    if: ${{ !github.event.pull_request.draft }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        with:
+          python-version-file: ".python-version"
+
+      - name: All version locations agree
+        run: |
+          python -m pip install --quiet --disable-pip-version-check packaging
+          python scripts/update_versions.py check

.github/workflows/merge-ready.yml

@@ -27,7 +27,9 @@ on:
   pull_request_target:
     types: [labeled]
   workflow_run:
-    workflows: [PR Template, CI, Lint, E2E UI Tests, E2E Tests, Integration Tests]
+    workflows: [PR Template, CI, Lint, Docker build, E2E UI Tests, E2E Tests, Integration Tests]
+    types: [completed]
+  check_run:
     types: [completed]
   issue_comment:
     types: [created]
@@ -48,7 +50,7 @@ permissions:
   contents: read
 
 concurrency:
-  group: merge-ready-${{ github.event.pull_request.number || github.event.issue.number || inputs.pr || github.event.workflow_run.head_sha }}
+  group: merge-ready-${{ github.event.pull_request.number || github.event.issue.number || inputs.pr || github.event.workflow_run.head_sha || github.event.check_run.head_sha }}
   cancel-in-progress: true
 
 jobs:
@@ -61,8 +63,9 @@ jobs:
       actions: read         # evaluate-checks.sh reads GET /actions/runs to classify missing checks
       statuses: write
     # Fire on automerge label adds, PR CI workflow_run completions (same-repo
-    # and fork), `/merge` comments, or a workflow_dispatch re-eval. Runs with no
-    # open PR (push to main, etc.) are dropped by the ctx step.
+    # and fork), DCO check_run completions, `/merge` comments, or a
+    # workflow_dispatch re-eval. Runs with no open PR (push to main, etc.) are
+    # dropped by the ctx step.
     if: >-
       (
         github.event_name == 'pull_request_target' &&
@@ -72,6 +75,11 @@ jobs:
         github.event_name == 'workflow_run' &&
         github.event.workflow_run.event == 'pull_request'
       ) ||
+      (
+        github.event_name == 'check_run' &&
+        github.event.check_run.name == 'DCO' &&
+        github.event.check_run.app.slug == 'dco'
+      ) ||
       github.event_name == 'workflow_dispatch' ||
       (
         github.event_name == 'issue_comment' &&
@@ -102,6 +110,7 @@ jobs:
           # Via env, not interpolated: author-controlled, so direct
           # interpolation would be a shell-injection vector.
           WF_PRS: ${{ toJSON(github.event.workflow_run.pull_requests) }}
+          CHECK_RUN_SHA: ${{ github.event.check_run.head_sha }}
           COMMENT_BODY: ${{ github.event.comment.body }}
           PR_INPUT: ${{ inputs.pr }}
           SHA_INPUT: ${{ inputs.sha }}
@@ -142,6 +151,14 @@ jobs:
             fi
             PR="${{ github.event.issue.number }}"
             SHA=$(gh pr view "$PR" --repo "$REPO" --json headRefOid --jq '.headRefOid')
+          elif [[ "${{ github.event_name }}" == "check_run" ]]; then
+            SHA="$CHECK_RUN_SHA"
+            PR=$(resolve_pr_from_sha "$SHA")
+            if [[ -z "$PR" ]]; then
+              echo "::notice::Skipped: DCO check_run has no associated open PR"
+              echo "skip=true" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
           else
             PR=$(echo "$WF_PRS" | jq -r '.[0].number // empty')
             SHA="${{ github.event.workflow_run.head_sha }}"

.github/workflows/oss-publish-images.yml

@@ -12,10 +12,8 @@
 #                   `pip install omnigent` resolves to. Pre-releases never move it.
 #   :latest-rc      the highest version OVERALL, max(release, rc) — the newest
 #                   thing tagged, pre-release or not.
-#   :latest-dev     the most recent main build (bleeding edge); moves on every
-#                   qualifying main commit.
-#   :latest-nightly the most recent main build as of the daily cron; retagged
-#                   from :latest-dev once a day (no rebuild).
+#   :latest-nightly the most recent nightly main build (bleeding edge); moves
+#                   once a day when the scheduled build rebuilds main HEAD.
 # Ordering for :latest / :latest-rc uses PEP 440 (1.2.3rc1 < 1.2.3), which
 # `sort -V` gets wrong, so the max is computed with .github/scripts/
 # oss-publish-images/maxver.py (Python `packaging`).
@@ -25,23 +23,15 @@
 name: Publish images (public)
 
 on:
+  # Release builds only — every v* tag push publishes the immutable version pin
+  # and moves the floating release tags. Per-commit main builds were retired in
+  # favour of the nightly rebuild below; PRs get a build-only check (docker-build.yml)
+  # so a broken image is caught before merge without a push.
   push:
-    branches: [main]
     tags: ['v*']
-    # Only rebuild when something that lands in the image changes.
-    paths:
-      - 'deploy/docker/Dockerfile'
-      - 'deploy/docker/entrypoint.py'
-      - 'omnigent/**'
-      - 'web/**'
-      - 'sdks/**'
-      - 'pyproject.toml'
-      - 'setup.py'
-      - 'uv.lock'
-      - 'web/package-lock.json'
-      - '.github/workflows/oss-publish-images.yml'
-  # Daily nightly promotion (07:00 UTC). Retags the current :latest-dev as
-  # :latest-nightly — handled by promote-nightly, not a rebuild.
+  # Nightly rebuild of main HEAD (07:00 UTC): the build-and-push job publishes
+  # :sha-<short> + :latest-nightly. This is what keeps bleeding-edge ~1 day
+  # fresh now that main commits no longer each trigger a build.
   schedule:
     - cron: '0 7 * * *'
   workflow_dispatch:
@@ -50,10 +40,6 @@ on:
         description: 'Also move :latest to this build (manual release of latest). Off by default.'
         type: boolean
         default: false
-      force_nightly:
-        description: 'Promote :latest-dev -> :latest-nightly now (runs only the nightly job). Off by default.'
-        type: boolean
-        default: false
       reconcile_floating:
         description: 'Repoint :latest and :latest-rc onto the correct existing version images (no rebuild). Runs only the reconcile job. Off by default.'
         type: boolean
@@ -73,10 +59,11 @@ jobs:
     permissions:
       contents: read
       packages: write # push the image to GHCR via GITHUB_TOKEN
-    # Gated to this repository; inert in forks and mirrors. Skip the (re)build
-    # on schedule, force_nightly, and reconcile_floating dispatches — those only
-    # drive the promote-nightly / reconcile-floating jobs.
-    if: github.repository == 'omnigent-ai/omnigent' && github.event_name != 'schedule' && !inputs.force_nightly && !inputs.reconcile_floating
+    # Gated to this repository; inert in forks and mirrors. Runs on tag pushes,
+    # the nightly schedule (rebuild of main HEAD), and bump_latest dispatches.
+    # Skipped on reconcile_floating dispatches — that only drives the
+    # reconcile-floating retag job.
+    if: github.repository == 'omnigent-ai/omnigent' && !inputs.reconcile_floating
     runs-on: ubuntu-latest
     # Multi-arch: the linux/arm64 leg cross-builds under QEMU emulation on this
     # amd64 runner, which roughly doubles the host-image build time (emulated
@@ -124,23 +111,26 @@ jobs:
           IMAGE="ghcr.io/omnigent-ai/omnigent-server"
           HOST_IMAGE="ghcr.io/omnigent-ai/omnigent-host"
           OPENSHELL_IMAGE="ghcr.io/omnigent-ai/omnigent-server-openshell"
+          KUBERNETES_IMAGE="ghcr.io/omnigent-ai/omnigent-server-kubernetes"
           SHORT_SHA=$(git rev-parse --short HEAD)
 
           # Immutable per-commit pin, always.
           TAGS="${IMAGE}:sha-${SHORT_SHA}"
           HOST_TAGS="${HOST_IMAGE}:sha-${SHORT_SHA}"
           OPENSHELL_TAGS="${OPENSHELL_IMAGE}:sha-${SHORT_SHA}"
+          KUBERNETES_TAGS="${KUBERNETES_IMAGE}:sha-${SHORT_SHA}"
 
           # Append a floating/version tag to all images.
           add_tag() {
             TAGS="${TAGS},${IMAGE}:$1"
             HOST_TAGS="${HOST_TAGS},${HOST_IMAGE}:$1"
             OPENSHELL_TAGS="${OPENSHELL_TAGS},${OPENSHELL_IMAGE}:$1"
+            KUBERNETES_TAGS="${KUBERNETES_TAGS},${KUBERNETES_IMAGE}:$1"
           }
 
-          # Every qualifying main commit moves :latest-dev (bleeding edge).
+          # The nightly rebuild of main moves :latest-nightly (bleeding edge).
           if [ "${GH_REF}" = "refs/heads/main" ]; then
-            add_tag "latest-dev"
+            add_tag "latest-nightly"
           fi
 
           if [[ "${GH_REF}" == refs/tags/v* ]]; then
@@ -175,6 +165,7 @@ jobs:
           echo "tags=${TAGS}" >> "$GITHUB_OUTPUT"
           echo "host_tags=${HOST_TAGS}" >> "$GITHUB_OUTPUT"
           echo "openshell_tags=${OPENSHELL_TAGS}" >> "$GITHUB_OUTPUT"
+          echo "kubernetes_tags=${KUBERNETES_TAGS}" >> "$GITHUB_OUTPUT"
 
       # No build-args: the Dockerfile ARGs default to public registries.
       # Multi-arch: each tag publishes as a manifest list spanning amd64 + arm64,
@@ -234,10 +225,32 @@ jobs:
           cache-to: type=gha,mode=max
           provenance: false
           sbom: true
+
+      # Kubernetes server variant: the default server image plus the kubernetes
+      # client extra (OMNIGENT_EXTRAS=kubernetes), so `sandbox.provider:
+      # kubernetes` works without a self-built image. Used by the
+      # deploy/kubernetes/overlays/sandbox-runners kustomize overlay. Reuses
+      # the shared builder-stage layers from the gha cache.
+      - name: Build and push kubernetes server image
+        id: build-kubernetes
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf  # v7.2.0
+        with:
+          context: .
+          file: deploy/docker/Dockerfile
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.tags.outputs.kubernetes_tags }}
+          build-args: |
+            OMNIGENT_EXTRAS=kubernetes
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: false
+          sbom: true
     outputs:
       server-digest: ${{ steps.build-server.outputs.digest }}
       host-digest: ${{ steps.build-host.outputs.digest }}
       openshell-digest: ${{ steps.build-openshell.outputs.digest }}
+      kubernetes-digest: ${{ steps.build-kubernetes.outputs.digest }}
 
   generate-sbom:
     # Runs in a separate job with read-only permissions so the Syft
@@ -281,6 +294,13 @@ jobs:
             -o cyclonedx-json=openshell-sbom.cdx.json \
             -o spdx-json=openshell-sbom.spdx.json
 
+      - name: Generate kubernetes server SBOM
+        run: |
+          set -euo pipefail
+          syft "ghcr.io/omnigent-ai/omnigent-server-kubernetes@${{ needs.build-and-push.outputs.kubernetes-digest }}" \
+            -o cyclonedx-json=kubernetes-sbom.cdx.json \
+            -o spdx-json=kubernetes-sbom.spdx.json
+
       - name: Upload SBOMs
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
@@ -292,45 +312,10 @@ jobs:
             host-sbom.spdx.json
             openshell-sbom.cdx.json
             openshell-sbom.spdx.json
+            kubernetes-sbom.cdx.json
+            kubernetes-sbom.spdx.json
           retention-days: 90
 
-  promote-nightly:
-    # Daily cron (or a manual force_nightly dispatch): move :latest-nightly to
-    # the current main build by retagging :latest-dev with `crane tag`
-    # (digest-preserving, no rebuild).
-    if: github.repository == 'omnigent-ai/omnigent' && (github.event_name == 'schedule' || inputs.force_nightly)
-    permissions:
-      contents: read
-      packages: write # retag within GHCR via GITHUB_TOKEN
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - name: Set up crane
-        uses: imjasonh/setup-crane@59c71e96a00b28651f10369ba3359a6d730740a0  # v0.6
-        with:
-          version: v0.21.6
-
-      - name: Log in to GHCR
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee  # v4.2.0
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Promote latest-dev -> latest-nightly
-        run: |
-          set -euo pipefail
-          # crane tag points a new tag at an EXISTING manifest digest without
-          # re-serializing it, so :latest-nightly keeps :latest-dev's exact digest.
-          for img in ghcr.io/omnigent-ai/omnigent-server ghcr.io/omnigent-ai/omnigent-host ghcr.io/omnigent-ai/omnigent-server-openshell; do
-            if crane digest "${img}:latest-dev" >/dev/null 2>&1; then
-              crane tag "${img}:latest-dev" latest-nightly
-              echo "promoted ${img}:latest-dev -> :latest-nightly ($(crane digest "${img}:latest-nightly"))"
-            else
-              echo "::warning::${img}:latest-dev not found yet; skipping nightly promotion"
-            fi
-          done
-
   reconcile-floating:
     # Manual reconcile (workflow_dispatch with reconcile_floating=true): repoint
     # :latest and :latest-rc onto the correct EXISTING version images, computed
@@ -393,7 +378,7 @@ jobs:
             fi
           }
 
-          for img in ghcr.io/omnigent-ai/omnigent-server ghcr.io/omnigent-ai/omnigent-host ghcr.io/omnigent-ai/omnigent-server-openshell; do
+          for img in ghcr.io/omnigent-ai/omnigent-server ghcr.io/omnigent-ai/omnigent-host ghcr.io/omnigent-ai/omnigent-server-openshell ghcr.io/omnigent-ai/omnigent-server-kubernetes; do
             retag "${img}" "latest-rc" "${RC_TAG}"
             retag "${img}" "latest" "${LATEST_TAG}"
           done

.github/workflows/release.yml

@@ -0,0 +1,531 @@
+# Cut or advance a release deterministically (designs/RELEASE-AUTOMATION.md):
+#
+#   dispatch with version=0.6.0rc1  ->  create release/v0.6.0 from `ref`, stamp the
+#   lockstep version (scripts/update_versions.py + `uv lock`), tag v0.6.0rc1,
+#   push branch + tag. Later dispatches (0.6.0rc2, 0.6.0, 0.6.1) reuse the
+#   existing release/v0.6.0 head and ignore `ref`.
+#
+# The branch + tag are pushed with the omnigent-ci App token, NOT GITHUB_TOKEN:
+# GITHUB_TOKEN-pushed tags trigger no workflows by GitHub policy, and the whole
+# release chain (github-release.yml -> draft-release-notes.yml, and
+# oss-publish-images.yml) hangs off the tag push.
+#
+# PyPI publishing does NOT happen here — after this run, dispatch the secure
+# release repo on the tag (see RELEASING.md). Everything here is idempotent:
+# re-dispatch with identical inputs after any failure and it converges
+# (branch exists -> reused; version stamped -> no new commit; tag at the
+# converged commit -> no-op; tag anywhere else -> loud failure).
+#
+# `dry_run` defaults TRUE (repo convention, same as the vscode release
+# workflows): the plan job prints exactly what would happen; nothing is pushed.
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release, e.g. 0.6.0rc1 or 0.6.0 (no leading v)."
+        required: true
+        type: string
+      ref:
+        description: "Branch/tag/SHA to cut release/vX.Y.0 from. Only consulted when the branch does not exist yet (rc1); later phases build from the existing branch head."
+        required: false
+        default: main
+        type: string
+      dry_run:
+        description: "Plan only: validate + print what would happen, push nothing."
+        required: false
+        type: boolean
+        default: true
+      skip_ci_check:
+        description: "Skip the green-CI assertion on the base commit (flaky-check escape hatch — use deliberately)."
+        required: false
+        type: boolean
+        default: false
+      skip_benchmark:
+        description: "Skip the pre-cut benchmark regression check (escape hatch — use deliberately)."
+        required: false
+        type: boolean
+        default: false
+
+# Nothing here writes with GITHUB_TOKEN; pushes use the App token.
+permissions:
+  contents: read
+
+# Serialize all release runs: two concurrent cuts (even of different versions)
+# could race the same release/vX.Y.0 head.
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  # Releases are maintainer-only. `workflow_dispatch` is open to anyone with
+  # write access, so gate on the dispatcher's actual repo role instead of a
+  # hand-kept list. `github.actor` on a dispatch is the dispatcher.
+  authorize:
+    if: github.repository == 'omnigent-ai/omnigent'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Require admin/maintain role
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ACTOR: ${{ github.actor }}
+        run: |
+          set -euo pipefail
+          role="$(gh api "repos/${GITHUB_REPOSITORY}/collaborators/${ACTOR}/permission" --jq .role_name)"
+          case "$role" in
+            admin|maintain)
+              echo "Dispatcher ${ACTOR} has role ${role} — authorized." | tee -a "$GITHUB_STEP_SUMMARY" ;;
+            *)
+              echo "::error::Release workflows require the admin or maintain role (dispatcher ${ACTOR} has '${role}')."
+              exit 1 ;;
+          esac
+
+  # Resolve everything and validate BEFORE mutating anything. Runs checkout-free
+  # (pure API reads) and also serves as the whole dry run.
+  plan:
+    needs: authorize
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      version: ${{ steps.derive.outputs.version }}
+      tag: ${{ steps.derive.outputs.tag }}
+      branch: ${{ steps.derive.outputs.branch }}
+      prerelease: ${{ steps.derive.outputs.prerelease }}
+      branch_exists: ${{ steps.state.outputs.branch_exists }}
+      base_sha: ${{ steps.state.outputs.base_sha }}
+      already_done: ${{ steps.state.outputs.already_done }}
+    steps:
+      - name: Validate version and derive names
+        id: derive
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          set -euo pipefail
+          # Final X.Y.Z or a PEP 440 pre-release (a/b/rc). No dev/post here.
+          if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+((a|b|rc)[0-9]+)?$ ]]; then
+            echo "::error::Invalid release version: ${VERSION} (expect 0.6.0 or 0.6.0rc1)"; exit 1
+          fi
+          major="${VERSION%%.*}"; rest="${VERSION#*.}"; minor="${rest%%.*}"
+          prerelease=false
+          case "$VERSION" in *a[0-9]*|*b[0-9]*|*rc[0-9]*) prerelease=true ;; esac
+          {
+            echo "version=${VERSION}"
+            echo "tag=v${VERSION}"
+            echo "branch=release/v${major}.${minor}.0"
+            echo "prerelease=${prerelease}"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Resolve branch, base commit, and tag state
+        id: state
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.derive.outputs.version }}
+          TAG: ${{ steps.derive.outputs.tag }}
+          BRANCH: ${{ steps.derive.outputs.branch }}
+          REF: ${{ inputs.ref }}
+        run: |
+          set -euo pipefail
+
+          # `gh api` prints the error body to STDOUT on 404, so capturing with
+          # `|| true` would treat the "Not Found" JSON as an existing ref —
+          # gate on the exit code instead.
+          if branch_sha="$(gh api "repos/${GITHUB_REPOSITORY}/git/ref/heads/${BRANCH}" --jq .object.sha 2>/dev/null)"; then
+            branch_exists=true
+            base_sha="$branch_sha"
+            # `ref` only applies at branch creation. An explicit non-default ref
+            # that disagrees with the branch head is a mistake, not a retarget.
+            if [ "$REF" != "main" ]; then
+              ref_sha="$(gh api "repos/${GITHUB_REPOSITORY}/commits/${REF}" --jq .sha)"
+              if [ "$ref_sha" != "$branch_sha" ]; then
+                echo "::error::${BRANCH} already exists at ${branch_sha}; ref=${REF} (${ref_sha}) would not be used. Re-dispatch without ref, or delete the branch if this is recovery."
+                exit 1
+              fi
+            fi
+          else
+            branch_exists=false
+            base_sha="$(gh api "repos/${GITHUB_REPOSITORY}/commits/${REF}" --jq .sha)"
+          fi
+
+          # Tag state: absent -> normal; at the converged release commit ->
+          # no-op; anywhere else -> refuse (never silently move a tag).
+          already_done=false
+          if tag_sha="$(gh api "repos/${GITHUB_REPOSITORY}/git/ref/tags/${TAG}" --jq .object.sha 2>/dev/null)"; then
+            tag_type="$(gh api "repos/${GITHUB_REPOSITORY}/git/ref/tags/${TAG}" --jq .object.type)"
+            if [ "$tag_type" = "tag" ]; then
+              tag_sha="$(gh api "repos/${GITHUB_REPOSITORY}/git/tags/${tag_sha}" --jq .object.sha)"
+            fi
+            stamped="$(gh api -H "Accept: application/vnd.github.raw+json" \
+              "repos/${GITHUB_REPOSITORY}/contents/pyproject.toml?ref=${TAG}" \
+              | sed -n 's/^version = "\(.*\)"$/\1/p' | head -1)"
+            if [ "$tag_sha" = "$base_sha" ] && [ "$stamped" = "$VERSION" ]; then
+              already_done=true
+              echo "Tag ${TAG} already at the converged release commit ${base_sha} — nothing to do." \
+                | tee -a "$GITHUB_STEP_SUMMARY"
+            else
+              echo "::error::Tag ${TAG} already exists at ${tag_sha} (stamped version: ${stamped:-unknown}), which is not the converged branch head ${base_sha}. Delete the tag first if this is recovery (see RELEASING.md)."
+              exit 1
+            fi
+          fi
+
+          {
+            echo "branch_exists=${branch_exists}"
+            echo "base_sha=${base_sha}"
+            echo "already_done=${already_done}"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Assert green CI on the base commit
+        if: steps.state.outputs.already_done != 'true' && !inputs.skip_ci_check
+        env:
+          GH_TOKEN: ${{ github.token }}
+          BASE_SHA: ${{ steps.state.outputs.base_sha }}
+        run: |
+          set -euo pipefail
+          runs="$(gh api "repos/${GITHUB_REPOSITORY}/commits/${BASE_SHA}/check-runs?per_page=100" \
+            --paginate --jq '.check_runs[] | [.name, .status, .conclusion // "-"] | @tsv')"
+          total="$(printf '%s' "$runs" | grep -c . || true)"
+          pending="$(printf '%s' "$runs" | awk -F'\t' '$2 != "completed"' || true)"
+          # Cancelled runs are chronically present on main (superseded
+          # benchmark/eval runs) — warn, don't block; real failures still gate.
+          bad="$(printf '%s' "$runs" | awk -F'\t' '$3 ~ /^(failure|timed_out|action_required|startup_failure)$/' || true)"
+          cancelled="$(printf '%s' "$runs" | awk -F'\t' '$3 == "cancelled"' || true)"
+          if [ -n "$bad" ]; then
+            echo "::error::Failing check runs on ${BASE_SHA}:"; printf '%s\n' "$bad"; exit 1
+          fi
+          if [ -n "$pending" ]; then
+            echo "::error::Check runs still running on ${BASE_SHA} — wait for CI:"; printf '%s\n' "$pending"; exit 1
+          fi
+          if [ "$total" -eq 0 ]; then
+            echo "::error::No check runs found on ${BASE_SHA}. Wait for CI on that commit, or re-dispatch with skip_ci_check=true if you are sure."
+            exit 1
+          fi
+          if [ -n "$cancelled" ]; then
+            echo "::warning::Cancelled (superseded) check runs on ${BASE_SHA} — not blocking:"
+            printf '%s\n' "$cancelled"
+          fi
+          echo "CI green on ${BASE_SHA} (${total} completed check runs, none failing)." \
+            | tee -a "$GITHUB_STEP_SUMMARY"
+
+      - name: Write the plan
+        env:
+          DRY_RUN: ${{ inputs.dry_run }}
+          VERSION: ${{ steps.derive.outputs.version }}
+          TAG: ${{ steps.derive.outputs.tag }}
+          BRANCH: ${{ steps.derive.outputs.branch }}
+          BRANCH_EXISTS: ${{ steps.state.outputs.branch_exists }}
+          BASE_SHA: ${{ steps.state.outputs.base_sha }}
+          ALREADY_DONE: ${{ steps.state.outputs.already_done }}
+        run: |
+          set -euo pipefail
+          {
+            echo "## Release plan for ${TAG}"
+            echo ""
+            echo "| | |"
+            echo "| --- | --- |"
+            echo "| Version | \`${VERSION}\` |"
+            echo "| Branch | \`${BRANCH}\` ($([ "$BRANCH_EXISTS" = "true" ] && echo "exists — reused" || echo "will be created")) |"
+            echo "| Base commit | \`${BASE_SHA}\` |"
+            echo "| Converged already | ${ALREADY_DONE} |"
+            echo "| Mode | $([ "$DRY_RUN" = "true" ] && echo "DRY RUN — nothing pushed" || echo "EXECUTE") |"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  # Run benchmark on the release commit vs the previous stable release tag —
+  # same runner, back-to-back, so machine variance cancels out. A detected
+  # regression surfaces as an output flag that gates the benchmark-approve job
+  # (requiring manual sign-off) rather than failing outright. Skipped on dry
+  # runs, already-converged runs, and when skip_benchmark=true.
+  benchmark:
+    needs: [authorize, plan]
+    if: ${{ !inputs.dry_run && needs.plan.outputs.already_done != 'true' && !inputs.skip_benchmark }}
+    outputs:
+      regression: ${{ steps.compare.outputs.regression }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    env:
+      OMNIGENT_SKIP_WEB_UI: "true"
+      UV_INDEX_URL: https://pypi.org/simple
+      PIP_INDEX_URL: https://pypi.org/simple
+    steps:
+      - name: Check out release base
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ needs.plan.outputs.branch_exists == 'true' && needs.plan.outputs.branch || needs.plan.outputs.base_sha }}
+          # Full history so we can re-checkout the previous release tag.
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version-file: ".python-version"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v3
+        with:
+          enable-cache: true
+
+      # Seed once with the same corpus size as the nightly (5000×200) so the
+      # candidate and baseline numbers are on an equal footing and directly
+      # comparable to the nightly trend dashboard. The DB is reused for both
+      # candidate and baseline runs — both check out different code but share
+      # the same pre-populated SQLite file, keeping conditions identical.
+      # Cache key mirrors benchmark.yml: schema head + seed script hash.
+      - name: Resolve seed cache key
+        id: seedkey
+        run: |
+          HEAD="$(uv run --no-sync dev/benchmarks/omnigent/seed.py --print-head)"
+          echo "key=benchdb-sqlite-${HEAD}-5000x200-${{ hashFiles('dev/benchmarks/omnigent/seed.py') }}" \
+            >> "$GITHUB_OUTPUT"
+
+      - name: Restore seeded SQLite corpus
+        id: seedcache
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v4
+        with:
+          path: bench.db
+          key: ${{ steps.seedkey.outputs.key }}
+
+      - name: Seed SQLite corpus
+        if: steps.seedcache.outputs.cache-hit != 'true'
+        run: |
+          uv run --no-sync dev/benchmarks/omnigent/seed.py \
+            --database-uri "sqlite:///bench.db" \
+            --sessions 5000 --items-per-session 200
+
+      - name: Benchmark candidate (release base)
+        run: |
+          uv sync --extra dev
+          uv run --no-sync dev/benchmarks/omnigent/run.py \
+            --database-uri "sqlite:///bench.db" \
+            --iterations 100 --runs 3 --output candidate.json
+          echo "Candidate benchmark complete." | tee -a "$GITHUB_STEP_SUMMARY"
+
+      - name: Find previous stable release tag
+        id: prev
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          PREV_TAG=$(gh api "repos/${GITHUB_REPOSITORY}/releases?per_page=20" \
+            --jq '[.[] | select(.prerelease == false and .draft == false)] | .[0].tag_name // empty')
+          if [ -z "$PREV_TAG" ]; then
+            echo "No previous stable release found — skipping regression check." | tee -a "$GITHUB_STEP_SUMMARY"
+            echo "found=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "Previous stable release: ${PREV_TAG}" | tee -a "$GITHUB_STEP_SUMMARY"
+            echo "found=true" >> "$GITHUB_OUTPUT"
+            echo "tag=${PREV_TAG}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Benchmark previous release (${{ steps.prev.outputs.tag }})
+        if: steps.prev.outputs.found == 'true'
+        run: |
+          git checkout "${{ steps.prev.outputs.tag }}"
+          uv sync --extra dev
+          uv run --no-sync dev/benchmarks/omnigent/run.py \
+            --database-uri "sqlite:///bench.db" \
+            --iterations 100 --runs 3 --output baseline.json
+          # Return to release base so compare.py is available.
+          git checkout -
+
+      - name: Compare results
+        id: compare
+        if: steps.prev.outputs.found == 'true'
+        run: |
+          set +e
+          uv run --no-sync dev/benchmarks/omnigent/compare.py \
+            --baseline baseline.json \
+            --candidate candidate.json \
+            --threshold 1.0 \
+            --output-markdown comparison.md
+          RC=$?
+          set -e
+          # Expose regression flag as an output so the approval job can gate on it.
+          echo "regression=$([ $RC -ne 0 ] && echo 'true' || echo 'false')" >> "$GITHUB_OUTPUT"
+
+      - name: Write step summary
+        if: steps.prev.outputs.found == 'true'
+        run: |
+          REGRESSION="${{ steps.compare.outputs.regression }}"
+          {
+            if [ "$REGRESSION" != "true" ]; then
+              echo "### Benchmark: PASS ✓"
+            else
+              echo "### Benchmark: REGRESSION DETECTED ✗"
+              echo ""
+              echo "> A regression exceeding the threshold was found."
+              echo "> The **benchmark-approve** job is awaiting maintainer sign-off before cut proceeds."
+            fi
+            echo ""
+            cat comparison.md 2>/dev/null || echo "_No comparison report generated._"
+            echo ""
+            echo "_Candidate vs ${{ steps.prev.outputs.tag }} · 100 iterations × 3 runs · SQLite · threshold 100% on P50/P95_"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload benchmark artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: always()
+        with:
+          name: benchmark-release-${{ github.run_id }}
+          path: |
+            candidate.json
+            baseline.json
+          retention-days: 90
+          if-no-files-found: ignore
+
+  # Pauses for a maintainer to review and approve in the GitHub UI when the
+  # benchmark job detected a regression. Uses an environment with required
+  # reviewers — configure "benchmark-regression-gate" in repo Settings →
+  # Environments. Skipped (passes through) when there is no regression.
+  benchmark-approve:
+    needs: [authorize, plan, benchmark]
+    if: |
+      !inputs.dry_run &&
+      needs.plan.outputs.already_done != 'true' &&
+      !inputs.skip_benchmark &&
+      needs.benchmark.outputs.regression == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    environment: benchmark-regression-gate
+    steps:
+      - name: Regression approved by maintainer
+        run: |
+          echo "Benchmark regression approved. Proceeding with cut." | tee -a "$GITHUB_STEP_SUMMARY"
+
+  # Stamp + tag + push. Only reached on a real run that isn't already converged.
+  cut:
+    needs: [authorize, plan, benchmark, benchmark-approve]
+    if: ${{ !inputs.dry_run && needs.plan.outputs.already_done != 'true' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      # Clean public resolution for `uv lock` — the committed lockfile must
+      # reference https://pypi.org/simple (never a proxy).
+      UV_INDEX_URL: https://pypi.org/simple
+      PIP_INDEX_URL: https://pypi.org/simple
+    steps:
+      - name: Mint App token (omnigent)
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ vars.OMNIGENT_BOT_APP_ID }}
+          private-key: ${{ secrets.OMNIGENT_BOT_APP_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: omnigent
+
+      - name: Checkout base
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          # Existing branch: its head. New branch: the resolved base commit.
+          ref: ${{ needs.plan.outputs.branch_exists == 'true' && needs.plan.outputs.branch || needs.plan.outputs.base_sha }}
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: false
+
+      - name: Stamp the lockstep version
+        env:
+          VERSION: ${{ needs.plan.outputs.version }}
+        run: |
+          set -euo pipefail
+          current="$(uv run --no-project --python 3.12 --with packaging \
+            python scripts/update_versions.py check 2>/dev/null || true)"
+          if [ "$current" = "$VERSION" ]; then
+            echo "Already stamped at ${VERSION} — skipping bump (idempotent re-run)."
+          else
+            uv run --no-project --python 3.12 --with packaging \
+              python scripts/update_versions.py pre-release --new-version "$VERSION"
+            uv lock
+          fi
+          uv run --no-project --python 3.12 --with packaging \
+            python scripts/update_versions.py check --expect "$VERSION"
+
+      - name: Commit, tag, and push
+        env:
+          PUSH_TOKEN: ${{ steps.app-token.outputs.token }}
+          VERSION: ${{ needs.plan.outputs.version }}
+          TAG: ${{ needs.plan.outputs.tag }}
+          BRANCH: ${{ needs.plan.outputs.branch }}
+        run: |
+          set -euo pipefail
+          git config user.name "omnigent-ci[bot]"
+          git config user.email "294685417+omnigent-ci[bot]@users.noreply.github.com"
+
+          git add pyproject.toml sdks/python-client/pyproject.toml sdks/ui/pyproject.toml \
+            omnigent/version.py uv.lock
+          if git diff --cached --quiet; then
+            echo "No version changes to commit (already stamped)."
+          else
+            git commit -s -m "release: ${TAG}"
+          fi
+
+          git tag "$TAG"
+          # One push for branch + tag, via the App token so the tag-push
+          # workflows fire. Non-fast-forward on the branch fails loudly.
+          push_url="https://x-access-token:${PUSH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+          git push "$push_url" "HEAD:refs/heads/${BRANCH}" "refs/tags/${TAG}"
+          echo "Pushed ${BRANCH} + ${TAG} at $(git rev-parse HEAD)." | tee -a "$GITHUB_STEP_SUMMARY"
+
+      - name: Next steps
+        env:
+          TAG: ${{ needs.plan.outputs.tag }}
+          PRERELEASE: ${{ needs.plan.outputs.prerelease }}
+        run: |
+          set -euo pipefail
+          {
+            echo "## Next steps"
+            echo ""
+            echo "1. Dispatch the secure-release repo on this tag:"
+            echo '   ```'
+            echo "   gh workflow run omnigent.yml --repo databricks/secure-public-registry-releases-eng \\"
+            echo "     -f ref=${TAG} -f destination=pypi -f dry-run=true    # gates rehearsal"
+            echo "   gh workflow run omnigent.yml --repo databricks/secure-public-registry-releases-eng \\"
+            echo "     -f ref=${TAG} -f destination=pypi -f dry-run=false   # real publish"
+            echo '   ```'
+            if [ "$PRERELEASE" = "true" ]; then
+              echo "2. Validate the rc from PyPI (see RELEASING.md). The GitHub draft for ${TAG} stays unpublished."
+            else
+              echo "2. Merge the CHANGELOG PR, curate the ${TAG} draft notes, then dispatch finalize-release.yml (tag=${TAG})."
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  # First cut of a cycle (rc1) immediately moves main to the next .dev0 so main
+  # never re-freezes and doc-sync keeps deriving the right X.Y-docs branch.
+  bump-main:
+    needs: [authorize, plan, cut]
+    if: ${{ !inputs.dry_run && needs.plan.outputs.branch_exists == 'false' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      actions: write
+    steps:
+      - name: Dispatch the post-release main bump
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ needs.plan.outputs.version }}
+        run: |
+          set -euo pipefail
+          # A cut below main's current line (a throwaway rehearsal rc, or
+          # resurrecting an old series for a backport) must not walk main's
+          # version backwards.
+          MAIN_VERSION="$(gh api -H "Accept: application/vnd.github.raw+json" \
+            "repos/${GITHUB_REPOSITORY}/contents/pyproject.toml?ref=main" \
+            | sed -n 's/^version = "\(.*\)"$/\1/p' | head -1)"
+          export MAIN_VERSION
+          python3 -m pip install --quiet --disable-pip-version-check packaging
+          if ! python3 -c 'import os, sys; from packaging.version import Version; sys.exit(0 if Version(os.environ["VERSION"]) > Version(os.environ["MAIN_VERSION"]) else 1)'; then
+            echo "Released ${VERSION} sorts below main's ${MAIN_VERSION} — skipping the main bump." \
+              | tee -a "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+          gh workflow run bump-version.yml --repo "$GITHUB_REPOSITORY" \
+            -f mode=post-release -f "new_version=${VERSION}" -f base_branch=main
+          echo "Dispatched bump-version.yml (post-release ${VERSION}) — review and merge the main bump PR." \
+            | tee -a "$GITHUB_STEP_SUMMARY"

.github/workflows/update-homebrew.yml

@@ -0,0 +1,247 @@
+# Open the omnigent-ai/homebrew-tap version-bump PR when a FINAL release is
+# published (designs/RELEASE-AUTOMATION.md). This is the missing link that let
+# the tap freeze while PyPI moved on: the tap already builds bottles on every
+# PR (brew test-bot) and publishes them on the `pr-pull` label — nobody was
+# opening the bump PR.
+#
+# What it does: wait for the new sdist on PyPI, rewrite the formula's
+# url/sha256 (dropping any bottle `revision`), regenerate the pinned Python
+# resources with `brew update-python-resources`, sanity-check that the
+# hand-maintained sections survived, and open the tap PR. A human reviews the
+# resource diff and applies `pr-pull`; the tap's own automation bottles and
+# merges. The omnigent-desktop cask is `version :latest` and needs nothing.
+#
+# Pre-releases never reach the tap. The `release: published` trigger fires
+# from finalize-release.yml's App-token publish; `workflow_dispatch` covers
+# retries and catch-up (e.g. jumping the formula straight to the newest
+# version after a missed cycle).
+name: Update Homebrew tap
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Final release tag to bump the tap to, e.g. v0.6.0."
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: update-homebrew-${{ github.event.release.tag_name || inputs.tag }}
+  cancel-in-progress: false
+
+jobs:
+  resolve:
+    name: Resolve release tag
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      tag: ${{ steps.r.outputs.tag }}
+      is_final: ${{ steps.r.outputs.is_final }}
+    steps:
+      - name: Resolve tag and finality
+        id: r
+        env:
+          EVENT_TAG: ${{ github.event.release.tag_name }}
+          PRERELEASE: ${{ github.event.release.prerelease }}
+          INPUT_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          tag="${INPUT_TAG:-$EVENT_TAG}"
+          is_final=true
+          case "$tag" in
+            v[0-9]*.[0-9]*.[0-9]*) ;;
+            *) is_final=false ;;
+          esac
+          case "$tag" in
+            *rc*|*dev*|*a[0-9]*|*b[0-9]*) is_final=false ;;
+          esac
+          if [ "${PRERELEASE}" = "true" ]; then
+            is_final=false
+          fi
+          {
+            echo "tag=${tag}"
+            echo "is_final=${is_final}"
+          } >> "$GITHUB_OUTPUT"
+          echo "Resolved tag=${tag} is_final=${is_final}" | tee -a "$GITHUB_STEP_SUMMARY"
+
+  bump:
+    name: Open tap bump PR
+    needs: resolve
+    # Canonical repo only; skip cleanly where the App isn't configured. The
+    # release-event path is already gated by finalize-release's environment
+    # approval; only manual dispatches need the role check below.
+    if: >-
+      needs.resolve.outputs.is_final == 'true' &&
+      github.repository == 'omnigent-ai/omnigent' &&
+      vars.OMNIGENT_BOT_APP_ID != ''
+    # macOS: `brew update-python-resources` evaluates the formula (with its
+    # on_macos blocks) in a real Homebrew.
+    runs-on: macos-latest
+    timeout-minutes: 30
+    env:
+      TAG: ${{ needs.resolve.outputs.tag }}
+      TAP_REPO: ${{ github.repository_owner }}/homebrew-tap
+    steps:
+      - name: Require admin/maintain role (manual dispatches)
+        if: github.event_name == 'workflow_dispatch'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ACTOR: ${{ github.actor }}
+        run: |
+          set -euo pipefail
+          role="$(gh api "repos/${GITHUB_REPOSITORY}/collaborators/${ACTOR}/permission" --jq .role_name)"
+          case "$role" in
+            admin|maintain)
+              echo "Dispatcher ${ACTOR} has role ${role} — authorized." ;;
+            *)
+              echo "::error::Release workflows require the admin or maintain role (dispatcher ${ACTOR} has '${role}')."
+              exit 1 ;;
+          esac
+
+      - name: Wait for the sdist on PyPI
+        id: sdist
+        run: |
+          set -euo pipefail
+          version="${TAG#v}"
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+          for _ in $(seq 1 30); do
+            if json="$(curl -fsS "https://pypi.org/pypi/omnigent/${version}/json" 2>/dev/null)"; then
+              url="$(printf '%s' "$json" | jq -r '.urls[] | select(.packagetype == "sdist") | .url')"
+              sha="$(printf '%s' "$json" | jq -r '.urls[] | select(.packagetype == "sdist") | .digests.sha256')"
+              if [ -n "$url" ] && [ -n "$sha" ]; then
+                {
+                  echo "url=${url}"
+                  echo "sha=${sha}"
+                } >> "$GITHUB_OUTPUT"
+                echo "sdist for ${version}: ${url}"
+                exit 0
+              fi
+            fi
+            echo "omnigent==${version} not visible on PyPI yet — retrying in 20s…"
+            sleep 20
+          done
+          echo "::error::omnigent==${version} never appeared on PyPI (is the secure-repo publish done?)."
+          exit 1
+
+      - name: Mint App token (homebrew-tap)
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ vars.OMNIGENT_BOT_APP_ID }}
+          private-key: ${{ secrets.OMNIGENT_BOT_APP_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: homebrew-tap
+
+      - name: Checkout the tap
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          repository: ${{ env.TAP_REPO }}
+          token: ${{ steps.app-token.outputs.token }}
+          path: tap
+          persist-credentials: false
+
+      - name: Set up Homebrew
+        uses: Homebrew/actions/setup-homebrew@18fcb8e3e06b4247c676c506750dc95ea7226479 # 2026-07-10
+        with:
+          token: ${{ github.token }}
+
+      - name: Rewrite the formula's stable url/sha256
+        working-directory: tap
+        env:
+          SDIST_URL: ${{ steps.sdist.outputs.url }}
+          SDIST_SHA: ${{ steps.sdist.outputs.sha }}
+        run: |
+          set -euo pipefail
+          python3 - <<'PYEOF'
+          import os, pathlib, re
+          path = pathlib.Path("Formula/omnigent.rb")
+          text = path.read_text(encoding="utf-8")
+          # The formula's own url/sha256 sit at 2-space indent; resource and
+          # bottle entries are deeper, so first-match at this indent is safe.
+          text, n_url = re.subn(r'(?m)^  url ".*"$', f'  url "{os.environ["SDIST_URL"]}"', text, count=1)
+          text, n_sha = re.subn(r'(?m)^  sha256 ".*"$', f'  sha256 "{os.environ["SDIST_SHA"]}"', text, count=1)
+          text, _ = re.subn(r'(?m)^  revision \d+\n', "", text, count=1)
+          assert n_url == 1 and n_sha == 1, f"unexpected formula shape (url={n_url}, sha={n_sha})"
+          path.write_text(text, encoding="utf-8")
+          PYEOF
+          git diff --stat
+
+      - name: Regenerate the pinned Python resources
+        env:
+          HOMEBREW_NO_AUTO_UPDATE: "1"
+          HOMEBREW_NO_INSTALL_FROM_API: "1"
+        run: |
+          set -euo pipefail
+          # Make the checkout visible to brew as the real tap.
+          tap_root="$(brew --repository)/Library/Taps/omnigent-ai"
+          mkdir -p "$tap_root"
+          ln -sfn "${GITHUB_WORKSPACE}/tap" "${tap_root}/homebrew-tap"
+          # Excluded packages stay hand-maintained in the formula: the brewed
+          # deps (certifi/cryptography/pydantic/rpds-py and their transitive
+          # cffi/pycparser) and the platform-conditional google-antigravity
+          # wheel stanzas.
+          brew update-python-resources \
+            --exclude-packages=certifi,cryptography,pydantic,rpds-py,cffi,pycparser,google-antigravity \
+            omnigent-ai/tap/omnigent
+          brew style omnigent-ai/tap/omnigent
+
+      - name: Assert the hand-maintained sections survived
+        working-directory: tap
+        run: |
+          set -euo pipefail
+          fail=0
+          for needle in 'resource "google-antigravity"' 'depends_on "pydantic"' 'depends_on "cryptography"'; do
+            if ! grep -qF "$needle" Formula/omnigent.rb; then
+              echo "::error::update-python-resources dropped: ${needle} — fix the formula by hand this cycle."
+              fail=1
+            fi
+          done
+          [ "$fail" -eq 0 ]
+          # The lockstep siblings must have moved with the release. Match the
+          # sdist filename (PEP 503-normalized name + version) in the resource
+          # url, not a bare version substring.
+          version="${TAG#v}"
+          for sib in omnigent-client omnigent-ui-sdk; do
+            if ! grep -A2 "resource \"${sib}\"" Formula/omnigent.rb | grep -q "${sib//-/_}-${version}"; then
+              echo "::error::resource ${sib} did not update to ${version}."
+              exit 1
+            fi
+          done
+
+      - name: Open or update the tap bump PR
+        working-directory: tap
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          VERSION: ${{ steps.sdist.outputs.version }}
+        run: |
+          set -euo pipefail
+          if [ -z "$(git status --porcelain -- Formula/omnigent.rb)" ]; then
+            echo "Formula already at ${VERSION} — nothing to do." | tee -a "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+          BRANCH="bump-omnigent-${VERSION}"
+          git config user.name "omnigent-ci[bot]"
+          git config user.email "294685417+omnigent-ci[bot]@users.noreply.github.com"
+          PUSH_URL="https://x-access-token:${GH_TOKEN}@github.com/${TAP_REPO}.git"
+          git switch -C "$BRANCH"
+          git add Formula/omnigent.rb
+          git commit -m "omnigent ${VERSION}"
+          git push --force "$PUSH_URL" "$BRANCH"
+
+          if [ -n "$(gh pr list --repo "$TAP_REPO" --head "$BRANCH" --state open --json number --jq '.[].number')" ]; then
+            echo "Bump PR already open for ${BRANCH} — force-push updated it." | tee -a "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+          body="$(printf 'Bumps the omnigent formula to **%s** (new sdist url/sha256, resources regenerated via `brew update-python-resources`).\n\ntest-bot builds the bottles on this PR. Review the resource diff — especially that the extras'"'"' deps survived — then apply the `pr-pull` label to publish bottles and merge.\n\nOpened by omnigent `.github/workflows/update-homebrew.yml`.' "$VERSION")"
+          gh pr create \
+            --repo "$TAP_REPO" \
+            --base main \
+            --head "$BRANCH" \
+            --title "omnigent ${VERSION}" \
+            --body "$body"
+          echo "Opened tap bump PR for omnigent ${VERSION}." | tee -a "$GITHUB_STEP_SUMMARY"

.pre-commit-config.yaml

@@ -105,6 +105,16 @@ repos:
         files: ^uv\.lock$
         pass_filenames: true
 
+      # Fail if routing.proto changed without regenerating the committed
+      # bindings (or vice versa). Verify-only, not a fixer: regen needs
+      # grpcio-tools, so CI's `uv sync --extra dev` enforces it (like ktlint).
+      - id: routing-pb2-fresh
+        name: routing protobuf bindings are up to date
+        language: system
+        entry: .venv/bin/python scripts/gen_routing_pb2.py --check
+        files: ^omnigent/api/routing/v1/routing(\.proto|_pb2\.pyi?)$
+        pass_filenames: false
+
   # ── File hygiene ────────────────────────────────────────────────
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.6.0

CHANGELOG.md

@@ -5,6 +5,97 @@ generated at release time from each PR's `## Changelog` section, tagged by the
 PR's `Type of change` (e.g. `[UI]`); the concise, curated highlights live on the
 website under `/releases`.
 
+## [Unreleased]
+
+### Features
+
+- [UI / Feature] Added a Nord color theme (arctic frost-blue palette) to the Appearance settings palette picker.
+
+## [v0.5.0] — 2026-07-10
+
+- [Bug fix] Messaging a long-idle session no longer risks the new turn being killed mid-flight by the idle reaper (#1834)
+- [UI / Feature] Introduce more secure sharing modes and the ability to toggle public chats on/off. (#1835)
+- [UI / Feature] Added: `.ipynb` notebooks render as read-only previews in the workspace file viewer (raw JSON still available via the source view) (#1848)
+- [Feature] `OMNIGENT_OIDC_SKIP_EMAIL_VERIFICATION=1` lets OIDC logins through when the IdP omits the `email_verified` claim (e.g. standard-tier Okta with directory-provisioned users) (#1859)
+- [UI / Feature] User message bubbles now have a copy button, matching assistant responses (#1900)
+- [UI] Renamed the sidebar's "Chats" section to "Sessions" to match the "New session" button (#1903)
+- [UI / Bug fix] Brain-harness override (e.g. claude-sdk vs openai-agents) is now remembered across sessions per agent (#1904)
+- [UI / Bug fix] "Back to Omnigent" from Settings now returns you to the conversation you were viewing instead of the home page (#1905)
+- [Bug fix] Release notes now list only user-facing bug fixes and call out breaking changes in their own section (#1909)
+- [Test/CI] Auto-drafted docs now stage on a per-minor `X.Y-docs` branch and publish to the live site at release, instead of deploying on merge. (#1915)
+- [UI] Removed the collapse toggle from the Files panel "Working folder" header — the file list is always visible (#1916)
+- [UI / Bug fix] Opencode agents addressed as `native-opencode` now render with their native terminal UI instead of falling back to plain chat. (#1929)
+- [Bug fix / Chore] Fixed harness workers (claude, codex, etc.) failing to start when omnigent is launched from a macOS or Linux GUI client due to a stripped PATH. Fix now lives in the Electron launcher (web/electron/src/main.js) per reviewer guidance. (#1935)
+- [Feature] Child-session lookup by `(agent, title)` now filters server-side instead of fetching all children and scanning in Python. (#1944)
+- [Bug fix] Sandboxed claude-sdk harnesses now authenticate from an existing host Claude login (`~/.claude/.credentials.json` is bound into the sandbox). (#1946)
+- [Chore / Test/CI] Runner MCP servers are shared across matching agent specs and started lazily to reduce local memory use. (#1948)
+- [Bug fix] Fixed: resumed claude-native sessions no longer crash on compaction ("Cannot destructure property 'cumulativeDroppedTokens'") (#1957)
+- [UI / Feature] The Claude model picker now offers Fable and both Sonnet generations (Sonnet 5 and Sonnet 4.6) as separate selections (#1981)
+- [Bug fix] Stop rendering a false "terminal did not become ready" error when sending a message to Claude Code mid-turn (#2001)
+- [UI] [UI] The "Working…" indicator now stays visible for the whole turn and rotates through a few different labels. (#2006)
+- [Bug fix] Members page now shows a clear "not available in single-user mode" message instead of a confusing auth error when running without accounts or OIDC. (#2013)
+- [UI / Bug fix] Global Policies settings page now appears correctly in single-user/header auth mode instead of showing a "no permission" error. (#2017)
+- [Feature] `intent_gate` policy now prompts for user approval (`ASK`) instead of hard-blocking (`DENY`) tool calls that don't match the session's original intent. (#2024)
+- [UI / Bug fix] Submitting the Codex goal dialog no longer shifts the footer buttons — the loading spinner replaces the button label in place instead of widening the button (#2032)
+- [UI / Feature] Add a UI font size setting in Appearance to scale the interface (#2040)
+- [Bug fix] `/compact` on a `claude-sdk` agent with a pinned Anthropic model no longer 500s — the compaction summarizer was routing bare `claude-*` ids to OpenAI instead of Anthropic. (#2043)
+- [UI / Feature] Set a custom UI font family in Settings → Appearance (type any installed font; blank = system default). (#2047)
+- [UI / Bug fix] Fix the Appearance font-size input so you can clear and retype a value instead of it clamping mid-edit (#2053)
+- [Bug fix] Native Claude sessions no longer get stuck showing "Stop" after switching models in the terminal with `/model` (#2082)
+- [UI / Feature] The sidebar "Search" now opens the command palette (⌘K) to search sessions by title and chat content, with a keyboard-shortcut hint on hover (#2086)
+- [UI / Feature] Start a new session directly in an existing git worktree by picking it from the worktree field. (#2088)
+- [Bug fix] Stop rendering a false "terminal did not become ready" error when sending a message to Claude Code mid-turn with many subagents running (#2089)
+- [UI / Feature] Generate a unique worktree branch name from the new-session composer. (#2094)
+- [Feature] The harness capability bench now observes native harness tool calls (Tool (#2096)
+- [Bug fix] Report missing bubblewrap when building a `web_fetch` researcher instead of failing during spawn (#2097)
+- [UI / Feature] Sessions started in an existing git worktree now show the branch in the sidebar and can delete the worktree + branch from the session delete dialog. (#2098)
+- [Bug fix] Fixed OpenShell k8s managed sandboxes failing due to Landlock LSM denying `/home/sandbox`; changed home path to `/sandbox` (#2106)
+- [UI / Bug fix] The share dialog no longer overflows when a grantee's email is long — the name truncates and the domain stays visible. (#2108)
+- [Bug fix / Test/CI] Keep claude-native model, permission mode, and effort overrides stable across wrapped Claude Code restarts that preserve the settings sidecar. (#2116)
+- [Feature] Kubernetes sandbox runner Pods can now schedule on arm64 nodes: set `sandbox.kubernetes.node_selector: {kubernetes.io/arch: arm64}` (amd64 remains the default). (#2123)
+- [Feature / Test/CI] New official `omnigent-server-kubernetes` image ships the kubernetes sandbox provider SDK — the `sandbox-runners` overlay now works against published images, no custom build needed. (#2124)
+- [UI / Bug fix] codex-native sessions now show MCP server startup progress in the chat, name servers that failed or were cancelled, and Stop can abort a slow MCP startup (#2128)
+- [Bug fix] Host-spawned runners now inherit `DATABRICKS_AUTH_STORAGE`, so a runner authenticates against the same Databricks token store as the host (fixes a runner tunnel 401 when the store is selected via env var rather than `~/.databrickscfg`). (#2132)
+- [UI / Feature] Set the code editor and terminal font size and family from Settings → Appearance (#2135)
+- [Bug fix] Intelligent routing now correctly routes claude sessions instead of leaving them (#2136)
+- [Bug fix] Fixed inbox approvals not resuming the gated tool call. (#2142)
+- [UI / Feature] Pick a color theme (Omnigent, Dracula, GitHub, Catppuccin, or Gruvbox) in Appearance settings, independent of light/dark mode. (#2147)
+- [UI / Feature] Choose a terminal theme (light or dark) independent of the app theme in Settings, Appearance (#2154)
+- [UI / Feature] Sessions shared with you now live in a dedicated "Shared with me" sidebar tab (multi-user servers only) (#2156)
+- [Feature] Tightened `conversations.title` DB column to NOT NULL; untitled conversations are now stored as `''` instead of `NULL`. (#2158)
+- [Feature / Test/CI] Add a performance-benchmark harness for HTTP user journeys, with a seeded corpus, a SQLite+Postgres backend matrix, and a nightly workflow (`uv run dev/benchmarks/omnigent/run.py`) (#2159)
+- [Bug fix] Sub-agent hermes sessions no longer wake their parent orchestrator before the turn's final answer is mirrored into the transcript (#2161)
+- [UI / Feature] Session search now shows a preview of the matching message so you can see why a session matched, with the search term highlighted (#2162)
+- [Feature / Test/CI] Host runner start logs now include the `conv_*` conversation ID alongside the runner token and log path. (#2170)
+- [Bug fix] The harness capability bench now reports a real native Policy DENY verdict (#2171)
+- [UI / Bug fix] Cancel in the add-policy dialog now returns to the policy list instead of closing it (#2183)
+- [UI / Feature] Users can now edit the policy name in the Add Policy dialog before submitting. (#2196)
+- [Feature / Test/CI] Add a performance-benchmark harness for HTTP + full-turn user journeys (`uv run dev/benchmarks/omnigent/run.py`), with a seeded corpus and SQLite+Postgres backend matrix (#2202)
+- [UI / Bug fix] The new-session picker now remembers the host you last picked instead of resetting to the default. (#2218)
+- [Bug fix] Fixed the Hermes `pre_tool_call` hook double-gating Omnigent relay tools, which parked a (#2220)
+- [UI / Chore] Redesigned Appearance settings: separate Mode and Color theme sections, app-preview Mode tiles, and a color-theme dropdown. (#2225)
+- [UI / Feature] Added: auto-routing decisions now show as a collapsible card (model pill, tier, rationale, expandable raw verdict) matching the SmartRoutingCard style (#2246)
+- [Bug fix] Sessions shared with you no longer appear under "My sessions" when they belong to a project — they stay under "Shared with me" (#2249)
+- [Test/CI] Doc-sync site PRs are now titled after the documentation change instead of the source PR number. (#2250)
+- [UI / Bug fix] Stop-session dialog now shows the actual server error instead of a generic message. (#2252)
+- [UI / Bug fix] Project picker menu rows now align on the left and share a consistent height (#2260)
+- [Feature] The harness bench can now probe any registered harness by name — including the (#2265)
+- [UI / Feature] A default base branch can be set in Settings › Git to auto-fill the base when naming a new worktree branch (#2267)
+- [Feature] `omnigent debug logs` tails runner, server, or CLI diagnostic logs; `--session` scopes runner logs to a specific session across relaunches (#2273)
+- [Bug fix] `omni run --harness acp:<slug>` now launches a configured ACP agent instead of failing on the colon in the synthesized agent name. (#2280)
+- [UI / Bug fix] [UI] Fix iOS crash when granting camera or voice-dictation permission in the app (#2282)
+- [Test/CI] DELETE THIS WHOLE SECTION — CI-only change, not user-facing. (#2288)
+- [Bug fix / Feature] Fixed: intelligent routing now overrides any model the orchestrator specified in `sys_session_send` when the parent session has the routing toggle on (#2291)
+- [Bug fix] Fixed a crash when resuming a Claude-native session whose history contained a `TaskOutput` (or similar) result, so resume no longer times out with a terminal-not-ready error. (#2293)
+- [Test/CI] DELETE THIS WHOLE SECTION — CI-only change, not user-facing. (#2295)
+- [UI / Bug fix] "Select all" in bulk selection mode now only selects sessions in expanded sidebar sections, not hidden or archived ones. (#2311)
+- [Bug fix] Fix pi (and opencode policy) losing live web-UI updates on multi-instance deployments by sending their out-of-process callbacks to the same server instance as the runner. (#2328)
+- [Bug fix] Default policies created via the API (`POST /v1/policies`) now take effect on sessions. (#2333)
+- [Feature] omnidev dev pods now get their own isolated `config.yaml` (seeded from `~/.omnigent/config.yaml`), so server-config edits while testing in a pod no longer touch your real config (#2360)
+- [Bug fix] Session search returns matched-content previews faster on large histories. (#2365)
+- [Feature / Docs / Test/CI] Harness Bench now measures Policy ALLOW and ASK through native CLI policy hooks. (#2370)
+- [Bug fix] Managed claude-native sessions against an Anthropic-compatible gateway (e.g. LiteLLM or Databricks) now pass through the gateway model and don't stall on Claude Code's custom-API-key menu. (#2371)
+
 ## [v0.4.0] — 2026-07-03
 
 Highlights and full notes: <https://github.com/omnigent-ai/omnigent/releases/tag/v0.4.0>

README.md

@@ -67,6 +67,26 @@ One command installs Omnigent and everything it needs:
 curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh
 ```
 
+<details>
+<summary>Optional integrations and extras</summary>
+
+Need an optional integration? Pass one or more extras to the installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh -s -- --extra databricks
+curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh -s -- --extra modal,e2b
+```
+
+Available user-facing extras include:
+
+- **Model providers:** `databricks`, `bedrock`, `vertex`
+- **Sandbox providers:** `modal`, `daytona`, `boxlite`, `cwsandbox`, `e2b`,
+  `openshell`, `kubernetes`
+- **SDK harnesses:** `antigravity`, `copilot`, `cursor`, `agents-sdk`
+- **Storage and memory:** `s3`, `hindsight`
+
+</details>
+
 <details>
 <summary>Prefer to install manually?</summary>
 
@@ -76,6 +96,12 @@ Omnigent needs **Python 3.12+**. Install the `omnigent` package:
 uv tool install omnigent        # or: pip install "omnigent"
 ```
 
+Manual installs use the same extras syntax, for example:
+
+```bash
+uv tool install "omnigent[databricks,modal]"
+```
+
 Or with [Homebrew](https://github.com/omnigent-ai/homebrew-tap):
 
 ```bash
@@ -173,6 +199,41 @@ mirrors work out of the box; override with `OMNIGENT_INDEX_URL` if needed.
 
 </details>
 
+<details>
+<summary>Uninstalling Omnigent</summary>
+
+Preview the CLI/profile cleanup that would run by default:
+
+```bash
+omnigent uninstall
+```
+
+Remove the CLI and installer-managed PATH entries while keeping your local
+history, credentials, and projects:
+
+```bash
+omnigent uninstall --yes
+```
+
+To also remove Omnigent state under `~/.omnigent`, pass `--purge`; Omnigent
+backs it up outside the target before deletion. Your `~/omnigent` workspace is
+kept unless you explicitly add `--purge-workspace`.
+
+```bash
+omnigent uninstall --purge --yes
+```
+
+If the installed wheel is broken or `omnigent` is not on `PATH`, run the
+standalone script instead:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/uninstall_oss.sh | sh
+```
+
+Add `--yes` to the standalone script to perform the previewed CLI cleanup.
+
+</details>
+
 ### 2. Start your first agent
 
 `omnigent` picks a model with you and starts a session in your terminal. It
@@ -451,6 +512,10 @@ Polly at [`examples/polly/`](https://github.com/omnigent-ai/omnigent/tree/main/e
 
 Contributions are welcome. See [CONTRIBUTING.md](https://github.com/omnigent-ai/omnigent/blob/main/CONTRIBUTING.md) for how to set up your environment, run the checks, and open a pull request.
 
+Adding or changing support for a harness (Claude, Codex, Cursor, OpenCode,
+Hermes, Pi, ...)? Run the [harness test bench](https://github.com/omnigent-ai/omnigent/tree/main/tests/harness_bench)
+to check its capability matrix against observed behavior.
+
 
 ### Contributors
 
@@ -459,4 +524,3 @@ Thanks to all of our amazing contributors!
 <a href="https://github.com/omnigent-ai/omnigent/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=omnigent-ai/omnigent" />
 </a>
-

RELEASING.md

@@ -13,6 +13,11 @@ omnigent ships **three PyPI packages that version-lock together**:
 pin each other with `==`), so every release builds and publishes **all three at
 one identical version**.
 
+Releases are driven by **workflow dispatches, not by hand** (design:
+`designs/RELEASE-AUTOMATION.md`). Every workflow below is idempotent —
+re-dispatch with identical inputs after any failure and it converges — and
+every dispatch requires the **admin or maintain** role on this repo.
+
 ## Where things run
 
 - **Source of truth** (versions, tags, GitHub Releases): **`omnigent-ai/omnigent`**
@@ -20,31 +25,31 @@ one identical version**.
   on the public repo).
 - **Publishing to PyPI**: the central **secure-release repo**
   **`databricks/secure-public-registry-releases-eng`**, `omnigent` workflow —
-  use the **Databricks EMU account**. Publishing runs on hardened runner
+  use whichever account has access to that repo. Publishing runs on hardened runner
   groups with **OIDC Trusted Publishing (no stored secrets)** and a **mandatory
-  dependency scan**. This is why we don't publish from `omnigent-ai/omnigent`.
+  dependency scan**. This is why we don't publish from `omnigent-ai/omnigent`,
+  and why the pipeline is two dispatches per phase rather than one.
 
 > The exact account handles — and how to request publish access — live in the
 > internal release wiki; this public runbook refers to them only by role.
-> Substitute your own handles for `<oss-account>` / `<emu-account>` in the
-> `gh auth switch --user …` commands below.
 
 The legacy `.github/workflows/release-omnigent.yml` in this repo is a
 **deprecated manual fallback only** — its tag-push trigger was removed so a tag
 never double-publishes. Use the secure repo for real releases.
 
-> The secure `omnigent` workflow is **manual `workflow_dispatch`** — it can't see
-> this repo's tag pushes. You bump + tag here, then dispatch it with that tag.
-
 ## Versioning model
 
 - `main` always carries the **next** version with a `.dev0` suffix
-  (e.g. `0.2.0.dev0`) — never a clean released number. This matches
+  (e.g. `0.6.0.dev0`) — never a clean released number. This matches
   MLflow / Delta / Unity Catalog and keeps every `main` build PEP 440-ordered as
   "ahead of the last release, not yet the next one".
-- Releases are cut on **per-minor release branches** (`branch-X.Y`) and tagged
-  there (`vX.Y.Z`); patches (`vX.Y.1`, `vX.Y.2`, …) are cherry-picked onto the
-  same `branch-X.Y`. `main` is never tagged.
+- Releases are cut on **per-minor release branches** (`release/vX.Y.0`) and tagged
+  there (`vX.Y.Z`, rc tags `vX.Y.ZrcN`); patches (`vX.Y.1`, `vX.Y.2`, …) are
+  cherry-picked onto the same `release/vX.Y.0`. `main` is never tagged.
+- Every release ships as an **rc first** (`0.6.0rc1` → … → `0.6.0`). rcs go to
+  **real PyPI** as PEP 440 pre-releases — a default `pip install omnigent`
+  never resolves them, and testers install with exact pins. TestPyPI is no
+  longer part of the standard flow.
 
 ## Docs staging
 
@@ -56,221 +61,247 @@ branch** on `omnigent-site` instead of `main`:
 - **`doc-sync.yml`** — drafts prose docs for each merged PR that needs them.
 - **`sync-openapi-to-site.yml`** — syncs the API reference (`openapi.json`).
 
-Both derive the branch name from `omnigent/version.py` (`0.5.0.dev0` → `0.5-docs`)
+Both derive the branch name from `omnigent/version.py` (`0.6.0.dev0` → `0.6-docs`)
 and create it off site `main` the first time a doc PR lands in the cycle. All docs
-for the `0.5` line — including patches — accumulate on `0.5-docs`. Each PR still
+for the `0.6` line — including patches — accumulate on `0.6-docs`. Each PR still
 gets its own review, but merging one only lands it on the staging branch, not the
-live site.
-
-At release, publishing the GitHub Release fires `publish-changelog.yml`, which
-opens the **`0.5-docs → main`** PR (see step 5). Merging that publishes the whole
-cycle's docs at once. Nothing to create or retarget by hand — the branch name
-tracks `main`'s version automatically.
+live site. At finalize time, the whole batch goes live at once (step 4 below).
 
 ---
 
-## Release steps (example: `v0.2.0`)
+## Standard flow
 
-### 1. Cut the release branch + tag — `omnigent-ai/omnigent` (OSS account)
+### rc phase (example: `0.6.0rc1`)
 
-Only tag a commit that already has **green CI** — verify `main` is green before
-branching:
+**1. Cut + tag — dispatch `Release` (`release.yml`), OSS account.**
 
 ```bash
-gh auth switch --user <oss-account>
-git fetch origin
-gh run list --repo omnigent-ai/omnigent --branch main --status success --limit 1
-git checkout -b branch-0.2 origin/main
+gh workflow run release.yml --repo omnigent-ai/omnigent \
+  -f version=0.6.0rc1 -f dry_run=false
+# optional: -f ref=<sha> to cut release/v0.6.0 from a specific commit (rc1 only);
+# dry_run defaults to true — run once without -f dry_run to preview the plan.
 ```
 
-Set the release version in **all three** `pyproject.toml` files — the
-`version` field **and** the cross-package `==` pins — plus `uv.lock`
-(`0.2.0.dev0` → `0.2.0`):
+What it does (all idempotent):
 
-- `pyproject.toml` (`version`, `omnigent-client==`, `omnigent-ui-sdk==`)
-- `sdks/python-client/pyproject.toml` (`version`, `omnigent==`)
-- `sdks/ui/pyproject.toml` (`version`, `omnigent-client==`)
-- `uv.lock` — **hand-edit** the three `version = "…"` lines (omnigent,
-  omnigent-client, omnigent-ui-sdk) and the one cross-pin `specifier = "==…"`
-  (`omnigent-ui-sdk`'s dep on `omnigent-client`). The three packages are
-  **editable workspace members** (`source = { editable = … }`), so uv records
-  **no wheel `hash` entries** for them, and the other two cross-deps appear as
-  `editable = "…"` with no `==` specifier — so only those version/specifier
-  strings change, nothing else (no hashes to touch).
-  **Do not run `uv lock`** locally: it rewrites every registry URL to the
-  internal proxy and that leaks into the lockfile (breaks CI). The published
-  lock must use `https://pypi.org/simple`.
+- asserts green CI on the base commit (escape hatch: `-f skip_ci_check=true`,
+  use deliberately — needed for a flaky check, or when the base commit ran no
+  checks at all, e.g. a cherry-pick that only touched `paths-ignore`d files);
+- creates `release/v0.6.0` from `ref` (rc1) or reuses the existing branch head
+  (rc2+, final, patches — `ref` is ignored then);
+- stamps the lockstep version via `scripts/update_versions.py` and regenerates
+  `uv.lock` with a clean public-PyPI resolution — **never hand-edit `uv.lock`
+  or run `uv lock` behind a proxy**; the workflow owns this now;
+- commits `release: v0.6.0rc1`, tags, and pushes branch + tag with the
+  omnigent-ci App token, which fires the downstream automation:
+  `github-release.yml` (draft GH release, pre-release flagged),
+  `draft-release-notes.yml`, and `oss-publish-images.yml` (Docker);
+- on the **first** cut of a cycle (rc1), dispatches `bump-version.yml`
+  (post-release) — **review and merge the `main → 0.7.0.dev0` bump PR
+  promptly**, so `doc-sync` keeps staging to the right docs branch.
 
-Stage exactly the version files (don't `-a`, which would sweep in any stray
-local edits), then commit, tag, and push **the branch + only this tag**:
+**2. Publish to PyPI — dispatch the secure repo (EMU account).**
 
 ```bash
-git add pyproject.toml sdks/python-client/pyproject.toml sdks/ui/pyproject.toml uv.lock
-git commit -m "release: v0.2.0"
-git tag v0.2.0
-git push -u origin branch-0.2 v0.2.0        # explicit tag, NOT --tags; pushing the tag drafts the GitHub Release (step 5)
-```
-
-> Pushing the tag also kicks off the **changelog automation** (see step 5):
-> `github-release.yml` drafts the Release, then `draft-release-notes.yml` opens a
-> `CHANGELOG.md` PR and fills the draft with curated notes — both ready by the time
-> you get to step 5.
-
-Keep `main` from re-freezing — bump it to the next dev marker and push:
-
-```bash
-git checkout main
-# set 0.2.0.dev0 -> 0.3.0.dev0 in the 3 pyprojects (+ pins) and uv.lock.
-# Hand-edit uv.lock here too — same rule, do NOT run `uv lock` (it leaks the proxy URL).
-git add pyproject.toml sdks/python-client/pyproject.toml sdks/ui/pyproject.toml uv.lock
-git commit -m "chore: bump main to 0.3.0.dev0"
-git push
-```
-
-### 2. Dry-run the gates — secure repo (EMU account)
-
-```bash
-gh auth switch --user <emu-account>
+gh auth switch --user <secure-repo-account>
 gh workflow run omnigent.yml --repo databricks/secure-public-registry-releases-eng \
-  -f ref=v0.2.0 -f destination=test-pypi -f dry-run=true
-```
-
-Runs build + dependency scan + the gates (lockstep version/pins, web-UI-in-wheel,
-`twine check`, smoke-install) and the OIDC token exchange — **without uploading**.
-
-### 3. Publish to TestPyPI + validate
-
-```bash
+  -f ref=v0.6.0rc1 -f destination=pypi -f dry-run=true    # gates rehearsal
 gh workflow run omnigent.yml --repo databricks/secure-public-registry-releases-eng \
-  -f ref=v0.2.0 -f destination=test-pypi -f dry-run=false
+  -f ref=v0.6.0rc1 -f destination=pypi -f dry-run=false   # real publish
 ```
 
-Validate in a clean venv. **Don't** use `--extra-index-url` with TestPyPI: pip
-resolves each name across *both* indexes and picks the highest version, so anyone
-squatting `omnigent` / `omnigent-client` / `omnigent-ui-sdk` on real PyPI at a
-higher version wins the resolution (dependency confusion). Instead, take **deps
-from real PyPI only** and the **candidates from TestPyPI only**, exact-pinned with
-`--no-deps`:
+The dry run exercises build + dependency scan + the gates (lockstep
+version/pins, web-UI-in-wheel, `twine check`, smoke-install) and the OIDC
+token exchange without uploading. The real run binds the per-package
+Trusted-Publisher environments (may gate on reviewer approval) and re-verifies
+that `ref` is exactly the tag and points at the built commit.
+
+**3. Validate from PyPI** (clean venv; exact pins resolve pre-releases;
+behind a corporate network, point `--index-url` at your PyPI mirror
+instead — this is a manual step on purpose: the secure repo's runners
+cannot see a fresh index view, so no CI job can do it):
 
 ```bash
-python -m venv /tmp/omni-rc
-# 1) seed the dependency closure from REAL PyPI (the last released omnigent):
-/tmp/omni-rc/bin/pip install --index-url https://pypi.org/simple/ omnigent
-# 2) overlay the candidates from TestPyPI ONLY, exact-pinned, no deps:
-/tmp/omni-rc/bin/pip install --index-url https://test.pypi.org/simple/ --no-deps \
-  omnigent==0.2.0 omnigent-client==0.2.0 omnigent-ui-sdk==0.2.0
-/tmp/omni-rc/bin/omnigent --version    # expect 0.2.0
+python -m venv /tmp/omni-rc && /tmp/omni-rc/bin/pip install \
+  --index-url https://pypi.org/simple/ \
+  omnigent==0.6.0rc1 omnigent-client==0.6.0rc1 omnigent-ui-sdk==0.6.0rc1
+/tmp/omni-rc/bin/omnigent --version    # expect 0.6.0rc1
 ```
 
-> If this release **adds a new runtime dependency** the previous release didn't
-> have, install it explicitly from real PyPI first
-> (`/tmp/omni-rc/bin/pip install --index-url https://pypi.org/simple/ <dep>`) —
-> never let a `--no-deps` TestPyPI install pull third-party deps from TestPyPI.
+The rc's GitHub draft stays **unpublished** — rc drafts are never published.
+Need another candidate? Repeat with `0.6.0rc2` (fixes land on `release/v0.6.0`
+first, via cherry-pick PRs or direct pushes; CI runs on `release/v*` pushes).
 
-### 4. Publish to PyPI (prod)
+### Final phase (example: `0.6.0`)
 
-Requires **admin/maintain** on the secure repo (if you hit a 403, request access
-via the secure-release owning team / internal release wiki before proceeding);
-binds the per-package `pypi-omnigent`, `pypi-omnigent-client`,
-`pypi-omnigent-ui-sdk` Trusted-Publisher environments (may gate on reviewer
-approval). The prod path also re-verifies that
-`ref` is exactly the `vX.Y.Z` tag and that the tag points at the built commit.
+1. **Cut + tag**: `gh workflow run release.yml -f version=0.6.0 -f dry_run=false`
+   — same as above; builds from the `release/v0.6.0` head.
+2. **Publish to PyPI**: same secure-repo dispatches on `ref=v0.6.0`.
+3. **Curate**: merge the `CHANGELOG.md` PR that `draft-release-notes.yml`
+   opened, and review/trim the curated notes in the `v0.6.0` draft on the
+   Releases page — whatever you leave becomes the website post.
+4. **Finalize — dispatch `Finalize release` (`finalize-release.yml`)**:
 
-```bash
-gh workflow run omnigent.yml --repo databricks/secure-public-registry-releases-eng \
-  -f ref=v0.2.0 -f destination=pypi -f dry-run=false
+   ```bash
+   gh workflow run finalize-release.yml --repo omnigent-ai/omnigent -f tag=v0.6.0
+   ```
 
-uv tool install omnigent==0.2.0        # final sanity from real PyPI
-```
+   It verifies PyPI serves all three packages, the CHANGELOG PR isn't open,
+   and the **docs sweep**: no open PRs against `0.6-docs` on `omnigent-site`
+   (it lists any stragglers — get them reviewed and merged/closed, then
+   re-dispatch). Then it pauses on the **`publish-release` environment**;
+   approving it attests "I reviewed the draft notes". It publishes the release
+   as **Latest**, which fires:
+   - `publish-changelog.yml` → the site **release-post PR** and the
+     **`0.6-docs → main` docs-publish PR** — review and merge both;
+   - `update-homebrew.yml` → the **homebrew-tap bump PR** (new sdist pin +
+     regenerated resources; test-bot builds the bottles on it) — review the
+     resource diff, then apply the **`pr-pull`** label to bottle + merge.
 
-> Note: the dispatch's `-f ref=v0.2.0` is the **omnigent source ref**; it is
-> distinct from `gh workflow run --ref`, which selects the branch the *workflow
-> definition* runs from (the secure repo's default).
+### Patch release (example: `0.6.1`)
 
-### 5. Publish the GitHub Release — `omnigent-ai/omnigent` (OSS account)
-
-Pushing the `v0.2.0` tag (step 1) set the **changelog automation** in motion —
-two workflows have already done the prep for you:
-
-- `github-release.yml` created a **draft** release.
-- `draft-release-notes.yml` (fires right after) then:
-  1. opened a **`CHANGELOG.md` PR to `main`** — the granular, feature-level log,
-     harvested mechanically from each merged PR's `## Changelog` section; and
-  2. **filled the draft's body** with concise, curated notes (Major new features /
-     Breaking changes / Bug fixes — user-facing only), synthesized by an agent from
-     the merged PRs, with the original auto-notes tucked into a collapsed
-     `<details>` for reference. Security and CI/internal fixes are deliberately left
-     out of the highlights.
-
-Now:
-
-1. **Merge the `CHANGELOG.md` PR** as part of cutting the release, so the draft's
-   `Full Changelog` link (which points at `CHANGELOG.md` on `main`) resolves.
-2. Open <https://github.com/omnigent-ai/omnigent/releases>, find the `v0.2.0`
-   draft, and **review/trim the curated notes** — they're a strong starting point,
-   not the final word. Lead with user-facing highlights; call out breaking changes.
-   Whatever you leave here becomes the website post, so curate it well.
-3. **Publish the release** (ideally only after the prod PyPI publish in step 4 has
-   succeeded, so you never advertise a version that isn't installable).
-
-Publishing a **final** release fires `.github/workflows/publish-changelog.yml`,
-which opens **two** PRs to review and merge (pre-releases are skipped):
-
-- **`omnigent-site` `/releases/<version>`** — a per-version post mirroring the
-  notes you just curated (PR refs and angle/brace characters are made MDX-safe for
-  you). Targets `main`.
-- **`omnigent-site` `X.Y-docs → main`** — publishes the docs staged this cycle
-  (see [Docs staging](#docs-staging) below). Skipped if that branch doesn't exist
-  or has nothing beyond `main`. Review the batch and merge to take the version's
-  docs live.
-
-To re-run either half for an already-cut tag: dispatch `draft-release-notes.yml`
-with the `tag` (re-opens the CHANGELOG PR; it leaves the notes alone once the
-release is published), or `publish-changelog.yml` with the `tag` (re-opens the
-site post PR).
-
-If the draft wasn't created (e.g. the workflow was disabled), do it manually:
-
-```bash
-gh auth switch --user <oss-account>
-gh release create v0.2.0 --repo omnigent-ai/omnigent \
-  --draft --verify-tag --generate-notes --title "v0.2.0"
-# review/edit, then publish from the Releases page (or `gh release edit v0.2.0 --draft=false`)
-```
+Cherry-pick the fixes onto `release/v0.6.0` (CI runs on the push), then run the
+same flow with `version=0.6.1` — an rc first if the patch warrants one. `main`
+does not change for a patch, and a patch never needs a new branch.
 
 ---
 
-## Patch release (e.g. `v0.2.1`)
+## One-time setup (repo admin)
 
-Cherry-pick the fix onto the existing `branch-0.2`, then:
-
-1. Confirm CI is green on `branch-0.2` after the cherry-pick
-   (`gh run list --repo omnigent-ai/omnigent --branch branch-0.2 --status success --limit 1`).
-2. Bump the three versions/pins + `uv.lock` to `0.2.1` (same hand-edit rules as above).
-3. Stage explicitly, commit, and tag **on `branch-0.2`**:
-   `git add <version files> && git commit -m "release: v0.2.1" && git tag v0.2.1 && git push origin branch-0.2 v0.2.1`.
-4. Repeat steps 2–5.
-
-`main` does **not** change for a patch, and a patch never needs a new
-`branch-0.Y` — patches always ship from the existing minor branch.
-
----
+- **`publish-release` environment** on `omnigent-ai/omnigent` with required
+  reviewers = the release managers. Without it the finalize publish job runs
+  ungated.
+- **omnigent-ci App** installed on `omnigent-ai/homebrew-tap` (it already
+  covers `omnigent` and `omnigent-site`).
+- **Tag ruleset** (recommended): restrict `v[0-9]*` create/update/delete to
+  the omnigent-ci App + admins, so no write-access account can start the
+  tag-push automation by hand.
 
 ## If a publish goes wrong (recovery)
 
 **PyPI releases can't be deleted, only _yanked_**, and a version number once used
 can never be reused. So:
 
-- **TestPyPI failed / candidate is bad:** bump to the next number (don't reuse the
-  version) and re-run — TestPyPI is disposable.
+- **Any workflow failed mid-run:** fix the cause and **re-dispatch with the
+  same inputs** — every step converges (branch exists → reused; version
+  stamped → no new commit; tag at the converged commit → no-op) or fails
+  loudly (tag elsewhere) rather than duplicating work.
+- **Wrong commit tagged, nothing published yet:** delete the tag and draft
+  (`gh release delete vX.Y.Z`, `git push origin :refs/tags/vX.Y.Z`), then
+  re-dispatch `release.yml`.
+- **rc is bad:** just cut the next rc — rcs are cheap and invisible to
+  default installs.
 - **Prod publish partially succeeded** (e.g. two of three packages uploaded):
   **yank** the published version(s) on PyPI (each affected project → *Manage* →
-  *Releases* → *Yank*) so installs don't resolve a half-published set, then cut the
-  next patch with the fix. Don't try to overwrite — Trusted Publishing / `twine`
-  rejects re-uploading an existing version.
-- **GitHub Release** for a version you abandoned:
-  `gh release delete vX.Y.Z --repo omnigent-ai/omnigent`, and drop the tag if it
-  shouldn't exist (`git push origin :refs/tags/vX.Y.Z`); re-tag only the corrected
-  commit.
-- Publishing uses **OIDC Trusted Publishing (no stored secrets)**, so a failed run
-  leaks nothing — just fix forward to the next version.
+  *Releases* → *Yank*) so installs don't resolve a half-published set, then cut
+  the next version with the fix. Don't try to overwrite — Trusted Publishing /
+  `twine` rejects re-uploading an existing version.
+- Publishing uses **OIDC Trusted Publishing (no stored secrets)**, so a failed
+  run leaks nothing — fix forward to the next version.
+
+---
+
+## Rehearsing the pipeline (throwaway rc release)
+
+To exercise the whole flow end to end without touching users, release a
+deliberately **below-latest** rc on the dead `0.0` line. A below-latest rc is
+inert everywhere that matters: the GitHub draft stays unpublished, Docker
+publishes only the immutable version image tag (`:latest` / `:latest-rc` only
+move for the highest version), the notes/site/homebrew workflows ignore rc
+tags, `bump-main` skips itself (the version sorts below main's), and a
+PEP 440 pre-release is never resolved by a default `pip install` — on real
+PyPI or TestPyPI alike.
+
+**Pick a version that has never touched the destination index.** PyPI
+filenames are burned forever — even for yanked releases — so reusing a number
+fails the upload with "File already exists". (`0.0.1rc1` itself is spent: it
+reserved the PyPI project names in June 2026.) Confirm before starting; a 404
+means the version is free:
+
+```bash
+curl -fsS https://pypi.org/pypi/omnigent/0.0.1rc2/json   # expect 404
+```
+
+The examples below use `0.0.1rc2`; substitute the next free number.
+
+1. **Plan (read-only)** — dry run is the default:
+
+   ```bash
+   gh workflow run release.yml --repo omnigent-ai/omnigent -f version=0.0.1rc2
+   ```
+
+2. **Execute**: re-run with `-f dry_run=false`. Expect `release/v0.0.0` + tag
+   `v0.0.1rc2` pushed, the tag firing the draft-release and image workflows,
+   and CI running on the branch push. If the CI gate rejects main's head
+   (failing or still-pending checks), that's the gate working — wait, or
+   re-dispatch with `-f ref=<green sha>` / `-f skip_ci_check=true`.
+   Cancelled (superseded) runs only warn.
+3. **Idempotency**: dispatch the exact same command again — it must no-op
+   ("already at the converged release commit").
+4. **Secure-repo publish.** Real PyPI is safe for a below-latest rc and
+   exercises the full prod path (the tag gate + the per-package reviewer
+   environments; approve all three) — so rehearse against
+   `destination=pypi`. `destination=test-pypi` also works, but skips the
+   prod tag gate and needs TestPyPI Trusted Publishers configured. Then
+   validate the published rc manually, exactly like a real release (step 3
+   of the standard flow).
+
+   ```bash
+   gh workflow run omnigent.yml --repo databricks/secure-public-registry-releases-eng \
+     -f ref=v0.0.1rc2 -f destination=pypi -f dry-run=true    # gates only
+   gh workflow run omnigent.yml --repo databricks/secure-public-registry-releases-eng \
+     -f ref=v0.0.1rc2 -f destination=pypi -f dry-run=false   # real publish
+   ```
+
+5. **No-double-publish check** (optional): re-dispatching step 4's second
+   command must FAIL every leg with "File already exists" — PyPI
+   immutability doing its job. The publish is deliberately **write-only**:
+   the release runners cannot read the index, so there is no
+   already-published skip (a curl probe and twine's `--skip-existing` both
+   failed live for exactly that reason). A real partial publish is recovered
+   by yank + next version (see "If a publish goes wrong").
+6. **Finalize gates (no side effects)**:
+   `gh workflow run finalize-release.yml -f tag=v0.0.1rc2` must fail fast
+   ("not a final tag"), and `-f tag=v0.5.1` (any already-published release)
+   must no-op as already published.
+
+Cleanup — delete everything the rehearsal minted on GitHub:
+
+```bash
+gh release delete v0.0.1rc2 --repo omnigent-ai/omnigent --cleanup-tag --yes
+gh api -X DELETE 'repos/omnigent-ai/omnigent/git/refs/heads/release/v0.0.0'
+```
+
+Optionally delete the rehearsal image versions from GHCR. The PyPI side needs
+no cleanup: the rc is invisible to default installs and only the version
+number is spent — optionally yank it (*Manage → Releases → Yank*) for
+tidiness.
+
+---
+
+## Break-glass appendix (manual fallback)
+
+If the workflows are unavailable, the flow can be driven by hand — but keep two
+rules even then:
+
+1. **Never hand-edit `uv.lock` and never run `uv lock` behind a proxy.** Use
+   `bump-version.yml` (mode `pre-release`, `base_branch=release/vX.Y.0`) to
+   produce the bump as a PR with a cleanly regenerated lockfile, and merge it.
+2. **Push tags from an account, not automation you improvised** — the tag push
+   must fire `github-release.yml` et al., which a `GITHUB_TOKEN`-authored push
+   would not.
+
+```bash
+gh auth switch --user <oss-account>
+git fetch origin && git checkout -b release/v0.6.0 origin/main   # rc1 only
+gh workflow run bump-version.yml -f mode=pre-release -f new_version=0.6.0rc1 \
+  -f base_branch=release/v0.6.0                                  # then merge the PR
+git fetch origin && git checkout release/v0.6.0 && git pull
+git tag v0.6.0rc1 && git push origin release/v0.6.0 v0.6.0rc1    # explicit tag, NOT --tags
+```
+
+Then continue from step 2 of the standard flow (secure-repo dispatches). If the
+GH draft wasn't created, `gh release create vX.Y.Z --draft --verify-tag
+--title vX.Y.Z` recreates it. To re-run the notes/site halves for an existing
+tag, dispatch `draft-release-notes.yml` or `publish-changelog.yml` with the
+`tag` input; for the tap, dispatch `update-homebrew.yml`.

deploy/docker/Dockerfile

@@ -334,7 +334,8 @@ RUN set -eu; \
 # site-packages and imports no longer require /build at runtime.
 COPY --from=builder /opt/venv /opt/venv
 COPY --from=builder /build /build
-RUN pip install --no-cache-dir /build
+RUN pip install --no-cache-dir /build /build/sdks/python-client /build/sdks/ui \
+ && ! grep -R --include='*.pth' --include='*.egg-link' -nE '/build(/|$)' /opt/venv/lib/python*/site-packages
 
 # Sandbox launchers exec commands through `bash -lc`, and Debian's
 # /etc/profile unconditionally resets PATH for login shells — the ENV

deploy/islo/README.md

@@ -10,10 +10,9 @@ running Omnigent hosts, two ways:
   a session is created with `"host_type": "managed"` and terminates it
   when the session is deleted.
 
-Sandboxes boot from the official prebaked host image, so startup is
-seconds. Unlike Modal and Daytona, the Islo launcher talks to the Islo
-HTTP API directly through `httpx` (already an Omnigent dependency), so
-there is **no provider SDK extra to install** — just an API key.
+Sandboxes boot from the official prebaked host image. The Islo launcher
+uses the Islo Python SDK, installed with the optional `omnigent[islo]`
+extra, and authenticates with an API key.
 
 What makes Islo different from the other providers, and shapes the rest
 of this guide:
@@ -31,11 +30,13 @@ of this guide:
 
 ## Prerequisites
 
-Install the [Islo CLI](https://docs.islo.dev) and create an API key, then
-make it available where the launcher runs — your shell for the CLI flow,
-the **server** process for managed sandboxes:
+Install Omnigent with the Islo extra, install the
+[Islo CLI](https://docs.islo.dev), and create an API key. Make the key
+available where the launcher runs — your shell for the CLI flow, the
+**server** process for managed sandboxes:
 
 ```bash
+pip install 'omnigent[islo]'                   # or: uv tool install 'omnigent[islo]'
 curl -fsSL https://islo.dev/install.sh | sh   # install the islo CLI
 islo login                                     # browser OAuth (one-time)
 islo api-key create omnigent --show            # prints an islo_key_… value
@@ -44,9 +45,9 @@ export ISLO_API_KEY=islo_key_…
 # export ISLO_BASE_URL=https://api.islo.dev
 ```
 
-`ISLO_API_KEY` is exchanged for a short-lived session token at
-`POST /auth/token`; the token is cached until shortly before expiry. The
-key is the only required credential — no SDK, no `~/.config` file.
+`ISLO_API_KEY` is exchanged by the SDK for short-lived session tokens and
+refreshed automatically. The key is the only required runtime credential;
+no `~/.config` file is needed where the launcher runs.
 
 > [!NOTE]
 > **Islo cannot forward a local callback port into the sandbox.** The
@@ -95,7 +96,7 @@ pulls the image, not Omnigent).
 Provision a sandbox and ship your local checkout into it:
 
 ```bash
-omnigent sandbox create --provider islo
+omnigent sandbox create --provider islo --server https://your-host
 ```
 
 This pulls the host image, builds wheels from your local checkout, and
@@ -121,6 +122,31 @@ delete the old one (Islo sandboxes have no lifetime cap, so an abandoned
 sandbox keeps billing until removed via `islo rm <id>` or the
 [dashboard](https://app.islo.dev)).
 
+### Live smoke checklist
+
+Use this checklist before opening a provider-change PR, or when validating
+a new Islo account/key. It assumes your Omnigent server is reachable from
+Islo's cloud at `https://your-host` (for local testing, expose it with a
+tunnel and use the public URL).
+
+```bash
+islo login
+islo api-key create omnigent-smoke --show
+export ISLO_API_KEY=islo_key_...
+omnigent sandbox create --provider islo --server https://your-host
+omnigent sandbox connect --provider islo \
+  --sandbox-id <id-printed-by-create> \
+  --server https://your-host
+islo ls
+islo rm <id-printed-by-create>
+```
+
+Expected result: `create` provisions the sandbox and ships wheels,
+`connect` registers the host with the Omnigent server, `islo ls` shows the
+sandbox while it exists, and `islo rm` deletes it. If `connect` cannot
+reach the server, first verify the `--server` URL from a machine outside
+your laptop network.
+
 To inject LLM/git credentials into a CLI-launched sandbox, set
 `OMNIGENT_ISLO_SANDBOX_ENV` in your shell to a comma-separated list of
 variable names (e.g. `ANTHROPIC_API_KEY,GIT_TOKEN`) before running
@@ -184,6 +210,12 @@ Each managed sandbox authenticates back with a server-minted, per-launch
 token (7-day TTL — see [Lifecycle](#lifecycle-notes)); no user
 credentials enter the sandbox for the server connection.
 
+Managed Islo sandboxes pause after 15 idle minutes by default. When a new
+message arrives for a session bound to an offline Islo-managed host,
+Omnigent resumes the same sandbox id, mints a fresh launch token, and
+restarts `omnigent host` against the existing workspace. Deleting the
+session still deletes the sandbox.
+
 ### Managed hosts and server auth
 
 How the dial-back authenticates depends on how the **server** does auth,
@@ -234,11 +266,12 @@ sandbox:
     env: [OPENAI_API_KEY, GIT_TOKEN]               # copy from server env
     base_url: https://api.islo.dev                 # non-default API endpoint
     gateway_profile: default                       # Islo gateway for egress + credential injection
-    snapshot_name: warm-host                       # boot from a prebaked snapshot
+    snapshot_name: omnigent-host-snapshot          # optional named Islo snapshot
     workdir: /root/workspace                       # sandbox working directory
     vcpus: 2
     memory_mb: 4096
     disk_gb: 20
+    idle_pause_after_s: 900                        # null disables idle pause
 ```
 
 ## Model credentials (LLM keys)
@@ -441,8 +474,21 @@ guide](../modal/README.md#git-credentials-private-repositories).
   yourself (`islo rm <id>`).
 - **Resources.** Sandboxes default to 2 vCPUs and 4 GiB of memory;
   override per managed launch with `vcpus` / `memory_mb` / `disk_gb`.
-- **Warm starts.** Set `sandbox.islo.snapshot_name` to boot from a
-  prebaked Islo snapshot instead of a cold image pull.
+- **Snapshots.** Set `sandbox.islo.snapshot_name` to boot from a named
+  Islo snapshot instead of the configured image.
+- **Idle pause.** Server-managed Islo sandboxes pause after 15 idle
+  minutes by default (`idle_pause_after_s: 900`). Set
+  `idle_pause_after_s: null` to opt out and manage sandbox lifetime
+  yourself. The policy is set when the sandbox is created, so changing it
+  affects new managed sandboxes, not existing ones. This uses Islo's
+  pause/resume lifecycle because the workspace survives and Omnigent can
+  wake it on the next message. Daytona's 15-minute provider default is
+  disabled in Omnigent instead, because Daytona auto-stop would otherwise
+  kill the host between turns.
+- **Managed resume.** Paused or stopped server-managed Islo sandboxes can
+  resume in place under the same sandbox id and workspace. Session delete
+  still deletes the sandbox. This resume path is what wakes a 15-minute
+  idle-paused host on the next message.
 - **Provider-side lifecycle** (list / status / delete / stop) — use the
   `islo` CLI (`islo ls`, `islo rm <id>`) or the
   [dashboard](https://app.islo.dev) directly.
@@ -485,6 +531,7 @@ free credits. Rates: [islo.dev](https://islo.dev).
 |---|---|---|
 | `ISLO_API_KEY` | CLI machine / server | Islo API credentials (required) |
 | `ISLO_BASE_URL` | CLI machine / server | Non-default Islo API endpoint (default `https://api.islo.dev`) |
+| `ISLO_COMPUTE_URL` | CLI machine / server | Non-default Islo compute endpoint (SDK default is production compute) |
 | `OMNIGENT_ISLO_HOST_IMAGE` | CLI machine / server | Override the host image ref (`sandbox.islo.image` takes precedence for managed) |
 | `OMNIGENT_ISLO_SANDBOX_ENV` | CLI machine / server | Comma-separated launcher-side env var names to inject (`sandbox.islo.env` takes precedence for managed) |
 | `OMNIGENT_RUNNER_ENV_PASSTHROUGH` | inside the sandbox (injected) | Extra env var names the host forwards to runners |

deploy/kubernetes/README.md

@@ -249,13 +249,12 @@ The `overlays/sandbox-runners/` overlay turns on the **`kubernetes`** managed
 sandbox provider: a `host_type: managed` session spawns one runner Pod that runs
 `omnigent host` as its entrypoint and dials back over the launch-token tunnel. It
 adds a dedicated runner namespace, a least-privilege server SA (scoped Pod +
-Secret rights, **no `pods/exec`**), and the `sandbox:` server config. The server
-image must be built with the `kubernetes` extra
-(`--build-arg OMNIGENT_EXTRAS=kubernetes`). See
-`overlays/sandbox-runners/README.md` for the full guide.
+Secret rights, **no `pods/exec`**), and the `sandbox:` server config. The
+overlay swaps in the official `omnigent-server-kubernetes` image variant, which
+adds the `kubernetes` client extra the provider imports (the base server image
+omits it). See `overlays/sandbox-runners/README.md` for the full guide.
 
 ```bash
-# set the server image in overlays/sandbox-runners/kustomization.yaml first
 kubectl apply -k deploy/kubernetes/overlays/sandbox-runners
 # then create the omnigent-creds harness Secret (see the overlay README)
 ```

deploy/kubernetes/overlays/sandbox-runners/README.md

@@ -42,10 +42,11 @@ the generated runner Pod is already restricted-compliant (non-root uid 1000, dro
 
 ## Prerequisites
 
-1. **A server image built with the `kubernetes` extra.** The base image omits
-   it, so `_ensure_sdk()` would fail every launch. Build with
-   `--build-arg OMNIGENT_EXTRAS=kubernetes` (see `deploy/docker`) and set the
-   image in `kustomization.yaml` (`images:` → `newName`/`newTag`).
+1. **A server image built with the `kubernetes` extra.** The overlay's
+   `images:` block already points at the official `omnigent-server-kubernetes`
+   variant, which includes it — nothing to build. If you self-build instead,
+   keep `kubernetes` in `OMNIGENT_EXTRAS` (see `deploy/docker`) or
+   `_ensure_sdk()` fails every launch, and point `images:` at your build.
 2. **Harness credentials.** The runners read their LLM / git credentials from a
    Secret named by `secret_name` (default `omnigent-creds`); you create it out of
    band after applying the overlay — see step 2 of **Apply**. It is deliberately
@@ -130,9 +131,9 @@ writing nothing to disk — use HTTPS repository URLs. Details by provider match
 | `namespace` | Runner-Pod namespace (defaults to `omnigent-sandboxes`). |
 | `secret_name` | Harness-creds Secret projected into every Pod via `envFrom`. |
 | `service_account` | ServiceAccount the runner Pods run as (powerless). |
-| `image` | Optional runner image override (defaults to the official amd64 host image). |
+| `image` | Optional runner image override (defaults to the official multi-arch amd64/arm64 host image). |
 | `env` | Optional list of SERVER env-var names to inject as literal Pod env (prefer `secret_name` for credentials). |
-| `node_selector` | Optional extra node labels, merged with the mandatory `kubernetes.io/arch: amd64`. |
+| `node_selector` | Optional extra node labels, merged with a default `kubernetes.io/arch: amd64` — set that key to `arm64` to schedule runners on arm64 nodes. (arm64 note: the CEL policy module is unavailable there — `cel-expr-python` ships no aarch64 wheel — and degrades gracefully.) |
 | `resources` | Optional `requests` / `limits` (`cpu` / `memory`) override. |
 | `in_cluster` | Optional cluster-config source: `true` (in-cluster SA only), `false` (kubeconfig only), omit (try in-cluster, then kubeconfig). |
 | `kubeconfig` | Optional kubeconfig path for the out-of-cluster fallback (env: `OMNIGENT_KUBERNETES_KUBECONFIG`). |

deploy/kubernetes/overlays/sandbox-runners/kustomization.yaml

@@ -17,13 +17,14 @@ resources:
 # omnigent-creds) is NOT checked in — create it out of band like the base
 # OIDC secret (see README.md "Apply"). Prefer sealed-secrets/external-secrets.
 
-# The base server image lacks the `kubernetes` extra, so a managed launch would
-# fail to import the client. Build the server WITH it
-# (`--build-arg OMNIGENT_EXTRAS=kubernetes`, see deploy/docker) and set it here.
+# Use the server image variant that includes the kubernetes client extra
+# (built by CI with OMNIGENT_EXTRAS=kubernetes). The base image omits it, so a
+# managed launch there fails to import the client. Self-builds must keep
+# `kubernetes` in OMNIGENT_EXTRAS (see deploy/docker); point newName at such a
+# build here if you use one.
 images:
   - name: ghcr.io/omnigent-ai/omnigent-server
-    newName: ghcr.io/REPLACE_ME/omnigent-server
-    newTag: kubernetes
+    newName: ghcr.io/omnigent-ai/omnigent-server-kubernetes
 
 patches:
   - path: deployment-patch.yaml

deploy/kubernetes/overlays/sandbox-runners/sandbox-config.yaml

@@ -28,9 +28,9 @@ data:
         # ServiceAccount the runner Pods run as (deliberately powerless).
         service_account: omnigent-runner
         # ── all optional below ──
-        # image: ghcr.io/your-org/omnigent-host:latest  # default: official amd64 host image
+        # image: ghcr.io/your-org/omnigent-host:latest  # default: official multi-arch (amd64/arm64) host image
         # env: [PROXY_URL]           # SERVER env vars injected as literal Pod env (prefer secret_name for creds)
-        # node_selector:             # extra node labels, merged with the mandatory kubernetes.io/arch: amd64
+        # node_selector:             # extra node labels; default kubernetes.io/arch: amd64, override to arm64 to run there
         #   disktype: ssd
         # resources:                 # runner Pod sizing (defaults: 0.5-2 cpu / 1-4Gi)
         #   requests: {cpu: "500m", memory: "1Gi"}

designs/RELEASE-AUTOMATION.md

@@ -0,0 +1,492 @@
+# Deterministic release pipeline
+
+Status: accepted 2026-07-14; implemented in this repo 2026-07-15 (release.yml,
+finalize-release.yml, update-homebrew.yml, bump-version App token, branch-CI
+triggers, lockstep CI check, RELEASING.md rewrite). Secure-repo restructure and
+the tag ruleset are follow-ups. Owner: @dhruv0811.
+
+Today a release is an LLM agent (or human) walking `RELEASING.md` step by step:
+~15 CLI commands across two GitHub accounts, two repos, a hand-edited lockfile,
+and judgment calls interleaved with mechanical steps. Every step of that runbook
+is either already a workflow or trivially expressible as one. This doc proposes
+collapsing the mechanical 90% into **two `workflow_dispatch` runs per release
+phase** (rc, then final), parameterized by `version` + `ref`, while keeping every
+human-judgment point (publish approval, notes curation, docs review) as an
+explicit gate rather than an implicit runbook step.
+
+## What exists today (verified against the repo, 2026-07-14)
+
+The pipeline is already more automated than RELEASING.md's manual framing
+suggests. Per release step:
+
+| Step | Mechanism today | Deterministic? |
+| --- | --- | --- |
+| Cut `release/vX.Y.0` from green main/SHA | human CLI | ❌ manual |
+| Lockstep bump (3 `pyproject.toml` + `omnigent/version.py` + `uv.lock`) | `scripts/update_versions.py` (+ `bump-version.yml` wrapper) | ✅ exists, but human-invoked; RELEASING.md still says "hand-edit `uv.lock`" (CI `uv lock` has no proxy problem) |
+| Tag `vX.Y.Z[rcN]` + push | human CLI | ❌ manual |
+| Bump main to next `.dev0` | human CLI (or `bump-version.yml` post-release) | 🟡 semi |
+| Draft GH release (prerelease flag for rc, rerun-safe) | `github-release.yml` on tag push | ✅ |
+| CHANGELOG PR + LLM-curated draft notes | `draft-release-notes.yml` via `workflow_run` (final tags only) | ✅ |
+| Secure-repo gates + PyPI publish | manual `gh workflow run omnigent.yml` ×2–3 (dry-run, [test-pypi], pypi) in `databricks/secure-public-registry-releases-eng` | ❌ manual dispatches |
+| Post-publish validation (clean venv install + `--version`) | human CLI recipe | ❌ manual |
+| Publish GH release as Latest | human UI click | ❌ manual (and API publish does **not** set `make_latest` unless told to) |
+| Site release post + `X.Y-docs → main` PR | `publish-changelog.yml` on `release: published` | ✅ |
+| Sweep open doc PRs against `X.Y-docs` before docs go live | nobody | ❌ missing |
+| Docker images (`:vX.Y.Z`, `:latest`, `:latest-rc`) | `oss-publish-images.yml` on tag push, PEP 440-ordered moving tags | ✅ |
+| Homebrew formula bump (`omnigent-ai/homebrew-tap`) | nobody — tap frozen at **0.2.0** while PyPI is at 0.5.1 | ❌ missing |
+
+Internal precedent: the VS Code extension track already ships the exact target
+shape — `vscode-release-pr.yml` (`version`, `dry_run` → bump PR) +
+`vscode-extension-release.yml` (`version`, `dry_run` → build + draft release).
+This proposal is the same pattern applied to the Python release.
+
+Actual release history confirms the rc-then-final model this automates:
+`v0.4.0rc1 → rc2 → v0.4.0`, `v0.5.0rc1 → rc2 → v0.5.0 → v0.5.1` (patch), with rc
+GitHub releases left as prerelease drafts.
+
+## Target model
+
+Per phase (rc or final), the human does:
+
+```
+rc:    dispatch release.yml (version=0.6.0rc1)      # cut/bump/tag — one run
+       dispatch secure omnigent.yml (ref=v0.6.0rc1) # gates → [approve] → publish → validate
+final: dispatch release.yml (version=0.6.0)
+       dispatch secure omnigent.yml (ref=v0.6.0)
+       …curate the draft notes, merge the CHANGELOG PR…
+       dispatch finalize-release.yml (tag=v0.6.0)   # checks → [approve] → publish-as-Latest
+       …merge the two site PRs it triggers…
+       …review the auto-opened homebrew-tap bump PR, apply the pr-pull label…
+```
+
+Two runs per phase (finalize is the third, final-only, and exists to *gate*
+judgment, not do work). Everything inside a run is deterministic, idempotent,
+and re-dispatchable after a failure with the same inputs.
+
+Deliberately **not** one run: the secure-repo dispatch stays separate because it
+crosses the org/account boundary that repo exists to enforce. Auto-dispatching
+it from the public repo would require storing a Databricks-account PAT in
+`omnigent-ai/omnigent` — weakening the isolation for the sake of one saved
+click. Rejected.
+
+## Workflow 1 — `release.yml` (new, omnigent-ai/omnigent)
+
+`workflow_dispatch` inputs:
+
+- `version` — `0.6.0rc1` | `0.6.0` | `0.6.1` (no leading `v`; `.dev` rejected)
+- `ref` — default `main`; branch/tag/SHA to cut from. **Only consulted when
+  `release/vX.Y.0` does not exist yet** (i.e. at rc1). Later rcs, the final, and
+  patches always build from the existing `release/vX.Y.0` head; passing a `ref` that
+  disagrees with it fails loudly instead of silently retargeting.
+- `dry_run` — default `true` (repo convention, matches the vscode workflows):
+  run the whole plan, print it, push nothing.
+
+Jobs:
+
+1. **plan** (always): validate version shape (reuse `bump-version.yml`'s PEP 440
+   regex minus `.dev`); derive `release/vX.Y.0` + `vX.Y.Z[rcN]`; resolve the base SHA
+   (existing branch head, else `ref`); assert the tag doesn't exist (or already
+   points at the fully-converged state → declare no-op); assert the resolved
+   SHA's check suites are green (not just "some run on main succeeded"); for a
+   final, warn if no `vX.Y.*rc*` tag exists on the branch. Write the plan to the
+   step summary.
+2. **execute** (`dry_run == false`): mint the omnigent-ci App token; create
+   `release/vX.Y.0` at the base SHA if missing; `update_versions.py pre-release
+   --new-version $VERSION`; `uv lock` (runner resolves against real PyPI — this
+   *retires the hand-edit-uv.lock ritual entirely*); `update_versions.py check`;
+   commit `release: vX.Y.Z` (skip when already stamped); tag; push branch + tag
+   **with the App token**. Pushing with the App token (not `GITHUB_TOKEN`) is
+   load-bearing: `GITHUB_TOKEN`-pushed tags do not trigger workflows, and the
+   whole downstream chain (`github-release.yml` → `draft-release-notes.yml`,
+   `oss-publish-images.yml`) hangs off that tag push.
+3. **bump-main** (only when the branch was created in this run, i.e. rc1):
+   `gh workflow run bump-version.yml -f mode=post-release …` — opens the
+   `main → next .dev0` PR immediately at branch cut, exactly as RELEASING.md
+   step 1 prescribes ("keep main from re-freezing"). Merging it promptly also
+   matters for docs: `doc-sync.yml` derives the `X.Y-docs` staging branch from
+   main's version. **Decided:** `bump-version.yml` switches its PR-creation
+   push to the omnigent-ci App token (falling back to `GITHUB_TOKEN` where the
+   App vars are absent, e.g. forks) so CI runs on bump PRs — retiring the
+   documented "push an empty commit to kick CI" workaround.
+4. **summary**: print the exact secure-repo dispatch command for this tag.
+
+Idempotency contract: branch exists → reuse; version already stamped → no
+commit; tag exists at the converged commit → no-op; tag exists elsewhere →
+fail. A half-failed run is always safe to re-dispatch verbatim.
+
+Security posture: this executes repo scripts from a maintainer-chosen,
+CI-green commit under `workflow_dispatch` — the same trust level as the
+existing `bump-version.yml`. The no-code-exec guarantee of `github-release.yml`
+(which is *tag-triggered*, attacker-influenceable) is unaffected.
+
+## Workflow 2 — secure repo `omnigent.yml` restructure
+
+Today: 2–3 dispatches (dry-run=true, optional test-pypi, then pypi) with manual
+validation between. Proposal — same file, split into three chained jobs so one
+dispatch covers the user flow "dry-run, then real publish, then validate":
+
+1. **gates** (always): build all three distributions once; dependency scan;
+   lockstep/pin verification; web-UI-in-wheel; `twine check`; smoke-install.
+   Upload the built artifacts as run artifacts. This *is* the dry run.
+2. **publish**: `needs: gates`, bound to the protected Trusted-Publisher
+   environments (required reviewer = the human authorization click). Downloads
+   the **same artifacts** — never rebuilds, so what was scanned is what ships.
+   Before each upload, probe `https://pypi.org/pypi/<pkg>/<ver>/json` and skip
+   already-published packages (`skip-existing` semantics): a partially-failed
+   publish is healed by re-running instead of yanking, because the remaining
+   identical artifacts complete the set.
+3. **validate**: `needs: publish`. Clean venv; poll the real index until all
+   three resolve (propagation lag, bounded ~10 min); `pip install
+   omnigent==X omnigent-client==X omnigent-ui-sdk==X` (exact rc pins resolve
+   without `--pre`); assert `omnigent --version` == X; import smoke. Replaces
+   the manual venv recipe.
+
+`destination=test-pypi` and `dry-run=true` inputs stay for rehearsals, but the
+standard flow no longer uses TestPyPI (per new policy: rc goes to real PyPI as a
+PEP 440 prerelease, which default `pip install omnigent` never resolves — safer
+than the TestPyPI dependency-confusion dance RELEASING.md currently documents).
+
+Net: one dispatch, one approval click, per phase.
+
+## Workflow 3 — `finalize-release.yml` (new, final releases only)
+
+`workflow_dispatch` input: `tag` (e.g. `v0.6.0`).
+
+1. **checks** (all fail with actionable links):
+   - tag is a final `vX.Y.Z`; a *draft* GH release exists for it;
+   - PyPI serves all three packages at the version (JSON API) — never publish
+     release notes for something uninstallable;
+   - the `auto/changelog/vX.Y.Z` CHANGELOG PR is merged;
+   - **docs sweep**: zero open PRs in `omnigent-site` with base `X.Y-docs` —
+     the deterministic form of "all release docs PRs reviewed + merged/closed".
+     Each open PR is listed in the summary; resolving them stays human work.
+2. **publish** behind a `publish-release` environment (required reviewer).
+   Approving *is* the attestation "I reviewed/curated the draft notes."
+   Then, with the App token: `gh release edit vX.Y.Z --draft=false --latest`.
+   Two footguns handled here that have bitten before: `--latest` must be
+   explicit (API publishes don't set `make_latest`), and the App token (not
+   `GITHUB_TOKEN`) ensures the `release: published` event actually fires
+   `publish-changelog.yml`, which opens the site release-post PR and the
+   `X.Y-docs → main` docs-publish PR.
+3. **summary**: links to the two site PRs awaiting merge.
+
+rc releases never finalize: their GH drafts stay unpublished prerelease drafts
+(**decided**: keep exactly today's pattern — rc drafts are never published on
+GitHub).
+
+## Workflow 4 — `update-homebrew.yml` (new, final releases only)
+
+Current state of `omnigent-ai/homebrew-tap`: a homebrew-core-style tap that is
+already 2/3 automated —
+
+- `Formula/omnigent.rb`: `Language::Python::Virtualenv` formula; stable
+  installs the **PyPI sdist** (url + sha256) with **94 pinned Python
+  resources**; a few deps come from brewed formulae instead
+  (`certifi`/`cryptography`/`pydantic`/`rpds-py` as `:no_linkage`, plus
+  `python@3.14`, `libyaml`, `tmux`, Rust build deps); hand-maintained
+  platform-conditional `google-antigravity` wheel stanzas; bottles hosted on
+  the tap's GitHub releases.
+- `tests.yml`: `brew test-bot` on 3 macOS runners — on every PR it builds the
+  formula (i.e. builds the bottles) and uploads them as artifacts.
+- `publish.yml`: on the `pr-pull` label, `brew pr-pull` publishes the bottles
+  to a tap release, rewrites the bottle block, merges to main.
+
+The **only missing link is the bump PR** — nobody opens it, which is exactly
+why the tap froze at 0.2.0 (2026-06-23) while PyPI moved to 0.5.1. The
+`omnigent-desktop` cask needs nothing: it is `version :latest` /
+`sha256 :no_check` against `omnigent.ai/download/mac`, i.e. evergreen.
+
+New workflow in omnigent-ai/omnigent, shaped exactly like
+`publish-changelog.yml` (event + dispatch fallback, App token, idempotent
+PR-opening):
+
+- Triggers: `release: types: [published]` (fires automatically from
+  finalize's App-token publish; guarded to final `vX.Y.Z` like
+  publish-changelog) + `workflow_dispatch(tag)` for retries and catch-up.
+- Steps: bounded-poll the PyPI JSON API until the new sdist is visible; on a
+  macOS runner with `Homebrew/actions/setup-homebrew`, check out the tap via
+  an App token (App installed on `homebrew-tap`); rewrite `url`/`sha256` from
+  the PyPI metadata and drop any `revision`; regenerate the resource pins with
+  `brew update-python-resources` (excluding the brewed-formula deps and the
+  hand-maintained `google-antigravity` stanzas so they're preserved); run
+  `brew style`/`brew audit` as a sanity gate; push `bump-omnigent-<version>`
+  and open (or update) the tap PR.
+- From there the tap's own machinery takes over: test-bot builds the bottles
+  on the PR; a human reviews the resource diff and applies `pr-pull`; the
+  existing publish workflow bottles + merges. One review + one label click per
+  final release — the human gate the tap already has, kept.
+
+First run doubles as the **catch-up**: dispatch with `tag=v0.5.1` to jump the
+formula 0.2.0 → 0.5.1 (expect that one resource diff to be large).
+
+## Who can trigger a release (maintainer-only)
+
+`workflow_dispatch` is runnable by anyone with write access, which is too
+broad. Every release workflow (`release.yml`, `finalize-release.yml`,
+`update-homebrew.yml`'s dispatch path) gets a first `authorize` job that all
+other jobs `need`:
+
+```
+role=$(gh api "repos/$GITHUB_REPOSITORY/collaborators/${GITHUB_ACTOR}/permission" --jq .role_name)
+case "$role" in admin|maintain) ;; *) fail "release workflows require maintain/admin" ;; esac
+```
+
+`github.actor` on a dispatch is the dispatcher and can't be spoofed; roles
+come from repo settings, so there's no hand-kept allowlist to rot. Defense in
+depth stacks three independent layers: this actor gate (highest repo
+privilege to start anything), the `v[0-9]*` **tag ruleset** (create/update/
+delete restricted to the omnigent-ci App + admins — even a bypassed workflow
+can't tag; goose's primary gate), and the secure repo's own access model
+(admin/maintain to dispatch, environment reviewers on the upload). The
+alternative — a required-reviewer environment on the first job — adds an
+approval click and a separately-maintained reviewer list for no additional
+precision; rejected.
+
+## What stays human, on purpose
+
+1. Choosing version/timing/base commit (the dispatches).
+2. Secure-repo environment approval — publish authorization.
+3. Release-notes curation + the finalize approval that attests to it.
+4. Content review merges: CHANGELOG PR, bump-main PR, doc PRs on `X.Y-docs`,
+   the release-post PR, the docs-publish PR.
+4a. The homebrew-tap bump PR: review the resource diff, apply `pr-pull`.
+5. Yank decisions when something shipped broken (policy unchanged: never reuse
+   a version; `skip-existing` re-runs heal *partial* publishes, yank handles
+   *bad* ones).
+
+## Recovery model
+
+Any run can be re-dispatched with identical inputs after any failure; every
+step converges or fails loudly rather than duplicating. Pre-publish mistakes
+(wrong commit tagged): delete tag + draft, re-dispatch — unchanged from
+RELEASING.md. Post-publish: fix forward to the next version.
+
+## Cleanups this unlocks
+
+- **Delete `release-omnigent.yml`** — its own header says "to be deleted once
+  the secure path has done a prod release", which has now happened repeatedly.
+  Also retire its `pypi`/`test-pypi` Trusted Publishers on PyPI: a live trusted
+  publisher pointing at the public repo is standing attack surface.
+- Rewrite `RELEASING.md` around the dispatches, demoting today's CLI runbook to
+  a break-glass appendix. The `uv.lock` hand-edit instructions disappear.
+
+## What peer projects do (survey, 2026-07)
+
+### pi (`earendil-works/pi`)
+
+Lean solo-maintainer automation, no release branches, no rc channel — cadence
+(a release every 1–2 days) substitutes for candidates. Mechanics worth noting:
+
+- **Draft-then-flip**: binaries staged on a *draft* GH release; the release is
+  made public only after npm publish succeeds; any failure deletes the draft;
+  the workflow *refuses to mutate an already-published release*.
+- **Idempotent publish**: `npm view <pkg>@<ver>` before every upload, skip if
+  present — re-running a tag workflow after a partial failure heals it.
+  (The direct inspiration for the `skip-existing` PyPI probe above.)
+- **Recovery dispatch**: the tag-triggered build workflow has a
+  `workflow_dispatch` twin with `tag` + `source_ref`, labeled "release
+  recovery only".
+- Lockstep versions across 4 npm packages enforced by one sync script with a
+  check mode (their `sync-versions.js` ≈ our `update_versions.py`).
+- Release notes: maintainer runs pi's own `/cl` prompt to audit CHANGELOG
+  entries with a human-confirm step — the same posture as our
+  `draft-release-notes.yml` + human curation.
+- Pre-publish smoke is a *manual* isolated-install checklist in AGENTS.md;
+  **no automated post-publish validation exists** in their CI.
+
+### opencode (`anomalyco/opencode`)
+
+Continuous-publish machine: every push to `dev` ships an npm prerelease under
+a branch-named dist-tag; an hourly bot assembles a `beta` branch (with their
+own agent resolving merge conflicts); a real "latest" release is **one
+`workflow_dispatch` click** (bump dropdown) — build, sign, notarize, npm,
+Docker, AUR, Homebrew, LLM-authored release notes, Discord announce, all
+unattended. Relevant mechanics:
+
+- Bot pushes via a **GitHub App token** (`create-github-app-token`), never a
+  PAT — same identity pattern as our omnigent-ci App.
+- Same idempotent already-published-skip before every npm publish.
+- npm auth is OIDC trusted publishing, zero registry tokens in CI.
+- Fully autonomous LLM changelog with *no* human review gate, and no
+  environment protection on the publish job at all — a rigor level below what
+  a Databricks-governed project should copy.
+- Docs are evergreen/unversioned, deployed on push, fully decoupled from
+  releases.
+
+### Cross-cutting (both)
+
+- **Neither peer automates post-publish validation** (clean-env install of
+  the just-published artifact + run it). The `validate` job in the secure repo
+  puts omnigent ahead of both, not just at parity.
+- **Neither has an rc→final concept** — both rebuild rather than promote.
+  Rebuilding the final from the same `release/vX.Y.0` (rather than promoting rc
+  artifacts) is also what our model does; PyPI's no-reupload rule makes
+  rebuild-and-restamp the pragmatic norm.
+- Both decouple docs publishing from the release pipeline structurally — which
+  supports keeping our site PRs as separate human-reviewed merges rather than
+  folding them into `release.yml`.
+
+### cline (`cline/cline`)
+
+Three independent release trains (VS Code extension, CLI, SDK), all
+`workflow_dispatch`, all preconditioned on a *human-authored* version-bump +
+changelog PR — despite appearances, no bot writes their bumps. Worth stealing:
+
+- **Tag/SHA idempotency guard** (`ext-vscode-publish-stable.yml`, "Resolve
+  Release Tag"): tag exists → assert it points at the tested SHA (no-op on
+  match, hard-fail on mismatch); tag absent → create it from the tested SHA
+  after asserting that SHA is an ancestor of `main`. Verbatim the semantics
+  `release.yml`'s plan/execute jobs adopt.
+- **Gate placement**: the named-required-reviewer GitHub Environment guards
+  *only* the VS Code Marketplace publish (highest blast radius); CLI/SDK get a
+  typed `confirm_publish: "publish"` string. Principle: spend the heavyweight
+  second-person gate on the irreversible step only — for omnigent, that is the
+  secure-repo PyPI upload, which already has exactly such an environment.
+- **Changelog-as-gate**: publish hard-fails if the changelog's top entry ≠ the
+  version, then reuses that section as the release body (and a Slack post).
+  Our equivalent is finalize's "CHANGELOG PR merged" check.
+- No release branches, no rc versions (marketplace "pre-release" is a flag on
+  a normal version), no post-publish validation, no rollback story.
+
+### kilocode (`Kilo-Org/kilocode`)
+
+Product forked from cline, but the *release pipeline* is forked from opencode
+(they even poll `anomalyco/opencode` releases to sync). Main train: **one
+dispatch** (`bump` dropdown, `pre_release` defaults true) → version → build →
+**validate matrix** (executes the built binary on macOS/Linux/Windows/Alpine)
+→ **smoke-test** (real eval tasks against the *draft release's* assets) →
+unattended publish to npm/Marketplace/GHCR/AUR/brew. No environment gate at
+all on that train — below the rigor a Databricks-governed project should copy.
+The interesting part is the **JetBrains train**, the only peer flow with true
+rc→stable promotion: `prepare-jetbrains-release.yml` (`kind: rc|stable`,
+`version`, `from_tag`) opens a release branch + PR; the human *merge* of that
+PR is the approval gate; `publish-jetbrains.yml` fires on the merge, with a
+dispatch fallback for re-runs; rc tags chain `-rc.1 … -rc.15 → stable`.
+
+**Considered variant for omnigent** (from the JetBrains pattern): have
+`release.yml` open a bump *PR* onto `release/vX.Y.0` instead of pushing directly,
+making the merge a second-person cut-approval and running CI on the bump
+commit. Rejected as the default: the bump is deterministic robot output
+(`update_versions.py` + `check`), the cut is fully reversible, the secure
+repo's gates re-verify everything against the tag before anything publishes,
+and the extra merge per rc works against the 1–2-runs goal. Easy to switch to
+later if a second-person cut gate is ever wanted.
+
+### goose (`block/goose` → now `aaif-goose/goose`)
+
+The closest org-shape analogue (big-company compliance, busy monorepo,
+canary + stable channels, release branches). Minor release = weekly scheduled
+bump PR → human merge → auto-cut `release/X.Y.0` + release PR → human runs two
+copy-pasted `git tag && git push` commands → everything downstream (10-platform
+build, signing, GHCR + SLSA, LLM release notes, Discord, auto-created next
+hotfix branch) is automatic. ~5 human actions per minor. Findings that matter:
+
+- **Their gate is a repo-wide tag-protection ruleset** (create/update/delete
+  blocked on *all* tags without bypass privilege), not environment reviewers —
+  environments are used only to scope secrets. Cheap, auditable.
+- **They hit the `GITHUB_TOKEN` event-suppression gotcha in production**:
+  their LLM release-notes workflow runs on `workflow_run` *specifically*
+  because `release: published` doesn't fire for token-authored releases — the
+  same trap our App-token choices are designed around (and that
+  `draft-release-notes.yml` already dodges the same way).
+- Their SDK packages **silently drifted out of lockstep** because nothing
+  asserts it — the failure mode our `update_versions.py check` prevents, and
+  an argument for running it in CI permanently (see hardening below).
+- Canary = a single floating GH release overwritten in place; promotion is
+  always rebuild-from-source, never relabel.
+- No dry-run, no post-publish validation, dependency scan *not* wired as a
+  publish gate, idempotency uneven, no rollback runbook.
+
+### hermes (`NousResearch/hermes-agent`)
+
+Real and public. CalVer tags (`v2026.7.7.2`), no release branches, no rc
+channel, weekly cadence with same-day suffixed hotfixes; releasing is a local
+`release.py` a maintainer runs (~3 actions), with GH Actions as reactive side
+effects. Worth stealing:
+
+- **Lockstep-as-a-test**: a real CI test asserts their four version locations
+  agree — drift is caught structurally no matter how it happened (bad merge,
+  cherry-pick, manual edit), not just when the bump script runs.
+- **PyPI publish uses `skip-existing: true`** (pypa action) — direct precedent
+  for the partial-publish healing proposed for the secure repo.
+- **Re-publish escape hatch**: `upload_to_pypi.yml` has a dispatch with a
+  `confirm_tag` input documented as "re-publish an existing tag" — the
+  idempotent-retry shape our secure-repo dispatch already has via `ref`.
+- Bounded poll-with-warning (not hard-fail) when reading back a just-created
+  release/tag that may lag — adopted in the `validate` job's PyPI polling.
+- Cautionary tale: their dependency-manifest review ruleset was empirically
+  self-merged around on a real release PR — review gates that the same person
+  can approve are decoration. (The secure repo's separate-org reviewer set
+  doesn't have this hole; keep it that way.)
+
+### Cross-cutting (all six)
+
+- **Nobody automates post-publish validation** — the secure repo `validate`
+  job is ahead of every peer surveyed.
+- **Nobody has versioned docs** — all continuous-deploy latest-only. The
+  `X.Y-docs` staging design has no prior art to borrow; it's already built and
+  just needs the sweep gate.
+- **Nobody has a backport/patch-branch story** as good as `release/vX.Y.0` +
+  cherry-pick; cline maintains one frozen legacy branch, kilocode has nothing.
+- Pre-publish smoke against built artifacts (kilocode) ≈ the secure repo's
+  existing smoke-install gate. Parity, not a gap.
+- **Nobody documents rollback/yank** — RELEASING.md's recovery section is
+  ahead of all six; the new workflows keep it (and make partial-publish
+  recovery automatic via skip-existing).
+- rc→final promotion is rebuild-from-the-pinned-ref everywhere it exists at
+  all (goose canary→stable, kilocode JetBrains) — never artifact relabeling.
+  Validates our model: the final independently re-runs build+scan+publish
+  from `release/vX.Y.0`, which the mandatory dependency scan requires anyway.
+- omnigent's mandatory scan-gates-publish + separate-org publisher is
+  **stricter than every peer surveyed** (goose's scan isn't a gate; hermes's
+  review gate was self-merged around; opencode/kilocode publish unattended).
+
+## Hardening extras (cheap, independent of the workflows)
+
+- **Run `update_versions.py check` in CI permanently** (a test or `ci.yml`
+  step), not just inside bump/release workflows — goose's SDKs silently
+  drifted out of lockstep for lack of exactly this assertion (hermes has it
+  and it works).
+- **Tag ruleset on `v[0-9]*`**: restrict create/update/delete to maintainers +
+  the omnigent-ci App. Today any write-access account can push a version tag
+  and set off the draft-release + docker-publish chain; goose treats tag
+  protection as their primary release gate.
+
+## Decisions (2026-07-14)
+
+> **Correction (2026-07-16, after two live failures):** the
+> skip-existing / partial-publish-healing idea below is **withdrawn**. Every
+> skip mechanism must first *read* the index, and the release runners have
+> no egress to pypi.org's JSON API — the curl probe silently never matched,
+> and twine's `--skip-existing` pre-checks that same API client-side and
+> crashed every upload (secure-repo run 29459796204), including brand-new
+> versions. The publish leg is **write-only**: re-uploads hard-fail
+> ("File already exists") and a partial publish is recovered by yank + next
+> version, as it always was. The peer-survey skip-existing citations stand
+> as facts about those projects; they don't transfer to egress-restricted
+> runners. The **`validate` job is withdrawn for the same reason**: the
+> runners' only index view is a JFrog mirror whose metadata lags weeks
+> behind PyPI (its first live run couldn't see the version it had just
+> published — nor even 0.5.x), so post-publish validation stays the manual
+> runbook step, run from a network with a fresh PyPI view.
+
+1. **Secure-repo restructure: approved direction** — gates → env-approval →
+   publish (skip-existing — *withdrawn, see correction above*) → validate,
+   one dispatch per phase.
+2. **rc GH drafts are never published** — keep today's pattern exactly.
+3. **bump PRs move to the App token** so CI runs on them (empty-commit
+   workaround retired).
+4. **Release workflows are maintainer-only**: `authorize` actor-role gate
+   (admin/maintain) + the `v[0-9]*` tag ruleset as backstop.
+5. **Homebrew joins the pipeline** via `update-homebrew.yml` on
+   `release: published`; tap-side human gate (`pr-pull` label) kept.
+
+## Open questions
+
+1. Environment `publish-release` reviewer set = who may finalize a release.
+2. `brew update-python-resources` vs. the hand-maintained formula sections:
+   confirm on the catch-up run that the exclusion flags preserve the
+   `google-antigravity` platform stanzas and the brewed-dep comments, or keep
+   those sections behind guard comments the updater skips.
+3. Tap bottle coverage (currently arm64 macOS only) — widen the test-bot
+   matrix? Orthogonal to this pipeline; tracked here so it isn't forgotten.

dev/benchmarks/__init__.py

@@ -0,0 +1 @@
+"""Performance benchmarks (runnable via ``uv run``, not shipped)."""

dev/benchmarks/omnigent/README.md

@@ -0,0 +1,263 @@
+# Omnigent performance benchmark
+
+Baseline, repeatable latency/throughput numbers for key Omnigent user
+journeys, so we can track them over time and catch regressions. Modeled on
+MLflow's `dev/benchmarks/gateway/` workflow.
+
+The harness boots a real `omnigent server`, drives the selected journeys under
+load, prints latency/throughput tables, and writes a versioned JSON report.
+Two families: **HTTP/API journeys** (server + DB, no runner/LLM — fast and
+low-noise) and **full-turn journeys** (a real agent turn through the runner +
+a zero-latency mock LLM). See *Journeys* below.
+
+By default the server boots a fresh, empty SQLite DB, which gives best-case
+numbers that don't move with load. For meaningful results, point it at a
+**pre-seeded corpus** (`seed.py`) and, ideally, at **Postgres** — production
+runs on Databricks Lakebase (Postgres), whose per-query round-trip + pooling
+cost SQLite doesn't have. See *Seeding* and *Backends* below.
+
+## Run it
+
+```bash
+# All journeys, sequential latency (100 iterations × 3 runs each).
+uv run --no-sync dev/benchmarks/omnigent/run.py
+
+# A subset, writing a report for CI artifact upload.
+uv run --no-sync dev/benchmarks/omnigent/run.py \
+    --journeys list_sessions,load_conversation_history \
+    --iterations 200 --runs 3 --output bench.json
+
+# Throughput mode: >1 concurrency drives concurrency-safe journeys as load.
+uv run --no-sync dev/benchmarks/omnigent/run.py \
+    --requests 500 --concurrency 25 --runs 3
+
+# CI gating: exit 1 if a threshold is breached.
+uv run --no-sync dev/benchmarks/omnigent/run.py --max-p50-ms 25 --max-p99-ms 100
+```
+
+`--no-sync` runs against the already-installed venv. (A bare `uv run` may try to
+rebuild the project, which fails in a git worktree without a Node web-UI build;
+`OMNIGENT_SKIP_WEB_UI=true uv sync` prepares the venv once, then use
+`--no-sync`.)
+
+Key flags (`--help` for all): `--journeys A,B`, `--database-uri URI` (seeded
+corpus / Postgres; default: throwaway empty SQLite), `--iterations N` (per
+latency run), `--requests N` / `--concurrency N` (throughput), `--runs N`,
+`--warmup N`, `--output FILE`, `--min-rps` / `--max-p50-ms` / `--max-p99-ms`
+(CI thresholds).
+
+## Journeys
+
+### HTTP/API (server + DB, runner-free)
+
+| Journey | Operation timed | Stressed by |
+| --- | --- | --- |
+| `list_sessions` | `GET /v1/sessions` — session-list read | session count |
+| `create_session` | `POST /v1/sessions` then `DELETE` — session create | write path |
+| `get_session` | `GET /v1/sessions/{id}` — single-session snapshot | (O(1)) |
+| `load_conversation_history` | `GET /v1/sessions/{id}/items` — history read | items/session |
+| `search_sessions` | `GET /v1/sessions?search_query=` — unindexed `LIKE` | total item count |
+| `fork_session` | `POST /v1/sessions/{id}/fork` — fork (deep-copy items); forks deleted in teardown, untimed | items/session |
+| `add_comment` | `POST /v1/sessions/{id}/comments` — create a review comment | write path |
+
+Read journeys target a **pre-seeded** session when the DB has a corpus; against
+an empty DB they self-seed a small fallback session over HTTP (the
+`external_conversation_item` event — appends items without starting a task), so
+they still work with no runner or LLM.
+
+### Full-turn (runner + mock LLM)
+
+These drive a real agent turn end-to-end — `POST …/events` → server → **runner**
+→ in-process executor → mock LLM → stream back → `idle`. Selecting any of them
+boots `BenchEnvironment(with_runner=True)` automatically.
+
+Each turn costs ~1 s+ (vs. the millisecond HTTP journeys), so these journeys
+cap their latency iterations (`Journey.max_iterations`, currently 5) — a large
+`--iterations` tuned for the HTTP journeys is clamped down for them so the run
+stays within the CI time budget, with `--runs` providing the repeats. The cap
+only lowers the count, never raises it. A cold start never deletes its session,
+so sessions accumulate across a run; keeping the count small also keeps that
+drift negligible (~2 ms/turn).
+
+| Journey | Operation timed |
+| --- | --- |
+| `session_cold_start` | Spawn a **fresh runner process**, wait for its tunnel, bind a session, and drive the first turn to `idle` — the full new-conversation cold path |
+| `warm_turn` | Drive a turn on an already-warm session — steady-state dispatch overhead |
+| `time_to_first_token` | Post a turn; time to the first streamed `output_text` delta |
+| `interrupt` | Interrupt a running (gated) turn; time to cancellation |
+| `read_runner_file` | `GET .../environments/default/filesystem/{path}` — server → runner filesystem read proxy |
+
+**`session_cold_start` spawns a real runner.** The env spawns one runner at
+boot, but the warm journeys reuse it — so `session_cold_start` instead spawns a
+*fresh* runner subprocess per iteration and waits for its reverse tunnel to
+register before binding and driving the turn. That captures the runner process
+start + tunnel handshake that a real new conversation always pays (and that a
+host-launched session pays on its first message), not just the sub-second
+executor-construction + first-turn overhead. Each iteration terminates its
+runner afterward, so at most one extra runner is ever live. Each spawned runner
+mints its own binding token and derives its `runner_id` from it (so tunnel,
+mint, and session binding all agree on one id) and registers over loopback,
+exactly like the boot runner — a fully independent runner.
+
+`read_runner_file` needs a runner but does **not** drive a turn or call the LLM:
+its setup plants a file via `PUT`, and the timed op is the proxied read (a
+localhost round-trip). Being far cheaper than a turn, it uses a higher iteration
+cap (50) than the full-turn journeys.
+
+**Only measure what we control.** Full-turn journeys always use the
+**`openai-agents`** SDK harness, which runs **in-process** (a call into the
+`agents` library + an HTTP call to the mock LLM) — no vendor binary, no external
+process. Native harnesses (e.g. `claude-native`) launch the real vendor CLI
+into a tmux pane, whose startup we don't control, so they're deliberately
+excluded. The mock LLM is zero-latency, so every number is omnigent
+dispatch/streaming/cancel overhead, not model latency.
+
+Add a journey by registering a `Journey` in `journeys.py` (set `needs_runner`
+for full-turn journeys).
+
+## Seeding a realistic corpus
+
+`seed.py` writes a sizeable, deterministic corpus directly through the store
+API (no HTTP, no runner) into the same DB the server then boots against:
+
+```bash
+# Seed 5000 sessions × 50 items into a SQLite file, then benchmark against it.
+uv run --no-sync dev/benchmarks/omnigent/seed.py \
+    --database-uri sqlite:////abs/path/bench.db --sessions 5000 --items-per-session 50
+uv run --no-sync dev/benchmarks/omnigent/run.py \
+    --database-uri sqlite:////abs/path/bench.db --output bench.json
+```
+
+Seeding is **idempotent**: a matching corpus (same sessions/items/schema) is
+detected and reused, so re-running is a fast no-op — pass `--reseed` to force,
+or a differing config to be warned. SQLite absolute paths need four slashes
+(`sqlite:////abs/...`). The reuse marker records the DB's Alembic head read at
+seed time, so a corpus from an older schema is automatically reseeded — no
+manual revision bookkeeping. `test_seed_creates_listable_corpus` (which seeds
+through the store, running migrations to the current head) is the safety net
+that a schema change hasn't broken seeding.
+
+## Backends
+
+`--database-uri` selects the DB; the report's `backend` field (`sqlite` /
+`postgres` / `mysql`) is derived from the URI scheme so results group by
+backend.
+
+- **SQLite** (default) — in-process; fast, but not prod-representative.
+- **Postgres** — `postgresql+psycopg://user@host:5432/db` (the fully-qualified
+  `+psycopg` form; the server CLI does not normalize a bare `postgresql://`).
+  Requires `psycopg[binary]` (the `databricks` extra). Matches prod's
+  round-trip/pooling profile. Stand up a local one with
+  `docker run -e POSTGRES_PASSWORD=… -p 5432:5432 postgres:16`.
+- **MySQL** — `mysql+mysqldb://user@host:3306/db`. Requires the `mysqlclient`
+  driver (`pip install mysqlclient`, which needs the `libmysqlclient-dev`
+  system library) — it is not in any extra. A supported backend, though prod
+  runs on Postgres. Stand up a local one with
+  `docker run -e MYSQL_ROOT_PASSWORD=… -e MYSQL_DATABASE=benchdb -p 3306:3306 mysql:8.0`.
+
+## Output → Databricks → dashboard
+
+The harness writes JSON only. Storage and charting live in Databricks:
+
+```
+run.py --output bench.json   →   GitHub Actions artifact   →   Databricks notebook (ETL)   →   Delta table   →   AI/BI dashboard
+        (this repo)                    (CI, follow-up)              (workspace, yours)
+```
+
+The repo's contract is the **JSON schema** below. A workspace notebook (owned
+outside this repo, modeled on MLflow's gateway ETL) pulls the CI artifacts via
+the GitHub API, flattens each run's `summary` + `runs` + metadata, and
+`saveAsTable`s into a Delta table the dashboard reads. `sample_output.json` is a
+committed, faithful example so the notebook can be written against a real
+document without running the harness.
+
+### JSON schema (`schema.py`, `SCHEMA_VERSION`)
+
+```jsonc
+{
+  "schema_version": 2,
+  "generated_at": "<ISO-8601 UTC>",
+  "git_sha": "<HEAD sha>",
+  "git_branch": "<branch>",
+  "host": {"platform": "...", "python": "...", "cpu_count": 12},
+  "harness": "http-only",
+  "config": {"iterations": 100, "requests": 500, "concurrency": 1,
+             "runs": 3, "warmup": 10, "with_runner": false,
+             "backend": "sqlite"},
+  "journeys": {
+    "<journey name>": {
+      "kind": "latency" | "throughput",
+      "backend": "sqlite" | "postgres" | "mysql",
+      "needs_runner": false,          // hardcoded per journey: HTTP=false, full-turn=true
+      "runs": [                       // one per --runs
+        {"n_success": N, "n_failures": N, "failures": {"HTTP 500": 1},
+         "wall_time_s": …, "mean_ms": …, "p50_ms": …, "p95_ms": …,
+         "p99_ms": …, "max_ms": …, "rps": …}
+      ],
+      "summary": {"avg_mean_ms": …, "avg_p50_ms": …, "avg_p95_ms": …,
+                  "avg_p99_ms": …, "avg_rps": …}    // averaged across runs
+    }
+  }
+}
+```
+
+The per-journey `summary` + `runs` shape mirrors MLflow's gateway benchmark, so
+the same ETL flatten works — keyed by `journey` and `backend`. Bump
+`SCHEMA_VERSION` on any breaking shape change so the notebook can branch on it.
+
+## Layout
+
+| File | Role |
+| --- | --- |
+| `run.py` | CLI orchestrator + entrypoint |
+| `seed.py` | deterministic corpus seeder (store API) |
+| `journeys.py` | `Journey` dataclass, latency/throughput runners, registry |
+| `environment.py` | server (± runner + mock LLM) lifecycle; `--database-uri` |
+| `measure.py` | `RunResult`, percentile, aggregation, thresholds, tables |
+| `schema.py` | `SCHEMA_VERSION`, `build_report`, git/host metadata |
+| `sample_output.json` | committed example of the JSON contract |
+
+The smoke test is `tests/benchmarks/test_benchmark_smoke.py` (boots the server
+with tiny counts + a seeded-corpus unit test; runs on the normal CI lane, no
+creds).
+
+## CI
+
+`.github/workflows/benchmark.yml` runs nightly (and on dispatch) as a backend
+matrix — `sqlite`, `postgres` (a `postgres:16` service container), and `mysql`
+(a `mysql:8.0` service container; the `mysqlclient` driver is installed on that
+leg only). Each leg seeds a corpus (SQLite reuses a cache keyed on the schema
+head + `seed.py` + corpus config, so a migration busts the cache and forces a
+reseed; Postgres and MySQL are fresh per run), runs the benchmark, and uploads
+`benchmark-results-<backend>-<run_id>.json`. The workspace notebook pulls those
+artifacts.
+
+Schema changes need no manual step: the seed always targets the current
+migrated schema (migrations run when the store is constructed), the reuse
+marker records the head read at seed time (so old corpora auto-reseed), and
+`test_seed_creates_listable_corpus` fails if a migration genuinely breaks
+seeding.
+
+## Follow-ups
+
+- **Subagent spawn.** A planned full-turn journey (`needs_runner=True`): the
+  parent agent emits a `sys_session_send` tool call, the runner dispatches a
+  child session, and the parent auto-wakes with the collected result. It's
+  fully mockable with the zero-latency mock LLM (no real model) — script the
+  parent's queue to emit the tool call and the child's queue to return a short
+  reply, then poll for the child's marker. It needs the parent bundle to declare
+  a sub-agent under `tools:` (extend `_agent_bundle`); the pattern is in
+  `tests/e2e/test_coder_subagent.py`.
+- **Excluded journeys** (agent-behaviour-dependent, deliberately not measured):
+  multi-turn and tool-calling turns (dominated by the agent's own choices) and
+  large-history turns (the O(N) `history_to_input_items` conversion is real app
+  work but only fires on a cold runner cache, so isolating it entangles with
+  cold-start cost).
+- **CI matrix.** Runner journeys are backend-agnostic (they exercise runner
+  dispatch, not big DB reads), so the nightly workflow can run them on the
+  SQLite leg only rather than both — wire a runner `--journeys` set into
+  `benchmark.yml` when desired.
+- **Simulated provider latency.** The mock LLM returns at ~zero latency, which
+  is what isolates omnigent overhead. A fixed per-response delay knob would let
+  turns model end-user wall-clock instead; it's a small change behind the
+  `configure_mock` / `set_mock_fallback` seam if that's ever wanted.

dev/benchmarks/omnigent/__init__.py

@@ -0,0 +1,7 @@
+"""Omnigent user-journey performance benchmark.
+
+Stands up a real server + runner against a zero-latency mock LLM, drives
+key user journeys under load, and emits a versioned JSON report of latency
+percentiles and throughput. See ``README.md`` for the workflow and how the
+workspace ETL notebook consumes the JSON.
+"""

dev/benchmarks/omnigent/compare.py

@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+"""Compare two benchmark JSON reports for performance regressions.
+
+Usage:
+    uv run --no-sync dev/benchmarks/omnigent/compare.py \\
+        --baseline nightly.json --candidate pr.json [--threshold 0.20] \\
+        [--output-markdown report.md] [--backend sqlite]
+
+Exits 0 if no regression, 1 if regression detected.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def _fmt_ms(v: float | None) -> str:
+    return f"{v:.1f}" if v is not None else "—"
+
+
+def _fmt_delta(v: float | None) -> str:
+    if v is None:
+        return "—"
+    sign = "+" if v >= 0 else ""
+    return f"{sign}{v * 100:.1f}%"
+
+
+def compare_reports(
+    baseline: dict,
+    candidate: dict,
+    threshold: float,
+    backend: str | None = None,
+) -> tuple[bool, list[dict]]:
+    """Compare journeys between two reports.
+
+    :param baseline: Parsed baseline JSON report.
+    :param candidate: Parsed candidate JSON report.
+    :param threshold: Regression threshold as a fraction (e.g. 0.20 = 20%).
+    :param backend: If set, only compare journeys whose ``backend`` key matches.
+    :returns: ``(passed, rows)`` where *rows* hold per-journey comparison data.
+    """
+    baseline_journeys = baseline.get("journeys", {})
+    candidate_journeys = candidate.get("journeys", {})
+    rows: list[dict] = []
+    passed = True
+
+    for name, c_data in candidate_journeys.items():
+        if backend is not None and c_data.get("backend") != backend:
+            continue
+
+        c_summary = c_data.get("summary", {})
+        c_p50 = c_summary.get("avg_p50_ms")
+        c_p95 = c_summary.get("avg_p95_ms")
+
+        if name not in baseline_journeys:
+            rows.append(
+                {
+                    "journey": name,
+                    "status": "new",
+                    "b_p50": None,
+                    "c_p50": c_p50,
+                    "b_p95": None,
+                    "c_p95": c_p95,
+                    "delta_p50": None,
+                    "delta_p95": None,
+                }
+            )
+            continue
+
+        b_data = baseline_journeys[name]
+        if backend is not None and b_data.get("backend") != backend:
+            # Baseline journey exists but for a different backend — treat as new.
+            rows.append(
+                {
+                    "journey": name,
+                    "status": "new",
+                    "b_p50": None,
+                    "c_p50": c_p50,
+                    "b_p95": None,
+                    "c_p95": c_p95,
+                    "delta_p50": None,
+                    "delta_p95": None,
+                }
+            )
+            continue
+
+        b_summary = b_data.get("summary", {})
+        b_p50 = b_summary.get("avg_p50_ms", 0.0)
+        b_p95 = b_summary.get("avg_p95_ms", 0.0)
+
+        c_p50 = c_p50 or 0.0
+        c_p95 = c_p95 or 0.0
+        delta_p50 = (c_p50 - b_p50) / b_p50 if b_p50 > 0 else 0.0
+        delta_p95 = (c_p95 - b_p95) / b_p95 if b_p95 > 0 else 0.0
+
+        regression = delta_p50 > threshold or delta_p95 > threshold
+        if regression:
+            passed = False
+
+        rows.append(
+            {
+                "journey": name,
+                "status": "regression" if regression else "ok",
+                "b_p50": b_p50,
+                "c_p50": c_p50,
+                "delta_p50": delta_p50,
+                "b_p95": b_p95,
+                "c_p95": c_p95,
+                "delta_p95": delta_p95,
+            }
+        )
+
+    return passed, rows
+
+
+def _status_style(status: str) -> str:
+    return {"regression": "red", "new": "cyan", "ok": "green"}.get(status, "")
+
+
+def print_table(rows: list[dict], threshold: float) -> None:
+    """Render the comparison rows as a rich table."""
+    table = Table(
+        title=f"Benchmark comparison (regression threshold: {threshold * 100:.0f}%)",
+        show_header=True,
+        header_style="bold cyan",
+        box=None,
+        padding=(0, 2),
+        title_justify="left",
+    )
+    table.add_column("Journey", no_wrap=True)
+    table.add_column("Status", justify="center")
+    table.add_column("Base P50 ms", justify="right")
+    table.add_column("Cand P50 ms", justify="right")
+    table.add_column("Δ P50", justify="right")
+    table.add_column("Base P95 ms", justify="right")
+    table.add_column("Cand P95 ms", justify="right")
+    table.add_column("Δ P95", justify="right")
+
+    for row in rows:
+        style = _status_style(row["status"])
+        delta_p50_str = _fmt_delta(row["delta_p50"])
+        delta_p95_str = _fmt_delta(row["delta_p95"])
+
+        if row["status"] == "regression":
+            if row["delta_p50"] is not None and row["delta_p50"] > threshold:
+                delta_p50_str = f"[red]{delta_p50_str}[/red]"
+            if row["delta_p95"] is not None and row["delta_p95"] > threshold:
+                delta_p95_str = f"[red]{delta_p95_str}[/red]"
+
+        table.add_row(
+            row["journey"],
+            f"[{style}]{row['status']}[/{style}]" if style else row["status"],
+            _fmt_ms(row["b_p50"]),
+            _fmt_ms(row["c_p50"]),
+            delta_p50_str,
+            _fmt_ms(row["b_p95"]),
+            _fmt_ms(row["c_p95"]),
+            delta_p95_str,
+        )
+
+    console.print()
+    console.print(table)
+    console.print()
+
+
+def build_markdown(rows: list[dict], threshold: float, passed: bool) -> str:
+    """Render the comparison rows as a GitHub-flavoured markdown table."""
+    lines = [
+        "## Benchmark comparison",
+        "",
+        f"Regression threshold: **{threshold * 100:.0f}%** on avg P50 or avg P95.",
+        "",
+        "| Journey | Status | Base P50 ms | Cand P50 ms | Δ P50"
+        " | Base P95 ms | Cand P95 ms | Δ P95 |",
+        "| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: |",
+    ]
+
+    for row in rows:
+        status = row["status"]
+        emoji = {"regression": "🔴", "new": "🆕", "ok": "✅"}.get(status, status)
+        b_p50 = _fmt_ms(row["b_p50"])
+        c_p50 = _fmt_ms(row["c_p50"])
+        d_p50 = _fmt_delta(row["delta_p50"])
+        b_p95 = _fmt_ms(row["b_p95"])
+        c_p95 = _fmt_ms(row["c_p95"])
+        d_p95 = _fmt_delta(row["delta_p95"])
+        lines.append(
+            f"| {row['journey']} | {emoji} {status} "
+            f"| {b_p50} | {c_p50} | {d_p50} "
+            f"| {b_p95} | {c_p95} | {d_p95} |"
+        )
+
+    lines.append("")
+    verdict = (
+        "**PASS** — no regressions detected." if passed else "**FAIL** — regression(s) detected."
+    )
+    lines.append(verdict)
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Compare benchmark JSON reports for performance regressions."
+    )
+    parser.add_argument("--baseline", required=True, type=Path, help="Baseline JSON report")
+    parser.add_argument("--candidate", required=True, type=Path, help="Candidate JSON report")
+    parser.add_argument(
+        "--threshold",
+        type=float,
+        default=1.0,
+        help="Regression threshold as a fraction (default 1.0 = 100%%, checks P50 and P95)",
+    )
+    parser.add_argument(
+        "--output-markdown",
+        type=Path,
+        metavar="FILE",
+        help="Write markdown comparison table to FILE",
+    )
+    parser.add_argument(
+        "--backend",
+        help="Filter to journeys for this backend only (e.g. sqlite, postgres)",
+    )
+    args = parser.parse_args(argv)
+
+    baseline = json.loads(args.baseline.read_text())
+    candidate = json.loads(args.candidate.read_text())
+
+    console.print(
+        f"[bold]Baseline:[/bold]  {args.baseline} (git: {baseline.get('git_sha', 'unknown')[:12]})"
+    )
+    sha = candidate.get("git_sha", "unknown")[:12]
+    console.print(f"[bold]Candidate:[/bold] {args.candidate} (git: {sha})")
+    if args.backend:
+        console.print(f"[bold]Backend filter:[/bold] {args.backend}")
+
+    passed, rows = compare_reports(baseline, candidate, args.threshold, backend=args.backend)
+
+    if not rows:
+        console.print("[yellow]No journeys found to compare.[/yellow]")
+        return 0
+
+    print_table(rows, args.threshold)
+
+    regressions = [r for r in rows if r["status"] == "regression"]
+    new_journeys = [r for r in rows if r["status"] == "new"]
+
+    if new_journeys:
+        names = ", ".join(r["journey"] for r in new_journeys)
+        console.print(f"[cyan]New journeys (no baseline):[/cyan] {names}")
+
+    if regressions:
+        console.print(
+            f"[red bold]REGRESSION DETECTED[/red bold] in "
+            f"{len(regressions)} journey(s): "
+            f"{', '.join(r['journey'] for r in regressions)}"
+        )
+    else:
+        console.print("[green bold]PASS[/green bold] — no regressions detected.")
+
+    if args.output_markdown:
+        md = build_markdown(rows, args.threshold, passed)
+        args.output_markdown.write_text(md)
+        console.print(f"Markdown report written to {args.output_markdown}")
+
+    return 0 if passed else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dev/benchmarks/omnigent/environment.py

@@ -0,0 +1,937 @@
+"""Benchmark environment lifecycle.
+
+:class:`BenchEnvironment` is an async context manager that stands up a real
+Omnigent ``server`` with no Databricks credentials. Two modes:
+
+- ``with_runner=False`` (default): server + SQLite DB only. Enough for the
+  HTTP/API journeys, which never drive an agent turn.
+- ``with_runner=True``: additionally spawns a zero-latency mock LLM and a
+  sibling ``runner``, routes the server-side prompt-policy classifier at the
+  mock (via ``--config``), and sets an ALLOW fallback — everything the
+  full-turn journeys need.
+
+A full env is a strict superset of the HTTP-only env, so both modes share one
+class; the runner mode is gated behind the flag rather than forked into a
+separate type. It mirrors the proven ``live_server`` e2e recipe
+(``tests/e2e/conftest.py``) and reuses the credential-free spawn core: the
+compat helpers (so subprocesses import this worktree) and
+``token_bound_runner_id``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import io
+import os
+import signal
+import socket
+import subprocess
+import sys
+import tarfile
+import time
+import uuid
+from pathlib import Path
+from typing import IO
+
+import httpx
+import yaml
+
+from omnigent.host.identity import HOST_ID_ENV_VAR, HOST_NAME_ENV_VAR
+from omnigent.runner.identity import OMNIGENT_INTERNAL_WS_ORIGIN, token_bound_runner_id
+from tests._helpers.compat import (
+    apply_runner_env,
+    apply_server_env,
+    compat_runner_cwd,
+    compat_server_cwd,
+    runner_executable,
+    server_executable,
+)
+
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+_MOCK_SERVER = _REPO_ROOT / "tests" / "server" / "integration" / "mock_llm_server.py"
+
+_HEALTH_TIMEOUT_S = 90.0
+_MOCK_TIMEOUT_S = 15.0
+_POLL_INTERVAL_S = 0.2
+_TURN_TIMEOUT_S = 180.0
+# Budget for the host daemon (session_cold_start journey, with_host) to connect
+# its tunnel and register in the hosts table after being spawned. Covers
+# interpreter start + imports + the reverse-tunnel handshake.
+_HOST_ONLINE_TIMEOUT_S = 60.0
+
+# Terminal SSE events — if one arrives before any delta, the turn produced no
+# streamed text (a failure for the TTFT journey).
+_STREAM_TERMINAL_EVENTS = frozenset(
+    {"response.completed", "response.failed", "response.cancelled"}
+)
+# The server persists an interrupted turn as a synthetic user message whose
+# text contains this marker (see tests/e2e/test_cancel_history.py).
+_CANCELLATION_MARKER = "interrupted"
+
+# Default full-turn agent (with_runner=True). The mock ignores the model for
+# routing (its "default" queue serves any request), but the key is baked into
+# the spec so the harness has a concrete model to send.
+_DEFAULT_MODEL = "mock-bench-brain"
+_DEFAULT_HARNESS = "openai-agents"
+
+# Server-side prompt-policy classifier queue key. In runner mode we set an
+# ALLOW fallback here so a classifier call (if the agent trips one) never
+# blocks or returns non-verdict text.
+_POLICY_LLM_KEY = "_policy_llm_"
+_POLICY_ALLOW = '{"action": "allow", "reason": ""}'
+
+
+def _find_free_port() -> int:
+    """Bind an ephemeral port and return it (races are tolerated by retries)."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return int(sock.getsockname()[1])
+
+
+def _omni_executable() -> str:
+    """The ``omni`` console script beside the (compat-aware) interpreter.
+
+    ``server_executable()`` returns the interpreter the server/runner subprocess
+    should run under — ``sys.executable`` normally, or a pinned older build's
+    python in cross-version compat mode. The ``omni`` console script is
+    installed next to that interpreter (``[project.scripts]`` in pyproject), so
+    deriving it from the same directory launches the real user-facing command
+    (``omni server`` / ``omni host``) while still honoring the compat pin.
+    """
+    return str(Path(server_executable()).with_name("omni"))
+
+
+class BenchEnvironment:
+    """Async context manager owning the benchmark's server (± runner + mock).
+
+    :param with_runner: When ``False`` (default), boot the server only — the
+        v1 HTTP-journey path. When ``True``, also spawn the mock LLM and a
+        runner and wire the policy classifier at the mock — the phase-2
+        full-turn path.
+    :param with_host: When ``True`` (implies ``with_runner``), additionally
+        spawn a real ``omnigent host`` daemon. Additive over ``with_runner``:
+        the boot runner still serves the warm journeys, while the daemon lets
+        the ``session_cold_start`` journey create host-bound sessions that fire
+        ``host.launch_runner`` and launch their OWN fresh runner — so the first
+        message races the runner's boot, reproducing the true UI cold path.
+    :param database_uri: SQLAlchemy URI the server boots against. ``None``
+        (default) uses a fresh throwaway SQLite file in the temp dir — the
+        empty-DB path. Pass a pre-seeded URI (e.g. a seeded SQLite file, or a
+        ``postgresql+psycopg://…`` instance) to benchmark against a realistic
+        corpus. Postgres must be the fully-qualified ``+psycopg`` form — the
+        server CLI does not normalize it.
+    :param harness: Harness for full-turn agents when ``with_runner`` (default
+        ``openai-agents``, a base dependency needing no vendor CLI binary).
+    :param model: Model string baked into registered agent specs.
+    """
+
+    def __init__(
+        self,
+        *,
+        with_runner: bool = False,
+        with_host: bool = False,
+        database_uri: str | None = None,
+        harness: str = _DEFAULT_HARNESS,
+        model: str = _DEFAULT_MODEL,
+    ) -> None:
+        # with_host is additive over with_runner: the boot runner still serves
+        # the warm journeys, and the host daemon additionally lets the cold-start
+        # journey create host-bound sessions that launch their own runners.
+        self.with_host = with_host
+        self.with_runner = with_runner or with_host
+        self.database_uri = database_uri
+        self.harness = harness
+        self.model = model
+        self.base_url = ""
+        self.mock_url = ""
+        self.runner_id = ""
+        self.host_id = ""
+        self.host_workspace = ""
+        self.client: httpx.AsyncClient | None = None
+
+        self._tmp = Path("/tmp") / f"omni-bench-{uuid.uuid4().hex[:8]}"
+        self._mock_proc: subprocess.Popen[bytes] | None = None
+        self._server_proc: subprocess.Popen[bytes] | None = None
+        self._runner_proc: subprocess.Popen[bytes] | None = None
+        self._host_proc: subprocess.Popen[bytes] | None = None
+        # Base env retained so the host daemon is built identically to the boot
+        # runner's server-facing env (worktree source, mock LLM routing).
+        self._runner_base_env: dict[str, str] = {}
+        self._log_handles: list[IO[bytes]] = []
+        self._agent_cache: dict[str, str] = {}
+
+    # ── lifecycle ────────────────────────────────────────────
+
+    async def __aenter__(self) -> BenchEnvironment:
+        await asyncio.to_thread(self._start)
+        self.client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=300.0,
+            headers={"Origin": OMNIGENT_INTERNAL_WS_ORIGIN},
+        )
+        if self.with_runner:
+            # ALLOW fallback so a server-side classifier call resolves against
+            # the mock (never api.openai.com) and returns a valid verdict.
+            await self._mock_post(
+                "/mock/set_fallback", {"key": _POLICY_LLM_KEY, "text": _POLICY_ALLOW}
+            )
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        if self.client is not None:
+            await self.client.aclose()
+        await asyncio.to_thread(self._stop)
+
+    def _start(self) -> None:
+        """Spawn the server (± mock + runner) and block until ready."""
+        self._tmp.mkdir(mode=0o700, parents=True, exist_ok=True)
+        artifact_dir = self._tmp / "artifacts"
+        artifact_dir.mkdir(exist_ok=True)
+
+        if self.with_runner:
+            mock_port = _find_free_port()
+            self.mock_url = f"http://127.0.0.1:{mock_port}"
+            self._mock_proc = self._spawn_mock(mock_port)
+            self._wait_mock_ready()
+
+        port = _find_free_port()
+        self.base_url = f"http://localhost:{port}"
+        binding_token = uuid.uuid4().hex
+
+        base_env = {**os.environ}
+        if self.with_runner:
+            self.runner_id = token_bound_runner_id(binding_token)
+            base_env["OPENAI_API_KEY"] = "mock-key"
+            # The OpenAI SDK appends /responses, so include /v1 in the base.
+            base_env["OPENAI_BASE_URL"] = f"{self.mock_url}/v1"
+        # Prepend the worktree so subprocesses import this branch's source.
+        apply_server_env(base_env, _REPO_ROOT)
+        # Retained so the host daemon (with_host) is built with the same
+        # server-facing env as the boot runner.
+        self._runner_base_env = base_env
+
+        self._server_proc = self._spawn_server(port, base_env, binding_token, artifact_dir)
+        if self.with_runner:
+            self._runner_proc = self._spawn_runner(base_env, binding_token)
+        self._wait_ready()
+        # The host daemon is ADDITIVE — the boot runner above still serves the
+        # warm journeys; the daemon exists so the cold-start journey can create
+        # host-bound sessions that launch their OWN fresh runners on demand
+        # (the race the cold path measures). The two never share a runner id.
+        if self.with_host:
+            self._host_proc = self._spawn_host(base_env)
+            self._wait_host_online()
+
+    def _stop(self) -> None:
+        """Terminate host, runner, server, and mock; remove the temp dir."""
+        # Host first: SIGTERM-ing the daemon reaps the runners IT spawned (they
+        # are daemon-owned children), so it must go before the server so those
+        # runners' tunnels close cleanly.
+        for proc in (
+            self._host_proc,
+            self._runner_proc,
+            self._server_proc,
+            self._mock_proc,
+        ):
+            if proc is not None and proc.poll() is None:
+                proc.send_signal(signal.SIGTERM)
+                try:
+                    proc.wait(timeout=8)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+                    proc.wait(timeout=5)
+        for handle in self._log_handles:
+            handle.close()
+        import shutil
+
+        shutil.rmtree(self._tmp, ignore_errors=True)
+
+    # ── spawns ───────────────────────────────────────────────
+
+    def _log(self, name: str) -> IO[bytes]:
+        handle = (self._tmp / name).open("wb")
+        self._log_handles.append(handle)
+        return handle
+
+    def _spawn_mock(self, port: int) -> subprocess.Popen[bytes]:
+        return subprocess.Popen(
+            [sys.executable, str(_MOCK_SERVER), str(port)],
+            env={**os.environ, "PYTHONPATH": str(_REPO_ROOT)},
+            stdout=self._log("mock.log"),
+            stderr=subprocess.STDOUT,
+        )
+
+    def _spawn_server(
+        self,
+        port: int,
+        base_env: dict[str, str],
+        binding_token: str,
+        artifact_dir: Path,
+    ) -> subprocess.Popen[bytes]:
+        # Pre-seeded URI when given (realistic corpus), else a throwaway SQLite
+        # file in the temp dir (the empty-DB path). SQLite absolute paths need
+        # four slashes; the temp path is absolute.
+        db_uri = self.database_uri or f"sqlite:///{self._tmp / 'bench.db'}"
+        args = [
+            _omni_executable(),
+            "server",
+            "--port",
+            str(port),
+            "--database-uri",
+            db_uri,
+            "--artifact-location",
+            str(artifact_dir),
+        ]
+        env = {**base_env}
+        if self.with_runner:
+            # Route the server-side policy-classifier LLM at the mock, mirroring
+            # live_server. Without this the classifier's client defaults to
+            # api.openai.com and errors. Server-only mode needs no llm config —
+            # the classifier only builds under OMNIGENT_SMART_ROUTING=1.
+            server_cfg = self._tmp / "server.yaml"
+            server_cfg.write_text(
+                yaml.safe_dump(
+                    {
+                        "llm": {
+                            "model": _POLICY_LLM_KEY,
+                            "connection": {
+                                "base_url": f"{self.mock_url}/v1",
+                                "api_key": "mock-key",
+                            },
+                        }
+                    }
+                )
+            )
+            args.extend(["--config", str(server_cfg)])
+            env["OMNIGENT_RUNNER_TUNNEL_TOKEN"] = binding_token
+        return subprocess.Popen(
+            args,
+            env=env,
+            cwd=compat_server_cwd(),
+            stdout=self._log("server.log"),
+            stderr=subprocess.STDOUT,
+        )
+
+    def _spawn_runner(
+        self, base_env: dict[str, str], binding_token: str
+    ) -> subprocess.Popen[bytes]:
+        # Point the runner's filesystem workspace at the temp dir so file
+        # writes (e.g. read_runner_file's setup) land there and are cleaned up
+        # on teardown, rather than in the launch cwd (its default).
+        workspace = self._tmp / "workspace"
+        workspace.mkdir(exist_ok=True)
+        return self._spawn_runner_process(
+            base_env,
+            binding_token,
+            runner_id=self.runner_id,
+            workspace=workspace,
+            log_name="runner.log",
+        )
+
+    def _spawn_runner_process(
+        self,
+        base_env: dict[str, str],
+        binding_token: str,
+        *,
+        runner_id: str,
+        workspace: Path,
+        log_name: str,
+    ) -> subprocess.Popen[bytes]:
+        """Spawn one runner subprocess under *runner_id* + *binding_token*.
+
+        Factored out of :meth:`_spawn_runner` so the ``session_cold_start``
+        journey can spawn additional runners on demand, each under its own id,
+        binding token, and workspace. The caller must pair *runner_id* with the token
+        it derives from (``token_bound_runner_id(binding_token)``): the runner
+        derives its managed-mint URL from the token internally, so a mismatch
+        would register the tunnel under one id but mint under another (→ 401).
+        """
+        runner_env = apply_runner_env(
+            {
+                **base_env,
+                "OMNIGENT_RUNNER_ID": runner_id,
+                "OMNIGENT_RUNNER_TUNNEL_BINDING_TOKEN": binding_token,
+                "OMNIGENT_RUNNER_PARENT_PID": str(os.getpid()),
+                "RUNNER_SERVER_URL": self.base_url,
+                "OMNIGENT_RUNNER_WORKSPACE": str(workspace),
+            }
+        )
+        return subprocess.Popen(
+            [runner_executable(), "-m", "omnigent.runner._entry"],
+            env=runner_env,
+            cwd=compat_runner_cwd(),
+            stdout=self._log(log_name),
+            stderr=subprocess.STDOUT,
+        )
+
+    def _spawn_host(self, base_env: dict[str, str]) -> subprocess.Popen[bytes]:
+        """Spawn a real ``omni host`` daemon against the bench server.
+
+        Runs the user-facing ``omni host --server`` command — the same daemon a
+        developer starts by hand. Identity comes from :data:`HOST_ID_ENV_VAR` /
+        :data:`HOST_NAME_ENV_VAR`: with both set, ``load_or_create_host_identity``
+        returns that identity WITHOUT reading or writing any ``config.yaml``, so
+        the daemon never touches the developer's real ``~/.omnigent`` (nor
+        collides with a sibling bench leg). ``--non-interactive`` keeps it from
+        ever launching a browser login (moot for the loopback server, which is
+        not Databricks-fronted, but explicit for CI). The daemon self-registers
+        over loopback (single-user ``RESERVED_USER_LOCAL`` owner, no token) and
+        launches runners on demand when the server sends ``host.launch_runner``.
+        """
+        # Bare 32-char hex uuid — host_id is a Uuid16 (binary) column, so it
+        # must be a valid uuid (a synthetic "host_bench_…" string no longer fits).
+        self.host_id = uuid.uuid4().hex
+        workspace = self._tmp / "host-workspace"
+        workspace.mkdir(exist_ok=True)
+        self.host_workspace = str(workspace)
+        host_env = {
+            **base_env,
+            HOST_ID_ENV_VAR: self.host_id,
+            HOST_NAME_ENV_VAR: f"bench-host-{self.host_id[-8:]}",
+        }
+        return subprocess.Popen(
+            [_omni_executable(), "host", "--server", self.base_url, "--non-interactive"],
+            env=host_env,
+            cwd=str(workspace),
+            stdout=self._log("host-daemon.log"),
+            stderr=subprocess.STDOUT,
+        )
+
+    # ── readiness ────────────────────────────────────────────
+
+    def _wait_mock_ready(self) -> None:
+        deadline = time.monotonic() + _MOCK_TIMEOUT_S
+        while time.monotonic() < deadline:
+            try:
+                if httpx.get(f"{self.mock_url}/stats", timeout=1).status_code == 200:
+                    return
+            except httpx.HTTPError:
+                pass
+            time.sleep(0.1)
+        raise RuntimeError(f"mock LLM not ready within {_MOCK_TIMEOUT_S}s; logs in {self._tmp}")
+
+    def _wait_ready(self) -> None:
+        """Wait for ``/health`` (and, in runner mode, the runner online)."""
+        deadline = time.monotonic() + _HEALTH_TIMEOUT_S
+        while time.monotonic() < deadline:
+            try:
+                health = httpx.get(f"{self.base_url}/health", timeout=2)
+                if health.status_code == 200 and self._runner_ready():
+                    return
+            except httpx.HTTPError:
+                pass
+            time.sleep(_POLL_INTERVAL_S)
+        raise RuntimeError(f"server not ready within {_HEALTH_TIMEOUT_S}s; logs in {self._tmp}")
+
+    def _runner_ready(self) -> bool:
+        """Whether the boot runner reports online (always ``True`` server-only)."""
+        if not self.with_runner:
+            return True
+        status = httpx.get(f"{self.base_url}/v1/runners/{self.runner_id}/status", timeout=2)
+        return status.status_code == 200 and status.json().get("online") is True
+
+    def _wait_host_online(self) -> None:
+        """Block until the host daemon's row reads ``status=online``.
+
+        Polls ``GET /v1/hosts`` (the single-user owner is ``local``) until the
+        daemon we spawned has connected its tunnel and been upserted online, so
+        a host-bound session-create has a live launch target.
+        """
+        deadline = time.monotonic() + _HOST_ONLINE_TIMEOUT_S
+        while time.monotonic() < deadline:
+            if self._host_proc is not None and self._host_proc.poll() is not None:
+                raise RuntimeError(
+                    f"host daemon exited (code {self._host_proc.returncode}) before "
+                    f"coming online; logs in {self._tmp}"
+                )
+            try:
+                resp = httpx.get(f"{self.base_url}/v1/hosts", timeout=2)
+                if resp.status_code == 200:
+                    for host in resp.json().get("hosts", []):
+                        if host.get("host_id") == self.host_id and host.get("status") == "online":
+                            return
+            except httpx.HTTPError:
+                # Server not yet accepting requests, or a transient read error:
+                # keep polling until the deadline rather than failing the boot.
+                pass
+            time.sleep(_POLL_INTERVAL_S)
+        raise RuntimeError(f"host {self.host_id} not online within {_HOST_ONLINE_TIMEOUT_S}s")
+
+    # ── mock control (runner mode only) ──────────────────────
+
+    async def _mock_post(self, path: str, body: dict[str, object]) -> None:
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            resp = await client.post(f"{self.mock_url}{path}", json=body)
+            resp.raise_for_status()
+
+    async def configure_mock(
+        self,
+        responses: list[dict[str, object]],
+        *,
+        key: str = "default",
+        match: str | None = None,
+    ) -> None:
+        """Load a keyed response queue on the mock (see e2e ``configure_mock_llm``)."""
+        payload: dict[str, object] = {"key": key, "responses": responses}
+        if match is not None:
+            payload["match"] = match
+        await self._mock_post("/mock/configure", payload)
+
+    async def set_mock_fallback(
+        self, text: str, *, key: str = "default", stream: bool = False
+    ) -> None:
+        """Set a reset-surviving fallback response for a mock queue *key*.
+
+        :param stream: When ``True`` the fallback emits per-word
+            ``output_text.delta`` events before completing — needed for the
+            time-to-first-token journey to observe streamed deltas.
+        """
+        await self._mock_post("/mock/set_fallback", {"key": key, "text": text, "stream": stream})
+
+    # ── agent + session primitives ───────────────────────────
+
+    def _agent_bundle(self, name: str) -> bytes:
+        """Build a ``spec_version: 1`` agent bundle.
+
+        In runner mode the executor is wired at the mock LLM (auth +
+        connection). Server-only, no LLM is ever called, so the bundle just
+        needs to be a valid spec the server can register and bind sessions to.
+        """
+        executor: dict[str, object] = {
+            "type": "omnigent",
+            "model": self.model,
+            "config": {"harness": self.harness},
+        }
+        config: dict[str, object] = {
+            "spec_version": 1,
+            "name": name,
+            "prompt": "You are a helpful assistant used for performance benchmarking.",
+            "executor": executor,
+        }
+        if self.with_runner:
+            executor["auth"] = {
+                "type": "api_key",
+                "api_key": "mock-key",
+                "base_url": f"{self.mock_url}/v1",
+            }
+            executor["connection"] = {"base_url": f"{self.mock_url}/v1", "api_key": "mock-key"}
+            # A filesystem env so the runner can serve the resource endpoints
+            # (read_runner_file). Without os_env the runner has no primary
+            # environment to materialize and the filesystem proxy 404s.
+            # sandbox.type=none avoids needing a bwrap binary on the host.
+            config["os_env"] = {
+                "type": "caller_process",
+                "cwd": ".",
+                "sandbox": {"type": "none"},
+            }
+        buf = io.BytesIO()
+        with tarfile.open(fileobj=buf, mode="w:gz") as tar:
+            payload = yaml.safe_dump(config).encode()
+            info = tarfile.TarInfo("config.yaml")
+            info.size = len(payload)
+            tar.addfile(info, io.BytesIO(payload))
+        return buf.getvalue()
+
+    async def ensure_agent(self, name: str = "bench-agent") -> str:
+        """Register the benchmark agent once, returning its name (idempotent)."""
+        assert self.client is not None
+        if name in self._agent_cache:
+            return name
+        resp = await self.client.post(
+            "/v1/sessions",
+            data={"metadata": "{}"},
+            files={"bundle": ("agent.tar.gz", self._agent_bundle(name), "application/gzip")},
+        )
+        if resp.status_code not in (200, 201, 409):
+            raise RuntimeError(f"agent register failed: {resp.status_code} {resp.text[:400]}")
+        self._agent_cache[name] = name
+        return name
+
+    async def agent_id(self, agent_name: str) -> str:
+        """Resolve a registered agent's id by name."""
+        assert self.client is not None
+        listing = await self.client.get(
+            "/v1/sessions", params={"agent_name": agent_name, "limit": 1}
+        )
+        listing.raise_for_status()
+        return str(listing.json()["data"][0]["agent_id"])
+
+    async def create_session(self, agent_id: str) -> str:
+        """Create an (unbound) session for *agent_id*, returning its id."""
+        assert self.client is not None
+        created = await self.client.post("/v1/sessions", json={"agent_id": agent_id})
+        created.raise_for_status()
+        return str(created.json()["id"])
+
+    async def create_hosted_session(self, agent_id: str) -> str:
+        """Create a host-bound session that fires ``host.launch_runner``.
+
+        The inline-launch ``POST /v1/sessions`` shape the Web UI's New Chat
+        wizard sends: passing ``host_id`` + ``workspace`` makes the server bind a
+        runner id and dispatch a launch frame to the host daemon, then return
+        immediately (~tens of ms) WITHOUT waiting for the runner to connect.
+        Returned without any readiness poll on purpose — the caller's first
+        message then races the runner's boot, which is the cold path we measure.
+
+        :raises RuntimeError: If the env was not built with ``with_host=True``.
+        """
+        assert self.client is not None
+        if not self.with_host:
+            raise RuntimeError("create_hosted_session requires with_host=True")
+        created = await self.client.post(
+            "/v1/sessions",
+            json={
+                "agent_id": agent_id,
+                "host_id": self.host_id,
+                "host_type": "external",
+                "workspace": self.host_workspace,
+            },
+        )
+        created.raise_for_status()
+        return str(created.json()["id"])
+
+    async def seed_items(self, session_id: str, count: int) -> None:
+        """Append *count* history items over HTTP, with no runner or LLM.
+
+        Uses the ``external_conversation_item`` event, which the server
+        appends "without starting or steering a task" — the runner-free path
+        for giving ``load_conversation_history`` something to read back.
+
+        Items are user messages: assistant messages require an ``agent`` field
+        the server only has after a real turn, and the read path this seeds is
+        role-agnostic — item count and size, not role, drive its cost.
+        """
+        assert self.client is not None
+        for i in range(count):
+            body = {
+                "type": "external_conversation_item",
+                "data": {
+                    "item_type": "message",
+                    "item_data": {
+                        "role": "user",
+                        "content": [{"type": "input_text", "text": f"benchmark seed item {i}"}],
+                    },
+                },
+            }
+            resp = await self.client.post(f"/v1/sessions/{session_id}/events", json=body)
+            resp.raise_for_status()
+
+    # ── runner-mode session driving (phase 2) ────────────────
+
+    async def create_bound_session(self, agent_id: str) -> str:
+        """Create a session for *agent_id* and bind it to the boot runner."""
+        return await self.create_session_bound_to(agent_id, self.runner_id)
+
+    async def create_session_bound_to(self, agent_id: str, runner_id: str) -> str:
+        """Create a session for *agent_id* and bind it to *runner_id*.
+
+        Binds a session to an already-online runner by patching its
+        ``runner_id`` — used by the warm journeys via :meth:`create_bound_session`
+        to pin the boot runner.
+        """
+        assert self.client is not None
+        if not self.with_runner:
+            raise RuntimeError("create_session_bound_to requires with_runner=True")
+        session_id = await self.create_session(agent_id)
+        bound = await self.client.patch(
+            f"/v1/sessions/{session_id}", json={"runner_id": runner_id}
+        )
+        bound.raise_for_status()
+        return session_id
+
+    async def write_runner_file(self, session_id: str, relative_path: str, content: str) -> None:
+        """Write a file into the runner's default environment over HTTP.
+
+        The server proxies the ``PUT`` to the bound runner, which writes to its
+        sandboxed filesystem — so this needs a runner. Used to plant a file the
+        read journey can then fetch back.
+
+        :raises RuntimeError: If not in runner mode.
+        """
+        assert self.client is not None
+        if not self.with_runner:
+            raise RuntimeError("write_runner_file requires with_runner=True")
+        resp = await self.client.put(
+            f"/v1/sessions/{session_id}/resources/environments/default/filesystem/{relative_path}",
+            json={"content": content, "encoding": "utf-8"},
+        )
+        resp.raise_for_status()
+
+    async def read_runner_file(self, session_id: str, relative_path: str) -> None:
+        """Read a file from the runner's default environment over HTTP.
+
+        Times the server → runner filesystem proxy (a localhost round-trip); no
+        LLM is involved. Requires a runner — the server returns 502 without one.
+
+        :raises RuntimeError: If not in runner mode.
+        """
+        assert self.client is not None
+        if not self.with_runner:
+            raise RuntimeError("read_runner_file requires with_runner=True")
+        resp = await self.client.get(
+            f"/v1/sessions/{session_id}/resources/environments/default/filesystem/{relative_path}",
+        )
+        resp.raise_for_status()
+
+    async def drive_turn(
+        self, session_id: str, text: str, *, timeout: float = _TURN_TIMEOUT_S
+    ) -> None:
+        """Post a user message and poll the session to a terminal state.
+
+        :raises RuntimeError: If not in runner mode, the turn fails, or it does
+            not settle within *timeout* seconds.
+        """
+        assert self.client is not None
+        if not self.with_runner:
+            raise RuntimeError("drive_turn requires with_runner=True")
+        body = {
+            "type": "message",
+            "data": {"role": "user", "content": [{"type": "input_text", "text": text}]},
+        }
+        posted = await self.client.post(f"/v1/sessions/{session_id}/events", json=body)
+        posted.raise_for_status()
+
+        deadline = time.monotonic() + timeout
+        seen_running = False
+        while time.monotonic() < deadline:
+            snap = await self.client.get(f"/v1/sessions/{session_id}")
+            snap.raise_for_status()
+            status = snap.json().get("status")
+            if status in ("running", "waiting"):
+                seen_running = True
+            elif status == "failed":
+                raise RuntimeError(f"turn failed: {snap.json().get('last_task_error')}")
+            elif status == "idle" and seen_running:
+                return
+            await asyncio.sleep(_POLL_INTERVAL_S)
+        raise RuntimeError(f"turn did not settle within {timeout}s (session {session_id})")
+
+    async def _wait_idle(self, session_id: str, *, timeout: float = _TURN_TIMEOUT_S) -> None:
+        """Poll until the session is ``idle`` (a prior turn has settled)."""
+        assert self.client is not None
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            snap = await self.client.get(f"/v1/sessions/{session_id}")
+            snap.raise_for_status()
+            if snap.json().get("status") == "idle":
+                return
+            await asyncio.sleep(_POLL_INTERVAL_S)
+        raise RuntimeError(f"session did not reach idle within {timeout}s ({session_id})")
+
+    async def _post_and_await_first_delta(
+        self,
+        session_id: str,
+        text: str,
+        *,
+        wait_idle_first: bool,
+        timeout: float = _TURN_TIMEOUT_S,
+    ) -> None:
+        """Imitate the UI first-token path: attach SSE, then post, then await.
+
+        The exact sequence the web client follows for a one-shot turn:
+        subscribe to ``GET …/stream``, wait for the stream's ready heartbeat (the
+        first SSE line — the server yields it right after registering the
+        live-tail slot, so no event can be missed), POST the message, and return
+        on the first response from the model — either a
+        ``response.output_text.delta`` (streamed text) or a
+        ``response.output_item.done`` (a completed output item, e.g. a tool call
+        for harnesses that don't stream text deltas). This measures time to *any*
+        first response, not just text. A terminal event before either arrives
+        means the turn produced no response at all (a failure).
+
+        :param wait_idle_first: When ``True``, wait for the session to be ``idle``
+            before subscribing so a prior turn's terminal event can't race this
+            turn's response (warm-session TTFT). ``False`` for a fresh session whose
+            first turn is the only one — the cold path, where the timed span must
+            include runner launch + connect, so we must NOT poll it warm first.
+        :raises RuntimeError: If not in runner mode, or no response / a terminal
+            event arrives within *timeout*.
+        """
+        assert self.client is not None
+        if not self.with_runner:
+            raise RuntimeError("first-delta timing requires with_runner=True")
+
+        connected = asyncio.Event()
+        first_delta = asyncio.Event()
+        first_response = asyncio.Event()
+        outcome: dict[str, str] = {}
+
+        async def _read_stream() -> None:
+            try:
+                async with self.client.stream(  # type: ignore[union-attr]
+                    "GET", f"/v1/sessions/{session_id}/stream", timeout=timeout
+                ) as resp:
+                    # Any first line means the SSE connection is live (the server
+                    # emits a ready heartbeat on connect). Signalling here lets us
+                    # post the turn only once subscribed — without a blind sleep
+                    # that would otherwise inflate the measured time-to-first-delta.
+                    connected.set()
+                    async for line in resp.aiter_lines():
+                        if not line.startswith("event:"):
+                            continue
+                        etype = line[len("event:") :].strip()
+                        if etype == "response.output_text.delta":
+                            first_delta.set()
+                            return
+                        if etype == "response.output_item.done":
+                            first_response.set()
+                            return
+                        if etype in _STREAM_TERMINAL_EVENTS:
+                            outcome["terminal"] = etype
+                            first_delta.set()
+                            return
+            except httpx.HTTPError as exc:
+                outcome["error"] = repr(exc)
+                connected.set()
+                first_delta.set()
+
+        if wait_idle_first:
+            # Warm path: ensure any prior turn has settled so the fresh
+            # subscription's first terminal event can't be the previous turn
+            # completing (which would otherwise race ahead of this turn's delta).
+            await self._wait_idle(session_id, timeout=timeout)
+
+        reader = asyncio.create_task(_read_stream())
+        try:
+            # Wait until the stream is actually connected (not a fixed sleep) so
+            # the measured window is post → first response, not subscription setup.
+            await asyncio.wait_for(connected.wait(), timeout=timeout)
+            posted = await self.client.post(
+                f"/v1/sessions/{session_id}/events",
+                json={
+                    "type": "message",
+                    "data": {"role": "user", "content": [{"type": "input_text", "text": text}]},
+                },
+            )
+            posted.raise_for_status()
+            # Return on the first response, whichever comes first: a streamed text
+            # delta or a completed output item (e.g. a tool call for harnesses that
+            # don't stream text).
+            waiters = [
+                asyncio.create_task(first_delta.wait()),
+                asyncio.create_task(first_response.wait()),
+            ]
+            done, pending = await asyncio.wait(
+                waiters, timeout=timeout, return_when=asyncio.FIRST_COMPLETED
+            )
+            for task in pending:
+                task.cancel()
+            if not done:
+                raise RuntimeError(
+                    "no output_text.delta or output_item.done within "
+                    f"{timeout}s (session {session_id})"
+                )
+            if "error" in outcome:
+                raise RuntimeError(f"stream error: {outcome['error']}")
+            if "terminal" in outcome:
+                raise RuntimeError(
+                    f"turn reached {outcome['terminal']} before any response "
+                    f"(session {session_id})"
+                )
+        finally:
+            reader.cancel()
+
+    async def time_to_first_delta(
+        self, session_id: str, text: str, *, timeout: float = _TURN_TIMEOUT_S
+    ) -> None:
+        """Post a turn on a WARM session and return on the first output delta.
+
+        Times omnigent's streaming-pipeline overhead to first token against an
+        already-connected runner — with the zero-latency mock there is no model
+        latency in the number. See :meth:`_post_and_await_first_delta`.
+        """
+        await self._post_and_await_first_delta(
+            session_id, text, wait_idle_first=True, timeout=timeout
+        )
+
+    async def cold_start_first_delta(
+        self, agent_id: str, text: str, *, timeout: float = _TURN_TIMEOUT_S
+    ) -> None:
+        """Time the full UI cold path: create → attach SSE → send → first token.
+
+        Reproduces exactly what the Web UI does for a brand-new host-bound
+        session: create the session (which fires ``host.launch_runner`` and
+        returns before the runner connects), then run the standard first-token
+        sequence (attach the SSE stream, wait for its ready heartbeat, POST the
+        first message, await the first ``response.output_text.delta``). Because
+        the runner is still booting when the message posts, the server's
+        connect-grace wait is on the timed path — so the measured span captures
+        the real cold-start cost the ``session_cold_start`` journey exists for:
+        host launch + runner boot + reverse-tunnel connect + first-token
+        pipeline. No pre-warm and no ``GET /session`` status polling — the SSE
+        first-delta signal is the same one the UI renders on.
+
+        :raises RuntimeError: If not host-backed, or no delta / a terminal event
+            arrives within *timeout*.
+        """
+        session_id = await self.create_hosted_session(agent_id)
+        await self._post_and_await_first_delta(
+            session_id, text, wait_idle_first=False, timeout=timeout
+        )
+
+    async def drive_and_interrupt(
+        self, session_id: str, *, timeout: float = _TURN_TIMEOUT_S
+    ) -> None:
+        """Drive a gated turn, interrupt it mid-flight, return when cancelled.
+
+        The caller configures a ``block=True`` mock response first (see
+        :meth:`configure_mock`), so the turn parks in ``running`` on the
+        executor's LLM call. We post an ``interrupt`` once running, wait for the
+        server's cancellation marker, then release the gate so the runner
+        unwinds cleanly. Times the server → runner → executor cancel path.
+
+        :raises RuntimeError: If not in runner mode, or the interrupt is not
+            honored within *timeout*.
+        """
+        assert self.client is not None
+        if not self.with_runner:
+            raise RuntimeError("drive_and_interrupt requires with_runner=True")
+        body = {
+            "type": "message",
+            "data": {"role": "user", "content": [{"type": "input_text", "text": "Interrupt me."}]},
+        }
+        posted = await self.client.post(f"/v1/sessions/{session_id}/events", json=body)
+        posted.raise_for_status()
+
+        deadline = time.monotonic() + timeout
+        interrupted = False
+        try:
+            while time.monotonic() < deadline:
+                snap = (await self.client.get(f"/v1/sessions/{session_id}")).json()
+                status = snap.get("status")
+                items = snap.get("items", [])
+                if status in ("running", "waiting") and not interrupted:
+                    await self.client.post(
+                        f"/v1/sessions/{session_id}/events", json={"type": "interrupt"}
+                    )
+                    interrupted = True
+                if _has_cancellation_marker(items):
+                    return
+                if status == "idle" and interrupted:
+                    if _has_cancellation_marker(items):
+                        return
+                    raise RuntimeError("turn settled without a cancellation marker")
+                await asyncio.sleep(_POLL_INTERVAL_S)
+            raise RuntimeError(f"interrupt not honored within {timeout}s (session {session_id})")
+        finally:
+            # Always release the gate so the blocked runner turn unwinds and
+            # teardown doesn't hang, even if the interrupt path errored above.
+            with contextlib.suppress(httpx.HTTPError):
+                await self._mock_post("/gate/release", {})
+
+
+def _has_cancellation_marker(items: list[dict[str, object]]) -> bool:
+    """Whether items include the synthetic 'interrupted' user message."""
+    for raw in items:
+        data = raw.get("data", raw)
+        if not isinstance(data, dict):
+            continue
+        if raw.get("type") == "message" and data.get("role") == "user":
+            content = data.get("content") or []
+            if isinstance(content, list) and any(
+                isinstance(b, dict) and _CANCELLATION_MARKER in str(b.get("text", ""))
+                for b in content
+            ):
+                return True
+    return False

dev/benchmarks/omnigent/journeys.py

@@ -0,0 +1,607 @@
+"""User-journey definitions and the runners that time them.
+
+A :class:`Journey` names a user-facing operation, an optional per-journey
+``setup`` that returns a context object, and a ``measure`` coroutine — the
+timed unit. :func:`run_latency` times ``measure`` sequentially; journeys marked
+``concurrency_safe`` can also be driven by :func:`run_throughput` with many
+operations in flight.
+
+v1 journeys are pure HTTP/API (server + DB, no runner, no LLM):
+
+- ``list_sessions`` — the session-list read behind the sidebar/home.
+- ``create_session`` — session creation cost (POST then DELETE).
+- ``get_session`` — single-session snapshot load.
+- ``load_conversation_history`` — history read, seeded runner-free via
+  ``external_conversation_item`` (see :meth:`BenchEnvironment.seed_items`).
+- ``fork_session`` — fork a session (deep-copy its items), then DELETE.
+- ``add_comment`` — create a review comment on a file (DB write).
+
+``read_runner_file`` needs a runner but no LLM turn: it plants a file in the
+runner environment (setup) and times the server → runner filesystem read proxy.
+
+Full-turn journeys (``needs_runner=True``) drive a real turn through the runner
++ mock LLM. ``session_cold_start`` (``needs_host=True``) measures the real UI
+new-conversation cold path: it spawns a host daemon once, then per iteration
+creates a host-bound session (which fires ``host.launch_runner``), attaches the
+SSE stream, sends the first message, and times to the first output-text delta —
+so the span includes the on-demand runner launch + reverse-tunnel handshake the
+UI's first message races, exactly as a real new chat pays it.
+
+The framework (``Journey`` + the two runners) is harness-agnostic and reused
+verbatim by phase-2 full-turn journeys.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Literal, cast
+
+import httpx
+
+from .environment import BenchEnvironment
+from .measure import RunResult
+
+# Per-journey context returned by ``setup`` and threaded to ``measure``. Its
+# concrete type varies by journey (an agent id, a session id, or nothing), so
+# it is opaque at the framework level; each measure op casts it as needed.
+JourneyContext = object
+
+JourneyKind = Literal["latency", "throughput"]
+
+# Items requested per history-read page. Also the count self-seeded into a
+# fallback session when the DB has no corpus (empty-DB smoke path).
+_HISTORY_PAGE_LIMIT = 20
+_HISTORY_SEED_ITEMS = _HISTORY_PAGE_LIMIT
+
+
+@dataclass
+class Journey:
+    """One benchmarkable user journey.
+
+    :param name: Stable identifier used on the CLI and as the report key.
+    :param kind: ``"latency"`` (time each operation) or ``"throughput"``
+        (fixed request count under concurrency). A latency journey that is
+        ``concurrency_safe`` can additionally be run as throughput.
+    :param measure: Coroutine performing exactly one timed operation, given
+        the environment and the setup context.
+    :param setup: Optional coroutine run once before timing; its return value
+        is passed to ``measure`` (and ``teardown``) as ``ctx``.
+    :param teardown: Optional coroutine run once after timing, given ``ctx``.
+    :param concurrency_safe: Whether many ``measure`` calls may run at once
+        against a shared setup (true for read-only / independent-write HTTP
+        journeys).
+    :param needs_runner: Whether this journey drives a full agent turn and so
+        requires ``BenchEnvironment(with_runner=True)`` (mock LLM + runner).
+        HTTP/DB journeys leave this ``False``.
+    :param needs_host: Whether this journey needs a real host daemon
+        (``BenchEnvironment(with_host=True)``) so a host-bound session-create
+        fires ``host.launch_runner`` and the first message races the runner's
+        boot. Implies ``needs_runner``. Only ``session_cold_start`` sets this.
+    :param max_iterations: Upper bound on latency iterations for this journey,
+        clamping ``--iterations`` down (never up). Full-turn journeys cost ~1s+
+        per op, so 100+ iterations would blow the CI time budget; they cap at a
+        few samples per run and lean on ``--runs`` for repeats. ``None`` (HTTP
+        journeys) means no cap.
+    :param description: Human-readable one-liner for ``--list``.
+    """
+
+    name: str
+    kind: JourneyKind
+    measure: Callable[[BenchEnvironment, JourneyContext], Awaitable[None]]
+    setup: Callable[[BenchEnvironment], Awaitable[JourneyContext]] | None = None
+    teardown: Callable[[BenchEnvironment, JourneyContext], Awaitable[None]] | None = None
+    concurrency_safe: bool = False
+    needs_runner: bool = False
+    needs_host: bool = False
+    max_iterations: int | None = None
+    description: str = ""
+
+    async def run_setup(self, env: BenchEnvironment) -> JourneyContext:
+        return await self.setup(env) if self.setup is not None else None
+
+    async def run_teardown(self, env: BenchEnvironment, ctx: JourneyContext) -> None:
+        if self.teardown is not None:
+            await self.teardown(env, ctx)
+
+
+# ── timed operation (shared by both runners) ─────────────────
+
+
+async def _timed(
+    journey: Journey, env: BenchEnvironment, ctx: JourneyContext, result: RunResult
+) -> None:
+    """Run one ``measure`` op, recording its latency or a failure reason."""
+    start = time.perf_counter()
+    try:
+        await journey.measure(env, ctx)
+    except httpx.HTTPStatusError as exc:
+        result.record_failure(f"HTTP {exc.response.status_code}")
+    except Exception as exc:  # noqa: BLE001 — any failure is a recorded data point
+        result.record_failure(exc.__class__.__name__)
+    else:
+        result.latencies_ms.append((time.perf_counter() - start) * 1000)
+
+
+# ── runners ──────────────────────────────────────────────────
+
+
+async def run_latency(
+    journey: Journey, env: BenchEnvironment, *, iterations: int, warmup: int
+) -> RunResult:
+    """Time *iterations* sequential operations after discarding *warmup*.
+
+    Warmup operations run through the same path but are excluded from the
+    result, so first-call import/JIT/connection costs don't skew the numbers.
+    """
+    ctx = await journey.run_setup(env)
+    try:
+        for _ in range(warmup):
+            with contextlib.suppress(Exception):  # warmup errors are non-fatal
+                await journey.measure(env, ctx)
+        result = RunResult()
+        wall_start = time.perf_counter()
+        for _ in range(iterations):
+            await _timed(journey, env, ctx, result)
+        result.wall_time = time.perf_counter() - wall_start
+        return result
+    finally:
+        await journey.run_teardown(env, ctx)
+
+
+async def run_throughput(
+    journey: Journey,
+    env: BenchEnvironment,
+    *,
+    requests: int,
+    concurrency: int,
+    warmup: int,
+) -> RunResult:
+    """Fire *requests* operations with at most *concurrency* in flight.
+
+    Wall time spans from the first dispatch to the last completion, so
+    ``throughput`` reflects sustained req/s under load (MLflow's ``_run_once``
+    shape, with an :class:`asyncio.Semaphore` gate).
+    """
+    ctx = await journey.run_setup(env)
+    try:
+        sem = asyncio.Semaphore(concurrency)
+
+        async def _one(count_it: bool, result: RunResult) -> None:
+            async with sem:
+                if count_it:
+                    await _timed(journey, env, ctx, result)
+                else:
+                    with contextlib.suppress(Exception):  # warmup errors are non-fatal
+                        await journey.measure(env, ctx)
+
+        if warmup:
+            throwaway = RunResult()
+            await asyncio.gather(*[_one(False, throwaway) for _ in range(warmup)])
+
+        result = RunResult()
+        wall_start = time.perf_counter()
+        await asyncio.gather(*[_one(True, result) for _ in range(requests)])
+        result.wall_time = time.perf_counter() - wall_start
+        return result
+    finally:
+        await journey.run_teardown(env, ctx)
+
+
+# ── journey implementations ──────────────────────────────────
+#
+# Setups return the context each measure op needs. Ops must be independent so
+# concurrency-safe journeys don't interfere across in-flight calls.
+
+
+# A token present in the seeded corpus (titles + item text, see seed.py
+# _FRAGMENTS) so search_sessions exercises the LIKE path with real matches.
+_SEARCH_TOKEN = "runner"
+
+
+async def _setup_agent_id(env: BenchEnvironment) -> str:
+    """Register the benchmark agent and return its id."""
+    name = await env.ensure_agent()
+    return await env.agent_id(name)
+
+
+async def _setup_target_session(env: BenchEnvironment) -> str:
+    """Return a session id to read: an existing corpus session if any, else make one.
+
+    Real runs target a pre-seeded corpus (``seed.py``), so we read a
+    representative existing session. When the DB is empty (e.g. the smoke test
+    against a throwaway DB), fall back to creating one with a little history so
+    the journey still exercises the read path.
+    """
+    assert env.client is not None
+    listing = await env.client.get("/v1/sessions", params={"limit": 1})
+    listing.raise_for_status()
+    data = listing.json().get("data", [])
+    if data:
+        return str(data[0]["id"])
+    # Empty DB: self-seed one session over HTTP (runner-free).
+    name = await env.ensure_agent()
+    agent_id = await env.agent_id(name)
+    session_id = await env.create_session(agent_id)
+    await env.seed_items(session_id, _HISTORY_SEED_ITEMS)
+    return session_id
+
+
+async def _measure_list_sessions(env: BenchEnvironment, _ctx: JourneyContext) -> None:
+    assert env.client is not None
+    resp = await env.client.get("/v1/sessions", params={"limit": 20})
+    resp.raise_for_status()
+
+
+async def _measure_search_sessions(env: BenchEnvironment, _ctx: JourneyContext) -> None:
+    assert env.client is not None
+    resp = await env.client.get(
+        "/v1/sessions", params={"limit": 20, "search_query": _SEARCH_TOKEN}
+    )
+    resp.raise_for_status()
+
+
+async def _measure_create_session(env: BenchEnvironment, ctx: JourneyContext) -> None:
+    assert env.client is not None
+    agent_id = cast(str, ctx)  # _setup_agent_id
+    created = await env.client.post("/v1/sessions", json={"agent_id": agent_id})
+    created.raise_for_status()
+    # Delete inline so a long run doesn't accumulate unbounded sessions; the
+    # POST is the operation of interest and dominates the timed span.
+    session_id = created.json()["id"]
+    deleted = await env.client.delete(f"/v1/sessions/{session_id}")
+    deleted.raise_for_status()
+
+
+async def _measure_get_session(env: BenchEnvironment, ctx: JourneyContext) -> None:
+    assert env.client is not None
+    session_id = cast(str, ctx)  # _setup_target_session
+    resp = await env.client.get(f"/v1/sessions/{session_id}")
+    resp.raise_for_status()
+
+
+async def _measure_load_history(env: BenchEnvironment, ctx: JourneyContext) -> None:
+    assert env.client is not None
+    session_id = cast(str, ctx)  # _setup_target_session
+    resp = await env.client.get(
+        f"/v1/sessions/{session_id}/items",
+        params={"order": "asc", "limit": _HISTORY_PAGE_LIMIT},
+    )
+    resp.raise_for_status()
+
+
+@dataclass
+class _ForkContext:
+    """Fork-journey context: the session to fork + the forks to clean up.
+
+    ``measure`` records each fork's id here instead of deleting it inline, so
+    the DELETE stays out of the timed span; ``teardown`` removes them after.
+    """
+
+    source_id: str
+    fork_ids: list[str]
+
+
+async def _setup_fork_session(env: BenchEnvironment) -> _ForkContext:
+    """Resolve a session to fork; start an empty fork-id collector."""
+    source_id = await _setup_target_session(env)
+    return _ForkContext(source_id=source_id, fork_ids=[])
+
+
+async def _measure_fork_session(env: BenchEnvironment, ctx: JourneyContext) -> None:
+    assert env.client is not None
+    fork_ctx = cast(_ForkContext, ctx)  # _setup_fork_session
+    forked = await env.client.post(f"/v1/sessions/{fork_ctx.source_id}/fork", json={})
+    forked.raise_for_status()
+    # Record the fork for teardown; deleting it here would fold the DELETE into
+    # the timed span. The fork POST (a deep-copy of the source's items) is the
+    # operation of interest.
+    fork_ctx.fork_ids.append(forked.json()["id"])
+
+
+async def _teardown_fork_session(env: BenchEnvironment, ctx: JourneyContext) -> None:
+    """Delete every fork created during the run (best effort, untimed)."""
+    assert env.client is not None
+    fork_ctx = cast(_ForkContext, ctx)
+    for fork_id in fork_ctx.fork_ids:
+        with contextlib.suppress(httpx.HTTPError):
+            await env.client.delete(f"/v1/sessions/{fork_id}")
+
+
+# Anchor snapshot for the comment journey; the offsets below span it.
+_COMMENT_ANCHOR = "benchmark"
+
+
+async def _measure_add_comment(env: BenchEnvironment, ctx: JourneyContext) -> None:
+    assert env.client is not None
+    session_id = cast(str, ctx)  # _setup_target_session
+    # Each POST creates an independent comment row. Unlike sessions, an
+    # accumulating comment skews no measured read path, so there's no cleanup.
+    # The file need not exist — the handler stores the path + offsets + body.
+    resp = await env.client.post(
+        f"/v1/sessions/{session_id}/comments",
+        json={
+            "path": "bench_target.py",
+            "body": "benchmark review comment",
+            "start_index": 0,
+            "end_index": len(_COMMENT_ANCHOR),
+            "anchor_content": _COMMENT_ANCHOR,
+        },
+    )
+    resp.raise_for_status()
+
+
+# ── runner (full-turn) journeys ──────────────────────────────
+#
+# These drive a real agent turn through the runner + mock LLM (with_runner=True,
+# openai-agents). The mock is zero-latency, so every number is omnigent dispatch
+# / streaming / cancel overhead, not model latency. Short deterministic replies.
+
+# A multi-word reply so the streaming path emits several output_text deltas.
+_TURN_REPLY = "Hello there, this is a mock benchmark reply."
+_TURN_PROMPT = "Say hello."
+
+# Iteration cap for full-turn journeys. At ~1s+ per turn, matching the HTTP
+# journeys' iteration count would overrun the CI time budget, so we take a few
+# samples per run and lean on --runs for repeats. Sessions accumulate across a
+# run (a cold start never deletes its session), so a small count also keeps that
+# drift negligible.
+_RUNNER_MAX_ITERATIONS = 5
+
+# Iteration cap for the runner filesystem read. It's a proxied localhost read,
+# not a full turn, so it's far cheaper than the drive-a-turn journeys — a higher
+# cap gives a usable p50/p99 while staying well within the CI time budget.
+_RUNNER_FS_MAX_ITERATIONS = 50
+
+# File planted by the read-runner-file setup and fetched by its measure op.
+# ~1 KB — a modest, representative source file, not a stress case.
+_RUNNER_FILE_PATH = "bench_read_target.txt"
+_RUNNER_FILE_CONTENT = "benchmark file content line\n" * 40
+
+
+async def _setup_turn_agent(env: BenchEnvironment, *, stream: bool = False) -> str:
+    """Register the agent + a reset-surviving reply; return the agent id.
+
+    The fallback survives per-call queue exhaustion, so every turn in the run
+    gets the same reply regardless of how many turns consume the queue. When
+    *stream* is set the reply emits per-word deltas (for the TTFT journey).
+    """
+    name = await env.ensure_agent()
+    await env.set_mock_fallback(_TURN_REPLY, stream=stream)
+    return await env.agent_id(name)
+
+
+async def _setup_cold_start_agent(env: BenchEnvironment) -> str:
+    """Register a streaming-reply agent for the cold-start journey; return its id.
+
+    No session and no warm-up turn — the cold-start measure creates a fresh
+    host-bound session each iteration. The reply streams deltas so the measured
+    op can return on the first ``response.output_text.delta`` (the UI's
+    first-token signal).
+    """
+    return await _setup_turn_agent(env, stream=True)
+
+
+async def _setup_warm_session(env: BenchEnvironment) -> str:
+    """Create+bind a session and drive one warm-up turn; return the session id.
+
+    The warm-up pays the cold-start cost (runner spawn + executor construction)
+    so the measured op times only steady-state per-turn overhead.
+    """
+    agent_id = await _setup_turn_agent(env)
+    session_id = await env.create_bound_session(agent_id)
+    await env.drive_turn(session_id, _TURN_PROMPT)
+    return session_id
+
+
+async def _setup_streaming_session(env: BenchEnvironment) -> str:
+    """Warm session whose mock reply streams deltas — for the TTFT journey."""
+    agent_id = await _setup_turn_agent(env, stream=True)
+    session_id = await env.create_bound_session(agent_id)
+    await env.drive_turn(session_id, _TURN_PROMPT)
+    return session_id
+
+
+async def _setup_interrupt_session(env: BenchEnvironment) -> str:
+    """Create+bind a session for the interrupt journey; return the session id.
+
+    Configures a ``block=True`` mock response so each turn parks in ``running``
+    until the gate is released — giving the interrupt something to cancel
+    mid-flight, deterministically.
+    """
+    name = await env.ensure_agent()
+    agent_id = await env.agent_id(name)
+    session_id = await env.create_bound_session(agent_id)
+    await env.configure_mock([{"text": _TURN_REPLY, "block": True}])
+    return session_id
+
+
+async def _measure_session_cold_start(env: BenchEnvironment, ctx: JourneyContext) -> None:
+    """Time the real UI cold path: create host-bound session → first token.
+
+    Faithfully imitates the Web UI's New Chat flow on a fresh session (see
+    ``BenchEnvironment.cold_start_first_delta``): create a host-bound session
+    (which fires ``host.launch_runner`` at the host daemon and returns before
+    the runner connects), attach the SSE stream, wait for its ready heartbeat,
+    POST the first message, and return on the first response.
+
+    Because the message posts while the runner is still booting, the server's
+    connect-grace wait is on the timed path — so the measured span captures the
+    true new-conversation cost: host launch + runner boot + reverse-tunnel
+    connect + first-token pipeline.
+
+    Each iteration is its own fresh session with its own host-launched runner.
+    The server never stops an external-host runner on idle (only on an explicit
+    stop/delete, neither of which the UI first-message path does), so each
+    iteration's runner stays connected until the daemon is SIGTERM'd at env
+    teardown, which reaps them together. That is bounded — ``_RUNNER_MAX_ITERATIONS``
+    (+ warmups) runners at most, all cleaned up at the end — so we deliberately
+    skip per-iteration teardown: stopping the runner would add a
+    stop-round-trip to a journey whose whole point is to time the fresh-launch
+    cost, and would not reflect what a real first message does.
+    """
+    agent_id = cast(str, ctx)  # _setup_turn_agent (stream=True)
+    await env.cold_start_first_delta(agent_id, _TURN_PROMPT)
+
+
+async def _measure_warm_turn(env: BenchEnvironment, ctx: JourneyContext) -> None:
+    session_id = cast(str, ctx)  # _setup_warm_session
+    await env.drive_turn(session_id, _TURN_PROMPT)
+
+
+async def _measure_time_to_first_token(env: BenchEnvironment, ctx: JourneyContext) -> None:
+    session_id = cast(str, ctx)  # _setup_warm_session
+    await env.time_to_first_delta(session_id, _TURN_PROMPT)
+
+
+async def _measure_interrupt(env: BenchEnvironment, ctx: JourneyContext) -> None:
+    session_id = cast(str, ctx)  # _setup_interrupt_session
+    await env.drive_and_interrupt(session_id)
+
+
+async def _setup_runner_file_session(env: BenchEnvironment) -> str:
+    """Bind a session to the runner and plant a file to read; return its id.
+
+    No turn is driven and no mock reply is configured — the measured op is a
+    filesystem read proxied to the runner, which never calls the LLM.
+    """
+    name = await env.ensure_agent()
+    agent_id = await env.agent_id(name)
+    session_id = await env.create_bound_session(agent_id)
+    await env.write_runner_file(session_id, _RUNNER_FILE_PATH, _RUNNER_FILE_CONTENT)
+    return session_id
+
+
+async def _measure_read_runner_file(env: BenchEnvironment, ctx: JourneyContext) -> None:
+    session_id = cast(str, ctx)  # _setup_runner_file_session
+    await env.read_runner_file(session_id, _RUNNER_FILE_PATH)
+
+
+# ── registry ─────────────────────────────────────────────────
+
+ALL_JOURNEYS: dict[str, Journey] = {
+    j.name: j
+    for j in (
+        Journey(
+            name="list_sessions",
+            kind="latency",
+            measure=_measure_list_sessions,
+            concurrency_safe=True,
+            description="GET /v1/sessions — session list read.",
+        ),
+        Journey(
+            name="create_session",
+            kind="latency",
+            measure=_measure_create_session,
+            setup=_setup_agent_id,
+            concurrency_safe=True,
+            description="POST /v1/sessions then DELETE — session create.",
+        ),
+        Journey(
+            name="get_session",
+            kind="latency",
+            measure=_measure_get_session,
+            setup=_setup_target_session,
+            concurrency_safe=True,
+            description="GET /v1/sessions/{id} — single-session snapshot.",
+        ),
+        Journey(
+            name="load_conversation_history",
+            kind="latency",
+            measure=_measure_load_history,
+            setup=_setup_target_session,
+            concurrency_safe=True,
+            description="GET /v1/sessions/{id}/items — conversation history read.",
+        ),
+        Journey(
+            name="search_sessions",
+            kind="latency",
+            measure=_measure_search_sessions,
+            concurrency_safe=True,
+            description="GET /v1/sessions?search_query= — unindexed LIKE over titles + items.",
+        ),
+        Journey(
+            name="fork_session",
+            kind="latency",
+            measure=_measure_fork_session,
+            setup=_setup_fork_session,
+            teardown=_teardown_fork_session,
+            concurrency_safe=True,
+            description="POST /v1/sessions/{id}/fork — session fork (deep-copy); DELETE untimed.",
+        ),
+        Journey(
+            name="add_comment",
+            kind="latency",
+            measure=_measure_add_comment,
+            setup=_setup_target_session,
+            concurrency_safe=True,
+            description="POST /v1/sessions/{id}/comments — create a review comment.",
+        ),
+        # Runner (full-turn) journeys — with_runner=True, openai-agents, mock LLM.
+        Journey(
+            name="session_cold_start",
+            kind="latency",
+            measure=_measure_session_cold_start,
+            setup=_setup_cold_start_agent,
+            needs_runner=True,
+            needs_host=True,
+            max_iterations=_RUNNER_MAX_ITERATIONS,
+            description="Create a host-bound session (fires host.launch_runner) then "
+            "time create → attach SSE → send → first token — the real UI cold path.",
+        ),
+        Journey(
+            name="warm_turn",
+            kind="latency",
+            measure=_measure_warm_turn,
+            setup=_setup_warm_session,
+            needs_runner=True,
+            max_iterations=_RUNNER_MAX_ITERATIONS,
+            description="Drive a turn on an already-warm session (steady-state overhead).",
+        ),
+        Journey(
+            name="time_to_first_token",
+            kind="latency",
+            measure=_measure_time_to_first_token,
+            setup=_setup_streaming_session,
+            needs_runner=True,
+            max_iterations=_RUNNER_MAX_ITERATIONS,
+            description="Post a turn; time to the first streamed output_text delta.",
+        ),
+        Journey(
+            name="interrupt",
+            kind="latency",
+            measure=_measure_interrupt,
+            setup=_setup_interrupt_session,
+            needs_runner=True,
+            max_iterations=_RUNNER_MAX_ITERATIONS,
+            description="Interrupt a running (gated) turn; time to cancellation.",
+        ),
+        Journey(
+            name="read_runner_file",
+            kind="latency",
+            measure=_measure_read_runner_file,
+            setup=_setup_runner_file_session,
+            needs_runner=True,
+            max_iterations=_RUNNER_FS_MAX_ITERATIONS,
+            description="GET .../environments/default/filesystem/{path} — runner file read proxy.",
+        ),
+    )
+}
+
+
+def resolve_journeys(names: list[str] | None) -> list[Journey]:
+    """Resolve requested journey *names* (or all when ``None``/empty).
+
+    :raises KeyError: If a requested name isn't registered.
+    """
+    if not names:
+        return list(ALL_JOURNEYS.values())
+    resolved = []
+    for name in names:
+        if name not in ALL_JOURNEYS:
+            raise KeyError(f"unknown journey {name!r}; known: {', '.join(ALL_JOURNEYS)}")
+        resolved.append(ALL_JOURNEYS[name])
+    return resolved

dev/benchmarks/omnigent/measure.py

@@ -0,0 +1,222 @@
+"""Latency/throughput measurement primitives.
+
+Pure and I/O-free: a :class:`RunResult` accumulates per-operation latencies
+and failures for one timed run, :func:`aggregate` folds several runs into the
+``runs`` + ``summary`` shape the workspace ETL flattens, and
+:func:`check_thresholds` gates a run in CI. Adapted from MLflow's
+``dev/benchmarks/gateway/benchmark.py``.
+"""
+
+from __future__ import annotations
+
+import math
+import statistics
+from dataclasses import dataclass, field
+
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+@dataclass
+class RunResult:
+    """Latencies and failures collected during one timed run.
+
+    :param latencies_ms: Per-operation wall-clock latency in milliseconds,
+        one entry per successful operation.
+    :param failures: Failure reason (e.g. ``"HTTP 500"`` / an exception
+        class name) mapped to how many times it occurred.
+    :param wall_time: Total elapsed seconds for the run, used for throughput.
+    """
+
+    latencies_ms: list[float] = field(default_factory=list)
+    failures: dict[str, int] = field(default_factory=dict)
+    wall_time: float = 0.0
+
+    @property
+    def n_success(self) -> int:
+        """Number of operations that completed without error."""
+        return len(self.latencies_ms)
+
+    @property
+    def n_failures(self) -> int:
+        """Total failed operations across all reasons."""
+        return sum(self.failures.values())
+
+    @property
+    def throughput(self) -> float:
+        """Successful operations per second over the run's wall time."""
+        return self.n_success / self.wall_time if self.wall_time > 0 else 0.0
+
+    def record_failure(self, reason: str) -> None:
+        """Increment the count for one failure *reason*."""
+        self.failures[reason] = self.failures.get(reason, 0) + 1
+
+    def percentile(self, p: float) -> float:
+        """Return the *p*-th percentile latency in ms (ceil-index method).
+
+        :param p: Percentile in ``[0, 100]``, e.g. ``99`` for p99.
+        :returns: The latency at that percentile, or ``0.0`` when no
+            successful operation was recorded.
+        """
+        if not self.latencies_ms:
+            return 0.0
+        ordered = sorted(self.latencies_ms)
+        idx = max(0, math.ceil(p / 100 * len(ordered)) - 1)
+        return ordered[idx]
+
+    def mean_ms(self) -> float:
+        """Mean latency in ms, or ``0.0`` when no operation succeeded."""
+        return statistics.mean(self.latencies_ms) if self.latencies_ms else 0.0
+
+    def max_ms(self) -> float:
+        """Maximum latency in ms, or ``0.0`` when no operation succeeded."""
+        return max(self.latencies_ms) if self.latencies_ms else 0.0
+
+
+def _run_to_dict(result: RunResult) -> dict[str, object]:
+    """Flatten one :class:`RunResult` into a JSON-serializable per-run row."""
+    return {
+        "n_success": result.n_success,
+        "n_failures": result.n_failures,
+        "failures": dict(result.failures),
+        "wall_time_s": result.wall_time,
+        "mean_ms": result.mean_ms(),
+        "p50_ms": result.percentile(50),
+        "p95_ms": result.percentile(95),
+        "p99_ms": result.percentile(99),
+        "max_ms": result.max_ms(),
+        "rps": result.throughput,
+    }
+
+
+def aggregate(results: list[RunResult]) -> dict[str, object]:
+    """Fold per-run results into ``{"runs": [...], "summary": {...}}``.
+
+    The ``summary`` averages each metric across runs. Its keys mirror
+    MLflow's gateway benchmark (``avg_mean_ms`` / ``avg_p50_ms`` /
+    ``avg_p99_ms`` / ``avg_rps``) plus ``avg_p95_ms``, so the workspace ETL
+    that flattens ``summary`` works unchanged.
+
+    :param results: One :class:`RunResult` per timed run (warmup excluded).
+    :returns: A dict with a per-run ``runs`` list and an averaged
+        ``summary`` (empty ``summary`` when *results* is empty).
+    """
+    runs = [_run_to_dict(r) for r in results]
+    if not results:
+        return {"runs": runs, "summary": {}}
+    summary = {
+        "avg_mean_ms": statistics.mean(r.mean_ms() for r in results),
+        "avg_p50_ms": statistics.mean(r.percentile(50) for r in results),
+        "avg_p95_ms": statistics.mean(r.percentile(95) for r in results),
+        "avg_p99_ms": statistics.mean(r.percentile(99) for r in results),
+        "avg_rps": statistics.mean(r.throughput for r in results),
+    }
+    return {"runs": runs, "summary": summary}
+
+
+def check_thresholds(
+    results: list[RunResult],
+    *,
+    min_rps: float | None = None,
+    max_p50_ms: float | None = None,
+    max_p99_ms: float | None = None,
+) -> bool:
+    """Check averaged results against optional CI thresholds.
+
+    :param results: Timed runs for one journey.
+    :param min_rps: Fail if average throughput is below this (req/s).
+    :param max_p50_ms: Fail if average p50 latency exceeds this (ms).
+    :param max_p99_ms: Fail if average p99 latency exceeds this (ms).
+    :returns: ``True`` when every supplied threshold passes (vacuously
+        true when none are supplied or *results* is empty).
+    """
+    if not results:
+        return True
+    avg_rps = statistics.mean(r.throughput for r in results)
+    avg_p50 = statistics.mean(r.percentile(50) for r in results)
+    avg_p99 = statistics.mean(r.percentile(99) for r in results)
+    passed = True
+
+    if min_rps is not None and avg_rps < min_rps:
+        console.print(
+            f"  [red]THRESHOLD FAILED:[/red] avg throughput {avg_rps:.0f} req/s"
+            f" < minimum {min_rps:.0f} req/s"
+        )
+        passed = False
+    if max_p50_ms is not None and avg_p50 > max_p50_ms:
+        console.print(
+            f"  [red]THRESHOLD FAILED:[/red] avg P50 {avg_p50:.1f} ms"
+            f" > maximum {max_p50_ms:.1f} ms"
+        )
+        passed = False
+    if max_p99_ms is not None and avg_p99 > max_p99_ms:
+        console.print(
+            f"  [red]THRESHOLD FAILED:[/red] avg P99 {avg_p99:.1f} ms"
+            f" > maximum {max_p99_ms:.1f} ms"
+        )
+        passed = False
+    return passed
+
+
+def print_results(journey_name: str, results: list[RunResult]) -> None:
+    """Render per-run and averaged metrics for one journey as a rich table.
+
+    :param journey_name: Journey label used as the table title.
+    :param results: Timed runs to display.
+    """
+    table = Table(
+        title=journey_name,
+        show_header=True,
+        header_style="bold cyan",
+        box=None,
+        padding=(0, 2),
+        title_justify="left",
+    )
+    table.add_column("Run", style="dim", width=5)
+    table.add_column("Mean ms", justify="right")
+    table.add_column("P50 ms", justify="right")
+    table.add_column("P95 ms", justify="right")
+    table.add_column("P99 ms", justify="right")
+    table.add_column("Max ms", justify="right")
+    table.add_column("Req/s", justify="right")
+    table.add_column("Failures", justify="right")
+
+    for i, r in enumerate(results):
+        fail_str = f"[red]{r.n_failures}[/red]" if r.n_failures else "0"
+        table.add_row(
+            str(i + 1),
+            f"{r.mean_ms():.1f}",
+            f"{r.percentile(50):.1f}",
+            f"{r.percentile(95):.1f}",
+            f"{r.percentile(99):.1f}",
+            f"{r.max_ms():.1f}",
+            f"{r.throughput:.0f}",
+            fail_str,
+        )
+
+    if len(results) > 1:
+        table.add_section()
+        table.add_row(
+            "[bold]avg[/bold]",
+            f"[bold]{statistics.mean(r.mean_ms() for r in results):.1f}[/bold]",
+            f"[bold]{statistics.mean(r.percentile(50) for r in results):.1f}[/bold]",
+            f"[bold]{statistics.mean(r.percentile(95) for r in results):.1f}[/bold]",
+            f"[bold]{statistics.mean(r.percentile(99) for r in results):.1f}[/bold]",
+            f"[bold]{statistics.mean(r.max_ms() for r in results):.1f}[/bold]",
+            f"[bold]{statistics.mean(r.throughput for r in results):.0f}[/bold]",
+            "",
+        )
+
+    console.print()
+    console.print(table)
+
+    combined: dict[str, int] = {}
+    for r in results:
+        for reason, count in r.failures.items():
+            combined[reason] = combined.get(reason, 0) + count
+    if combined:
+        console.print("  [red]Failure breakdown:[/red]")
+        for reason, count in sorted(combined.items(), key=lambda kv: -kv[1]):
+            console.print(f"    {reason}: {count}")

dev/benchmarks/omnigent/run.py

@@ -0,0 +1,279 @@
+"""Omnigent user-journey benchmark runner.
+
+Boots a real ``omnigent server`` against a SQLite DB (no runner, no LLM),
+drives the selected HTTP journeys under load, prints per-journey latency /
+throughput tables, and writes a versioned JSON report. Exits non-zero if any
+supplied threshold is breached.
+
+Runs in the project venv — it imports ``omnigent`` and ``tests._helpers`` and
+spawns the real server, so it is NOT a standalone PEP 723 script. Invoke with
+``--no-sync`` so ``uv`` uses the existing environment instead of rebuilding the
+project (which triggers a web-UI build that fails in a worktree)::
+
+    uv run --no-sync dev/benchmarks/omnigent/run.py
+    uv run --no-sync dev/benchmarks/omnigent/run.py --journeys list_sessions,get_session
+    uv run --no-sync dev/benchmarks/omnigent/run.py --requests 500 --concurrency 25 --runs 3
+    uv run --no-sync dev/benchmarks/omnigent/run.py --output bench.json --max-p50-ms 25
+
+The JSON is the contract consumed by the workspace Databricks ETL notebook —
+see ``README.md``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import datetime
+import json
+import sys
+from pathlib import Path
+
+# Allow ``uv run <path>`` (no package context) to import the sibling modules.
+sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
+
+from dev.benchmarks.omnigent.environment import BenchEnvironment
+from dev.benchmarks.omnigent.journeys import (
+    ALL_JOURNEYS,
+    Journey,
+    resolve_journeys,
+    run_latency,
+    run_throughput,
+)
+from dev.benchmarks.omnigent.measure import (
+    RunResult,
+    aggregate,
+    check_thresholds,
+    console,
+    print_results,
+)
+from dev.benchmarks.omnigent.schema import build_report
+
+# Harness label stamped in the report: HTTP/DB journeys drive no agent turn;
+# runner journeys drive turns through the in-process openai-agents SDK harness.
+_HTTP_HARNESS = "http-only"
+_RUNNER_HARNESS = "openai-agents"
+
+
+def _backend_of(database_uri: str | None) -> str:
+    """Classify the DB URI into a coarse backend label for the report.
+
+    ``None`` is the harness's throwaway SQLite temp file. Otherwise key off the
+    URI scheme so the report (and the workspace dashboard) can group by backend.
+    """
+    if database_uri is None or database_uri.startswith("sqlite"):
+        return "sqlite"
+    if database_uri.startswith("postgres"):
+        return "postgres"
+    if database_uri.startswith("mysql"):
+        return "mysql"
+    return "other"
+
+
+def _effective_iterations(journey: Journey, requested: int) -> int:
+    """Clamp *requested* iterations down to the journey's ``max_iterations``.
+
+    Full-turn journeys cost ~1s+ per op and cap themselves so a large
+    ``--iterations`` (tuned for the millisecond HTTP journeys) doesn't overrun
+    the CI time budget. The cap only ever lowers the count, never raises it.
+    """
+    if journey.max_iterations is not None:
+        return min(requested, journey.max_iterations)
+    return requested
+
+
+async def _run_journey(
+    journey: Journey, env: BenchEnvironment, args: argparse.Namespace
+) -> tuple[str, list[RunResult]]:
+    """Run one journey's timed runs, returning its report kind + per-run results.
+
+    A journey runs as throughput when ``--concurrency > 1`` and it is
+    concurrency-safe; otherwise as sequential latency.
+    """
+    as_throughput = args.concurrency > 1 and journey.concurrency_safe
+    iterations = _effective_iterations(journey, args.iterations)
+    results: list[RunResult] = []
+    for _ in range(args.runs):
+        if as_throughput:
+            results.append(
+                await run_throughput(
+                    journey,
+                    env,
+                    requests=args.requests,
+                    concurrency=args.concurrency,
+                    warmup=args.warmup,
+                )
+            )
+        else:
+            results.append(
+                await run_latency(journey, env, iterations=iterations, warmup=args.warmup)
+            )
+    return ("throughput" if as_throughput else "latency"), results
+
+
+async def run_benchmark(args: argparse.Namespace) -> tuple[dict[str, object], bool]:
+    """Run all selected journeys and build the report.
+
+    :returns: ``(report, passed)`` where *passed* is ``False`` if any journey
+        breached a supplied threshold.
+    """
+    journeys = resolve_journeys(args.journeys)
+    journey_results: dict[str, dict[str, object]] = {}
+    passed = True
+    backend = _backend_of(args.database_uri)
+
+    # Any full-turn journey needs the runner + mock LLM. A full env is a
+    # superset — HTTP journeys still run against it — so a mixed selection just
+    # boots with_runner=True. The harness label reflects what drove the turns.
+    # A host-backed journey (session_cold_start) additionally needs a host
+    # daemon; with_host is a further superset (it implies with_runner) so a
+    # mixed selection that includes it boots the host too.
+    with_runner = any(j.needs_runner for j in journeys)
+    with_host = any(j.needs_host for j in journeys)
+    harness = _RUNNER_HARNESS if with_runner else _HTTP_HARNESS
+
+    async with BenchEnvironment(
+        with_runner=with_runner, with_host=with_host, database_uri=args.database_uri
+    ) as env:
+        for journey in journeys:
+            console.print(f"\n[bold]Benchmarking[/bold] {journey.name} [dim]({backend})[/dim]")
+            kind, results = await _run_journey(journey, env, args)
+            print_results(journey.name, results)
+            block = aggregate(results)
+            block["kind"] = kind
+            block["backend"] = backend
+            # Hardcoded per-journey mapping: HTTP journeys are False, full-turn
+            # journeys True. Sourced from the journey itself, not the run-level
+            # env, so it stays correct in a mixed selection (where with_runner
+            # is True for the whole run because *some* journey needs it).
+            block["needs_runner"] = journey.needs_runner
+            journey_results[journey.name] = block
+            if not check_thresholds(
+                results,
+                min_rps=args.min_rps,
+                max_p50_ms=args.max_p50_ms,
+                max_p99_ms=args.max_p99_ms,
+            ):
+                passed = False
+
+    config = {
+        "iterations": args.iterations,
+        "requests": args.requests,
+        "concurrency": args.concurrency,
+        "runs": args.runs,
+        "warmup": args.warmup,
+        "with_runner": with_runner,
+        "backend": backend,
+    }
+    generated_at = datetime.datetime.now(datetime.timezone.utc).isoformat()
+    report = build_report(
+        journey_results,
+        generated_at=generated_at,
+        config=config,
+        harness=harness,
+    )
+    return report, passed
+
+
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="omnigent-benchmark",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--journeys",
+        type=lambda s: [p.strip() for p in s.split(",") if p.strip()],
+        default=None,
+        metavar="A,B,C",
+        help=f"Comma-separated journeys to run. Default: all ({', '.join(ALL_JOURNEYS)}).",
+    )
+    parser.add_argument(
+        "--database-uri",
+        default=None,
+        metavar="URI",
+        help="DB the server boots against — a pre-seeded SQLite file, a "
+        "postgresql+psycopg://… instance, or a mysql+mysqldb://… instance "
+        "(see seed.py). Default: a fresh throwaway SQLite DB (empty — "
+        "best-case numbers). The report's `backend` field is derived from this.",
+    )
+    parser.add_argument(
+        "--iterations",
+        type=int,
+        default=100,
+        metavar="N",
+        help="Sequential operations per latency run (default: 100).",
+    )
+    parser.add_argument(
+        "--requests",
+        type=int,
+        default=500,
+        metavar="N",
+        help="Total operations per throughput run — used when --concurrency>1 (default: 500).",
+    )
+    parser.add_argument(
+        "--concurrency",
+        type=int,
+        default=1,
+        metavar="N",
+        help="Max in-flight operations. >1 runs concurrency-safe journeys as "
+        "throughput (default: 1 = sequential latency).",
+    )
+    parser.add_argument(
+        "--runs",
+        type=int,
+        default=3,
+        metavar="N",
+        help="Timed runs per journey; results are per-run and averaged (default: 3).",
+    )
+    parser.add_argument(
+        "--warmup",
+        type=int,
+        default=10,
+        metavar="N",
+        help="Warmup operations discarded before each run (default: 10).",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=None,
+        metavar="FILE",
+        help="Write the JSON report to FILE (for CI artifact upload).",
+    )
+    parser.add_argument(
+        "--min-rps",
+        type=float,
+        default=None,
+        metavar="N",
+        help="Exit 1 if any journey's avg throughput falls below N req/s.",
+    )
+    parser.add_argument(
+        "--max-p50-ms",
+        type=float,
+        default=None,
+        metavar="N",
+        help="Exit 1 if any journey's avg P50 latency exceeds N ms.",
+    )
+    parser.add_argument(
+        "--max-p99-ms",
+        type=float,
+        default=None,
+        metavar="N",
+        help="Exit 1 if any journey's avg P99 latency exceeds N ms.",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv if argv is not None else sys.argv[1:])
+    report, passed = asyncio.run(run_benchmark(args))
+    if args.output is not None:
+        args.output.write_text(json.dumps(report, indent=2))
+        console.print(f"\n  Results written to [cyan]{args.output}[/cyan]")
+    if not passed:
+        console.print("\n[red]One or more thresholds failed.[/red]")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dev/benchmarks/omnigent/sample_output.json

@@ -0,0 +1,273 @@
+{
+  "schema_version": 2,
+  "generated_at": "2026-07-08T18:30:00+00:00",
+  "git_sha": "0000000000000000000000000000000000000000",
+  "git_branch": "main",
+  "host": {
+    "platform": "macOS-15.5-arm64-arm-64bit",
+    "python": "3.12.8",
+    "cpu_count": 12
+  },
+  "harness": "http-only",
+  "config": {
+    "iterations": 100,
+    "requests": 500,
+    "concurrency": 1,
+    "runs": 3,
+    "warmup": 10,
+    "with_runner": false,
+    "backend": "sqlite"
+  },
+  "journeys": {
+    "list_sessions": {
+      "runs": [
+        {
+          "n_success": 100,
+          "n_failures": 0,
+          "failures": {},
+          "wall_time_s": 0.6587757079978473,
+          "mean_ms": 6.586994149838574,
+          "p50_ms": 6.261250004172325,
+          "p95_ms": 7.65325000975281,
+          "p99_ms": 7.9127089702524245,
+          "max_ms": 38.27937500318512,
+          "rps": 151.79673261468648
+        },
+        {
+          "n_success": 100,
+          "n_failures": 0,
+          "failures": {},
+          "wall_time_s": 0.6238234580378048,
+          "mean_ms": 6.237602901528589,
+          "p50_ms": 6.126708001829684,
+          "p95_ms": 7.152916979975998,
+          "p99_ms": 7.425624993629754,
+          "max_ms": 7.667875033803284,
+          "rps": 160.30176280087855
+        },
+        {
+          "n_success": 100,
+          "n_failures": 0,
+          "failures": {},
+          "wall_time_s": 0.5675292499945499,
+          "mean_ms": 5.674769564066082,
+          "p50_ms": 5.528832960408181,
+          "p95_ms": 6.237249996047467,
+          "p99_ms": 7.393250009045005,
+          "max_ms": 11.83562504593283,
+          "rps": 176.20237194992208
+        }
+      ],
+      "summary": {
+        "avg_mean_ms": 6.166455538477749,
+        "avg_p50_ms": 5.972263655470063,
+        "avg_p95_ms": 7.014472328592092,
+        "avg_p99_ms": 7.577194657642394,
+        "avg_rps": 162.7669557884957
+      },
+      "kind": "latency",
+      "backend": "sqlite",
+      "needs_runner": false
+    },
+    "create_session": {
+      "runs": [
+        {
+          "n_success": 100,
+          "n_failures": 0,
+          "failures": {},
+          "wall_time_s": 2.4451411250047386,
+          "mean_ms": 24.450668342760764,
+          "p50_ms": 24.028874991927296,
+          "p95_ms": 27.25041698431596,
+          "p99_ms": 29.374166973866522,
+          "max_ms": 29.56758299842477,
+          "rps": 40.89743490769115
+        },
+        {
+          "n_success": 100,
+          "n_failures": 0,
+          "failures": {},
+          "wall_time_s": 2.498600291030016,
+          "mean_ms": 24.985182073432952,
+          "p50_ms": 24.459875014144927,
+          "p95_ms": 28.391665953677148,
+          "p99_ms": 29.0600000298582,
+          "max_ms": 34.39550002804026,
+          "rps": 40.02240788932922
+        },
+        {
+          "n_success": 100,
+          "n_failures": 0,
+          "failures": {},
+          "wall_time_s": 2.455423459003214,
+          "mean_ms": 24.553418274153955,
+          "p50_ms": 24.073333013802767,
+          "p95_ms": 27.43383398046717,
+          "p99_ms": 29.375000041909516,
+          "max_ms": 29.430416005197912,
+          "rps": 40.72617276394162
+        }
+      ],
+      "summary": {
+        "avg_mean_ms": 24.663089563449223,
+        "avg_p50_ms": 24.187361006624997,
+        "avg_p95_ms": 27.691972306153428,
+        "avg_p99_ms": 29.269722348544747,
+        "avg_rps": 40.548671853654
+      },
+      "kind": "latency",
+      "backend": "sqlite",
+      "needs_runner": false
+    },
+    "get_session": {
+      "runs": [
+        {
+          "n_success": 100,
+          "n_failures": 0,
+          "failures": {},
+          "wall_time_s": 0.5546917500323616,
+          "mean_ms": 5.5460037814918905,
+          "p50_ms": 5.360124981962144,
+          "p95_ms": 6.925499998033047,
+          "p99_ms": 7.144333969336003,
+          "max_ms": 7.331291970331222,
+          "rps": 180.28030882767922
+        },
+        {
+          "n_success": 100,
+          "n_failures": 0,
+          "failures": {},
+          "wall_time_s": 0.49645508296089247,
+          "mean_ms": 4.963922067545354,
+          "p50_ms": 4.782959003932774,
+          "p95_ms": 5.978292028885335,
+          "p99_ms": 6.7617910099215806,
+          "max_ms": 6.881375040393323,
+          "rps": 201.42809174919327
+        },
+        {
+          "n_success": 100,
+          "n_failures": 0,
+          "failures": {},
+          "wall_time_s": 0.460644083970692,
+          "mean_ms": 4.605880451854318,
+          "p50_ms": 4.526541975792497,
+          "p95_ms": 5.18629199359566,
+          "p99_ms": 5.445250018965453,
+          "max_ms": 5.790999974124134,
+          "rps": 217.08734244020465
+        }
+      ],
+      "summary": {
+        "avg_mean_ms": 5.0386021002971875,
+        "avg_p50_ms": 4.889875320562472,
+        "avg_p95_ms": 6.030028006838013,
+        "avg_p99_ms": 6.450458332741012,
+        "avg_rps": 199.59858100569238
+      },
+      "kind": "latency",
+      "backend": "sqlite",
+      "needs_runner": false
+    },
+    "load_conversation_history": {
+      "runs": [
+        {
+          "n_success": 100,
+          "n_failures": 0,
+          "failures": {},
+          "wall_time_s": 0.20811437495285645,
+          "mean_ms": 2.080691678565927,
+          "p50_ms": 2.037000027485192,
+          "p95_ms": 2.5742079596966505,
+          "p99_ms": 2.768124977592379,
+          "max_ms": 2.784749958664179,
+          "rps": 480.50501087516284
+        },
+        {
+          "n_success": 100,
+          "n_failures": 0,
+          "failures": {},
+          "wall_time_s": 0.19513549999101087,
+          "mean_ms": 1.9509158097207546,
+          "p50_ms": 1.9018329912796617,
+          "p95_ms": 2.284207963384688,
+          "p99_ms": 2.4481670116074383,
+          "max_ms": 2.5021659675985575,
+          "rps": 512.4644157757384
+        },
+        {
+          "n_success": 100,
+          "n_failures": 0,
+          "failures": {},
+          "wall_time_s": 0.19278304203180596,
+          "mean_ms": 1.9274150469573215,
+          "p50_ms": 1.8819589749909937,
+          "p95_ms": 2.2150420118123293,
+          "p99_ms": 2.2878749878145754,
+          "max_ms": 2.316958038136363,
+          "rps": 518.7178236532945
+        }
+      ],
+      "summary": {
+        "avg_mean_ms": 1.9863408450813342,
+        "avg_p50_ms": 1.9402639979186158,
+        "avg_p95_ms": 2.3578193116312227,
+        "avg_p99_ms": 2.5013889923381307,
+        "avg_rps": 503.8957501013986
+      },
+      "kind": "latency",
+      "backend": "sqlite",
+      "needs_runner": false
+    },
+    "search_sessions": {
+      "runs": [
+        {
+          "n_success": 100,
+          "n_failures": 0,
+          "failures": {},
+          "wall_time_s": 8.150427000015043,
+          "mean_ms": 81.50338126753923,
+          "p50_ms": 80.11816703947261,
+          "p95_ms": 90.9090840141289,
+          "p99_ms": 94.67683301772922,
+          "max_ms": 96.44366696011275,
+          "rps": 12.26929582950874
+        },
+        {
+          "n_success": 100,
+          "n_failures": 0,
+          "failures": {},
+          "wall_time_s": 8.152122708968818,
+          "mean_ms": 81.5203430026304,
+          "p50_ms": 79.57212498877198,
+          "p95_ms": 95.20591603359208,
+          "p99_ms": 98.80137501750141,
+          "max_ms": 99.93629204109311,
+          "rps": 12.266743714490682
+        },
+        {
+          "n_success": 100,
+          "n_failures": 0,
+          "failures": {},
+          "wall_time_s": 8.053999124967959,
+          "mean_ms": 80.53909589187242,
+          "p50_ms": 79.52124997973442,
+          "p95_ms": 91.39445802429691,
+          "p99_ms": 93.2748339837417,
+          "max_ms": 94.79766699951142,
+          "rps": 12.416192061654566
+        }
+      ],
+      "summary": {
+        "avg_mean_ms": 81.18760672068068,
+        "avg_p50_ms": 79.73718066932634,
+        "avg_p95_ms": 92.50315269067262,
+        "avg_p99_ms": 95.58434733965744,
+        "avg_rps": 12.317410535217997
+      },
+      "kind": "latency",
+      "backend": "sqlite",
+      "needs_runner": false
+    }
+  }
+}

dev/benchmarks/omnigent/schema.py

@@ -0,0 +1,89 @@
+"""Benchmark report schema + metadata capture.
+
+:func:`build_report` assembles the single JSON document the harness writes.
+Its per-journey ``summary`` + ``runs`` shape mirrors MLflow's gateway
+benchmark so the workspace ETL notebook flattens it unchanged — keyed by
+journey (and ``harness``) instead of ``backend``. Bump :data:`SCHEMA_VERSION`
+whenever the document's shape changes so the ETL can branch on it.
+"""
+
+from __future__ import annotations
+
+import platform
+import subprocess
+
+# Incremented on any breaking change to the report document shape below.
+SCHEMA_VERSION = 2
+
+
+def _git(*args: str) -> str:
+    """Run ``git *args`` at the repo root, returning stripped stdout or ``""``.
+
+    Never raises: a missing git, detached checkout, or non-zero exit all
+    surface as an empty string so a benchmark run outside a clean checkout
+    still produces a valid report.
+    """
+    try:
+        out = subprocess.run(
+            ["git", *args],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    return out.stdout.strip() if out.returncode == 0 else ""
+
+
+def git_sha() -> str:
+    """Return the current commit SHA, or ``""`` when unavailable."""
+    return _git("rev-parse", "HEAD")
+
+
+def git_branch() -> str:
+    """Return the current branch name, or ``""`` when detached/unavailable."""
+    return _git("rev-parse", "--abbrev-ref", "HEAD")
+
+
+def host_info() -> dict[str, object]:
+    """Capture coarse host facts for cross-machine result comparison."""
+    import os
+
+    return {
+        "platform": platform.platform(),
+        "python": platform.python_version(),
+        "cpu_count": os.cpu_count(),
+    }
+
+
+def build_report(
+    journey_results: dict[str, dict[str, object]],
+    *,
+    generated_at: str,
+    config: dict[str, object],
+    harness: str,
+) -> dict[str, object]:
+    """Assemble the full benchmark report document.
+
+    :param journey_results: Per-journey ``{"kind", "runs", "summary"}``
+        blocks (each ``runs``/``summary`` produced by
+        :func:`measure.aggregate`), keyed by journey name.
+    :param generated_at: ISO-8601 timestamp stamped by the caller (kept out
+        of this pure function so it stays deterministic under test).
+    :param config: The run's knobs (iterations, requests, concurrency, runs,
+        mock_llm) for provenance.
+    :param harness: Harness driving full-turn journeys, e.g.
+        ``"openai-agents"``.
+    :returns: The JSON-serializable report document.
+    """
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "generated_at": generated_at,
+        "git_sha": git_sha(),
+        "git_branch": git_branch(),
+        "host": host_info(),
+        "harness": harness,
+        "config": config,
+        "journeys": journey_results,
+    }

dev/benchmarks/omnigent/seed.py

@@ -0,0 +1,228 @@
+"""Deterministic corpus seeder for the performance benchmark.
+
+The v1 harness booted an empty DB, so the read journeys measured a best-case
+near-empty table. This seeds a sizeable, realistic corpus directly through the
+store API (no HTTP, no runner) so ``list_sessions`` / ``get_session`` /
+``load_conversation_history`` read a production-shaped volume.
+
+Writes to the same DB URI the server later boots against; startup migrations
+are an idempotent no-op on an at-head DB. The seed is deterministic (fixed RNG,
+fixed counts) so the same config always yields the same corpus — which is what
+makes "seed once, reuse" sound. The reuse marker records the Alembic head read
+at seed time, so a corpus from an older schema is auto-reseeded (no manual
+revision bookkeeping).
+
+Listable-corpus recipe, per session (the permission grant is the gotcha — the
+loopback server resolves every request to user ``"local"`` and
+``list_sessions`` filters by it):
+
+1. ``create_session_with_agent`` — conversation + session-scoped agent row.
+2. ``permission_store.grant("local", sid, LEVEL_OWNER)`` — makes it listable.
+3. one batched ``append(sid, items)`` — user-role message items.
+
+Run standalone::
+
+    uv run --no-sync dev/benchmarks/omnigent/seed.py \
+        --database-uri sqlite:///tmp/bench.db --sessions 5000 --items-per-session 50
+"""
+
+from __future__ import annotations
+
+import argparse
+import random
+import sys
+from pathlib import Path
+
+# Allow ``uv run <path>`` (no package context) to import omnigent + siblings.
+sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
+
+from omnigent.db.utils import _get_head_db_revision, generate_agent_id
+from omnigent.entities import MessageData, NewConversationItem
+from omnigent.server.auth import LEVEL_OWNER, RESERVED_USER_LOCAL
+from omnigent.stores.conversation_store.sqlalchemy_store import SqlAlchemyConversationStore
+from omnigent.stores.permission_store.sqlalchemy_store import SqlAlchemyPermissionStore
+
+# Label key stamped on the first seeded session recording the corpus config, so
+# a later run can detect an existing (and matching) seed and skip re-seeding.
+_SEED_META_LABEL = "omni_bench_seed"
+
+# Fixed identifiers so the corpus is byte-stable across runs at a given config.
+_AGENT_NAME = "bench-agent"
+_DEFAULT_SESSIONS = 5000
+_DEFAULT_ITEMS = 50
+_DEFAULT_RNG_SEED = 1234
+
+# A pool of realistic-ish message fragments; the RNG assembles item text from
+# these so search_text has lexical variety without external data.
+_FRAGMENTS = (
+    "investigate the failing migration",
+    "the runner keeps disconnecting under load",
+    "add pagination to the sessions endpoint",
+    "why does the policy classifier time out",
+    "refactor the conversation store append path",
+    "benchmark the list endpoints against postgres",
+    "the web UI drops the last streamed token",
+    "trace the tunnel handshake for this runner id",
+    "summarize the changes in this pull request",
+    "reproduce the elicitation race on reconnect",
+)
+
+
+def _meta_value(sessions: int, items_per_session: int, rng_seed: int, head: str) -> str:
+    """Serialize the corpus config into the seed-marker label value.
+
+    Includes the Alembic *head* read at seed time, so a corpus seeded under an
+    older schema auto-mismatches the current head and is reseeded — no
+    hand-maintained revision constant.
+    """
+    return f"sessions={sessions};items={items_per_session};rng={rng_seed};rev={head}"
+
+
+def _existing_seed_meta(conv: SqlAlchemyConversationStore) -> str | None:
+    """Return the seed-marker label value if a bench corpus already exists.
+
+    Looks up the most recent ``bench-agent`` session and reads its
+    ``omni_bench_seed`` label. ``None`` means no (recognizable) seed present.
+    """
+    listing = conv.list_conversations(limit=1, agent_name=_AGENT_NAME)
+    if not listing.data:
+        return None
+    marked = conv.get_conversation(listing.data[0].id)
+    return marked.labels.get(_SEED_META_LABEL) if marked is not None else None
+
+
+def _make_items(rng: random.Random, count: int) -> list[NewConversationItem]:
+    """Build *count* deterministic user-role message items.
+
+    User-role only: assistant messages require an ``agent`` field the store
+    only assigns after a real turn, and the seeded read path is role-agnostic.
+    """
+    items: list[NewConversationItem] = []
+    for i in range(count):
+        text = f"{rng.choice(_FRAGMENTS)} (item {i})"
+        items.append(
+            NewConversationItem(
+                type="message",
+                response_id=f"resp_seed_{i}",
+                data=MessageData(role="user", content=[{"type": "input_text", "text": text}]),
+            )
+        )
+    return items
+
+
+def seed(
+    db_uri: str,
+    *,
+    sessions: int = _DEFAULT_SESSIONS,
+    items_per_session: int = _DEFAULT_ITEMS,
+    rng_seed: int = _DEFAULT_RNG_SEED,
+    reseed: bool = False,
+) -> int:
+    """Seed *sessions* sessions × *items_per_session* items into *db_uri*.
+
+    Idempotent: if a matching seed already exists (same config + schema
+    revision) it is left untouched unless *reseed* is set. Constructing the
+    store runs migrations to head on first init, so *db_uri* need not
+    pre-exist.
+
+    :param db_uri: SQLAlchemy URI the server will also boot against, e.g.
+        ``"sqlite:///abs/bench.db"`` or ``"postgresql+psycopg://…"``.
+    :param sessions: Number of listable sessions to create.
+    :param items_per_session: Conversation items appended to each session.
+    :param rng_seed: Seed for the deterministic text RNG.
+    :param reseed: Seed even when a matching corpus is already present.
+    :returns: The number of sessions created (0 when a matching seed is reused).
+    """
+    conv = SqlAlchemyConversationStore(db_uri)
+    perms = SqlAlchemyPermissionStore(db_uri)
+
+    # Read the current schema head at runtime (no DB contacted) and fold it into
+    # the reuse marker, so a corpus from an older schema is auto-reseeded.
+    head = _get_head_db_revision("sqlite:///:memory:")
+    want = _meta_value(sessions, items_per_session, rng_seed, head)
+    if not reseed:
+        existing = _existing_seed_meta(conv)
+        if existing == want:
+            print(f"seed: matching corpus already present ({want}); skipping")
+            return 0
+        if existing is not None:
+            print(f"seed: existing corpus differs ({existing!r} != {want!r}); pass --reseed")
+            return 0
+
+    perms.ensure_user(RESERVED_USER_LOCAL)
+    rng = random.Random(rng_seed)
+
+    last_sid = ""
+    for s in range(sessions):
+        created = conv.create_session_with_agent(
+            agent_id=generate_agent_id(),
+            agent_name=_AGENT_NAME,
+            agent_bundle_location="bench/seed",  # never validated on the read path
+            agent_description=None,
+            title=f"bench session {s}: {rng.choice(_FRAGMENTS)}",
+        )
+        sid = created.conversation.id
+        last_sid = sid
+        perms.grant(RESERVED_USER_LOCAL, sid, LEVEL_OWNER)
+        if items_per_session:
+            conv.append(sid, _make_items(rng, items_per_session))
+        if sessions >= 100 and s % (sessions // 10) == 0 and s:
+            print(f"seed: {s}/{sessions} sessions")
+
+    # Stamp the corpus config on the LAST (newest) session — that's the one
+    # ``_existing_seed_meta``'s default desc listing returns, so the reuse
+    # check finds it regardless of corpus size.
+    if last_sid:
+        conv.set_labels(last_sid, {_SEED_META_LABEL: want})
+
+    print(f"seed: created {sessions} sessions × {items_per_session} items ({want})")
+    return sessions
+
+
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="omnigent-benchmark-seed",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--database-uri",
+        metavar="URI",
+        help="DB to seed. Required unless --print-head.",
+    )
+    parser.add_argument("--sessions", type=int, default=_DEFAULT_SESSIONS, metavar="N")
+    parser.add_argument("--items-per-session", type=int, default=_DEFAULT_ITEMS, metavar="N")
+    parser.add_argument("--rng-seed", type=int, default=_DEFAULT_RNG_SEED, metavar="N")
+    parser.add_argument(
+        "--reseed",
+        action="store_true",
+        help="Seed even if a matching corpus is already present.",
+    )
+    parser.add_argument(
+        "--print-head",
+        action="store_true",
+        help="Print the repo's Alembic head revision and exit (drift-check helper).",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv if argv is not None else sys.argv[1:])
+    if args.print_head:
+        print(_get_head_db_revision("sqlite:///:memory:"))
+        return 0
+    if not args.database_uri:
+        print("seed: --database-uri is required (unless --print-head)", file=sys.stderr)
+        return 2
+    seed(
+        args.database_uri,
+        sessions=args.sessions,
+        items_per_session=args.items_per_session,
+        rng_seed=args.rng_seed,
+        reseed=args.reseed,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dev/omnidev/Cargo.lock

@@ -2,6 +2,15 @@
 # It is not intended for manual editing.
 version = 4
 
+[[package]]
+name = "aho-corasick"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
+dependencies = [
+ "memchr",
+]
+
 [[package]]
 name = "allocator-api2"
 version = "0.2.21"
@@ -83,6 +92,16 @@ version = "2.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
 
+[[package]]
+name = "bstr"
+version = "1.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5cee35f73844aa3014bb606320a6c1f010249dbdf43342fe54b5a4f6a8ed4b79"
+dependencies = [
+ "memchr",
+ "serde_core",
+]
+
 [[package]]
 name = "bytes"
 version = "1.12.0"
@@ -170,6 +189,31 @@ dependencies = [
  "static_assertions",
 ]
 
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5181e0de7b61eb03a81e347d6dd8797bae9da5146707b51077e2d71a54ec0ceb"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d6914041f254d6e9176c01941b21115dcfb7089e55135a35411081bd106ef3f"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61803da095bee82a81bb1a452ecc25d3b2f1416d1897eb86430c6159ef717c17"
+
 [[package]]
 name = "crossterm"
 version = "0.28.1"
@@ -275,6 +319,19 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "globset"
+version = "0.4.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52dfc19153a48bde0cbd630453615c8151bce3a5adfac7a0aebfbf0a1e1f57e3"
+dependencies = [
+ "aho-corasick",
+ "bstr",
+ "log",
+ "regex-automata",
+ "regex-syntax",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.15.5"
@@ -304,6 +361,32 @@ version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39"
 
+[[package]]
+name = "if-addrs"
+version = "0.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c0a05c691e1fae256cf7013d99dad472dc52d5543322761f83ec8d47eab40d2b"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "ignore"
+version = "0.4.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fe112b004901c62c2faa11f4f75e9864e0cc5af8da71c9115d184a3aa888749f"
+dependencies = [
+ "crossbeam-deque",
+ "globset",
+ "log",
+ "memchr",
+ "regex-automata",
+ "same-file",
+ "walkdir",
+ "winapi-util",
+]
+
 [[package]]
 name = "indexmap"
 version = "2.14.0"
@@ -515,13 +598,17 @@ dependencies = [
  "anyhow",
  "clap",
  "crossterm",
+ "if-addrs",
+ "ignore",
  "libc",
  "notify",
  "notify-debouncer-full",
  "ratatui",
  "serde",
+ "serde_json",
  "tokio",
  "toml",
+ "unicode-width 0.2.0",
 ]
 
 [[package]]
@@ -613,6 +700,23 @@ dependencies = [
  "bitflags",
 ]
 
+[[package]]
+name = "regex-automata"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
 [[package]]
 name = "rustix"
 version = "0.38.44"
@@ -683,6 +787,19 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "serde_json"
+version = "1.0.150"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
 [[package]]
 name = "serde_spanned"
 version = "0.6.9"
@@ -742,7 +859,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "52d1cfed4120b4d927bf7c0f86d2087a4a7d6027c906d9f9d525a80573b9be51"
 dependencies = [
  "libc",
- "windows-sys 0.60.2",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -1136,3 +1253,9 @@ checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
 dependencies = [
  "memchr",
 ]
+
+[[package]]
+name = "zmij"
+version = "1.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"

dev/omnidev/Cargo.toml

@@ -15,10 +15,13 @@ clap = { version = "4", features = ["derive"] }
 crossterm = "0.28"
 ratatui = "0.29"
 ansi-to-tui = "7"
+unicode-width = "0.2"
 notify = "8"
 notify-debouncer-full = "0.5"
+ignore = "0.4"
 libc = "0.2"
 serde = { version = "1", features = ["derive"] }
+serde_json = "1"
 toml = "0.8"
 tokio = { version = "1", features = [
     "rt-multi-thread",
@@ -30,3 +33,4 @@ tokio = { version = "1", features = [
     "sync",
     "signal",
 ] }
+if-addrs = "0.15"

dev/omnidev/README.md

@@ -1,8 +1,18 @@
 # omnidev
 
-A per-repo dev **pod** supervisor for the Omnigent repo, as a single
-long-running terminal UI. It replaces the three-terminal local dev flow
-(`omnigent server`, `omnigent host`, `npm run dev`) with one process that:
+Dev tooling for Omnigent, in one binary with two independent capabilities:
+
+1. A per-repo dev **pod supervisor** (bare `omnidev`) — the default.
+2. **Install management** (`omnidev install`/`update`/`check`) — install and
+   keep a git-based omnigent up to date. See
+   [Managing your omnigent install](#managing-your-omnigent-install). These
+   subcommands need no checkout and run anywhere.
+
+## Pod supervisor
+
+A per-repo dev **pod** supervisor, as a single long-running terminal UI. It
+replaces the three-terminal local dev flow (`omnigent server`, `omnigent host`,
+`npm run dev`) with one process that:
 
 - runs each checkout in an **isolated pod** — its own state dir, database,
   artifacts, logs, and auto-allocated ports — so multiple worktrees never
@@ -10,8 +20,11 @@ long-running terminal UI. It replaces the three-terminal local dev flow
 - **supervises** the backend server, the host daemon, and the Vite frontend,
   restarting any that crash (with backoff);
 - **reloads the backend** (server → host) when you edit `omnigent/**/*.py`;
-  the frontend self-reloads through Vite HMR;
-- gives you **scrollable per-process log panes** plus a combined view.
+  gitignored files under `omnigent/` (e.g. the build-time `_build_info.py`) are
+  skipped so generated churn doesn't reload; the frontend self-reloads through
+  Vite HMR;
+- gives you **per-process log panes** plus a combined view, each a `less`-style
+  pager with wrap and search (see [Keys](#keys)).
 
 ## Build & run
 
@@ -32,18 +45,33 @@ Run it from anywhere inside the checkout — it walks up to the repo root
 
 | Process | Command | Notes |
 |---|---|---|
-| server | `uv run omnigent server --host 127.0.0.1 --port <p> --database-uri … --artifact-location …` | Waited on via `GET /health`. |
-| host   | `uv run omnigent host --server http://127.0.0.1:<p>` | Started once the server is healthy. |
-| vite   | `npm run dev -- --port <p> --strictPort` (cwd `web/`) | `OMNIGENT_URL` points its proxy at the pod's server. |
+| server | `uv run omnigent --log-to-stderr server --host 127.0.0.1 --port <p> --database-uri … --artifact-location …` | Waited on via `GET /health`. |
+| host   | `uv run omnigent --log-to-stderr host --server http://127.0.0.1:<p>` | Started once the server is healthy. |
+| vite   | `npm run dev -- --host <host> --port <p> --strictPort` (cwd `web/`) | `OMNIGENT_URL` points its proxy at the pod's server. |
+
+Before Vite starts (and on a manual Vite restart), omnidev runs `npm install`
+in `web/` when needed — `node_modules/` is missing, or `package.json` /
+`package-lock.json` is newer than it — so a fresh checkout or a new dependency
+doesn't make Vite fail its dependency scan. Output streams into the `vite` pane.
 
 Open the UI at the `ui` URL shown in the header (the Vite dev server).
 
 ## Isolation
 
-All Omnigent state is redirected into the pod dir via environment variables —
-the same pattern `scripts/backend-smoke.sh` uses:
-`HOME`, `TMPDIR`, `XDG_*`, `OMNIGENT_CONFIG_HOME`, `OMNIGENT_DATA_DIR`,
-`OMNIGENT_DATABASE_URI`, and `OMNIGENT_URL`.
+Only Omnigent's own state is isolated per pod — enough that concurrent pods
+never share a database, server pidfile, or `config.yaml` — via
+`OMNIGENT_DATA_DIR`, `OMNIGENT_DATABASE_URI`, `OMNIGENT_URL`, and
+`OMNIGENT_CONFIG_HOME`. Everything else (your real `HOME`, credentials, and
+uv/npm caches) is inherited, because the agents Omnigent runs need it. This is
+deliberately lighter than the hermetic `scripts/backend-smoke.sh` sandbox,
+which repoints `HOME`/`XDG_*` to touch nothing real.
+
+Each pod gets its own `config.yaml` under `<pod>/config/`, pointed to by
+`OMNIGENT_CONFIG_HOME`. On first create it's **seeded** from your real
+`~/.omnigent/config.yaml` (if present) so the pod works out of the box — it
+keeps your providers — after which the two are independent: server-config edits
+inside a pod (via the UI or `omnigent config`) don't touch your real config.
+`--clean` wipes the pod dir, so the next run re-seeds from your real config.
 
 The pod dir defaults to
 `${XDG_CACHE_HOME:-~/.cache}/omnidev/<repo-name>-<hash>/`, keyed to the
@@ -55,20 +83,108 @@ canonical checkout path. Per-process logs are written through to
 ```
 --server-port <N>   Force the backend port (default: probe from 6767)
 --vite-port <N>     Force the Vite port (default: probe from 5173)
+--vite-host <ADDR>  Vite bind host (default: 127.0.0.1; use 0.0.0.0 for LAN access)
+--trust-lan-origins Trust this machine's LAN origins (for device testing)
 --pod-dir <PATH>    Use a specific pod dir instead of the per-repo default
 --no-vite           Backend + host only (no frontend)
 --clean             Wipe the pod dir before starting
+--debug             Log each watched file change and whether it reloads
 ```
 
+`--vite-host 0.0.0.0` exposes the Vite dev server on all interfaces for device
+testing. Vite still proxies API traffic to the pod backend through `127.0.0.1`.
+
+### Testing from a phone or tablet
+
+`--vite-host 0.0.0.0` alone lets a device load the UI, but the backend runs in
+single-user local mode, where its CSRF/CSWSH guard trusts only loopback
+origins. A device loads the UI at `http://<your-lan-ip>:<vite-port>`, so its
+browser stamps that non-loopback origin on every request — and the guard then
+rejects multipart uploads (403) and refuses the live WebSocket stream.
+
+`--trust-lan-origins` fixes that: omnidev enumerates this machine's LAN IPv4
+addresses and trusts the matching `http://<ip>:<vite-port>` origins via the
+server's `OMNIGENT_WS_ALLOWED_ORIGINS` allowlist (merged with any value you
+already export). It stays exact-match — only those origins are trusted, nothing
+is disabled — so it's for dev pods, not deployed servers. The trusted origins
+are printed in the combined log at startup.
+
+```bash
+omnidev --vite-host 0.0.0.0 --trust-lan-origins
+```
+
+This covers IPv4 LAN addresses; mDNS `.local` hostnames and HTTPS origins are
+not auto-trusted (add those to `OMNIGENT_WS_ALLOWED_ORIGINS` yourself).
+
 ## Keys
 
+The log pane is a `less`-style pager, so the movement and search keys should
+feel familiar.
+
 | Key | Action |
 |---|---|
 | `1` / `2` / `3` / `0` | Focus server / host / vite / combined pane |
 | `Tab` | Cycle panes |
-| `↑` `↓` `PgUp` `PgDn` | Scroll (detaches from tail) |
-| `f` | Toggle follow-tail |
+| `j` / `k` (or `↓` / `↑`) | Scroll one line |
+| `f` / `Space` / `PgDn` (or `b` / `PgUp`) | Page forward / back one window |
+| `d` / `u` | Half-page forward / back |
+| `g` / `G` | Jump to top / bottom (bottom re-follows the tail) |
+| `F` | Toggle follow-tail (like `less +F`) |
+| `w` | Toggle line wrap (on by default) |
+| `/` `?` | Search forward / back — type, `Enter` to jump, `Esc` to cancel |
+| `n` / `N` | Next / previous match |
 | `r` | Restart the focused process (server/host restart as a pair) |
 | `R` | Restart the backend (server then host) |
 | `c` | Clear the focused pane |
 | `q` / `Ctrl-C` | Quit and tear down all processes |
+
+## Managing your omnigent install
+
+For people who *run* omnigent (installed from git via `uv tool install`) rather
+than develop it. This wraps the fiddly PEP 508 install syntax and adds a daily
+update check — filling a gap, since omnigent's own update notice only works for
+PyPI-wheel installs and skips git installs.
+
+These subcommands manage the global tool and work from **any directory** (no
+checkout needed).
+
+```
+omnidev install     # uv tool install omnigent from git (databricks extra, main)
+omnidev update      # reinstall the latest of the tracked ref/extras
+omnidev check       # check for an update; prompt to update on a TTY
+omnidev refresh     # refresh the check cache from the network (usually detached)
+omnidev shell-hook  # print the daily-check snippet for your shell rc
+```
+
+`install` options: `--ref <branch/tag/sha>` (default `main`), `--extra <name>`
+(repeatable; defaults to `databricks`), `--no-default-extra` (install with no
+extras), `--repo <url>`. The choice is saved to
+`${XDG_CONFIG_HOME:-~/.config}/omnidev/install.toml` so `update` reuses it.
+
+Installing from git **builds the web UI from source**, so Node 22+/npm must be
+on PATH (the PyPI wheel ships the UI prebuilt; the git install does not).
+`omnidev install` fails early with a clear message if `uv` or `npm` is missing.
+
+### Daily update check
+
+Append the hook to your shell rc once to be told, at most once a day, when a
+newer `main` commit is available — and be offered to update on the spot:
+
+```bash
+omnidev shell-hook >> ~/.zshrc     # or ~/.bashrc
+```
+
+The snippet itself guards on `command -v omnidev`, so it's a no-op in shells
+where omnidev isn't on PATH — nothing to fail. (Appending the snippet is
+preferred over `eval "$(omnidev shell-hook)"`: the latter would run omnidev on
+every shell startup and print a "command not found" error whenever omnidev is
+absent.)
+
+On each interactive shell it runs `omnidev check --quiet`, which reads a cached
+result (`${XDG_CACHE_HOME:-~/.cache}/omnidev/omnigent-check.json`) and, when
+stale (>24h), refreshes it in a detached background process — so shell startup
+never blocks on the network. When a newer commit is available it prints a notice
+and, on a terminal, prompts `Update omnigent now? [y/N]`; on yes it runs
+`omnidev update` in the foreground. Declining suppresses that same commit until a
+newer one lands. Set `OMNIGENT_NO_UPDATE_CHECK` in your environment if you want
+to silence omnigent's own separate notice.

dev/omnidev/src/install.rs

@@ -0,0 +1,209 @@
+//! Manage the user's git-based omnigent installation via `uv tool install`.
+//!
+//! None of this needs a local checkout: it drives `uv` and reads the installed
+//! tool's metadata, and any git call targets the remote.
+
+use std::path::PathBuf;
+use std::process::Command;
+
+use anyhow::{bail, Context, Result};
+use serde::{Deserialize, Serialize};
+
+use crate::paths;
+
+pub const DEFAULT_REPO: &str = "https://github.com/omnigent-ai/omnigent.git";
+pub const DEFAULT_REF: &str = "main";
+pub const DEFAULT_EXTRA: &str = "databricks";
+const PYTHON_VERSION: &str = "3.12";
+
+/// Durable record of how the user wants omnigent installed. Persisted so
+/// `update` reinstalls the same repo/ref/extras without re-specifying them.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct InstallConfig {
+    pub repo: String,
+    #[serde(rename = "ref")]
+    pub git_ref: String,
+    pub extras: Vec<String>,
+}
+
+impl Default for InstallConfig {
+    fn default() -> Self {
+        InstallConfig {
+            repo: DEFAULT_REPO.to_string(),
+            git_ref: DEFAULT_REF.to_string(),
+            extras: vec![DEFAULT_EXTRA.to_string()],
+        }
+    }
+}
+
+impl InstallConfig {
+    pub fn load() -> Result<Option<InstallConfig>> {
+        let path = paths::install_config_path()?;
+        match std::fs::read_to_string(&path) {
+            Ok(text) => Ok(Some(
+                toml::from_str(&text).with_context(|| format!("parsing {}", path.display()))?,
+            )),
+            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
+            Err(e) => Err(e).with_context(|| format!("reading {}", path.display())),
+        }
+    }
+
+    pub fn save(&self) -> Result<()> {
+        let path = paths::install_config_path()?;
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent)
+                .with_context(|| format!("creating {}", parent.display()))?;
+        }
+        let text = toml::to_string(self).context("serializing install config")?;
+        std::fs::write(&path, text).with_context(|| format!("writing {}", path.display()))?;
+        Ok(())
+    }
+
+    /// The PEP 508 install spec, e.g.
+    /// `omnigent[databricks] @ git+https://github.com/omnigent-ai/omnigent.git@main`.
+    /// With no extras it collapses to the bare `git+<repo>@<ref>` URL.
+    pub fn spec(&self) -> String {
+        let source = format!("git+{}@{}", self.repo, self.git_ref);
+        if self.extras.is_empty() {
+            source
+        } else {
+            format!("omnigent[{}] @ {}", self.extras.join(","), source)
+        }
+    }
+}
+
+/// Fail early with a clear message if the toolchain a git install needs is
+/// missing. Installing from git builds the web UI from source (Node/npm),
+/// unlike the PyPI wheel which ships it prebuilt.
+fn preflight() -> Result<()> {
+    if which("uv").is_none() {
+        bail!("`uv` is not on PATH. Install it first: https://docs.astral.sh/uv/");
+    }
+    if which("npm").is_none() {
+        bail!(
+            "`npm` is not on PATH. Installing omnigent from git builds the web UI \
+             from source and needs Node 22+/npm. Install Node, then retry."
+        );
+    }
+    Ok(())
+}
+
+/// Install omnigent from git per `config`. `reinstall` forces uv past its cache
+/// so a moving ref (e.g. `main`) actually re-resolves.
+pub fn run_uv_install(config: &InstallConfig, reinstall: bool) -> Result<()> {
+    preflight()?;
+    let spec = config.spec();
+
+    let mut cmd = Command::new("uv");
+    cmd.args(["tool", "install", "--force", "--python", PYTHON_VERSION]);
+    if reinstall {
+        cmd.arg("--reinstall");
+    }
+    cmd.arg(&spec);
+
+    eprintln!("omnidev: uv tool install {spec}");
+    let status = cmd
+        .status()
+        .context("running `uv tool install` (is uv installed?)")?;
+    if !status.success() {
+        bail!("`uv tool install` failed ({status})");
+    }
+    Ok(())
+}
+
+/// `install` subcommand: persist intent, install, then record the resolved sha.
+pub fn install(config: &InstallConfig) -> Result<()> {
+    config.save()?;
+    run_uv_install(config, false)?;
+    record_installed_sha(config);
+    println!("omnidev: installed omnigent ({})", config.spec());
+    Ok(())
+}
+
+/// `update` subcommand: reinstall the latest of the persisted ref/extras. Falls
+/// back to defaults when no config has been written yet.
+pub fn update() -> Result<()> {
+    let config = InstallConfig::load()?.unwrap_or_default();
+    config.save()?;
+    run_uv_install(&config, true)?;
+    record_installed_sha(&config);
+    println!("omnidev: updated omnigent ({})", config.spec());
+    Ok(())
+}
+
+/// After a successful install, capture the remote sha of the tracked ref and
+/// stash it in the cache so `check` has a baseline even before the dist-info
+/// reader runs. Best-effort — failures here never fail the install.
+fn record_installed_sha(config: &InstallConfig) {
+    if let Some(sha) = crate::update_check::remote_sha(&config.repo, &config.git_ref) {
+        let _ = crate::update_check::set_installed_sha(&sha);
+    }
+}
+
+/// Read the commit the installed omnigent tool was built from, via its PEP 610
+/// `direct_url.json`. Returns `None` for a non-VCS install or when uv/metadata
+/// can't be read. Never touches the working directory.
+pub fn installed_commit() -> Option<String> {
+    let dir = uv_tool_dir()?;
+    // …/omnigent/**/omnigent-*.dist-info/direct_url.json
+    let omnigent_root = dir.join("omnigent");
+    let dist_info = find_dist_info(&omnigent_root)?;
+    let text = std::fs::read_to_string(dist_info.join("direct_url.json")).ok()?;
+    let value: serde_json::Value = serde_json::from_str(&text).ok()?;
+    value
+        .get("vcs_info")?
+        .get("commit_id")?
+        .as_str()
+        .map(str::to_string)
+}
+
+fn uv_tool_dir() -> Option<PathBuf> {
+    let output = Command::new("uv").args(["tool", "dir"]).output().ok()?;
+    if !output.status.success() {
+        return None;
+    }
+    let path = String::from_utf8(output.stdout).ok()?;
+    let trimmed = path.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(PathBuf::from(trimmed))
+    }
+}
+
+/// Find the `omnigent-*.dist-info` dir under a uv tool's environment. uv lays
+/// tools out as `<tool>/lib/pythonX.Y/site-packages/<pkg>-<ver>.dist-info`, so
+/// we walk rather than hardcode the python version.
+fn find_dist_info(root: &std::path::Path) -> Option<PathBuf> {
+    let mut stack = vec![root.to_path_buf()];
+    while let Some(dir) = stack.pop() {
+        let Ok(entries) = std::fs::read_dir(&dir) else {
+            continue;
+        };
+        for entry in entries.flatten() {
+            let path = entry.path();
+            if !path.is_dir() {
+                continue;
+            }
+            let name = entry.file_name();
+            let name = name.to_string_lossy();
+            if name.starts_with("omnigent-") && name.ends_with(".dist-info") {
+                return Some(path);
+            }
+            stack.push(path);
+        }
+    }
+    None
+}
+
+/// Locate an executable on PATH (portable `which`, no external dep).
+fn which(program: &str) -> Option<PathBuf> {
+    let path = std::env::var_os("PATH")?;
+    for dir in std::env::split_paths(&path) {
+        let candidate = dir.join(program);
+        if candidate.is_file() {
+            return Some(candidate);
+        }
+    }
+    None
+}

dev/omnidev/src/lan.rs

@@ -0,0 +1,114 @@
+//! LAN origin discovery for device testing.
+//!
+//! When Vite binds to `0.0.0.0` (`--vite-host 0.0.0.0`), a phone or tablet on
+//! the same network loads the UI at `http://<lan-ip>:<vite-port>`. Its browser
+//! stamps that non-loopback address as the `Origin` on every request. The
+//! backend runs in local single-user mode, where the origin guard
+//! (`omnigent.server.ws_origin.origin_allowed`) admits only loopback origins —
+//! so multipart uploads get a 403 and the WebSocket stream is refused.
+//!
+//! `--trust-lan-origins` closes that gap by enumerating this machine's LAN
+//! IPv4 addresses and handing the server the matching `http://<ip>:<port>`
+//! origins via `OMNIGENT_WS_ALLOWED_ORIGINS` — the server's own exact-match
+//! allowlist. It stays exact-match (no security disable): only the origins we
+//! name are trusted.
+
+use std::net::Ipv4Addr;
+
+/// Whether an IPv4 address is a usable LAN address to trust as an origin.
+///
+/// Keeps private (RFC 1918) and link-local (169.254/16) addresses — the ones a
+/// device on the same network actually reaches this machine by. Drops loopback
+/// (already trusted), unspecified (`0.0.0.0`), broadcast, documentation, and
+/// multicast, none of which a real device browses to.
+fn is_lan_ipv4(ip: &Ipv4Addr) -> bool {
+    (ip.is_private() || ip.is_link_local())
+        && !ip.is_loopback()
+        && !ip.is_unspecified()
+        && !ip.is_broadcast()
+        && !ip.is_multicast()
+}
+
+/// Build the `http://<ip>:<port>` origins to trust for a given set of LAN
+/// IPv4 addresses.
+///
+/// Split out from interface enumeration so the origin-shaping (which is all we
+/// assert on) is testable without touching the host's real interfaces. The
+/// input is deduplicated and the output is sorted for a stable env value.
+fn origins_for_ips(ips: impl IntoIterator<Item = Ipv4Addr>, vite_port: u16) -> Vec<String> {
+    let mut origins: Vec<String> = ips
+        .into_iter()
+        .filter(is_lan_ipv4)
+        .map(|ip| format!("http://{ip}:{vite_port}"))
+        .collect();
+    origins.sort();
+    origins.dedup();
+    origins
+}
+
+/// Discover the `http://<lan-ip>:<vite-port>` origins for this machine's LAN
+/// interfaces.
+///
+/// Returns an empty vector when no LAN interface is found (e.g. offline) — the
+/// caller then simply trusts nothing extra rather than failing. Interface
+/// enumeration errors are treated the same way: LAN trust is a convenience, so
+/// a lookup failure must not block the pod from starting.
+pub fn trusted_lan_origins(vite_port: u16) -> Vec<String> {
+    let ips = match if_addrs::get_if_addrs() {
+        Ok(ifaces) => ifaces
+            .into_iter()
+            .filter_map(|iface| match iface.addr.ip() {
+                std::net::IpAddr::V4(v4) => Some(v4),
+                std::net::IpAddr::V6(_) => None,
+            }),
+        Err(_) => return Vec::new(),
+    };
+    origins_for_ips(ips, vite_port)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn keeps_private_and_link_local_drops_loopback_and_public() {
+        assert!(is_lan_ipv4(&Ipv4Addr::new(192, 168, 1, 42)));
+        assert!(is_lan_ipv4(&Ipv4Addr::new(10, 0, 0, 5)));
+        assert!(is_lan_ipv4(&Ipv4Addr::new(172, 16, 3, 9)));
+        assert!(is_lan_ipv4(&Ipv4Addr::new(169, 254, 10, 1)));
+
+        assert!(!is_lan_ipv4(&Ipv4Addr::new(127, 0, 0, 1)));
+        assert!(!is_lan_ipv4(&Ipv4Addr::new(0, 0, 0, 0)));
+        assert!(!is_lan_ipv4(&Ipv4Addr::new(8, 8, 8, 8)));
+        assert!(!is_lan_ipv4(&Ipv4Addr::new(255, 255, 255, 255)));
+    }
+
+    #[test]
+    fn builds_http_origins_with_the_vite_port() {
+        let origins = origins_for_ips([Ipv4Addr::new(192, 168, 1, 42)], 5173);
+        assert_eq!(origins, vec!["http://192.168.1.42:5173"]);
+    }
+
+    #[test]
+    fn filters_and_sorts_and_dedups() {
+        let origins = origins_for_ips(
+            [
+                Ipv4Addr::new(10, 0, 0, 9),
+                Ipv4Addr::new(127, 0, 0, 1), // loopback dropped
+                Ipv4Addr::new(8, 8, 8, 8),   // public dropped
+                Ipv4Addr::new(192, 168, 1, 5),
+                Ipv4Addr::new(10, 0, 0, 9), // duplicate collapsed
+            ],
+            8080,
+        );
+        assert_eq!(
+            origins,
+            vec!["http://10.0.0.9:8080", "http://192.168.1.5:8080"]
+        );
+    }
+
+    #[test]
+    fn no_lan_interfaces_yields_no_origins() {
+        assert!(origins_for_ips([Ipv4Addr::new(127, 0, 0, 1)], 5173).is_empty());
+    }
+}

dev/omnidev/src/main.rs

@@ -1,38 +1,54 @@
-//! omnidev — a per-repo dev pod supervisor TUI for the Omnigent repo.
+//! omnidev — dev tooling for Omnigent.
 //!
-//! Manages one isolated dev instance (its own state dir + ports) and its three
-//! processes (server, host, vite), restarting the backend on Python changes
-//! while Vite handles frontend HMR itself.
+//! Two independent capabilities in one binary:
+//! - **pod supervisor** (bare `omnidev`): manages an isolated dev instance for
+//!   the current checkout — server/host/vite, restarting the backend on Python
+//!   changes while Vite handles frontend HMR.
+//! - **install management** (`omnidev install`/`update`/`check`/…): install and
+//!   keep a git-based omnigent up to date. These need no checkout and run
+//!   anywhere.
 
+mod install;
+mod lan;
 mod lock;
 mod logs;
 mod paths;
 mod pod;
 mod ports;
 mod process;
+mod shellhook;
 mod state;
 mod supervisor;
 mod tui;
+mod update_check;
 mod watcher;
 
 use std::path::PathBuf;
 use std::sync::Arc;
 
 use anyhow::Result;
-use clap::Parser;
+use clap::{Parser, Subcommand};
 use tokio::sync::mpsc;
 
+use install::InstallConfig;
 use pod::Pod;
 use ports::Ports;
 use state::Shared;
 use supervisor::{Cmd, Supervisor};
 
 #[derive(Parser, Debug)]
-#[command(
-    name = "omnidev",
-    about = "Isolated dev pod supervisor for the Omnigent repo"
-)]
+#[command(name = "omnidev", about = "Dev tooling for Omnigent", version)]
 struct Args {
+    #[command(subcommand)]
+    command: Option<Command>,
+
+    #[command(flatten)]
+    run: RunArgs,
+}
+
+/// Flags for the default (no-subcommand) pod-supervisor run.
+#[derive(clap::Args, Debug)]
+struct RunArgs {
     /// Force the backend server port (default: probe from 6767).
     #[arg(long)]
     server_port: Option<u16>,
@@ -41,6 +57,15 @@ struct Args {
     #[arg(long)]
     vite_port: Option<u16>,
 
+    /// Vite dev-server bind host (default: 127.0.0.1; use 0.0.0.0 for LAN access).
+    #[arg(long, default_value = "127.0.0.1")]
+    vite_host: String,
+
+    /// Trust this machine's LAN origins so a phone/tablet on the same network
+    /// can use the UI (uploads + live stream). Pairs with `--vite-host 0.0.0.0`.
+    #[arg(long)]
+    trust_lan_origins: bool,
+
     /// Use this pod directory instead of the per-repo default.
     #[arg(long)]
     pod_dir: Option<PathBuf>,
@@ -52,12 +77,85 @@ struct Args {
     /// Wipe the pod directory before starting.
     #[arg(long)]
     clean: bool,
+
+    /// Log every observed file change and whether it triggers a backend reload
+    /// (with the skip reason otherwise).
+    #[arg(long)]
+    debug: bool,
 }
 
-#[tokio::main]
-async fn main() -> Result<()> {
+#[derive(Subcommand, Debug)]
+enum Command {
+    /// Install omnigent from git (defaults to the databricks extra, main).
+    Install {
+        /// Git ref (branch/tag/sha) to track.
+        #[arg(long, default_value = install::DEFAULT_REF)]
+        r#ref: String,
+        /// Extra to include (repeatable). Defaults to `databricks`.
+        #[arg(long = "extra")]
+        extras: Vec<String>,
+        /// Omit the default databricks extra (install with no extras).
+        #[arg(long)]
+        no_default_extra: bool,
+        /// Git repo URL.
+        #[arg(long, default_value = install::DEFAULT_REPO)]
+        repo: String,
+    },
+    /// Reinstall the latest of the tracked ref/extras.
+    Update,
+    /// Check for an omnigent update (the shell hook calls this).
+    Check {
+        /// Print nothing when already up to date.
+        #[arg(long)]
+        quiet: bool,
+    },
+    /// Refresh the update-check cache from the network (usually run detached).
+    Refresh,
+    /// Print a shell snippet to eval from .zshrc/.bashrc for daily checks.
+    ShellHook,
+}
+
+fn main() -> Result<()> {
     let args = Args::parse();
 
+    // Install-management subcommands manage a global tool and must work from
+    // anywhere — dispatch them before any checkout discovery.
+    match args.command {
+        Some(Command::Install {
+            r#ref,
+            extras,
+            no_default_extra,
+            repo,
+        }) => {
+            let extras = if !extras.is_empty() {
+                extras
+            } else if no_default_extra {
+                vec![]
+            } else {
+                vec![install::DEFAULT_EXTRA.to_string()]
+            };
+            let config = InstallConfig {
+                repo,
+                git_ref: r#ref,
+                extras,
+            };
+            install::install(&config)
+        }
+        Some(Command::Update) => install::update(),
+        Some(Command::Check { quiet }) => update_check::check(quiet),
+        Some(Command::Refresh) => update_check::refresh(),
+        Some(Command::ShellHook) => {
+            shellhook::print();
+            Ok(())
+        }
+        None => run_supervisor(args.run),
+    }
+}
+
+/// Default path: the pod supervisor for the current checkout. This is the only
+/// path that requires an Omnigent checkout.
+#[tokio::main]
+async fn run_supervisor(args: RunArgs) -> Result<()> {
     let cwd = std::env::current_dir()?;
     let repo_root = paths::find_repo_root(&cwd)?;
     let pod_dir = match &args.pod_dir {
@@ -75,17 +173,41 @@ async fn main() -> Result<()> {
     let _lock = lock::acquire(&pod_dir)?;
 
     let ports = Ports::resolve(&pod_dir, args.server_port, args.vite_port)?;
-    let pod = Arc::new(Pod::create(repo_root, pod_dir, ports)?);
+    // LAN origins are keyed to the resolved Vite port, so compute them here
+    // once the port is known. Empty unless `--trust-lan-origins` is set.
+    let trusted_origins = if args.trust_lan_origins {
+        lan::trusted_lan_origins(ports.vite)
+    } else {
+        Vec::new()
+    };
+    let pod = Arc::new(Pod::create(
+        repo_root,
+        pod_dir,
+        ports,
+        args.vite_host,
+        trusted_origins,
+    )?);
 
     let shared = Shared::new(&pod);
     let (cmd_tx, cmd_rx) = mpsc::unbounded_channel::<Cmd>();
 
     // File watcher: Python changes -> Reload commands. Keep the debouncer alive
     // for the whole session.
-    let _watcher = watcher::spawn(&pod.omnigent_dir(), cmd_tx.clone())?;
+    let _watcher = watcher::spawn(
+        &pod.repo_root,
+        &pod.omnigent_dir(),
+        shared.clone(),
+        args.debug,
+        cmd_tx.clone(),
+    )?;
 
     // Supervisor runs on the tokio runtime; the TUI drives it via cmd_tx.
-    let supervisor = Supervisor::new(pod.clone(), shared.clone(), !args.no_vite);
+    let supervisor = Supervisor::new(
+        pod.clone(),
+        shared.clone(),
+        !args.no_vite,
+        args.trust_lan_origins,
+    );
     let sup_handle = tokio::spawn(supervisor.run(cmd_rx));
 
     // Run the TUI (owns the terminal) until the user quits.

dev/omnidev/src/paths.rs

@@ -49,7 +49,8 @@ pub fn default_pod_dir(repo_root: &Path) -> Result<PathBuf> {
     Ok(cache.join("omnidev").join(format!("{slug}-{hash}")))
 }
 
-fn cache_home() -> Result<PathBuf> {
+/// `${XDG_CACHE_HOME:-~/.cache}`.
+pub fn cache_home() -> Result<PathBuf> {
     if let Some(x) = std::env::var_os("XDG_CACHE_HOME") {
         if !x.is_empty() {
             return Ok(PathBuf::from(x));
@@ -59,6 +60,27 @@ fn cache_home() -> Result<PathBuf> {
     Ok(PathBuf::from(home).join(".cache"))
 }
 
+/// `${XDG_CONFIG_HOME:-~/.config}`.
+pub fn config_home() -> Result<PathBuf> {
+    if let Some(x) = std::env::var_os("XDG_CONFIG_HOME") {
+        if !x.is_empty() {
+            return Ok(PathBuf::from(x));
+        }
+    }
+    let home = std::env::var_os("HOME").context("HOME is not set")?;
+    Ok(PathBuf::from(home).join(".config"))
+}
+
+/// `~/.config/omnidev/install.toml` — durable record of install intent.
+pub fn install_config_path() -> Result<PathBuf> {
+    Ok(config_home()?.join("omnidev").join("install.toml"))
+}
+
+/// `~/.cache/omnidev/omnigent-check.json` — volatile update-check state.
+pub fn check_cache_path() -> Result<PathBuf> {
+    Ok(cache_home()?.join("omnidev").join("omnigent-check.json"))
+}
+
 /// FNV-1a 64-bit, rendered as 8 hex chars. No external dep needed — we only
 /// need a stable, collision-unlikely tag for a filesystem path.
 fn short_hash(bytes: &[u8]) -> String {

dev/omnidev/src/pod.rs

@@ -11,32 +11,45 @@ pub struct Pod {
     pub repo_root: PathBuf,
     pub dir: PathBuf,
     pub ports: Ports,
+    pub vite_host: String,
+    /// LAN origins to trust for device testing (`--trust-lan-origins`); empty
+    /// otherwise. Fed to the server as `OMNIGENT_WS_ALLOWED_ORIGINS`.
+    pub trusted_origins: Vec<String>,
 }
 
 impl Pod {
     /// Create the pod directory tree (idempotent) and return the pod handle.
-    /// Mirrors the isolation layout proven by `scripts/backend-smoke.sh`.
-    pub fn create(repo_root: PathBuf, dir: PathBuf, ports: Ports) -> Result<Pod> {
-        for sub in [
-            "home",
-            "tmp",
-            "config/xdg",
-            "data/xdg",
-            "cache/xdg",
-            "config/omnigent",
-            "data/omnigent",
-            "artifacts",
-            "logs",
-        ] {
+    /// Only omnigent's own state is isolated (DB, artifacts, logs, config); the
+    /// pod inherits your real home, credentials, and caches.
+    pub fn create(
+        repo_root: PathBuf,
+        dir: PathBuf,
+        ports: Ports,
+        vite_host: String,
+        trusted_origins: Vec<String>,
+    ) -> Result<Pod> {
+        for sub in ["data/omnigent", "artifacts", "logs", "config"] {
             let p = dir.join(sub);
             std::fs::create_dir_all(&p)
                 .with_context(|| format!("creating pod dir {}", p.display()))?;
         }
-        Ok(Pod {
+        let pod = Pod {
             repo_root,
             dir,
             ports,
-        })
+            vite_host,
+            trusted_origins,
+        };
+        // Seed the pod's config from the developer's real one so it works out
+        // of the box (keeps their providers). Best-effort: a copy failure just
+        // starts the pod with an empty config, so warn rather than abort.
+        if let Some(src) = real_config_path() {
+            let dest = pod.config_dir().join("config.yaml");
+            if let Err(e) = seed_config_file(&src, &dest) {
+                eprintln!("omnidev: could not seed pod config: {e:#}");
+            }
+        }
+        Ok(pod)
     }
 
     pub fn db_uri(&self) -> String {
@@ -50,6 +63,13 @@ impl Pod {
         self.dir.join("artifacts")
     }
 
+    /// The pod's isolated config home, exposed to children as
+    /// `OMNIGENT_CONFIG_HOME` so its `config.yaml` is separate from the
+    /// developer's real `~/.omnigent/config.yaml`.
+    pub fn config_dir(&self) -> PathBuf {
+        self.dir.join("config")
+    }
+
     pub fn server_url(&self) -> String {
         format!("http://127.0.0.1:{}", self.ports.server)
     }
@@ -70,6 +90,27 @@ impl Pod {
         self.repo_root.join("web")
     }
 
+    /// Whether `web/` needs `npm install` before Vite can start: either
+    /// `node_modules/` is absent, or the lockfile / `package.json` is newer
+    /// than the installed tree (a dependency was added/changed since the last
+    /// install — the case that makes Vite's dependency scan fail).
+    pub fn needs_npm_install(&self) -> bool {
+        let web = self.web_dir();
+        let modules = web.join("node_modules");
+        if !modules.is_dir() {
+            return true;
+        }
+        let mtime = |p: PathBuf| std::fs::metadata(p).and_then(|m| m.modified()).ok();
+        let Some(installed) = mtime(modules) else {
+            return true;
+        };
+        // Reinstall if either manifest is newer than node_modules.
+        [web.join("package-lock.json"), web.join("package.json")]
+            .into_iter()
+            .filter_map(mtime)
+            .any(|t| t > installed)
+    }
+
     /// Directory to watch for backend source changes.
     pub fn omnigent_dir(&self) -> PathBuf {
         self.repo_root.join("omnigent")
@@ -80,22 +121,52 @@ impl Pod {
     }
 
     /// The env overrides applied on top of the inherited parent env for every
-    /// child. Keeps PATH/uv resolvable while redirecting all Omnigent state
-    /// into the pod dir. `OMNIGENT_URL` is the seam `web/vite.config.ts` reads
-    /// to point its proxy at this pod's backend.
+    /// child. We isolate omnigent's own state — the DB, data dir, and config
+    /// home — so concurrent pods don't share a database, pidfile, or
+    /// `config.yaml`. The rest (real `HOME`, credentials, uv/npm caches) is
+    /// inherited, since the agents omnigent runs need it. `OMNIGENT_URL` is the
+    /// seam `web/vite.config.ts` reads to point its proxy at this pod's backend;
+    /// `OMNIGENT_CONFIG_HOME` is where the server/host/runner read `config.yaml`.
     pub fn env(&self) -> Vec<(String, String)> {
         let d = |p: &str| self.dir.join(p).display().to_string();
-        vec![
-            ("HOME".into(), d("home")),
-            ("TMPDIR".into(), d("tmp")),
-            ("XDG_CONFIG_HOME".into(), d("config/xdg")),
-            ("XDG_DATA_HOME".into(), d("data/xdg")),
-            ("XDG_CACHE_HOME".into(), d("cache/xdg")),
-            ("OMNIGENT_CONFIG_HOME".into(), d("config/omnigent")),
+        let mut env = vec![
             ("OMNIGENT_DATA_DIR".into(), d("data/omnigent")),
             ("OMNIGENT_DATABASE_URI".into(), self.db_uri()),
             ("OMNIGENT_URL".into(), self.server_url()),
-        ]
+            (
+                "OMNIGENT_CONFIG_HOME".into(),
+                self.config_dir().display().to_string(),
+            ),
+        ];
+        if let Some(allowed) = self.allowed_origins_env() {
+            env.push(("OMNIGENT_WS_ALLOWED_ORIGINS".into(), allowed));
+        }
+        env
+    }
+
+    /// The `OMNIGENT_WS_ALLOWED_ORIGINS` value to inject, or `None` to leave it
+    /// untouched. Merges the trusted LAN origins onto any value inherited from
+    /// the parent environment (comma-separated, order-preserving, deduped) so a
+    /// developer's own allowlist survives. Returns `None` when there are no LAN
+    /// origins to add — then the parent's value (if any) simply passes through.
+    fn allowed_origins_env(&self) -> Option<String> {
+        if self.trusted_origins.is_empty() {
+            return None;
+        }
+        let inherited = std::env::var("OMNIGENT_WS_ALLOWED_ORIGINS").unwrap_or_default();
+        let mut merged: Vec<String> = Vec::new();
+        let parts = inherited
+            .split(',')
+            .map(str::trim)
+            .filter(|s| !s.is_empty())
+            .map(str::to_string)
+            .chain(self.trusted_origins.iter().cloned());
+        for part in parts {
+            if !merged.contains(&part) {
+                merged.push(part);
+            }
+        }
+        Some(merged.join(","))
     }
 }
 
@@ -107,3 +178,171 @@ pub fn clean(dir: &Path) -> Result<()> {
     }
     Ok(())
 }
+
+/// The developer's real omnigent `config.yaml` to seed a fresh pod from.
+///
+/// Honors `OMNIGENT_CONFIG_HOME` if the parent env sets it (nested/test
+/// setups), else `~/.omnigent/config.yaml` via `HOME`. Returns `None` when the
+/// file does not exist — a fresh pod then starts with an empty config, just
+/// like a first-run user.
+fn real_config_path() -> Option<PathBuf> {
+    let home = match std::env::var_os("OMNIGENT_CONFIG_HOME") {
+        Some(h) if !h.is_empty() => PathBuf::from(h),
+        _ => PathBuf::from(std::env::var_os("HOME")?).join(".omnigent"),
+    };
+    let path = home.join("config.yaml");
+    path.exists().then_some(path)
+}
+
+/// Copy `src` to `dest`, but only when `dest` does not already exist — a normal
+/// pod restart must not clobber config the developer edited inside the pod.
+/// After `--clean` the whole pod dir is gone, so `dest` is absent and this
+/// re-seeds.
+fn seed_config_file(src: &Path, dest: &Path) -> Result<()> {
+    if dest.exists() {
+        return Ok(());
+    }
+    std::fs::copy(src, dest)
+        .with_context(|| format!("seeding {} from {}", dest.display(), src.display()))?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Mutex;
+
+    // `real_config_path` reads process-global env; serialize the tests that
+    // set it so parallel runs don't observe each other's overrides.
+    static ENV_LOCK: Mutex<()> = Mutex::new(());
+
+    fn tempdir() -> PathBuf {
+        let unique = format!(
+            "omnidev-pod-test-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        );
+        let dir = std::env::temp_dir().join(unique);
+        std::fs::create_dir_all(&dir).unwrap();
+        dir
+    }
+
+    fn make_pod(pod_dir: PathBuf) -> Pod {
+        Pod::create(
+            tempdir(),
+            pod_dir,
+            Ports {
+                server: 19191,
+                vite: 19292,
+            },
+            "127.0.0.1".into(),
+            Vec::new(),
+        )
+        .unwrap()
+    }
+
+    /// Point `OMNIGENT_CONFIG_HOME` at `home` for the duration of `f`, restoring
+    /// the previous value afterwards. Serialized against other env-touching
+    /// tests via `ENV_LOCK`.
+    fn with_config_home<T>(home: &Path, f: impl FnOnce() -> T) -> T {
+        let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let prev = std::env::var_os("OMNIGENT_CONFIG_HOME");
+        std::env::set_var("OMNIGENT_CONFIG_HOME", home);
+        let out = f();
+        match prev {
+            Some(v) => std::env::set_var("OMNIGENT_CONFIG_HOME", v),
+            None => std::env::remove_var("OMNIGENT_CONFIG_HOME"),
+        }
+        out
+    }
+
+    #[test]
+    fn create_makes_config_dir() {
+        let real = tempdir(); // empty config home -> nothing to seed
+        let pod = with_config_home(&real, || make_pod(tempdir()));
+        assert!(pod.config_dir().is_dir());
+    }
+
+    #[test]
+    fn env_includes_config_home() {
+        let real = tempdir();
+        let pod = with_config_home(&real, || make_pod(tempdir()));
+        let env = pod.env();
+        let got = env
+            .iter()
+            .find(|(k, _)| k == "OMNIGENT_CONFIG_HOME")
+            .map(|(_, v)| v.clone());
+        assert_eq!(got, Some(pod.config_dir().display().to_string()));
+    }
+
+    #[test]
+    fn create_seeds_pod_config_from_real() {
+        let real = tempdir();
+        std::fs::write(real.join("config.yaml"), "providers:\n  seeded: true\n").unwrap();
+
+        let pod = with_config_home(&real, || make_pod(tempdir()));
+
+        let seeded = std::fs::read_to_string(pod.config_dir().join("config.yaml")).unwrap();
+        assert_eq!(seeded, "providers:\n  seeded: true\n");
+    }
+
+    #[test]
+    fn create_skips_seed_when_real_config_absent() {
+        let real = tempdir(); // no config.yaml inside
+        let pod = with_config_home(&real, || make_pod(tempdir()));
+        assert!(!pod.config_dir().join("config.yaml").exists());
+    }
+
+    #[test]
+    fn seed_does_not_overwrite_existing() {
+        let dir = tempdir();
+        let src = dir.join("src.yaml");
+        let dest = dir.join("dest.yaml");
+        std::fs::write(&src, "from: real\n").unwrap();
+        std::fs::write(&dest, "edited: in-pod\n").unwrap();
+
+        seed_config_file(&src, &dest).unwrap();
+
+        // Existing pod-local edits survive; the real config does not clobber them.
+        assert_eq!(std::fs::read_to_string(&dest).unwrap(), "edited: in-pod\n");
+    }
+
+    #[test]
+    fn real_config_path_honors_config_home() {
+        let real = tempdir();
+        std::fs::write(real.join("config.yaml"), "x: 1\n").unwrap();
+        let got = with_config_home(&real, real_config_path);
+        assert_eq!(got, Some(real.join("config.yaml")));
+    }
+
+    #[test]
+    fn real_config_path_falls_back_to_home_dot_omnigent() {
+        // With no OMNIGENT_CONFIG_HOME, the real config resolves under
+        // `$HOME/.omnigent/` — the path a normal pod run seeds from.
+        let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let prev_cfg = std::env::var_os("OMNIGENT_CONFIG_HOME");
+        let prev_home = std::env::var_os("HOME");
+
+        let home = tempdir();
+        std::fs::create_dir_all(home.join(".omnigent")).unwrap();
+        std::fs::write(home.join(".omnigent/config.yaml"), "y: 2\n").unwrap();
+
+        std::env::remove_var("OMNIGENT_CONFIG_HOME");
+        std::env::set_var("HOME", &home);
+        let got = real_config_path();
+
+        match prev_cfg {
+            Some(v) => std::env::set_var("OMNIGENT_CONFIG_HOME", v),
+            None => std::env::remove_var("OMNIGENT_CONFIG_HOME"),
+        }
+        match prev_home {
+            Some(v) => std::env::set_var("HOME", v),
+            None => std::env::remove_var("HOME"),
+        }
+
+        assert_eq!(got, Some(home.join(".omnigent/config.yaml")));
+    }
+}

dev/omnidev/src/process.rs

@@ -5,22 +5,34 @@ use std::path::PathBuf;
 use crate::pod::Pod;
 
 /// A resolved command line + working dir for one process. Env is applied by the
-/// supervisor from `Pod::env()`, so it is not duplicated here.
+/// supervisor from `Pod::env()`, with per-process additions from `extra_env`.
 pub struct ProcSpec {
     pub program: String,
     pub args: Vec<String>,
     pub cwd: PathBuf,
+    pub extra_env: Vec<(String, String)>,
 }
 
 impl ProcSpec {
-    /// `uv run omnigent server --host 127.0.0.1 --port <p> --database-uri <db>
-    /// --artifact-location <dir>`, from the repo root.
+    fn omnigent_log_env() -> Vec<(String, String)> {
+        // Child stderr is a pipe that omnidev reads into its process panes.
+        // Let Omnigent's process logger mirror to that pipe despite it not
+        // being a terminal, and force ANSI colors because omnidev parses them.
+        vec![
+            ("OMNIGENT_LOG_TTY_FD".into(), "2".into()),
+            ("OMNIGENT_LOG_FORCE_COLOR".into(), "1".into()),
+        ]
+    }
+
+    /// `uv run omnigent --log-to-stderr server --host 127.0.0.1 --port <p>
+    /// --database-uri <db> --artifact-location <dir>`, from the repo root.
     pub fn server(pod: &Pod) -> ProcSpec {
         ProcSpec {
             program: "uv".into(),
             args: vec![
                 "run".into(),
                 "omnigent".into(),
+                "--log-to-stderr".into(),
                 "server".into(),
                 "--host".into(),
                 "127.0.0.1".into(),
@@ -32,26 +44,51 @@ impl ProcSpec {
                 pod.artifacts_dir().display().to_string(),
             ],
             cwd: pod.repo_root.clone(),
+            extra_env: Self::omnigent_log_env(),
         }
     }
 
-    /// `uv run omnigent host --server http://127.0.0.1:<p>`, from the repo root.
+    /// `uv run omnigent --log-to-stderr host --server http://127.0.0.1:<p>`,
+    /// from the repo root.
     pub fn host(pod: &Pod) -> ProcSpec {
         ProcSpec {
             program: "uv".into(),
             args: vec![
                 "run".into(),
                 "omnigent".into(),
+                "--log-to-stderr".into(),
                 "host".into(),
                 "--server".into(),
                 pod.server_url(),
             ],
             cwd: pod.repo_root.clone(),
+            extra_env: Self::omnigent_log_env(),
         }
     }
 
-    /// `npm run dev -- --port <p> --strictPort`, from `web/`. `OMNIGENT_URL`
-    /// (in the pod env) points Vite's proxy at this pod's backend.
+    /// `npm install`, from `web/`. Run before Vite when deps are missing or
+    /// stale so Vite's dependency scan doesn't fail on an unresolved import.
+    ///
+    /// `--loglevel http` makes npm emit a line per package fetch even when its
+    /// stdout is piped (its progress bar is TTY-only), so the pane streams real
+    /// progress. `--no-fund --no-audit` trims the trailing noise.
+    pub fn npm_install(pod: &Pod) -> ProcSpec {
+        ProcSpec {
+            program: "npm".into(),
+            args: vec![
+                "install".into(),
+                "--no-fund".into(),
+                "--no-audit".into(),
+                "--loglevel".into(),
+                "http".into(),
+            ],
+            cwd: pod.web_dir(),
+            extra_env: Vec::new(),
+        }
+    }
+
+    /// `npm run dev -- --host <host> --port <p> --strictPort`, from `web/`.
+    /// `OMNIGENT_URL` (in the pod env) points Vite's proxy at this pod's backend.
     pub fn vite(pod: &Pod) -> ProcSpec {
         ProcSpec {
             program: "npm".into(),
@@ -59,11 +96,95 @@ impl ProcSpec {
                 "run".into(),
                 "dev".into(),
                 "--".into(),
+                "--host".into(),
+                pod.vite_host.clone(),
                 "--port".into(),
                 pod.ports.vite.to_string(),
                 "--strictPort".into(),
             ],
             cwd: pod.web_dir(),
+            extra_env: Vec::new(),
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::ports::Ports;
+
+    #[test]
+    fn vite_uses_configured_bind_host_but_backend_url_stays_loopback() {
+        let repo = tempdir();
+        let pod_dir = tempdir();
+        let pod = Pod::create(
+            repo,
+            pod_dir,
+            Ports {
+                server: 19191,
+                vite: 19292,
+            },
+            "0.0.0.0".into(),
+            Vec::new(),
+        )
+        .unwrap();
+
+        let vite = ProcSpec::vite(&pod);
+        let host_flag = vite.args.iter().position(|arg| arg == "--host").unwrap();
+        assert_eq!(vite.args[host_flag + 1], "0.0.0.0");
+        assert_eq!(pod.server_url(), "http://127.0.0.1:19191");
+    }
+
+    #[test]
+    fn omnigent_processes_mirror_logs_to_omnidev_pipe() {
+        let repo = tempdir();
+        let pod_dir = tempdir();
+        let pod = Pod::create(
+            repo,
+            pod_dir,
+            Ports {
+                server: 19191,
+                vite: 19292,
+            },
+            "127.0.0.1".into(),
+            Vec::new(),
+        )
+        .unwrap();
+
+        for spec in [ProcSpec::server(&pod), ProcSpec::host(&pod)] {
+            assert!(
+                spec.args.iter().any(|arg| arg == "--log-to-stderr"),
+                "omnigent command should request stderr logging: {:?}",
+                spec.args
+            );
+            assert_eq!(
+                spec.extra_env
+                    .iter()
+                    .find(|(key, _)| key == "OMNIGENT_LOG_TTY_FD")
+                    .map(|(_, value)| value.as_str()),
+                Some("2")
+            );
+            assert_eq!(
+                spec.extra_env
+                    .iter()
+                    .find(|(key, _)| key == "OMNIGENT_LOG_FORCE_COLOR")
+                    .map(|(_, value)| value.as_str()),
+                Some("1")
+            );
+        }
+    }
+
+    fn tempdir() -> std::path::PathBuf {
+        let unique = format!(
+            "omnidev-process-test-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        );
+        let dir = std::env::temp_dir().join(unique);
+        std::fs::create_dir_all(&dir).unwrap();
+        dir
+    }
+}

dev/omnidev/src/shellhook.rs

@@ -0,0 +1,19 @@
+//! Emit the shell snippet that runs the daily update check.
+
+/// The snippet to append to `.zshrc`/`.bashrc`
+/// (`omnidev shell-hook >> ~/.zshrc`). All throttling and prompting live inside
+/// `omnidev check`, so this stays trivial and shell-agnostic: run once per
+/// interactive shell, quietly, and never fail the shell if it errors.
+///
+/// It self-guards on `command -v omnidev`, so it's meant to be appended to the
+/// rc (a static no-op when omnidev is absent) rather than run via
+/// `eval "$(omnidev shell-hook)"`, which would invoke omnidev on every shell
+/// startup and error when it isn't on PATH.
+const HOOK: &str = r#"# omnidev: daily omnigent update check
+if [ -n "${PS1:-}" ] && command -v omnidev >/dev/null 2>&1; then
+  omnidev check --quiet || true
+fi"#;
+
+pub fn print() {
+    println!("{HOOK}");
+}

dev/omnidev/src/supervisor.rs

@@ -62,6 +62,9 @@ pub struct Supervisor {
     shared: Arc<Mutex<Shared>>,
     env: Vec<(String, String)>,
     vite_enabled: bool,
+    /// Whether `--trust-lan-origins` was requested, so we can warn if it was
+    /// asked for but no LAN interface turned up any origins to trust.
+    trust_lan_origins: bool,
     slots: [Slot; 3],
     /// Generations we stopped on purpose — their exits are not crashes.
     expected_stops: HashSet<(usize, u64)>,
@@ -71,7 +74,12 @@ pub struct Supervisor {
 }
 
 impl Supervisor {
-    pub fn new(pod: Arc<Pod>, shared: Arc<Mutex<Shared>>, vite_enabled: bool) -> Supervisor {
+    pub fn new(
+        pod: Arc<Pod>,
+        shared: Arc<Mutex<Shared>>,
+        vite_enabled: bool,
+        trust_lan_origins: bool,
+    ) -> Supervisor {
         let env = pod.env();
         let (exit_tx, exit_rx) = mpsc::unbounded_channel();
         Supervisor {
@@ -79,6 +87,7 @@ impl Supervisor {
             shared,
             env,
             vite_enabled,
+            trust_lan_origins,
             slots: Default::default(),
             expected_stops: HashSet::new(),
             gen_counter: 0,
@@ -104,9 +113,18 @@ impl Supervisor {
             self.pod.ports.server,
             self.pod.ports.vite
         ));
+        if !self.pod.trusted_origins.is_empty() {
+            self.event(format!(
+                "trusting LAN origins for device testing: {}",
+                self.pod.trusted_origins.join(", ")
+            ));
+        } else if self.trust_lan_origins {
+            self.event("--trust-lan-origins: no LAN interface found; no extra origins trusted");
+        }
 
         self.start_backend().await;
         if self.vite_enabled {
+            self.prepare_vite().await;
             self.spawn(ProcId::Vite);
         }
 
@@ -169,6 +187,7 @@ impl Supervisor {
                 if self.vite_enabled {
                     self.event("restarting vite");
                     self.stop(ProcId::Vite).await;
+                    self.prepare_vite().await;
                     self.spawn(ProcId::Vite);
                 }
             }
@@ -192,6 +211,7 @@ impl Supervisor {
         cmd.args(&spec.args)
             .current_dir(&spec.cwd)
             .envs(self.env.iter().cloned())
+            .envs(spec.extra_env.iter().cloned())
             .stdin(Stdio::null())
             .stdout(Stdio::piped())
             .stderr(Stdio::piped())
@@ -252,6 +272,77 @@ impl Supervisor {
         });
     }
 
+    /// Run `npm install` to completion before Vite starts, but only when deps
+    /// are missing or stale — otherwise Vite's dependency scan fails on an
+    /// unresolved import (e.g. a dep added to package.json but not installed).
+    /// Output streams into the Vite pane. A failed/absent install is logged but
+    /// non-fatal: we still let Vite try, so a transient npm hiccup doesn't block
+    /// the whole session.
+    async fn prepare_vite(&self) {
+        if !self.pod.needs_npm_install() {
+            return;
+        }
+        self.set_status(ProcId::Vite, ProcStatus::Starting);
+        self.shared.lock().unwrap().log_proc(
+            ProcId::Vite,
+            "web deps missing or stale — running npm install".into(),
+        );
+
+        let spec = ProcSpec::npm_install(&self.pod);
+        let mut cmd = Command::new(&spec.program);
+        cmd.args(&spec.args)
+            .current_dir(&spec.cwd)
+            .envs(self.env.iter().cloned())
+            .envs(spec.extra_env.iter().cloned())
+            .stdin(Stdio::null())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped());
+
+        let mut child = match cmd.spawn() {
+            Ok(c) => c,
+            Err(e) => {
+                self.shared
+                    .lock()
+                    .unwrap()
+                    .log_proc(ProcId::Vite, format!("failed to run npm install: {e}"));
+                return;
+            }
+        };
+        if let Some(out) = child.stdout.take() {
+            self.pump(ProcId::Vite, out);
+        }
+        if let Some(err) = child.stderr.take() {
+            self.pump(ProcId::Vite, err);
+        }
+
+        // `--loglevel http` streams a line per package fetch, but npm still
+        // goes quiet during the final tree-build/link phase. A slow heartbeat
+        // covers those gaps so the pane never looks frozen.
+        let started = Instant::now();
+        let mut heartbeat = tokio::time::interval(Duration::from_secs(5));
+        heartbeat.tick().await; // the first tick fires immediately; skip it
+        let status = loop {
+            tokio::select! {
+                result = child.wait() => break result,
+                _ = heartbeat.tick() => {
+                    let secs = started.elapsed().as_secs();
+                    self.shared
+                        .lock()
+                        .unwrap()
+                        .log_proc(ProcId::Vite, format!("… npm install running ({secs}s)"));
+                }
+            }
+        };
+        match status {
+            Ok(s) if s.success() => self.event(format!(
+                "npm install complete ({}s)",
+                started.elapsed().as_secs()
+            )),
+            Ok(s) => self.event(format!("npm install exited {s} — starting Vite anyway")),
+            Err(e) => self.event(format!("npm install wait error: {e}")),
+        }
+    }
+
     /// Spawn a task that streams one pipe into the shared buffer, line by line.
     fn pump<R>(&self, id: ProcId, reader: R)
     where

dev/omnidev/src/tui/mod.rs

@@ -3,6 +3,7 @@
 
 mod render;
 
+use std::cell::Cell;
 use std::io::{self, Stdout};
 use std::sync::{Arc, Mutex};
 use std::time::Duration;
@@ -30,6 +31,35 @@ pub enum View {
     All,
 }
 
+/// Search direction. `Fwd` scans toward the tail (newer lines), `Back` toward
+/// the head — matching `less`'s `/` and `?`.
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub enum Dir {
+    Fwd,
+    Back,
+}
+
+impl Dir {
+    fn flip(self) -> Dir {
+        match self {
+            Dir::Fwd => Dir::Back,
+            Dir::Back => Dir::Fwd,
+        }
+    }
+}
+
+/// A committed search: the query and the direction it was entered with.
+pub struct Search {
+    pub query: String,
+    pub dir: Dir,
+}
+
+/// The line-editor state while the user is typing a `/` or `?` query.
+pub struct InputMode {
+    pub dir: Dir,
+    pub query: String,
+}
+
 impl View {
     fn proc(self) -> Option<ProcId> {
         match self {
@@ -46,9 +76,23 @@ pub struct App {
     shared: Arc<Mutex<Shared>>,
     cmds: mpsc::UnboundedSender<Cmd>,
     view: View,
-    /// Lines scrolled up from the bottom; 0 == pinned to tail.
+    /// Display rows scrolled up from the bottom; 0 == pinned to tail. Counted in
+    /// *rendered rows*, so it stays correct whether or not lines wrap.
     scroll_back: usize,
     follow: bool,
+    /// Wrap long lines to the next row (default) vs. clip them at the edge.
+    wrap: bool,
+    /// Body size in rows/cols, refreshed by the renderer each frame so key
+    /// handling can page by a full/half window and lay out wraps for search.
+    /// Seeded so keys pressed before the first draw still behave.
+    viewport_h: Cell<usize>,
+    viewport_w: Cell<usize>,
+    /// The last committed search, if any (drives `n`/`N` and highlighting).
+    search: Option<Search>,
+    /// Logical line index of the match `n`/`N` last jumped to, for anchoring.
+    current_match: Option<usize>,
+    /// Set while the user is typing a query; steals keys from command mode.
+    input: Option<InputMode>,
     should_quit: bool,
 }
 
@@ -61,6 +105,12 @@ impl App {
             view: View::All,
             scroll_back: 0,
             follow: true,
+            wrap: true,
+            viewport_h: Cell::new(20),
+            viewport_w: Cell::new(80),
+            search: None,
+            current_match: None,
+            input: None,
             should_quit: false,
         }
     }
@@ -98,9 +148,21 @@ impl App {
         if key.kind != KeyEventKind::Press {
             return;
         }
-        let page = 20;
+        // Ctrl-C always quits, even mid-search.
+        if key.code == KeyCode::Char('c') && key.modifiers.contains(KeyModifiers::CONTROL) {
+            self.should_quit = true;
+            return;
+        }
+        // While typing a query, keys build/commit/cancel it instead of running
+        // commands.
+        if self.input.is_some() {
+            self.on_key_input(key);
+            return;
+        }
+
+        let window = self.viewport_h.get().max(1);
+        let half = (window / 2).max(1);
         match (key.code, key.modifiers) {
-            (KeyCode::Char('c'), KeyModifiers::CONTROL) => self.should_quit = true,
             (KeyCode::Char('q'), _) => self.should_quit = true,
 
             (KeyCode::Char('1'), _) => self.set_view(View::Server),
@@ -109,17 +171,33 @@ impl App {
             (KeyCode::Char('0'), _) => self.set_view(View::All),
             (KeyCode::Tab, _) => self.cycle_view(),
 
-            (KeyCode::Up, _) => self.scroll(1),
-            (KeyCode::Down, _) => self.scroll_down(1),
-            (KeyCode::PageUp, _) => self.scroll(page),
-            (KeyCode::PageDown, _) => self.scroll_down(page),
+            // Pager movement — full `less` semantics.
+            (KeyCode::Char('j'), _) | (KeyCode::Down, _) => self.scroll_down(1),
+            (KeyCode::Char('k'), _) | (KeyCode::Up, _) => self.scroll_up(1),
+            (KeyCode::Char('f'), _) | (KeyCode::Char(' '), _) | (KeyCode::PageDown, _) => {
+                self.scroll_down(window)
+            }
+            (KeyCode::Char('b'), _) | (KeyCode::PageUp, _) => self.scroll_up(window),
+            (KeyCode::Char('d'), _) => self.scroll_down(half),
+            (KeyCode::Char('u'), _) => self.scroll_up(half),
+            (KeyCode::Char('g'), _) | (KeyCode::Home, _) => self.scroll_to_top(),
+            (KeyCode::Char('G'), _) | (KeyCode::End, _) => self.scroll_to_bottom(),
 
-            (KeyCode::Char('f'), _) => {
+            // `less +F`: capital F toggles tail-follow.
+            (KeyCode::Char('F'), _) => {
                 self.follow = !self.follow;
                 if self.follow {
                     self.scroll_back = 0;
                 }
             }
+            (KeyCode::Char('w'), _) => self.toggle_wrap(),
+
+            // Search.
+            (KeyCode::Char('/'), _) => self.begin_search(Dir::Fwd),
+            (KeyCode::Char('?'), _) => self.begin_search(Dir::Back),
+            (KeyCode::Char('n'), _) => self.repeat_search(false),
+            (KeyCode::Char('N'), _) => self.repeat_search(true),
+
             (KeyCode::Char('r'), _) => {
                 if let Some(id) = self.view.proc() {
                     let _ = self.cmds.send(Cmd::Restart(id));
@@ -135,9 +213,43 @@ impl App {
         }
     }
 
+    /// Handle a key while a `/` or `?` query is being typed.
+    fn on_key_input(&mut self, key: KeyEvent) {
+        match key.code {
+            KeyCode::Enter => {
+                let input = self.input.take().unwrap();
+                if !input.query.is_empty() {
+                    self.search = Some(Search {
+                        query: input.query,
+                        dir: input.dir,
+                    });
+                    self.current_match = None;
+                    self.run_search(input.dir, true);
+                }
+            }
+            KeyCode::Esc => self.input = None,
+            KeyCode::Backspace => {
+                let done = {
+                    let input = self.input.as_mut().unwrap();
+                    input.query.pop();
+                    input.query.is_empty()
+                };
+                if done {
+                    self.input = None;
+                }
+            }
+            KeyCode::Char(c) if !key.modifiers.contains(KeyModifiers::CONTROL) => {
+                self.input.as_mut().unwrap().query.push(c);
+            }
+            _ => {}
+        }
+    }
+
     fn set_view(&mut self, v: View) {
         self.view = v;
         self.scroll_back = 0;
+        // Match indices are per-view; drop the anchor on switch.
+        self.current_match = None;
     }
 
     fn cycle_view(&mut self) {
@@ -148,9 +260,10 @@ impl App {
             View::Vite => View::All,
         };
         self.scroll_back = 0;
+        self.current_match = None;
     }
 
-    fn scroll(&mut self, n: usize) {
+    fn scroll_up(&mut self, n: usize) {
         // Scrolling up detaches from the tail.
         self.follow = false;
         self.scroll_back = self.scroll_back.saturating_add(n);
@@ -163,6 +276,147 @@ impl App {
         }
     }
 
+    fn scroll_to_top(&mut self) {
+        self.follow = false;
+        let lines = self.display_lines();
+        let counts = self.row_counts(&lines);
+        let total: usize = counts.iter().sum();
+        let height = self.viewport_h.get().max(1);
+        self.scroll_back = total.saturating_sub(height);
+    }
+
+    fn scroll_to_bottom(&mut self) {
+        self.scroll_back = 0;
+        self.follow = true;
+    }
+
+    fn toggle_wrap(&mut self) {
+        self.wrap = !self.wrap;
+        // Row counts change with wrap; re-anchor on the matched line if any,
+        // otherwise drop to the tail so we land somewhere sane.
+        match self.current_match {
+            Some(idx) => {
+                let lines = self.display_lines();
+                self.jump_to_logical(idx, &lines);
+            }
+            None => self.scroll_to_bottom(),
+        }
+    }
+
+    fn begin_search(&mut self, dir: Dir) {
+        self.input = Some(InputMode {
+            dir,
+            query: String::new(),
+        });
+    }
+
+    /// `n` repeats the committed search in its direction; `N` (opposite=true)
+    /// reverses it.
+    fn repeat_search(&mut self, opposite: bool) {
+        let Some(search) = self.search.as_ref() else {
+            return;
+        };
+        let dir = if opposite {
+            search.dir.flip()
+        } else {
+            search.dir
+        };
+        self.run_search(dir, false);
+    }
+
+    /// Scan for the next match and jump to it. `fresh` anchors from the current
+    /// viewport; otherwise it steps off the last matched line.
+    fn run_search(&mut self, dir: Dir, fresh: bool) {
+        let Some(query) = self.search.as_ref().map(|s| s.query.to_ascii_lowercase()) else {
+            return;
+        };
+        let lines = self.display_lines();
+        let n = lines.len();
+        if n == 0 || query.is_empty() {
+            return;
+        }
+
+        let start = if fresh {
+            self.anchor(&lines, dir)
+        } else {
+            match self.current_match {
+                Some(m) => match dir {
+                    Dir::Fwd => (m + 1) % n,
+                    Dir::Back => (m + n - 1) % n,
+                },
+                None => self.anchor(&lines, dir),
+            }
+        };
+
+        // Scan every line once, wrapping around the ends.
+        for k in 0..n {
+            let i = match dir {
+                Dir::Fwd => (start + k) % n,
+                Dir::Back => (start + n - (k % n)) % n,
+            };
+            if lines[i].to_ascii_lowercase().contains(&query) {
+                self.current_match = Some(i);
+                self.jump_to_logical(i, &lines);
+                return;
+            }
+        }
+    }
+
+    /// Displayed text (ANSI stripped, `[label]` prefix included in the combined
+    /// view) for every logical line of the focused channel — the exact text the
+    /// renderer shows, so search offsets and wrap counts line up.
+    fn display_lines(&self) -> Vec<String> {
+        let all_view = self.view == View::All;
+        let s = self.shared.lock().unwrap();
+        let iter: Box<dyn Iterator<Item = &String>> = match self.view {
+            View::Server => Box::new(s.buf(ProcId::Server).iter()),
+            View::Host => Box::new(s.buf(ProcId::Host).iter()),
+            View::Vite => Box::new(s.buf(ProcId::Vite).iter()),
+            View::All => Box::new(s.all.iter()),
+        };
+        iter.map(|l| render::display_text(l, all_view)).collect()
+    }
+
+    /// Per-line display-row counts at the current width/wrap.
+    fn row_counts(&self, lines: &[String]) -> Vec<usize> {
+        let width = self.viewport_w.get();
+        lines
+            .iter()
+            .map(|t| render::row_count(t, width, self.wrap))
+            .collect()
+    }
+
+    /// The logical line a fresh search should scan from: the top visible line
+    /// going forward, the bottom visible line going back.
+    fn anchor(&self, lines: &[String], dir: Dir) -> usize {
+        let counts = self.row_counts(lines);
+        let total: usize = counts.iter().sum();
+        let height = self.viewport_h.get().max(1);
+        let back = self.scroll_back.min(total.saturating_sub(height));
+        let end = total.saturating_sub(back); // one past the bottom visible row
+        let top_row = end.saturating_sub(height);
+        match dir {
+            Dir::Fwd => line_at_row(&counts, top_row),
+            Dir::Back => line_at_row(&counts, end.saturating_sub(1)),
+        }
+    }
+
+    /// Scroll so logical line `idx`'s first display row sits at the top of the
+    /// viewport (clamped so we never scroll past the tail).
+    fn jump_to_logical(&mut self, idx: usize, lines: &[String]) {
+        let counts = self.row_counts(lines);
+        if idx >= counts.len() {
+            return;
+        }
+        let height = self.viewport_h.get().max(1);
+        let below: usize = counts[idx + 1..].iter().sum();
+        let own = counts[idx];
+        let total: usize = counts.iter().sum();
+        let max_back = total.saturating_sub(height);
+        self.scroll_back = (own + below).saturating_sub(height).min(max_back);
+        self.follow = false;
+    }
+
     fn clear_current(&mut self) {
         let mut s = self.shared.lock().unwrap();
         match self.view {
@@ -172,9 +426,10 @@ impl App {
             View::All => s.all.clear(),
         }
         self.scroll_back = 0;
+        self.current_match = None;
     }
 
-    /// Total line count of the focused channel, for the status readout.
+    /// Total logical line count of the focused channel, for the status readout.
     pub fn line_count(&self) -> usize {
         let s = self.shared.lock().unwrap();
         match self.view {
@@ -184,6 +439,53 @@ impl App {
             View::All => s.all.iter().count(),
         }
     }
+
+    /// The committed query, ASCII-lowercased, for the renderer's highlight
+    /// pass. `None` when no search is active.
+    pub fn search_query_lower(&self) -> Option<String> {
+        self.search
+            .as_ref()
+            .filter(|s| !s.query.is_empty())
+            .map(|s| s.query.to_ascii_lowercase())
+    }
+
+    /// The in-progress query prompt (`dir`, text) while the user is typing.
+    pub fn input_prompt(&self) -> Option<(Dir, &str)> {
+        self.input.as_ref().map(|i| (i.dir, i.query.as_str()))
+    }
+
+    /// Number of logical lines matching the committed search, for the status
+    /// readout, plus the 1-based rank of the current match within them.
+    pub fn match_stats(&self) -> Option<(usize, usize)> {
+        let query = self.search.as_ref()?.query.to_ascii_lowercase();
+        if query.is_empty() {
+            return None;
+        }
+        let lines = self.display_lines();
+        let mut total = 0;
+        let mut rank = 0;
+        for (i, l) in lines.iter().enumerate() {
+            if l.to_ascii_lowercase().contains(&query) {
+                total += 1;
+                if Some(i) == self.current_match {
+                    rank = total;
+                }
+            }
+        }
+        Some((rank, total))
+    }
+}
+
+/// Map a display-row index to the logical line that contains it.
+fn line_at_row(counts: &[usize], target_row: usize) -> usize {
+    let mut acc = 0;
+    for (i, &rc) in counts.iter().enumerate() {
+        if target_row < acc + rc {
+            return i;
+        }
+        acc += rc;
+    }
+    counts.len().saturating_sub(1)
 }
 
 fn setup_terminal() -> Result<Terminal<CrosstermBackend<Stdout>>> {
@@ -214,3 +516,172 @@ fn spawn_input() -> mpsc::UnboundedReceiver<KeyEvent> {
     });
     rx
 }
+
+#[cfg(test)]
+mod tests {
+    //! Headless end-to-end: drive the real `on_key` and render through
+    //! ratatui's `TestBackend`, so the full key → state → draw path is
+    //! exercised without a TTY or a live pod.
+    use super::*;
+    use crate::ports::Ports;
+    use ratatui::backend::TestBackend;
+    use ratatui::Terminal;
+
+    /// Build an `App` over a throwaway pod and a channel whose receiver we keep
+    /// so `cmds.send` never fails.
+    fn app() -> (App, mpsc::UnboundedReceiver<Cmd>) {
+        let root = std::env::temp_dir().join(format!("omnidev-tui-{}", std::process::id()));
+        let dir = root.join("pod");
+        let pod = Arc::new(
+            Pod::create(
+                root.clone(),
+                dir,
+                Ports {
+                    server: 6767,
+                    vite: 5173,
+                },
+                "127.0.0.1".into(),
+                Vec::new(),
+            )
+            .unwrap(),
+        );
+        let shared = Shared::new(&pod);
+        let (tx, rx) = mpsc::unbounded_channel();
+        (App::new(pod, shared, tx), rx)
+    }
+
+    fn press(app: &mut App, code: KeyCode) {
+        app.on_key(KeyEvent::new(code, KeyModifiers::NONE));
+    }
+
+    fn type_str(app: &mut App, s: &str) {
+        for c in s.chars() {
+            press(app, KeyCode::Char(c));
+        }
+    }
+
+    /// Render one frame at the given size and return the body rows (everything
+    /// between the 4 header rows and the footer) as trimmed strings.
+    fn body(app: &App, w: u16, h: u16) -> Vec<String> {
+        let mut term = Terminal::new(TestBackend::new(w, h)).unwrap();
+        term.draw(|f| render::draw(f, app)).unwrap();
+        let buf = term.backend().buffer().clone();
+        let mut rows = Vec::new();
+        // Layout: 4 header rows, body fills the middle, 1 footer row.
+        for y in 4..h - 1 {
+            let mut s = String::new();
+            for x in 0..w {
+                s.push_str(buf.cell((x, y)).unwrap().symbol());
+            }
+            rows.push(s.trim_end().to_string());
+        }
+        rows
+    }
+
+    fn seed(app: &App, n: usize) {
+        let mut s = app.shared.lock().unwrap();
+        for i in 0..n {
+            s.all.push(format!("line{i:03}"));
+        }
+    }
+
+    #[test]
+    fn renders_tail_by_default() {
+        let (app, _rx) = app();
+        seed(&app, 100);
+        let rows = body(&app, 40, 12); // 4 header + 7 body + 1 footer
+        assert_eq!(rows.last().unwrap(), "line099");
+        assert!(rows.iter().any(|r| r == "line093"));
+    }
+
+    #[test]
+    fn paging_and_ends_move_the_window() {
+        let (mut app, _rx) = app();
+        seed(&app, 100);
+        // Establish viewport height via a first render (7 body rows).
+        let _ = body(&app, 40, 12);
+        press(&mut app, KeyCode::Char('b')); // page back one window
+        assert!(!app.follow);
+        let rows = body(&app, 40, 12);
+        assert_eq!(rows.last().unwrap(), "line092");
+
+        press(&mut app, KeyCode::Char('g')); // top
+        let rows = body(&app, 40, 12);
+        assert_eq!(rows.first().unwrap(), "line000");
+
+        press(&mut app, KeyCode::Char('G')); // bottom + follow
+        assert!(app.follow);
+        let rows = body(&app, 40, 12);
+        assert_eq!(rows.last().unwrap(), "line099");
+    }
+
+    #[test]
+    fn wrap_toggle_changes_row_shape() {
+        let (mut app, _rx) = app();
+        {
+            let mut s = app.shared.lock().unwrap();
+            s.all.push("X".repeat(30)); // wider than a 10-col body
+        }
+        // Default wrap ON: the 30-char line occupies multiple body rows.
+        let wrapped = body(&app, 10, 8);
+        let nonblank = wrapped.iter().filter(|r| !r.is_empty()).count();
+        assert!(nonblank >= 3, "expected wrap across rows, got {wrapped:?}");
+
+        press(&mut app, KeyCode::Char('w')); // wrap OFF → clipped to one row
+        let clipped = body(&app, 10, 8);
+        let nonblank = clipped.iter().filter(|r| !r.is_empty()).count();
+        assert_eq!(nonblank, 1);
+    }
+
+    #[test]
+    fn search_jumps_and_highlights() {
+        let (mut app, _rx) = app();
+        {
+            let mut s = app.shared.lock().unwrap();
+            for i in 0..100 {
+                let tag = if i == 5 { " ERROR here" } else { "" };
+                s.all.push(format!("line{i:03}{tag}"));
+            }
+        }
+        let _ = body(&app, 40, 12);
+        // `/error` + Enter jumps up to the match near the top of the body.
+        press(&mut app, KeyCode::Char('/'));
+        type_str(&mut app, "error");
+        press(&mut app, KeyCode::Enter);
+        assert_eq!(app.current_match, Some(5));
+        assert_eq!(app.match_stats(), Some((1, 1)));
+
+        // The matched line is visible and its "ERROR" is highlighted.
+        let mut term = Terminal::new(TestBackend::new(40, 12)).unwrap();
+        term.draw(|f| render::draw(f, &app)).unwrap();
+        let buf = term.backend().buffer().clone();
+        let mut highlit = 0;
+        for y in 4..11 {
+            for x in 0..40 {
+                let cell = buf.cell((x, y)).unwrap();
+                let is_match_char = matches!(cell.symbol(), "E" | "R" | "O");
+                if is_match_char && cell.bg == render::match_bg() {
+                    highlit += 1;
+                }
+            }
+        }
+        assert!(
+            highlit >= 5,
+            "expected the match highlighted, got {highlit}"
+        );
+    }
+
+    #[test]
+    fn typing_query_does_not_run_commands() {
+        let (mut app, _rx) = app();
+        seed(&app, 100);
+        let _ = body(&app, 40, 12);
+        press(&mut app, KeyCode::Char('/'));
+        // 'q' would quit in command mode; here it's just query text.
+        type_str(&mut app, "q");
+        assert!(!app.should_quit);
+        assert_eq!(app.input_prompt(), Some((Dir::Fwd, "q")));
+        press(&mut app, KeyCode::Esc);
+        assert!(app.input_prompt().is_none());
+    }
+}

dev/omnidev/src/tui/render.rs

@@ -9,8 +9,9 @@ use ratatui::style::{Color, Modifier, Style};
 use ratatui::text::{Line, Span};
 use ratatui::widgets::{Paragraph, Tabs};
 use ratatui::Frame;
+use unicode_width::UnicodeWidthChar;
 
-use super::{App, View};
+use super::{App, Dir, View};
 use crate::state::{ProcId, ProcStatus};
 
 // Palette calibrated (Solarized accents) to stay legible on both light and
@@ -26,16 +27,28 @@ const SERVER: Color = Color::Rgb(38, 139, 210); // blue
 const HOST: Color = Color::Rgb(42, 161, 152); // cyan
 const VITE: Color = Color::Rgb(211, 54, 130); // magenta
 const EVENT: Color = Color::Rgb(181, 137, 0); // amber (omnidev channel)
+const LABEL_WIDTH: usize = 7;
 
 const OK: Color = Color::Rgb(133, 153, 0); // green (running)
 const WARN: Color = Color::Rgb(203, 75, 22); // orange (starting/restarting)
 const ERR: Color = Color::Rgb(220, 50, 47); // red (crashed)
 
+// Search-match highlight: amber background with near-black text, legible on
+// either theme and distinct from the ANSI log colors underneath.
+const MATCH_BG: Color = Color::Rgb(181, 137, 0);
+const MATCH_FG: Color = Color::Rgb(20, 20, 20);
+
 /// Style for the header/footer chrome bars.
 fn chrome() -> Style {
     Style::default().bg(CHROME_BG).fg(CHROME_FG)
 }
 
+/// The search-match background, exposed for tests that assert highlighting.
+#[cfg(test)]
+pub fn match_bg() -> Color {
+    MATCH_BG
+}
+
 pub fn draw(f: &mut Frame, app: &App) {
     let chunks = Layout::default()
         .direction(Direction::Vertical)
@@ -54,7 +67,7 @@ pub fn draw(f: &mut Frame, app: &App) {
     draw_chips(f, app, chunks[2]);
     draw_tabs_row(f, app, chunks[3]);
     draw_body(f, app, chunks[4]);
-    draw_footer(f, chunks[5]);
+    draw_footer(f, app, chunks[5]);
 }
 
 fn draw_pod(f: &mut Frame, app: &App, area: Rect) {
@@ -106,7 +119,7 @@ fn draw_tabs_row(f: &mut Frame, app: &App, area: Rect) {
     // Split the row: tabs on the left, scroll/follow status right-aligned.
     let cols = Layout::default()
         .direction(Direction::Horizontal)
-        .constraints([Constraint::Min(0), Constraint::Length(24)])
+        .constraints([Constraint::Min(0), Constraint::Length(36)])
         .split(area);
 
     let entries = [
@@ -134,11 +147,18 @@ fn draw_tabs_row(f: &mut Frame, app: &App, area: Rect) {
     f.render_widget(tabs, cols[0]);
 
     let total = app.line_count();
-    let status = if app.follow {
-        format!("{total} ln · follow ")
+    let mut status = format!("{total} ln");
+    if !app.wrap {
+        status.push_str(" · nowrap");
+    }
+    if let Some((rank, count)) = app.match_stats() {
+        status.push_str(&format!(" · {rank}/{count}"));
+    }
+    if app.follow {
+        status.push_str(" · follow ");
     } else {
-        format!("{total} ln · ↑{} ", app.scroll_back)
-    };
+        status.push_str(&format!(" · ↑{} ", app.scroll_back));
+    }
     f.render_widget(
         Paragraph::new(Line::from(Span::styled(status, Style::default().fg(MUTED))))
             .alignment(Alignment::Right)
@@ -149,6 +169,12 @@ fn draw_tabs_row(f: &mut Frame, app: &App, area: Rect) {
 
 fn draw_body(f: &mut Frame, app: &App, area: Rect) {
     let all_view = app.view == View::All;
+    let width = area.width as usize;
+    let height = area.height as usize;
+    // Publish the body geometry so key handling can page and search can wrap.
+    app.viewport_h.set(height);
+    app.viewport_w.set(width);
+
     let shared = app.shared.lock().unwrap();
     let lines: Vec<String> = match app.view {
         View::Server => shared.buf(ProcId::Server).iter().cloned().collect(),
@@ -158,54 +184,230 @@ fn draw_body(f: &mut Frame, app: &App, area: Rect) {
     };
     drop(shared);
 
-    let height = area.height as usize;
-    let total = lines.len();
-    let max_back = total.saturating_sub(height);
-    let back = app.scroll_back.min(max_back);
-    let end = total.saturating_sub(back);
-    let start = end.saturating_sub(height);
-
-    let rendered: Vec<Line> = lines[start..end]
-        .iter()
-        .map(|l| render_line(l, all_view))
-        .collect();
-
-    f.render_widget(Paragraph::new(rendered), area);
-}
-
-fn draw_footer(f: &mut Frame, area: Rect) {
-    let hint = " 1/2/3/0 view · Tab cycle · ↑↓/PgUp/PgDn scroll · f follow · r restart · R backend · c clear · q quit ";
-    f.render_widget(
-        Paragraph::new(Line::from(Span::styled(
-            hint,
-            Style::default().fg(CHROME_FG),
-        )))
-        .style(chrome()),
-        area,
+    let query = app.search_query_lower();
+    let visible = visible_rows(
+        &lines,
+        all_view,
+        width,
+        height,
+        app.wrap,
+        app.scroll_back,
+        query.as_deref(),
     );
+    f.render_widget(Paragraph::new(visible), area);
 }
 
-/// Turn one stored log line into a styled `Line`. In the combined view the
-/// leading `[service]` tag is colored per service and the rest keeps its ANSI
-/// colors; per-service panes just pass their ANSI through.
-fn render_line(raw: &str, all_view: bool) -> Line<'static> {
+/// The window of display rows to show: the `height` rows sitting `scroll_back`
+/// rows above the tail. Rows are built from the bottom up, wrapping only enough
+/// logical lines to cover `scroll_back + height` so a full buffer isn't
+/// re-parsed every frame. Equivalent to wrapping every line and slicing the
+/// flat list, but without the wasted work.
+fn visible_rows(
+    lines: &[String],
+    all_view: bool,
+    width: usize,
+    height: usize,
+    wrap: bool,
+    scroll_back: usize,
+    query: Option<&str>,
+) -> Vec<Line<'static>> {
+    // `acc` holds rows bottom-to-top; each logical line yields one row (wrap
+    // off) or several (wrap on), so `scroll_back` counts rendered rows.
+    let needed = scroll_back.saturating_add(height);
+    let mut acc: Vec<Line> = Vec::with_capacity(needed + 8);
+    let mut exhausted = true;
+    for raw in lines.iter().rev() {
+        let spans = render_line(raw, all_view);
+        let ranges = query.map(|q| match_ranges(raw, all_view, q));
+        let mut line_rows: Vec<Line> = Vec::new();
+        wrap_spans(spans, width, wrap, ranges.as_deref(), &mut line_rows);
+        acc.extend(line_rows.into_iter().rev());
+        if acc.len() >= needed {
+            exhausted = false;
+            break;
+        }
+    }
+
+    // If we ran out of lines the buffer is shorter than the scroll offset, so
+    // clamp to the top; otherwise `scroll_back` is within range as-is.
+    let back = if exhausted {
+        scroll_back.min(acc.len().saturating_sub(height))
+    } else {
+        scroll_back
+    };
+    let end = (back + height).min(acc.len());
+    let mut visible: Vec<Line> = acc.drain(back..end).collect();
+    visible.reverse();
+    visible
+}
+
+fn draw_footer(f: &mut Frame, app: &App, area: Rect) {
+    // While typing a query the footer becomes the search prompt with a cursor
+    // block; otherwise it lists the key hints.
+    let line = if let Some((dir, query)) = app.input_prompt() {
+        let sigil = match dir {
+            Dir::Fwd => '/',
+            Dir::Back => '?',
+        };
+        Line::from(vec![
+            Span::styled(
+                format!(" {sigil}{query}"),
+                Style::default().fg(CHROME_FG).add_modifier(Modifier::BOLD),
+            ),
+            Span::styled("█", Style::default().fg(CHROME_FG)),
+        ])
+    } else {
+        let hint = " f/b page · d/u half · j/k line · g/G ends · F follow · w wrap · / ? search · n/N next · 1230/Tab view · r/R restart · c clear · q quit ";
+        Line::from(Span::styled(hint, Style::default().fg(CHROME_FG)))
+    };
+    f.render_widget(Paragraph::new(line).style(chrome()), area);
+}
+
+/// Turn one stored log line into styled spans. In the combined view the leading
+/// `[service]` tag is colored per service and the rest keeps its ANSI colors;
+/// per-service panes just pass their ANSI through.
+fn render_line(raw: &str, all_view: bool) -> Vec<Span<'static>> {
     if all_view {
         if let Some(rest) = raw.strip_prefix('[') {
             if let Some(end) = rest.find(']') {
                 let label = &rest[..end];
                 let body = &rest[end + 1..];
                 let mut spans = vec![Span::styled(
-                    format!("[{label}]"),
+                    format!("[{label:<LABEL_WIDTH$}]"),
                     Style::default()
                         .fg(label_color(label))
                         .add_modifier(Modifier::BOLD),
                 )];
                 spans.extend(ansi_spans(body));
-                return Line::from(spans);
+                return spans;
             }
         }
     }
-    Line::from(ansi_spans(raw))
+    ansi_spans(raw)
+}
+
+/// The exact text `render_line` will display (ANSI stripped, `[label]` prefix
+/// included), so search offsets and wrap-row counts line up with what's drawn.
+pub fn display_text(raw: &str, all_view: bool) -> String {
+    render_line(raw, all_view)
+        .iter()
+        .map(|s| s.content.as_ref())
+        .collect()
+}
+
+/// Column width of a char for layout. Control and zero-width chars (including
+/// tabs) count as 0 — good enough for log lines.
+fn char_cols(c: char) -> usize {
+    UnicodeWidthChar::width(c).unwrap_or(0)
+}
+
+/// How many display rows `text` occupies at `width` columns. Must stay in step
+/// with `wrap_spans`' row splitting so scroll math and search jumps agree.
+pub fn row_count(text: &str, width: usize, wrap: bool) -> usize {
+    if !wrap || width == 0 {
+        return 1;
+    }
+    let mut rows = 1;
+    let mut col = 0;
+    for c in text.chars() {
+        let w = char_cols(c);
+        if col + w > width && col > 0 {
+            rows += 1;
+            col = 0;
+        }
+        col += w;
+    }
+    rows
+}
+
+/// Char-offset ranges of every case-insensitive occurrence of `query` (already
+/// ASCII-lowercased) in the line's displayed text. Offsets are in chars so they
+/// align with `wrap_spans`' per-char highlight test.
+fn match_ranges(raw: &str, all_view: bool, query: &str) -> Vec<(usize, usize)> {
+    let mut ranges = Vec::new();
+    if query.is_empty() {
+        return ranges;
+    }
+    let hay: Vec<char> = display_text(raw, all_view)
+        .chars()
+        .map(|c| c.to_ascii_lowercase())
+        .collect();
+    let q: Vec<char> = query.chars().collect();
+    if hay.len() < q.len() {
+        return ranges;
+    }
+    let mut i = 0;
+    while i + q.len() <= hay.len() {
+        if hay[i..i + q.len()] == q[..] {
+            ranges.push((i, i + q.len()));
+            i += q.len();
+        } else {
+            i += 1;
+        }
+    }
+    ranges
+}
+
+/// Split one logical line's spans into display rows, pushing each row onto
+/// `out`. When `wrap` is off (or width 0) the line stays a single row — clipped
+/// at the edge by the renderer, as before. Contiguous same-style chars coalesce
+/// into one span. Chars whose char-offset falls in a `matches` range get the
+/// search-highlight style overlaid, so a match spanning a wrap boundary lights
+/// up on both rows.
+fn wrap_spans(
+    spans: Vec<Span<'static>>,
+    width: usize,
+    wrap: bool,
+    matches: Option<&[(usize, usize)]>,
+    out: &mut Vec<Line<'static>>,
+) {
+    let matches = matches.unwrap_or(&[]);
+    // Nothing to reflow or highlight: emit the spans as one row untouched.
+    if (!wrap || width == 0) && matches.is_empty() {
+        out.push(Line::from(spans));
+        return;
+    }
+
+    let in_match = |off: usize| matches.iter().any(|&(s, e)| off >= s && off < e);
+
+    let mut row: Vec<Span<'static>> = Vec::new();
+    let mut run = String::new();
+    let mut run_style: Option<Style> = None;
+    let mut col = 0usize;
+    let mut offset = 0usize;
+
+    for span in &spans {
+        let base = span.style;
+        for c in span.content.chars() {
+            let w = char_cols(c);
+            if wrap && width > 0 && col + w > width && col > 0 {
+                flush_run(&mut run, run_style.unwrap_or_default(), &mut row);
+                out.push(Line::from(std::mem::take(&mut row)));
+                col = 0;
+            }
+            let style = if in_match(offset) {
+                base.bg(MATCH_BG).fg(MATCH_FG).add_modifier(Modifier::BOLD)
+            } else {
+                base
+            };
+            if run_style != Some(style) {
+                flush_run(&mut run, run_style.unwrap_or_default(), &mut row);
+                run_style = Some(style);
+            }
+            run.push(c);
+            col += w;
+            offset += 1;
+        }
+    }
+    flush_run(&mut run, run_style.unwrap_or_default(), &mut row);
+    out.push(Line::from(row));
+}
+
+/// Emit the buffered same-style run as a span, clearing the buffer.
+fn flush_run(run: &mut String, style: Style, row: &mut Vec<Span<'static>>) {
+    if !run.is_empty() {
+        row.push(Span::styled(std::mem::take(run), style));
+    }
 }
 
 /// Parse a single line of possibly-ANSI text into owned spans, falling back to
@@ -251,3 +453,150 @@ fn status_color(st: &ProcStatus) -> Color {
         ProcStatus::Idle => MUTED,
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn rows(text: &str, width: usize, wrap: bool) -> Vec<String> {
+        let mut out = Vec::new();
+        wrap_spans(
+            vec![Span::raw(text.to_string())],
+            width,
+            wrap,
+            None,
+            &mut out,
+        );
+        out.iter()
+            .map(|l| l.spans.iter().map(|s| s.content.as_ref()).collect())
+            .collect()
+    }
+
+    #[test]
+    fn wrap_off_is_one_row() {
+        assert_eq!(rows("hello world", 4, false), vec!["hello world"]);
+        assert_eq!(row_count("hello world", 4, false), 1);
+    }
+
+    #[test]
+    fn wrap_splits_at_width_and_row_count_agrees() {
+        let text = "abcdefgh";
+        assert_eq!(rows(text, 3, true), vec!["abc", "def", "gh"]);
+        assert_eq!(row_count(text, 3, true), 3);
+    }
+
+    #[test]
+    fn wide_char_that_does_not_fit_wraps_first() {
+        // "a" then a 2-wide char into width 2: the wide char can't share the
+        // row with "a", so it starts the next one.
+        let rows = rows("a世", 2, true);
+        assert_eq!(rows, vec!["a", "世"]);
+        assert_eq!(row_count("a世", 2, true), 2);
+    }
+
+    #[test]
+    fn zero_width_join_does_not_add_a_row() {
+        // A trailing combining mark rides the last column, not a new row.
+        assert_eq!(row_count("abc\u{0301}", 3, true), 1);
+    }
+
+    #[test]
+    fn width_zero_never_panics() {
+        assert_eq!(rows("abc", 0, true), vec!["abc"]);
+        assert_eq!(row_count("abc", 0, true), 1);
+    }
+
+    #[test]
+    fn match_ranges_are_case_insensitive_char_offsets() {
+        assert_eq!(
+            match_ranges("Error: ERROR", false, "error"),
+            vec![(0, 5), (7, 12)]
+        );
+        assert_eq!(match_ranges("nope", false, "error"), vec![]);
+    }
+
+    /// Reference: wrap every line into one flat list, then slice the window —
+    /// the obvious-but-wasteful version `visible_rows` optimizes.
+    fn naive_visible(
+        lines: &[String],
+        width: usize,
+        height: usize,
+        wrap: bool,
+        scroll_back: usize,
+    ) -> Vec<String> {
+        let mut all: Vec<Line> = Vec::new();
+        for raw in lines {
+            wrap_spans(vec![Span::raw(raw.clone())], width, wrap, None, &mut all);
+        }
+        let total = all.len();
+        let back = scroll_back.min(total.saturating_sub(height));
+        let end = total.saturating_sub(back);
+        let start = end.saturating_sub(height);
+        all[start..end].iter().map(row_text).collect()
+    }
+
+    fn row_text(l: &Line) -> String {
+        l.spans.iter().map(|s| s.content.as_ref()).collect()
+    }
+
+    fn lazy_visible(
+        lines: &[String],
+        width: usize,
+        height: usize,
+        wrap: bool,
+        scroll_back: usize,
+    ) -> Vec<String> {
+        visible_rows(lines, false, width, height, wrap, scroll_back, None)
+            .iter()
+            .map(row_text)
+            .collect()
+    }
+
+    #[test]
+    fn lazy_slice_matches_naive_across_offsets() {
+        let lines: Vec<String> = (0..30).map(|i| format!("line{i:02}=abcdefghij")).collect();
+        for &wrap in &[false, true] {
+            for width in [6usize, 8, 40] {
+                for height in [1usize, 5, 12] {
+                    for back in [0usize, 3, 10, 25, 999] {
+                        assert_eq!(
+                            lazy_visible(&lines, width, height, wrap, back),
+                            naive_visible(&lines, width, height, wrap, back),
+                            "wrap={wrap} width={width} height={height} back={back}",
+                        );
+                    }
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn empty_and_short_buffers_do_not_panic() {
+        assert!(lazy_visible(&[], 10, 5, true, 0).is_empty());
+        let one = vec!["hi".to_string()];
+        assert_eq!(lazy_visible(&one, 10, 5, true, 0), vec!["hi"]);
+        assert_eq!(lazy_visible(&one, 10, 5, true, 99), vec!["hi"]);
+    }
+
+    #[test]
+    fn highlight_survives_a_wrap_boundary() {
+        // "error" at chars 2..7 straddles the width-4 wrap between rows.
+        let ranges = match_ranges("--error--", false, "error");
+        let mut out = Vec::new();
+        wrap_spans(
+            vec![Span::raw("--error--".to_string())],
+            4,
+            true,
+            Some(&ranges),
+            &mut out,
+        );
+        // Every row that overlaps the match must carry a highlighted span.
+        let highlighted: usize = out
+            .iter()
+            .flat_map(|l| &l.spans)
+            .filter(|s| s.style.bg == Some(MATCH_BG))
+            .map(|s| s.content.chars().count())
+            .sum();
+        assert_eq!(highlighted, 5); // all five chars of "error"
+    }
+}

dev/omnidev/src/update_check.rs

@@ -0,0 +1,228 @@
+//! Daily update check for a git-installed omnigent.
+//!
+//! Fills a real gap: omnigent's own update notice only works for PyPI-wheel
+//! installs and bails on VCS installs. The hot path (`check`) never blocks on
+//! the network — it reads a cache and spawns a detached `refresh` when stale.
+
+use std::io::{IsTerminal, Write};
+use std::process::{Command, Stdio};
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use anyhow::{Context, Result};
+use serde::{Deserialize, Serialize};
+
+use crate::install::{self, InstallConfig};
+use crate::paths;
+
+const STALE_SECS: u64 = 24 * 60 * 60;
+const LS_REMOTE_TIMEOUT_SECS: u64 = 5;
+
+/// Volatile update-check state cached between runs.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct CheckCache {
+    #[serde(default)]
+    pub last_checked: u64,
+    #[serde(default)]
+    pub remote_sha: Option<String>,
+    #[serde(default)]
+    pub installed_sha: Option<String>,
+    /// The remote sha we already prompted about, so a declined update isn't
+    /// re-nagged until a newer commit lands.
+    #[serde(default)]
+    pub last_prompted_sha: Option<String>,
+}
+
+impl CheckCache {
+    pub fn load() -> CheckCache {
+        let Ok(path) = paths::check_cache_path() else {
+            return CheckCache::default();
+        };
+        std::fs::read_to_string(&path)
+            .ok()
+            .and_then(|t| serde_json::from_str(&t).ok())
+            .unwrap_or_default()
+    }
+
+    pub fn save(&self) -> Result<()> {
+        let path = paths::check_cache_path()?;
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent)
+                .with_context(|| format!("creating {}", parent.display()))?;
+        }
+        let text = serde_json::to_string_pretty(self).context("serializing check cache")?;
+        std::fs::write(&path, text).with_context(|| format!("writing {}", path.display()))?;
+        Ok(())
+    }
+}
+
+/// Whether the cache indicates an update the user hasn't already declined.
+/// Pure so it can be unit-tested without touching disk or the network.
+///
+/// `installed` is the best-known installed commit (dist-info first, else the
+/// cached `installed_sha`). An update is available when we have a remote sha
+/// that differs from what's installed and that we haven't already prompted for.
+pub fn update_available(cache: &CheckCache, installed: Option<&str>) -> bool {
+    let Some(remote) = cache.remote_sha.as_deref() else {
+        return false;
+    };
+    if Some(remote) == installed {
+        return false;
+    }
+    if cache.last_prompted_sha.as_deref() == Some(remote) {
+        return false;
+    }
+    true
+}
+
+/// Whether `last_checked` is older than the staleness window.
+pub fn is_stale(cache: &CheckCache, now: u64) -> bool {
+    now.saturating_sub(cache.last_checked) > STALE_SECS
+}
+
+fn now_epoch() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_secs())
+        .unwrap_or(0)
+}
+
+/// The remote HEAD sha of `git_ref` in `repo`, via `git ls-remote` (targets the
+/// remote, so no local checkout is needed). `None` on any failure/timeout.
+pub fn remote_sha(repo: &str, git_ref: &str) -> Option<String> {
+    // `timeout` isn't portable (absent on macOS by default), so bound the call
+    // with git's own connect timeout and a wait guard instead.
+    let mut child = Command::new("git")
+        .args(["ls-remote", repo, git_ref])
+        .env("GIT_TERMINAL_PROMPT", "0")
+        .stdout(Stdio::piped())
+        .stderr(Stdio::null())
+        .stdin(Stdio::null())
+        .spawn()
+        .ok()?;
+
+    let deadline = SystemTime::now() + Duration::from_secs(LS_REMOTE_TIMEOUT_SECS);
+    loop {
+        match child.try_wait().ok()? {
+            Some(_) => break,
+            None => {
+                if SystemTime::now() > deadline {
+                    let _ = child.kill();
+                    return None;
+                }
+                std::thread::sleep(Duration::from_millis(100));
+            }
+        }
+    }
+    let output = child.wait_with_output().ok()?;
+    if !output.status.success() {
+        return None;
+    }
+    let text = String::from_utf8(output.stdout).ok()?;
+    // First whitespace-delimited token of the first line is the sha.
+    text.lines()
+        .next()
+        .and_then(|l| l.split_whitespace().next())
+        .map(str::to_string)
+}
+
+/// Record the installed sha into the cache (called after install/update).
+pub fn set_installed_sha(sha: &str) -> Result<()> {
+    let mut cache = CheckCache::load();
+    cache.installed_sha = Some(sha.to_string());
+    cache.save()
+}
+
+/// `refresh` subcommand: hit the network, update `remote_sha` + `last_checked`.
+/// Invoked detached by `check`, but also runnable directly.
+pub fn refresh() -> Result<()> {
+    let config = InstallConfig::load()?.unwrap_or_default();
+    let mut cache = CheckCache::load();
+    cache.remote_sha = remote_sha(&config.repo, &config.git_ref);
+    cache.last_checked = now_epoch();
+    cache.save()
+}
+
+/// Best-known installed commit: the tool's dist-info first (authoritative),
+/// else the sha we recorded at install time.
+fn installed_commit(cache: &CheckCache) -> Option<String> {
+    install::installed_commit().or_else(|| cache.installed_sha.clone())
+}
+
+/// `check` subcommand: the fast hook primitive. Never blocks on the network.
+///
+/// - Stale cache ⇒ spawn a detached `refresh` and return.
+/// - An available update ⇒ notice; on a TTY, prompt and update in the
+///   foreground on yes, else record the decline.
+/// - `quiet` suppresses the "up to date" path so shell startup stays silent.
+pub fn check(quiet: bool) -> Result<()> {
+    let cache = CheckCache::load();
+
+    if is_stale(&cache, now_epoch()) {
+        spawn_detached_refresh();
+        // Still evaluate against whatever we already had cached.
+    }
+
+    let installed = installed_commit(&cache);
+    if !update_available(&cache, installed.as_deref()) {
+        if !quiet {
+            println!("omnigent is up to date.");
+        }
+        return Ok(());
+    }
+
+    let remote = cache.remote_sha.clone().unwrap_or_default();
+    let short = |s: &str| s.chars().take(8).collect::<String>();
+    let installed_desc = installed
+        .as_deref()
+        .map(short)
+        .unwrap_or_else(|| "unknown".to_string());
+    eprintln!(
+        "omnigent update available: {} → {} (git)",
+        installed_desc,
+        short(&remote),
+    );
+
+    // Only prompt on an interactive terminal; scripts/CI just see the notice.
+    if !(std::io::stdin().is_terminal() && std::io::stderr().is_terminal()) {
+        return Ok(());
+    }
+
+    if prompt_yes_no("Update omnigent now? [y/N] ") {
+        install::update()?;
+    } else {
+        // Don't re-nag for this same commit.
+        let mut cache = CheckCache::load();
+        cache.last_prompted_sha = Some(remote);
+        cache.save()?;
+    }
+    Ok(())
+}
+
+/// Prompt on the controlling terminal. Reads from `/dev/tty` so it works even
+/// when the hook's stdin is redirected. Any read failure ⇒ treated as "no".
+fn prompt_yes_no(prompt: &str) -> bool {
+    use std::io::BufRead;
+    let Ok(tty) = std::fs::OpenOptions::new().read(true).open("/dev/tty") else {
+        return false;
+    };
+    eprint!("{prompt}");
+    let _ = std::io::stderr().flush();
+    let mut line = String::new();
+    if std::io::BufReader::new(tty).read_line(&mut line).is_err() {
+        return false;
+    }
+    matches!(line.trim().to_ascii_lowercase().as_str(), "y" | "yes")
+}
+
+/// Launch `omnidev refresh` fully detached so shell startup never waits on it.
+fn spawn_detached_refresh() {
+    let Ok(exe) = std::env::current_exe() else {
+        return;
+    };
+    let _ = Command::new(exe)
+        .arg("refresh")
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .spawn();
+}

dev/omnidev/src/watcher.rs

@@ -3,24 +3,38 @@
 //! handles those.
 
 use std::path::Path;
+use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
 use anyhow::{Context, Result};
+use ignore::gitignore::{Gitignore, GitignoreBuilder};
 use notify::RecursiveMode;
 use notify_debouncer_full::new_debouncer;
 use tokio::sync::mpsc;
 
+use crate::state::Shared;
 use crate::supervisor::Cmd;
 
 /// Start watching `omnigent_dir` for `*.py` changes. Coalesced bursts become a
 /// single `Cmd::Reload(n)` on `cmd_tx`. The returned debouncer must be kept
 /// alive for the watch to persist.
+///
+/// Gitignored files (e.g. the build-time `omnigent/_build_info.py`) are skipped
+/// so churn from generated files doesn't trigger reloads. With `debug` on, every
+/// observed change is logged with whether it triggered a reload or why it was
+/// skipped.
 pub fn spawn(
+    repo_root: &Path,
     omnigent_dir: &Path,
+    shared: Arc<Mutex<Shared>>,
+    debug: bool,
     cmd_tx: mpsc::UnboundedSender<Cmd>,
 ) -> Result<impl Send + 'static> {
-    // The debouncer coalesces rapid saves; we still filter to *.py and skip
-    // caches so editor churn and __pycache__ writes don't trigger reloads.
+    let ignore = build_ignore(repo_root);
+    let repo_root = repo_root.to_path_buf();
+
+    // The debouncer coalesces rapid saves; we still filter to *.py, skip caches
+    // and gitignored files so editor churn and generated writes don't reload.
     let mut debouncer = new_debouncer(
         Duration::from_millis(500),
         None,
@@ -29,8 +43,18 @@ pub fn spawn(
             let mut changed = 0usize;
             for event in &events {
                 for path in &event.paths {
-                    if is_relevant(path) {
-                        changed += 1;
+                    match classify(path, &ignore) {
+                        Ok(()) => {
+                            changed += 1;
+                            if debug {
+                                log_watch(&shared, &repo_root, path, "reload trigger");
+                            }
+                        }
+                        Err(reason) => {
+                            if debug {
+                                log_watch(&shared, &repo_root, path, &format!("skip ({reason})"));
+                            }
+                        }
                     }
                 }
             }
@@ -48,9 +72,95 @@ pub fn spawn(
     Ok(debouncer)
 }
 
-fn is_relevant(path: &Path) -> bool {
-    if path.extension().and_then(|e| e.to_str()) != Some("py") {
-        return false;
-    }
-    !path.components().any(|c| c.as_os_str() == "__pycache__")
+/// Build a gitignore matcher from the repo's root `.gitignore` and
+/// `.git/info/exclude`. Both are best-effort — a missing or malformed file just
+/// contributes no rules. Nested `.gitignore` files under `omnigent/` are not
+/// consulted (the repo has none today); add them here if that changes.
+fn build_ignore(repo_root: &Path) -> Gitignore {
+    let mut b = GitignoreBuilder::new(repo_root);
+    b.add(repo_root.join(".gitignore"));
+    b.add(repo_root.join(".git").join("info").join("exclude"));
+    b.build().unwrap_or_else(|_| Gitignore::empty())
+}
+
+/// Decide whether a changed path should trigger a reload, or why not. The `Err`
+/// carries a short reason for the `--debug` log.
+fn classify(path: &Path, ignore: &Gitignore) -> Result<(), &'static str> {
+    if path.extension().and_then(|e| e.to_str()) != Some("py") {
+        return Err("non-.py");
+    }
+    if path.components().any(|c| c.as_os_str() == "__pycache__") {
+        return Err("__pycache__");
+    }
+    // `_or_any_parents` so files inside a gitignored directory (build/, dist/,
+    // *.egg-info/, …) are skipped too, matching git's own behavior — plain
+    // `matched` only catches paths named by a rule directly.
+    if ignore.matched_path_or_any_parents(path, false).is_ignore() {
+        return Err("gitignored");
+    }
+    Ok(())
+}
+
+/// Emit a `--debug` watch line into the combined pane, path shown relative to
+/// the repo root when possible.
+fn log_watch(shared: &Arc<Mutex<Shared>>, repo_root: &Path, path: &Path, what: &str) {
+    let rel = path.strip_prefix(repo_root).unwrap_or(path);
+    shared
+        .lock()
+        .unwrap()
+        .event(format!("watch: {what} {}", rel.display()));
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn ignore_with(line: &str) -> Gitignore {
+        let mut b = GitignoreBuilder::new("/repo");
+        b.add_line(None, line).unwrap();
+        b.build().unwrap()
+    }
+
+    #[test]
+    fn plain_python_file_triggers_reload() {
+        let ig = ignore_with("omnigent/_build_info.py");
+        assert_eq!(classify(Path::new("/repo/omnigent/cli.py"), &ig), Ok(()));
+    }
+
+    #[test]
+    fn gitignored_python_file_is_skipped() {
+        let ig = ignore_with("omnigent/_build_info.py");
+        assert_eq!(
+            classify(Path::new("/repo/omnigent/_build_info.py"), &ig),
+            Err("gitignored")
+        );
+    }
+
+    #[test]
+    fn file_inside_gitignored_dir_is_skipped() {
+        // A directory rule must ignore everything beneath it, like git does.
+        let ig = ignore_with("build/");
+        assert_eq!(
+            classify(Path::new("/repo/omnigent/build/foo.py"), &ig),
+            Err("gitignored")
+        );
+    }
+
+    #[test]
+    fn non_python_file_is_skipped() {
+        let ig = ignore_with("omnigent/_build_info.py");
+        assert_eq!(
+            classify(Path::new("/repo/omnigent/notes.txt"), &ig),
+            Err("non-.py")
+        );
+    }
+
+    #[test]
+    fn pycache_file_is_skipped() {
+        let ig = ignore_with("omnigent/_build_info.py");
+        assert_eq!(
+            classify(Path::new("/repo/omnigent/__pycache__/cli.py"), &ig),
+            Err("__pycache__")
+        );
+    }
 }

dev/omnidev/tests/install_mgmt.rs

@@ -0,0 +1,151 @@
+//! Exercises install-management logic without network or a real install:
+//! spec building, config round-trip, and the update-availability/staleness
+//! decisions.
+
+use std::sync::{Mutex, MutexGuard};
+
+// These modules reference each other via `crate::`, so declare the whole set at
+// the test crate root. Each test target exercises only part of the included
+// source, so allow dead code rather than chase per-item warnings.
+#[allow(dead_code)]
+#[path = "../src/install.rs"]
+mod install;
+#[allow(dead_code)]
+#[path = "../src/paths.rs"]
+mod paths;
+#[allow(dead_code)]
+#[path = "../src/update_check.rs"]
+mod update_check;
+
+use install::InstallConfig;
+use update_check::{is_stale, update_available, CheckCache};
+
+/// Tests here mutate process-global `XDG_*` env vars; serialize them.
+static ENV_LOCK: Mutex<()> = Mutex::new(());
+
+fn lock_env() -> MutexGuard<'static, ()> {
+    ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner())
+}
+
+#[test]
+fn spec_default_has_databricks_extra_and_main() {
+    let c = InstallConfig::default();
+    assert_eq!(
+        c.spec(),
+        "omnigent[databricks] @ git+https://github.com/omnigent-ai/omnigent.git@main"
+    );
+}
+
+#[test]
+fn spec_no_extras_is_bare_git_url() {
+    let c = InstallConfig {
+        repo: "https://github.com/omnigent-ai/omnigent.git".into(),
+        git_ref: "main".into(),
+        extras: vec![],
+    };
+    assert_eq!(
+        c.spec(),
+        "git+https://github.com/omnigent-ai/omnigent.git@main"
+    );
+}
+
+#[test]
+fn spec_reflects_custom_ref_and_extras() {
+    let c = InstallConfig {
+        repo: "https://example.com/x.git".into(),
+        git_ref: "dev".into(),
+        extras: vec!["databricks".into(), "kubernetes".into()],
+    };
+    assert_eq!(
+        c.spec(),
+        "omnigent[databricks,kubernetes] @ git+https://example.com/x.git@dev"
+    );
+}
+
+#[test]
+fn config_round_trips_through_disk() {
+    let _guard = lock_env();
+    let tmp = tempdir();
+    std::env::set_var("XDG_CONFIG_HOME", &tmp);
+
+    let c = InstallConfig {
+        repo: "https://github.com/omnigent-ai/omnigent.git".into(),
+        git_ref: "main".into(),
+        extras: vec!["databricks".into()],
+    };
+    c.save().unwrap();
+    let loaded = InstallConfig::load().unwrap().expect("config present");
+    assert_eq!(c, loaded);
+
+    std::env::remove_var("XDG_CONFIG_HOME");
+}
+
+#[test]
+fn missing_config_loads_as_none() {
+    let _guard = lock_env();
+    let tmp = tempdir();
+    std::env::set_var("XDG_CONFIG_HOME", &tmp);
+
+    assert!(InstallConfig::load().unwrap().is_none());
+
+    std::env::remove_var("XDG_CONFIG_HOME");
+}
+
+#[test]
+fn update_available_logic() {
+    let cache = CheckCache {
+        remote_sha: Some("bbbb".into()),
+        ..Default::default()
+    };
+    // Remote differs from installed and wasn't prompted → available.
+    assert!(update_available(&cache, Some("aaaa")));
+    // Installed already matches remote → not available.
+    assert!(!update_available(&cache, Some("bbbb")));
+    // No remote sha known → not available.
+    assert!(!update_available(&CheckCache::default(), Some("aaaa")));
+
+    // Declining a commit (last_prompted_sha == remote) suppresses it.
+    let declined = CheckCache {
+        remote_sha: Some("bbbb".into()),
+        last_prompted_sha: Some("bbbb".into()),
+        ..Default::default()
+    };
+    assert!(!update_available(&declined, Some("aaaa")));
+}
+
+#[test]
+fn staleness_window() {
+    let now = 1_000_000u64;
+    let day = 24 * 60 * 60;
+
+    let fresh = CheckCache {
+        last_checked: now - 10,
+        ..Default::default()
+    };
+    assert!(!is_stale(&fresh, now));
+
+    let old = CheckCache {
+        last_checked: now - day - 1,
+        ..Default::default()
+    };
+    assert!(is_stale(&old, now));
+
+    // Never checked (last_checked == 0) → stale.
+    assert!(is_stale(&CheckCache::default(), now));
+}
+
+/// Minimal unique temp dir without pulling a dev-dependency.
+fn tempdir() -> std::path::PathBuf {
+    let base = std::env::temp_dir();
+    let unique = format!(
+        "omnidev-mgmt-{}-{}",
+        std::process::id(),
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos()
+    );
+    let dir = base.join(unique);
+    std::fs::create_dir_all(&dir).unwrap();
+    dir
+}

dev/omnidev/tests/pod_setup.rs

@@ -1,15 +1,24 @@
 //! Exercises the non-TUI setup path: repo detection, pod dir tree, ports.
 
 use std::fs;
+use std::sync::{Mutex, MutexGuard};
 
-// The crate is a binary, so pull in the modules under test directly.
+// The crate is a binary, so pull in the modules under test directly. Each test
+// target uses only part of the included source, so allow dead code.
+#[allow(dead_code)]
 #[path = "../src/lock.rs"]
 mod lock;
+#[allow(dead_code)]
 #[path = "../src/paths.rs"]
 mod paths;
+#[allow(dead_code)]
+#[path = "../src/pod.rs"]
+mod pod;
+#[allow(dead_code)]
 #[path = "../src/ports.rs"]
 mod ports;
 
+use pod::Pod;
 use ports::Ports;
 
 /// A fake checkout (.git + omnigent/ + web/) is recognized as a root, and a
@@ -43,6 +52,40 @@ fn pod_dir_is_per_repo_and_stable() {
     assert_ne!(a1, b);
 }
 
+/// npm install is needed when node_modules is missing, and when a manifest is
+/// newer than it; not needed when node_modules is up to date.
+#[test]
+fn needs_npm_install_tracks_manifests() {
+    let repo = tempdir();
+    let web = repo.join("web");
+    fs::create_dir_all(&web).unwrap();
+    fs::write(web.join("package.json"), "{}").unwrap();
+
+    let pod = Pod {
+        repo_root: repo.clone(),
+        dir: repo.join("pod"),
+        ports: Ports {
+            server: 6767,
+            vite: 5173,
+        },
+        vite_host: "127.0.0.1".into(),
+        trusted_origins: Vec::new(),
+    };
+
+    // No node_modules yet → install needed.
+    assert!(pod.needs_npm_install());
+
+    // Fresh node_modules created after the manifest → up to date.
+    fs::create_dir_all(web.join("node_modules")).unwrap();
+    assert!(!pod.needs_npm_install());
+
+    // A manifest touched after node_modules → stale, install needed.
+    // (Sleep briefly so the mtime is observably newer on coarse filesystems.)
+    std::thread::sleep(std::time::Duration::from_millis(10));
+    fs::write(web.join("package-lock.json"), "{}").unwrap();
+    assert!(pod.needs_npm_install());
+}
+
 /// Ports probe to bindable values and persist/reuse across calls.
 #[test]
 fn ports_resolve_and_persist() {
@@ -98,6 +141,92 @@ fn pod_lock_is_exclusive() {
     lock::acquire(&pod).expect("acquire succeeds again after release");
 }
 
+const ALLOWED_ORIGINS_ENV: &str = "OMNIGENT_WS_ALLOWED_ORIGINS";
+
+/// Tests that read/write the process-global allowlist env var; serialize them.
+static ENV_LOCK: Mutex<()> = Mutex::new(());
+
+fn lock_env() -> MutexGuard<'static, ()> {
+    ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner())
+}
+
+/// Run `body` with `OMNIGENT_WS_ALLOWED_ORIGINS` set to `value` (or unset when
+/// `None`), restoring the prior value afterward so tests don't leak env state.
+fn with_allowlist_env(value: Option<&str>, body: impl FnOnce()) {
+    let _guard = lock_env();
+    let prev = std::env::var(ALLOWED_ORIGINS_ENV).ok();
+    match value {
+        Some(v) => std::env::set_var(ALLOWED_ORIGINS_ENV, v),
+        None => std::env::remove_var(ALLOWED_ORIGINS_ENV),
+    }
+    body();
+    match prev {
+        Some(v) => std::env::set_var(ALLOWED_ORIGINS_ENV, v),
+        None => std::env::remove_var(ALLOWED_ORIGINS_ENV),
+    }
+}
+
+fn pod_with_trusted(trusted: Vec<String>) -> Pod {
+    Pod {
+        repo_root: std::path::PathBuf::from("/repo"),
+        dir: std::path::PathBuf::from("/pod"),
+        ports: Ports {
+            server: 6767,
+            vite: 5173,
+        },
+        vite_host: "0.0.0.0".into(),
+        trusted_origins: trusted,
+    }
+}
+
+fn allowlist_from_env(pod: &Pod) -> Option<String> {
+    pod.env()
+        .into_iter()
+        .find(|(k, _)| k == ALLOWED_ORIGINS_ENV)
+        .map(|(_, v)| v)
+}
+
+/// With no trusted origins, the pod leaves the allowlist var untouched — even
+/// when the developer's shell already exports one (it passes through inherited).
+#[test]
+fn no_trusted_origins_does_not_set_allowlist() {
+    with_allowlist_env(Some("https://dev.example.com"), || {
+        let pod = pod_with_trusted(Vec::new());
+        assert_eq!(allowlist_from_env(&pod), None);
+    });
+}
+
+/// Trusted origins with no inherited value produce exactly those origins.
+#[test]
+fn trusted_origins_populate_allowlist() {
+    with_allowlist_env(None, || {
+        let pod = pod_with_trusted(vec!["http://192.168.1.42:5173".into()]);
+        assert_eq!(
+            allowlist_from_env(&pod).as_deref(),
+            Some("http://192.168.1.42:5173")
+        );
+    });
+}
+
+/// A developer's inherited allowlist is preserved and the LAN origins are
+/// appended (order-preserving, deduped) rather than clobbered.
+#[test]
+fn trusted_origins_merge_with_inherited_allowlist() {
+    with_allowlist_env(
+        Some("https://dev.example.com, http://192.168.1.42:5173"),
+        || {
+            let pod = pod_with_trusted(vec![
+                "http://192.168.1.42:5173".into(), // already inherited → not duplicated
+                "http://10.0.0.9:5173".into(),
+            ]);
+            assert_eq!(
+                allowlist_from_env(&pod).as_deref(),
+                Some("https://dev.example.com,http://192.168.1.42:5173,http://10.0.0.9:5173")
+            );
+        },
+    );
+}
+
 /// Minimal unique temp dir without pulling a dev-dependency.
 fn tempdir() -> std::path::PathBuf {
     let base = std::env::temp_dir();

docs/UNINSTALL_DESIGN.md

@@ -0,0 +1,591 @@
+# Omnigent Uninstaller Design
+
+Status: Implemented in PR #2550
+Owner: Pat Sukprasert (@PattaraS)
+Related discussion: brainstormed and debated via Debby (claude + gpt partners)
+
+Implementation note: PR #2550 ships the OSS CLI/script implementation as one
+combined PR rather than the staged PR breakdown below. Checkboxes marked here
+reflect the current implementation and focused test coverage in that PR.
+
+This document specifies how Omnigent should be uninstalled. It is written to be
+handed to an implementer without further design decisions. Track delivery with
+the checklists in each section.
+
+## 1. Overview and scope
+
+Ship four coupled pieces around one shared removal codepath:
+
+1. `scripts/uninstall_oss.sh` - pure POSIX `sh`, the actual removal logic. Works
+   even when the wheel is wedged or PATH is broken; usable via curl-pipe.
+2. `omnigent uninstall` - the discoverable CLI entry. It performs graceful
+   process shutdown and state/JSON handling in Python, then execs
+   `uninstall_oss.sh` for the final self-removal steps. One implementation, two
+   entry points.
+3. Install-side ledger writer - records what the installer did to
+   `~/.omnigent/install_ledger.json`.
+4. Back-fill routine - reconstructs a ledger as observed evidence (never
+   invented memory) for the pre-ledger install base.
+
+Out of scope: any cross-domain "reaper" spanning the wheel, the signed `.app`,
+and mobile sandboxes. App-store surfaces (iOS/Android/Electron) use OS-native
+uninstall and only point the user back at `omnigent uninstall --purge` for
+`~/.omnigent`. Shared runtimes (uv/Node/tmux/bwrap) are report-only in this
+version - never removed, even with `--yes`.
+
+Design principles that recur below:
+
+- Remove only what we own; report everything else.
+- Preserve user data by default; destruction is a separate, explicit intent.
+- Risk is a property of the artifact, not of how we learned about it.
+- Stop before you delete.
+- Idempotent by state-check, not error-swallowing.
+
+## 2. install_ledger.json schema
+
+- Path: `~/.omnigent/install_ledger.json`
+- Mode: `0600` (local paths; treat as sensitive)
+- Write: atomic - write `install_ledger.json.tmp` in the same dir, `fsync`,
+  `rename()` over target.
+- `schema_version`: `1` for first ship. Bump on any breaking change.
+
+### Top level
+
+| Field | Type | Allowed / notes |
+|---|---|---|
+| `schema_version` | int | `1`. |
+| `ledger_source` | enum | `installer` \| `backfill`. A backfill ledger never overwrites an installer one. |
+| `generator` | object | `{name, version, strategy, os, wrote_at}`; `strategy` = `install` \| `fast-backfill` \| `deep-backfill`; `os` = `macos` \| `linux`. |
+| `installation_id` | string \| null | Copied from `~/.omnigent/installation_id`; the anchor proving an install exists. |
+| `created_at` / `updated_at` / `last_validated_at` | string | RFC3339 UTC. |
+| `entries` | object | The reversible-action records (below). |
+
+### Per-entry provenance (every entry carries both)
+
+- `source`: `recorded` (installer saw itself act) \| `observed` (backfill saw
+  the artifact directly) \| `inferred` (backfill deduced it).
+- `confidence`: `certain` \| `high` \| `medium` \| `low` \| `none`.
+
+### entries sub-objects
+
+`profiles` (array) - shell profiles that received the delimited PATH block:
+`path`, `marker_begin` (`# >>> Omnigent installer >>>`), `marker_end`
+(`# <<< Omnigent installer <<<`), `line_range` [int,int] (1-indexed inclusive,
+advisory - removal re-locates by marker), `block_sha256` (of block text incl.
+markers, for tamper detection), `content_matches_current` (bool), `source`,
+`confidence`.
+
+`injected_external_config` (array) - entries Omnigent wrote into third-party
+files: `path`, `marker` (logical key, e.g. `mcp_servers.omnigent`), `format`
+(`json` \| `toml` \| `delimited_block`), `allowlist` (array of exact key paths /
+block markers we may remove - removal touches ONLY these), `block_sha256`
+(\| null), `source`, `confidence`.
+
+`deps` (object keyed by `uv`/`node`/`npm`/`tmux`/`bwrap`): `present` (bool),
+`path` (\| null), `version` (\| null), `installed_by` (`omnigent` - only ever set
+by a real installer that did the install; \| `preexisting` \| `unknown` -
+backfill may only write `unknown`), `confidence` (`none` whenever
+`installed_by=="unknown"`), optional `notes` (weak human hint, never actioned).
+
+`wheel` (object): `installed` (bool), `uv_tool_dir` (\| null), `bin_dir`
+(\| null, e.g. `~/.local/bin`), `console_scripts` (array, e.g.
+`["omnigent","omni"]`), `source`, `confidence`.
+
+`launch_agents` (array): `kind` (`launchd` \| `systemd_user`), `path`, `label`,
+`source`, `confidence`.
+
+`state_paths` (object, informational, only removed under `--purge`):
+`omnigent_home` (`~/.omnigent`), `workspace` (`~/omnigent`), `desktop_data`
+(array of observed Electron dirs).
+
+### Annotated example
+
+```json
+{
+  "schema_version": 1,
+  "ledger_source": "installer",
+  "installation_id": "b1f3c9a2-7e40-4c11-9d2a-3f6e8c0a1b22",
+  "created_at": "2026-07-14T18:03:22Z",
+  "updated_at": "2026-07-14T18:03:22Z",
+  "last_validated_at": "2026-07-14T18:03:22Z",
+  "generator": { "name": "omnigent", "version": "1.42.0", "strategy": "install", "os": "macos", "wrote_at": "2026-07-14T18:03:22Z" },
+  "entries": {
+    "profiles": [
+      { "path": "~/.zshrc", "marker_begin": "# >>> Omnigent installer >>>", "marker_end": "# <<< Omnigent installer <<<",
+        "line_range": [212, 215], "block_sha256": "9f2c...e1", "content_matches_current": true,
+        "source": "recorded", "confidence": "certain" }
+    ],
+    "injected_external_config": [
+      { "path": "~/.config/harness/hermes.json", "marker": "mcp_servers.omnigent", "format": "json",
+        "allowlist": ["mcp_servers.omnigent"], "block_sha256": null, "source": "recorded", "confidence": "certain" }
+    ],
+    "deps": {
+      "uv":   { "present": true, "path": "~/.local/bin/uv", "version": "0.5.11", "installed_by": "omnigent",    "confidence": "high" },
+      "node": { "present": true, "path": "/usr/bin/node",   "version": "22.3.0", "installed_by": "preexisting", "confidence": "high" }
+    },
+    "wheel": { "installed": true, "uv_tool_dir": "~/.local/share/uv/tools/omnigent", "bin_dir": "~/.local/bin",
+               "console_scripts": ["omnigent","omni"], "source": "recorded", "confidence": "certain" },
+    "launch_agents": [
+      { "kind": "launchd", "path": "~/Library/LaunchAgents/dev.omnigent.daemon.plist", "label": "dev.omnigent.daemon",
+        "source": "recorded", "confidence": "certain" }
+    ],
+    "state_paths": { "omnigent_home": "~/.omnigent", "workspace": "~/omnigent", "desktop_data": [] }
+  }
+}
+```
+
+Checklist:
+
+- [x] Schema documented and versioned (`schema_version = 1`)
+- [x] Atomic writer (tmp + fsync + rename) with `0600` mode
+- [x] Serializer / dataclass with round-trip unit tests
+- [x] `omnigent _internal write-ledger --from-env` hidden subcommand
+
+## 3. Install-side ledger writer
+
+Hook point: in `scripts/install_oss.sh`, after all side effects succeed and
+before `print_next_steps`. Since the installer is the source of truth, prefer
+having it call the hidden serializer subcommand
+`omnigent _internal write-ledger --from-env` (reuses the schema serializer, gets
+atomic-write + `0600` for free) rather than hand-building JSON in `sh`. Provide a
+`write_install_ledger` shell wrapper.
+
+Records (all `source: recorded`): each profile actually edited (path, markers,
+current `line_range`, `block_sha256`); each external-config injection (path,
+marker, format, allowlist); the wheel install (`uv tool dir`, bin dir, console
+scripts); deps the installer itself installed this run get
+`installed_by: omnigent` + version, deps found already present get
+`preexisting`; any LaunchAgent/systemd unit registered; `installation_id`;
+`state_paths`. Do not shell out to package managers for versions - cheap
+`--version` only.
+
+Upgrade / repair sync:
+
+1. If existing ledger is `backfill`, discard and write a fresh `installer`
+   ledger (a real record supersedes inference).
+2. If `installer`, merge: refresh `block_sha256`/`line_range` for re-touched
+   profiles, refresh wheel/dep versions, add newly-injected external config,
+   bump `generator.version` + `updated_at`.
+3. Never downgrade `installed_by` (`uv: omnigent` stays even if uv is now found
+   pre-present).
+4. Atomic write.
+
+Checklist:
+
+- [x] `write_install_ledger` hooked into `scripts/install_oss.sh` (post
+      side-effects, pre next-steps)
+- [x] Records profiles, external config, wheel, deps, launch agents, state paths
+- [x] Upgrade/repair merge logic (backfill superseded by installer; never
+      downgrade `installed_by`)
+- [x] Tests: fresh install, upgrade, backfill-superseded-by-installer
+
+## 4. Back-fill routine
+
+Reconstruction = observe current state, record with per-field confidence, never
+invent provenance.
+
+Anchor guard (refuse to fabricate): before writing anything, require at least
+one genuine install signal: `~/.omnigent/installation_id` exists, OR the wheel
+is installed (`uv tool list` shows `omnigent`), OR a known profile contains the
+exact marker pair. If none, write nothing and report "no Omnigent install
+detected."
+
+Fast vs deep:
+
+- Fast (startup, target <100ms, no package-manager subprocesses): stat the
+  ledger; if valid, return. Else cheap checks only - stat `installation_id`,
+  read + in-process scan of candidate profiles for markers (no shelling out to
+  `grep`), stat known `~/.omnigent` subdirs, existence checks for Electron
+  dirs. Mark wheel/deps `confidence: low` or omit; `generator.strategy =
+  fast-backfill`. Never spawn `uv`/`command -v` on the hot path.
+- Deep (uninstall / doctor, no budget): fast steps plus `uv tool list`/
+  `uv tool dir`, `command -v omnigent omni uv node tmux bwrap`, version
+  resolution, allowlisted external-config marker scans, LaunchAgent/systemd
+  enumeration. `generator.strategy = deep-backfill`.
+
+Per-field confidence assignment:
+
+| Signal | source | confidence |
+|---|---|---|
+| PATH block present (marker match) | observed | certain |
+| PATH block present, content != current | observed | certain (flag `content_matches_current:false`) |
+| Wheel / bin dir / console scripts | observed | high |
+| `~/.omnigent`, `installation_id` | observed | high |
+| LaunchAgent by known label | observed | high |
+| Injected external config (marker block) | observed | certain |
+| Injected external config (header fingerprint, no marker) | inferred | medium |
+| Any dep `installed_by` | inferred | unknown / none |
+
+Dependency `installed_by` is unrecoverable by design: backfill may write
+`present`/`path`/`version` but MUST write `installed_by: unknown`,
+`confidence: none`. A `notes` hint is allowed for `--dry-run` readers but never
+changes behavior.
+
+Never-overwrite-real + double-ledger:
+
+- If existing ledger is `installer`, backfill does nothing, ever.
+- Backfill writes to `~/.omnigent/install_ledger.backfill.json`, not directly
+  over `install_ledger.json`.
+- Uninstaller ledger resolution: use `install_ledger.json` if `installer`; else
+  use `install_ledger.backfill.json` if present; else run deep backfill on the
+  fly.
+- Re-run replaces the backfill file only if content differs; else bump
+  `last_validated_at`.
+
+Read-only-except-the-ledger: backfill never edits profiles, removes deps, or
+stops processes. It only reads and writes the (backfill) ledger.
+
+Triggers: eager fast-backfill on first CLI run when missing; lazy deep-backfill
+at uninstall when missing; explicit
+`omnigent doctor --migrate-ledger [--deep]` which prints a JSON diff and writes
+only with `--apply`.
+
+Checklist:
+
+- [x] Fast reconstruction (<100ms, no package-manager subprocesses, in-process
+      marker scan) on startup when missing
+- [x] Deep reconstruction at uninstall / doctor
+- [x] Anchor guard (refuse to fabricate without an install signal)
+- [x] Per-field confidence assignment per table
+- [x] Never-overwrite-real + `install_ledger.backfill.json` double-ledger handling
+- [x] `omnigent doctor --migrate-ledger [--deep] [--apply]`
+- [x] Read-only-except-the-ledger guarantee (tested)
+
+## 5. omnigent uninstall CLI
+
+`omnigent uninstall [targets...] [flags...]` (execs `scripts/uninstall_oss.sh`
+with the same args). Fallback: `scripts/uninstall_oss.sh [targets...]
+[flags...]`.
+
+Targets (default `cli` if none given):
+
+- `cli` - remove the uv tool entry + PATH/profile block(s).
+- `state` - remove user data under `~/.omnigent` and `~/omnigent` (backup by
+  default).
+- `desktop-data` - remove Electron caches/support/logs (NOT the app bundle).
+- `all` - alias for `cli state desktop-data`.
+
+Flags:
+
+- `--purge` - implies `state`; deletes state/caches; backs up first unless
+  `--no-backup`.
+- `--dry-run` - print exact planned actions (paths, sizes, line ranges); make no
+  changes.
+- With no destructive flag (`--yes`, `--purge`, `--force`,
+  `--modify-external-config`, `--no-backup`, `--assume-inferred`, or
+  `--purge-workspace`), uninstall defaults to dry-run preview mode.
+- `--yes` - non-interactive; suppresses prompts for auto-removable artifacts
+  only. Does NOT imply `--purge`.
+- `--json` - machine-readable output.
+- `--force` - allow SIGKILL after the SIGTERM grace window; proceed if daemons
+  resist; override tamper-refusal.
+- `--modify-external-config` - primary gate to touch third-party config files.
+- `--no-backup` - with `state`/`--purge`, skip archive creation.
+- `--assume-inferred` - secondary gate to act on `inferred` entries.
+- `--purge-workspace` - the only way to clear `~/omnigent` (your working files)
+  non-interactively. Without it, `--purge --yes` still removes `~/.omnigent`
+  (credentials/history) but leaves `~/omnigent` untouched and prints a notice.
+  This keeps a stray `--yes` in automation from wiping user work.
+
+Gate decision table. Two orthogonal gates. Intrinsic-risk (primary): own
+reversible artifacts auto-remove under `--yes`; third-party edits and data
+destruction need their explicit flag on both real and backfilled ledgers.
+Confidence (secondary, tighten-only): an `inferred`/low-confidence entry
+escalates one notch and won't auto-act under bare `--yes` - it can only add
+friction, never grant it.
+
+| Artifact | No destructive flags | `--yes` | Required gate |
+|---|---|---|---|
+| Wheel (`uv tool uninstall omnigent`) | dry-run preview | auto-remove | none |
+| Delimited PATH block (marker match) | dry-run preview | auto-remove | none; refuse if `block_sha256` mismatch (tampered) unless `--force` |
+| Injected external config, marker/observed | reported, skipped | reported, skipped | `--modify-external-config` |
+| Injected external config, inferred (no marker) | reported, skipped | reported, skipped | `--modify-external-config` AND `--assume-inferred` |
+| `~/.omnigent` state root | reported, skipped | removed only with `--purge` | `--purge` |
+| `~/omnigent` workspace | reported, skipped | kept unless `--purge-workspace` | `--purge` AND (`--purge-workspace` or interactive confirm) |
+| Desktop data | via `desktop-data`/`all` | same | none beyond target |
+| Shared deps (uv/node/tmux/bwrap) | report-only | report-only | none - never removed this version |
+
+Checklist:
+
+- [x] Python `omnigent uninstall` subcommand that execs the shell script
+- [x] Targets: `cli`, `state`, `desktop-data`, `all`
+- [x] Flags: `--purge`, `--purge-workspace`, `--dry-run`, `--yes`, `--json`,
+      `--force`, `--modify-external-config`, `--no-backup`, `--assume-inferred`
+- [x] Two-gate decision table implemented (intrinsic-risk + confidence
+      tighten-only)
+- [x] External-config stripping (marker/allowlist scoped only)
+
+## 6. Order of operations
+
+`omnigent uninstall` performs graceful shutdown + state/JSON in Python, then
+execs the shell script for removal. Sequence:
+
+1. Resolve ledger (section 4 resolution order).
+2. Stop processes first. Read pidfiles under `~/.omnigent/run/` (+ `daemons/`,
+   `runners/`, `local_server/`): SIGTERM -> wait 5s -> under `--force` SIGKILL.
+   Kill only `omnigent:*` tmux sessions. Unload ledger-recorded LaunchAgents/
+   systemd units. If a process won't stop, abort destructive steps (report and
+   exit nonzero) unless `--force`.
+3. `--dry-run`? Print exact paths + sizes + line ranges, then exit 0.
+4. Profile cleanup. Remove ONLY the delimited marker block, all shells incl.
+   fish (`config.fish` + `conf.d/`). Back up the profile file first. Refuse a
+   block whose `block_sha256` doesn't match the ledger (tampered) unless
+   `--force`.
+5. Strip injected external config (gated per table; marker-scoped /
+   allowlist-scoped only).
+6. Optional state / desktop-data (only with `--purge` / target). For `--purge`:
+   archive to a backup tarball OUTSIDE the target under `~/.omnigent-backups/`
+   (or `$XDG_STATE_HOME`). Prefer `<ts>.tar.zst` when `zstd` is present; fall
+   back to `<ts>.tar.gz` (gzip is POSIX-baseline) otherwise. Never silently skip
+   the backup because a compressor is missing - a purge that can't write its
+   backup must fail closed (exit 1) unless `--no-backup` was given. Print the
+   restore command, then delete. Never back up into `~/.omnigent`. Clearing
+   `~/omnigent` non-interactively requires `--purge-workspace` (see section 5);
+   otherwise it prompts for a separate confirm. Note that purging
+   `installation_id` makes a reinstall look like a new device (telemetry).
+7. `uv tool uninstall omnigent` - LAST (so earlier Python-driven steps still
+   have the wheel available).
+
+Checklist:
+
+- [x] Process-shutdown protocol (pidfiles, SIGTERM->5s->`--force` SIGKILL,
+      `omnigent:*` tmux, ledger LaunchAgents, abort-if-won't-stop)
+- [x] Profile block removal across all shells incl. fish; profile backed up
+      first; tamper-refusal
+- [x] `--purge` archives OUTSIDE the target (`.tar.zst`, gzip fallback; fail
+      closed if it can't write the backup), prints restore command, then
+      deletes; `~/omnigent` gated behind `--purge-workspace` (or confirm)
+- [x] `uv tool uninstall omnigent` runs last
+
+## 7. Idempotency and exit codes
+
+State-check semantics: already-absent = success (exit 0); tried-and-failed =
+report, continue with remaining steps, exit nonzero, summarize at end. Never
+swallow a real failure as success; distinguish "already gone" from "tried and
+failed."
+
+Exit codes:
+
+- `0` - all planned actions done or already-absent
+- `1` - one or more actions failed (details in summary)
+- `2` - aborted before destructive steps (e.g. process would not stop without
+  `--force`)
+- `3` - refused (tampered block / anchor guard / ambiguous, no `--force`)
+
+`--json` output shape:
+
+```json
+{
+  "schema_version": 1,
+  "dry_run": false,
+  "ledger_source": "installer",
+  "actions": [
+    { "artifact": "profile_block", "path": "~/.zshrc", "planned": "remove",
+      "status": "done", "gate": null, "detail": "block removed, backup at ~/.zshrc.omnigent.bak" },
+    { "artifact": "external_config", "path": "~/.config/harness/hermes.json", "marker": "mcp_servers.omnigent",
+      "planned": "remove", "status": "skipped", "gate": "--modify-external-config", "detail": "gate not provided" },
+    { "artifact": "shared_dep", "name": "uv", "planned": "report", "status": "reported",
+      "gate": null, "detail": "installed_by=unknown; not removed" }
+  ],
+  "backups": ["~/.omnigent-backups/2026-07-14T18-40-02Z.tar.zst"],
+  "summary": { "done": 1, "skipped": 1, "failed": 0, "reported": 1 },
+  "exit_code": 0
+}
+```
+
+Checklist:
+
+- [x] State-check idempotency (already-absent = 0; tried-and-failed = nonzero +
+      continue + summarize)
+- [x] Exit codes 0/1/2/3 as specified
+- [x] `--json` output shape stable and tested
+
+## 8. Test matrix
+
+| # | Scenario | Expect |
+|---|---|---|
+| 1 | fish profiles (`config.fish` + `conf.d/omnigent.fish`) | block removed from both; other lines intact |
+| 2 | Tampered / corrupted marker block (sha mismatch) | refuse without `--force`; exit 3 |
+| 3 | No ledger, valid install signal | deep-backfill runs, uninstall proceeds |
+| 4 | No ledger, no install signal | anchor guard: nothing written; "no install detected" |
+| 5 | Backfilled ledger present | inferred entries need `--assume-inferred`; deps report-only |
+| 6 | Live daemon running | stopped (SIGTERM->5s->`--force`); won't-stop aborts destructive steps |
+| 7 | `--dry-run` | prints exact paths/sizes/ranges; zero mutations; exit 0 |
+| 8 | `--purge` with backup | archive written OUTSIDE `~/.omnigent`; restore command printed; then delete |
+| 9 | `--purge --no-backup` | delete without archive; `~/omnigent` kept unless `--purge-workspace` |
+| 10 | Shared dep present (`installed_by:unknown`) | report-only, never removed, even with `--yes` |
+| 11 | Double ledger (real + backfill both present) | keep real; backfill copy left as `.backfill.json` for inspection |
+| 12 | Re-run after full uninstall (idempotency) | all already-absent; exit 0 |
+| 13 | Injected external config, marker vs inferred | marker gated by `--modify-external-config`; inferred also needs `--assume-inferred` |
+| 14 | uv tool uninstall runs last | earlier Python steps had the wheel available |
+| 15 | `--purge` on a box without `zstd` | backup written as `.tar.gz`; not skipped |
+| 16 | `--purge --yes` without `--purge-workspace` | `~/.omnigent` removed; `~/omnigent` kept + notice |
+
+Checklist:
+
+- [x] Rows 1-2, 6-7, 12, 14 covered by `uninstall_oss.sh` tests
+- [x] Rows 3-5, 8-11, 13 covered by focused CLI, ledger, and
+      `uninstall_oss.sh` tests
+
+## 9. Delivery plan (PR breakdown)
+
+- [x] PR 1 - Ledger schema + serializer. Schema, atomic-write + `0600` writer,
+      `omnigent _internal write-ledger` hidden subcommand, round-trip unit
+      tests. No behavior change.
+- [x] PR 2 - Install-side writer. Hook `write_install_ledger` into
+      `scripts/install_oss.sh` + upgrade/repair merge logic.
+- [x] PR 3 - Back-fill routine. Fast + deep reconstruction, anchor guard,
+      confidence assignment, never-overwrite-real + double-ledger,
+      `doctor --migrate-ledger`.
+- [x] PR 4 - `uninstall_oss.sh` core. Process shutdown, profile block removal
+      (all shells), `uv tool uninstall`, idempotency + exit codes,
+      `--dry-run`/`--json`.
+- [x] PR 5 - `omnigent uninstall` subcommand + gates. Python front, targets/
+      flags, two-gate decision table, `--purge` backup-outside-target,
+      external-config stripping.
+- [x] PR 6 - Docs + discovery. Installer next-steps + `--help` mention
+      uninstall; README documents the standalone fallback and purge behavior.
+      App-store and brew/apt-specific surfaces remain out of scope for this OSS
+      CLI/script PR.
+
+## Appendix A: ELI5
+
+Omnigent is a houseguest.
+
+- Installing = the guest moves in: hangs a coat by the door (the PATH line in
+  your shell profile), keeps a box of their stuff in a closet (`~/.omnigent` -
+  settings, logins, chat history) and a desk they work at (`~/omnigent`).
+  Sometimes they borrow shared tools from your garage that may already have been
+  there (uv, Node, tmux). Occasionally they leave a sticky note inside a
+  roommate's notebook (config injected into other tools).
+- Uninstalling = the guest moves out politely:
+  1. Finish what you're doing first. Stop working before packing (kill running
+     daemons/runners) - don't yank the desk out while they're typing.
+  2. Take only your own stuff. Grab your coat (remove only the marked PATH line,
+     not random lines), take your box, erase your sticky note from the
+     roommate's notebook.
+  3. Don't take the shared tools. The garage drill might belong to the house.
+     Just leave a note: "I think I brought this - you decide." Never haul it off
+     on your own.
+  4. Your box stays unless you say "throw it out." Moving out is not shredding
+     your photos. Only if you explicitly say `--purge` does the box go - and
+     even then it is boxed up in the garage first (a backup tarball OUTSIDE the
+     room) so you can get it back.
+- The ledger = a move-in checklist the guest writes on arrival: "hung a coat
+  here, borrowed this drill, left a note in that notebook." On move-out they
+  read the checklist and undo exactly those things - no guessing.
+- Back-fill = for guests who moved in before checklists existed, walk the house
+  and reconstruct the checklist from what you can see, writing down how sure you
+  are ("coat on hook - definitely mine" vs "this drill - no idea who brought it,
+  don't touch"). A reconstructed checklist never lets you auto-toss the risky
+  stuff.
+- Bare uninstall = "show me what would happen first." Nothing changes until you
+  add a destructive flag such as `--yes` or `--purge`.
+- `--yes` = "apply the previewed safe moves." It grabs the coat, but it still
+  leaves the box unless you add `--purge`, and still will not erase a roommate's
+  notebook unless you add `--modify-external-config`. Risky actions are gated by
+  what you are touching, not by which checklist you have.
+
+## Appendix B: Flowchart
+
+```
+                          +-----------------------------+
+                          |   omnigent uninstall [...]   |
+                          |  targets: cli | state |      |
+                          |  desktop-data | all          |
+                          |  flags: --purge --dry-run    |
+                          |  --yes --json --force        |
+                          |  --modify-external-config    |
+                          +--------------+--------------+
+                                         |
+                          +--------------v--------------+
+                          |  Load install_ledger.json    |
+                          +--------------+--------------+
+                                         |
+                    +--------------------+--------------------+
+                    |                    |                     |
+          ledger source=installer   source=backfill       NO ledger
+              (real, trust)        (evidence + per-        |
+                    |               field confidence)      |
+                    |                    |                 v
+                    |                    |        +----------------------+
+                    |                    |        | Genuine install       |
+                    |                    |        | signal present?       |
+                    |                    |        | (installation_id /    |
+                    |                    |        |  wheel / marker)      |
+                    |                    |        +-------+----------+----+
+                    |                    |            no  |      yes |
+                    |                    |                v          v
+                    |                    |        +------------+  +--------------+
+                    |                    |        | Refuse:     |  | Back-fill    |
+                    |                    |        | nothing to  |  | from markers |
+                    |                    |        | uninstall   |  | (read-only)  |
+                    |                    |        +------------+  +------+-------+
+                    +---------+----------+------------------------------+
+                              |
+                              v
+             =====================================
+             ||  1. PLAN/STOP PROCESSES FIRST    ||
+             ||  dry-run reports planned stops;   ||
+             ||  apply unloads LaunchAgents, then ||
+             ||  pidfiles/tmux -> SIGTERM/force   ||
+             =================+===================
+                             |  won't stop? --> ABORT destructive steps (exit 2)
+                             v
+             =====================================
+             ||  2. --dry-run?  -- yes -> print   ||
+             ||  planned stops, paths, sizes,     ||
+             ||  EXIT 0                            ||
+             =================+===================
+                             | no
+                             v
+        +--------------------------------------------------+
+        |  For each planned action, apply the GATES:        |
+        |                                                    |
+        |  INTRINSIC-RISK gate (primary):                    |
+        |   - own + reversible (wheel, marked PATH block)    |
+        |         -> auto under --yes                         |
+        |   - third-party file edit (injected config)        |
+        |         -> needs --modify-external-config          |
+        |   - data destruction (~/.omnigent, ~/omnigent)     |
+        |         -> needs --purge (defaults to No)          |
+        |   - shared deps (uv/Node/tmux, installed_by        |
+        |         =unknown) -> REPORT ONLY, never remove     |
+        |                                                    |
+        |  CONFIDENCE gate (secondary, tighten-only):        |
+        |   - inferred / low-confidence entry                |
+        |         -> +1 notch friction, no auto under        |
+        |            bare --yes (never loosens)              |
+        +----------------------+---------------------------+
+                                 |
+                                 v
+           ORDER OF OPERATIONS (each gated above):
+           +-------------------------------------------+
+           | (processes already stopped)                |
+           | 3. Profile cleanup - remove ONLY delimited |
+           |    marker block, all shells incl. fish;    |
+           |    back up profile; refuse if tampered     |
+           | 4. Strip injected external config (marker- |
+           |    scoped, ledger-recorded)                 |
+           | 5. --purge? archive to backup tarball       |
+           |    OUTSIDE target (~/.omnigent-backups/),  |
+           |    then delete state; keep ~/omnigent       |
+           |    unless --purge-workspace or confirm      |
+           | 6. uv tool uninstall omnigent  (LAST)       |
+           +--------------------+----------------------+
+                                |
+                                v
+             +--------------------------------------+
+             | Idempotency by STATE-CHECK:           |
+             |  already-absent = success (exit 0)    |
+             |  tried & failed  = report, non-zero,  |
+             |                    continue, summarize|
+             |  --json summary of what was done/kept |
+             +--------------------------------------+
+
+   Other package surfaces:
+   OS/package-manager uninstall owns package files. The Omnigent
+   uninstaller handles local profile/state cleanup and uses
+   uv tool uninstall for uv-installed wheels; it does not remove
+   shared dependencies or act as a cross-domain reaper.
+```

docs/harness-bench-design.md

@@ -6,9 +6,10 @@ available", "is steering possible", "does policy DENY actually block a call" —
 instead of a human hand-maintaining a spreadsheet and hoping it still reflects
 reality.
 
-> **Status:** shipped and in use. The MVP plus most of phase-2 is on `main` —
-> three transport drivers, the six P0 probes, and a capability-derived matrix
-> that has already caught and corrected real declaration drift. See
+> **Status:** shipped and in use. The bench on `main` has three transport
+> drivers, six P0 probes, five report-only P1 probes, automatic live/offline
+> selection, and a capability-derived matrix that has already caught and
+> corrected real declaration drift. See
 > [Current state](#current-state-shipped) for what is live vs. still open. The
 > sections before it describe the design and the decisions behind it.
 
@@ -125,48 +126,42 @@ list" to "discover"; probes, profiles, and reports are untouched.
 
 ## Architecture
 
-Three layers plus a report step.
+The implementation has three layers plus reporting:
 
 ```
 tests/harness_bench/
-  profile.py         # BenchProfile: per-harness self-declared facts
-  manifest.py        # registry of official BenchProfiles (the spreadsheet as data)
-  verdict.py         # Verdict enum, ProbeResult, priority (P0/P1)
-  transports/        # transport drivers keyed by class
-    _base.py         #   TransportDriver: launch/session/turn against a harness
-    sdk_inproc.py    #   in-proc HTTP (reuses existing e2e server helpers)
-    tmux_tui.py      #   (phase 2)
-    app_server.py    #   (phase 2)
-    http_sse.py      #   (phase 2)
-  probes/            # one module per dimension
-    _base.py         #   CapabilityProbe: name, priority, applies_to, declared(), run()
-    basic_turn.py
-    streaming.py
-    tool_calling.py  #   incl. "connects to Omnigent MCP"
-    interrupt.py
-    policy_deny.py
-    model_override.py
-    ...              #   (phase 2: steering, live_queue, resume_fork, elicitation,
-                     #    reasoning, images, cost, compaction)
-  bench.py           # driver: iterate probes x harnesses -> matrix
-  report.py          # render Markdown + JSON, with a DRIFT column
-  test_bench.py      # pytest wrapper (parametrized) for CI
+  profile.py             # BenchProfile and profile-name resolution
+  manifest.py            # official profiles derived from capabilities + e2e metadata
+  verdict.py             # verdict vocabulary, priority, and drift reconciliation
+  transport.py           # semantic Driver protocol and transport resolution
+  driver.py              # sdk-inproc driver + shared TurnResult/usage helpers
+  full_server.py         # shared server/runner lifecycle and registration
+  full_server_driver.py  # full-server driver and session polling
+  native_tui_driver.py   # native vendor CLI + host-daemon/tmux driver
+  session_items.py       # shared session-item envelope parsing
+  runtime_env.py         # config/credential resolution matching `omni run`
+  probes/                # one module per capability dimension
+  events.py              # structured progress events and plain sink
+  richreport.py          # optional live Rich matrix
+  bench.py               # orchestration, concurrency, and shared-server wiring
+  report.py              # terminal, Markdown, and JSON rendering
 ```
 
-- **Layer 0 — Profile / manifest.** The spreadsheet, as data. Source of truth
-  for the static columns and the *expected* verdicts for behavioral ones.
-- **Layer 1 — Offline conformance** (no network, always in CI). Harness
-  registers, `create_app()` builds, required routes exist, `Executor` flags are
-  internally consistent, a `BenchProfile` exists. Fast, catches structural
-  regressions.
-- **Layer 2 — Live probes** (gated on CLI + creds; reuses
-  `skip_if_harness_cli_missing`). Runs the behavioral table against a live
-  server, exactly like the existing e2e tests
-  (`/v1/sessions` + `send_user_message_to_session` +
-  `poll_session_until_terminal` + `final_assistant_text`).
-- **Report.** `python -m tests.harness_bench --harness codex` prints one
-  harness's matrix; no filter regenerates the whole sheet with a `DRIFT` column
-  diffing declared vs observed.
+Reusable configuration and runtime primitives live in production modules such
+as `omnigent.config`, `find_free_port`, and the harness registry rather than
+being reimplemented under tests.
+
+- **Layer 0 — Profile / manifest.** Static facts and declared verdicts are
+  derived from `harness_capabilities()` plus the existing e2e harness metadata.
+- **Layer 1 — Offline conformance.** No network or credentials. It validates
+  registration, profile shape, capability derivation, transport resolution,
+  rendering, and orchestration behavior in normal CI.
+- **Layer 2 — Live probes.** Drivers execute behavioral probes through the
+  wrap boundary or the real server/runner session API. Missing credentials,
+  vendor binaries, or vendor login produce capability-neutral skips.
+- **Report.** The CLI renders the declared matrix offline or reconciles live
+  observations into terminal, Markdown, and JSON reports. `DRIFT` produces a
+  non-zero exit status.
 
 ### Build on `HarnessProbe`, don't reinvent it
 
@@ -206,24 +201,38 @@ Validated for presence and shape only: `Owner`, `Transport`, `Implementation`,
 
 | Dimension | How the probe proves it |
 |---|---|
-| Basic turn (prereq) | ask model to reply with `<marker>`, assert marker in final text |
-| Connects to Omnigent MCP | expose an Omnigent tool, ask model to call it, assert `ToolCallRequest` dispatched through the relay |
-| Streaming | count `TextChunk` events: >1 delta = `deltas`, single blob = `complete-only` |
-| Model override | launch with a chosen model, assert routing (gateway request / `TurnComplete` usage model); cross-family reject verified via `model_family_mismatch` |
-| Policy: DENY | set DENY on a tool, ask model to call it, assert the call is blocked + surfaced |
-| Policy: ASK -> Elicitation | set ASK, assert an elicitation event is emitted upstream (web-surfaceable) |
-| Interrupt | start a long turn, call `interrupt_session`, assert it stops promptly |
-| Live queue (concurrent) | `enqueue_session_message` mid-turn, assert accepted (not rejected) |
-| Tool-boundary steer | inject steering text at a tool boundary, assert the next turn reflects it |
-| Resume/fork from transcript | run a convo, resume in a fresh session, assert prior context present; fork = branch diverges |
-| Compaction | assert `CompactionComplete` surfaced when triggered |
-| Reasoning | reasoning-heavy prompt, assert `ReasoningChunk` emitted |
-| Images | send an image, assert the model describes it |
-| Cost tracking | assert `TurnComplete` carries usage / cost |
+| Basic turn (P0 prerequisite) | complete a marker-echo turn and require assistant text |
+| Fork replay (P1) | clone the session after Basic turn, require copied marker history, and require the clone to recall it |
+| Streaming (P0) | count output-text deltas; repeated single-delta output is `PARTIAL` |
+| Reasoning (P1) | request high effort and require a forwarded reasoning delta or persisted reasoning item; no observation is inconclusive because the model may emit none |
+| Tool calling (P0) | provoke the transport's tool mechanism and require a surfaced call |
+| Omnigent MCP (P1, native only) | call read-only `sys_session_list` through the generated `omnigent` MCP relay and require a matching function-call item |
+| Policy DENY (P0) | apply a tool-call deny and require a blocked-call signal |
+| Policy ALLOW (P1) | attach an explicit allow and require a non-blocked tool output; native hooks expose no positive ALLOW event |
+| Policy ASK (P1) | apply ask and require an elicitation/approval request |
+| Model override (P0) | validate the requested harness/model pair and complete a turn |
+| Cost tracking (P1) | read priced cost or token usage from the turn/session |
+| Interrupt (P0) | interrupt a long turn and require cancellation or early termination |
+
+Planned dimensions are steering, live queue, resume, images, and compaction.
+
+Their declarations already have a place in `HarnessCapabilities`: resume uses
+the `Resume` mechanism enum, while steering, live queue, images, and compaction
+are optional booleans. An unset optional value makes no claim and therefore
+stays `UNKNOWN` until the corresponding probe work establishes the harness's
+expected behavior.
 
 Every behavioral probe also reads the corresponding declared flag and returns
 `DRIFT` when observed disagrees with declared.
 
+The CLI can slice this catalog with repeatable or comma-separated
+`--dimension` values. A slice always includes `basic_turn` because it proves
+the harness is exercisable before interpreting another probe's result. Reports
+and the live Rich grid contain only the selected columns. Each repeated
+`--harness NAME[=MODEL]` binds an optional model override directly to that
+harness, avoiding both test model-pool environment variables and positional
+cross-family assignment. Omitting `=MODEL` keeps that profile's default.
+
 ### Illustrative probe shape
 
 ```python
@@ -247,80 +256,56 @@ class StreamingProbe(CapabilityProbe):
 
 ## Transport drivers: the real ceiling on "all dimensions"
 
-Behavioral probes run through a **transport driver** resolved from the
-harness *family* plus flags: SDK harnesses default to `full-server` (`--fast`
-picks `sdk-inproc`), natives use `native-tui`, and `--transport NAME` overrides
-the family for any harness. A probe calls
-*semantic* methods on the driver (`run_basic_turn`, `run_streaming_turn`,
-`run_tool_turn(deny=...)`, `run_interrupt_turn`); the driver owns the
-*mechanism* and the probe owns the *interpretation*, so one probe runs across
-transports that reach the same capability by different means.
+Behavioral probes call semantic driver methods such as `run_basic_turn`,
+`run_tool_turn`, `run_policy_turn`, and `run_interrupt_turn`. Drivers own the
+transport-specific mechanism; probes interpret a common `TurnResult`.
 
-Three drivers exist today (see "Current state" above): `sdk-inproc`,
-`full-server`, `native-tui`. Two consequences fall out of this design:
+Three drivers exist:
 
-- A dimension is only observable where a driver exercises it. Tool calling and
-  Policy DENY need `full-server`; on `sdk-inproc`/`native-tui` they report `·`.
-  A `·` therefore often means "this transport can't exercise it here," not "the
-  harness lacks it" (see "Which transport exercises which dimension").
-- A harness that invents a *novel* transport (neither wrap-subprocess, full
-  server, nor native tmux) would degrade its transport-dependent probes to
-  `SKIPPED`/`UNKNOWN` until a driver for that class exists.
+- `full-server` is the SDK-family default. It drives a real server and runner,
+  uses a server-dispatched builtin for tool probes, and observes fixed
+  ALLOW/ASK/DENY policies.
+- `native-tui` drives a resident vendor CLI in a runner-owned tmux pane through
+  the server session API. It observes vendor tool calls and tool-call DENY via
+  the native policy hook. ALLOW/ASK are not yet implemented.
+- `sdk-inproc` drives the harness wrap directly. It is selected by `--fast` and
+  provides cheaper wrap-level coverage, but no server-side policy surface.
 
-So "run the bench, see all verdicts, zero code" is true *for any harness
-reusing a known transport class*, and honest about the cases where a dimension
-or a transport is not yet wired.
+A `SKIPPED` verdict therefore means the behavior was not measurable in that
+transport or environment, not that the harness lacks the capability. A novel
+transport class still requires a driver, but harnesses reusing one of these
+families flow through the existing probes without per-harness probe code.
 
 ## Current state (shipped)
 
-The MVP and most of phase-2 are landed. What exists on `main` today:
+The bench on `main` includes:
 
-- **Layer 0/1/2** — profile/manifest, offline conformance (runs in CI via the
-  `misc` pytest group), and the six P0 live probes (basic turn, streaming,
-  tool calling, policy DENY, model override, interrupt) with the `DRIFT`
-  column.
-- **Three transport drivers**, selected by harness *family* with flag overrides:
-  - `sdk-inproc` — drives a harness wrap subprocess directly (the four P0 SDK
-    harnesses: claude-sdk, codex, pi, openai-agents).
-  - `full-server` — a real server + runner; the only transport that exercises
-    **Tool calling** and **Policy DENY** as server-dispatched, policy-gated
-    calls (SDK harnesses only — it registers via an agent bundle).
-  - `native-tui` — a resident vendor CLI in a runner-owned tmux pane, driven
-    over the session HTTP surface via a host daemon.
-
-  SDK harnesses default to **`full-server`** — the fullest coverage, and a
-  strict superset of what `sdk-inproc` observes (everything sdk-inproc does,
-  *plus* Tool calling + Policy DENY). `--fast` opts the SDK family down to
-  `sdk-inproc` when you want to skip the server boot (those two dimensions then
-  report `·`). Native harnesses have a single transport `--fast` does not touch.
-  An explicit `--transport NAME` overrides the family default for any harness
-  and is mutually exclusive with `--fast`.
-- **Capability-derived matrix** — descriptive columns and declared verdicts
-  come from `harness_capabilities()` (the seam; see
-  `designs/harness-capabilities-bench-seam.md`), so a harness added to the
-  registry — in-repo *or* a community plugin — flows into the bench with no
-  bench edit.
-- **Native harnesses auto-derived** — every `NATIVE_TUI` harness is registered
-  and drivable by name; `native_vendor()` derives what the driver needs from
-  capabilities, with no per-vendor table.
+- **Six P0 probes:** Basic turn, Streaming, Tool calling, Policy DENY, Model
+  override, and Interrupt.
+- **Six P1 probes:** Fork replay, Reasoning, Omnigent MCP, Policy ALLOW, Policy ASK, and Cost tracking. P1 verdicts
+  are report-only and do not gate the same way as P0 declarations.
+- **Three transport drivers:** `full-server`, `native-tui`, and `sdk-inproc`,
+  selected by harness family with `--transport` and `--fast` overrides.
+- **Automatic live selection:** without an explicit mode, the CLI runs live
+  when credentials are resolvable and otherwise renders the declared matrix.
+  `--live` and `--no-live` force either mode. Credentials are derived like
+  `omni run`; `--profile` is only an override.
+- **Concurrent execution and shared infrastructure:** `--jobs` runs harnesses
+  concurrently while preserving report order, and full-server harnesses share
+  one server/runner pair within a run.
+- **Structured progress and reports:** plain or Rich live progress plus terminal,
+  Markdown, JSON, and optional report-file output.
+- **Capability-derived registration:** official SDK and native profiles derive
+  from `harness_capabilities()` and existing e2e metadata. Session-item parsing,
+  config loading, free-port selection, and polling helpers are shared rather
+  than duplicated.
 
 ### Not yet wired
 
-- **Bench observation of Tool calling / Policy DENY on `native-tui`** — a
-  *driver gap, not a native-harness limitation*. Native harnesses do call tools
-  and enforce permissions; the bench cannot yet observe it on this transport.
-  A native tool call is the vendor's own tool (Bash/Read/...), not a
-  server-dispatched `function_call_output` the bench can force, and a native
-  deny is a vendor permission decision, not a server-side policy evaluation the
-  probe can assert against. So both cells show `·` (not measured), never `✗`.
-  Wiring the observation needs new driver work. (SDK harnesses get these via
-  `full-server`.)
-- **P1 dimensions** — steering, live-queue, resume/fork, elicitation ASK,
-  reasoning, images, cost, compaction. Probes not written yet (report
-  `UNKNOWN`).
-- **Server-side native-agent seeding is a hardcoded list** — see the
-  plugin-seamlessness note below; this is the main gap between "the bench is
-  plugin-ready" and "a plugged-in native harness just works end to end".
+- Registry-driven server seeding for community native UI agents.
+- Steering, live queue, resume, images, and compaction probes.
+- Automatic provisioning of vendor login/provider configuration for native
+  harnesses; unavailable environments skip cleanly.
 
 ## CI integration
 
@@ -332,37 +317,29 @@ The MVP and most of phase-2 are landed. What exists on `main` today:
 ## Running the bench and reading the result
 
 ```
-# Offline: the declared matrix, no creds, every harness. Fast.
-python -m tests.harness_bench
+# Declared matrix only, with no credentials.
+python -m tests.harness_bench --no-live
 
-# Live: probe one harness against a gateway profile.
-python -m tests.harness_bench --harness codex-native --profile oss
+# Auto-live when configured or ambient credentials are available.
+python -m tests.harness_bench --harness codex
 
-# Live: probe every official harness (SDK + native) sequentially.
-python -m tests.harness_bench --profile oss
+# Force a named profile and probe several harnesses concurrently.
+python -m tests.harness_bench --profile oss --jobs 4 --rich
 
 # A community harness that ships its own BenchProfile.
-python -m tests.harness_bench --harness mypkg.harness:PROFILE --profile oss
+python -m tests.harness_bench --harness mypkg.harness:PROFILE --live
 ```
 
-**You do not need to live-probe every harness on every host — and you cannot.**
-Each native harness needs its own vendor CLI logged in (a login the bench
-cannot provision), so no single host has them all. The two layers split the
-work:
+Without `--live` or `--no-live`, resolvable credentials select live mode and
+missing credentials select the offline declared matrix. Native harnesses also
+need their vendor CLI installed and logged in; the bench cannot provision those
+accounts, so unavailable harnesses skip without aborting the run.
 
-- **Offline conformance** already covers every harness in CI — registration,
-  the declared matrix, capability derivation. No host access needed.
-- **Live probes** only answer "does observed behavior match the declaration?"
-  You get value from live-probing a harness where the declaration is unverified
-  or might be wrong — not from chasing 100% coverage on one box.
-
-Run the full set on whatever host you have (`--profile oss`); harnesses whose
-vendor CLI is absent or logged out **skip cleanly** (they do not fail or abort
-the run). Read two signals only: any `!!` DRIFT, and any harness you *can* run
-that shows an unexpected `✗` / `·`. A single live run is a spot-check, not a
-gate — live probes are non-deterministic (model behavior, timing), so re-run
-before treating one `·`/timeout as a regression. Drift coverage is cumulative:
-each host that has harness X logged in contributes a live check for X.
+Offline conformance covers every registered harness in CI. Live runs are
+spot-checks of observed behavior and can vary with model behavior and timing;
+re-run an isolated timeout or skip before treating it as a regression. The
+signals that matter most are `DRIFT` and repeatable unexpected
+`UNSUPPORTED`/`PARTIAL` verdicts on a runnable harness.
 
 ## Streaming is a binary declared capability
 
@@ -386,46 +363,20 @@ stream, the bench flags a real drift on the next run, rather than a false
 
 ## Which transport exercises which dimension
 
-Not every dimension is observable on every transport, so a `·` (SKIPPED) in a
-run always means "the bench did not measure this here," never "the harness
-lacks it." Two dimensions in particular only get a real verdict on the
-`full-server` transport:
-
-| Dimension | sdk-inproc (`--fast`) | full-server (default) | native-tui |
+| Dimension | `sdk-inproc` (`--fast`) | `full-server` (SDK default) | `native-tui` |
 |---|---|---|---|
-| Basic turn, Streaming, Model override, Interrupt | ✓ | ✓ | ✓ |
-| **Tool calling** | · (harness dispatches tools internally) | ✓ (server-dispatched builtin) | · (bench can't observe vendor tools yet) |
-| **Policy DENY** | · (wrap-direct: no tool-call policy hook) | ✓ (spec-baked deny, enforced) | · (bench can't observe vendor deny yet) |
+| Basic turn, Streaming, Reasoning, Model override, Interrupt | Wrap-level observation; reasoning effort is set per request | End-to-end server/runner observation; reasoning effort is set on the session | End-to-end server/runner/vendor observation; reasoning effort is set on the session |
+| Fork replay | Not observable | Clone + copied-history replay through server/runner | Clone + copied-history replay through server/runner/vendor |
+| Tool calling | Request-level wrap tool | Server-dispatched builtin | Vendor tool mirrored into session items |
+| Omnigent MCP | Not applicable | Not applicable | Generated `omnigent` MCP relay when supported by the vendor |
+| Policy DENY | Not observable | Fixed policy blocks the builtin | Session CEL policy triggers the native policy hook |
+| Policy ALLOW / ASK | Not observable | Fixed policy; ASK observes and resolves an elicitation | Temporary session CEL policy; ASK observes and resolves an elicitation |
+| Cost tracking | Completed-response usage when forwarded | Session snapshot usage/cost | Session snapshot when the vendor forwards usage |
 
-The `native-tui` `·` is a *bench observation gap, not a native-harness
-limitation*: native harnesses do call tools and enforce permissions, but a
-native tool call is the vendor's own (Bash/Read/...) and a native deny is a
-vendor permission decision, neither of which is the server-dispatched,
-policy-gated call the probe watches for. Giving those cells a real verdict
-needs new driver work, not a change to the harnesses.
-
-Because `full-server` sees everything `sdk-inproc` does *plus* these two, it is
-the **default** for SDK harnesses — a plain live run proves Tool calling and
-Policy DENY out of the box:
-
-```
-python -m tests.harness_bench --harness claude-sdk --profile oss
-```
-
-Live-verified: `claude-sdk` completes the full matrix on `full-server` —
-Tool calling `✓` and Policy DENY `✓` (the deny is delivered and the blocked
-call does not stall the turn). Add `--fast` to trade that coverage for a quicker
-run on `sdk-inproc`; those two columns then show `·`, since neither `sdk-inproc`
-nor `native-tui` (for natives) routes a tool call through a server policy
-evaluation.
-
-`full-server` covers **SDK harnesses only** — it registers the harness via an
-agent bundle, which is the SDK-wrap path; native harnesses need the host-daemon
-provisioning the `native-tui` driver owns. So Tool calling / Policy DENY on
-native harnesses are not observed by *any* transport yet — a bench follow-up,
-not a native-harness gap — distinct from the `--fast` (sdk-inproc) `·`, which
-is a transport limitation the default `full-server` run already answers for SDK
-harnesses.
+`full-server` remains the SDK default because it covers the deployed server
+path and all three policy actions. `--fast` trades that policy coverage for
+lower startup cost. `native-tui` now has real Tool calling and all three policy
+action probes through the native hook path.
 
 ## Plugin seamlessness: where it is and isn't
 
@@ -478,25 +429,15 @@ agree with it.
 
 ## Open items
 
-- **Registry-driven native-agent seeding** (highest leverage) — replace the
-  hardcoded `_ensure_default_*_agent()` list in `server/app.py` with a loop over
-  `native_agents()`, so any native harness (in-repo or plugin) registers
-  automatically. This is the fix for the plugin-seamlessness seam above.
-- **Bench observation of Tool calling / Policy DENY on `native-tui`** — a
-  driver gap, not a native-harness limitation: native harnesses call tools and
-  enforce permissions, but a native tool call is the vendor's own and a native
-  deny is a vendor permission decision, not the server-dispatched
-  `function_call_output` the probe watches for. The cells show `·` (not
-  measured), never `✗`. Needs new driver work. (SDK harnesses get these via
-  `full-server`.)
-- **Per-harness native provisioning gaps** the bench has surfaced but not yet
-  resolved: goose-native returns a 500 on the terminal-ensure endpoint;
-  hermes-native's forwarder does not wire up (a lazy-chat / first-turn gate to
-  confirm); kimi-native and own-auth natives need a vendor provider setup the
-  bench cannot provision (kimi in particular has no gateway path — it routes
-  via `kimi provider add`, out of band).
-- **P1 dimensions + their probes** — steering, live-queue, resume/fork,
-  elicitation ASK, reasoning, images, cost, compaction.
-- Exact `BenchProfile` field set and whether it subsumes `HarnessProbe` or wraps
-  it; whether the manifest fully retires the spreadsheet or diffs against an
-  exported CSV during transition.
+- **Declarative native tool-relay mechanism** — extend the harness capability
+  model to distinguish generated MCP, native registration, and no relay. Derive
+  the Omnigent MCP probe's applicability from that declaration instead of the
+  bench's temporary `_NATIVE_OMNIGENT_MCP_HARNESSES` list.
+- **Registry-driven native-agent seeding** — replace the hardcoded server
+  seeding list with registry iteration so community native harnesses work end
+  to end after plugin installation.
+- **Per-harness native provisioning** — some vendors require login or provider
+  configuration that the bench deliberately cannot create. Improve diagnostics
+  where possible while retaining clean skips.
+- **Additional dimensions** — steering, live queue, resume, images, and
+  compaction.

examples/aws_analyst/README.md

@@ -0,0 +1,35 @@
+# AWS Analyst
+
+An example Omnigent agent that answers questions over **governed AWS data** through
+the official [AWS Labs MCP servers](https://github.com/awslabs/mcp) — no custom
+connector code required. It shows how any AWS Labs MCP server plugs into Omnigent as
+a `type: mcp` tool.
+
+Wired connectors (both **read-only** by default):
+
+| Connector | AWS Labs server | Tools surfaced |
+|---|---|---|
+| `redshift` | `awslabs.redshift-mcp-server` | `list_clusters`, `list_databases`, `list_schemas`, `list_tables`, `list_columns`, `execute_query` |
+| `s3-tables` | `awslabs.s3-tables-mcp-server` | metadata discovery + read-only SQL |
+
+## Prerequisites
+
+- [`uv`/`uvx`](https://docs.astral.sh/uv/) on `PATH` — the AWS Labs servers are
+  published to PyPI as `awslabs.*` and launched via `uvx ...@latest`.
+- AWS credentials the servers can resolve: an `AWS_PROFILE` + `AWS_REGION`, or an
+  IAM role on the host.
+
+## Run
+
+```bash
+AWS_PROFILE=my-profile AWS_REGION=us-east-1 omnigent run examples/aws_analyst
+```
+
+## Notes
+
+- The S3 Tables server defaults to read-only; this recipe intentionally does **not**
+  pass `--allow-write`.
+- The `tools:` allow-list on the Redshift connector limits what the model can call —
+  a good default for a governed analytics agent.
+- Pairs naturally with a Databricks Genie connector for a Databricks-on-AWS
+  "better together" analyst that reasons across both platforms.

examples/aws_analyst/config.yaml

@@ -0,0 +1,70 @@
+# AWS Analyst — query governed AWS data through official awslabs MCP servers.
+#
+# This example agent wires two AWS Labs MCP servers as Omnigent connectors:
+#   - Amazon Redshift  (awslabs.redshift-mcp-server)
+#   - Amazon S3 Tables (awslabs.s3-tables-mcp-server)
+# Both run read-only by default. The agent uses them to answer analytical
+# questions over data governed in AWS — a natural companion to Databricks Genie
+# in a Databricks-on-AWS "better together" setup.
+#
+# Prerequisites:
+#   - `uvx` on PATH (the awslabs servers are published to PyPI as awslabs.*).
+#   - AWS credentials resolvable by the servers (AWS_PROFILE + AWS_REGION, or a role).
+#
+# Usage:
+#   AWS_PROFILE=my-profile AWS_REGION=us-east-1 omnigent run examples/aws_analyst
+
+spec_version: 1
+name: aws_analyst
+description: >-
+  An analyst agent that answers questions over governed AWS data — Amazon Redshift
+  and Amazon S3 Tables — through the official awslabs MCP servers (read-only).
+
+executor:
+  type: omnigent
+  config:
+    harness: claude-sdk
+
+tools:
+  # Amazon Redshift — discovery + read-only SQL over your clusters.
+  redshift:
+    type: mcp
+    command: uvx
+    args: [awslabs.redshift-mcp-server@latest]
+    env:
+      AWS_PROFILE: ${AWS_PROFILE}
+      AWS_REGION: ${AWS_REGION}
+      FASTMCP_LOG_LEVEL: INFO
+    # Allow-list: only these tools are surfaced to the model. execute_query is
+    # read-only on the server side; the discovery tools let the agent map the
+    # environment before querying.
+    tools: [list_clusters, list_databases, list_schemas, list_tables, list_columns, execute_query]
+
+  # Amazon S3 Tables — read-only metadata discovery + SQL over table buckets.
+  # (Server defaults to read-only; --allow-write is intentionally NOT set.)
+  s3-tables:
+    type: mcp
+    command: uvx
+    args: [awslabs.s3-tables-mcp-server@latest]
+    env:
+      AWS_PROFILE: ${AWS_PROFILE}
+      AWS_REGION: ${AWS_REGION}
+
+prompt: |
+  You are an AWS data analyst. You answer questions over governed AWS data using
+  two toolsets:
+
+  - `redshift` — Amazon Redshift. Start by discovering the environment
+    (list_clusters → list_databases → list_schemas → list_tables → list_columns)
+    before writing SQL, then use execute_query for read-only analytical queries.
+  - `s3-tables` — Amazon S3 Tables. Use it for metadata discovery and read-only
+    SQL over table buckets.
+
+  Rules:
+  - Prefer discovery before querying; never assume a table or column exists —
+    confirm it with the list_* tools first.
+  - These tools are read-only. Do not attempt inserts, updates, or deletes.
+  - Always state which source (Redshift or S3 Tables) and which table an answer
+    came from, so results are auditable.
+  - When a question spans multiple tables, explain your join logic before running
+    the query.

examples/polly/agents/claude_code/config.yaml

@@ -22,6 +22,8 @@ prompt: |
     contract.
   - Make the change, then drive it to green: run the relevant tests, lint, and
     typecheck for the code you touched.
+  - When you report test results, include the exact command and file set. If
+    you mention counts, distinguish collected test cases from test functions.
   - Co-sign every commit you author: end each commit message with a blank line
     followed by this exact trailer as its final line —
     `Co-authored-by: omnigent <noreply@omnigent.ai>`

examples/polly/agents/codex/config.yaml

@@ -22,6 +22,8 @@ prompt: |
     contract.
   - Make the change, then drive it to green: run the relevant tests, lint, and
     typecheck for the code you touched.
+  - When you report test results, include the exact command and file set. If
+    you mention counts, distinguish collected test cases from test functions.
   - Co-sign every commit you author: end each commit message with a blank line
     followed by this exact trailer as its final line —
     `Co-authored-by: omnigent <noreply@omnigent.ai>`

examples/polly/agents/cursor/config.yaml

@@ -3,14 +3,23 @@ name: cursor
 description: Cursor coding sub-agent — implements, cross-vendor reviews, or explores a scoped task in its own worktree.
 
 # Native Cursor TUI harness (`cursor-agent`): runs in its own terminal the
-# human can open in the UI's Subagents panel and TAKE OVER. cursor-agent owns
-# its own tool-approval gating (omnigent does not intercept it), so dangerous
-# actions surface in the cursor TUI / mirrored web cards rather than being
-# auto-bypassed.
+# human can open in the UI's Subagents panel and TAKE OVER. Headless workers
+# can't answer ApprovalCards, so YOLO skips cursor-agent's in-terminal
+# prompts (and the mirrored web cards). Omnigent ``blast_radius`` still
+# DENYs the catastrophic set. Opt out with ``yolo: false``; or set
+# ``permission_mode: auto`` for Smart Auto (``--auto-review``) instead.
 executor:
   type: omnigent
+  # Faster default for Polly Cursor workers; override per-session with ``/model``.
+  # Use the base id from Cursor's model list / SDK (``grok-4.5``). The compound
+  # ``cursor-grok-4.5-high`` also works on cursor-agent, but the SDK catalog
+  # exposes ``grok-4.5``.
+  model: grok-4.5
   config:
     harness: cursor-native
+    # YOLO: headless workers can't answer approval prompts, so run
+    # cursor-agent with full bypass (``--yolo``).
+    yolo: true
 
 prompt: |
   You are Cursor, a coding sub-agent dispatched by the polly
@@ -23,6 +32,8 @@ prompt: |
     contract.
   - Make the change, then drive it to green: run the relevant tests, lint, and
     typecheck for the code you touched.
+  - When you report test results, include the exact command and file set. If
+    you mention counts, distinguish collected test cases from test functions.
   - Co-sign every commit you author: end each commit message with a blank line
     followed by this exact trailer as its final line —
     `Co-authored-by: omnigent <noreply@omnigent.ai>`

examples/polly/agents/hermes/config.yaml

@@ -22,6 +22,8 @@ prompt: |
     contract.
   - Make the change, then drive it to green: run the relevant tests, lint, and
     typecheck for the code you touched.
+  - When you report test results, include the exact command and file set. If
+    you mention counts, distinguish collected test cases from test functions.
   - Co-sign every commit you author: end each commit message with a blank line
     followed by this exact trailer as its final line —
     `Co-authored-by: omnigent <noreply@omnigent.ai>`

examples/polly/agents/opencode/config.yaml

@@ -23,6 +23,8 @@ prompt: |
     contract.
   - Make the change, then drive it to green: run the relevant tests, lint, and
     typecheck for the code you touched.
+  - When you report test results, include the exact command and file set. If
+    you mention counts, distinguish collected test cases from test functions.
   - Co-sign every commit you author: end each commit message with a blank line
     followed by this exact trailer as its final line —
     `Co-authored-by: omnigent <noreply@omnigent.ai>`

examples/polly/agents/pi/config.yaml

@@ -21,6 +21,8 @@ prompt: |
     contract.
   - Make the change, then drive it to green: run the relevant tests, lint, and
     typecheck for the code you touched.
+  - When you report test results, include the exact command and file set. If
+    you mention counts, distinguish collected test cases from test functions.
   - Co-sign every commit you author: end each commit message with a blank line
     followed by this exact trailer as its final line —
     `Co-authored-by: omnigent <noreply@omnigent.ai>`

examples/polly/config.yaml

@@ -24,7 +24,7 @@ spawn: true
 # (`omnigent setup --no-internal-beta`) — an Anthropic API key, a Claude
 # subscription, an OpenAI-compatible gateway, or a Databricks workspace. With
 # no model named the claude-sdk harness resolves the configured provider's
-# default Claude model (the bundled catalog default is claude-opus-4-8).
+# default Claude model.
 executor:
   type: omnigent
   context_window: 1000000
@@ -178,6 +178,16 @@ prompt: |
   write or edit source code or tests, run a deep code investigation for your own
   answer, or merge a PR — those go to sub-agents.
 
+  Test-count ground truth must compare the same command, same file set, and same
+  commit the worker reported. For pytest, collected CASES are the count: use
+  `python -m pytest --collect-only -q <same files>` when reconciling a reported
+  total, and never use `grep -c 'def test_'` as a correctness oracle. A single
+  test function can expand into many collected cases via parametrized tests, and
+  a one-file function count cannot be compared to a multi-file gate. Do not record
+  `miscount`, `over-report`, or `fabrication` in `.polly/registry.json` or a
+  handoff unless you have re-collected the same gate at the same commit and the
+  numbers still disagree.
+
   For long-running processes that can't block a single tool call (a local dev
   server on localhost:PORT, file watchers, tailing logs) or ad-hoc shell where
   `sys_os_shell`'s one-shot blocking model doesn't fit, launch the `shell`

examples/polly/skills/cross-review/SKILL.md

@@ -15,6 +15,11 @@ anyone needs to read through.
 2. Run the deterministic gates first — tests / lint / typecheck via
    `sys_os_shell`. If red, re-dispatch the implementer to drive it green first;
    don't involve the reviewer yet.
+   If a pytest result's count must be recorded or reconciled, collect ground
+   truth with `python -m pytest --collect-only -q <same files>` against the
+   exact file set/command/commit the implementer reported. Never use
+   `grep -c 'def test_'` as a pytest count: it counts functions, not collected
+   cases, and misses parametrized case expansion.
 3. Dispatch a DIFFERENT-vendor sub-agent as reviewer: pick any AVAILABLE worker
    whose vendor differs from the implementer's — `claude_code`, `codex`,
    `opencode`, `cursor`, `hermes`, or `pi` (e.g. Claude built it → any of

examples/remy/config.yaml

@@ -0,0 +1,65 @@
+# Remy — an assistant that remembers.
+#
+# Remy uses Hindsight long-term memory so what you tell it in one run is
+# available in every future run. Before answering it recalls what it already
+# knows about you; when you share a durable fact it retains it; and it can
+# reflect over everything it has stored.
+#
+# Memory is keyed by the agent id, so all of Remy's runs share one memory bank.
+#
+# Setup:
+#   pip install 'omnigent[hindsight]'
+#   export HINDSIGHT_API_KEY=hsk_...        # https://ui.hindsight.vectorize.io
+#
+# Usage:
+#   omnigent run examples/remy
+#
+# Remy runs on the Claude Agent SDK harness, so configure a Claude provider
+# first (e.g. `omnigent setup`, or export ANTHROPIC_API_KEY).
+
+spec_version: 1
+name: remy
+description: >-
+  A helpful assistant with long-term memory. Remy recalls what it already knows
+  before answering, retains durable facts you share, and can reflect over its
+  memory — powered by Hindsight.
+
+executor:
+  type: omnigent
+  config:
+    harness: claude-sdk
+
+prompt: |
+  You are Remy, a helpful assistant with long-term memory powered by Hindsight.
+
+  Your conversation context is wiped between sessions — the ONLY way you
+  remember anything is by calling these tools. Acknowledging a fact in chat does
+  NOT save it.
+
+  Use your memory tools deliberately:
+  - Call `hindsight_recall` BEFORE answering anything that might depend on what
+    you already know about the user or past conversations.
+  - When the user shares a durable fact, preference, or decision — or asks you
+    to remember something — you MUST call `hindsight_retain`. Never say you have
+    saved or will remember something unless `hindsight_retain` actually ran and
+    returned success in this turn.
+  - Call `hindsight_reflect` when the user asks you to summarize or reason about
+    what you know overall, rather than retrieve specific facts.
+
+  Weave recalled memories into your answer naturally — don't dump raw tool
+  output. If recall returns nothing relevant, just answer normally.
+
+# bank_id pins a stable, human-readable memory bank. Omit it and the bank
+# defaults to the agent id (per-agent isolation) — handy, but opaque to find
+# in Hindsight. A fixed name keeps Remy's memory in one easy-to-inspect bank.
+tools:
+  builtins:
+    - name: hindsight_recall
+      api_key: ${HINDSIGHT_API_KEY}
+      bank_id: remy
+    - name: hindsight_retain
+      api_key: ${HINDSIGHT_API_KEY}
+      bank_id: remy
+    - name: hindsight_reflect
+      api_key: ${HINDSIGHT_API_KEY}
+      bank_id: remy

integrations/slack/.env.example

@@ -0,0 +1,22 @@
+SLACK_BOT_TOKEN=xoxb-your-bot-token
+SLACK_APP_TOKEN=xapp-your-app-level-token
+OMNIGENT_AGENT_NAME=your_agent_name
+
+# Optional. Defaults to the local Omnigent server from docs/api-1.yaml.
+OMNIGENT_BASE_URL=http://127.0.0.1:6767
+
+# Optional Omnigent auth modes.
+# OMNIGENT_AUTH_EMAIL=slack-bot@example.com
+# OMNIGENT_AUTH_HEADER_NAME=X-Forwarded-Email
+# OMNIGENT_SESSION_COOKIE=ap_session=...
+
+# Optional runner fallback. If no online runner exists, launch one on a host.
+# Defaults to the bot process current working directory.
+# OMNIGENT_RUNNER_WORKSPACE=/absolute/path/to/workspace
+# OMNIGENT_RUNNER_HOST_ID=host_optional_specific_host
+# OMNIGENT_RUNNER_LAUNCH_TIMEOUT_SECONDS=60
+
+# Optional runtime tuning.
+# LOG_LEVEL=INFO
+# OMNIGENT_SLACK_DATABASE_PATH=data/omnigent_slack.sqlite3
+# SLACK_UPDATE_INTERVAL_SECONDS=1.0

integrations/slack/.gitignore

@@ -0,0 +1,10 @@
+.env
+.venv/
+.uv-cache/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+data/*.sqlite3
+data/*.sqlite3-*

integrations/slack/.python-version

@@ -0,0 +1 @@
+3.12

integrations/slack/README.md

@@ -0,0 +1,39 @@
+# Omnigent Slack Bot
+
+Slack Socket Mode bot that maps one Slack thread to one Omnigent session.
+
+## Setup
+
+1. Create a Slack app with Socket Mode enabled.
+2. Add bot scopes for `app_mentions:read`, `chat:write`, and the history scopes needed for the channel types where the bot will run.
+3. Install the app into the workspace.
+4. Copy `.env.example` to `.env` and fill in Slack and Omnigent values.
+5. Run the bot:
+
+```bash
+UV_CACHE_DIR=.uv-cache uv run omnigent-slack
+```
+
+Set `LOG_LEVEL=DEBUG` in `.env` when diagnosing why Slack events are not producing replies.
+
+If Omnigent has no online runners, the bot launches one on an online host using
+the current working directory as the workspace. Set `OMNIGENT_RUNNER_WORKSPACE`
+when the host needs a different absolute path.
+
+Mention the bot with a message to start a session:
+
+```text
+@your-bot help me inspect this failure
+```
+
+Replies in that Slack thread continue the same Omnigent session.
+
+## Development
+
+```bash
+UV_CACHE_DIR=.uv-cache uv run pytest
+UV_CACHE_DIR=.uv-cache uv run ruff check
+UV_CACHE_DIR=.uv-cache uv run mypy src
+```
+
+The Omnigent API reference used for implementation is stored at `docs/api-1.yaml`.

integrations/slack/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "omnigent-slack"
+version = "0.1.0"
+description = "Slack Socket Mode bot that drives Omnigent sessions."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "aiosqlite>=0.21.0",
+    "aiohttp>=3.12.0",
+    "httpx>=0.28.0",
+    "pydantic-settings>=2.10.0",
+    "python-dotenv>=1.1.0",
+    "slack-bolt>=1.23.0",
+    "markdown-to-mrkdwn>=0.3.3",
+]
+
+[project.scripts]
+omnigent-slack = "omnigent_slack.__main__:main"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.16.0",
+    "pytest>=8.4.0",
+    "pytest-asyncio>=1.0.0",
+    "respx>=0.22.0",
+    "ruff>=0.12.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.0,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+exclude = [".uv-cache", ".venv", "docs"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unreachable = true
+
+[[tool.mypy.overrides]]
+module = [
+    "slack_bolt.*",
+    "slack_sdk.*",
+    "markdown_to_mrkdwn.*",
+]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

integrations/slack/src/omnigent_slack/__init__.py

@@ -0,0 +1,5 @@
+"""Slack bot for Omnigent sessions."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

integrations/slack/src/omnigent_slack/__main__.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import asyncio
+
+from omnigent_slack.app import run
+
+
+def main() -> None:
+    asyncio.run(run())
+
+
+if __name__ == "__main__":
+    main()

integrations/slack/src/omnigent_slack/app.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from dotenv import load_dotenv
+from slack_bolt.adapter.socket_mode.aiohttp import AsyncSocketModeHandler
+from slack_bolt.async_app import AsyncApp
+
+from omnigent_slack.config import load_settings
+from omnigent_slack.omnigent import OmnigentAuth, OmnigentClient
+from omnigent_slack.service import SlackOmnigentService
+from omnigent_slack.store import SQLiteStore
+
+
+async def run() -> None:
+    load_dotenv()
+    settings = load_settings()
+    logging.basicConfig(
+        level=getattr(logging, settings.log_level.upper(), logging.INFO),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    logger = logging.getLogger(__name__)
+    logger.info(
+        "Starting Omnigent Slack bot base_url=%s database=%s runner_workspace=%s",
+        settings.omnigent_base_url,
+        settings.database_path,
+        settings.omnigent_runner_workspace,
+    )
+
+    store = SQLiteStore(settings.database_path)
+    await store.initialize()
+
+    omnigent = OmnigentClient(
+        base_url=str(settings.omnigent_base_url),
+        auth=OmnigentAuth(
+            email=settings.omnigent_auth_email,
+            header_name=settings.omnigent_auth_header_name,
+            session_cookie=settings.omnigent_session_cookie,
+        ),
+        runner_workspace=settings.omnigent_runner_workspace,
+        runner_host_id=settings.omnigent_runner_host_id,
+        runner_launch_timeout_seconds=settings.omnigent_runner_launch_timeout_seconds,
+    )
+    logger.info("Checking Omnigent server availability base_url=%s", settings.omnigent_base_url)
+    try:
+        agents = await omnigent.list_agents()
+    except Exception:
+        logger.exception(
+            "Omnigent server is not reachable at %s; aborting startup", settings.omnigent_base_url
+        )
+        await omnigent.aclose()
+        raise
+    logger.info("Omnigent server is up; found %s built-in agents", len(agents))
+
+    agent_id = _resolve_agent_id(agents, settings.omnigent_agent_name)
+    if agent_id is None:
+        available = ", ".join(sorted(str(a.get("name")) for a in agents if a.get("name"))) or "none"
+        await omnigent.aclose()
+        raise RuntimeError(
+            f"No Omnigent agent named {settings.omnigent_agent_name!r} was found. "
+            f"Available agents: {available}"
+        )
+    logger.info("Resolved Omnigent agent name=%s to id=%s", settings.omnigent_agent_name, agent_id)
+
+    service = SlackOmnigentService(
+        store=store,
+        omnigent=omnigent,
+        omnigent_agent_id=agent_id,
+        update_interval_seconds=settings.slack_update_interval_seconds,
+    )
+
+    app = AsyncApp(token=settings.slack_bot_token)
+    register_handlers(app, service)
+
+    handler = AsyncSocketModeHandler(app, settings.slack_app_token)
+    try:
+        logger.info("Connecting to Slack Socket Mode")
+        await handler.start_async()  # type: ignore[no-untyped-call]
+    finally:
+        logger.info("Shutting down Omnigent Slack bot")
+        await service.shutdown()
+        await omnigent.aclose()
+
+
+def _resolve_agent_id(agents: list[dict[str, Any]], agent_name: str) -> str | None:
+    for agent in agents:
+        if agent.get("name") == agent_name:
+            agent_id = agent.get("id")
+            if isinstance(agent_id, str):
+                return agent_id
+    return None
+
+
+def register_handlers(app: AsyncApp, service: SlackOmnigentService) -> None:
+    @app.event("app_mention")
+    async def handle_app_mention(
+        body: dict[str, Any],
+        event: dict[str, Any],
+        client: Any,
+        context: dict[str, Any],
+    ) -> None:
+        await service.handle_app_mention(body=body, event=event, client=client, context=context)
+
+    @app.event("message")
+    async def handle_message(
+        body: dict[str, Any],
+        event: dict[str, Any],
+        client: Any,
+        context: dict[str, Any],
+    ) -> None:
+        if not body.get("team_id") and not event.get("team"):
+            return
+        await service.handle_message(body=body, event=event, client=client, context=context)

integrations/slack/src/omnigent_slack/config.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        case_sensitive=False,
+    )
+
+    slack_bot_token: str = Field(validation_alias="SLACK_BOT_TOKEN")
+    slack_app_token: str = Field(validation_alias="SLACK_APP_TOKEN")
+    omnigent_agent_name: str = Field(validation_alias="OMNIGENT_AGENT_NAME")
+
+    omnigent_base_url: str = Field(
+        default="http://127.0.0.1:6767",
+        validation_alias="OMNIGENT_BASE_URL",
+    )
+    omnigent_auth_email: str | None = Field(default=None, validation_alias="OMNIGENT_AUTH_EMAIL")
+    omnigent_auth_header_name: str = Field(
+        default="X-Forwarded-Email",
+        validation_alias="OMNIGENT_AUTH_HEADER_NAME",
+    )
+    omnigent_session_cookie: str | None = Field(
+        default=None,
+        validation_alias="OMNIGENT_SESSION_COOKIE",
+    )
+    omnigent_runner_workspace: str = Field(
+        default_factory=lambda: str(Path.cwd()),
+        validation_alias="OMNIGENT_RUNNER_WORKSPACE",
+    )
+    omnigent_runner_host_id: str | None = Field(
+        default=None,
+        validation_alias="OMNIGENT_RUNNER_HOST_ID",
+    )
+    omnigent_runner_launch_timeout_seconds: float = Field(
+        default=60.0,
+        ge=1.0,
+        validation_alias="OMNIGENT_RUNNER_LAUNCH_TIMEOUT_SECONDS",
+    )
+
+    database_path: Path = Field(
+        default=Path("data/omnigent_slack.sqlite3"),
+        validation_alias="OMNIGENT_SLACK_DATABASE_PATH",
+    )
+    log_level: str = Field(default="INFO", validation_alias="LOG_LEVEL")
+    slack_update_interval_seconds: float = Field(
+        default=1.0,
+        ge=0.0,
+        validation_alias="SLACK_UPDATE_INTERVAL_SECONDS",
+    )
+
+
+def load_settings() -> Settings:
+    return Settings()  # type: ignore[call-arg]

integrations/slack/src/omnigent_slack/dispatcher.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+
+from omnigent_slack.models import SlackTurn, ThreadKey
+
+TurnWorker = Callable[[SlackTurn], Awaitable[None]]
+
+
+class ThreadTurnDispatcher:
+    def __init__(self, worker: TurnWorker, idle_timeout_seconds: float = 60.0) -> None:
+        self._worker = worker
+        self._idle_timeout_seconds = idle_timeout_seconds
+        self._queues: dict[ThreadKey, asyncio.Queue[SlackTurn]] = {}
+        self._tasks: dict[ThreadKey, asyncio.Task[None]] = {}
+        self._lock = asyncio.Lock()
+        self._logger = logging.getLogger(__name__)
+
+    async def enqueue(self, turn: SlackTurn) -> None:
+        async with self._lock:
+            queue = self._queues.get(turn.key)
+            if queue is None:
+                queue = asyncio.Queue()
+                self._queues[turn.key] = queue
+                self._tasks[turn.key] = asyncio.create_task(self._run_queue(turn.key, queue))
+                self._logger.debug("Created turn queue for %s", turn.key.display())
+            await queue.put(turn)
+            self._logger.info(
+                "Queued Slack turn thread=%s queue_size=%s create_if_missing=%s",
+                turn.key.display(),
+                queue.qsize(),
+                turn.create_if_missing,
+            )
+
+    async def shutdown(self) -> None:
+        async with self._lock:
+            tasks = list(self._tasks.values())
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+    async def _run_queue(self, key: ThreadKey, queue: asyncio.Queue[SlackTurn]) -> None:
+        try:
+            while True:
+                try:
+                    turn = await asyncio.wait_for(queue.get(), timeout=self._idle_timeout_seconds)
+                except TimeoutError:
+                    self._logger.debug("Closing idle turn queue for %s", key.display())
+                    return
+                try:
+                    self._logger.info("Running queued Slack turn thread=%s", key.display())
+                    await self._worker(turn)
+                except Exception:
+                    self._logger.exception("Slack turn failed for %s", key.display())
+                finally:
+                    queue.task_done()
+        finally:
+            async with self._lock:
+                if self._queues.get(key) is queue:
+                    if queue.empty():
+                        self._queues.pop(key, None)
+                        self._tasks.pop(key, None)
+                    else:
+                        # A turn slipped in after the idle timeout fired but
+                        # before this teardown reacquired the lock. The queue
+                        # stays registered, so no future enqueue would spawn a
+                        # worker — re-arm one here to keep draining it.
+                        self._tasks[key] = asyncio.create_task(self._run_queue(key, queue))

integrations/slack/src/omnigent_slack/models.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class ThreadKey:
+    team_id: str
+    channel_id: str
+    thread_ts: str
+
+    @classmethod
+    def from_event(cls, team_id: str, event: dict[str, object]) -> ThreadKey:
+        channel_id = str(event["channel"])
+        thread_ts = str(event.get("thread_ts") or event["ts"])
+        return cls(team_id=team_id, channel_id=channel_id, thread_ts=thread_ts)
+
+    def display(self) -> str:
+        return f"{self.team_id}:{self.channel_id}:{self.thread_ts}"
+
+
+@dataclass(frozen=True, slots=True)
+class SlackTurn:
+    key: ThreadKey
+    text: str
+    user_id: str
+    create_if_missing: bool
+    title: str
+    slack_client: Any