docs(models): delegate Kimi example default

Remove the release-specific model from the Kimi launcher example so an unoverridden session uses the default already configured in the Kimi CLI.

Document the ownership boundary, assert that the spawn environment omits HARNESS_KIMI_MODEL when no model is declared, and ratchet the retired lint allowance.

Tests: 12 Kimi spawn-environment tests; structural example load; staged pre-commit including YAML and hardcoded-model checks.

Part of #3426

Signed-off-by: Pat Sukprasert <pat.sukprasert@databricks.com>

.claude/skills/antigravity-native-e2e-dev/SKILL.md

@@ -71,8 +71,10 @@ Three transports, easy to confuse:
    agy models   # exits 0 and lists models only when signed in; else 'Please sign in'
    ```
    `False` / non-zero → run `agy` once and sign in. agy's token lives under
-   `~/.gemini` (`oauth_creds.json` on macOS, `antigravity-cli/antigravity-oauth-token`
-   on Linux).
+   `~/.gemini` (`oauth_creds.json` on macOS through 1.0.10,
+   `antigravity-cli/antigravity-oauth-token` on Linux); agy 1.1.7+ on macOS
+   writes no token file and keeps the credential in the Keychain, which is why
+   `gemini_login_detected()` falls back to `agy models` there.
 4. **`tmux` is on PATH.** The agy terminal is a runner-owned tmux pane; the CLI
    attaches to it and the executor drives it via `tmux send-keys`
    (`_preflight_local_tools` hard-fails without tmux).
@@ -86,7 +88,7 @@ Three transports, easy to confuse:
 
 ```bash
 cd /path/to/omnigent
-.venv/bin/omni server start          # detached managed server on a free loopback port
+.venv/bin/omni server --background          # detached managed server on a free loopback port
 .venv/bin/omni server status         # prints the URL, e.g. http://127.0.0.1:6767
 SERVER=http://127.0.0.1:6767         # use the printed URL below
 curl -s "$SERVER/health"             # {"status":"ok"}

.claude/skills/antigravity-sdk-e2e-dev/SKILL.md

@@ -47,7 +47,7 @@ tests.
 
 ```bash
 cd /path/to/omnigent
-.venv/bin/omni server start          # spawns a detached server on a free loopback port
+.venv/bin/omni server --background          # spawns a detached server on a free loopback port
 .venv/bin/omni server status         # prints the URL, e.g. http://127.0.0.1:6767
 ```
 
@@ -134,7 +134,7 @@ streaming, harness.
 7. **Turns take ~10–60s** — always wrap in `timeout 280`.
 8. **Local-runner topology:** `omni run <bundle> --server <url>` runs the
    harness from your **current checkout**; the server only holds state. The
-   managed `omni server start` server runs from whatever venv launched it.
+   managed `omni server --background` server runs from whatever venv launched it.
 9. **Never print/echo the Gemini key** in logs or commands.
 
 ## Code & tests

.claude/skills/copilot-sdk-e2e-dev/SKILL.md

@@ -44,7 +44,7 @@ the unit tests.
 
 ```bash
 cd /path/to/omnigent
-.venv/bin/omni server --port 7788 --no-open    # foreground; or `omni server start` for detached
+.venv/bin/omni server --port 7788 --no-open    # foreground; or `omni server --background` for detached
 curl -s http://127.0.0.1:7788/health           # {"status":"ok"}
 ```
 

.claude/skills/cursor-sdk-e2e-dev/SKILL.md

@@ -35,7 +35,7 @@ Cursor as SDK `custom_tools`. This skill is the proven recipe for running it
 
 ```bash
 cd /path/to/omnigent
-.venv/bin/omni server start          # spawns a detached server on a free loopback port
+.venv/bin/omni server --background          # spawns a detached server on a free loopback port
 .venv/bin/omni server status         # prints the URL, e.g. http://127.0.0.1:6767
 ```
 
@@ -116,7 +116,7 @@ that works, the full stack is good: key, egress, bridge, harness.
 5. **Turns take 30–90s** — always wrap in `timeout 280`.
 6. **Local-runner topology:** `omni run <bundle> --server <url>` runs the
    harness from your **current checkout**; the server only holds state. The
-   managed `omni server start` server runs from whatever venv launched it.
+   managed `omni server --background` server runs from whatever venv launched it.
 7. **Never print/echo the Cursor key** in logs or commands.
 
 ## Code & tests

.claude/skills/pi-native-e2e-dev/SKILL.md

@@ -76,7 +76,7 @@ Two ways a turn reaches Pi — test both:
 
 ```bash
 cd /path/to/omnigent
-.venv/bin/omni server start          # detached managed server on a free loopback port
+.venv/bin/omni server --background          # detached managed server on a free loopback port
 .venv/bin/omni server status         # prints the URL, e.g. http://127.0.0.1:6767
 SERVER=http://127.0.0.1:6767         # use the printed URL below
 curl -s "$SERVER/health"             # {"status":"ok"}

.claude/skills/polly-e2e-dev/SKILL.md

@@ -118,7 +118,7 @@ right vendor, cross-reviews). That is the live recipe.
 ### Run a live turn
 
 ```bash
-.venv/bin/omni server start && .venv/bin/omni server status   # prints $SERVER, e.g. http://127.0.0.1:6767
+.venv/bin/omni server --background && .venv/bin/omni server status   # prints $SERVER, e.g. http://127.0.0.1:6767
 SERVER=http://127.0.0.1:6767
 timeout 280 .venv/bin/omni run examples/polly \
   -p "Investigate how the runner enforces tool-call policies and report file:line evidence." \

.github/MAINTAINER

@@ -10,11 +10,13 @@ dhruv0811
 Edwinhe03
 fanzeyi
 kerryspchang
+kunyuchen
 lisancao
 mahesh-venkatachalam
 mateiz
 newfront
 PattaraS
+rahulrav1
 SabhyaC26
 serena-ruan
 shivam5

.github/actions/run-omnigent-agent/action.yml

@@ -0,0 +1,128 @@
+name: Run Omnigent agent
+description: >-
+  Set up uv + the Claude Code CLI + an Omnigent gateway provider, run a tools-less
+  Omnigent agent headlessly on a prompt file, and secret-scan its output. Shared by
+  the release-cut (draft-release-notes) and publish (publish-changelog) workflows so
+  the LLM-runner scaffold lives in one place. The caller mints no write-token until
+  after this action returns — the only secret here is the model key.
+
+inputs:
+  workdir:
+    description: >-
+      Repo checkout dir relative to the workspace (`.` when checked out at the
+      root, `omnigent` when checked out into a subdir). Drives the venv path, the
+      cache key, and the uv --project / agent paths.
+    required: false
+    default: "."
+  agent:
+    description: Agent directory name under <workdir>/.github/agents/.
+    required: true
+  prompt-file:
+    description: Absolute path to the file holding the agent prompt.
+    required: true
+  output-file:
+    description: Absolute path to write the agent's stdout to.
+    required: true
+  stderr-file:
+    description: Absolute path to write the agent's stderr to.
+    required: false
+    default: /tmp/omnigent-agent-stderr.log
+  gateway-base-url:
+    description: Base URL of the Anthropic-compatible gateway.
+    required: true
+  llm-api-key:
+    description: Model API key (referenced by the provider config, used to scan output).
+    required: true
+  claude-code-version:
+    description: "@anthropic-ai/claude-code npm version to install."
+    required: false
+    default: 2.1.212
+
+runs:
+  using: composite
+  steps:
+    - name: Set up uv
+      uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      with:
+        enable-cache: true
+
+    - name: Cache virtualenv
+      uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+      with:
+        path: ${{ inputs.workdir }}/.venv
+        key: venv-${{ runner.os }}-${{ hashFiles(format('{0}/.python-version', inputs.workdir)) }}-${{ hashFiles(format('{0}/uv.lock', inputs.workdir)) }}
+
+    - name: Install dependencies
+      shell: bash
+      working-directory: ${{ inputs.workdir }}
+      run: uv sync --extra all --extra dev
+
+    - name: Install Claude Code CLI
+      shell: bash
+      env:
+        NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
+        CLAUDE_CODE_VERSION: ${{ inputs.claude-code-version }}
+      run: |
+        set -euo pipefail
+        # Install outside the checked-out tree: a repo-root package.json would
+        # otherwise capture this bare `npm install` and hoist it there, leaving
+        # this dir's node_modules empty.
+        CC_CLI_DIR="${RUNNER_TEMP}/omnigent-cc-cli"
+        mkdir -p "$CC_CLI_DIR"
+        cd "$CC_CLI_DIR"
+        npm install --ignore-scripts --no-audit --no-fund "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}"
+        node node_modules/@anthropic-ai/claude-code/install.cjs
+        echo "$CC_CLI_DIR/node_modules/.bin" >> "$GITHUB_PATH"
+
+    - name: Write Omnigent provider config
+      shell: bash
+      env:
+        GATEWAY_BASE_URL: ${{ inputs.gateway-base-url }}
+      run: |
+        set -euo pipefail
+        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))
+        "
+
+    - name: Run the agent
+      shell: bash
+      env:
+        LLM_API_KEY: ${{ inputs.llm-api-key }}
+        WORKDIR: ${{ inputs.workdir }}
+        AGENT: ${{ inputs.agent }}
+        PROMPT_FILE: ${{ inputs.prompt-file }}
+        OUTPUT_FILE: ${{ inputs.output-file }}
+        STDERR_FILE: ${{ inputs.stderr-file }}
+      run: |
+        set -euo pipefail
+        project="${GITHUB_WORKSPACE}/${WORKDIR}"
+        prompt="$(cat "$PROMPT_FILE")"
+        uv run --project "$project" omnigent run \
+          "${project}/.github/agents/${AGENT}" \
+          -p "$prompt" --no-session \
+          2>"$STDERR_FILE" | tee "$OUTPUT_FILE" \
+          || { echo "::warning::agent exited non-zero — caller keeps its fallback"; cat "$STDERR_FILE"; }
+
+    # ::add-mask:: only redacts rendered logs; the caller still redacts artifact
+    # files before upload. This aborts the run outright if the key leaked to stdout.
+    - name: Scan agent output for secrets
+      shell: bash
+      env:
+        LLM_API_KEY: ${{ inputs.llm-api-key }}
+        OUTPUT_FILE: ${{ inputs.output-file }}
+      run: |
+        set -euo pipefail
+        if [ -n "${LLM_API_KEY:-}" ] && grep -qF "$LLM_API_KEY" "$OUTPUT_FILE" 2>/dev/null; then
+          echo "::error::Agent output contains LLM_API_KEY — aborting."
+          exit 1
+        fi

.github/actions/setup-node/action.yml

@@ -1,37 +0,0 @@
-name: "setup-node"
-description: "Set up Node and pin npm, with npm dependency caching keyed on the web lockfile."
-
-# Single source of truth for the JS toolchain across CI. Pins npm to the
-# EXACT version that regenerates the lockfile in oss-regenerate-and-smoke.yml
-# (npm 11.12.1); without this, jobs use whatever npm Node 20 bundles
-# (npm 10.x) and the `package-lock.json` freshness gate in lint.yml would
-# flake on version-skew churn (dev/extraneous flags, metadata). Keep this
-# version in lockstep with the regen workflow so generation and
-# verification never diverge.
-
-inputs:
-  node-version:
-    description: "Node version to use."
-    default: "20"
-    required: false
-  cache:
-    description: "Package-manager cache to enable (passed to actions/setup-node)."
-    default: "npm"
-    required: false
-  cache-dependency-path:
-    description: "Lockfile path used as the cache key."
-    default: "web/package-lock.json"
-    required: false
-
-runs:
-  using: "composite"
-  steps:
-    - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4.4.0
-      with:
-        node-version: ${{ inputs.node-version }}
-        cache: ${{ inputs.cache }}
-        cache-dependency-path: ${{ inputs.cache-dependency-path }}
-
-    - name: Pin npm
-      shell: bash
-      run: npm install -g npm@11.12.1

.github/actions/setup-pnpm/action.yml

@@ -0,0 +1,21 @@
+name: "setup-pnpm"
+description: "Set up Node + pnpm for the web workspace"
+
+inputs:
+  node-version:
+    description: "Node version to use."
+    default: "22"
+    required: false
+
+runs:
+  using: composite
+  steps:
+    - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+      with:
+        standalone: true
+
+    - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+      with:
+        node-version: ${{ inputs.node-version }}
+        cache: pnpm
+        cache-dependency-path: pnpm-lock.yaml

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

@@ -17,9 +17,9 @@ 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).
+  the omnigent code, and writes a short one-screen user-facing post, marking 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
@@ -64,6 +64,15 @@ prompt: |
   NEVER write product source code or tests, and you NEVER edit anything in the
   omnigent code repo.
 
+  ## Write ONLY the post page — the blog surface already exists
+  The blog infrastructure is already in place on omnigent-site: `app/blog/`
+  layout + index page auto-discover posts via `lib/blog.js`, and the nav links to
+  it. Your ONE and ONLY output file is `app/blog/<SLUG>/page.mdx`. You MUST NOT
+  create or edit any layout, index (`app/blog/page.js`), sidebar, `lib/` scanner,
+  navigation, or other site plumbing — dropping in the post page is enough for it
+  to appear. If you think infra is missing, flag it under "Manual review needed"
+  rather than scaffolding it (inventing plumbing can break the site build).
+
   ## 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.
@@ -83,54 +92,112 @@ prompt: |
   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
+  ## Step 2 — Match the existing post conventions (read-only)
   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.
+  existing post under `app/blog/` and copy its frontmatter shape and JSX
+  conventions EXACTLY — the import lines, the metadata/frontmatter helper, the
+  frontmatter fields (`date`, `category`, `author`, `heroArt`), and the body
+  structure. Posts are auto-discovered by `lib/blog.js`, so you do NOT register
+  the post anywhere — matching the existing post shape is all that's needed. Read
+  `lib/blog.js` only to confirm which frontmatter fields it expects; do not edit
+  it. Every post's title + author + date + reading-time header is rendered by the
+  `<BlogPostHeader slug="SLUG" />` component (registered globally in
+  `mdx-components.js`, so no import is needed) — use it as the first thing in the
+  body and never hand-write a `# H1` title (item 1 below).
 
   ## 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:
+  Create `app/blog/<SLUG>/page.mdx` — this is the ONLY file you write. 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.
+  The five items below are the SHAPE of the post, in order — they are NOT section
+  headings and NOT sentence lead-ins. Write flowing prose. Do NOT emit label text
+  like "Who it's for:", "The problem it solves", "How to use", or "What's next" —
+  neither as headings nor at the start of a sentence. Do NOT write a Markdown
+  `# H1` title at all — the title and byline are rendered by the header component
+  (see item 1); a `#` heading would duplicate it. Use `##` for any in-body
+  subheadings only if genuinely needed (usually none for a one-screen post).
 
-  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".
+  1. Frontmatter first: after the `import { pageMeta } from "@/lib/og";` line and
+     the exported `metadata`, export a `meta` object carrying
+     `title: "<the benefit HEADLINE>"`, `date: "DATE"`, `category: "CATEGORY"`,
+     `author: "omnigent"` (default; a human may overwrite it during review), and
+     `heroArt: ""`. Then, as the FIRST thing in the body, render the header:
+     `<BlogPostHeader slug="SLUG" />` (use the exact SLUG you were given). This
+     component draws the title + author + date + reading-time byline, so do not
+     repeat the title as text. Follow it with a short opening paragraph that says
+     who it helps and what they can now do as a natural sentence ("If you drive
+     long agent runs in the web UI, you can now line up your next few messages
+     instead of waiting for each turn to finish."), NOT as a "Who it's for:" label.
+  2. In 2–3 sentences, describe the problem this removes and the outcome, in the
+     user's terms. Lead with what the user gets, then just enough of how it works
+     to be concrete. Let the "orchestration layer over many agents, any device,
+     with governance" wedge show through the framing; never sloganeer it.
+  3. The demo. You CANNOT produce the screenshot/recording, so emit EXACTLY this
+     marker where it belongs, with a one-line suggestion of what to show. It MUST
+     be an MDX comment (`{/* ... */}`), NOT an HTML comment (`<!-- ... -->`);
+     HTML comments are invalid in MDX and break the site build:
+     `{/* DEMO REQUIRED: 15–30s recording or light/dark screenshot pair, realistic data. No sanitized mockups. Suggested: <what to show> */}`
+  4. Show how to use it: a short prose sentence plus, when the feature has one, a
+     copy-pasteable fenced command block (only commands/flags grounded in
+     `MATERIAL_FILE`), and a link to the relevant docs page. If it is a UI feature
+     with no command, describe the click path in one or two sentences instead.
+  5. Optionally close with one plain sentence on what is coming next, ONLY if the
+     material clearly supports it; otherwise stop. Do NOT write the closing CTA /
+     star ask — the workflow appends a fixed footer.
+
+  ## Voice and content rules (IMPORTANT — the last drafts failed these)
+  - **User-facing, not implementation.** Write about what the reader can now DO,
+    never about how it is built or verified. Do NOT list harness ids, internal
+    component names, per-harness verification status, PR numbers, flags, or
+    "verified for X, still being verified for Y" caveats. If a capability works
+    across harnesses, say "works with any agent you run in Omnigent" — not a list
+    of `claude-sdk, codex-sdk, ...`. When the material is full of engineering
+    detail, translate it into the one user outcome that matters and drop the rest.
+  - **Few dashes.** Do NOT use " — " (spaced em/en dashes) as a sentence
+    connector; it reads as AI-generated. Write separate sentences, or use a comma,
+    "and", parentheses, or a colon. At most ONE dash in the whole post, and only
+    if nothing else fits. Do not use "not X but Y" or "It's not just … it's …"
+    constructions.
+  - **Plain and concrete.** Short sentences, active voice, no marketing adjectives
+    ("powerful", "seamless", "effortless", "game-changing"), no hype. Prefer a
+    real example over an abstraction.
+
+  Leave `heroArt: ""` in the frontmatter. The workflow generates the hero image
+  from your `IMAGE_PROMPT` (below) and fills `heroArt` in; do not set it yourself.
+  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.
+  Emit these two single-line fields (each on its own line), then the summary
+  block. Extraction is by prefix, so order between the two does not matter, but
+  `BLOG_PR_TITLE:` MUST be the line immediately before `<!-- BLOG_DRAFT_SUMMARY -->`.
+
+  - `IMAGE_PROMPT:` — one sentence describing a concrete visual SCENE that
+    depicts THIS feature's content, for an illustrated hero image. Describe the
+    subject only (what is happening, the objects/actors and their relationship),
+    grounded in what the feature actually does. Examples: for a queue/steer
+    feature, "a person lining up a stack of chat message cards that feed one at a
+    time into a working AI agent, with a hand redirecting one mid-flight"; for a
+    multi-harness feature, "several distinct robot agents plugging into a single
+    central hub that routes their work". Rules: NO text, words, letters, logos,
+    UI screenshots, charts, or watermarks in the scene; do NOT mention colors,
+    art style, aspect ratio, or "flat vector / navy / starfish" — the workflow
+    appends the fixed brand style. Just the subject.
+  - `BLOG_PR_TITLE:` — 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`.
+  - `## Post drafted` — the path of the single post file you created
+    (`app/blog/<SLUG>/page.mdx`). You should not have edited any other file.
   - `## 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.
+    include the mandatory demo line (the `{/* DEMO REQUIRED */}` marker you left).
+    Note that the hero image is auto-generated from your `IMAGE_PROMPT` and the
+    author byline defaults to `omnigent`; list each as "review / optionally
+    replace" rather than a blocking task. 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.
 

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

@@ -22,7 +22,8 @@ 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,
+  warrant a feature-blog post. Applies a signal-based bar, caps at the requested
+  limit (default top 2–3),
   and emits a ranked BLOG_CANDIDATES JSON block (often empty). No tools, no
   sub-agents — a pure selection turn.
 
@@ -72,8 +73,9 @@ prompt: |
     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.
+  - **Cap: rank strongest-first and return at most the number of features the
+    run asks for** (the run prompt states the limit; default is the top 2–3).
+    Even if more clear the bar, never exceed that limit.
   - **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.)

.github/agents/release-post-formatter/config.yaml

@@ -0,0 +1,150 @@
+# release-post-formatter — a tiny, single-purpose agent used by the
+# publish-changelog.yml workflow at release-PUBLISH time.
+#
+# The GitHub Release notes stay as they are (crisp emoji bullets under
+# "Major new features" / "Bug fixes"). This agent turns that already-published body
+# into the narrative post the WEBSITE wants (mlflow.org/releases/<v>-style): an
+# intro summary plus numbered sections for the OUTSTANDING features only — minor
+# items and bug fixes are dropped — each explaining what the feature is and how to
+# use it, with demo + docs-link placeholders a human fills in before merge. No PR
+# links, no emoji. It invents no new facts, versions, or flag names.
+# It has NO tools and NO sub-agents, so a run is fast, cheap, and can't hang. The
+# workflow drops its output into the site page; on any failure the publish step
+# falls back to the raw release body.
+#
+# Run headlessly:  omnigent run .github/agents/release-post-formatter -p "<release body>" --no-session
+#
+# Security posture (mirrors release-notes-drafter / doc-drafter):
+#   - Runs only on an ALREADY-PUBLISHED, maintainer-curated release body, at
+#     publish time on the trusted default branch.
+#   - The only secret in this process's env is LLM_API_KEY. The omnigent-site
+#     write-token that opens the release-post PR is minted by the workflow AFTER
+#     this agent finishes, so it never coexists with model input.
+#   - Its input is maintainer-written release text — a prose prompt-injection
+#     surface. The workflow secret-scans this agent's stdout for LLM_API_KEY
+#     (abort on hit) and redacts artifacts, and a human reviews the site PR before
+#     merge. Honest residual risk: with network allowed and LLM_API_KEY in env, an
+#     injection could drive an outbound request that exfiltrates the key; a
+#     network-denying sandbox is the real mitigation but is not used here for the
+#     same CI-fragility reason documented in release-notes-drafter/config.yaml.
+#     We accept the same residual risk already accepted for release-notes-drafter.
+
+spec_version: 1
+name: release-post-formatter
+description: >-
+  Turns an already-curated GitHub Release body into the narrative website post: a
+  short intro summary plus a handful of numbered sections for the OUTSTANDING
+  features only (minor items and bug fixes are dropped), each explaining what the
+  feature is and how to use it. Links features to a real site docs page when one
+  matches (from a provided list), else omits the link; leaves a demo placeholder
+  for a human. No PR links, no emoji. Emits the post between RELEASE_POST markers.
+  No tools, no sub-agents.
+
+executor:
+  type: omnigent
+  config:
+    harness: claude-sdk
+
+prompt: |
+  You are the Omnigent release-POST formatter. A version has just been published.
+  You are given two inputs: the curated GitHub Release body — crisp, emoji-prefixed
+  bullets under headings like "Major new features" and "Bug fixes", each bullet
+  ending with the contributing PR references, e.g. `(#123, #456)` — and a list of
+  the site's available docs pages (URL and title, one per line) to link features to.
+
+  Your job: turn that content into the narrative website post, matching the style
+  of the MLflow 3.14.0 release post (https://mlflow.org/releases/3.14.0/) — see
+  "The MLflow 3.14.0 style" below for exactly what that means. You do NOT mirror
+  the whole release body: you CURATE it down to the outstanding features and write
+  each one up. You must not invent features, versions, or flag names.
+
+  ## Output shape (STRICT)
+  Emit ONLY the following, between the markers, and nothing else — no preamble, no
+  top-level `# vX.Y.Z` heading (the site adds the title, date, and byline):
+
+  <!-- RELEASE_POST -->
+  <one-paragraph intro summary — see the intro pattern below; flowing prose, no
+  bullet list>
+
+  ## 1. <Feature title — a noun phrase naming the feature/command>
+
+  ![TODO: add a demo screenshot or GIF for "<feature title>"](TODO)
+
+  <1-3 short paragraphs of prose, present tense, addressing the reader as "you":
+  first what the feature IS and the problem it solves, then HOW to use it — the
+  command, menu, or workflow. No PR references anywhere.>
+
+  _Learn more in the [<matching docs page title>](<its URL from the docs list>)._
+
+  ## 2. <Next outstanding feature>
+
+  ...
+
+  Full Changelog: <copy the exact `Full Changelog:` line from the input, verbatim>
+  <!-- /RELEASE_POST -->
+
+  ## The MLflow 3.14.0 style (match this)
+  - CURATE, don't mirror. Pick only the ~4-6 OUTSTANDING, headline features and
+    give each its own numbered section. DROP minor features, small tweaks, and
+    everything under "Bug fixes". There is NO "Bug fixes" / "Fixes & improvements"
+    section — omit it entirely. (MLflow 3.14.0 has 6 feature sections and no fixes
+    section; comprehensive changes live behind the Full Changelog link only.)
+  - Intro: ONE flowing paragraph. First sentence follows the shape
+    "Omnigent <version> is a major release focused on <core theme>, from <X> to
+    <Y>." — theme and X→Y span drawn from the outstanding features. Then a sentence
+    or two naming the biggest ones as prose. No bullets.
+    (MLflow's reads: "MLflow 3.14.0 is a major release focused on closing the GenAI
+    development loop, from getting an app instrumented in the first place to
+    reviewing, testing, and iterating on it.")
+  - Headings: `## N. <Title>` — a NOUN PHRASE naming the feature, including the
+    concrete command/flag/UI name when the input gives one (e.g.
+    "## 1. Omnigent for iOS"). Never a verb phrase.
+  - Each feature section, in order: a demo placeholder line, then the prose, then —
+    only when a docs page genuinely matches — a "Learn more" link (see "Demo
+    placeholder" and "Docs links" below). The prose is 1-3 short paragraphs,
+    present tense, "you"/"your", explaining what it is AND how to use it — MLflow
+    opens a section with "Getting an app onto MLflow observability should not mean
+    reading setup guides", then shows the command.
+  - Tone: hybrid marketing-technical — name the developer friction and the
+    practical workflow, in approachable language. Conversational, not cutesy.
+
+  ## Demo placeholder (a human fills this before merge)
+  The release body carries no demo media, so you cannot produce it — emit a clear
+  placeholder immediately under EACH feature heading:
+    `![TODO: add a demo screenshot or GIF for "<feature title>"](TODO)`
+  Use the literal token `TODO` so a reviewer can grep for it. Never fabricate a
+  real-looking image path.
+
+  ## Docs links (link to the most specific real page/section, or omit the line)
+  The "## Available docs pages and sections" input lists every real docs URL and
+  its title; INDENTED lines below a page are `#section` anchors within that page
+  (URL already includes the `#slug`). For each feature, add the "Learn more" line
+  ONLY when a listed entry is clearly about that feature:
+    `_Learn more in the [<that entry's title>](<that entry's URL>)._`
+  Prefer the MOST SPECIFIC match: if an indented `#section` anchor is about the
+  feature, link that anchor rather than the whole page (e.g. link
+  `/docs/build/harnesses#custom-acp-agents` for an ACP-harness feature, not the
+  bare `/docs/build/harnesses`). Fall back to the page URL only when no section
+  fits better.
+  If nothing clearly matches — or the list is empty / says none available — OMIT
+  the "Learn more" line for that feature entirely. Do NOT emit a `TODO` link, do
+  NOT guess a URL, and do NOT link a loosely-related page just to have a link.
+
+  ## Fidelity rules
+  - NO PR references. Drop every `(#123)` / `#123` — do not carry them into the
+    post (they belong in the GitHub Release and CHANGELOG, not here).
+  - Prose, not bullets: turn "- 📱 X — Y" into sentences. Drop ALL emoji.
+  - Never invent facts, versions, flag names, or docs URLs — a docs link must be a
+    verbatim URL from the provided list, or the line is omitted.
+  - If the input has a "Full Changelog:" line, copy it verbatim as the last line
+    before the closing marker; if not, omit it.
+  - Do NOT reproduce the "Thanks to our community" note — the site page omits it
+    (the GitHub Release keeps it).
+
+  ## Security
+  You are running in CI with access to secrets. Never echo secrets, tokens, or
+  credentials, and never make outbound network calls.
+
+  ## Act in the same turn you announce
+  Never end a turn after only saying what you will do — produce the RELEASE_POST
+  block in the same turn.

.github/areas.json

@@ -58,8 +58,7 @@
       ],
       "owners": [
         "serena-ruan",
-        "daniellok-db",
-        "hzub"
+        "daniellok-db"
       ]
     },
     {

.github/ci-deps/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "description": "Pinned npm CLIs the e2e workflow installs (claude-code, codex, pi).",
   "dependencies": {
-    "@anthropic-ai/claude-code": "2.1.163",
+    "@anthropic-ai/claude-code": "2.1.212",
     "@earendil-works/pi-coding-agent": "0.79.0",
     "@openai/codex": "0.139.0"
   }

.github/scripts/changelog/release_to_mdx.py

@@ -3,14 +3,18 @@
 
 The website's `/releases/<version>` post is the *concise, curated highlights* —
 it mirrors the GitHub Release notes a maintainer already hand-edits in the
-draft→edit→publish flow. This module does a small mechanical transform so that
-GitHub-flavoured Markdown renders cleanly through the site's MDX pipeline
-(`@next/mdx`):
+draft→edit→publish flow. The narrative body (intro summary + numbered feature
+sections) is written by the release-notes-drafter agent; this module does a small
+mechanical transform so that GitHub-flavoured Markdown renders cleanly through the
+site's MDX pipeline (`@next/mdx`), and wraps it in the site-only chrome the
+release body can't carry (a byline and a "What's Next" footer):
 
   * unwrap `<https://…>` autolinks (angle brackets are JSX in MDX),
   * escape `{`, `}`, and any remaining `<` so MDX never tries to evaluate them,
   * linkify bare `#1234` references to the PR,
-  * prepend a `# vX.Y.Z` heading + a `_Released <date>_` line the index reads.
+  * prepend a `# vX.Y.Z` heading + a byline (`_Released <date>_` — the exact token
+    the site index reads — plus estimated read time and author),
+  * append a static "What's Next" footer (install command + community links).
 
 No LLM, no reflow — the curation is the human's; we only make it MDX-safe.
 """
@@ -28,6 +32,22 @@ _AUTOLINK_RE = re.compile(r"<((?:https?://)[^>\s]+)>")
 # "# Title" (space after #), so they never match.
 _PR_REF_RE = re.compile(r"(?<![\w/#])#(\d+)\b")
 
+AUTHOR = "Omnigent maintainers"
+# Average adult reading speed; used only for the "N min read" byline estimate.
+_WORDS_PER_MINUTE = 200
+
+WHATS_NEXT = """## What's Next
+
+Install or upgrade Omnigent:
+
+```bash
+uv tool install --python 3.12 omnigent   # or: pip install "omnigent"
+```
+
+- Star the project and file issues on [GitHub](https://github.com/omnigent-ai/omnigent).
+- Join the conversation on our [Discord](https://discord.gg/omnigent).
+- Browse the [docs](https://omnigent.ai/docs) to go deeper."""
+
 
 def mdx_escape(text: str) -> str:
     """Make GitHub-flavoured Markdown safe to parse as MDX."""
@@ -44,6 +64,12 @@ def linkify_pr_refs(text: str, repo: str) -> str:
     )
 
 
+def _read_time_minutes(text: str) -> int:
+    """Estimate reading time in whole minutes (>=1) from a word count."""
+    words = len(text.split())
+    return max(1, round(words / _WORDS_PER_MINUTE))
+
+
 def release_body_to_mdx(tag: str, date: str, body: str, repo: str) -> str:
     """Render the MDX page for one release."""
     transformed = linkify_pr_refs(mdx_escape(body or ""), repo)
@@ -52,8 +78,13 @@ def release_body_to_mdx(tag: str, date: str, body: str, repo: str) -> str:
         + tag
         + ". Edit the GitHub Release, not this file. */}"
     )
-    header = f"{comment}\n\n# {tag}\n\n_Released {date}_\n\n"
-    return header + transformed.strip() + "\n"
+    # Byline mirrors the MLflow release-post layout: keep the exact
+    # `_Released <date>_` token the site index regex reads, then append the
+    # read-time estimate and author on the same line.
+    minutes = _read_time_minutes(transformed)
+    byline = f"_Released {date}_ · {minutes} min read · {AUTHOR}"
+    header = f"{comment}\n\n# {tag}\n\n{byline}\n\n"
+    return header + transformed.strip() + "\n\n" + WHATS_NEXT + "\n"
 
 
 def _tag_date(tag: str) -> str:

.github/scripts/ci/backcompat-pairwise-matrix.sh

@@ -3,7 +3,7 @@
 # `e2e_matrix` and `integration_matrix`.
 #
 # We test `main` (the checked-out code = client + tests, always) against each
-# non-rc release tag AT OR ABOVE the backcompat floor (MIN_VERSION, default
+# final (non-prerelease) release tag AT OR ABOVE the backcompat floor (MIN_VERSION, default
 # 0.2.0 — the first release with the mock-LLM e2e infra; see below), on BOTH
 # axes — and ONLY those cells:
 #   (server=main,      runner=<release>)  — new server vs a previously-shipped runner
@@ -17,8 +17,9 @@
 #
 # Env in:
 #   VERSIONS    optional comma-separated override of the version set used for
-#               BOTH axes (e.g. "main,v0.2.0"). Empty = main + all non-rc tags.
-#               Blank entries are dropped and surrounding whitespace trimmed.
+#               BOTH axes (e.g. "main,v0.2.0"). Empty = main + all final
+#               (non-prerelease) tags. Blank entries are dropped and
+#               surrounding whitespace trimmed.
 #   NUM_SHARDS  e2e shard count per cell (default 4).
 # Out (GITHUB_OUTPUT):
 #   e2e_matrix={"include":[{"server":..,"runner":..,"shard_id":..,"num_shards":..}, ...]}
@@ -61,9 +62,12 @@ if [ -n "${VERSIONS:-}" ]; then
   IFS=',' read -ra raw <<<"$VERSIONS"
 else
   raw=("main")
-  # `[^a-z]rc[0-9]` so we drop vX.Y.ZrcN without over-excluding tags that merely
-  # contain the substring "rc" (e.g. a hypothetical "...march").
-  while IFS= read -r tag; do raw+=("$tag"); done < <(git tag --sort=-v:refname | grep -viE '(^|[^a-z])rc[0-9]')
+  # Drop pre-release tags (vX.Y.ZrcN / .devN / preN — same trio github-release.yml
+  # skips): they are snapshots of main, so main-vs-them is not a compat signal, and
+  # under the 256-job cap they would evict the oldest FINAL releases from coverage.
+  # `[^a-z]` guards against over-excluding tags that merely contain the substring
+  # (e.g. a hypothetical "...march"). An explicit VERSIONS override still accepts them.
+  while IFS= read -r tag; do raw+=("$tag"); done < <(git tag --sort=-v:refname | grep -viE '(^|[^a-z])(rc|dev|pre)[0-9]')
 fi
 
 # Trim whitespace, drop blanks, reject invalid tokens, drop below-floor releases.

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

@@ -7,6 +7,7 @@
 # Generated file -- do not hand-edit; it is replaced wholesale on every sync.
 
 REQUIRED=(
+  "DCO"
   "Pre-commit checks"
   "Docker build"
   "Pytest (runtime-harnesses)"
@@ -32,6 +33,7 @@ REQUIRED=(
   "E2E UI Tests (shard 0/3)"
   "E2E UI Tests (shard 1/3)"
   "E2E UI Tests (shard 2/3)"
+  "UI Snapshot (visual baselines)"
   "Integration (claude-sdk)"
   "Integration (openai-agents)"
   "Integration (codex)"
@@ -62,6 +64,7 @@ ALLOW_SKIP=(
   "E2E UI Tests (shard 0/3)"
   "E2E UI Tests (shard 1/3)"
   "E2E UI Tests (shard 2/3)"
+  "UI Snapshot (visual baselines)"
   "Integration (claude-sdk)"
   "Integration (openai-agents)"
   "Integration (codex)"
@@ -79,6 +82,7 @@ workflow_for() {
     "Pytest ("*)             echo "CI" ;;
     "E2E Tests (shard "*)    echo "E2E Tests" ;;
     "E2E UI Tests (shard "*) echo "E2E UI Tests" ;;
+    "UI Snapshot (visual baselines)") echo "UI Snapshot" ;;
     "Integration ("*)        echo "Integration Tests" ;;
     *)                       echo "" ;;
   esac

.github/scripts/waiting_on_author.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+"""Keep the waiting-on-author pull request label actionable."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import UTC, datetime
+from email.message import Message
+from typing import Any
+
+LABEL = "waiting-on-author"
+WAITING_DAYS = 7
+CANONICAL_REPO = "omnigent-ai/omnigent"
+MAX_CLOSURES_PER_RUN = 30
+
+
+def label_names(item: dict[str, Any]) -> list[str]:
+    return [
+        label.get("name", label) if isinstance(label, dict) else label
+        for label in item.get("labels", [])
+    ]
+
+
+def has_waiting_label(item: dict[str, Any]) -> bool:
+    return LABEL in label_names(item)
+
+
+def parse_time(value: str) -> datetime:
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def days_between(start: str, end: datetime) -> int:
+    return int((end - parse_time(start)).total_seconds() // 86400)
+
+
+def latest_waiting_label_at(timeline: list[dict[str, Any]]) -> str | None:
+    latest: str | None = None
+    for event in timeline:
+        if event.get("event") != "labeled" or not event.get("created_at"):
+            continue
+        label = event.get("label") or {}
+        name = label.get("name") if isinstance(label, dict) else label
+        if name != LABEL:
+            continue
+        if latest is None or parse_time(event["created_at"]) > parse_time(latest):
+            latest = event["created_at"]
+    return latest
+
+
+def close_message(label_applied_at: str) -> str:
+    return "\n".join(
+        [
+            f"Closing this PR because it has been labeled `{LABEL}` for "
+            f"{WAITING_DAYS} days without an author reply or new commit.",
+            "",
+            f"The label was last applied on {label_applied_at}. If you are "
+            "ready to continue, please reopen this PR or open a new one.",
+        ]
+    )
+
+
+class GitHubAPI:
+    def __init__(self, token: str, repo: str):
+        self.token = token
+        self.repo = repo
+
+    def request(
+        self, method: str, path: str, body: dict[str, Any] | None = None
+    ) -> tuple[Any, Message]:
+        data = None if body is None else json.dumps(body).encode()
+        request = urllib.request.Request(
+            f"https://api.github.com{path}",
+            data=data,
+            method=method,
+            headers={
+                "Accept": "application/vnd.github+json",
+                "Authorization": f"Bearer {self.token}",
+                "Content-Type": "application/json",
+                "X-GitHub-Api-Version": "2022-11-28",
+            },
+        )
+        with urllib.request.urlopen(request) as response:
+            raw = response.read()
+            parsed = json.loads(raw.decode()) if raw else None
+            return parsed, response.headers
+
+    def paginated(self, path: str) -> list[dict[str, Any]]:
+        items: list[dict[str, Any]] = []
+        next_path: str | None = path
+        while next_path:
+            page, headers = self.request("GET", next_path)
+            items.extend(page or [])
+            next_path = next_link(headers.get("Link", ""))
+        return items
+
+    def get_pull(self, pull_number: int) -> dict[str, Any]:
+        pull, _ = self.request("GET", f"/repos/{self.repo}/pulls/{pull_number}")
+        return pull
+
+    def remove_label(self, issue_number: int, label: str) -> bool:
+        quoted = urllib.parse.quote(label, safe="")
+        try:
+            self.request("DELETE", f"/repos/{self.repo}/issues/{issue_number}/labels/{quoted}")
+        except urllib.error.HTTPError as error:
+            if error.code == 404:
+                return False
+            raise
+        return True
+
+    def list_waiting_issues(self) -> list[dict[str, Any]]:
+        query = urllib.parse.urlencode({"state": "open", "labels": LABEL, "per_page": 100})
+        return self.paginated(f"/repos/{self.repo}/issues?{query}")
+
+    def list_timeline(self, issue_number: int) -> list[dict[str, Any]]:
+        return self.paginated(f"/repos/{self.repo}/issues/{issue_number}/timeline?per_page=100")
+
+    def list_issue_comments(self, issue_number: int) -> list[dict[str, Any]]:
+        return self.paginated(f"/repos/{self.repo}/issues/{issue_number}/comments?per_page=100")
+
+    def list_review_comments(self, pull_number: int) -> list[dict[str, Any]]:
+        return self.paginated(f"/repos/{self.repo}/pulls/{pull_number}/comments?per_page=100")
+
+    def list_reviews(self, pull_number: int) -> list[dict[str, Any]]:
+        return self.paginated(f"/repos/{self.repo}/pulls/{pull_number}/reviews?per_page=100")
+
+    def list_commits(self, pull_number: int) -> list[dict[str, Any]]:
+        return self.paginated(f"/repos/{self.repo}/pulls/{pull_number}/commits?per_page=100")
+
+    def close_pull(self, pull_number: int) -> None:
+        self.request("PATCH", f"/repos/{self.repo}/pulls/{pull_number}", {"state": "closed"})
+
+    def create_comment(self, issue_number: int, body: str) -> None:
+        self.request("POST", f"/repos/{self.repo}/issues/{issue_number}/comments", {"body": body})
+
+
+def next_link(link_header: str) -> str | None:
+    for part in link_header.split(","):
+        url_part, _, rel_part = part.partition(";")
+        if 'rel="next"' not in rel_part:
+            continue
+        url = url_part.strip()[1:-1]
+        parsed = urllib.parse.urlparse(url)
+        return f"{parsed.path}?{parsed.query}"
+    return None
+
+
+def remove_waiting_label(api: GitHubAPI, issue_number: int, reason: str) -> bool:
+    removed = api.remove_label(issue_number, LABEL)
+    if removed:
+        print(f"Removed {LABEL} from #{issue_number}: {reason}")
+    else:
+        print(f"#{issue_number} no longer has {LABEL}; nothing to remove.")
+    return removed
+
+
+def user_login(item: dict[str, Any]) -> str | None:
+    login = item.get("user", {}).get("login")
+    return login.lower() if login else None
+
+
+def is_after(timestamp: str | None, since: str) -> bool:
+    return bool(timestamp and parse_time(timestamp) > parse_time(since))
+
+
+def authored_after(items: list[dict[str, Any]], author: str, since: str, key: str) -> bool:
+    return any(user_login(item) == author and is_after(item.get(key), since) for item in items)
+
+
+def commit_after(commits: list[dict[str, Any]], since: str) -> bool:
+    for commit in commits:
+        authored_at = commit.get("commit", {}).get("author", {}).get("date")
+        committed_at = commit.get("commit", {}).get("committer", {}).get("date")
+        if is_after(authored_at, since) or is_after(committed_at, since):
+            return True
+    return False
+
+
+def author_activity_since_label(api: GitHubAPI, pull: dict[str, Any], since: str) -> str | None:
+    author = pull.get("user", {}).get("login")
+    if not author:
+        return None
+    author = author.lower()
+    pull_number = pull["number"]
+
+    if authored_after(api.list_issue_comments(pull_number), author, since, "created_at"):
+        return "the author commented"
+    if authored_after(api.list_review_comments(pull_number), author, since, "created_at"):
+        return "the author replied to a review comment"
+    if authored_after(api.list_reviews(pull_number), author, since, "submitted_at"):
+        return "the author submitted a review response"
+    if commit_after(api.list_commits(pull_number), since):
+        return "new commits were pushed"
+    return None
+
+
+def clear_on_author_activity(event_name: str, payload: dict[str, Any], api: GitHubAPI) -> bool:
+    pull_number: int | None = None
+    actor: str | None = None
+    reason: str | None = None
+    author_activity = False
+
+    if event_name in {"pull_request", "pull_request_target"} and payload.get("pull_request"):
+        if payload.get("action") != "synchronize":
+            return False
+        pull_number = payload["pull_request"]["number"]
+        reason = "new commits were pushed"
+        author_activity = True
+    elif event_name == "issue_comment" and "pull_request" in payload.get("issue", {}):
+        pull_number = payload["issue"]["number"]
+        actor = payload.get("comment", {}).get("user", {}).get("login")
+        reason = "the author commented"
+    elif event_name == "pull_request_review_comment" and payload.get("pull_request"):
+        pull_number = payload["pull_request"]["number"]
+        actor = payload.get("comment", {}).get("user", {}).get("login")
+        reason = "the author replied to a review comment"
+    elif event_name == "pull_request_review" and payload.get("pull_request"):
+        pull_number = payload["pull_request"]["number"]
+        actor = payload.get("review", {}).get("user", {}).get("login")
+        reason = "the author submitted a review response"
+    else:
+        return False
+
+    if pull_number is None or reason is None:
+        return False
+    pull = api.get_pull(pull_number)
+    if pull.get("state") != "open" or not has_waiting_label(pull):
+        return False
+
+    if not author_activity:
+        author = pull.get("user", {}).get("login")
+        author_activity = bool(actor and author and actor.lower() == author.lower())
+
+    if not author_activity:
+        return False
+    return remove_waiting_label(api, pull_number, reason)
+
+
+def close_stale_waiting_prs(api: GitHubAPI, now: datetime | None = None) -> int:
+    now = now or datetime.now(UTC)
+    closed = 0
+    for issue in api.list_waiting_issues():
+        if closed >= MAX_CLOSURES_PER_RUN:
+            break
+        if "pull_request" not in issue or not has_waiting_label(issue):
+            continue
+
+        try:
+            label_applied_at = latest_waiting_label_at(api.list_timeline(issue["number"]))
+            if label_applied_at is None:
+                print(
+                    f"::warning::#{issue['number']} has {LABEL} but no label timestamp "
+                    "in the timeline; skipping."
+                )
+                continue
+
+            pull = api.get_pull(issue["number"])
+            reason = author_activity_since_label(api, pull, label_applied_at)
+            if reason:
+                remove_waiting_label(api, issue["number"], reason)
+                continue
+
+            if days_between(label_applied_at, now) < WAITING_DAYS:
+                continue
+
+            api.close_pull(issue["number"])
+            api.create_comment(issue["number"], close_message(label_applied_at))
+            closed += 1
+            print(f"Closed #{issue['number']}; {LABEL} was applied at {label_applied_at}.")
+        except Exception as error:  # noqa: BLE001 - keep the sweep moving across PRs.
+            print(f"::warning::Could not close #{issue['number']}: {error}")
+    print(f"Closed {closed} PR(s) labeled {LABEL}.")
+    return closed
+
+
+def run(
+    event_name: str,
+    payload: dict[str, Any],
+    api: GitHubAPI,
+    repo: str,
+    now: datetime | None = None,
+) -> None:
+    if repo != CANONICAL_REPO:
+        print(f"Skipping {repo}; waiting-on-author hygiene only runs for {CANONICAL_REPO}.")
+        return
+
+    if event_name in {"schedule", "workflow_dispatch"}:
+        close_stale_waiting_prs(api, now=now)
+        return
+
+    clear_on_author_activity(event_name, payload, api)
+
+
+def load_event_payload() -> dict[str, Any]:
+    path = os.environ.get("GITHUB_EVENT_PATH")
+    if not path:
+        return {}
+    with open(path, encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def main() -> int:
+    repo = os.environ.get("GITHUB_REPOSITORY", "")
+    token = os.environ.get("GITHUB_TOKEN")
+    if not token:
+        print("GITHUB_TOKEN is required", file=sys.stderr)
+        return 1
+    event_name = os.environ.get("GITHUB_EVENT_NAME", "")
+    run(event_name, load_event_payload(), GitHubAPI(token, repo), repo)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.github/scripts/waiting_on_author_test.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""Offline tests for waiting_on_author.py."""
+
+from __future__ import annotations
+
+import importlib.util
+import pathlib
+import unittest
+from datetime import UTC, datetime
+from typing import Any
+
+SCRIPT_PATH = pathlib.Path(__file__).with_name("waiting_on_author.py")
+SPEC = importlib.util.spec_from_file_location("waiting_on_author", SCRIPT_PATH)
+waiting_on_author = importlib.util.module_from_spec(SPEC)
+assert SPEC and SPEC.loader
+SPEC.loader.exec_module(waiting_on_author)
+
+
+def pr(
+    number: int = 12, author: str = "alice", labels: list[str] | None = None, state: str = "open"
+) -> dict[str, Any]:
+    labels = [waiting_on_author.LABEL] if labels is None else labels
+    return {
+        "number": number,
+        "state": state,
+        "user": {"login": author},
+        "labels": [{"name": label} for label in labels],
+    }
+
+
+def issue(number: int, labels: list[str] | None = None, is_pr: bool = True) -> dict[str, Any]:
+    labels = [waiting_on_author.LABEL] if labels is None else labels
+    item: dict[str, Any] = {"number": number, "labels": [{"name": label} for label in labels]}
+    if is_pr:
+        item["pull_request"] = {}
+    return item
+
+
+def labeled_at(iso: str, label: str | None = None) -> dict[str, Any]:
+    return {
+        "event": "labeled",
+        "label": {"name": label or waiting_on_author.LABEL},
+        "created_at": iso,
+    }
+
+
+class FakeAPI:
+    def __init__(
+        self,
+        *,
+        pull: dict[str, Any] | None = None,
+        issues: list[dict[str, Any]] | None = None,
+        timeline_by_issue: dict[int, list[dict[str, Any]]] | None = None,
+        issue_comments: dict[int, list[dict[str, Any]]] | None = None,
+        review_comments: dict[int, list[dict[str, Any]]] | None = None,
+        reviews: dict[int, list[dict[str, Any]]] | None = None,
+        commits: dict[int, list[dict[str, Any]]] | None = None,
+    ):
+        self.pull = pull or pr()
+        self.issues = issues or []
+        self.timeline_by_issue = timeline_by_issue or {}
+        self.issue_comments = issue_comments or {}
+        self.review_comments = review_comments or {}
+        self.reviews = reviews or {}
+        self.commits = commits or {}
+        self.removed: list[tuple[int, str]] = []
+        self.closed: list[int] = []
+        self.comments: list[tuple[int, str]] = []
+
+    def get_pull(self, pull_number: int) -> dict[str, Any]:
+        return self.pull | {"number": pull_number}
+
+    def remove_label(self, issue_number: int, label: str) -> bool:
+        self.removed.append((issue_number, label))
+        return True
+
+    def list_waiting_issues(self) -> list[dict[str, Any]]:
+        return self.issues
+
+    def list_timeline(self, issue_number: int) -> list[dict[str, Any]]:
+        return self.timeline_by_issue.get(issue_number, [])
+
+    def list_issue_comments(self, issue_number: int) -> list[dict[str, Any]]:
+        return self.issue_comments.get(issue_number, [])
+
+    def list_review_comments(self, pull_number: int) -> list[dict[str, Any]]:
+        return self.review_comments.get(pull_number, [])
+
+    def list_reviews(self, pull_number: int) -> list[dict[str, Any]]:
+        return self.reviews.get(pull_number, [])
+
+    def list_commits(self, pull_number: int) -> list[dict[str, Any]]:
+        return self.commits.get(pull_number, [])
+
+    def close_pull(self, pull_number: int) -> None:
+        self.closed.append(pull_number)
+
+    def create_comment(self, issue_number: int, body: str) -> None:
+        self.comments.append((issue_number, body))
+
+
+class WaitingOnAuthorTest(unittest.TestCase):
+    def test_latest_waiting_label_at_uses_latest_matching_label(self) -> None:
+        self.assertEqual(
+            waiting_on_author.latest_waiting_label_at(
+                [
+                    labeled_at("2026-07-01T00:00:00Z"),
+                    labeled_at("2026-07-10T00:00:00Z", "other"),
+                    labeled_at("2026-07-12T00:00:00Z"),
+                ]
+            ),
+            "2026-07-12T00:00:00Z",
+        )
+
+    def test_author_issue_comment_removes_waiting_label(self) -> None:
+        api = FakeAPI(pull=pr(author="Alice"))
+        waiting_on_author.clear_on_author_activity(
+            "issue_comment",
+            {"issue": {"number": 12, "pull_request": {}}, "comment": {"user": {"login": "alice"}}},
+            api,
+        )
+        self.assertEqual(api.removed, [(12, waiting_on_author.LABEL)])
+
+    def test_author_review_thread_reply_removes_waiting_label(self) -> None:
+        api = FakeAPI(pull=pr(author="alice"))
+        waiting_on_author.clear_on_author_activity(
+            "pull_request_review_comment",
+            {"pull_request": {"number": 12}, "comment": {"user": {"login": "alice"}}},
+            api,
+        )
+        self.assertEqual(api.removed, [(12, waiting_on_author.LABEL)])
+
+    def test_maintainer_comment_keeps_waiting_label(self) -> None:
+        api = FakeAPI(pull=pr(author="alice"))
+        waiting_on_author.clear_on_author_activity(
+            "issue_comment",
+            {
+                "issue": {"number": 12, "pull_request": {}},
+                "comment": {"user": {"login": "maintainer"}},
+            },
+            api,
+        )
+        self.assertEqual(api.removed, [])
+
+    def test_new_commits_remove_waiting_label(self) -> None:
+        api = FakeAPI(pull=pr(author="alice"))
+        waiting_on_author.clear_on_author_activity(
+            "pull_request_target",
+            {"action": "synchronize", "pull_request": {"number": 12}},
+            api,
+        )
+        self.assertEqual(api.removed, [(12, waiting_on_author.LABEL)])
+
+    def test_scheduled_sweep_closes_pr_after_7_days(self) -> None:
+        api = FakeAPI(
+            issues=[issue(20)], timeline_by_issue={20: [labeled_at("2026-07-17T00:00:00Z")]}
+        )
+        waiting_on_author.close_stale_waiting_prs(api, now=datetime(2026, 7, 24, tzinfo=UTC))
+        self.assertEqual(api.closed, [20])
+        self.assertEqual(len(api.comments), 1)
+        self.assertIn(waiting_on_author.LABEL, api.comments[0][1])
+
+    def test_scheduled_sweep_removes_label_after_author_comment(self) -> None:
+        api = FakeAPI(
+            pull=pr(number=23, author="alice"),
+            issues=[issue(23)],
+            timeline_by_issue={23: [labeled_at("2026-07-01T00:00:00Z")]},
+            issue_comments={
+                23: [{"user": {"login": "alice"}, "created_at": "2026-07-20T00:00:00Z"}]
+            },
+        )
+        waiting_on_author.close_stale_waiting_prs(api, now=datetime(2026, 7, 24, tzinfo=UTC))
+        self.assertEqual(api.removed, [(23, waiting_on_author.LABEL)])
+        self.assertEqual(api.closed, [])
+
+    def test_scheduled_sweep_keeps_label_after_maintainer_comment(self) -> None:
+        api = FakeAPI(
+            pull=pr(number=24, author="alice"),
+            issues=[issue(24)],
+            timeline_by_issue={24: [labeled_at("2026-07-18T00:00:00Z")]},
+            issue_comments={
+                24: [{"user": {"login": "maintainer"}, "created_at": "2026-07-20T00:00:00Z"}]
+            },
+        )
+        waiting_on_author.close_stale_waiting_prs(api, now=datetime(2026, 7, 24, tzinfo=UTC))
+        self.assertEqual(api.removed, [])
+        self.assertEqual(api.closed, [])
+
+    def test_scheduled_sweep_removes_label_after_new_commit(self) -> None:
+        api = FakeAPI(
+            pull=pr(number=25, author="alice"),
+            issues=[issue(25)],
+            timeline_by_issue={25: [labeled_at("2026-07-01T00:00:00Z")]},
+            commits={25: [{"commit": {"author": {"date": "2026-07-20T00:00:00Z"}}}]},
+        )
+        waiting_on_author.close_stale_waiting_prs(api, now=datetime(2026, 7, 24, tzinfo=UTC))
+        self.assertEqual(api.removed, [(25, waiting_on_author.LABEL)])
+        self.assertEqual(api.closed, [])
+
+    def test_scheduled_sweep_ignores_author_comment_before_label(self) -> None:
+        api = FakeAPI(
+            pull=pr(number=26, author="alice"),
+            issues=[issue(26)],
+            timeline_by_issue={26: [labeled_at("2026-07-17T00:00:00Z")]},
+            issue_comments={
+                26: [{"user": {"login": "alice"}, "created_at": "2026-07-10T00:00:00Z"}]
+            },
+        )
+        waiting_on_author.close_stale_waiting_prs(api, now=datetime(2026, 7, 24, tzinfo=UTC))
+        self.assertEqual(api.removed, [])
+        self.assertEqual(api.closed, [26])
+
+    def test_scheduled_sweep_leaves_6_day_pr_open(self) -> None:
+        api = FakeAPI(
+            issues=[issue(21)], timeline_by_issue={21: [labeled_at("2026-07-18T00:00:00Z")]}
+        )
+        waiting_on_author.close_stale_waiting_prs(api, now=datetime(2026, 7, 24, tzinfo=UTC))
+        self.assertEqual(api.closed, [])
+        self.assertEqual(api.comments, [])
+
+    def test_scheduled_sweep_skips_missing_label_timestamp(self) -> None:
+        api = FakeAPI(issues=[issue(22)], timeline_by_issue={22: []})
+        waiting_on_author.close_stale_waiting_prs(api, now=datetime(2026, 7, 24, tzinfo=UTC))
+        self.assertEqual(api.closed, [])
+
+    def test_scheduled_sweep_caps_closures_per_run(self) -> None:
+        issues = [issue(100 + idx) for idx in range(waiting_on_author.MAX_CLOSURES_PER_RUN + 3)]
+        timeline = {item["number"]: [labeled_at("2026-07-01T00:00:00Z")] for item in issues}
+        api = FakeAPI(issues=issues, timeline_by_issue=timeline)
+        waiting_on_author.close_stale_waiting_prs(api, now=datetime(2026, 7, 24, tzinfo=UTC))
+        self.assertEqual(len(api.closed), waiting_on_author.MAX_CLOSURES_PER_RUN)
+
+
+if __name__ == "__main__":
+    unittest.main()

.github/workflows/android-bundle.yml

@@ -0,0 +1,64 @@
+name: Android Bundle
+
+# Builds an unsigned release AAB in CI and uploads it as a workflow artifact.
+# Download the artifact and sign it locally with your upload keystore — no
+# secrets on GitHub, no signing key in CI.
+
+on:
+  workflow_dispatch:
+    inputs:
+      version-code:
+        description: "versionCode (must be higher than the last uploaded to Play; starts at 3)"
+        required: true
+        type: string
+      version-note:
+        description: "Optional note appended to the artifact filename (e.g. rc1)"
+        required: false
+        default: ""
+  pull_request:
+    paths:
+      - ".github/workflows/android-bundle.yml"
+      - "web/android/**"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build unsigned AAB
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web/android
+
+    steps:
+      - name: Check out
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9  # v4
+        with:
+          distribution: temurin
+          java-version: 17
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@48b5f213c81028ace310571dc5ec0fbbca0b2947  # v4
+        with:
+          cache-read-only: false
+
+      - name: Build release AAB
+        run: ./gradlew bundleRelease --no-daemon --console=plain -PversionCode=${{ github.event.inputs.version-code }}
+
+      - name: Verify artifact
+        run: |
+          AAB=app/build/outputs/bundle/release/app-release.aab
+          test -f "$AAB" || { echo "::error::AAB not found at $AAB"; exit 1; }
+          echo "AAB size: $(du -h "$AAB" | cut -f1)"
+
+      - name: Upload artifact
+        if: github.event_name == 'workflow_dispatch'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: omnigent-android-aab${{ inputs.version-note && format('-{0}', inputs.version-note) || '' }}
+          path: web/android/app/build/outputs/bundle/release/app-release.aab
+          retention-days: 30

.github/workflows/benchmark-pr.yml

@@ -15,6 +15,7 @@ on:
     paths:
       - "omnigent/db/migrations/**"
       - "omnigent/stores/**"
+      - "dev/benchmarks/**"
       - ".github/workflows/benchmark-pr.yml"
 
 permissions:
@@ -152,14 +153,25 @@ jobs:
           } > comment_body.md
 
       - name: Post PR comment
+        # Fork PRs have a read-only GITHUB_TOKEN so the comment may fail —
+        # that's acceptable; results are still available in the artifact.
+        continue-on-error: true
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
         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
+          COMMENT_MARKER="<!-- benchmark-pr-comment -->"
+          COMMENT_ID=$(gh api --paginate \
+            "repos/${REPO}/issues/${PR_NUMBER}/comments" \
+            --jq ".[] | select(.body | startswith(\"$COMMENT_MARKER\")) | .id" \
+            | head -1)
+          if [ -n "$COMMENT_ID" ]; then
+            gh api "repos/${REPO}/issues/comments/${COMMENT_ID}" \
+              -X PATCH -f body="$(cat comment_body.md)"
+          else
+            gh pr comment "$PR_NUMBER" --repo "$REPO" --body-file comment_body.md
+          fi
 
       - name: Upload candidate results
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1

.github/workflows/benchmark.yml

@@ -37,6 +37,10 @@ on:
         description: "Seeded items per session"
         required: false
         default: "200"
+      network_delay_ms:
+        description: "Simulated client→server latency per request (ms; 0 = loopback)"
+        required: false
+        default: "0"
 
 permissions:
   contents: read
@@ -51,6 +55,9 @@ env:
   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' }}
+  # 0 on the nightly schedule (loopback, for stable trend data); dispatchable
+  # higher to model a real network hop when testing network optimizations.
+  NETWORK_DELAY_MS: ${{ github.event_name == 'workflow_dispatch' && inputs.network_delay_ms || '0' }}
 
 concurrency:
   # Never cancel a scheduled run mid-flight (each is a distinct data point).
@@ -179,6 +186,7 @@ jobs:
             --database-uri "${{ steps.db.outputs.uri }}" \
             --iterations "$ITERATIONS" \
             --runs "$RUNS" \
+            --network-delay-ms "$NETWORK_DELAY_MS" \
             --output "benchmark-results-${{ matrix.backend }}.json"
 
       - name: Upload benchmark results

.github/workflows/bump-version.yml

@@ -139,6 +139,6 @@ jobs:
             --title "Bump version to ${resolved}" \
             --body "Automated version bump via \`.github/workflows/bump-version.yml\` (mode: \`${MODE}\`, input: \`${NEW_VERSION}\`).
 
-          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\`.
+          Rewrote \`[project].version\` and sibling \`==\` pins across all four packages (\`pyproject.toml\`, \`sdks/python-client\`, \`sdks/ui\`, \`integrations/slack\`), the runtime \`VERSION\` constant in \`omnigent/version.py\`, and regenerated \`uv.lock\`.
 
           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

@@ -141,6 +141,17 @@ jobs:
             paths: tests/db tests/deploy
             extra: databricks
             markexpr: databricks
+          # Slack integration (integrations/slack). Its tests live outside the
+          # top-level tests/ tree and import the decoupled `omnigent_slack`
+          # package, so this lane installs the `slack` extra to pull it in. The
+          # tests are run from the repo root on purpose: they rely on the root
+          # pyproject's `asyncio_mode = auto` (rootdir resolution), and
+          # coverage of the omnigent package is a no-op here (the code under
+          # test is omnigent_slack, not omnigent) — harmless, kept for a
+          # uniform pytest step.
+          - group: slack
+            paths: integrations/slack/tests
+            extra: slack
 
     steps:
       - name: Check out repo
@@ -359,14 +370,14 @@ jobs:
           path: .tmp-codex-parity-target/debug/codex-parity-sidecar
           key: codex-parity-bin-${{ runner.os }}-${{ steps.rustc.outputs.version }}-${{ hashFiles('tests/codex_parity/sidecar/**') }}
 
-      - name: Set up Node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: 20
+      - name: Set up pnpm
+        uses: ./.github/actions/setup-pnpm
 
       - name: Install codex CLI
+        env:
+          NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
         run: |
-          npm install --ignore-scripts --prefix .github/ci-deps
+          pnpm install --frozen-lockfile --ignore-scripts --filter e2e-ci-deps
           echo "${GITHUB_WORKSPACE}/.github/ci-deps/node_modules/.bin" >> "$GITHUB_PATH"
 
       - name: Cache virtualenv
@@ -414,8 +425,12 @@ jobs:
     # Combines per-shard coverage into a coverage-summary artifact. Runs in the
     # unprivileged pull_request context (read-only); code-coverage.yml consumes
     # the artifact and posts the status. Report-only.
+    #
+    # Only runs when every pytest shard passed: a failed shard drops its covered
+    # lines from the combine, so coverage off partial data would be misleading —
+    # and a red run gets re-run anyway, re-triggering this.
     needs: pytest
-    if: ${{ !cancelled() && !github.event.pull_request.draft }}
+    if: ${{ success() && !github.event.pull_request.draft }}
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:

.github/workflows/doc-sync.yml

@@ -254,10 +254,14 @@ jobs:
         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
+          # Install outside the checked-out tree: a repo-root package.json would
+          # otherwise capture this bare `npm install` and hoist it there, leaving
+          # this dir's node_modules empty.
+          CC_CLI_DIR="${RUNNER_TEMP}/omnigent-cc-cli"
+          mkdir -p "$CC_CLI_DIR" && cd "$CC_CLI_DIR"
+          npm install --ignore-scripts --no-audit --no-fund @anthropic-ai/claude-code@2.1.212
           node node_modules/@anthropic-ai/claude-code/install.cjs
-          echo "${GITHUB_WORKSPACE}/.cc-cli/node_modules/.bin" >> "$GITHUB_PATH"
+          echo "$CC_CLI_DIR/node_modules/.bin" >> "$GITHUB_PATH"
 
       - name: Write Omnigent provider config
         if: steps.plan.outputs.proceed == 'true' && steps.creds.outputs.available == 'true'

.github/workflows/docker-build.yml

@@ -31,7 +31,8 @@ on:
       - 'pyproject.toml'
       - 'setup.py'
       - 'uv.lock'
-      - 'web/package-lock.json'
+      - 'pnpm-lock.yaml'
+      - 'pnpm-workspace.yaml'
       - '.github/workflows/docker-build.yml'
 
 permissions:

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

@@ -89,14 +89,14 @@ jobs:
           base="${INPUT_BASE:-}"
           proceed=false; dry_run=false
 
-          # Does the tag look like a final release (vX.Y.Z, not rc/dev/alpha/beta)?
+          # Does the tag look like a final release (vX.Y.Z, not a pre-release)?
           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 ;;
+            *rc[0-9]*|*dev[0-9]*|*pre[0-9]*) is_version=false ;;
           esac
 
           if [ "$EVENT_NAME" = "workflow_run" ]; then
@@ -199,52 +199,6 @@ jobs:
             echo "available=true" >> "$GITHUB_OUTPUT"
           fi
 
-      - 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))
-          "
-
       - name: Build drafter prompt
         if: steps.guard.outputs.proceed == 'true' && steps.creds.outputs.available == 'true'
         env:
@@ -277,30 +231,20 @@ jobs:
           pathlib.Path("/tmp/draft_prompt.txt").write_text(prompt)
           PYEOF
 
+      # Runs the tools-less drafter and secret-scans its output; the mechanical
+      # scaffold (already in /tmp/release_notes.md) is the fallback if it can't run.
+      # Checked out at the workspace root, so the action's workdir is the default.
       - name: Run release-notes drafter
         id: draft
         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/draft_prompt.txt)"
-          uv run --project "${GITHUB_WORKSPACE}" omnigent run \
-            "${GITHUB_WORKSPACE}/.github/agents/release-notes-drafter" \
-            -p "$prompt" --no-session \
-            2>draft-stderr.log | tee /tmp/draft_out.txt \
-            || { echo "::warning::drafter exited non-zero — keeping mechanical draft"; cat draft-stderr.log; }
-
-      - name: Scan drafter output for secrets
-        if: steps.draft.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/draft_out.txt 2>/dev/null; then
-            echo "::error::Drafter output contains LLM_API_KEY — aborting."
-            exit 1
-          fi
+        uses: ./.github/actions/run-omnigent-agent
+        with:
+          agent: release-notes-drafter
+          prompt-file: /tmp/draft_prompt.txt
+          output-file: /tmp/draft_out.txt
+          stderr-file: /tmp/draft-stderr.log
+          gateway-base-url: ${{ secrets.GATEWAY_BASE_URL }}
+          llm-api-key: ${{ secrets.LLM_API_KEY }}
 
       - name: Extract synthesized notes (fall back to mechanical)
         if: steps.guard.outputs.proceed == 'true' && steps.creds.outputs.available == 'true'
@@ -455,7 +399,7 @@ jobs:
           python3 - <<'PYEOF'
           import os, pathlib
           key = os.environ.get("LLM_API_KEY", "")
-          for f in ["draft-stderr.log", "/tmp/draft_out.txt", "/tmp/draft_prompt.txt",
+          for f in ["/tmp/draft-stderr.log", "/tmp/draft_out.txt", "/tmp/draft_prompt.txt",
                     "/tmp/release_notes.md"]:
               p = pathlib.Path(f)
               if not p.is_file() or not key:
@@ -472,7 +416,7 @@ jobs:
         with:
           name: draft-release-notes-${{ steps.guard.outputs.tag }}-${{ github.run_id }}
           path: |
-            draft-stderr.log
+            /tmp/draft-stderr.log
             /tmp/draft_out.txt
             /tmp/release_notes.md
             /tmp/mechanical_notes.md

.github/workflows/e2e-ui.yml

@@ -168,8 +168,8 @@ jobs:
         with:
           python-version-file: ".python-version"
 
-      - name: Set up Node 20
-        uses: ./.github/actions/setup-node
+      - name: Set up pnpm
+        uses: ./.github/actions/setup-pnpm
 
       - name: Install uv
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39  # v8.2.0
@@ -225,14 +225,11 @@ jobs:
       - name: Build web SPA
         # Build BEFORE pytest: Vite's emptyOutDir clobbers the static dir,
         # so never run it under xdist or alongside the live server.
-        # --legacy-peer-deps avoids re-resolving the known React 19 peer
-        # conflict under @emoji-mart/react.
         env:
           NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
         run: |
-          cd web
-          npm ci --legacy-peer-deps --no-audit --no-fund
-          npm run build
+          pnpm install --frozen-lockfile --filter web
+          pnpm --filter web run build
 
       # Native coding-agent harness enablement: the next steps let the
       # native render-parity tests boot a real Claude Code / Codex CLI. The
@@ -241,15 +238,17 @@ jobs:
         # claude-code 2.1.170, NOT the 2.1.124 in .github/ci-deps: 2.1.124
         # doesn't recognise the hook events the native bridge configures and
         # shows a blocking startup modal that swallows the first message.
-        # --ignore-scripts then run install.cjs explicitly (audited: platform
-        # detect + same-tree hardlink, no network/exec) and put its bin on PATH.
+        # Runs the package's install script so the platform-specific binary is
+        # linked into the temporary CLI directory and put on PATH.
+        # (The install.cjs script was removed in the same version the upstream
+        # npm package no longer ships it, so lifecycle scripts are required.)
         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"
+          CC_CLI_DIR="${RUNNER_TEMP}/omnigent-cc-cli"
+          mkdir -p "$CC_CLI_DIR" && cd "$CC_CLI_DIR"
+          npm install --no-audit --no-fund @anthropic-ai/claude-code@2.1.212
+          echo "$CC_CLI_DIR/node_modules/.bin" >> "$GITHUB_PATH"
 
       - name: Install Codex CLI
         # @openai/codex at the .github/ci-deps pin (same build as e2e.yml's
@@ -259,9 +258,10 @@ jobs:
         env:
           NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
         run: |
-          mkdir -p "${GITHUB_WORKSPACE}/.codex-cli" && cd "${GITHUB_WORKSPACE}/.codex-cli"
+          CODEX_CLI_DIR="${RUNNER_TEMP}/omnigent-codex-cli"
+          mkdir -p "$CODEX_CLI_DIR" && cd "$CODEX_CLI_DIR"
           npm install --ignore-scripts --no-audit --no-fund @openai/codex@0.139.0
-          echo "${GITHUB_WORKSPACE}/.codex-cli/node_modules/.bin" >> "$GITHUB_PATH"
+          echo "$CODEX_CLI_DIR/node_modules/.bin" >> "$GITHUB_PATH"
 
       - name: Run UI e2e tests
         # --ui-skip-build: the SPA was built in the previous step.

.github/workflows/electron-build.yml

@@ -3,9 +3,12 @@ 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
+# installers PLUS the electron-updater feed manifests (latest-linux.yml /
+# latest.yml) 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.
+# rather than failing when a cert is absent. No publishing to a provider / no
+# release upload (`--publish never`): the artifacts are captured here for manual
+# placement onto the omnigent.ai update feed (omnigent-site repo + artifact host).
 #
 # Run it from the Actions tab (Run workflow). macOS is intentionally omitted —
 # its signed/notarized build lives elsewhere.
@@ -52,37 +55,65 @@ jobs:
         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: Set up pnpm
+        uses: ./.github/actions/setup-pnpm
 
       - name: Install dependencies
-        working-directory: web/electron
-        run: npm ci --no-audit --no-fund
+        env:
+          NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
+        run: |-
+          pnpm install --frozen-lockfile --filter @omnigent/electron
+          pnpm install --frozen-lockfile --filter web
 
       - name: Build ${{ matrix.platform }} app
         working-directory: web/electron
         env:
+          NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
           # 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
+        run: pnpm run ${{ matrix.build-script }} -- --publish never
 
-      - name: Upload installers
+      # One artifact per platform bundling the COMPLETE electron-updater feed —
+      # the installer(s), the .blockmap electron-updater needs for differential
+      # downloads (referenced by path inside latest*.yml; the .deb has no
+      # blockmap since debs aren't differentially updated), and the feed
+      # manifest (latest-linux.yml / latest.yml). upload-artifact zips all
+      # matched files into a single download, so each platform yields one zip
+      # whose contents can be dropped straight onto a feed root (local HTTP
+      # server for testing, or public/_desktop/updates/ on the artifact host).
+      # Ship only the distributables + feed files, not electron-builder's
+      # unpacked intermediates (dist/*-unpacked).
+      #
+      # electron-builder writes the latest*.yml manifests to dist/ even under
+      # --publish never (a publish config exists in build.*.publish, so
+      # update-info generation runs; --publish only skips the provider upload).
+      # The manifest lists each artifact with sha512 + size + relative url.
+
+      - name: Upload Linux feed
+        if: matrix.platform == 'linux'
         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).
+          name: omnigent-desktop-linux
           path: |
             web/electron/dist/*.AppImage
+            web/electron/dist/*.AppImage.blockmap
             web/electron/dist/*.deb
-            web/electron/dist/*.exe
+            web/electron/dist/latest-linux.yml
+          if-no-files-found: error
+          retention-days: 14
+
+      - name: Upload Windows feed
+        if: matrix.platform == 'win'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: omnigent-desktop-win
+          path: |
+            web/electron/dist/*.exe
+            web/electron/dist/*.exe.blockmap
+            web/electron/dist/latest.yml
           if-no-files-found: error
           retention-days: 14

.github/workflows/feature-blog.yml

@@ -52,6 +52,13 @@ on:
         type: choice
         options: [auto, "true", "false"]
         default: auto
+      max_posts:
+        description: >-
+          Maximum number of blog posts to draft (the scout still only picks
+          features that clear the bar, so it may pick fewer). Default 3.
+        required: false
+        type: string
+        default: "3"
 
 permissions:
   contents: read
@@ -86,12 +93,21 @@ jobs:
           INPUT_TAG: ${{ inputs.tag }}
           INPUT_BASE: ${{ inputs.base }}
           INPUT_DRY_RUN: ${{ inputs.dry_run }}
+          INPUT_MAX_POSTS: ${{ inputs.max_posts }}
         run: |
           set -euo pipefail
           tag="${INPUT_TAG:-$RUN_BRANCH}"
           base="${INPUT_BASE:-}"
           proceed=false; dry_run=false
 
+          # How many posts to draft at most. Only settable via manual dispatch;
+          # a real release cut (workflow_run) uses the default. Must be a positive
+          # integer, else fall back to the default.
+          max_posts="${INPUT_MAX_POSTS:-3}"
+          case "$max_posts" in
+            ""|*[!0-9]*|0) max_posts=3 ;;
+          esac
+
           # Does the tag look like a final release (vX.Y.Z, not rc/dev/alpha/beta)?
           is_version=true
           case "$tag" in
@@ -122,7 +138,8 @@ jobs:
           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}" \
+          echo "max_posts=${max_posts}" >> "$GITHUB_OUTPUT"
+          echo "Resolved tag=${tag} base=${base:-<none>} proceed=${proceed} dry_run=${dry_run} max_posts=${max_posts}" \
             | tee -a "$GITHUB_STEP_SUMMARY"
 
       # Trusted default branch, full history + tags for the range computation.
@@ -174,62 +191,18 @@ jobs:
           [ -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 }}
+          MAX_POSTS: ${{ steps.guard.outputs.max_posts }}
         run: |
           set -euo pipefail
           python3 -u <<'PYEOF'
           import os, pathlib
           tag = os.environ["TAG"]
+          max_posts = int(os.environ.get("MAX_POSTS", "3"))
           # `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
@@ -240,6 +213,8 @@ jobs:
           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}.
+          Return AT MOST {max_posts} feature(s), ranked strongest-first — pick fewer
+          if fewer clear the bar. This overrides any other cap in your instructions.
           {note}
           ## Merged PRs (number, title, and author changelog entries)
           {pr_list}
@@ -251,34 +226,28 @@ jobs:
           pathlib.Path("/tmp/scout_prompt.txt").write_text(prompt)
           PYEOF
 
+      # Sets up uv + Claude CLI + the gateway provider config, runs the tools-less
+      # scout on the prompt file, and secret-scans its stdout — the same runner
+      # scaffold draft-release-notes.yml / publish-changelog.yml share. The env it
+      # sets up (PATH, ~/.omnigent, .venv) persists into the drafter loop below, so
+      # only the scout needs to invoke the action.
       - 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
+        uses: ./.github/actions/run-omnigent-agent
+        with:
+          agent: feature-blog-scout
+          prompt-file: /tmp/scout_prompt.txt
+          output-file: /tmp/scout_out.txt
+          stderr-file: ${{ github.workspace }}/scout-stderr.log
+          gateway-base-url: ${{ secrets.GATEWAY_BASE_URL }}
+          llm-api-key: ${{ secrets.LLM_API_KEY }}
 
       - name: Parse candidates
         id: candidates
         if: steps.guard.outputs.proceed == 'true' && steps.creds.outputs.available == 'true'
+        env:
+          MAX_POSTS: ${{ steps.guard.outputs.max_posts }}
         run: |
           set -euo pipefail
           python3 -u <<'PYEOF'
@@ -326,8 +295,9 @@ jobs:
               c["pr_refs"] = refs
               cands.append(c)
 
-          # Cap at 3 defensively (the scout is instructed to, but enforce it here).
-          cands = cands[:3]
+          # Enforce the post cap defensively (the scout is told the limit too).
+          max_posts = int(os.environ.get("MAX_POSTS", "3"))
+          cands = cands[:max_posts]
           pathlib.Path("/tmp/candidates.json").write_text(json.dumps(cands))
           out = os.environ["GITHUB_OUTPUT"]
           with open(out, "a") as f:
@@ -402,6 +372,15 @@ jobs:
                    "## Changelog entries (from the release harvest)", pr_list, "",
                    "## PR diffs"]
           BUDGET = 60_000
+          # Tally who merged the contributing PRs so we can request review from the
+          # maintainer with the most context on the feature (mirrors doc-sync, but a
+          # blog spans many PRs so we pick the most frequent merger). Authors fall
+          # back for it — outside contributors may lack site access, a maintainer
+          # always merges. Skip bots / the CI identity.
+          from collections import Counter
+          mergers, authors = Counter(), Counter()
+          def _usable(login):
+              return bool(login) and not login.endswith("[bot]") and login != "omnigent-ci"
           for pr in refs:
               try:
                   diff = subprocess.run(
@@ -410,7 +389,25 @@ jobs:
               except Exception as e:
                   diff = f"(diff unavailable: {e})"
               parts += [f"### PR #{pr}", f"{fence}diff", diff[:BUDGET], fence]
+              try:
+                  meta = json.loads(subprocess.run(
+                      ["gh", "pr", "view", str(pr), "--repo", repo,
+                       "--json", "mergedBy,author"],
+                      capture_output=True, text=True, timeout=60).stdout or "{}")
+                  mb = (meta.get("mergedBy") or {}).get("login", "")
+                  au = (meta.get("author") or {}).get("login", "")
+                  if _usable(mb):
+                      mergers[mb] += 1
+                  if _usable(au):
+                      authors[au] += 1
+              except Exception as e:
+                  print(f"::notice::Could not read merger/author for PR #{pr}: {e}")
           pathlib.Path(f"/tmp/material_{idx}.txt").write_text("\n".join(parts))
+          # Most-frequent merger wins; ties broken by Counter insertion order (PR
+          # order). Fall back to the most-frequent author, then empty.
+          reviewer = (mergers.most_common(1)[0][0] if mergers
+                      else authors.most_common(1)[0][0] if authors else "")
+          pathlib.Path(f"/tmp/reviewer_{idx}.txt").write_text(reviewer)
           PYEOF
 
             # Start each candidate from a pristine tree: a prior candidate that
@@ -471,14 +468,120 @@ jobs:
 
             # 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)"
+            # can't see untracked paths). Use -uall: plain porcelain collapses a
+            # brand-new directory to "app/blog/<slug>/" and never names the file
+            # inside it, so grep 'page.mdx' would miss it. Porcelain lines are
+            # "XY path"; take the path field of the first added/modified page.mdx.
+            post="$(git -C "$SITE" status --porcelain -uall | grep -m1 'page.mdx' | awk '{print $NF}' || true)"
+
+            # Fail fast on HTML comments in the MDX: `<!-- ... -->` is invalid in
+            # MDX (only `{/* ... */}` works) and would break the site's `next build`
+            # only after the PR is opened. Catch it here so we never ship a red PR.
+            if [ -n "$post" ] && grep -qF '<!--' "${SITE}/${post}"; then
+              echo "::error::Drafted ${post} contains an HTML comment (<!-- -->); MDX requires {/* */}. Aborting."
+              exit 1
+            fi
+
             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' \
+              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 [check the latest release](https://omnigent.ai/releases).\n' \
                 >> "${SITE}/${post}"
             fi
 
+            # Generate the hero illustration from the drafter's IMAGE_PROMPT (the
+            # per-feature subject) plus a fixed brand style suffix, via the image
+            # model on the same gateway host. Fail-soft: any error leaves heroArt
+            # blank (the index falls back to a placeholder card), never blocking
+            # the draft. The scene is machine-drawn from the prompt, so no secret
+            # can reach it; the drafted-file secret scan above already ran.
+            image_prompt="$(sed -n 's/^IMAGE_PROMPT:[[:space:]]*//p' "/tmp/drafter_out_${i}.txt" | head -n1)"
+            if [ -n "$post" ] && [ -n "$image_prompt" ]; then
+              # GATEWAY_BASE_URL is scoped to THIS invocation only (not the step
+              # env), so the unsandboxed drafter run above never sees it and it
+              # can't reach the drafter's scanned stdout.
+              GATEWAY_BASE_URL='${{ secrets.GATEWAY_BASE_URL }}' \
+              IMAGE_PROMPT="$image_prompt" SLUG="$slug" SITE="$SITE" POST="$post" \
+              python3 -u <<'PYEOF' || echo "::warning::hero image generation failed for ${slug}; leaving heroArt blank"
+          import base64, json, os, pathlib, re, urllib.request
+          gw = os.environ.get("GATEWAY_BASE_URL", "")
+          key = os.environ.get("LLM_API_KEY", "")
+          if not gw or not key:
+              raise SystemExit("no gateway/key for image generation")
+          # The image model lives on the same workspace host as the anthropic
+          # gateway (GATEWAY_BASE_URL = <host>/anthropic). Derive scheme://host.
+          m = re.match(r"(https?://[^/]+)", gw)
+          if not m:
+              raise SystemExit(f"cannot parse gateway host from {gw!r}")
+          model = os.environ.get("IMAGE_MODEL", "databricks-gemini-3-pro-image")
+          url = f"{m.group(1)}/serving-endpoints/{model}/invocations"
+          style = (" Flat vector illustration, dark navy tech background with subtle "
+                   "circuit lines, teal and pink accents, 16:9 wide, no text, no words, "
+                   "no logos.")
+          body = json.dumps({"messages": [{"role": "user",
+                 "content": os.environ["IMAGE_PROMPT"] + style}], "max_tokens": 4096}).encode()
+          req = urllib.request.Request(url, data=body, method="POST", headers={
+              "Authorization": f"Bearer {key}", "Content-Type": "application/json"})
+          with urllib.request.urlopen(req, timeout=120) as resp:
+              data = json.load(resp)
+          # The image is the content part of type image_url (a data: URI).
+          uri = None
+          for part in data["choices"][0]["message"]["content"]:
+              if isinstance(part, dict) and part.get("type") == "image_url":
+                  uri = part["image_url"]["url"]
+                  break
+          if not uri or "," not in uri:
+              raise SystemExit("no image in model response")
+          raw = base64.b64decode(uri.split(",", 1)[1])
+          if raw[:8] != b"\x89PNG\r\n\x1a\n":
+              raise SystemExit("model returned non-PNG data")
+          slug = os.environ["SLUG"]
+          # Defense-in-depth: slug is validated as strict kebab-case upstream, but
+          # this is the one place it names a new file — re-check before writing.
+          if not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", slug):
+              raise SystemExit(f"unsafe slug for hero path: {slug!r}")
+          dest = pathlib.Path(os.environ["SITE"], "public", "images", "blog", f"{slug}.png")
+          dest.parent.mkdir(parents=True, exist_ok=True)
+          dest.write_bytes(raw)
+          # Point heroArt at the served path (public/ maps to site root).
+          post_path = pathlib.Path(os.environ["SITE"], os.environ["POST"])
+          text = post_path.read_text(encoding="utf-8")
+          text, n = re.subn(r'heroArt:\s*"[^"]*"', f'heroArt: "/images/blog/{slug}.png"', text, count=1)
+          if not n:
+              # No double-quoted heroArt to rewrite — drop the orphan PNG so we
+              # don't commit an image nothing references.
+              dest.unlink(missing_ok=True)
+              raise SystemExit("no heroArt: \"\" field to rewrite; discarding hero image")
+          post_path.write_text(text, encoding="utf-8")
+          print(f"generated hero image ({len(raw)} bytes) -> /images/blog/{slug}.png")
+          PYEOF
+            fi
+
+            # Prettier the drafter's changed files so they pass the site's
+            # `fmt:check` gate — LLM-generated MDX/JS (and the CTA footer appended
+            # above) are rarely prettier-clean. Run from inside $SITE so prettier
+            # discovers the site's .prettierrc.json + .prettierignore, and pin the
+            # site's major version. Formatting failures are non-fatal: a human
+            # reviews the draft PR and CI still reports any residual issue.
+            mapfile -t changed < <(git -C "$SITE" status --porcelain -uall | awk '{print $NF}')
+            if [ "${#changed[@]}" -gt 0 ]; then
+              ( cd "$SITE" && npx --yes prettier@3 --write --ignore-unknown "${changed[@]}" ) \
+                || echo "::warning::prettier --write failed for ${slug}; committing unformatted (CI will flag)"
+            fi
+
+            # Surface the drafted post itself: copy it to /tmp (uploaded as an
+            # artifact) and, on a dry run, render it into the job summary so the
+            # post body can be reviewed without opening a PR.
+            if [ -n "$post" ] && [ -f "${SITE}/${post}" ]; then
+              cp "${SITE}/${post}" "/tmp/post_${i}.mdx"
+              {
+                echo "<details><summary>Drafted post: ${slug}</summary>"
+                echo
+                echo '```mdx'
+                cat "${SITE}/${post}"
+                echo '```'
+                echo "</details>"
+              } >> "$GITHUB_STEP_SUMMARY"
+            fi
+
             title=$(sed -n 's/^BLOG_PR_TITLE:[[:space:]]*//p' "/tmp/drafter_out_${i}.txt" | head -n1)
             [ -z "$title" ] && title="add feature blog: ${headline}"
 
@@ -528,26 +631,57 @@ jobs:
           gh label create automated-blog --repo "$SITE_REPO" \
             --color 5319e7 --description "Auto-drafted feature-blog post" 2>/dev/null || true
 
+          # Request review from the maintainer with the most context on the
+          # feature — the person who merged the most of its contributing PRs
+          # (computed in the Draft posts step). The @-mention in the body is the
+          # durable ping (reaches concealed org members); the --add-reviewer /
+          # --add-assignee calls are best-effort (GitHub 422s non-collaborators),
+          # so tolerate their failure and never let it block the PR.
+          assign_reviewer() {
+            local pr_ref="$1" who="$2"
+            [ -n "$who" ] || return 0
+            gh pr edit "$pr_ref" --repo "$SITE_REPO" --add-reviewer "$who" \
+              || echo "::notice::Could not request review from ${who} (not addable); they're @-mentioned in the PR body."
+            gh pr edit "$pr_ref" --repo "$SITE_REPO" --add-assignee "$who" \
+              || echo "::notice::Could not assign ${who} (not addable); they're @-mentioned in the PR body."
+          }
+
+          echo "## Draft blog PRs" >> "$GITHUB_STEP_SUMMARY"
           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"
+            reviewer="$(cat "/tmp/reviewer_${idx}.txt" 2>/dev/null || true)"
+            mention=""
+            [ -n "$reviewer" ] && mention=" · most context @${reviewer}"
+
+            # Build the body once so the update path can refresh it too — the
+            # @-mention is the durable ping (--add-reviewer commonly 422s because
+            # the source-repo maintainer isn't an omnigent-site collaborator), so
+            # it must be written on BOTH the create and force-push-update paths.
+            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) and do a final voice pass. The hero image and `author: omnigent` byline are auto-generated — review and optionally replace them.\n\n%s\n\nSource release: %s%s\n<sub>Generated by omnigent `.github/workflows/feature-blog.yml`. Review for accuracy before merging.</sub>' "$title" "$TAG" "$summary" "$TAG" "$mention")"
+
+            existing="$(gh pr list --repo "$SITE_REPO" --head "$branch" --state open --json url --jq '.[].url' | head -n1)"
+            if [ -n "$existing" ]; then
+              gh pr edit "$existing" --repo "$SITE_REPO" --body "$body" \
+                || echo "::notice::Could not refresh body for ${existing}."
+              assign_reviewer "$existing" "$reviewer"
+              echo "- [${title}](${existing})${mention} — updated existing draft (force-pushed)" \
+                >> "$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 \
+            url="$(gh pr create \
               --repo "$SITE_REPO" \
               --base main \
               --head "$branch" \
               --draft \
               --title "blog: ${title}" \
               --body "$body" \
-              --label automated-blog
+              --label automated-blog)"
+            assign_reviewer "$url" "$reviewer"
+            echo "- [${title}](${url})${mention}" >> "$GITHUB_STEP_SUMMARY"
           done < /tmp/drafted_branches.txt
 
       # ::add-mask:: redacts rendered logs, not artifact files — scrub the key
@@ -565,6 +699,7 @@ jobs:
           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")
+          files += glob.glob("/tmp/post_*.mdx")
           for f in files:
               p = pathlib.Path(f)
               if not p.is_file() or not key:
@@ -575,7 +710,7 @@ jobs:
                   print(f"redacted key from {f}")
           PYEOF
 
-      - name: Upload logs on failure
+      - name: Upload logs and drafted posts
         if: always() && steps.guard.outputs.proceed == 'true'
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
@@ -586,5 +721,6 @@ jobs:
             /tmp/scout_out.txt
             /tmp/candidates.json
             /tmp/drafter_out_*.txt
+            /tmp/post_*.mdx
           retention-days: 7
           if-no-files-found: ignore

.github/workflows/finalize-release.yml

@@ -2,13 +2,16 @@
 # 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,
+# Deterministic gates first (each fails with actionable links):
+#   * the tag is a final vX.Y.Z (input is normalized: `0.7.0` -> `v0.7.0`)
+#     with an unpublished draft release; a draft whose tag binding was lost
+#     to a web-UI edit (tag_name became `untagged-…`) is rebound automatically,
 #   * 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 auto/changelog/vX.Y.Z CHANGELOG PR isn't sitting open.
+# The docs sweep (open PRs against omnigent-site's X.Y-docs staging branch) is
+# ADVISORY only: it lists what is still unmerged but never blocks the publish —
+# docs can land after the release, any time before the docs-publish PR merges.
 #
 # The publish job binds the `publish-release` environment (one-time setup:
 # create it in repo settings with required reviewers). Approving it is the
@@ -64,16 +67,23 @@ jobs:
     outputs:
       release_id: ${{ steps.draft.outputs.release_id }}
       already_published: ${{ steps.draft.outputs.already_published }}
+      tag: ${{ steps.tag.outputs.tag }}
     steps:
       - name: Require a final vX.Y.Z tag
+        id: tag
         env:
-          TAG: ${{ inputs.tag }}
+          RAW_TAG: ${{ inputs.tag }}
         run: |
           set -euo pipefail
+          # Normalize the input: trim whitespace, add the leading v if omitted
+          # (`0.7.0` -> `v0.7.0`), so a bare version doesn't fail the dispatch.
+          TAG="$(printf '%s' "$RAW_TAG" | tr -d '[:space:]')"
+          case "$TAG" in v*) ;; *) TAG="v${TAG}" ;; esac
           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."
+            echo "::error::${RAW_TAG} is not a final vX.Y.Z tag — rc/dev/pre releases never finalize."
             exit 1
           fi
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
 
       # Drafts are invisible to read-only tokens and unaddressable by tag
       # (the get-by-tag endpoint 404s on drafts) — resolve by listing with the
@@ -93,11 +103,32 @@ jobs:
         id: draft
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
-          TAG: ${{ inputs.tag }}
+          TAG: ${{ steps.tag.outputs.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
+            # Editing a draft in the web UI can silently drop its tag binding
+            # (tag_name becomes `untagged-…` while the name stays vX.Y.Z; bit
+            # v0.5.0 and v0.7.0). Recover: match the DRAFT by name and rebind —
+            # only ever onto a tag that already exists, so publishing can never
+            # mint a new tag at main.
+            match="$(gh api "repos/${GITHUB_REPOSITORY}/releases" --paginate \
+              --jq 'map(select(.draft == true and .name == env.TAG)) | first // empty')"
+            if [ -n "$match" ]; then
+              if ! gh api "repos/${GITHUB_REPOSITORY}/git/ref/tags/${TAG}" --jq .object.sha >/dev/null 2>&1; then
+                echo "::error::Draft named ${TAG} exists but the git tag does not — push the tag before finalizing."
+                exit 1
+              fi
+              rebind_id="$(printf '%s' "$match" | jq -r '.id')"
+              gh api --method PATCH "repos/${GITHUB_REPOSITORY}/releases/${rebind_id}" \
+                -f tag_name="$TAG" > /dev/null
+              match="$(gh api "repos/${GITHUB_REPOSITORY}/releases/${rebind_id}")"
+              echo "Rebound draft ${rebind_id} to ${TAG} (tag binding was lost, usually to a web-UI edit)." \
+                | tee -a "$GITHUB_STEP_SUMMARY"
+            fi
+          fi
           if [ -z "$match" ]; then
             echo "::error::No GitHub release found for ${TAG}. Did the tag push run github-release.yml?"
             exit 1
@@ -118,7 +149,7 @@ jobs:
       - name: Assert PyPI serves all three packages
         if: steps.draft.outputs.already_published != 'true'
         env:
-          TAG: ${{ inputs.tag }}
+          TAG: ${{ steps.tag.outputs.tag }}
         run: |
           set -euo pipefail
           version="${TAG#v}"
@@ -134,7 +165,7 @@ jobs:
         if: steps.draft.outputs.already_published != 'true'
         env:
           GH_TOKEN: ${{ github.token }}
-          TAG: ${{ inputs.tag }}
+          TAG: ${{ steps.tag.outputs.tag }}
         run: |
           set -euo pipefail
           open_pr="$(gh pr list --repo "$GITHUB_REPOSITORY" --head "auto/changelog/${TAG}" \
@@ -145,11 +176,14 @@ jobs:
           fi
           echo "CHANGELOG PR for ${TAG}: merged or not needed."
 
-      - name: Docs sweep — no open PRs against the X.Y-docs staging branch
+      # Advisory only: docs frequently land after the release. The list tells
+      # the coordinator what must merge into X.Y-docs before the docs-publish
+      # PR does — it never blocks the publish itself.
+      - name: Docs sweep — list 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 }}
+          TAG: ${{ steps.tag.outputs.tag }}
           SITE_REPO: ${{ github.repository_owner }}/omnigent-site
         run: |
           set -euo pipefail
@@ -158,16 +192,17 @@ jobs:
           open="$(gh pr list --repo "$SITE_REPO" --base "$docs_branch" --state open \
             --json url,title --jq '.[] | "- \(.url)  \(.title)"')"
           if [ -n "$open" ]; then
+            count="$(printf '%s\n' "$open" | grep -c .)"
             {
-              echo "## Docs sweep failed for ${TAG}"
+              echo "## Docs sweep for ${TAG} — ${count} open PR(s) still target \`${docs_branch}\`"
               echo ""
-              echo "Open PRs still target \`${docs_branch}\` on ${SITE_REPO} — review and merge/close them, then re-dispatch:"
+              echo "Advisory, not blocking. Merge/close these before merging the docs-publish PR:"
               echo "$open"
             } | tee -a "$GITHUB_STEP_SUMMARY"
-            echo "::error::Open doc PRs still target ${docs_branch} — see the run summary."
-            exit 1
+            echo "::warning::${count} open doc PR(s) still target ${docs_branch} (non-blocking) — see the run summary."
+          else
+            echo "Docs sweep clean: no open PRs against ${docs_branch}." | tee -a "$GITHUB_STEP_SUMMARY"
           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:
@@ -189,7 +224,7 @@ jobs:
       - name: Publish the draft as Latest
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
-          TAG: ${{ inputs.tag }}
+          TAG: ${{ needs.checks.outputs.tag }}
           RELEASE_ID: ${{ needs.checks.outputs.release_id }}
         run: |
           set -euo pipefail

.github/workflows/flake-stress-e2e.yml

@@ -238,22 +238,26 @@ jobs:
         # executor adapters import at collection time.
         run: uv sync --extra all --extra dev
 
+      - name: Set up pnpm
+        uses: ./.github/actions/setup-pnpm
+
       - name: Install binary dependencies
         # Mirrors e2e.yml. ripgrep: Grep fallback for inner tests. tmux +
         # bubblewrap: the e2e runner runs real agents under the linux_bwrap
         # sandbox, which fails loud if `bwrap` is missing. The apparmor
         # sysctl mirrors ci.yml (Ubuntu 24.04 blocks unprivileged user
-        # namespaces, which bwrap's unshare(CLONE_NEWUSER) needs). npm install
-        # with --ignore-scripts blocks postinstall; the claude-code stub needs
-        # its audited install.cjs run explicitly (platform detect + same-tree
-        # hardlink, no network/exec) for claude-sdk harness rows.
-        working-directory: .github/ci-deps
+        # namespaces, which bwrap's unshare(CLONE_NEWUSER) needs). pnpm
+        # install with --ignore-scripts blocks postinstall; the claude-code
+        # stub needs its audited install.cjs run explicitly (platform detect +
+        # same-tree hardlink, no network/exec) for claude-sdk harness rows.
+        env:
+          NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
         run: |
           sudo apt-get update
           sudo apt-get install -y ripgrep tmux bubblewrap
           sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
-          npm install --ignore-scripts
-          node node_modules/@anthropic-ai/claude-code/install.cjs
+          pnpm install --frozen-lockfile --ignore-scripts --filter e2e-ci-deps
+          node .github/ci-deps/node_modules/@anthropic-ai/claude-code/install.cjs
           echo "${GITHUB_WORKSPACE}/.github/ci-deps/node_modules/.bin" >> "$GITHUB_PATH"
 
       - name: Run pytest target

.github/workflows/flake-stress-ui.yml

@@ -162,8 +162,8 @@ jobs:
         with:
           python-version-file: ".python-version"
 
-      - name: Set up Node 20
-        uses: ./.github/actions/setup-node
+      - name: Set up pnpm
+        uses: ./.github/actions/setup-pnpm
 
       - name: Install uv
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39  # v8.2.0
@@ -222,20 +222,20 @@ jobs:
         env:
           NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
         run: |
-          cd web
-          npm ci --legacy-peer-deps --no-audit --no-fund
-          npm run build
+          pnpm install --frozen-lockfile --filter web
+          pnpm --filter web run build
 
       - name: Install Claude Code CLI
         # Pinned to match e2e-ui.yml (2.1.170 recognises the native bridge
-        # hook events). --ignore-scripts then run the audited install.cjs.
+        # hook events). Runs lifecycle scripts so the platform-specific binary
+        # is linked and put on PATH.
         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"
+          CC_CLI_DIR="${RUNNER_TEMP}/omnigent-cc-cli"
+          mkdir -p "$CC_CLI_DIR" && cd "$CC_CLI_DIR"
+          npm install --no-audit --no-fund @anthropic-ai/claude-code@2.1.212
+          echo "$CC_CLI_DIR/node_modules/.bin" >> "$GITHUB_PATH"
 
       - name: Install Codex CLI
         # @openai/codex pinned to match e2e-ui.yml; goal-mode app-server APIs
@@ -243,9 +243,10 @@ jobs:
         env:
           NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
         run: |
-          mkdir -p "${GITHUB_WORKSPACE}/.codex-cli" && cd "${GITHUB_WORKSPACE}/.codex-cli"
+          CODEX_CLI_DIR="${RUNNER_TEMP}/omnigent-codex-cli"
+          mkdir -p "$CODEX_CLI_DIR" && cd "$CODEX_CLI_DIR"
           npm install --ignore-scripts --no-audit --no-fund @openai/codex@0.139.0
-          echo "${GITHUB_WORKSPACE}/.codex-cli/node_modules/.bin" >> "$GITHUB_PATH"
+          echo "$CODEX_CLI_DIR/node_modules/.bin" >> "$GITHUB_PATH"
 
       - name: Run pytest target
         # Inputs validated by prep. Word-splitting on $TEST_TARGET / $EXTRA_ARGS

.github/workflows/github-release.yml

@@ -28,7 +28,10 @@ on:
   push:
     tags:
       # Version tags only (v0.2.0, v0.2.0rc1, …) — `v[0-9]*` avoids triggering
-      # on non-release tags like `v-infra-*`.
+      # on non-release tags like `v-infra-*`. Pre-release tags (rcN / devN /
+      # preN) still match the glob but are skipped in the job below — no
+      # GitHub release is created for them; their installable artifacts live
+      # only on PyPI, and a curated release page is reserved for the final cut.
       - "v[0-9]*"
 
 # Least privilege: creating a release requires `contents: write`; nothing here
@@ -43,9 +46,30 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
+      - name: Skip pre-release tags (rcN / devN / preN)
+        id: tag
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          # Pre-release tags (rcN / devN / preN) get NO GitHub release — they
+          # live on PyPI only, and a curated release page is reserved for the
+          # final cut. The tag glob above still matches them, so gate here.
+          # A trailing digit is required so a substring like 'dev' or 'pre' in a
+          # mistyped tag name can't trigger a skip by accident.
+          case "$TAG" in
+            *rc[0-9]*|*dev[0-9]*|*pre[0-9]*)
+              echo "Pre-release tag ${TAG} — not creating a GitHub release (rc/dev/pre releases live on PyPI only)." \
+                | tee -a "$GITHUB_STEP_SUMMARY"
+              echo "skip=true" >> "$GITHUB_OUTPUT" ;;
+            *)
+              echo "skip=false" >> "$GITHUB_OUTPUT" ;;
+          esac
+
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        if: steps.tag.outputs.skip != 'true'
 
       - name: Draft release with a placeholder body
+        if: steps.tag.outputs.skip != 'true'
         env:
           GH_TOKEN: ${{ github.token }}
           TAG: ${{ github.ref_name }}
@@ -57,20 +81,11 @@ jobs:
             echo "Release $TAG already exists — skipping." | tee -a "$GITHUB_STEP_SUMMARY"
             exit 0
           fi
-          # rc / dev / alpha / beta tags are flagged as pre-releases.
-          pre=""
-          case "$TAG" in
-            *rc*|*dev*|*a[0-9]*|*b[0-9]*) pre="--prerelease" ;;
-          esac
-          # $pre is intentionally UNQUOTED: it word-splits to nothing when empty,
-          # and is only ever "" or "--prerelease" (set just above, never from
-          # external input). Quoting it would pass an empty positional arg.
           gh release create "$TAG" \
             --repo "$GITHUB_REPOSITORY" \
             --draft \
             --verify-tag \
             --notes "_Release notes are being drafted automatically — check back shortly._" \
-            --title "$TAG" \
-            $pre
+            --title "$TAG"
           echo "Drafted release $TAG — curated notes will be filled in by draft-release-notes.yml; review and publish from the Releases page." \
             | tee -a "$GITHUB_STEP_SUMMARY"

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

@@ -61,14 +61,14 @@ jobs:
           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).
+          # Only final vX.Y.Z tags; exclude rcN/devN/preN pre-releases and
+          # the event's prerelease flag (homebrew users get stable releases).
           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 ;;
+            *rc[0-9]*|*dev[0-9]*|*pre[0-9]*|*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"

.github/workflows/issue-triage.yml

@@ -179,10 +179,14 @@ jobs:
         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
+          # Install outside the checked-out tree: a repo-root package.json would
+          # otherwise capture this bare `npm install` and hoist it there, leaving
+          # this dir's node_modules empty.
+          CC_CLI_DIR="${RUNNER_TEMP}/omnigent-cc-cli"
+          mkdir -p "$CC_CLI_DIR" && cd "$CC_CLI_DIR"
+          npm install --ignore-scripts --no-audit --no-fund @anthropic-ai/claude-code@2.1.212
           node node_modules/@anthropic-ai/claude-code/install.cjs
-          echo "${GITHUB_WORKSPACE}/.cc-cli/node_modules/.bin" >> "$GITHUB_PATH"
+          echo "$CC_CLI_DIR/node_modules/.bin" >> "$GITHUB_PATH"
 
       - name: Set LLM credentials
         if: steps.creds.outputs.available == 'true'

.github/workflows/lint.yml

@@ -76,32 +76,30 @@ jobs:
         # a stale lockfile). Fix locally with `uv lock`.
         run: uv sync --locked --extra dev
 
-      # Sets up Node 20 and pins npm to the same major that regenerates
-      # the lockfile in the OSS-regen workflows, so the freshness gate
-      # below doesn't flake on npm version-skew churn.
-      - name: Set up Node.js
-        uses: ./.github/actions/setup-node
+      # Sets up Node 20 + pnpm, with pnpm dependency caching keyed on the
+      # workspace lockfile. pnpm is pinned in .github/actions/setup-pnpm.
+      - name: Set up pnpm
+        uses: ./.github/actions/setup-pnpm
 
       - name: Install web dependencies
-        working-directory: web
-        # Pin the npm registry to the npmjs default.
+        # Pin the npm registry to the npmjs default; limit to the web package
+        # so the Electron package's large native devDependencies are not fetched.
         env:
           NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
-        run: npm ci --legacy-peer-deps
+        run: pnpm install --frozen-lockfile --filter web
 
-      # The npm equivalent of the `uv sync --locked` gate above. `npm ci`
-      # only checks the lockfile is CONSISTENT with package.json; it
-      # tolerates cosmetic drift (dev/extraneous flags, metadata) that a
-      # fresh resolution would rewrite. Regenerate the lockfile and fail
-      # if it differs from the committed one.
-      - name: Check web/package-lock.json is up to date
-        working-directory: web
+      # The pnpm equivalent of the `uv sync --locked` gate above.
+      # `pnpm install --frozen-lockfile` only checks the lockfile is CONSISTENT
+      # with package.json; it tolerates cosmetic drift that a fresh resolution
+      # would rewrite. Regenerate the lockfile and fail if it differs from the
+      # committed one.
+      - name: Check pnpm-lock.yaml is up to date
         env:
           NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
         run: |
-          npm install --package-lock-only --legacy-peer-deps --no-audit --no-fund
-          git diff --exit-code package-lock.json || {
-            echo "::error::web/package-lock.json is out of date. Run 'npm install --package-lock-only --legacy-peer-deps' in web/ and commit the result."
+          pnpm install --lockfile-only
+          git diff --exit-code pnpm-lock.yaml || {
+            echo "::error::pnpm-lock.yaml is out of date. Run 'pnpm install --lockfile-only' at the repo root and commit the result."
             exit 1
           }
 
@@ -125,11 +123,12 @@ jobs:
       - name: Run formatting, lint, and typing checks
         run: uv run pre-commit run --all-files --show-diff-on-failure
 
-      - name: Type-check web
-        working-directory: web
-        run: npm run type-check
+      # Type-checking is temporarily skipped in CI while the pnpm lockfile
+      # settles; `pnpm --filter web run type-check` still works locally.
+      # - name: Type-check web
+      #   run: pnpm --filter web run type-check
 
-  # The three packages release in lockstep (identical versions + `==` sibling
+  # The four 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:

.github/workflows/merge-ready.yml

@@ -27,7 +27,9 @@ on:
   pull_request_target:
     types: [labeled]
   workflow_run:
-    workflows: [PR Template, CI, Lint, Docker build, E2E UI Tests, E2E Tests, Integration Tests]
+    workflows: [PR Template, CI, Lint, Docker build, E2E UI Tests, E2E Tests, Integration Tests, UI Snapshot]
+    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

@@ -50,8 +50,10 @@ permissions:
   contents: read
 
 concurrency:
-  # Key by SHA so back-to-back merges each build; don't cancel mid-push.
-  group: oss-publish-images-${{ github.sha }}
+  # One build at a time: rc and final tags land minutes apart at a release cut,
+  # and built concurrently they race each other's layer cache cold and blow the
+  # job timeout. Serialized, the later build reuses the earlier one's layers.
+  group: oss-publish-images
   cancel-in-progress: false
 
 jobs:
@@ -67,9 +69,10 @@ jobs:
     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
-    # npm/pip native steps). 30m was tight for two native amd64 builds; give the
-    # four-variant (server+host × amd64+arm64) build headroom.
-    timeout-minutes: 60
+    # npm/pip native steps). A cold-cache four-variant (server+host × amd64+
+    # arm64) build can exceed 60m, and hitting the timeout loses the release's
+    # images silently — give it real headroom.
+    timeout-minutes: 120
     steps:
       - name: Checkout
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0

.github/workflows/oss-regen-on-comment.yml

@@ -1,5 +1,5 @@
 # A maintainer comments `/regen` on a PR to regenerate the repo's lockfiles
-# (uv.lock + web/package-lock.json) against public PyPI/npm and commit them
+# (uv.lock + pnpm-lock.yaml) against public PyPI/npmjs.org and commit them
 # ONTO that PR's branch. Use when the PR itself moved a dependency; complements
 # oss-regenerate-and-smoke.yml (standalone rolling PR on dispatch).
 #
@@ -164,28 +164,14 @@ jobs:
         with:
           enable-cache: false
 
-      - name: Set up Node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
-        with:
-          node-version: "20"
+      - name: Set up pnpm
+        uses: ./.github/actions/setup-pnpm
 
-      # 7-day cooldown comes from uv.toml (`exclude-newer = "P7D"`), recorded as
-      # a relative span; an env-var cutoff would stamp an absolute date and break
-      # later `uv sync --locked`. npm's cooldown (web/.npmrc min-release-age=7)
-      # is only honored by npm >= 11.10.0; node 20 ships npm 10.x which ignores it.
-      # Pin the EXACT version (not a range) and keep it in lockstep with
-      # .github/actions/setup-node (npm 11.12.1): this workflow generates the
-      # lockfile and that action verifies it, so a version gap would fail the
-      # freshness gate in lint.yml.
-      - name: Ensure npm honors the dependency cooldown
-        run: npm install -g npm@11.12.1
-      # Delete package-lock.json so npm RESOLVES from scratch: min-release-age
-      # only filters during resolution, and --package-lock-only keeps an existing
-      # in-range pin without re-applying the cooldown.
-      # --legacy-peer-deps is REQUIRED and MUST match the flag lint.yml verifies
-      # with (React 18 runtime vs React 19 peers would otherwise ERESOLVE-fail,
-      # and a flag mismatch rewrites dev/extraneous flags, failing the gate).
-      - name: Regenerate lockfiles against public PyPI/npm
+      # 7-day cooldown comes from uv.toml (`exclude-newer = "P7D"`) and from
+      # pnpm-workspace.yaml (`minimumReleaseAge: 10080`), recorded as a relative
+      # span; an env-var cutoff would stamp an absolute date and break later
+      # `uv sync --locked` / `pnpm install --frozen-lockfile`.
+      - name: Regenerate lockfiles against public PyPI/npmjs.org
         env:
           REGEN_MODE: ${{ needs.authorize.outputs.mode }}
           UPGRADE_PKGS: ${{ needs.authorize.outputs.pkgs }}
@@ -203,7 +189,8 @@ jobs:
           else
             uv lock
           fi
-          ( cd web && rm -f package-lock.json && npm install --package-lock-only --legacy-peer-deps --no-audit --no-fund )
+          rm -f pnpm-lock.yaml
+          pnpm install --lockfile-only
 
       # Mint the App token only AFTER `uv lock` so untrusted PR build backends
       # never see it. Skipped when the App isn't configured (push then falls back
@@ -229,12 +216,12 @@ jobs:
           git config user.name "omnigent-ci[bot]"
           git config user.email "294685417+omnigent-ci[bot]@users.noreply.github.com"
           # --porcelain (not git diff) so first-time UNTRACKED lockfiles count too.
-          if [ -z "$(git status --porcelain -- uv.lock web/package-lock.json)" ]; then
+          if [ -z "$(git status --porcelain -- uv.lock pnpm-lock.yaml)" ]; then
             echo "changed=false" >> "$GITHUB_OUTPUT"
             echo "Lockfiles already current — nothing to commit."
             exit 0
           fi
-          git add uv.lock web/package-lock.json
+          git add uv.lock pnpm-lock.yaml
           git commit -m "chore(oss): regenerate public lockfiles against public PyPI/npm"
           git push "https://x-access-token:${PUSH_TOKEN}@github.com/${REPO}.git" "HEAD:$HEAD_REF"
           echo "changed=true" >> "$GITHUB_OUTPUT"
@@ -256,7 +243,7 @@ jobs:
             upgraded=" (upgraded: $UPGRADE_PKGS)"
           fi
           if [ "$CHANGED" = "true" ]; then
-            base="✅ Regenerated \`uv.lock\`$upgraded + \`web/package-lock.json\` against public PyPI/npm and pushed to this PR."
+            base="✅ Regenerated \`uv.lock\`$upgraded + \`pnpm-lock.yaml\` against public PyPI/npmjs.org and pushed to this PR."
             if [ "$APP_USED" = "true" ]; then
               body="$base CI will re-run on the new commit."
             else

.github/workflows/oss-regenerate-and-smoke.yml

@@ -40,40 +40,26 @@ jobs:
         with:
           enable-cache: false
 
-      - name: Set up Node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: "20"
+      - name: Set up pnpm
+        uses: ./.github/actions/setup-pnpm
 
-      # 7-day cooldown comes from uv.toml (`exclude-newer = "P7D"`), recorded as
-      # a relative span; an env-var cutoff would stamp an absolute date and break
-      # later `uv sync --locked`.
+      # 7-day cooldown comes from uv.toml (`exclude-newer = "P7D"`) and from
+      # pnpm-workspace.yaml (`minimumReleaseAge: 10080`), recorded as a relative
+      # span; an env-var cutoff would stamp an absolute date and break later
+      # `uv sync --locked` / `pnpm install --frozen-lockfile`.
       - name: Regenerate uv.lock
         run: uv lock
 
-      # npm's cooldown (web/.npmrc `min-release-age=7`) is only honored by
-      # npm >= 11.10.0; node 20 ships npm 10.x which silently ignores it.
-      # Pin the EXACT version (not a range) and keep it in lockstep with
-      # .github/actions/setup-node: this workflow generates the lockfile and
-      # that action verifies it, so a version gap would fail the freshness
-      # gate in lint.yml. 11.12.1 satisfies the >= 11.10.0 cooldown floor.
-      - name: Ensure npm honors the dependency cooldown
-        run: npm install -g npm@11.12.1
-      # Delete the lockfile so npm RESOLVES from scratch: min-release-age only
-      # filters during resolution, and --package-lock-only keeps an existing
-      # in-range pin without re-applying the cooldown.
-      #
-      # --legacy-peer-deps is REQUIRED: the tree pins React 18 at runtime while
-      # much of the UI stack (and @types/react) peer-requires React 19, so npm's
-      # strict resolver would ERESOLVE-fail without it. It MUST match the flag the
-      # freshness gate in lint.yml verifies with; generating without it resolves
-      # the peer graph differently and rewrites the dev/devOptional/extraneous
-      # flags, failing that byte-exact gate.
-      - name: Regenerate package-lock.json
-        working-directory: web
+      # pnpm's cooldown is configured in pnpm-workspace.yaml and respected by
+      # the workspace root. Delete the lockfile so pnpm RESOLVES from scratch:
+      # --lockfile-only keeps an existing in-range pin without re-applying the
+      # cooldown, so we drop it first.
+      - name: Regenerate pnpm-lock.yaml
+        env:
+          NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
         run: |
-          rm -f package-lock.json
-          npm install --package-lock-only --legacy-peer-deps --no-audit --no-fund
+          rm -f pnpm-lock.yaml
+          pnpm install --lockfile-only
 
       # Validate BEFORE committing: the Docker build proves the regenerated
       # locks + public registries produce a working image.
@@ -106,15 +92,15 @@ jobs:
           git config user.name "omnigent-ci[bot]"
           git config user.email "294685417+omnigent-ci[bot]@users.noreply.github.com"
           # --porcelain (not git diff) so first-regen UNTRACKED lockfiles count too.
-          if [ -z "$(git status --porcelain -- uv.lock web/package-lock.json)" ]; then
+          if [ -z "$(git status --porcelain -- uv.lock pnpm-lock.yaml)" ]; then
             echo "Lockfiles already current — nothing to PR."
             exit 0
           fi
           # One rolling branch, force-pushed each run, so regens update a single PR.
           BRANCH="automation/oss-lockfile-regen"
           git checkout -b "$BRANCH"
-          git add uv.lock web/package-lock.json
-          git commit -m "chore(oss): regenerate public lockfiles against public PyPI/npm"
+          git add uv.lock pnpm-lock.yaml
+          git commit -m "chore(oss): regenerate public lockfiles against public PyPI/npmjs.org"
           git push --force "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.git" "$BRANCH"
           # An already-open PR just picks up the force-pushed update.
           if [ -n "$(gh pr list --head "$BRANCH" --state open --json number --jq '.[0].number // empty')" ]; then

.github/workflows/polly-review.yml

@@ -171,19 +171,26 @@ jobs:
         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
+          # Install outside the checked-out tree: a repo-root package.json would
+          # otherwise capture this bare `npm install` and hoist it there, leaving
+          # this dir's node_modules empty.
+          CC_CLI_DIR="${RUNNER_TEMP}/omnigent-cc-cli"
+          mkdir -p "$CC_CLI_DIR" && cd "$CC_CLI_DIR"
+          npm install --ignore-scripts --no-audit --no-fund @anthropic-ai/claude-code@2.1.212
           node node_modules/@anthropic-ai/claude-code/install.cjs
-          echo "${GITHUB_WORKSPACE}/.cc-cli/node_modules/.bin" >> "$GITHUB_PATH"
+          echo "$CC_CLI_DIR/node_modules/.bin" >> "$GITHUB_PATH"
 
       - name: Install Codex CLI
         if: steps.trigger.outputs.skip != 'true' && steps.creds.outputs.available == 'true'
         env:
           NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
         run: |
-          mkdir -p "${GITHUB_WORKSPACE}/.codex-cli" && cd "${GITHUB_WORKSPACE}/.codex-cli"
+          # Install outside the checked-out tree so a repo-root package.json
+          # can't capture this bare `npm install` and hoist it away from here.
+          CODEX_CLI_DIR="${RUNNER_TEMP}/omnigent-codex-cli"
+          mkdir -p "$CODEX_CLI_DIR" && cd "$CODEX_CLI_DIR"
           npm install --ignore-scripts --no-audit --no-fund @openai/codex@0.139.0
-          echo "${GITHUB_WORKSPACE}/.codex-cli/node_modules/.bin" >> "$GITHUB_PATH"
+          echo "$CODEX_CLI_DIR/node_modules/.bin" >> "$GITHUB_PATH"
 
       - name: Set LLM credentials
         if: steps.trigger.outputs.skip != 'true' && steps.creds.outputs.available == 'true'

.github/workflows/publish-changelog.yml

@@ -17,6 +17,11 @@ name: Publish Changelog
 # 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
 # omnigent-site — the same App used by sync-openapi-to-site.yml.
+#
+# Manual dispatch with `dry_run: true` previews only — it renders the site page
+# and prints it to the run log + job summary, mints no token, and opens no PR (so
+# it runs from a fork too). Use it to eyeball the narrative reflow before a real
+# publish.
 
 on:
   release:
@@ -27,6 +32,13 @@ on:
         description: Final release tag to (re)publish, e.g. v0.3.0
         required: true
         type: string
+      dry_run:
+        description: >-
+          Preview only: render the site page and print it to the run log +
+          job summary, but do NOT mint a token or open any PR.
+        required: false
+        type: boolean
+        default: false
 
 permissions:
   contents: read
@@ -42,6 +54,7 @@ jobs:
     outputs:
       tag: ${{ steps.r.outputs.tag }}
       is_final: ${{ steps.r.outputs.is_final }}
+      dry_run: ${{ steps.r.outputs.dry_run }}
     steps:
       - name: Resolve tag and finality
         id: r
@@ -49,41 +62,55 @@ jobs:
           EVENT_TAG: ${{ github.event.release.tag_name }}
           PRERELEASE: ${{ github.event.release.prerelease }}
           INPUT_TAG: ${{ inputs.tag }}
+          # Only a manual dispatch can request dry-run; a real published release
+          # is never a preview.
+          INPUT_DRY_RUN: ${{ inputs.dry_run }}
         run: |
           set -euo pipefail
           tag="${INPUT_TAG:-$EVENT_TAG}"
           echo "tag=${tag}" >> "$GITHUB_OUTPUT"
 
+          dry_run=false
+          [ "${INPUT_DRY_RUN}" = "true" ] && dry_run=true
+          echo "dry_run=${dry_run}" >> "$GITHUB_OUTPUT"
+
           is_final=true
-          # Only final vX.Y.Z tags; exclude rc/dev/alpha/beta and the
-          # event's prerelease flag.
+          # Only final vX.Y.Z tags; exclude rcN/devN/preN pre-releases and
+          # the event's prerelease flag.
           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 ;;
+            *rc[0-9]*|*dev[0-9]*|*pre[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"
+          echo "Resolved tag=${tag} is_final=${is_final} dry_run=${dry_run}" | tee -a "$GITHUB_STEP_SUMMARY"
 
   publish:
     name: Open release-post PR (omnigent-site)
     needs: resolve
     runs-on: ubuntu-latest
-    # Canonical repo only; skip cleanly where the App isn't configured.
+    # Canonical repo only, and only where the App is configured — EXCEPT a
+    # dry-run, which just renders + prints (no cross-repo write), so it runs
+    # anywhere (e.g. a fork) to preview the page.
     if: >-
       needs.resolve.outputs.is_final == 'true' &&
-      github.repository == 'omnigent-ai/omnigent' &&
-      vars.OMNIGENT_BOT_APP_ID != ''
+      (needs.resolve.outputs.dry_run == 'true' ||
+       (github.repository == 'omnigent-ai/omnigent' &&
+        vars.OMNIGENT_BOT_APP_ID != ''))
     env:
       TAG: ${{ needs.resolve.outputs.tag }}
+      DRY_RUN: ${{ needs.resolve.outputs.dry_run }}
       SOURCE_REPO: ${{ github.repository }}
       SITE_REPO: ${{ github.repository_owner }}/omnigent-site
       RELEASES_BRANCH: auto/releases/${{ needs.resolve.outputs.tag }}
+      OMNIGENT_SKIP_WEB_UI: "true"
+      UV_INDEX_URL: https://pypi.org/simple
+      PIP_INDEX_URL: https://pypi.org/simple
     steps:
       - name: Checkout omnigent (for the render script)
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
@@ -95,7 +122,7 @@ jobs:
         with:
           python-version: "3.11"
 
-      - name: Render the curated release body to MDX
+      - name: Read the curated release body
         working-directory: omnigent
         # The release read uses the workflow's own token (scoped to this repo);
         # only the cross-repo site write needs the App token, minted below.
@@ -110,14 +137,180 @@ jobs:
             --json body,publishedAt > /tmp/release.json
           jq -r '.body' /tmp/release.json > /tmp/release_body.md
           date="$(jq -r '.publishedAt' /tmp/release.json | cut -c1-10)"
+          echo "RELEASE_DATE=${date}" >> "$GITHUB_ENV"
+          # The site post is the narrative reflow; the raw release body is the
+          # fallback if the formatter agent is unavailable or fails.
+          cp /tmp/release_body.md /tmp/site_body.md
+
+      # --- AI reflow (primary; degrades to the raw release body) ---
+      # The GitHub Release itself is untouched — this rewrites its body into the
+      # website's narrative, prose-driven post for the site page ONLY.
+      - name: Check LLM credentials
+        id: creds
+        env:
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+        run: |
+          if [ -z "${LLM_API_KEY:-}" ]; then
+            echo "::warning::No LLM credentials — publishing the raw release body."
+            echo "available=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "::add-mask::${LLM_API_KEY}"
+            echo "available=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Build a docs index (URL + title, one per line) from the live site so the
+      # formatter can link each feature to a real /docs page — or omit the link
+      # when nothing fits. omnigent-site is public; a blobless partial + sparse
+      # checkout of app/docs pulls only the page.mdx tree, no token needed. Best
+      # effort: on any failure the index is empty and every "Learn more" is dropped.
+      - name: Build docs index
+        if: steps.creds.outputs.available == 'true'
+        env:
+          SITE_REPO: ${{ env.SITE_REPO }}
+        run: |
+          set -euo pipefail
+          : > /tmp/docs_index.txt
+          tmp="$(mktemp -d)"
+          if git clone --depth 1 --filter=blob:none --sparse \
+              "https://github.com/${SITE_REPO}.git" "$tmp" 2>/dev/null \
+             && git -C "$tmp" sparse-checkout set app/docs 2>/dev/null; then
+            python3 -u - "$tmp" <<'PYEOF'
+          import pathlib, re, sys
+          root = pathlib.Path(sys.argv[1])
+          docs = root / "app" / "docs"
+
+          def slugify(text):
+              # Mirror components/HeadingAnchors.js so #anchors resolve on the site.
+              text = text.lower()
+              text = re.sub(r"[^a-z0-9\s-]", "", text)
+              text = re.sub(r"\s+", "-", text)
+              text = re.sub(r"-+", "-", text)
+              return text.strip()
+
+          lines, pages = [], 0
+          for page in sorted(docs.rglob("page.mdx")):
+              url = "/" + page.relative_to(root).parent.as_posix().removeprefix("app/")
+              title, sections, in_fence = "", [], False
+              for ln in page.read_text(encoding="utf-8", errors="replace").splitlines():
+                  if ln.lstrip().startswith("```"):  # skip fenced code blocks
+                      in_fence = not in_fence
+                      continue
+                  if in_fence:
+                      continue
+                  m = re.match(r"(#{1,3})\s+(.*\S)", ln)  # only h1-h3 get anchors
+                  if not m:
+                      continue
+                  level, text = len(m.group(1)), m.group(2).strip()
+                  # Reduce `[label](url)` to `label`: the site slugs rendered text.
+                  text = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", text)
+                  if level == 1 and not title:
+                      title = text
+                  elif level > 1:
+                      sections.append((slugify(text), text))
+              pages += 1
+              lines.append(f"{url}\t{title}" if title else url)
+              for slug, text in sections:
+                  lines.append(f"  {url}#{slug}\t{text}")
+          pathlib.Path("/tmp/docs_index.txt").write_text("\n".join(lines) + ("\n" if lines else ""))
+          print(f"Indexed {pages} docs pages, {len(lines) - pages} sections.")
+          PYEOF
+          else
+            echo "::warning::Could not fetch omnigent-site docs — 'Learn more' links will be omitted."
+          fi
+          rm -rf "$tmp"
+
+      - name: Build formatter prompt
+        if: steps.creds.outputs.available == 'true'
+        env:
+          TAG: ${{ env.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 (MAX_ARG_STRLEN). A release body is far smaller, but
+          # cap defensively; the raw body is the fallback if the agent can't run.
+          MAX = 100_000
+          body = pathlib.Path("/tmp/release_body.md").read_text(encoding="utf-8", errors="replace")[:MAX]
+          docs = pathlib.Path("/tmp/docs_index.txt")
+          docs_index = docs.read_text(encoding="utf-8", errors="replace").strip() if docs.is_file() else ""
+          docs_block = docs_index if docs_index else "(none available — omit every \"Learn more\" line)"
+          prompt = f"""Reformat the {tag} release notes into the website post.
+
+          ## Curated GitHub Release body (rewrite this — do not add or drop facts)
+          {body}
+
+          ## Available docs pages and sections (URL <TAB> title; indented = a
+          ## #section anchor within the page above) — link features to these only
+          {docs_block}
+
+          Produce the RELEASE_POST block per your instructions."""
+          pathlib.Path("/tmp/format_prompt.txt").write_text(prompt)
+          PYEOF
+
+      # Runs the tools-less formatter and secret-scans its output; degrades to the
+      # raw release body (below) if the agent can't run. Omnigent is checked out
+      # into omnigent/, so the action's workdir is that subdir.
+      - name: Run release-post formatter
+        id: format
+        if: steps.creds.outputs.available == 'true'
+        uses: ./omnigent/.github/actions/run-omnigent-agent
+        with:
+          workdir: omnigent
+          agent: release-post-formatter
+          prompt-file: /tmp/format_prompt.txt
+          output-file: /tmp/format_out.txt
+          stderr-file: /tmp/format-stderr.log
+          gateway-base-url: ${{ secrets.GATEWAY_BASE_URL }}
+          llm-api-key: ${{ secrets.LLM_API_KEY }}
+
+      - name: Extract narrative post (fall back to raw body)
+        if: steps.creds.outputs.available == 'true'
+        run: |
+          set -euo pipefail
+          python3 -u <<'PYEOF'
+          import pathlib, re
+          raw = pathlib.Path("/tmp/format_out.txt").read_text(encoding="utf-8", errors="replace") \
+              if pathlib.Path("/tmp/format_out.txt").is_file() else ""
+          m = re.search(r"<!--\s*RELEASE_POST\s*-->(.*?)<!--\s*/RELEASE_POST\s*-->", raw, re.DOTALL)
+          post = (m.group(1).strip() if m else "")
+          if post:
+              pathlib.Path("/tmp/site_body.md").write_text(post + "\n")
+              print("Using AI-formatted narrative release post.")
+          else:
+              print("::warning::No RELEASE_POST block parsed — publishing the raw release body.")
+          PYEOF
+
+      - name: Render the release post to MDX
+        working-directory: omnigent
+        run: |
+          set -euo pipefail
           mkdir -p /tmp/site_page
           python3 .github/scripts/changelog/release_to_mdx.py \
-            --tag "$TAG" --repo "$SOURCE_REPO" --date "$date" \
-            --body-file /tmp/release_body.md \
+            --tag "$TAG" --repo "$SOURCE_REPO" --date "$RELEASE_DATE" \
+            --body-file /tmp/site_body.md \
             --out "/tmp/site_page/page.mdx"
 
+      # Dry-run stops here: print the generated page (and the intermediate
+      # narrative body) to the log and the job summary. No token is minted and no
+      # PR is opened — every step below is gated on DRY_RUN != 'true'.
+      - name: Preview rendered page (dry-run)
+        if: env.DRY_RUN == 'true'
+        run: |
+          set -euo pipefail
+          {
+            echo "## Dry-run — release post for \`${TAG}\` at \`/releases/${VERSION}\`"
+            echo "### Narrative body (pre-MDX)"
+            echo '```markdown'; cat /tmp/site_body.md; echo '```'
+            echo "### Rendered \`app/releases/${VERSION}/page.mdx\`"
+            echo '```mdx'; cat /tmp/site_page/page.mdx; echo '```'
+          } | tee -a "$GITHUB_STEP_SUMMARY"
+          echo "Dry-run: no token minted, no PR opened."
+
       - name: Mint App token (omnigent-site)
         id: app-token
+        if: env.DRY_RUN != 'true'
         uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
         with:
           app-id: ${{ vars.OMNIGENT_BOT_APP_ID }}
@@ -126,6 +319,7 @@ jobs:
           repositories: omnigent-site
 
       - name: Checkout omnigent-site (sync target)
+        if: env.DRY_RUN != 'true'
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           repository: ${{ env.SITE_REPO }}
@@ -133,6 +327,7 @@ jobs:
           path: site
 
       - name: Open or update the release-post PR (omnigent-site)
+        if: env.DRY_RUN != 'true'
         working-directory: site
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
@@ -158,7 +353,7 @@ jobs:
             echo "Release-post PR already open for ${RELEASES_BRANCH} — force-push updated it."
             exit 0
           fi
-          body="$(printf 'Publishes the **%s** release post at `/releases/%s`, mirroring the curated GitHub Release notes.\n\nGenerated by omnigent `.github/workflows/publish-changelog.yml`. Edit the GitHub Release, not this file.' "$TAG" "$VERSION")"
+          body="$(printf 'Publishes the **%s** release post at `/releases/%s` — the curated GitHub Release notes reformatted into the site'"'"'s narrative, prose-driven style.\n\nGenerated by omnigent `.github/workflows/publish-changelog.yml`. Edit the GitHub Release, not this file.' "$TAG" "$VERSION")"
           gh pr create \
             --repo "$SITE_REPO" \
             --base main \
@@ -173,6 +368,7 @@ jobs:
       # when the branch doesn't exist or carries nothing beyond main (e.g. a patch
       # release with no staged docs).
       - name: Open docs-branch → main PR (omnigent-site)
+        if: env.DRY_RUN != 'true'
         working-directory: site
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
@@ -206,3 +402,38 @@ jobs:
             --head "$DOCS_BRANCH" \
             --title "docs: publish ${VERSION%.*} docs to the live site" \
             --body "$body"
+
+      # ::add-mask:: redacts rendered logs, not artifact files — scrub the key
+      # from artifacts (incl. the unscanned stderr) before upload.
+      - name: Redact secrets from artifacts
+        if: always() && 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, pathlib
+          key = os.environ.get("LLM_API_KEY", "")
+          for f in ["/tmp/format-stderr.log", "/tmp/format_out.txt",
+                    "/tmp/format_prompt.txt", "/tmp/site_body.md"]:
+              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()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: publish-changelog-${{ env.TAG }}-${{ github.run_id }}
+          path: |
+            /tmp/format-stderr.log
+            /tmp/format_out.txt
+            /tmp/site_body.md
+          retention-days: 7
+          if-no-files-found: ignore

.github/workflows/release-omnigent.yml

@@ -71,24 +71,21 @@ jobs:
         with:
           enable-cache: false
 
-      - name: Set up Node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
-        with:
-          node-version: "20"
+      - name: Set up pnpm
+        uses: ./.github/actions/setup-pnpm
 
       # 1. Build the web UI FIRST into the package tree, clean. Ordering is
       #    load-bearing: the wheel packages on-disk files, so the bundle must
       #    exist before `uv build`. `rm -rf` backstops Vite's emptyOutDir
-      #    against stale bundles; `npm ci` installs the exact locked deps.
-      #    `--legacy-peer-deps` matches how web's lockfile is generated and
-      #    validated everywhere else (lint, e2e-ui, web-tests, the regen
-      #    jobs) — required for the React 19 peer conflict; without it `npm ci`
-      #    rejects the lockfile ("Missing: yaml@1.10.3 from lock file").
+      #    against stale bundles; `pnpm install --frozen-lockfile --filter web`
+      #    installs the exact locked deps for the web workspace package.
       - name: Build web UI (clean, fresh)
+        env:
+          NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
         run: |
           rm -rf omnigent/server/static/web-ui
-          npm --prefix web ci --legacy-peer-deps
-          npm --prefix web run build # Vite outDir -> omnigent/server/static/web-ui
+          pnpm install --frozen-lockfile --filter web
+          pnpm --filter web run build # Vite outDir -> omnigent/server/static/web-ui
 
       # 2. Tag-driven: the tag must match the version in all three pyprojects
       #    and the core package's `==` sibling-SDK pins, so the lockstep

.github/workflows/release.yml

@@ -103,13 +103,13 @@ jobs:
           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
+          # Final X.Y.Z or a PEP 440 pre-release (rc). No dev/post/alpha/beta here.
+          if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(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
+          case "$VERSION" in *rc[0-9]*) prerelease=true ;; esac
           {
             echo "version=${VERSION}"
             echo "tag=v${VERSION}"
@@ -182,8 +182,24 @@ jobs:
           BASE_SHA: ${{ steps.state.outputs.base_sha }}
         run: |
           set -euo pipefail
+          # This gate is meta-CI, not CI itself. Every job this Release workflow
+          # spawns (plan, benchmark, cut, bump-main, …) leaves a check-run on
+          # the base commit; a single premature failure on a prior dispatch
+          # would otherwise poison the SHA and block every retry in a
+          # self-sustaining loop. Exclude *all* check-runs that belong to a run
+          # of this workflow, identified by run ID in details_url — not by job
+          # name, so a real nightly `benchmark` regression (different workflow)
+          # is still gated.
+          own_runs="$(gh api "repos/${GITHUB_REPOSITORY}/actions/workflows/release.yml/runs?head_sha=${BASE_SHA}&per_page=100&status=completed" \
+            --jq '.workflow_runs[].id' 2>/dev/null | paste -sd, -)"
           runs="$(gh api "repos/${GITHUB_REPOSITORY}/commits/${BASE_SHA}/check-runs?per_page=100" \
-            --paginate --jq '.check_runs[] | [.name, .status, .conclusion // "-"] | @tsv')"
+            --paginate --jq '.check_runs[] | [.name, .status, .conclusion // "-", .details_url] | @tsv')"
+          # Drop check-runs whose details_url references one of this
+          # workflow's own runs (e.g. .../actions/runs/<id>/job/<id>).
+          runs="$(printf '%s' "$runs" | awk -F'\t' -v rel="$own_runs" '
+            BEGIN { n=split(rel, a, ","); for (i=1; i<=n; i++) if (a[i]!="") runs[a[i]]=1 }
+            { own=0; for (r in runs) if (index($4, "/runs/" r "/")) { own=1; break }
+              if (!own) print $1 "\t" $2 "\t" $3 }')"
           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
@@ -230,18 +246,20 @@ jobs:
             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:
+  # Seed the corpus at the OLDER release's schema head so both servers can
+  # boot: the baseline (older code) reads it natively, and the candidate (newer
+  # code) auto-migrates it forward on startup. Migrations are forward-only, so
+  # seeding at the newer schema would leave a DB the older code can't read.
+  # The seeded bench.db is passed to baseline + candidate as an artifact so
+  # they run in parallel on separate runners (each migrates/reads its own copy).
+  benchmark-seed:
     needs: [authorize, plan]
     if: ${{ !inputs.dry_run && needs.plan.outputs.already_done != 'true' && !inputs.skip_benchmark }}
     outputs:
-      regression: ${{ steps.compare.outputs.regression }}
+      prev_tag: ${{ steps.prev.outputs.tag }}
+      has_prev: ${{ steps.prev.outputs.found }}
     runs-on: ubuntu-latest
-    timeout-minutes: 60
+    timeout-minutes: 20
     env:
       OMNIGENT_SKIP_WEB_UI: "true"
       UV_INDEX_URL: https://pypi.org/simple
@@ -251,7 +269,6 @@ jobs:
         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
 
@@ -265,40 +282,8 @@ jobs:
         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: Install dependencies
+        run: uv sync --extra dev
 
       - name: Find previous stable release tag
         id: prev
@@ -317,20 +302,188 @@ jobs:
             echo "tag=${PREV_TAG}" >> "$GITHUB_OUTPUT"
           fi
 
-      - name: Benchmark previous release (${{ steps.prev.outputs.tag }})
+      # Seed at the OLDER schema head so both servers can boot. When there is
+      # no previous release (first cut) seed at the current schema instead.
+      - name: Seed at previous release schema
         if: steps.prev.outputs.found == 'true'
         run: |
           git checkout "${{ steps.prev.outputs.tag }}"
           uv sync --extra dev
+          uv run --no-sync dev/benchmarks/omnigent/seed.py \
+            --database-uri "sqlite:///bench.db" \
+            --sessions 5000 --items-per-session 200
+
+      - name: Seed at current schema (no previous release)
+        if: steps.prev.outputs.found != 'true'
+        run: |
+          uv run --no-sync dev/benchmarks/omnigent/seed.py \
+            --database-uri "sqlite:///bench.db" \
+            --sessions 5000 --items-per-session 200
+
+      - name: Upload seeded corpus
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: bench-db-${{ github.run_id }}
+          path: bench.db
+          retention-days: 1
+          if-no-files-found: error
+
+  # Benchmark the previous release. Skipped on the first cut (no prev tag).
+  benchmark-baseline:
+    needs: [benchmark-seed]
+    if: ${{ needs.benchmark-seed.outputs.has_prev == 'true' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      OMNIGENT_SKIP_WEB_UI: "true"
+      UV_INDEX_URL: https://pypi.org/simple
+      PIP_INDEX_URL: https://pypi.org/simple
+    steps:
+      - name: Check out previous release
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ needs.benchmark-seed.outputs.prev_tag }}
+          persist-credentials: false
+
+      - name: Download seeded corpus
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: bench-db-${{ github.run_id }}
+          path: .
+
+      - 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
+
+      - name: Run baseline benchmark
+        run: |
           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 -
+          echo "Baseline benchmark complete." | tee -a "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload baseline results
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: baseline-results-${{ github.run_id }}
+          path: baseline.json
+          retention-days: 7
+          if-no-files-found: error
+
+  # Benchmark the release candidate. Always runs (even on first cut, solo).
+  benchmark-candidate:
+    needs: [authorize, plan, benchmark-seed]
+    if: ${{ !inputs.dry_run && needs.plan.outputs.already_done != 'true' && !inputs.skip_benchmark }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    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 }}
+          persist-credentials: false
+
+      - name: Download seeded corpus
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: bench-db-${{ github.run_id }}
+          path: .
+
+      - 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
+
+      # The seeded bench.db is at the previous release's schema head. The
+      # candidate (newer code) auto-migrates on server boot, but the z7
+      # binary-UUID conversion is a per-row Python loop over ~1M items that
+      # takes >90s — longer than the benchmark harness's health-check window.
+      # Pre-migrate explicitly so the server boots against an already-current DB.
+      - name: Migrate corpus to release-base schema
+        run: |
+          uv run --no-sync omni debug db-upgrade "sqlite:///bench.db"
+          echo "Corpus migrated to release-base schema head." | tee -a "$GITHUB_STEP_SUMMARY"
+
+      - name: Run candidate benchmark
+        run: |
+          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: Upload candidate results
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: candidate-results-${{ github.run_id }}
+          path: candidate.json
+          retention-days: 7
+          if-no-files-found: error
+
+  # Compare baseline vs candidate. Downloaded as artifacts from the parallel
+  # jobs. A detected regression surfaces as an output flag that gates the
+  # benchmark-approve job (requiring manual sign-off) rather than failing
+  # outright. Skipped on the first cut (no baseline).
+  benchmark:
+    needs: [authorize, plan, benchmark-seed, benchmark-baseline, benchmark-candidate]
+    if: ${{ !inputs.dry_run && needs.plan.outputs.already_done != 'true' && !inputs.skip_benchmark && needs.benchmark-seed.outputs.has_prev == 'true' }}
+    outputs:
+      regression: ${{ steps.compare.outputs.regression }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    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 }}
+          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
+
+      - name: Download results
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: "{baseline,candidate}-results-${{ github.run_id }}"
+          merge-multiple: true
+          path: .
 
       - name: Compare results
         id: compare
-        if: steps.prev.outputs.found == 'true'
         run: |
           set +e
           uv run --no-sync dev/benchmarks/omnigent/compare.py \
@@ -340,11 +493,9 @@ jobs:
             --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 }}"
           {
@@ -359,10 +510,10 @@ jobs:
             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_"
+            echo "_Candidate vs ${{ needs.benchmark-seed.outputs.prev_tag }} · 100 iterations × 3 runs · SQLite · threshold 100% on P50/P95_"
           } >> "$GITHUB_STEP_SUMMARY"
 
-      - name: Upload benchmark artifacts
+      - name: Upload comparison artifacts
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         if: always()
         with:
@@ -370,6 +521,7 @@ jobs:
           path: |
             candidate.json
             baseline.json
+            comparison.md
           retention-days: 90
           if-no-files-found: ignore
 
@@ -383,6 +535,7 @@ jobs:
       !inputs.dry_run &&
       needs.plan.outputs.already_done != 'true' &&
       !inputs.skip_benchmark &&
+      needs.benchmark.result == 'success' &&
       needs.benchmark.outputs.regression == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 60
@@ -394,8 +547,12 @@ jobs:
 
   # 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' }}
+    needs: [authorize, plan, benchmark-candidate, benchmark, benchmark-approve]
+    # benchmark (compare) + benchmark-approve are skipped on the first cut (no
+    # previous release to compare against); benchmark-candidate always runs and
+    # is the real gate. `!cancelled` lets the optional compare/approve jobs be
+    # skipped without blocking, while still failing the run if they actually fail.
+    if: ${{ !inputs.dry_run && needs.plan.outputs.already_done != 'true' && !cancelled() }}
     runs-on: ubuntu-latest
     timeout-minutes: 15
     env:
@@ -490,7 +647,7 @@ jobs:
             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."
+              echo "2. Validate the rc from PyPI (see RELEASING.md). No GitHub release is created for rc tags (rcs live on PyPI only) — skip straight to the next rc or the final cut."
             else
               echo "2. Merge the CHANGELOG PR, curate the ${TAG} draft notes, then dispatch finalize-release.yml (tag=${TAG})."
             fi
@@ -500,7 +657,6 @@ jobs:
   # 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:
@@ -510,8 +666,24 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
           VERSION: ${{ needs.plan.outputs.version }}
+          DRY_RUN: ${{ inputs.dry_run }}
+          BRANCH_EXISTS: ${{ needs.plan.outputs.branch_exists }}
         run: |
           set -euo pipefail
+          # Gate in shell, not a job-level `if`: a CLI/API dispatch delivers
+          # boolean inputs as the STRING "false", which is truthy in an
+          # expression, so `!inputs.dry_run` silently skipped this job at the
+          # v0.7.0 cut. Shell string comparison is dispatch-channel-proof and
+          # logs its decision instead of vanishing from the run.
+          if [ "$DRY_RUN" = "true" ]; then
+            echo "Dry run — not dispatching the main bump." | tee -a "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+          if [ "$BRANCH_EXISTS" != "false" ]; then
+            echo "Release branch pre-existed (not the first cut of this cycle) — main bump not needed." \
+              | tee -a "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
           # 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.

.github/workflows/rerun-ci.yml

@@ -0,0 +1,134 @@
+# A contributor comments `/rerun` on a PR to re-run its failed CI **on the
+# existing head commit** -- no empty commit, no rebase, so no push event and
+# thus no dismissed approvals (branch protection keeps dismiss-stale-reviews
+# on to block approve-then-swap). Use for flaky-test recovery instead of
+# pushing a throwaway commit to re-trigger checks.
+#
+# CI here runs entirely against the in-process mock LLM (no gateway spend), so
+# a re-run costs only Actions minutes; `cancel-in-progress` on each suite caps
+# concurrent burn. Polly AI Review (the one real-LLM path) is gated by
+# maintainer approval elsewhere and is intentionally NOT re-run here.
+#
+# Authorization: the PR author (so fork contributors can re-run their own PR)
+# OR a write-access commenter (OWNER/MEMBER/COLLABORATOR). `issue_comment` runs
+# from the base repo, so its token is writable even for fork PRs and is not
+# held behind the fork-approval gate -- unlike `pull_request_target`, this
+# needs no privileged `workflow_run` relay (cf. rerun-security-gate*.yml).
+name: Rerun CI on /rerun comment
+
+on:
+  issue_comment:
+    types: [created]
+
+# Read-only at the top level; write scopes live on the job below.
+permissions:
+  contents: read
+
+concurrency:
+  # One re-run in flight per PR; a second `/rerun` supersedes the first.
+  group: rerun-ci-${{ github.event.issue.number }}
+  cancel-in-progress: false
+
+jobs:
+  rerun:
+    name: Re-run failed CI for the PR head
+    permissions:
+      actions: write        # gh run rerun
+      pull-requests: read   # resolve the PR head SHA
+      issues: write         # react to the comment + post the result
+    # PR comment, body starts with `/rerun`, not a bot, in this repo, AND the
+    # commenter is the PR author or has write access. `issue.user.login` is the
+    # PR author; `comment.user.login` is the commenter.
+    if: >-
+      github.repository == 'omnigent-ai/omnigent'
+      && github.event.issue.pull_request != null
+      && startsWith(github.event.comment.body, '/rerun')
+      && !endsWith(github.actor, '[bot]')
+      && (
+        github.event.comment.author_association == 'OWNER'
+        || github.event.comment.author_association == 'MEMBER'
+        || github.event.comment.author_association == 'COLLABORATOR'
+        || github.event.comment.user.login == github.event.issue.user.login
+      )
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      # The job `if` startsWith() also matches `/rerunfoo`; re-validate `/rerun`
+      # as a command (first non-space token is exactly `/rerun`, optional args).
+      - name: Validate command
+        id: cmd
+        env:
+          COMMENT_BODY: ${{ github.event.comment.body }}
+        run: |
+          if ! grep -qE '^[[:space:]]*/rerun([[:space:]]|$)' <<<"$COMMENT_BODY"; then
+            echo "::notice::Comment mentions '/rerun' but not as a command; skipping."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Acknowledge
+        if: steps.cmd.outputs.skip != 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          COMMENT_ID: ${{ github.event.comment.id }}
+        run: |
+          gh api "repos/$REPO/issues/comments/$COMMENT_ID/reactions" \
+            -f content=eyes --silent || true
+
+      - name: Re-run failed CI runs for the PR head
+        if: steps.cmd.outputs.skip != 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          # Integer from the payload, but sanitised to digits before shell use.
+          PR_NUMBER: ${{ github.event.issue.number }}
+        run: |
+          set -euo pipefail
+          PR_NUMBER="$(tr -dc '0-9' <<<"$PR_NUMBER")"
+          [ -n "$PR_NUMBER" ] || { echo "::error::Empty PR number."; exit 1; }
+
+          # Resolve the PR's CURRENT head SHA (a push could have superseded any
+          # SHA recorded at comment time).
+          SHA="$(gh api "repos/$REPO/pulls/$PR_NUMBER" --jq '.head.sha')"
+          echo "PR #$PR_NUMBER head $SHA"
+
+          # Latest run per workflow for this SHA, restricted to `pull_request`
+          # events -- this is the test-suite set (CI, Lint, E2E, E2E UI,
+          # Integration, Docker build, web Tests). It deliberately EXCLUDES the
+          # merge machinery (Merge Ready, Maintainer Approval, Polly) which run
+          # on pull_request_target / workflow_run / issue_comment, so `/rerun`
+          # never re-triggers a gate or the real-LLM review.
+          mapfile -t FAILED < <(
+            gh api "repos/$REPO/actions/runs?head_sha=$SHA&per_page=100" --paginate \
+              --jq '[.workflow_runs[] | select(.event=="pull_request")]
+                    | group_by(.name)
+                    | map(sort_by(.created_at) | last)
+                    | .[] | select(.conclusion=="failure")
+                    | "\(.id)\t\(.name)"'
+          )
+
+          if [ "${#FAILED[@]}" -eq 0 ]; then
+            echo "No failed pull_request CI runs for $SHA."
+            gh pr comment "$PR_NUMBER" --repo "$REPO" \
+              --body "🔁 \`/rerun\`: no failed CI runs on the current head (\`${SHA:0:7}\`) to re-run. If a check is stuck *pending*, it needs a push or a maintainer, not a re-run."
+            exit 0
+          fi
+
+          RERAN=""
+          while IFS=$'\t' read -r id name; do
+            [ -n "$id" ] || continue
+            echo "• Re-running failed jobs in '$name' (run $id)"
+            # --failed: re-run only the failed jobs (cheapest path for a flake).
+            # --repo is REQUIRED: this job has no checkout, so `gh run rerun`
+            # cannot infer the repo from a git remote and would fail client-side.
+            if gh run rerun "$id" --repo "$REPO" --failed; then
+              RERAN="$RERAN"$'\n'"- $name"
+            else
+              echo "::warning::Could not re-run '$name' (run $id) -- may be in progress."
+              RERAN="$RERAN"$'\n'"- $name ⚠️ (skipped: already running or not re-runnable)"
+            fi
+          done < <(printf '%s\n' "${FAILED[@]}")
+
+          NOTE="The \`Merge Ready\` gate re-evaluates automatically when these complete."
+          gh pr comment "$PR_NUMBER" --repo "$REPO" \
+            --body "🔁 \`/rerun\`: re-running failed jobs on \`${SHA:0:7}\`:${RERAN}"$'\n\n'"$NOTE"

.github/workflows/review-sla.yml

@@ -1,18 +1,16 @@
 name: Reviewer SLA
 
-# Daily (weekday) sweep that enforces a 5-working-day reviewer SLA: any open PR
+# Manual-only sweep that enforces a 5-working-day reviewer SLA: any open PR
 # awaiting review from a maintainer -- or open issue awaiting a maintainer
 # assignee -- with no reply in 5 working days gets the assignee re-pinged in a
 # comment plus a second reviewer (PR) / second assignee (issue), then a one-shot
 # `review-sla-escalated` label so it's never nudged twice. All logic + safety
 # notes live in review-sla.js (offline unit test: review-sla.test.js).
 #
-# Scheduled -> runs on the trusted default branch with the repo GITHUB_TOKEN; it
-# reads no PR-authored code, only .github/ config + the issues/PRs API.
+# Runs on the trusted default branch with the repo GITHUB_TOKEN; it reads no
+# PR-authored code, only .github/ config + the issues/PRs API.
 
 on:
-  schedule:
-    - cron: "0 8 * * 1-5" # 08:00 UTC, Mon-Fri (weekday SLA -> no weekend pings)
   workflow_dispatch:
 
 permissions:

.github/workflows/security-triage.yml

@@ -195,10 +195,14 @@ jobs:
         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
+          # Install outside the checked-out tree: a repo-root package.json would
+          # otherwise capture this bare `npm install` and hoist it there, leaving
+          # this dir's node_modules empty.
+          CC_CLI_DIR="${RUNNER_TEMP}/omnigent-cc-cli"
+          mkdir -p "$CC_CLI_DIR" && cd "$CC_CLI_DIR"
+          npm install --ignore-scripts --no-audit --no-fund @anthropic-ai/claude-code@2.1.212
           node node_modules/@anthropic-ai/claude-code/install.cjs
-          echo "${GITHUB_WORKSPACE}/.cc-cli/node_modules/.bin" >> "$GITHUB_PATH"
+          echo "$CC_CLI_DIR/node_modules/.bin" >> "$GITHUB_PATH"
 
       - name: Write gateway profile (~/.databrickscfg)
         if: steps.creds.outputs.available == 'true'

.github/workflows/server-compat.yml

@@ -4,7 +4,7 @@ name: Backwards-Compat
 # suites, over the FULL pairwise (server, runner) version matrix.
 #
 # The version universe is `main` (the checked-out code = client + tests, always)
-# plus every non-rc release tag; we cross every server version with every runner
+# plus every final (non-prerelease) release tag; we cross every server version with every runner
 # version. Each cell pins the server and/or runner subprocess to that build
 # (a "main" axis value leaves that component on the checked-out code) while the
 # client and tests stay on main. The (main, main) cell is omitted — it pins
@@ -18,13 +18,13 @@ name: Backwards-Compat
 #
 # Triggers:
 #   workflow_dispatch   manual; optional `versions` CSV overrides the set.
-#   schedule            every 12h; full pairwise over main + all non-rc tags.
+#   schedule            every 12h; full pairwise over main + all final tags.
 
 on:
   workflow_dispatch:
     inputs:
       versions:
-        description: "Comma-separated version set for BOTH axes (e.g. 'main,v0.2.0'). Empty = main + all non-rc tags."
+        description: "Comma-separated version set for BOTH axes (e.g. 'main,v0.2.0'). Empty = main + all final (non-prerelease) tags."
         required: false
         default: ""
   schedule:

.github/workflows/ui-preview.yml

@@ -106,7 +106,7 @@ jobs:
       - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39  # v8.2.0
         with:
           enable-cache: true
-      - uses: ./.github/actions/setup-node
+      - uses: ./.github/actions/setup-pnpm
 
       - name: Build wheels (no UI)
         # Build the wheels WITHOUT the SPA so they stay small (Databricks Apps
@@ -120,10 +120,11 @@ jobs:
         run: bash deploy/databricks/build.sh
 
       - name: Build UI
-        working-directory: web
+        env:
+          NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
         run: |
-          npm ci --legacy-peer-deps --no-audit --no-fund
-          npm run build
+          pnpm install --frozen-lockfile --filter web
+          pnpm --filter web run build
 
       - name: Package UI assets
         run: |

.github/workflows/ui-snapshot-update.yml

@@ -80,8 +80,18 @@ jobs:
           ref: ${{ github.event.pull_request.head.ref }}
           persist-credentials: false
 
-      - name: Set up Node 20
-        uses: ./.github/actions/setup-node
+      # The pinned Playwright image doesn't ship Node, so install Node before
+      # the pnpm action (pnpm/action-setup's self-installer needs a Node binary).
+      - name: Set up Node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: "22"
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+        with:
+          version: 11.15.1
+          standalone: true
 
       - name: Install uv
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39  # v8.2.0
@@ -106,9 +116,8 @@ jobs:
         env:
           NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
         run: |
-          cd web
-          npm ci --legacy-peer-deps --no-audit --no-fund
-          npm run build
+          pnpm install --frozen-lockfile --filter web
+          pnpm --filter web run build
 
       - name: Compare the baselines (no --update-snapshots)
         # Deliberately NOT --update-snapshots: that rewrites EVERY PNG, churning

.github/workflows/ui-snapshot.yml

@@ -95,7 +95,7 @@ jobs:
           if ! files=$(gh api "repos/$REPO/pulls/$PR/files" --paginate --jq '.[].filename'); then
             echo "ui=true" >> "$GITHUB_OUTPUT"; echo "file list unavailable -> render"; exit 0
           fi
-          pattern='^(web/|tests/e2e_ui/visual/|tests/e2e_ui/conftest\.py|\.github/actions/setup-node/|\.github/workflows/ui-snapshot\.yml|pyproject\.toml|uv\.lock)'
+          pattern='^(web/|tests/e2e_ui/visual/|tests/e2e_ui/conftest\.py|\.github/actions/setup-pnpm/|\.github/workflows/ui-snapshot\.yml|pnpm-lock\.yaml|pnpm-workspace\.yaml|pyproject\.toml|uv\.lock)'
           if printf '%s\n' "$files" | grep -qE "$pattern"; then
             echo "ui=true" >> "$GITHUB_OUTPUT"
             echo "render-affecting files changed:"
@@ -106,7 +106,7 @@ jobs:
           fi
 
   ui-snapshot:
-    name: UI Snapshot (visual baselines) [non-blocking]
+    name: UI Snapshot (visual baselines)
     needs: detect
     # Skipped (not failed) when no render input changed -> reports SUCCESS, so a
     # non-UI PR neither runs the render nor blocks a required check.
@@ -130,8 +130,18 @@ jobs:
         with:
           ref: ${{ github.event.inputs.ref || github.ref }}
 
-      - name: Set up Node 20
-        uses: ./.github/actions/setup-node
+      # The pinned Playwright image doesn't ship Node, so install Node before
+      # the pnpm action (pnpm/action-setup's self-installer needs a Node binary).
+      - name: Set up Node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: "22"
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+        with:
+          version: 11.15.1
+          standalone: true
 
       - name: Install uv
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39  # v8.2.0
@@ -156,14 +166,12 @@ jobs:
 
       - name: Build web SPA
         # Build BEFORE pytest: Vite's emptyOutDir clobbers the static dir, so
-        # never run it alongside the live server. --legacy-peer-deps avoids
-        # re-resolving the known React 19 peer conflict under @emoji-mart/react.
+        # never run it alongside the live server.
         env:
           NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
         run: |
-          cd web
-          npm ci --legacy-peer-deps --no-audit --no-fund
-          npm run build
+          pnpm install --frozen-lockfile --filter web
+          pnpm --filter web run build
 
       - name: Compare (PR) or regenerate (dispatch) the visual snapshots
         id: snapshot

.github/workflows/update-homebrew.yml

@@ -15,11 +15,21 @@
 # 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).
+#
+# brew resolves resources through pip's `--uploaded-prior-to=P1D` window, so a
+# run within 24h of the PyPI upload cannot see the new sdist and used to go
+# red every release day (v0.6.0, v0.7.0). Now: runs inside that window defer
+# (green, with a warning), and the nightly `schedule` catch-up — which targets
+# the latest published release and no-ops when the formula is already
+# current — opens the tap PR once the window has passed.
 name: Update Homebrew tap
 
 on:
   release:
     types: [published]
+  schedule:
+    # Nightly catch-up for the P1D window (see header). No-ops when current.
+    - cron: "45 23 * * *"
   workflow_dispatch:
     inputs:
       tag:
@@ -31,7 +41,7 @@ permissions:
   contents: read
 
 concurrency:
-  group: update-homebrew-${{ github.event.release.tag_name || inputs.tag }}
+  group: update-homebrew-${{ github.event.release.tag_name || inputs.tag || 'nightly' }}
   cancel-in-progress: false
 
 jobs:
@@ -46,12 +56,18 @@ jobs:
       - name: Resolve tag and finality
         id: r
         env:
+          GH_TOKEN: ${{ github.token }}
           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}"
+          if [ -z "$tag" ]; then
+            # Scheduled catch-up: target the latest published final release
+            # (empty when the repo has none yet — resolves to is_final=false).
+            tag="$(gh api "repos/${GITHUB_REPOSITORY}/releases/latest" --jq .tag_name 2>/dev/null || echo "")"
+          fi
           is_final=true
           case "$tag" in
             v[0-9]*.[0-9]*.[0-9]*) ;;
@@ -145,12 +161,29 @@ jobs:
           path: tap
           persist-credentials: false
 
+      - name: Skip when the formula is already at this version
+        id: current
+        working-directory: tap
+        env:
+          VERSION: ${{ steps.sdist.outputs.version }}
+        run: |
+          set -euo pipefail
+          # Nightly catch-up no-op: the stable url already points at this sdist.
+          if grep -q "omnigent-${VERSION}\.tar\.gz" Formula/omnigent.rb; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "Formula already at ${VERSION} — nothing to do." | tee -a "$GITHUB_STEP_SUMMARY"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Set up Homebrew
+        if: steps.current.outputs.skip != 'true'
         uses: Homebrew/actions/setup-homebrew@18fcb8e3e06b4247c676c506750dc95ea7226479 # 2026-07-10
         with:
           token: ${{ github.token }}
 
       - name: Rewrite the formula's stable url/sha256
+        if: steps.current.outputs.skip != 'true'
         working-directory: tap
         env:
           SDIST_URL: ${{ steps.sdist.outputs.url }}
@@ -172,9 +205,12 @@ jobs:
           git diff --stat
 
       - name: Regenerate the pinned Python resources
+        id: regen
+        if: steps.current.outputs.skip != 'true'
         env:
           HOMEBREW_NO_AUTO_UPDATE: "1"
           HOMEBREW_NO_INSTALL_FROM_API: "1"
+          GH_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
           # Make the checkout visible to brew as the real tap.
@@ -185,12 +221,31 @@ jobs:
           # deps (certifi/cryptography/pydantic/rpds-py and their transitive
           # cffi/pycparser) and the platform-conditional google-antigravity
           # wheel stanzas.
-          brew update-python-resources \
+          if ! brew update-python-resources \
             --exclude-packages=certifi,cryptography,pydantic,rpds-py,cffi,pycparser,google-antigravity \
-            omnigent-ai/tap/omnigent
+            omnigent-ai/tap/omnigent; then
+            # brew resolves through pip's --uploaded-prior-to=P1D window: a
+            # release <24h old is invisible and resolution ALWAYS fails. Defer
+            # to the nightly catch-up instead of going red; older releases are
+            # real failures.
+            published_at="$(gh api "repos/${GITHUB_REPOSITORY}/releases/tags/${TAG}" --jq .published_at 2>/dev/null || echo "")"
+            age_h=999
+            if [ -n "$published_at" ]; then
+              age_h="$(python3 -c 'import datetime, sys; d = datetime.datetime.fromisoformat(sys.argv[1].replace("Z", "+00:00")); print(int((datetime.datetime.now(datetime.timezone.utc) - d).total_seconds() // 3600))' "$published_at")"
+            fi
+            if [ "$age_h" -lt 24 ]; then
+              echo "deferred=true" >> "$GITHUB_OUTPUT"
+              echo "::warning::Resource resolution failed with ${TAG} only ${age_h}h old — inside pip's --uploaded-prior-to=P1D window. The nightly catch-up will open the tap PR."
+              echo "Deferred to the nightly catch-up (${TAG} is ${age_h}h old, inside the 24h PyPI window)." >> "$GITHUB_STEP_SUMMARY"
+              exit 0
+            fi
+            exit 1
+          fi
+          echo "deferred=false" >> "$GITHUB_OUTPUT"
           brew style omnigent-ai/tap/omnigent
 
       - name: Assert the hand-maintained sections survived
+        if: steps.current.outputs.skip != 'true' && steps.regen.outputs.deferred != 'true'
         working-directory: tap
         run: |
           set -euo pipefail
@@ -214,6 +269,7 @@ jobs:
           done
 
       - name: Open or update the tap bump PR
+        if: steps.current.outputs.skip != 'true' && steps.regen.outputs.deferred != 'true'
         working-directory: tap
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}

.github/workflows/vscode-extension-release.yml

@@ -68,15 +68,16 @@ jobs:
         with:
           ref: release/vscode-v${{ inputs.version }}
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
-        with:
-          node-version: "20"
+      - name: Set up pnpm
+        uses: ./.github/actions/setup-pnpm
 
       - name: Install, build, and package
+        env:
+          NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
         run: |
-          npm ci
-          npm run build
-          npm run package
+          pnpm install --frozen-lockfile --filter omnigent-vscode
+          pnpm --filter omnigent-vscode run build
+          pnpm --filter omnigent-vscode run package
 
       - name: Resolve tag and verify package.json version
         id: meta

.github/workflows/vscode-release-pr.yml

@@ -62,6 +62,9 @@ jobs:
           fetch-depth: 0
           fetch-tags: true
 
+      - name: Set up pnpm
+        uses: ./.github/actions/setup-pnpm
+
       - name: Validate version
         env:
           VERSION: ${{ inputs.version }}
@@ -80,10 +83,10 @@ jobs:
         working-directory: editors/vscode
         env:
           VERSION: ${{ inputs.version }}
-        # `npm pkg set` edits ONLY package.json (unlike `npm version`, which also
-        # rewrites package-lock.json). Keeps the release PR to package.json +
+        # `pnpm pkg set` edits ONLY package.json (unlike `pnpm version`, which
+        # also rewrites the lockfile). Keeps the release PR to package.json +
         # CHANGELOG.md.
-        run: npm pkg set version="$VERSION"
+        run: pnpm pkg set version="$VERSION"
 
       - name: Add the CHANGELOG section (placeholder)
         working-directory: editors/vscode

.github/workflows/waiting-on-author-test.yml

@@ -0,0 +1,31 @@
+name: Waiting on Author Test
+
+# Offline unit test for waiting-on-author hygiene. Runs on PR head without
+# secrets or network and only when the workflow logic changes.
+
+on:
+  pull_request:
+    paths:
+      - .github/scripts/waiting_on_author.py
+      - .github/scripts/waiting_on_author_test.py
+      - .github/workflows/waiting-on-author.yml
+      - .github/workflows/waiting-on-author-test.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: waiting-on-author-test-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - name: Run waiting-on-author unit test
+        run: python3 .github/scripts/waiting_on_author_test.py

.github/workflows/waiting-on-author.yml

@@ -0,0 +1,46 @@
+name: Waiting on Author Hygiene
+
+# Keeps the `waiting-on-author` PR label actionable: author activity clears it,
+# and PRs that sit in that state for 7 days are closed. The workflow runs from
+# trusted default-branch code and never checks out PR-authored files.
+
+on:
+  pull_request_target:
+    types: [synchronize]
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  pull_request_review:
+    types: [submitted]
+  schedule:
+    - cron: "0 */12 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: waiting-on-author-${{ github.event.pull_request.number || github.event.issue.number || github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  hygiene:
+    if: github.repository == 'omnigent-ai/omnigent'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Check out .github
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          sparse-checkout: .github
+          persist-credentials: false
+      - name: Update waiting-on-author state
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: python3 .github/scripts/waiting_on_author.py

.github/workflows/web-tests.yml

@@ -24,14 +24,14 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  # Security precondition gate: npm ci/test runs the PR's own install hooks and
+  # Security precondition gate: pnpm install/test runs the PR's own install hooks and
   # test code, so untrusted PRs are held until the scan passes (security-gate.yml).
   # Trusted authors and non-PR events pass through.
   gate:
     uses: ./.github/workflows/security-gate.yml
 
-  npm-test:
-    name: npm test
+  web-test:
+    name: web test
     needs: gate
     if: ${{ !github.event.pull_request.draft }}
     runs-on: ubuntu-latest
@@ -41,31 +41,29 @@ jobs:
       - name: Check out repo
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
 
-      - name: Set up Node.js
-        uses: ./.github/actions/setup-node
+      - name: Set up pnpm
+        uses: ./.github/actions/setup-pnpm
 
       - name: Install dependencies
-        working-directory: web
-        # Pin the npm registry to the npmjs default.
+        # Pin the npm registry to the npmjs default; limit to the web package
+        # so the Electron package's large native devDependencies are not fetched.
         env:
           NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
-        run: npm ci --legacy-peer-deps
+        run: pnpm install --frozen-lockfile --filter web
 
       - name: Check formatting
-        working-directory: web
-        run: npm run format:check
+        run: pnpm --filter web run format:check
 
       - name: Run tests with coverage
-        working-directory: web
-        run: npm run test:coverage
+        run: pnpm --filter web run test:coverage
 
       # Distill the v8 json-summary into a single total.txt, mirroring the
       # backend's coverage-report job. ui-code-coverage.yml (privileged
       # workflow_run) consumes this artifact and posts the report-only status.
       - name: Summarize coverage
         if: always()
-        working-directory: web
         run: |
+          cd web
           mkdir -p ui-coverage-summary
           if [[ ! -f coverage/coverage-summary.json ]]; then
             echo "::warning::No coverage-summary.json; skipping UI coverage report."

.gitignore

@@ -2,6 +2,8 @@
 build/
 dist/
 node_modules/
+.pnpm-store/
+.pnpm-debug.log*
 reviews/
 
 # Generated artifact; never committed.
@@ -57,6 +59,7 @@ dev/omnidev/target/
 
 # Playwright test run output (screenshots, traces, videos).
 test-results/
+output/playwright/
 
 # Visual-snapshot failure output (actual/expected/diff PNGs from the UI diff
 # gate). Regenerated each run; only the baseline under

.pre-commit-config.yaml

@@ -36,10 +36,17 @@ repos:
         types: [python]
         files: ^tests/
 
+      - id: no-hardcoded-models
+        name: no new hardcoded LLM model ids
+        language: system
+        entry: .venv/bin/python dev/lint/lint_no_hardcoded_models.py
+        pass_filenames: false
+        files: ^((omnigent|scripts|examples|\.github|dev/lint)/.*\.(py|ya?ml|json|toml|sh)|dev/lint/hardcoded_model_allowlist\.txt)$
+
       - id: web-prettier
         name: web prettier
         language: system
-        entry: npm --prefix web exec -- prettier --write
+        entry: bash -c 'test -x web/node_modules/.bin/prettier && web/node_modules/.bin/prettier --write "$@"' --
         files: ^web/.*\.(css|html|js|jsx|json|md|mdx|ts|tsx|yaml|yml)$
         # Exclude generated assets: web-ui build output, Xcode asset catalogs,
         # and Apple Icon Composer `.icon` bundles (machine-formatted; prettier

AGENTS.md

@@ -9,6 +9,17 @@ Run the `pre-commit` hook before committing (`pre-commit run --all-files`, or
 let it run on staged files via `git commit`). Fix any issues it reports so the
 commit lands clean — CI runs the same checks.
 
+## Local development shortcuts
+
+Use `just` for common tasks; run `just --list` for grouped recipes.
+
+- `just ensure` — install/check prerequisites
+- `just run-ios` / `just run-android` — build/run mobile apps
+- `just dev` / `just dev-mobile` — start the omnigent dev pod
+- `just electron-dev` / `just electron-build` — Electron desktop shell
+- `just lint` / `just lint-all` — run pre-commit
+- `just normalize-locks` — rewrite lockfile registries to PyPI/npmjs.org
+
 ## Pull requests
 
 When you open a pull request, fill in the repo's PR template at
@@ -30,6 +41,20 @@ Generate the description from the actual diff and this session's context — lea
 with the motivation, then the change. Don't pass a `--body` that skips these
 sections.
 
+## Finishing a task
+
+When you finish a task, print instructions to the user on how to test it: the
+commands to run, the inputs to provide, or the steps to reproduce so they can
+verify the result themselves. Don't leave the user guessing how to confirm the
+work — tell them exactly what to do.
+
+## Deprecating features
+
+When deprecating a feature, note the version in which it is expected to be
+removed so we can clean it up when that version ships. Call out the deprecation
+version in code (e.g. a `@deprecated` tag or comment naming the target release)
+and in the PR/commit description, so there's a clear marker to act on later.
+
 ## Code comments
 
 Keep comments short and focused on the code, not on the change history.
@@ -41,3 +66,17 @@ Keep comments short and focused on the code, not on the change history.
   *why* it exists, in terms a future reader needs. Don't reference PR numbers,
   issue numbers, or ticket IDs (e.g. `#1646`, `fixes JIRA-123`); the scenario
   should be clear without chasing external links.
+
+## Framework-owned instructions
+
+Keep runtime lifecycle and metadata instructions separate from portable agent
+instructions:
+
+- Agent-spec and per-request instructions are user-authored. Framework-owned
+  instructions are additive runtime behavior and are appended after them in
+  `omnigent/runtime/prompt.py`.
+- Keep the canonical instruction text and lifecycle gate in the owning framework
+  module. Harness adapters should only transport the composed instructions; do
+  not duplicate policy across adapters or add lifecycle metadata to `AgentSpec`.
+- If framework instructions grow beyond a small ordered list, introduce a
+  structured `FrameworkInstructions` value at the prompt-composition boundary.

CHANGELOG.md

@@ -5,11 +5,146 @@ 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`.
 
+## [v0.7.0] — 2026-07-27
+
+- [Bug fix] Hermes thinking now appears in mirrored web conversations. (#1645)
+- [Bug fix] Image and file attachments now survive session relaunches on remote host runners; attachments that fail to load show a visible marker instead of silently disappearing. (#2085)
+- [UI / Feature] Voice dictation in the composer now works in Electron, Firefox, and Chromium via optional server-side transcription (`omnigent[dictation]`) — local models, live streaming partials, audio never leaves your server. (#2093)
+- [UI / Bug fix / Test/CI] Hide Claude task completion control messages from conversation history while preserving them for resume context. (#2104)
+- [Bug fix / Feature / Docs] Operators can mount pre-created PersistentVolumeClaims (NFS/SMB/SAN) into Kubernetes sandbox runners via `sandbox.kubernetes.pvc_mounts` (read-only by default) (#2435)
+- [Bug fix / Test/CI] `/compact` no longer races when multiple compact requests hit the same session at once (#2585)
+- [Bug fix / Test/CI] `sys_call_async` / `sys_cancel_async` now consistently use `handle_id` as the cancel identifier. (#2586)
+- [Bug fix / Test/CI] Runner idle timeout no longer kills sessions waiting on async tools, timers, or approval prompts (#2588)
+- [Bug fix] Misconfigured runner tool policies deny tool calls instead of silently allowing them (#2589)
+- [UI / Feature] Slash-command menus now match any part of a command's name, so `/using-superpowers` finds `/superpowers:using-superpowers` (#2655)
+- [Bug fix] Host-launched runners now reuse delegated credentials instead of repeating Databricks authentication during startup. (#2762)
+- [Feature] Projects are now a first-class entity with a `/v1/projects` CRUD API (create, list, rename, delete) and per-session membership. (#2765)
+- [Bug fix] Hermes forwarder introspects state.db columns to survive cross-version schema drift (#2774)
+- [Feature] `omni usage` reports your LLM cost for today / the last 7 / 30 days, with a per-session per-model cost breakdown (#2787)
+- [Feature / Chore] Native Claude sessions start faster by coalescing runner initialization into one handshake. (#2793)
+- [UI / Bug fix / Feature / Docs / Test/CI] Claude-native launch and in-session pickers now share the selected host's live model catalog, including Claude Code's managed routes. (#2831)
+- [Bug fix] Managed BoxLite sandboxes remain available after provisioning so agent launches can execute commands reliably. (#2846)
+- [Feature] Server-side smart routing can now call an external `routes:select` router via `routing.provider: external`, with provider-agnostic auth (`api_key`) and model-name mapping (`model_prefix`) (#2864)
+- [UI] Chat code blocks no longer load the syntax-highlighter engine until the first (#2886)
+- [UI / Bug fix] The main chat "Working…" indicator now clears reliably when the session goes idle, instead of occasionally staying lit after a reply completes. (#2900)
+- [Bug fix] The performance benchmark harness now records HTTP failures and continues the rest of the suite instead of aborting, and excludes fully-failed runs from the summary averages. (#2917)
+- [Feature / Test/CI] Scheduled tasks can now be created without a workspace or a pinned host for non-code work (research, summaries, chat-only, MCP-only); an unset host runs on your live host at fire time, and an unset workspace defaults to the host's home directory. A pinned host is now authorized (existence + ownership) at create time rather than only at fire time. (#2946)
+- [Chore / Test/CI] N/A — internal benchmark/dev tooling; no user-facing impact. (#2947)
+- [Feature] Set `OMNIGENT_CONTAINER_RUNTIME=podman` to use Podman (or another supported runtime) globally instead of Docker, without editing every agent's YAML. (#2949)
+- [Bug fix] Sending a message to a session whose Claude Code terminal crashed no longer (#2951)
+- [Bug fix] The desktop app now always quits within a few seconds even if its background cleanup stalls or the OS re-quit is dropped. (#2972)
+- [UI / Bug fix] Messages send immediately when a session's only remaining work is a background job, instead of being held in the queue until it finishes (#2974)
+- [UI / Feature] Desktop update notifications now appear in a native corner toast that works (#2975)
+- [Bug fix / Chore] Runner startup no longer waits several seconds for Git's optional untracked-file cache probe. (#2976)
+- [Feature / Test/CI] `omnigent` benchmark harness gains `--network-delay-ms` and per-journey HTTP request counts (#2977)
+- [UI / Bug fix] Pi sessions now show reasoning while it streams and after conversation history reloads. (#2979)
+- [Feature] The runner log now records why the runner exited (crash traceback, signal, idle timeout, tunnel close, or parent death) (#2985)
+- [UI / Feature] Set up a missing agent from the New Chat dialog with a guided, step-by-step checklist (#2987)
+- [UI / Bug fix / Feature] HTTP headers can now be set and edited for HTTP MCP servers in the session agent info panel. (#2989)
+- Capped unbounded DB list queries in the permission store and reduced session opens in `check_access`/`get_permission_level` from 2–3 to 1. (#2995)
+- Deleting a conversation with many descendants now issues a single FTS DELETE instead of one per descendant. (#2999)
+- [UI / Bug fix] Android auto theme and system-bar icons now stay readable with both device themes and explicit in-app theme overrides. (#3006)
+- [UI / Feature] 3D model files (STL, 3MF, OBJ) now render an interactive preview in the file browser (#3007)
+- [UI / Bug fix] Subagents panel Graph View now shows the same status dot colors as List View (#3009)
+- [Feature / Test/CI] Scheduled-task runs now transition to a terminal state (`succeeded`/`failed`) as soon as the dispatched turn finishes, instead of staying `running` forever; run history is readable at `GET /v1/scheduled-tasks/{id}/runs`. (#3014)
+- [Feature / Chore] When enabled, new sessions receive concise semantic titles in the background without adding work or latency to the active agent turn. (#3024)
+- [Feature] Offload dictation speech-to-text to a remote worker with (#3025)
+- [Bug fix / Docs / Test/CI] Codex-native subagents now appear in the Agents panel with their live conversations. (#3028)
+- [Bug fix] Credential proxy no longer attaches injected credentials to TRACE/OPTIONS requests, and the egress proxy now honors Max-Forwards as a conformant intermediary. (#3029)
+- [Docs] N/A — internal documentation cleanup. (#3031)
+- [Feature] Import local Qwen, Kiro, Pi, and Kimi coding chats into Omnigent (#3032)
+- [UI / Feature] Press ⌘⌥V (Ctrl+Alt+V) to toggle voice dictation from anywhere; while dictating, Enter keeps the text and Esc discards it (#3044)
+- [UI / Feature] Added: "Auto · smart routing" harness option in the new-chat picker — lets the intelligent router pick both harness and model based on the task description (#3045)
+- [Feature] Import existing OpenCode chats, including files and tool activity, with `omnigent import` (#3046)
+- [Bug fix] Dictation streams now reliably release their worker slot when a browser disconnects abruptly. (#3048)
+- [UI] New-session composer moves harness configuration into a gear-icon modal, with a cleaner agent picker (needs-setup and custom agents folded into flyouts) and Smart Routing offered as a model option. (#3050)
+- [Bug fix / Feature] The Slack bot can now run against an Omnigent server deployed on Databricks Apps, (#3051)
+- [Feature] Sessions can now be filed into first-class projects via `PATCH /v1/sessions/{id}` and listed with `GET /v1/sessions?project=<name>`, which dual-reads first-class membership and legacy project labels. (#3053)
+- [Bug fix / Test/CI] Fixed SDK session telemetry always recording `harness: null` in server deployments not started via the CLI. (#3054)
+- [Test/CI] N/A — test-only reliability change. (#3056)
+- [Bug fix] Databricks OAuth CLI profiles no longer fail with a misleading "malformed profile" error; the message now explains the real fix (install `omnigent[databricks]` or refresh the OAuth session). (#3059)
+- [Bug fix] An idle runner shutting down after inactivity no longer shows a scary "disconnected" error — just send a message to wake it back up. (#3060)
+- [UI / Feature] The sidebar now uses first-class projects: create empty projects, rename and delete them, and file sessions into them — while existing label-based projects keep working. (#3061)
+- [UI / Bug fix] The "Host is offline — click to reconnect" prompt now appears in the composer's host badge instead of a separate banner below the composer (#3062)
+- [Test/CI] N/A (test-only change) (#3063)
+- [Feature / Docs / Test/CI] New `databricks_cli` credential-proxy type lets sandboxed agents use the Databricks CLI without the real token entering the sandbox (#3080)
+- [UI / Feature / Test/CI] Polly sessions running on Claude SDK can start Goal mode from the chat composer. (#3084)
+- [UI / Bug fix] The Configure agent modal's footer no longer shows a gray background band behind Cancel/Save (#3089)
+- [UI / Feature] The Sidebar is more compact and polished, with clearer status indicators and richer session details on hover. (#3092)
+- [UI] Reordered the project-folder header buttons (new-session before the menu), (#3096)
+- [Chore / Breaking] `omni server start` is removed; use `omni server --background` to launch the (#3105)
+- [Bug fix] `omnigent server --host 0.0.0.0` now enables accounts (login) mode automatically instead of silently 401-ing every request (#3107)
+- [Feature] Projects can store default session settings (host, workspace, harness, model, …) via a new `config` field on the projects API. (#3108)
+- [Bug fix] Databricks-served Claude models no longer break non-streaming responses (prompt-policy and smart routing) when returning typed content blocks (#3109)
+- [Feature] `omnidev omnigent <args…>` runs an omnigent command against the current checkout's pod via `uv run omnigent`, with the pod's isolated env applied (#3110)
+- [UI / Feature] Configure a session's model, effort, and smart routing mid-chat from a new gear icon in the composer (#3111)
+- [UI / Feature / Test/CI] Add the `/tasks` Scheduled Tasks page with sidebar navigation, task rows, empty states, suggestion chips, create-dialog entry points, and Playwright E2E coverage. (#3112)
+- [Bug fix] Reading image files in a Claude Code native session no longer bloats conversation history and breaks resume/compaction on large sessions (#3113)
+- [Bug fix / Test/CI] The iOS app no longer follows cross-origin redirects when probing a newly approved server for the Databricks workspace mount, so a consented host can't redirect the probe to a different origin. (#3115)
+- [Bug fix] Forked native sessions (Claude Code, Codex, Pi, Qwen) again resume with their prior conversation history. (#3116)
+- [UI / Feature / Test/CI] Workspace pane icons now explain themselves on hover, with a cleaner right-side session layout and compact Share action. (#3122)
+- [UI / Bug fix / Feature] Add a dialog for creating recurring scheduled agent tasks. (#3123)
+- [UI] Sidebar session hover flyouts and rows now align with the project rows — matching flyout style, title size, and right-edge padding. (#3124)
+- [Bug fix] Resuming a session with large images stored in history no longer overflows the context window or breaks compaction, on both the SDK and native Claude Code paths (#3133)
+- [Feature] `omnigent session import` loads a `session export` JSONL back into a server as a new session (#3141)
+- [Feature] Telemetry now records the agent name for Polly and Debby sessions. (#3152)
+- [Chore / Breaking] `omni integration slack start` is removed; use `omni integration slack --background` to launch the (#3153)
+- [UI / Bug fix / Docs / Chore] Slack device login now requires a fresh password at the consent screen, closing a device-code phishing gap where an already-signed-in user could approve a login by reflex. (#3156)
+- [Feature] `omnigent claude` keeps tool search enabled when launched with `CLAUDE_CODE_USE_GATEWAY=1`. (#3161)
+- [Test/CI] Fix `test_session_stream_emits_heartbeat_on_idle` after `_session_labels_for_runner_spawn` was extracted into `omnigent.runner.native.orchestration`; patch the heartbeat cadence on `omnigent.runner.app` where it is defined and consumed. (#3163)
+- [Bug fix] Crash reports are no longer lost when a process crashes more than once in the same second. (#3173)
+- [Bug fix] Custom codex-native agents launch on the model declared in the agent spec (`executor.model`) instead of silently falling back to the provider default (#3175)
+- [Bug fix] Single-file agent YAMLs that nest the executor under `type:`/`config:` (the bundle config.yaml shape) now fail at load time with the correct flat spelling, instead of silently running a harness inferred from the model prefix (#3178)
+- [UI / Bug fix / Feature] Use native Codex goal mode from Polly's Goal control (#3181)
+- [UI / Bug fix] Renaming a session now updates the name in the sidebar instantly instead of after a short delay. (#3185)
+- [UI / Bug fix / Feature / Test/CI] Edit scheduled tasks and type exact run times, with a scrollable time picker and a consistent, fully-visible dialog. (#3186)
+- [UI / Feature] Pinned sessions now persist server-side per user, so pins follow you across devices and browsers. (#3189)
+- [Feature] New sessions now receive concise semantic titles automatically without additional configuration. (#3191)
+- [Test/CI] `/rerun` PR comment re-runs failed CI on the current commit without dismissing approvals (#3195)
+- [Feature] Native Codex sessions can now receive concise automatic background titles. (#3199)
+- [Bug fix] Qwen3, inkling, and other non-OpenAI models now work in the Pi SDK executor harness (#3203)
+- [Chore / Breaking] Slack-on-Databricks deploy: renamed `OMNIGENT_SLACK_WEBAUTH_BASE_URL` to `OMNIGENT_SLACK_DATABRICKS_APP_URL` (`--app-url`), removed the `WEBAUTH_PORT` / `DATABRICKS_WORKSPACE_HOST` overrides, and dropped deploy-time `uv lock` in favor of in-container `uv run`. (#3206)
+- [UI / Bug fix] Sidebar session titles use the available space cleanly and reveal branch and action details only when needed. (#3208)
+- [UI / Bug fix] Removed the redundant "Create new project" option from the sidebar project picker — create projects with the + icon next to Projects (#3210)
+- [Feature] Smart routing now activates automatically when a server `llm:` block or an external `routing:` block is configured — no `OMNIGENT_SMART_ROUTING` env var needed (#3215)
+- [UI / Feature / Test/CI] Scheduled task rows now show when each task will next run ("Next run in 15h") and a "Run now" action in the ⋯ menu to fire a task immediately, with refreshed row styling. (#3218)
+- [UI / Feature] Projects now carry default session settings (host, working directory, agent, optional git worktree) that pre-fill the new-session composer. (#3221)
+- [Bug fix] Fixed per-model cost attribution for native harnesses so a session's per-model (#3223)
+- [UI / Bug fix] Codex task plans now stay in Tasks instead of being duplicated in chat. (#3249)
+- [UI / Bug fix] Smart Routing no longer appears in the model dropdown for native terminal sessions (Claude Code, Codex, Pi), where it had no effect (#3259)
+- [Bug fix] Sandboxed agents can now run tools managed by update-alternatives (awk, python3, editor, and similar) on Linux. (#3263)
+- [Bug fix] Egress proxy now trusts corporate/MDM CA roots installed under the system `capath` directory, so TLS to hosts behind a corporate MITM works from a sandboxed agent. (#3264)
+- [Bug fix] Large historical attachments no longer inflate replay and compaction context as inline base64 text. (#3267)
+- [Docs] Contributors can now use `omnidev` as the documented worktree-safe local testing flow. (#3277)
+- [Bug fix] Custom OpenAI Agents can use Unity AI Gateway Model Services with fully qualified model names when a Databricks provider or profile is configured. (#3288)
+- [UI / Bug fix / Feature] Configure recoverable dangerous shell commands to ask for approval or deny execution, while always blocking catastrophic operations. (#3297)
+- [Bug fix / Feature] Pi harness now routes kimi, inkling, GLM, qwen3, Gemini 3+, and Llama through the correct AI Gateway endpoints, fixing "Stream ended without finish_reason" errors and ensuring `system.ai.*` ids are used throughout. (#3307)
+- [Feature] Add a top-level `justfile` with recipes for launching the iOS Simulator, running the Android debug build, starting the omnigent dev pod, and running pre-commit/lockfile normalization. (#3310)
+- [UI / Bug fix] Sidebar header action buttons are now vertically centered with section titles. Session row hover is smoother, and active items no longer flash when hovered. (#3311)
+- [UI / Bug fix] Aligns project folder icons and color with the rest of the sidebar. (#3317)
+- [Bug fix] Unsupported Claude Code slash commands are now escaped and sent as regular user messages instead of leaving the native terminal in an undriveable state. (#3319)
+- [Feature] `omnigent server` now tells users they can set `OMNIGENT_AUTH_ENABLED=0` to override automatic multi-user mode when binding to a non-loopback interface. (#3320)
+- [Chore / Breaking] [Breaking] The deprecated `OMNIGENT_ACCOUNTS_ENABLED` environment variable has been removed; use `OMNIGENT_AUTH_ENABLED` instead. (#3322)
+- [UI / Bug fix] Fixed pinned sessions being lost when the web UI was updated before the server. (#3323)
+- [UI / Feature] Automations list: tasks now render as cards and show a live-updating relative next-run time ("Next run in 3 hours"). (#3324)
+- [UI] Settings → Appearance no longer has a separate Sidebar font size control, and a new "Reset to defaults" button restores every appearance preference after confirmation. (#3326)
+- [UI] Starting a session inside a project now names the project in the new-session (#3327)
+- [UI] The Files workspace tab now uses a stacked-files icon. (#3329)
+- [UI / Feature] Automations: scheduled tasks can now pick a model and reasoning effort in the create/edit dialog (defaults to the agent's settings). (#3331)
+- [UI / Bug fix] Fixed sessions pinned in the updated web UI being lost after the server was updated. (#3332)
+- [UI / Feature] Native harness setup now checks the installed CLI version and prompts to upgrade if it is too old. Cursor's missing-binary case is normalized to the same structured `binary-missing` signal as the other CLI-backed native harnesses. (#3335)
+- [Bug fix] Pi sessions now show a clear error when their Databricks login has expired, instead of silently accepting messages with no reply (#3336)
+- [Test/CI] N/A (internal CI change). (#3338)
+- [Bug fix] claude-sdk harness now surfaces harness-level failures (expired login, auth error) as structured errors instead of storing them as assistant messages. (#3342)
+- [UI] Align the sidebar brand row with the rest of the navigation. (#3346)
+- [UI / Bug fix] Short links like `#3090` in chat markdown tables no longer stack one character per line (#3350)
+
 ## [Unreleased]
 
 ### Features
 
 - [UI / Feature] Added a Nord color theme (arctic frost-blue palette) to the Appearance settings palette picker.
+- [Feature] Per-harness startup command/args overrides via a polymorphic `harness:` key in `config.yaml`. The `harness:` key now accepts a mapping with a `default` plus per-harness `command`/`args` overrides (e.g. `harness: {default: claude-sdk, codex: {command: /usr/local/bin/codex, args: [--config, approval_policy=on-request]}}`). The legacy scalar form (`harness: claude-sdk`) still works and auto-migrates to the mapping form on the next config write. Harness binary-path precedence: `OMNIGENT_<NAME>_PATH` env var > config `harness.<id>.command` > built-in default; `args` follow the same precedence with config `args` as the base and CLI pass-through args appended. The `OMNIGENT_<NAME>_PATH` env var (base id, `-native` suffix stripped) is the canonical per-binary override, standardizing the headless `HARNESS_<NAME>_PATH` and native `OMNIGENT_*_PATH` conventions into one namespaced name; the legacy `HARNESS_<NAME>_PATH` is still read as a deprecated fallback that logs a one-time warning + a CLI startup notice, and is slated for removal in v0.8.0. The pre-existing `omnigent claude --command` flag is deprecated (warns on use, pointing to `OMNIGENT_CLAUDE_PATH`/config) and will be removed in a future release; no other native command gained a `--command` flag — override via env or config.
 
 ## [v0.5.0] — 2026-07-10
 

CONTRIBUTING.md

@@ -28,7 +28,9 @@ Install local prerequisites first:
 - `bubblewrap` (`bwrap`), **Linux only**, used to OS-sandbox those native
   Claude/Codex/Pi terminals (`apt install bubblewrap` on Debian/Ubuntu). macOS
   uses the built-in `seatbelt` sandbox and needs nothing extra.
-- Node.js 22 LTS or newer with `npm` when working on `web/`.
+- Node.js 22 LTS or newer with `pnpm` (install via `corepack enable` or
+  `npm install -g pnpm`) when working on `web/`.
+- A Rust toolchain for the recommended `omnidev` local development supervisor.
 
 ```bash
 git clone https://github.com/omnigent-ai/omnigent.git
@@ -51,24 +53,73 @@ uv run pre-commit run --all-files
 When touching `web/`:
 
 ```bash
-cd web && npm install && npm run lint && npm run build
+cd web && pnpm install && pnpm run lint && pnpm run build
 ```
 
 ## Running locally
 
-To try your changes, start a local server, register your machine as a host,
-and run the frontend dev server. Use three separate terminals:
+Start with the smallest relevant automated test described in [Tests](#tests).
+For full-stack manual testing, use `omnidev`.
+
+### Recommended: worktree-safe testing with `omnidev`
+
+`omnidev` runs the current checkout's server, host, and Vite frontend in one
+terminal. Each checkout path, including each worktree, gets isolated state,
+configuration, database, artifacts, logs, and automatically allocated ports,
+so it can run alongside your normal Omnigent installation and other worktrees.
+
+Install the supervisor once from an up-to-date checkout:
+
+```bash
+cargo install --path dev/omnidev --force
+```
+
+Then run it from anywhere inside the branch checkout or worktree you want to
+test. A fresh worktree needs its own Python environment first:
+
+```bash
+cd /path/to/omnigent-worktree
+uv sync --extra all --extra dev
+omnidev
+```
+
+Open the exact `ui` URL displayed in the header; do not assume the Vite port is
+`5173`. Python changes under `omnigent/` reload the server and host, while
+frontend changes use Vite HMR.
+
+Run CLI commands against the development pod through the passthrough so they
+use that checkout and its isolated state instead of a globally installed
+`omnigent`:
+
+```bash
+omnidev omnigent config show
+omnidev omnigent agent list
+```
+
+Keep `omnidev` in the foreground and quit with `q` or `Ctrl-C` so it tears down
+all three processes. An interactive terminal inside an existing Omnigent
+session also works; use `git rev-parse --show-toplevel` to confirm that its
+current checkout is the one you intend to test.
+
+See [`dev/omnidev/README.md`](dev/omnidev/README.md) for log controls,
+clean-state testing, backend-only and LAN modes, and other options.
+
+### Manual three-terminal fallback
+
+Use the manual flow when you need to run or debug each component separately.
+Unlike `omnidev`, it does not isolate state or allocate ports. These commands
+assume the default ports are free:
 
 ```bash
 # Terminal 1: local server on :6767
-omnigent server
+uv run omnigent server
 
 # Terminal 2: register your machine as a host
-omnigent host --server http://localhost:6767
+uv run omnigent host --server http://localhost:6767
 
 # Terminal 3: frontend dev server
 cd web
-npm run dev
+pnpm run dev
 ```
 
 Open the Vite URL from the frontend dev server, usually
@@ -81,7 +132,7 @@ The host URL can also be passed positionally (`omnigent host
 http://localhost:6767`). See the [README](README.md) for more on hosts,
 harnesses, and credentials.
 
-### Backend-only local development validation
+### Disposable backend-only validation
 
 Use this when you want to validate the Python backend and local API server from
 a source checkout without building the web UI, configuring provider
@@ -169,7 +220,7 @@ Two cross-cutting suites sit on top of these:
 Frontend changes follow the same expectation with a different toolchain:
 
 - Add or update a **colocated Vitest test** — a `*.test.ts`/`*.test.tsx` file
-  next to the component or module you changed — and run it with `npm test`.
+  next to the component or module you changed — and run it with `pnpm test`.
 - A change to **user-facing UI behaviour** also needs a Playwright test under
   `tests/e2e_ui/`. This one is enforced mechanically by the `E2E UI Required`
   check, so a UI PR won't merge without a covering test (or a maintainer
@@ -177,10 +228,27 @@ Frontend changes follow the same expectation with a different toolchain:
 - Styling/formatting-only changes, copy tweaks with no flow change, and
   refactors with no behaviour change are exempt, same as the backend.
 
+## Developer Certificate of Origin
+
+To contribute to this repository, you must sign off your commits to certify
+that you have the right to contribute the code and that it complies with the
+open source license. If you can certify the contents of the [DCO](DCO), add a
+`Signed-off-by` line to each commit message:
+
+```
+Signed-off-by: Joe Smith <joe.smith@email.com>
+```
+
+Please use your real name — pseudonymous/anonymous contributions are not
+accepted. If your `user.name` and `user.email` git configs are set, `git
+commit -s` adds the sign-off automatically. The DCO check on every pull
+request enforces this, so unsigned commits will block merging.
+
 ## Pull requests
 
 - Branch from `main`, keep changes focused, and include tests or docs when relevant.
-- Sign off your commits with `git commit -s` (Developer Certificate of Origin).
+- Sign off your commits with `git commit -s` (see
+  [Developer Certificate of Origin](#developer-certificate-of-origin) above).
 - Fill in the PR template. For **UI / frontend changes**, check the
   "UI / frontend change" box and attach a **video or images** in the `Demo`
   section showing the new behaviour, so reviewers can see it without checking

DCO

@@ -0,0 +1,34 @@
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.

NOTICE

@@ -45,8 +45,8 @@ Copyright 2016 Google LLC.
 opentelemetry-instrumentation-openai-agents-v2 - https://pypi.org/project/opentelemetry-instrumentation-openai-agents-v2/
 Copyright The OpenTelemetry Authors.
 
-cel-expr-python - https://github.com/cel-expr/cel-python/
-Copyright The Cel Expr Python Authors.
+cel-python - https://github.com/cloud-custodian/cel-python/
+Copyright The cel-python Authors.
 
 modal - https://pypi.org/project/modal/
 Copyright Modal Labs 2022.

README.md

@@ -122,10 +122,10 @@ uv tool install -q --python 3.12 git+https://github.com/omnigent-ai/omnigent.git
 - **`uv`** (required). https://docs.astral.sh/uv/getting-started/installation/
   The installer offers to set this up for you.
 - **`git`** (required).
-- **Node.js 22 LTS or newer** with **`npm`**, for the npm-installed coding
-  harnesses (Claude, Codex, OpenCode, Pi). `omnigent run` installs the
-  harness CLI you pick.
-  https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
+- **Node.js 22 LTS or newer** with **`npm`** (for the coding-harness CLIs
+  installed by `omnigent run`) and **`pnpm`** (for the web UI). You can get
+  both from a single Node install; pnpm is available via
+  `corepack enable` or `npm install -g pnpm`.
 - **Kiro CLI** (optional), for `omnigent kiro`: install with
   `curl -fsSL https://cli.kiro.dev/install | bash`, then sign in with Kiro.
   Kiro tool approvals stay answerable in the embedded Terminal; supported
@@ -294,7 +294,7 @@ see step 3.)
 **Prefer the browser?** Start a server and register your machine as a host:
 
 ```bash
-omnigent server start   # start the local server and web UI in the background
+omnigent server --background   # start the local server and web UI in the background
 omnigent host           # (separate terminal) register this machine as a host
 ```
 
@@ -374,7 +374,7 @@ Omnigent supports **multi-user accounts**, controlled by one environment
 variable:
 
 ```bash
-OMNIGENT_AUTH_ENABLED=1 omnigent server start
+OMNIGENT_AUTH_ENABLED=1 omnigent server --background
 ```
 
 The **Docker deploy in [step 4](#4-deploy-a-server-and-use-it-from-your-phone)
@@ -414,6 +414,11 @@ and they're in. Signup is invite-only.
   omnigent run --fork <session_id>
   ```
 
+Shared sessions identify model-visible messages with `[account]:` labels by
+default. Set `OMNIGENT_SHARED_MESSAGE_ATTRIBUTION_ENABLED=0` to hide those
+labels. This does not change stored authors, UI avatars, or who may approve or
+run privileged actions.
+
 > [!TIP]
 > Want your team to sign in with the logins they already have (**Google,
 > GitHub, Okta, Microsoft**)? Set `OMNIGENT_OIDC_ISSUER` plus a client ID
@@ -508,6 +513,17 @@ Polly at [`examples/polly/`](https://github.com/omnigent-ai/omnigent/tree/main/e
 
 ---
 
+## Telemetry
+
+Omnigent collects anonymized usage data (telemetry) by default. This data
+contains no sensitive or personally identifiable information. If you're using
+Omnigent through a managed service or distribution, please consult your managed
+service agreement to determine any data collection that may impact your use of
+the service. To opt out, follow our instructions in
+[Usage Telemetry](https://omnigent.ai/docs/deploy/telemetry).
+
+---
+
 ## Contributing
 
 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.

RELEASING.md

@@ -94,8 +94,9 @@ What it does (all idempotent):
   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);
+  `oss-publish-images.yml` (Docker; publishes the immutable version image tag),
+  `github-release.yml` (skips rc — no GitHub release is created for
+  pre-releases; rcs live on PyPI only), and `draft-release-notes.yml` (skips rc);
 - 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.
@@ -128,7 +129,8 @@ python -m venv /tmp/omni-rc && /tmp/omni-rc/bin/pip install \
 /tmp/omni-rc/bin/omnigent --version    # expect 0.6.0rc1
 ```
 
-The rc's GitHub draft stays **unpublished** — rc drafts are never published.
+No GitHub release is created for the rc — pre-releases live on PyPI only,
+and a curated release page is reserved for the final cut.
 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).
 
@@ -186,9 +188,10 @@ can never be reused. So:
   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`.
+- **Wrong commit tagged, nothing published yet:** delete the tag and, for a
+  final `vX.Y.Z` (which has a draft), the draft too —
+  `gh release delete vX.Y.Z`, `git push origin :refs/tags/vX.Y.Z` — then
+  re-dispatch `release.yml`. (rc tags have no draft to delete.)
 - **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):
@@ -205,7 +208,7 @@ can never be reused. So:
 
 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
+inert everywhere that matters: no GitHub release is created for rc tags, 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
@@ -231,8 +234,8 @@ The examples below use `0.0.1rc2`; substitute the next free number.
    ```
 
 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
+   `v0.0.1rc2` pushed, the tag firing the image workflow (`github-release.yml`
+   runs but skips the rc — no draft), 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.
@@ -268,11 +271,11 @@ The examples below use `0.0.1rc2`; substitute the next free number.
 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 `gh release delete` is needed: pre-release tags no longer create a GitHub
+release. 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.
@@ -300,8 +303,9 @@ 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
+Then continue from step 2 of the standard flow (secure-repo dispatches). For
+a final `vX.Y.Z`, if the GH draft wasn't created, `gh release create vX.Y.Z
+--draft --verify-tag --title vX.Y.Z` recreates it (rc tags get no draft by
+design). 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/boxlite/README.md

@@ -59,6 +59,18 @@ sandbox:
   server_url: https://omnigent.example.com   # the in-box host dials this back
 ```
 
+A top-level `sandbox.host_config:` (provider-agnostic) holds verbatim
+in-sandbox `~/.omnigent/config.yaml` content — e.g. a `providers:`
+block routing a harness through a self-hosted gateway — installed into
+the sandbox before `omnigent host` starts. The block is server-managed:
+entries injected by a previous launch are replaced or removed on the
+next launch/resume, while config created inside the sandbox survives.
+Keep secrets out via
+`api_key_ref: env:VAR` (resolved in the sandbox against the injected
+env). See the [sandbox-runners config
+table](../kubernetes/overlays/sandbox-runners/README.md#configuration-sandbox-configyaml)
+for the shape.
+
 `provider` + `server_url` is a complete config: the image defaults to
 the official prebaked host image and boxes run locally.
 

deploy/cloudflare/README.md

@@ -68,8 +68,8 @@ browser ───────────────►  Worker (src/index.js)
 
 ```bash
 cd deploy/cloudflare
-npm install
-npx wrangler login
+pnpm install
+pnpm exec wrangler login
 ```
 
 ## Deploy

deploy/cwsandbox/README.md

@@ -136,6 +136,18 @@ sandbox:
   server_url: https://your-host    # public URL sandboxes dial back to
 ```
 
+A top-level `sandbox.host_config:` (provider-agnostic) holds verbatim
+in-sandbox `~/.omnigent/config.yaml` content — e.g. a `providers:`
+block routing a harness through a self-hosted gateway — installed into
+the sandbox before `omnigent host` starts. The block is server-managed:
+entries injected by a previous launch are replaced or removed on the
+next launch/resume, while config created inside the sandbox survives.
+Keep secrets out via
+`api_key_ref: env:VAR` (resolved in the sandbox against the injected
+env). See the [sandbox-runners config
+table](../kubernetes/overlays/sandbox-runners/README.md#configuration-sandbox-configyaml)
+for the shape.
+
 `provider` + `server_url` is a complete config. `server_url` **must be reachable
 from CoreWeave** — the host inside the sandbox opens an outbound WebSocket to it,
 not `localhost`. For local testing, expose your server with a tunnel

deploy/databricks/build.sh

@@ -28,10 +28,8 @@ rm -rf omnigent/server/static/web-ui dist build omnigent.egg-info
 
 if [[ "${SKIP_WEB_UI:-}" != "1" ]]; then
     echo "==> Building web SPA into omnigent/server/static/web-ui/"
-    cd web
-    npm install
-    npm run build
-    cd "${REPO_ROOT}"
+    pnpm install --frozen-lockfile --filter web
+    pnpm --filter web run build
 else
     echo "==> SKIP_WEB_UI=1: skipping web build"
 fi

deploy/databricks/src/app.py

@@ -153,6 +153,9 @@ try:
         SqlAlchemyPermissionStore,
     )
     from omnigent.stores.policy_store.sqlalchemy_store import SqlAlchemyPolicyStore
+    from omnigent.stores.scheduled_task_store.sqlalchemy_store import (
+        SqlAlchemyScheduledTaskStore,
+    )
 
     DB_URI = f"postgresql+psycopg://{PGUSER}@{PGHOST}:{PGPORT}/{PGDATABASE}"
     ARTIFACT_URI = f"dbfs:{VOLUME_PATH}"
@@ -180,6 +183,7 @@ try:
     permission_store = SqlAlchemyPermissionStore(DB_URI)
     policy_store = SqlAlchemyPolicyStore(DB_URI)
     host_store = HostStore(DB_URI)
+    scheduled_task_store = SqlAlchemyScheduledTaskStore(DB_URI)
 
     agent_cache = AgentCache(artifact_store=artifact_store, cache_dir=CACHE_DIR)
 
@@ -212,6 +216,7 @@ try:
         permission_store=permission_store,
         policy_store=policy_store,
         host_store=host_store,
+        scheduled_task_store=scheduled_task_store,
         auth_provider=auth_provider,
     )
 

deploy/daytona/README.md

@@ -151,6 +151,18 @@ sandbox:
     env: [OPENAI_API_KEY, ANTHROPIC_API_KEY, GIT_TOKEN]
 ```
 
+A top-level `sandbox.host_config:` (provider-agnostic) holds verbatim
+in-sandbox `~/.omnigent/config.yaml` content — e.g. a `providers:`
+block routing a harness through a self-hosted gateway — installed into
+the sandbox before `omnigent host` starts. The block is server-managed:
+entries injected by a previous launch are replaced or removed on the
+next launch/resume, while config created inside the sandbox survives.
+Keep secrets out via
+`api_key_ref: env:VAR` (resolved in the sandbox against the injected
+env). See the [sandbox-runners config
+table](../kubernetes/overlays/sandbox-runners/README.md#configuration-sandbox-configyaml)
+for the shape.
+
 ## Credentials for the sandbox (LLM keys, git tokens)
 
 Daytona has no provider-side named-secret store to attach at sandbox

deploy/docker/.env.example

@@ -34,13 +34,19 @@ POSTGRES_PASSWORD=change-me-please
 # instance.
 #
 #   A) Built-in accounts (DEFAULT — no env needed for laptop testing).
-#      First boot auto-creates an admin user (named after the OS
-#      user, falling back to "admin"), prints the password to
-#      `docker compose logs omnigent`, and saves it to
-#      /data/admin-credentials on the persistent volume. Admin
-#      invites teammates via the web UI Members page.
+#      No credentials are auto-generated. First boot prints a
+#      "No admin yet" line pointing at the base URL; you create the
+#      first admin (username + password) via the web Create-admin
+#      form, or pre-seed it with OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD.
+#      Admin invites teammates via the web UI Members page.
 #      For any deploy behind a public domain you MUST set
 #      OMNIGENT_ACCOUNTS_BASE_URL — see below.
+#      Security note for public deployments: POST /auth/setup is
+#      intentionally unauthenticated while no password-bearing account
+#      exists, so an instance exposed before its operator reaches the
+#      form can be claimed by the first visitor. Pre-seed
+#      OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD, or keep the service
+#      private until setup completes.
 #
 #   B) Native OIDC (for shops with an existing IdP).
 #      Set the OMNIGENT_OIDC_* vars below (at minimum
@@ -82,9 +88,14 @@ POSTGRES_PASSWORD=change-me-please
 # omnigent:8000 container address.
 # OMNIGENT_ACCOUNTS_BASE_URL=https://omnigent.example.com
 #
-# Optional: pre-seed the initial admin password instead of the
-# auto-generated one. Useful for headless / CI deploys where
-# the operator can't read `docker compose logs`.
+# Optional: pre-seed the initial admin password so bootstrap creates
+# the first admin directly, instead of waiting for someone to claim it
+# through the web Create-admin form. Useful for headless / CI deploys
+# where that form can't be reached interactively. Nothing is ever
+# auto-generated: without this (and without an OIDC issuer) a fresh
+# instance stays in the needs-setup state and prints the setup URL to
+# stderr — no password appears in the logs. See the security note under
+# section A above for public deployments.
 # OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD=
 #
 # Optional: session/invite/magic TTLs. Defaults shown.
@@ -151,6 +162,14 @@ POSTGRES_PASSWORD=change-me-please
 # trusted enterprise directory — it makes any signed email claim the
 # user's identity. Off by default.
 # OMNIGENT_OIDC_SKIP_EMAIL_VERIFICATION=1
+#
+# Read the email identity from a different id_token claim. Some IdPs
+# omit the email claim entirely — Microsoft Entra ID commonly issues
+# only preferred_username (the UPN) — which fails login with
+# "Could not determine user email". A custom claim carries no
+# email_verified marker, so set OMNIGENT_OIDC_SKIP_EMAIL_VERIFICATION
+# alongside it. Default: email.
+# OMNIGENT_OIDC_EMAIL_CLAIM=preferred_username
 
 # ── Server config file (admins, allowed domains, …) ──────
 # Non-secret settings live in a YAML config file — the same one

deploy/docker/Dockerfile

@@ -55,7 +55,7 @@
 
 # Must satisfy pyproject requires-python (>=3.12); 3.11 fails dependency resolution.
 ARG PYTHON_VERSION=3.12
-ARG NODE_VERSION=20
+ARG NODE_VERSION=22
 
 # ── Web UI builder ──────────────────────────────────────
 # Builds the web SPA so `docker build` works from a clean checkout —
@@ -70,12 +70,20 @@ ARG NODE_VERSION=20
 FROM node:${NODE_VERSION}-slim AS web-builder
 ARG NPM_CONFIG_REGISTRY=
 ENV NPM_CONFIG_REGISTRY=${NPM_CONFIG_REGISTRY}
-WORKDIR /web/web
-# Manifests first so the install layer caches across pure source edits.
-COPY web/package.json web/package-lock.json ./
-RUN npm install --no-audit --no-fund
-COPY web/ ./
-RUN npm run build
+WORKDIR /web
+
+# Workspace manifests + lockfile first so the install layer caches across pure
+# source edits. The electron package JSON is included so the root workspace is
+# structurally complete, but we --filter web to avoid downloading Electron.
+COPY pnpm-workspace.yaml pnpm-lock.yaml ./
+COPY web/package.json ./web/
+COPY web/electron/package.json ./web/electron/
+
+RUN npm install -g pnpm@11.15.1
+RUN pnpm install --frozen-lockfile --filter web
+
+COPY web/ ./web/
+RUN pnpm --filter web run build
 
 # ── Python builder (shared: server + host) ──────────────
 # Installs the package (and its transitive native-extension deps) into

deploy/docker/Dockerfile.ubi

@@ -13,7 +13,7 @@
 #                -f deploy/docker/Dockerfile.ubi .
 
 ARG PYTHON_VERSION=3.12
-ARG NODE_VERSION=20
+ARG NODE_VERSION=22
 
 # ── Web UI builder ──────────────────────────────────────
 FROM registry.access.redhat.com/ubi9/nodejs-${NODE_VERSION} AS web-builder
@@ -21,11 +21,20 @@ ARG NPM_CONFIG_REGISTRY=
 ENV NPM_CONFIG_REGISTRY=${NPM_CONFIG_REGISTRY}
 
 USER 0
-WORKDIR /web/web
-COPY web/package.json web/package-lock.json ./
-RUN npm install --no-audit --no-fund
-COPY web/ ./
-RUN npm run build
+WORKDIR /web
+
+# Workspace manifests + lockfile first so the install layer caches across pure
+# source edits. The electron package JSON is included so the root workspace is
+# structurally complete, but we --filter web to avoid downloading Electron.
+COPY pnpm-workspace.yaml pnpm-lock.yaml ./
+COPY web/package.json ./web/
+COPY web/electron/package.json ./web/electron/
+
+RUN npm install -g pnpm@11.15.1
+RUN pnpm install --frozen-lockfile --filter web
+
+COPY web/ ./web/
+RUN pnpm --filter web run build
 
 # ── Python builder (shared: server + host) ──────────────
 FROM registry.access.redhat.com/ubi9/python-312 AS builder

deploy/docker/README.md

@@ -43,40 +43,47 @@ docker compose down -v
 
 Built-in accounts auth: no IdP to register, no proxy to host.
 This is the default — `docker compose up -d` brings it up with no
-extra env wiring. First boot creates an admin user (named after the
-operator's OS user, falling back to `admin` in headless containers)
-with a random password that lands in the container logs and on the
-persistent volume at `/data/admin-credentials`.
+extra env wiring. No credentials are auto-generated. On first boot,
+when no admin exists yet and none was pre-seeded, the server creates
+nothing and prints:
+
+```
+→ No admin yet. Open <base_url> to create the first admin account (choose a username + password).
+```
+
+You then open the web UI's **Create admin** form (it appears while no
+admin exists) and pick your own username + password.
 
 For any deploy reachable through a public domain, also set the
-external URL so invite links resolve correctly:
+external URL so the printed link and invite links resolve correctly:
 
 ```bash
 # Add to .env (bootstrap.sh already minted the cookie secret for you):
 OMNIGENT_ACCOUNTS_BASE_URL=https://omnigent.example.com
 
 docker compose up -d
-docker compose logs omnigent | grep -A4 "Created initial admin"
+docker compose logs omnigent      # shows the "No admin yet" line with your base URL
 ```
 
-Copy the random `password` from the log line into the web UI's
-login form, then:
+Once you've created the admin and signed in:
 
 - Click your username in the top-right → **Members** → **Invite member**.
 - Share the single-use URL with the teammate; they pick their own
   username and password when they redeem it.
 - Sign-out lives in the same account menu.
 
-Headless deploy (CI, Cloud Run, etc.) where you can't read the
-logs? Pre-seed the password:
+Headless deploy (CI, Cloud Run, etc.) where you can't reach the
+Create-admin form? Pre-seed the admin password so first boot creates
+the admin directly:
 
 ```bash
 OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD=<your-strong-password>
 ```
 
-The persistent password file is at `/data/admin-credentials` on
-the `artifact-data` volume — survives `docker compose restart`,
-deleted by `docker compose down -v`.
+`OMNIGENT_ADMIN_CREDENTIALS_PATH` (set to `/data/admin-credentials`
+in `docker-compose.yaml`) anchors the persistent state directory on
+the `artifact-data` volume — it survives `docker compose restart` and
+is deleted by `docker compose down -v`.
 
 ## Multi-user mode (OIDC)
 

deploy/docker/bootstrap.sh

@@ -94,8 +94,9 @@ echo
 echo "✓ deploy/docker/.env is ready. Next:"
 echo "    docker compose up -d && docker compose logs omnigent"
 echo
-echo "  Accounts mode is the default — the first-boot admin password"
-echo "  lands in the logs and in /data/admin-credentials on the"
-echo "  persistent volume. For any public-domain deploy also set:"
+echo "  Accounts mode is the default — no credentials are auto-generated."
+echo "  First boot prints a 'No admin yet' line; open that URL and create"
+echo "  the first admin (username + password) via the web form. For any"
+echo "  public-domain deploy also set:"
 echo "    OMNIGENT_ACCOUNTS_BASE_URL=<your public URL>"
-echo "  in .env so invite links resolve to the right host."
+echo "  in .env so that link and invite links resolve to the right host."

deploy/docker/docker-compose.yaml

@@ -8,9 +8,11 @@
 #   open http://localhost:8000  # web UI; start a local runner per the prompt
 #
 # Auth modes (OMNIGENT_AUTH_PROVIDER):
-#   - accounts (DEFAULT) — built-in accounts, no IdP needed. First
-#     boot prints the admin password to `docker compose logs` and
-#     saves it to /data/admin-credentials. Set
+#   - accounts (DEFAULT) — built-in accounts, no IdP needed. No
+#     credentials are auto-generated; first boot prints a "No admin
+#     yet" line and you create the first admin (username + password)
+#     via the web Create-admin form, or pre-seed it with
+#     OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD. Set
 #     OMNIGENT_ACCOUNTS_BASE_URL for any deploy reachable behind
 #     a public domain (defaults to http://<HOST>:<PORT> otherwise).
 #   - oidc — bring your own IdP. Set OMNIGENT_OIDC_* vars — see
@@ -60,9 +62,15 @@ services:
       ARTIFACT_DIR: /data/artifacts
       HOST: 0.0.0.0
       PORT: "8000"
-      # Pin the admin-credentials path to the persistent volume so
-      # the file survives container restarts. Empty/unset would
-      # write to /root/.omnigent/ inside the ephemeral container.
+      # Anchor the server's data dir on the persistent volume so
+      # file-backed operator config survives container restarts:
+      # the admin roster (/data/admins) and allowed-domains file
+      # (/data/allowed_domains), plus artifacts mounted elsewhere
+      # in the same volume. Account rows and password hashes live in
+      # PostgreSQL (the postgres-data volume), not here. The server
+      # resolves its data dir from this path's parent (/data);
+      # empty/unset would fall back to /root/.omnigent/ inside the
+      # ephemeral container.
       OMNIGENT_ADMIN_CREDENTIALS_PATH: /data/admin-credentials
 
       # ── Auth ─────────────────────────────────────────
@@ -101,6 +109,10 @@ services:
       # without API Access Management) that omit the claim for
       # directory-provisioned users. Off unless set; see .env.example.
       OMNIGENT_OIDC_SKIP_EMAIL_VERIFICATION: "${OMNIGENT_OIDC_SKIP_EMAIL_VERIFICATION:-}"
+      # Read the email identity from a different id_token claim — for
+      # IdPs (e.g. Microsoft Entra ID) that issue preferred_username
+      # instead of email. Empty means the default (email); see .env.example.
+      OMNIGENT_OIDC_EMAIL_CLAIM: "${OMNIGENT_OIDC_EMAIL_CLAIM:-}"
       # Opt-in OIDC invites (admin pre-authorizes one off-domain email).
       # Off unless set. The admin list (/data/admins) and the optional
       # allowed-domains file (/data/allowed_domains) need no env var —

deploy/docker/entrypoint.py

@@ -254,6 +254,25 @@ def _select_artifact_store(resolved_config: _ResolvedConfig) -> ArtifactStore:
     return LocalArtifactStore(str(resolved_config.artifact_dir))
 
 
+def _build_local_llm_routing_client(
+    server_llm: Any,  # type: ignore[explicit-any]  # LLMConfig | None
+) -> Any | None:  # type: ignore[explicit-any]  # LLMRoutingClient | None
+    if server_llm is None:
+        return None
+    from omnigent.runtime.policies.builder import (
+        _build_policy_llm_client,
+        _resolve_server_llm_connection,
+    )
+
+    conn = _resolve_server_llm_connection(server_llm)
+    policy_client = _build_policy_llm_client(server_llm, conn)
+    if policy_client is None:
+        return None
+    from omnigent.server.smart_routing import LLMRoutingClient
+
+    return LLMRoutingClient(policy_client)
+
+
 def build_app(resolved_config: _ResolvedConfig | None = None) -> _BuiltApp:
     """Resolve config if needed, wire the stores, and build the app.
 
@@ -289,6 +308,10 @@ def build_app(resolved_config: _ResolvedConfig | None = None) -> _BuiltApp:
     from omnigent.stores.permission_store.sqlalchemy_store import (
         SqlAlchemyPermissionStore,
     )
+    from omnigent.stores.policy_store.sqlalchemy_store import SqlAlchemyPolicyStore
+    from omnigent.stores.scheduled_task_store.sqlalchemy_store import (
+        SqlAlchemyScheduledTaskStore,
+    )
 
     telemetry.init()
 
@@ -298,6 +321,8 @@ def build_app(resolved_config: _ResolvedConfig | None = None) -> _BuiltApp:
     comment_store = SqlAlchemyCommentStore(database_url)
     permission_store = SqlAlchemyPermissionStore(database_url)
     host_store = HostStore(database_url)
+    policy_store = SqlAlchemyPolicyStore(database_url)
+    scheduled_task_store = SqlAlchemyScheduledTaskStore(database_url)
     # Fail startup loud on a malformed `sandbox:` section (an operator
     # typo should not surface as a runtime 502 on the first managed
     # session); the startup catch-all below logs it.
@@ -309,14 +334,62 @@ def build_app(resolved_config: _ResolvedConfig | None = None) -> _BuiltApp:
         cache_dir=artifact_dir / ".cache",
     )
 
+    from omnigent.spec import parse_default_policies, parse_server_llm
+
+    server_llm = parse_server_llm(cfg.get("llm"))
+
+    routing_cfg = cfg.get("routing")
+    if isinstance(routing_cfg, dict) and routing_cfg.get("provider") == "external":
+        from omnigent.server.smart_routing import ExternalRoutingClient, _bearer_auth
+
+        base_url = (routing_cfg.get("base_url") or "").strip()
+        router_name = (routing_cfg.get("router_name") or "").strip()
+        api_key_raw = (routing_cfg.get("api_key") or "").strip()
+        profile = (routing_cfg.get("profile") or "").strip()
+        raw_prefixes = routing_cfg.get("model_prefix")
+        if isinstance(raw_prefixes, str):
+            raw_prefixes = [raw_prefixes]
+        model_prefixes = (
+            [p.strip() for p in raw_prefixes if isinstance(p, str) and p.strip()]
+            if isinstance(raw_prefixes, list)
+            else []
+        )
+        if base_url and router_name:
+            auth = None
+            databricks_profile: str | None = None
+            if api_key_raw:
+                from omnigent.spec import expand_env_vars
+
+                auth = _bearer_auth(expand_env_vars({"api_key": api_key_raw})["api_key"])
+            elif profile:
+                databricks_profile = profile
+            routing_client = ExternalRoutingClient(
+                base_url=base_url,
+                router_name=router_name,
+                auth=auth,
+                databricks_profile=databricks_profile,
+                model_prefixes=model_prefixes,
+            )
+        else:
+            routing_client = None
+    else:
+        routing_client = _build_local_llm_routing_client(server_llm)
+
+    caps = RuntimeCaps(
+        default_policies=parse_default_policies(cfg.get("policies")),
+        llm=server_llm,
+        routing_client=routing_client,
+    )
+
     init_runtime(
         agent_cache=agent_cache,
-        caps=RuntimeCaps(),
+        caps=caps,
         agent_store=agent_store,
         file_store=file_store,
         conversation_store=conversation_store,
         artifact_store=artifact_store,
         comment_store=comment_store,
+        policy_store=policy_store,
     )
 
     # Build the auth provider from the live env (header/oidc/accounts).
@@ -343,7 +416,9 @@ def build_app(resolved_config: _ResolvedConfig | None = None) -> _BuiltApp:
         agent_cache=agent_cache,
         comment_store=comment_store,
         permission_store=permission_store,
+        policy_store=policy_store,
         host_store=host_store,
+        scheduled_task_store=scheduled_task_store,
         auth_provider=auth_provider,
         account_store=account_store,
         # Non-secret auth settings from the config file (admins are the

deploy/e2b/README.md

@@ -138,6 +138,18 @@ sandbox:
   server_url: https://your-host    # public URL sandboxes dial back to
 ```
 
+A top-level `sandbox.host_config:` (provider-agnostic) holds verbatim
+in-sandbox `~/.omnigent/config.yaml` content — e.g. a `providers:`
+block routing a harness through a self-hosted gateway — installed into
+the sandbox before `omnigent host` starts. The block is server-managed:
+entries injected by a previous launch are replaced or removed on the
+next launch/resume, while config created inside the sandbox survives.
+Keep secrets out via
+`api_key_ref: env:VAR` (resolved in the sandbox against the injected
+env). See the [sandbox-runners config
+table](../kubernetes/overlays/sandbox-runners/README.md#configuration-sandbox-configyaml)
+for the shape.
+
 `server_url` must be reachable *from E2B's cloud* — a public HTTPS URL,
 not `localhost`. Sessions created with `host_type: "managed"` (the API
 call or the Web UI's New Sandbox option) then run on a fresh E2B sandbox;

deploy/fly/README.md

@@ -35,14 +35,23 @@ Then:
 1. **Memory** — `fly.toml` pins a **1 GB** machine (`[[vm]] memory = "1gb"`).
    The server idles around ~275 MB RSS, so Fly's 256 MB default OOM-loops.
    Keep it at 1 GB (or `fly scale memory 1024 -a <your-app>` if you changed it).
-2. **Admin password** prints once in the first-boot logs:
+2. **Create the first admin.** No credentials are auto-generated. First boot
+   prints a "No admin yet" line pointing at your `*.fly.dev` URL:
    ```bash
    fly logs -a <your-app>
    ```
-   Look for `Created initial admin account ... password: <generated>` (also
-   written to `/data/admin-credentials` on the volume).
-3. Open `https://<your-app>.fly.dev`, log in as `admin`. The cookie secret and
-   base URL (`FLY_APP_NAME` -> `<app>.fly.dev`) are handled automatically.
+   Open `https://<your-app>.fly.dev` and use the web Create-admin form to pick
+   your own username + password. For a headless deploy, pre-seed
+   `OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD` (`fly secrets set …`) before first
+   boot to create the admin directly instead.
+3. Log in with the admin you just created. The cookie secret and base URL
+   (`FLY_APP_NAME` -> `<app>.fly.dev`) are handled automatically.
+
+> **Security note for public deployments:** `POST /auth/setup` is
+> unauthenticated while no password-bearing account exists, so an instance
+> exposed before you reach the Create-admin form can be claimed by the first
+> visitor. Pre-seed `OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD`, or complete setup
+> promptly after the deploy goes live.
 
 ## Deploy (Fly web-UI Launch)
 

deploy/hf-spaces/README.md

@@ -35,15 +35,21 @@ files plus two secrets.
    | `DATABASE_URL` | variable | `sqlite:////data/artifacts/chat.db` |
    | `OMNIGENT_ACCOUNTS_COOKIE_SECRET` | secret | `openssl rand -hex 32` (pin it: ephemeral disk would otherwise drop sessions on restart) |
 
-4. The Space builds + boots. Admin password is in the Space **Logs** on first
-   boot. The base URL is auto-detected from `SPACE_HOST`, so it needs no manual
-   set.
+4. The Space builds + boots. No admin credential is auto-generated: first boot
+   prints a "No admin yet" line to the Space **Logs**, and the Space serves a
+   web Create-admin form where you pick your own username + password. The base
+   URL is auto-detected from `SPACE_HOST`, so it needs no manual set. To create
+   the admin directly instead, add `OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD` as a
+   Space secret before first boot.
 5. **Log in via the direct URL** `https://<user>-<space>.hf.space` in its own
    tab — not HF's embedded preview. The session cookie is `SameSite=Lax`, which
    browsers won't send inside HF's cross-origin iframe, so logging in from the
    embedded view loops back to `/login`. The direct URL is top-level
    (same-site), so login sticks. Make the Space **Public** so the direct URL
-   isn't gated.
+   isn't gated — but note the Create-admin form is unauthenticated until the
+   first admin is claimed, so a public Space can be claimed by the first
+   visitor. Pre-seed `OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD` (step 4) or claim
+   the admin immediately after it goes public.
 
 ## Want persistence / multi-user later?
 

deploy/islo/README.md

@@ -191,6 +191,18 @@ sandbox:
   server_url: https://your-host    # public URL sandboxes dial back to
 ```
 
+A top-level `sandbox.host_config:` (provider-agnostic) holds verbatim
+in-sandbox `~/.omnigent/config.yaml` content — e.g. a `providers:`
+block routing a harness through a self-hosted gateway — installed into
+the sandbox before `omnigent host` starts. The block is server-managed:
+entries injected by a previous launch are replaced or removed on the
+next launch/resume, while config created inside the sandbox survives.
+Keep secrets out via
+`api_key_ref: env:VAR` (resolved in the sandbox against the injected
+env). See the [sandbox-runners config
+table](../kubernetes/overlays/sandbox-runners/README.md#configuration-sandbox-configyaml)
+for the shape.
+
 `server_url` must be reachable *from Islo's cloud* — a public HTTPS URL,
 not `localhost`. The server itself needs `ISLO_API_KEY` (and optional
 `ISLO_BASE_URL`) in its environment. Sessions created with

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

@@ -128,15 +128,53 @@ writing nothing to disk — use HTTPS repository URLs. Details by provider match
 | Key | Meaning |
 |---|---|
 | `server_url` | URL the runner Pod's host dials back to (in-cluster service DNS by default). |
+| `host_config` | Optional, top-level under `sandbox:` (provider-agnostic, not inside `kubernetes:`): verbatim in-sandbox `~/.omnigent/config.yaml` content installed before `omnigent host` starts — e.g. a `providers:` block routing the `pi` harness through a self-hosted gateway (LiteLLM/vLLM). Server-managed: entries injected by a previous launch are replaced or removed on the next launch/resume; config created inside the sandbox survives. Keep secrets out via `api_key_ref: env:VAR`, resolved inside the runner Pod against the `secret_name` Secret. Validated at server startup. |
 | `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 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 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.) |
+| `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. |
 | `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`). |
+| `pvc_mounts` | Optional pre-created PersistentVolumeClaims mounted into every runner Pod — see [Persistent storage mounts](#persistent-storage-mounts-pvc_mounts). |
+
+## Persistent storage mounts (`pvc_mounts`)
+
+Runner Pods are ephemeral by design — the workspace lives on an `emptyDir` and
+dies with the Pod. To expose durable data (datasets, model caches, shared
+output directories) mount pre-created PersistentVolumeClaims:
+
+1. Create the PV/PVC **in the runner namespace** (`omnigent-sandboxes`) out of
+   band — via your GitOps repo, with whatever backend your cluster provides
+   (NFS/SMB CSI drivers, SAN, cloud disks). Omnigent only references the claim;
+   it never creates volumes, so the server RBAC stays unchanged.
+2. List the claims under `sandbox.kubernetes.pvc_mounts` (see
+   `sandbox-config.yaml`). Mount paths may not overlap `/home/omnigent`, the
+   OS directories, or their ancestors (e.g. `/home`, `/var`) — the server
+   rejects such config at startup.
+
+Caveats:
+
+- **Multiple runners share writable claims concurrently** — use a
+  `ReadWriteMany`-capable backend (NFS/SMB/CephFS) for anything writable, and
+  prefer `read_only: true` (the default) everywhere else: a writable shared
+  mount lets one session's agent read and modify what another session wrote,
+  and anything written there outlives the Pod and its launch token.
+- Runner Pods run as uid/gid 1000660000 with `fsGroup`. NFS `root_squash` and
+  SMB ownership mapping must permit that identity (export to the uid, or use
+  CSI mount options like `uid=`/`gid=` for SMB); `fsGroupChangePolicy:
+  OnRootMismatch` avoids re-chowning large exports on every start.
+- `ReadWriteOnce` claims pin all runners to one node — combine with
+  `node_selector` deliberately, or the second Pod sits `Pending`.
+- A mount visible in the Pod is not automatically visible to a harness's own
+  OS-level sandbox (OmniBox path grants are separate).
+
+To verify `host_config` end to end against a live cluster, run
+`python tests/e2e/integrations/deploy/kubernetes/e2e_managed_host_config.py
+--server <url>` — it creates a managed session and asserts the injected
+config inside the runner Pod.
 
 ## Troubleshooting
 

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

@@ -19,6 +19,16 @@ data:
       # Service listens on port 80) is simplest; use your ingress URL if runner
       # Pods must reach the server through it.
       server_url: http://omnigent.omnigent.svc.cluster.local
+      # ── optional, provider-agnostic ──
+      # host_config:               # verbatim in-sandbox ~/.omnigent/config.yaml content,
+      #   providers:               # merged in before `omnigent host` starts — e.g. route
+      #     litellm:               # the `pi` harness through a self-hosted gateway.
+      #       kind: gateway        # Keep secrets out: api_key_ref: env: resolves inside
+      #       default: [pi]        # the runner Pod against the secret_name Secret below.
+      #       openai:
+      #         base_url: http://litellm.litellm.svc.cluster.local/v1
+      #         api_key_ref: env:LITELLM_API_KEY
+      #         wire_api: chat
       kubernetes:
         # Runner-Pod namespace (secret_name / service_account resolve here).
         namespace: omnigent-sandboxes
@@ -35,5 +45,9 @@ data:
         # resources:                 # runner Pod sizing (defaults: 0.5-2 cpu / 1-4Gi)
         #   requests: {cpu: "500m", memory: "1Gi"}
         #   limits: {cpu: "2", memory: "4Gi"}
+        # pvc_mounts:                # pre-created PVCs (in the runner namespace) mounted into every runner Pod
+        #   - claim_name: omnigent-datasets
+        #     mount_path: /mnt/datasets
+        #     read_only: true        # default true; set false only for claims meant as shared scratch
         # in_cluster: true           # config source: true=in-cluster SA only, false=kubeconfig only, omit=try both
         # kubeconfig: /path/to/config  # out-of-cluster kubeconfig (env: OMNIGENT_KUBERNETES_KUBECONFIG)

deploy/modal/README.md

@@ -50,23 +50,26 @@ the secret and redeploy.
 
 The first boot runs DB migrations over the network (~1 minute on Neon).
 
-**Get the admin password:** the first boot prints it to the app log:
+**Create the first admin.** No credentials are auto-generated. First boot
+prints a "No admin yet" line pointing at your `*.modal.run` URL:
 
 ```bash
 modal app logs omnigent
 ```
 
-```
-✓ Created initial admin account (accounts auth provider).
-    password: <generated>
-```
+Open that URL and use the web Create-admin form to pick your own username +
+password, then invite teammates from **Members** in the web UI.
 
-Log in as the admin and invite teammates from **Members** in the web UI.
-
-> To set a known admin password instead, add
-> `OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD=<password>` to the
+> To create the admin directly instead of claiming it through the web form,
+> add `OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD=<password>` to the
 > `omnigent-deploy` secret before the first deploy.
 
+> **Security note for public deployments:** `POST /auth/setup` is
+> unauthenticated while no password-bearing account exists, so an instance
+> exposed before you reach the Create-admin form can be claimed by the first
+> visitor. Pre-seed `OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD`, or complete setup
+> promptly after the deploy goes live.
+
 ### Modal-specific caveats
 
 - **2 MiB WebSocket message cap.** Modal's ingress limits WebSocket
@@ -302,6 +305,18 @@ sandbox:
     secrets: [omnigent-llm]                       # Modal secrets to inject
 ```
 
+A top-level `sandbox.host_config:` (provider-agnostic) holds verbatim
+in-sandbox `~/.omnigent/config.yaml` content — e.g. a `providers:`
+block routing a harness through a self-hosted gateway — installed into
+the sandbox before `omnigent host` starts. The block is server-managed:
+entries injected by a previous launch are replaced or removed on the
+next launch/resume, while config created inside the sandbox survives.
+Keep secrets out via
+`api_key_ref: env:VAR` (resolved in the sandbox against the injected
+env). See the [sandbox-runners config
+table](../kubernetes/overlays/sandbox-runners/README.md#configuration-sandbox-configyaml)
+for the shape.
+
 ### LLM credentials for managed sandboxes
 
 A fresh sandbox has no API keys. Park your provider credentials in a

deploy/openshell/README.md

@@ -14,7 +14,7 @@ This guide covers the Omnigent-specific OpenShell setup:
 - configure CLI-launched or server-managed sandboxes.
 
 ```bash
-pip install 'omnigent[openshell]'
+uv pip install 'omnigent[openshell]'
 ```
 
 Omnigent uses OpenShell two ways:
@@ -58,9 +58,9 @@ curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh |
 > **The gateway host must be amd64 Linux.** OpenShell's supervisor
 > (Landlock/seccomp/netns) does not run reliably under emulation — on an arm64
 > host (e.g. Apple Silicon via colima) the sandbox never reaches READY. The
-> official host image now publishes multi-arch (amd64 + arm64), but its arm64
-> variant omits `cel-expr-python` (no linux-arm64 wheel — CEL policies degrade to
-> unavailable there), so the amd64 variant is the one to run with OpenShell. On an
+> official host image now publishes multi-arch (amd64 + arm64). CEL policies are
+> available on all architectures (cel-python is pure Python), so the amd64 variant
+> is the one to run with OpenShell for supervisor reasons. On an
 > Apple-Silicon laptop, point the gateway at a remote **amd64 Linux** box (and the
 > server at that gateway) rather than the local Docker VM.
 
@@ -188,6 +188,18 @@ sandbox:
   server_url: https://your-host    # public URL sandboxes dial back to
 ```
 
+A top-level `sandbox.host_config:` (provider-agnostic) holds verbatim
+in-sandbox `~/.omnigent/config.yaml` content — e.g. a `providers:`
+block routing a harness through a self-hosted gateway — installed into
+the sandbox before `omnigent host` starts. The block is server-managed:
+entries injected by a previous launch are replaced or removed on the
+next launch/resume, while config created inside the sandbox survives.
+Keep secrets out via
+`api_key_ref: env:VAR` (resolved in the sandbox against the injected
+env). See the [sandbox-runners config
+table](../kubernetes/overlays/sandbox-runners/README.md#configuration-sandbox-configyaml)
+for the shape.
+
 `provider` + `server_url` is a complete config. Sessions created with
 `host_type: "managed"` (the API call or the Web UI's New Sandbox option) then run
 on a fresh OpenShell sandbox; the create returns immediately and provisioning
@@ -392,6 +404,6 @@ upload, foreground streaming, attach, terminate, env passthrough, error handling
 and the managed-config parsing:
 
 ```bash
-pip install -e '.[openshell,dev]'
+uv pip install -e '.[openshell,dev]'
 pytest tests/onboarding/sandboxes/test_openshell.py tests/server/test_managed_hosts.py
 ```

deploy/railway/README.md

@@ -47,14 +47,12 @@ steps below are validated end-to-end:
    reference value simply hadn't propagated yet — **redeploy** and it resolves.
    (To confirm, the app service should have a `DATABASE_URL` variable
    referencing the Postgres service, e.g. `${{Postgres.DATABASE_URL}}`.)
-3. **Get the admin password** from the first-boot **Deploy logs** (printed once;
-   idempotent — later boots don't reprint):
-   ```
-   ✓ Created initial admin account (accounts auth provider).
-       password: <generated>
-   ```
-   It's also written to `/data/admin-credentials`.
-4. Open the URL, log in as `admin`, invite teammates from **Members**.
+3. **Create the first admin.** No credentials are auto-generated. The
+   first-boot **Deploy logs** print a "No admin yet" line pointing at your
+   `*.up.railway.app` URL (printed once; idempotent — later boots don't
+   reprint). Open that URL and use the web Create-admin form to pick your own
+   username + password.
+4. Log in with the admin you just created, invite teammates from **Members**.
 
 > **`HOST` is handled automatically.** Railway injects `HOST=[::]`, which a
 > socket bind can't use and which Railway's IPv4 edge can't reach; the
@@ -69,6 +67,12 @@ steps below are validated end-to-end:
 > pin a known admin password, set `OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD`
 > before first boot.
 
+> **Security note for public deployments:** `POST /auth/setup` is
+> unauthenticated while no password-bearing account exists, so an instance
+> exposed before you reach the Create-admin form can be claimed by the first
+> visitor. Pre-seed `OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD`, or complete setup
+> promptly after the deploy goes live.
+
 ## Use your own IdP instead (OIDC)
 
 Prefer GitHub / Google / Okta login over built-in accounts? Switch the provider

deploy/render/README.md

@@ -23,8 +23,9 @@ The `render.yaml` blueprint at the repo root defines:
 - **omnigent-db** (`basic-256mb` managed Postgres) — `DATABASE_URL` is injected
   into the service automatically
 - **artifact-data** (10 GB persistent disk) — mounted at `/data` so server
-  config, first-boot credentials, cookie secrets, and agent artifacts survive
-  redeploys. Artifacts live under `/data/artifacts`.
+  config, the auto-minted cookie secret, and agent artifacts survive redeploys.
+  Artifacts live under `/data/artifacts`. (Account rows and password hashes
+  live in the managed Postgres, not on the disk.)
 
 ## Quickstart (built-in accounts — the default)
 
@@ -34,18 +35,22 @@ mints its own cookie secret and auto-detects its public URL from Render.
 
 1. Click the Deploy to Render button above → **Apply**. Wait ~3–5 min for the
    image pull + health check.
-2. **Get the admin password:** open the service → **Logs** and find the
-   first-boot block:
-   ```
-   ✓ Created initial admin account (accounts auth provider).
-       password: <generated>
-   ```
-   (also written to `/data/admin-credentials` on the disk; printed once).
-3. Open your `https://<service>.onrender.com` URL, log in as the admin, and
-   invite teammates from **Members** in the web UI.
+2. **Create the first admin.** No credentials are auto-generated. Open your
+   `https://<service>.onrender.com` URL — a fresh instance shows a
+   Create-admin form where you pick your own username + password. (First-boot
+   **Logs** also print a "No admin yet" line with that URL.)
+3. Log in as the admin you just created, and invite teammates from **Members**
+   in the web UI.
 
-> To set a known admin password instead of the generated one, add
-> `OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD` in the dashboard before first boot.
+> To create the admin directly instead of claiming it through the web form
+> (e.g. a headless deploy), add `OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD` in the
+> dashboard before first boot.
+
+> **Security note for public deployments:** `POST /auth/setup` is
+> unauthenticated while no password-bearing account exists, so an instance
+> exposed before you reach the Create-admin form can be claimed by the first
+> visitor. Pre-seed `OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD`, or complete setup
+> promptly after the deploy goes live.
 
 ## Use your own IdP instead (OIDC)
 

designs/DEVICE_AUTH.md

@@ -0,0 +1,357 @@
+# Delegated Auth — Device Authorization Grant (RFC 8628)
+
+> **IMPLEMENTED.**
+>
+> A generic, client-agnostic delegated-login mechanism. Slack is the first
+> consumer (`integrations/slack/`), but the server side carries no
+> Slack-specific concepts — the requesting application names itself with the
+> RFC 8628 `client_id` (a public string like `"slack"`; display/audit only).
+> It is a public OAuth client by default (no client secret), with an
+> **optional** shared secret (`OMNIGENT_DEVICE_CLIENT_SECRET`) that gates the
+> client-facing endpoints when set — see the phishing mitigations below.
+>
+> Server: `omnigent/server/routes/device_auth.py` (endpoints + the
+> `mint_delegated_token` / `DELEGATED_SCOPE` it owns),
+> `omnigent/server/device_grant_store.py`, `SqlDeviceGrant` +
+> `device_grants` migration (`d1e2f3a4b5c6`), and scope + revocation
+> enforcement in `omnigent/server/auth.py` (`delegated_path_allowed`,
+> `set_grant_revocation_check`). Wired in `omnigent/server/app.py`,
+> **opt-in and default-off** via `OMNIGENT_DEVICE_GRANT_ENABLED` (the
+> `/oauth/*` routes are unmounted unless it is truthy), and then only in
+> **accounts** mode (OIDC delegates login to the IdP via the cli-ticket
+> flow and never mounts these routes).
+> Slack: `integrations/slack/src/omnigent_slack/oauth.py`,
+> `tokens.py` (Fernet-encrypted `oauth_tokens`), `auth_manager.py`, plus
+> the bearer/refresh wiring in `omnigent.py` (`ClientAuth`,
+> per-`(server,user)` pool). Login is folded into the `/omnigent` setup
+> modal; `/omnigent logout` revokes + clears.
+>
+> **Auth-mode selection (Slack).** The bot probes the server's mode
+> (`oauth.probe_auth_mode` → `GET /v1/me`, mirroring the CLI) and picks
+> the flow: **accounts → this device grant**; **oidc → the server's
+> cli-login ticket flow** (`/auth/cli-login` + `/auth/cli-poll`), where
+> the user signs in at the IdP and the bot stores the server's session
+> JWT (no device grant, no refresh token). Both surface through one
+> `oauth.PendingLogin` shape so the setup/auth-manager code is
+> flow-agnostic. **Header/proxy mode is unsupported** — the server mints
+> no token and mounts no device-grant/cli-login router in that mode
+> (`app.py`: device auth is `oidc`/`accounts` only), so `start_login`
+> raises a clear error rather than firing a request the server would 404.
+>
+> Tests: `tests/server/test_device_auth.py`, and the Slack
+> `test_oauth.py` / `test_tokens.py` / `test_client_auth.py` /
+> `test_auth_manager.py`.
+
+## Problem
+
+The Slack integration (`integrations/slack/`) is a standalone Socket-Mode
+process that calls each user's Omnigent server over HTTP + SSE
+(`OmnigentClient` / `OmnigentClientPool`). Each Slack user's turns must reach
+the Omnigent server **as that user's own authenticated identity** — so the
+server can scope permissions and audit who did what — **without the Slack
+process ever handling the user's Omnigent credentials**. An unauthenticated
+client can only reach auth-disabled servers, and would present one shared
+anonymous identity the server can't distinguish per user.
+
+## Topology and trust
+
+```
+  omnigent server   <->   slack socket server   <->   slack.com   <->   user
+  (Auth + Resource        (OAuth client /             (transport)      (browser =
+   Server)                 "device")                                    Resource Owner)
+```
+
+Slack relays all messages between the user and the socket server, so **no
+Omnigent credential may pass through Slack**. The user authenticates directly
+against the Omnigent server in their own browser, out of band. This is exactly
+the shape of the **OAuth 2.0 Device Authorization Grant (RFC 8628)**: a device
+that cannot host a browser obtains a code, the user approves out-of-band, and
+the device polls for a token.
+
+Role mapping:
+
+| RFC 8628 role            | Here                                            |
+|--------------------------|-------------------------------------------------|
+| Authorization Server     | Omnigent server (`/oauth/device/*`, `/oauth/token`) |
+| Resource Server          | Omnigent server (existing `/v1/**` APIs)        |
+| Client / "device"        | Slack socket server                             |
+| Resource Owner           | The Slack user, authenticating in their browser |
+| Out-of-band channel      | Slack (delivers the verification link only)     |
+
+## Shared substrate (reused, not rebuilt)
+
+The device grant builds on existing server primitives:
+
+- **Atomic single-use token redemption** — `SqlAlchemyAccountStore.redeem_token`
+  uses `UPDATE … WHERE redeemed_at IS NULL` + rowcount so at most one caller
+  wins under concurrency (`accounts_store.py`). The grant store follows the
+  same pattern.
+- **Session JWT minting** — `mint_session_token(user_id, secret, ttl, provider)`
+  (`oidc.py`), HS256 with `sub`/`iat`/`exp`/`provider`.
+- **Bearer validation** — `UnifiedAuthProvider._check_cookie` accepts
+  `Authorization: Bearer <jwt>` and validates the same claim shape
+  (`auth.py`). Delegated access tokens validate through this path unchanged.
+- **Browser consent under accounts mode** — the `accounts` provider
+  establishes the browser identity via its session cookie; the consent page
+  runs behind it. (This is why the grant mounts in accounts mode only — see
+  the mount restriction below.)
+- **Open-redirect hardening** — `_sanitize_return_to` (`routes/auth.py`) guards
+  the post-login bounce back to the consent page.
+
+## Design decisions (agreed)
+
+1. **Public by default, optional client secret.** The baseline boundary is
+   the secret `device_code` the client holds, the ephemeral verification
+   link, and authenticated in-browser consent; initiation is per-IP
+   rate-limited and nothing is granted until a real user approves. On top of
+   that, setting `OMNIGENT_DEVICE_CLIENT_SECRET` on the server gates the
+   **client-facing** endpoints (authorize / token / revoke) behind a shared
+   secret header (`X-Omnigent-Client-Secret`, constant-time compared), so
+   only an authorized client can drive the flow. The **browser** endpoints
+   (consent GET / approve / deny) are never gated by it — the user's browser
+   doesn't hold the secret; their trust is the session cookie + Origin check.
+   Unset ⇒ endpoints stay public (backward compatible). Shipping the secret to
+   the Slack client is safe because its target is a **fixed operator config**
+   (`OMNIGENT_SERVER_URL`), not a user-supplied URL, so the secret only ever
+   travels to the trusted server.
+2. **Refresh tokens** — short-lived access tokens (≤ 1 h) plus a rotating,
+   revocable refresh token, with a 30-day absolute grant lifetime. The Slack
+   server refreshes silently; a stolen access token expires quickly and a grant
+   can be killed centrally or ages out on its own.
+
+## Flow
+
+```
+ 1. A Slack user opens the `/omnigent` setup modal against an
+       accounts-mode server; the modal detects auth is required and starts
+       the device flow (there is no separate login command).
+
+ 2. Slack server ─ POST /oauth/device/authorize ─────────────▶ Omnigent
+       body: { client_id }        # public app name, e.g. "slack"
+    Omnigent ─────────────────────────────────────────────────▶ Slack server
+       { device_code,            # secret, HELD BY SLACK SERVER ONLY
+         user_code,              # short, human-readable
+         verification_uri,       # e.g. https://srv/oauth/device
+         verification_uri_complete,   # verification_uri?user_code=XYZ
+         expires_in: 600, interval: 5 }
+
+ 3. Slack server shows the verification link (verification_uri_complete,
+       code prefilled for one-click) in the setup modal (initiator only),
+       plus the user_code so the user can confirm the match. The
+       device_code is NOT included — it never leaves the server pair.
+
+ 4. User clicks → Omnigent consent page (verification_uri).
+       The page REQUIRES a login started for THIS flow: if the browser's
+       session predates the grant (session iat < grant.created_at), it
+       bounces through the login page with ?reauth=1 — which forces a fresh
+       password entry even for an already-signed-in user — and returns here.
+       Once re-authenticated, the page shows: "<client_id> is requesting
+       permission to act as YOU (alice@example.com) on this Omnigent server.
+       [Approve] [Deny]" plus a warning to approve only a self-started login.
+       The forced re-auth means a grant can't be approved by one reflexive
+       click on a link the user didn't personally start (see threat #2).
+
+ 5. User approves → the grant is bound to the authenticated identity
+       (alice@…). client_id is recorded for display/audit only, never as
+       an authorization key.
+
+ 6. Slack server polls ─ POST /oauth/token ──────────────────▶ Omnigent
+       grant_type=urn:ietf:params:oauth:grant-type:device_code
+       { device_code }
+    Responses: 400 authorization_pending | 429 slow_down |
+               400 expired_token | 400 access_denied |
+               400 invalid_grant |
+               200 { access_token, refresh_token, expires_in, token_type }
+
+ 7. Slack server stores  (team_id, slack_user_id, server_url)
+       → { access_token, refresh_token }  ENCRYPTED AT REST,
+       and attaches  Authorization: Bearer <access_token>  on every
+       request for that user thereafter.
+
+ 8. On 401 / near-expiry: POST /oauth/token grant_type=refresh_token →
+       new access + rotated refresh.  On refresh failure (revoked/expired):
+       drop tokens and re-prompt login in the setup modal.
+```
+
+The Slack `(team_id, slack_user_id)` → identity mapping lives entirely on
+the Slack side (step 7). The server-side grant is client-agnostic: it
+knows only the RFC 8628 `client_id` and the Omnigent identity that
+approved it.
+
+## Server-side changes
+
+### Router `omnigent/server/routes/device_auth.py`
+
+Mounted in `app.py` only when **`OMNIGENT_DEVICE_GRANT_ENABLED` is truthy**
+(opt-in, **default-off** — the `/oauth/*` routes are absent otherwise), and
+then **only in `accounts` mode** (OIDC delegates login to the IdP via the
+cli-ticket flow and never mounts these routes; header mode has no
+server-mintable identity — see `create_device_auth_router`, which raises if
+constructed for any other source). The `device_grants` table is created
+unconditionally by the migration regardless of the flag; only the router
+mount is gated. This router **owns** `mint_delegated_token` and
+`DELEGATED_SCOPE`.
+
+- `POST /oauth/device/authorize` — **public** (rate-limited). Generates a
+  high-entropy `device_code` (`secrets.token_urlsafe`, stored **hashed**), a
+  short `user_code`, `expires_in`, `interval`. Persists a `pending` grant
+  carrying only the public `client_id`. Returns the RFC 8628 authorize
+  response. Opportunistically purges expired grants (no scheduler).
+- `GET /oauth/device` — the consent page (`verification_uri`). Requires a
+  browser identity via the active provider; if unauthenticated, bounce through
+  the provider's normal login and return here (`_sanitize_return_to`). Prefills
+  `user_code` from `verification_uri_complete`.
+- `POST /oauth/device/approve` / `POST /oauth/device/deny` — authenticated
+  browser actions, CSRF-gated by `_require_browser_origin` (rejects a missing
+  Origin). `approve` binds the grant to the authenticated `user_id` (`sub`),
+  stamps `approved_at` (the absolute-lifetime clock), and flips status to
+  `approved`; `deny` flips to `denied`.
+- `POST /oauth/token`:
+  - `grant_type=…:device_code` — look up by hashed `device_code`; return
+    `authorization_pending` / `slow_down` (interval enforcement) /
+    `expired_token` / `access_denied` / `invalid_grant`, or on approval mint an
+    **access token** (`mint_delegated_token`, TTL ≤ 1 h) + **refresh token** and
+    return them. Single-use: an atomic `approved → redeemed` transition means
+    the device_code cannot be exchanged twice.
+  - `grant_type=refresh_token` — validate the presented refresh token against
+    the stored hash, **rotate** it (issue new, invalidate old), mint a new
+    access token. Refuses rotation past the 30-day absolute lifetime
+    (`expired_token`). **Reuse detection**: presenting an already-rotated
+    refresh token revokes the whole grant (token-theft signal).
+- `POST /oauth/revoke` — revoke a grant: null the refresh token, mark revoked
+  (the `grant_id` then reads as revoked in the denylist check). Accepts a
+  `refresh_token`, or falls back to the `grant_id` on the caller's own bearer
+  so a client holding only its access token can still log out. Idempotent.
+  Backs `/omnigent logout`.
+
+### New store `omnigent/server/device_grant_store.py`
+
+Modeled on `SqlAlchemyAccountStore` — workspace-scoped, secrets stored hashed,
+atomic single-use redemption, `purge_expired`. New table `device_grants`:
+
+| column               | notes                                              |
+|----------------------|----------------------------------------------------|
+| `id` (grant id)      | PK with `workspace_id`                             |
+| `device_code_hash`   | HMAC/SHA-256 of the device_code; never store raw   |
+| `user_code`          | short code shown/typed by the user                 |
+| `client_id`          | RFC 8628 client id — the requesting application (e.g. `slack`); display + audit |
+| `status`             | `pending` / `approved` / `denied` / `redeemed` / `revoked` |
+| `user_id`            | bound Omnigent identity, set at approval           |
+| `refresh_token_hash` / `prev_refresh_token_hash` | current + prior digest (rotation + reuse detection) |
+| `created_at` / `expires_at` / `approved_at` / `last_polled_at` | TTL, absolute-lifetime clock, `slow_down` timing |
+
+### Token claims and validation (`auth.py`, `device_auth.py`)
+
+Delegated access tokens (minted by `mint_delegated_token`) keep the existing
+HS256 shape (so `_check_cookie` accepts them) plus four delegated-only claims:
+
+- `act` — provenance, RFC 8693-style: `{ "client_id": "slack" }`, naming the
+  application that obtained the grant so every delegated action is attributable
+  to it.
+- `scope` — set to `DELEGATED_SCOPE` (`"sessions"`). The auth layer's
+  fail-closed allowlist `delegated_path_allowed` restricts a token carrying
+  this scope to `/health`, `/v1/agents`, `/v1/hosts`, `/v1/sessions`,
+  `/v1/runners`, `/oauth/token`, `/oauth/revoke` (exact or `prefix/…`);
+  everything else — including admin / user-management (`/auth/users*`, invites,
+  setup) — is rejected.
+- `grant_id` — checked against the revoked-grant denylist (`is_revoked`, wired
+  via `set_grant_revocation_check`) on **every** request for a delegated token,
+  so revoking the grant kills the token immediately. Delegated tokens carrying
+  a `grant_id` skip the credential cache (they return before the cache write),
+  keeping the per-request revocation check honest without making ordinary
+  (non-delegated) sessions stateful. Fail-closed: an unknown `grant_id` reads
+  as revoked.
+- `jti` — unique token id for audit/log correlation (not a revocation key;
+  revocation is grant-scoped, not per-token).
+
+## Slack-side changes
+
+- **`oauth.py`** — device-authorize → post ephemeral link → poll token
+  endpoint (respecting `interval` / `slow_down`) → store tokens.
+- **`omnigent.py`** — attach `Authorization: Bearer` per
+  `(server_url, slack_user_id)`; on 401, refresh once and retry; on refresh
+  failure, surface a re-login prompt. `OmnigentClientPool` keys clients by
+  `(server_url, slack_user_id)` instead of `server_url` alone.
+- **`store.py`** — new `oauth_tokens` table `(team_id, user_id, server_url)` →
+  access/refresh **encrypted at rest** (key from env / secret manager, never in
+  the DB). `/omnigent logout` → `POST /oauth/revoke` + local delete.
+- **`setup.py`** — validation uses the user's token, so auth-enabled servers
+  are supported.
+- **`config.py`** — holds the local encryption key for token storage.
+
+## Security analysis
+
+| # | Threat | Mitigation |
+|---|--------|-----------|
+| 1 | `device_code` leak → token theft | Never transits Slack or the user — only `verification_uri_complete` (a `user_code`) does. Stored hashed; single-use. |
+| 2 | Link misdelivery / phishing another user | Link shown to the initiator only (in their own setup modal). **Consent requires a login started FOR this flow: the consent page rejects a session whose `iat` predates the grant and bounces through the login page with `reauth=1`, forcing a fresh password entry even for an already-signed-in user.** So an attacker-initiated flow can't be approved by a single reflexive click — the victim must deliberately re-enter their password against a screen naming the exact Omnigent identity and requesting `client_id`. The gate is enforced on both the consent GET and the approve POST. |
+| 3 | Anyone can initiate/poll (public client) | Cheap `pending` state grants nothing until an authenticated user approves. `POST /oauth/device/authorize` is rate-limited per client IP (10/60s → 429 `slow_down`); short (10 min) `device_code` expiry; `slow_down` enforced server-side on aggressive polling; expired grants purged opportunistically. |
+| 4 | Slack SQLite exfiltration → mass impersonation | Tokens **encrypted at rest**; access tokens short-lived (≤ 1 h); refresh tokens revocable. Bounded, centrally killable window. |
+| 5 | Compromised Slack server acts as all users (inherent to delegation) | Reduced scope (no admin), short TTL + refresh rotation, per-grant revocation, **absolute grant lifetime (30 d) enforced on refresh** so even an un-revoked grant dies, and an `act`-claim audit trail. |
+| 6 | Confused deputy — user A's token used for user B | On the Slack side, token lookup is strictly keyed by acting `slack_user_id`; the thread `owner_user_id` gate drops non-owner follow-ups (`service.py`). |
+| 7 | Stale/leaked delegated token can't be revoked | Per-grant `grant_id` revocation denylist (`is_revoked`, checked every request) makes delegated-token revocation immediate — closes today's stateless-JWT gap for these higher-value tokens. |
+| 8 | Refresh-token theft | Rotation on every use + **reuse detection**: the just-superseded token's digest is retained in `prev_refresh_token_hash`; presenting it (a replay) is recognised and revokes the whole grant, killing the attacker's freshly-rotated token too. |
+| 9 | Transport interception | Require HTTPS for `verification_uri` and all token/bearer traffic; refuse the flow over plaintext except localhost dev. |
+| 10 | Open redirect on the consent login bounce | Reuse `_sanitize_return_to` (OIDC, `routes/auth.py`) / `sanitizeReturnTo` (accounts SPA). Verified both providers reject absolute / `//` targets. |
+| 11 | CSRF on approve/deny if `SameSite=none` is ever enabled | `_require_browser_origin` rejects a **missing** `Origin` on approve/deny (stricter than the shared `require_trusted_origin`, which fail-opens for non-browser clients). These routes are browser-only, so the CSRF defense no longer depends on the cookie's `SameSite`. |
+
+### Device-code phishing — accepted risk, mitigated in depth
+
+The canonical RFC 8628 risk: a stranger initiates a flow and tricks a victim
+Omnigent user into approving the verification link, binding the grant to the
+*victim's* identity while the attacker (holding the `device_code`) polls for the
+token.
+
+When no client secret is configured the endpoints are **public**, so
+initiation is open — the defense is layered, not a gate:
+
+- **Forced re-authentication at consent.** Consent requires a login started for
+  THIS flow: the consent page (and the approve POST) reject a session whose
+  `iat` predates the grant's `created_at` and bounce through the login page with
+  `reauth=1`, which forces a fresh password entry even for an already-signed-in
+  user. This defeats the reflex-approve variant of the attack — a victim handed a
+  one-click link (even one with the code prefilled) still can't bind the grant
+  without deliberately re-entering their password against a screen naming the
+  exact identity and client. (`device_auth.py` `_session_iat` + the
+  `reauth=1` bounce; `LoginPage.tsx` suppresses its already-signed-in
+  auto-return under `reauth=1`.) The prefilled one-click link is therefore
+  retained for convenience — the re-auth step, not code handling, is the gate.
+- The consent page prominently **warns** the user to approve only a login they
+  personally started and to match the code shown by the application.
+- The delegated scope excludes admin / user-management endpoints.
+- The grant has a 30-day absolute lifetime and is revocable; a leaked/phished
+  grant self-expires even if never revoked.
+- Initiation is rate-limited per IP; nothing is granted until a real user
+  authenticates and approves in their own browser.
+- **Startup warning.** When the grant is mounted on a multi-user (accounts)
+  server with `OMNIGENT_DEVICE_CLIENT_SECRET` unset, the server logs a loud
+  warning at startup that the authorize endpoint is public — nudging the
+  operator to opt into the secret rather than leaving initiation open unknowingly
+  (`app.py`, at the device-router mount).
+
+Setting `OMNIGENT_DEVICE_CLIENT_SECRET` closes initiation entirely to
+unauthorized callers: without the matching `X-Omnigent-Client-Secret` header,
+authorize / token / revoke return `401 invalid_client` before anything is
+created, so only the operator's own client (which holds the secret) can even
+start a flow. This is now shippable to the Slack client because its server
+target is a fixed operator config, not a user-supplied URL — the secret only
+ever travels to the trusted server. The consent-page warning, short TTL, and
+absolute lifetime remain the defenses when the secret is left unset.
+
+### Deliberate deviation from the current model
+
+Ordinary Omnigent session JWTs are stateless and unrevocable today (revocation =
+cookie deletion + expiry). Delegated tokens are higher-value — one server acts
+for many users — so this design makes **delegated** tokens revocable (persisted
+grant + per-`grant_id` revocation check) while leaving normal sessions
+stateless. This added invariant is the main thing for reviewers to scrutinize.
+
+## Out of scope / follow-ups
+
+- Admin UI for listing and revoking active Slack delegations.
+- Multi-replica rate limiting: the authorize throttle is in-process; a
+  horizontally-scaled server would want a shared store (the grant table's
+  single-use/expiry semantics already bound abuse in the meantime).
+- Applying the same delegated grant to other non-browser clients (the CLI could
+  use it too, superseding the in-memory `_cli_tickets` store).
+- Per-scope consent granularity beyond the single "session APIs, no admin" scope.

designs/PROJECTS_PRD.md

@@ -0,0 +1,664 @@
+# PRD: Projects
+
+- Status: Draft
+- Author: Serena Ruan
+- Related: [`designs/SESSION_PROJECTS_SIDEBAR.md`](./SESSION_PROJECTS_SIDEBAR.md) (v1, label-based sidebar grouping), issue [#863](https://github.com/omnigent-ai/omnigent/issues/863), PR [#869](https://github.com/omnigent-ai/omnigent/pull/869)
+
+## 1. Overview
+
+A **Project** is a user-defined container that groups related sessions and
+carries owner-private configuration (memory, context, a default working
+directory). It gives users a durable "workspace" above the single session, so
+recurring work isn't re-configured each time or scattered across a flat list.
+
+This PRD scopes the **full vision**. A **v1** already exists (§4): projects as a
+reserved `omni_project` label, grouped in the sidebar — this covers grouping
+only. Everything else (empty projects, rename/reorder, memory/context/defaults)
+requires promoting Project from a *label* to a *first-class entity*.
+
+Two decisions shape the whole design and are worth stating up front:
+- **A project is owner-private metadata.** Sharing stays **per-session** exactly
+  as it is today; there is **no project-level ACL** (§9).
+- **Memory & context are owner-private** and never cross to a shared session's
+  recipient. A shared session appears **ungrouped** to the recipient (§9).
+
+## 2. Summary — what we support & UX impact
+
+Priority order (highest first), per product direction:
+
+| # | Capability | Support? | Mechanism | UX impact |
+|---|---|---|---|---|
+| 1 | **Create empty project** | ✅ | first-class `projects` table (needed for empty) | Always-visible **Projects** section in the sidebar; "New project" creates one with zero sessions |
+| 2 | **Move session in / create session in project** | ✅ | `project_id` FK on session | Session-row kebab "Add to / Move / Remove from project"; "New session here" from a project header, pre-filling its defaults |
+| 3 | **Rename projects** | ✅ | `PATCH /projects/{id}` on `name` (members untouched) | Inline rename from the project header |
+| 4a | **Default working dir / host / harness** | ✅ (soft hints) | default columns on project | "New session here" pre-fills the new-chat dialog; unsatisfiable hints (host offline / not owned) are silently dropped |
+| 4b | **Project memory** (owner-private) | ✅ | DB-backed, scoped to project, host-agnostic | Agent accumulates learnings across the project's sessions; never exposed to shared-session recipients |
+| 4c | **Project context** (owner-private) | ✅ | curated docs/instructions attached to project | Owner-curated inputs seed each session started in the project |
+| 5 | **Project-level sharing / ACL** | ❌ intentional | — | Sharing stays **per-session** (existing ACL). A shared session appears **ungrouped** in the recipient's "Shared with me" — no project, no memory/context |
+| opt | **Reorder projects** | 🔵 optional | client-only (localStorage, no DB column) | Drag-to-reorder in the sidebar; nice-to-have, not required for launch — see §7.2 |
+
+**Two-line model:**
+- Project = **owner-private organizer** carrying defaults + memory + context.
+- Sharing = **per-session only**; a shared session crosses the ACL boundary, its
+  project membership and memory/context do **not**.
+
+## 3. Where we are today (grounding)
+
+The exploration of the current codebase established the following, which every
+requirement below builds on:
+
+- **Session = `Conversation`** (`omnigent/entities/conversation.py`). Key fields:
+  `id`, `title`, `runner_id`, `host_id`, `workspace` (absolute path, **immutable
+  after creation**), `git_branch`, `model_override`, `reasoning_effort`,
+  `harness_override`, `cost_control_mode_override`, `labels`, `session_state`,
+  `archived`.
+- **Session creation** goes through `POST /v1/sessions`
+  (`SessionCreateRequest`, `omnigent/server/schemas.py`) with `agent_id`,
+  `host_type` (`external` | `managed`), `host_id`, `workspace`, optional `git`
+  worktree spec, and per-session overrides. UX lives in
+  `web/src/shell/NewChatDialog.tsx`.
+- **Working directory & host**: `workspace` is a path on a `host` (a machine
+  running `omnigent host`, or a server-managed sandbox). Bound at creation,
+  immutable thereafter. Git worktrees are opt-in at create time.
+- **Memory/context today**: only `session_state` (per-session key/value for
+  policy callables) and `session_usage`. There is **no cross-session or
+  project-level memory** and no shared context store.
+- **Permissions**: per-`(user_id, conversation_id)` rows with levels
+  read(1)/edit(2)/manage(3)/owner(4) (`omnigent/db/db_models.py`,
+  `omnigent/entities/permission.py`). `__public__` sentinel grants public read.
+  No org/team model. `workspace_id` is a multi-tenancy partition key, not a
+  user-facing grouping.
+- **Projects v1 already exists**: reserved label `omni_project` in
+  `conversation_labels`; endpoints `GET /v1/sessions/projects` and
+  `?project=<name>` filtering; `useProjects()` / `useMoveToProject()` hooks;
+  sidebar grouping. Projects are **implicit** — a project exists iff a
+  non-archived session references it, and vanishes when its last member leaves.
+  **There is no project row, so a project cannot be empty, renamed, or carry its
+  own config.**
+
+## 4. Key architectural decision: implicit label vs. first-class entity
+
+This is the foundational decision. Every requirement below except plain grouping
+requires promoting Project from a label to a first-class entity.
+
+| Capability | Implicit label (v1 today) | First-class entity (this PRD) |
+|---|---|---|
+| Group sessions | ✅ | ✅ |
+| Empty project | ❌ (project = its members) | ✅ |
+| Rename (cheap, safe) | ❌ (rewrite every member) | ✅ (rename the row) |
+| Project defaults (dir/host/model) | ❌ nowhere to store | ✅ (columns on project) |
+| Project memory/context | ❌ nowhere to attach | ✅ (FK to project) |
+| DB migration required | ❌ none | ✅ new table + backfill |
+
+**Recommendation:** ship v1 (labels) for grouping now, then **promote to a
+first-class `projects` entity** as the foundation for the rest.
+Migration: create `projects` rows from the distinct `omni_project` label values
+per owner, point sessions at `project_id`, retire the label. This is a one-time
+backfill, not user-visible.
+
+Proposed model, referenced throughout:
+- New `projects` table: `id`, `workspace_id`, `name`, `owner`, `created_at`,
+  `updated_at`, plus the config columns from §8. (No `position` column —
+  reorder is deferred and client-only, §7.2.)
+- Session→project membership = nullable `project_id` FK on conversation
+  metadata. `null` = unfiled. FK (over label-of-id) is cleaner for renames and
+  referential integrity.
+- CRUD endpoints: `POST /v1/projects`, `GET /v1/projects`,
+  `PATCH /v1/projects/{id}`, `DELETE /v1/projects/{id}`.
+
+## 5. Priority 1 — Create empty project
+
+### 5.1 What
+Create a project with **zero sessions**, then fill it later.
+
+### 5.2 Why this needs a first-class entity
+Under the implicit-label model a project *is* its set of member sessions — an
+empty project has no rows and therefore does not exist. Supporting empty
+projects **requires the `projects` table** from §4.
+
+### 5.3 UX
+- The sidebar always shows a **Projects** section, even with zero projects, so
+  the create-empty-then-fill flow is discoverable (not a hidden label action).
+- "New project" creates a named, empty project (`POST /v1/projects`).
+- **Deletion:** deleting a project with members prompts — (a) delete the project
+  and unfile its sessions (sessions kept) or (b) block until empty. **Proposed:
+  (a)** with confirmation. Never cascade-delete sessions. This replaces v1's
+  "archive all members to make the project vanish" behavior.
+
+### 5.4 Why ship empty-project creation first
+
+It's the right first slice — not just because it's P1, but because it's the
+**minimal change that forces the first-class entity**, which everything else
+builds on for free. An empty project is definitionally impossible under the v1
+label model (a label-project *is* its members), so "create empty project" *is*
+the `projects` table + the `project_id` membership column. Once those exist,
+move/rename/reorder/defaults are small additions on the same schema.
+
+Phase 1 is therefore exactly two schema changes: a new `projects` table, and a
+`project_id` column on the conversation metadata row. Config/memory/context
+columns (§8) are **deferred to Phase 2/3** — start with a lean table so Phase 1
+stays small and reversible.
+
+### 5.5 Proposed Phase-1 schema
+
+Follows the repo's conventions from the most recent table (`scheduled_tasks`,
+migration `z6…`, `omnigent/db/db_models.py`): `workspace_id` leads the PK, **no
+DB foreign keys** (schema Rule R032 — relationships enforced in the app), owner
+scoping via a `*_user_id` column, epoch-seconds timestamps.
+
+```python
+class SqlProject(OmnigentBase):
+    """A user-defined, owner-private container that groups sessions."""
+    __tablename__ = "projects"
+
+    workspace_id: Mapped[int] = mapped_column(
+        BigInteger, primary_key=True, nullable=False,
+        server_default="0", default=current_workspace_id,
+    )
+    # "proj_"-prefixed string id (not Uuid16) so it reads as a sibling of
+    # conversation ids and lives naturally in the metadata String column.
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    name: Mapped[str] = mapped_column(String(256), nullable=False)
+    # Owner stamped on the row (like scheduled_tasks), NOT derived from a
+    # permission table the way session ownership is. Correct here precisely
+    # because projects have no ACL and are owner-private (§9) — see the
+    # "Where ownership lives" note below. None in single-user/OSS mode.
+    owner_user_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    created_at: Mapped[int] = mapped_column(Integer, nullable=False)
+    updated_at: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    # No `position` column: ordering is deferred and, when added, will be a
+    # client-only concern (localStorage), not server state — see §7.2.
+
+    __table_args__ = (
+        # "list my projects": prefix scan on (workspace_id, owner). Server
+        # returns a stable order (e.g. created_at / name); the client may
+        # re-order locally.
+        Index("ix_projects_owner", "workspace_id", "owner_user_id", "id"),
+        # Per-owner name uniqueness (§7.1); app validates too.
+        Index("uq_projects_owner_name", "workspace_id", "owner_user_id", "name", unique=True),
+    )
+```
+
+Membership is one nullable column on the existing metadata table
+(`SqlConversationMetadata`, `omnigent_conversation_metadata`):
+
+```python
+# Relates to projects.id; no DB FK (Rule R032). NULL = unfiled.
+project_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+# In __table_args__ — "list sessions in project X" + counts (GROUP BY project_id):
+Index("ix_conversation_metadata_project_id", "workspace_id", "project_id", "id"),
+```
+
+**Column decisions worth sign-off:**
+
+| Choice | Proposed | Rationale / alternative |
+|---|---|---|
+| `id` type | `String(64)`, `proj_`-prefixed | Reads as a sibling of `conv_…` ids; lives in the metadata String column. Newest tables use `Uuid16` — diverge here for readability + column symmetry. |
+| Membership location | `project_id` on `omnigent_conversation_metadata` | Metadata already holds host/workspace/runner; `list_conversations` can filter it inline. |
+| Name uniqueness | per-`(workspace, owner)` unique index | Matches §7.1; case-sensitivity still open (Q3). |
+| Ownership | `owner_user_id` **column on the row** | See "Where ownership lives" below — differs from sessions on purpose. |
+| Ordering | **no `position` column** | Reorder is deferred and client-only (§7.2); no server state until proven needed. |
+| Deferred columns | default host/workspace/harness/model, memory/context refs | Added in Phase 2/3, not now. |
+
+**Where ownership lives (why a column, not the permission table).** The repo has
+two ownership conventions, and which is correct depends on whether the entity is
+shareable:
+
+- **Sessions** have *no* owner column — ownership is derived from
+  `session_permissions` as the `LEVEL_OWNER` grantee (`get_session_owner`,
+  `list_projects(owned_by=...)`). This is required *because sessions are shared*:
+  ownership is just the top row among many `(user, level)` grants.
+- **`scheduled_tasks`** — a personal, non-shareable artifact with no ACL — instead
+  stamps `owner_user_id` directly on the row (`db_models.py:1298`), indexed
+  `(workspace_id, owner_user_id, id)`.
+
+Projects follow `scheduled_tasks`, not sessions, **because §9 gives them no
+project-level ACL** — they're owner-private, single-owner, never granted to
+anyone else. With no `project_permissions` table to derive from, `owner_user_id`
+on the row is the correct and consistent choice. (The v1 label-based
+`list_projects` derives ownership from `session_permissions` only because a label
+has no row of its own to stamp — the first-class table removes that constraint.)
+If §9 is ever reversed and projects become shareable, we would drop this column
+and derive ownership from a `project_permissions` ACL, mirroring sessions.
+
+**Migration (mirrors `z6…`):** `op.create_table("projects", …)` with the two
+indexes; `op.add_column("omnigent_conversation_metadata", project_id)` + its
+index. **No backfill needed** for empty-project support — existing sessions stay
+`project_id = NULL` (unfiled). The `omni_project`-label → `project_id` backfill
+is a **separate, later** step (only when migrating v1 label-projects), kept out
+of this migration so Phase 1 stays clean and reversible.
+
+## 6. Priority 2 — Move session in / create session in project
+
+### 6.1 What
+Move existing sessions into (or out of) a project, and start new sessions
+already filed in a project.
+
+### 6.2 UX — how a session joins a project
+
+We deliberately **do not** add a project picker to the generic new-chat dialog.
+That dialog is already dense (agent, host, workspace, git, model, effort,
+permission mode); a picker would complicate the most-used "just start a chat"
+flow. Sessions join projects from the project surface instead:
+
+| Path | Behavior |
+|---|---|
+| **New session within a project** (primary) | From a project's header, "New session here" opens the new-chat dialog with the project pre-set and its defaults (host/workspace/harness — §8) pre-filled. This is where "create in project" happens. |
+| **After creation** (session-row kebab) | "Add to / Change / Remove from project" submenu, `PATCH /v1/sessions/{id}` — for reorganizing existing sessions. |
+
+- "Move session in/out" = update `project_id`. Moving to `null` = unfiled.
+- Membership is the **owner's** private metadata (see §9): a session's project
+  is scoped to its owner and does not travel to other viewers.
+
+### 6.3 Sidebar & navigation
+- Collapsible project sections, per-project counts (server-authoritative via
+  `GET /v1/sessions/projects`, not the loaded page).
+- Section precedence, highest wins: **Archived > Pinned > Project > Chats**
+  (from v1 design §7). Confirm this survives the first-class-entity move.
+- Filtering: `GET /v1/sessions?project=<id>`, incl. unfiled.
+- Pagination correctness: counts from server `GROUP BY`; expand-time fetch of a
+  project's full member list (v1 design §8).
+
+## 7. Priority 3 — Rename projects
+
+- First-class entity makes this a single `PATCH /v1/projects/{id}` on `name` —
+  members are unaffected (they reference `project_id`, not the name string).
+- Under v1 labels, rename means rewriting the label on every member (racy,
+  O(members), breaks on unloaded pages) — another reason to go first-class.
+- Validation: trim; reject empty/whitespace-only; max length (propose 100);
+  **case-sensitive**, unique **per owner** (`workspace_id` + `owner` scope).
+  Confirm case-sensitivity.
+
+### 7.2 Optional — Reorder projects (client-only, not required)
+- **Optional, not a launch requirement, and not a DB concern.** We deliberately
+  do **not** add a `position` column. The server returns projects in a stable
+  order (e.g. by `created_at` or name); manual ordering is a nice-to-have we can
+  add later without a schema change.
+- When we do add it, reorder should be a **client-only** preference (persisted in
+  localStorage, like the existing collapsed-section state) rather than server
+  state. Since projects are owner-private (§9), there's no shared-ordering
+  concern to force it into the DB — an owner's arrangement is theirs alone, and a
+  local preference is enough. Promoting it to a server column is a reversible
+  future step if cross-device ordering is ever wanted.
+
+## 8. Priority 4 — Project config: default working dir, host, memory & context
+
+Break into the three sub-capabilities. All are **owner-private** (§9).
+
+### 8.1 Default working directory & host
+- **What:** a project stores a default `host_id` + `workspace` (and optionally
+  default `git` base-branch / worktree policy, harness, model, reasoning
+  effort). New sessions created "in" the project pre-fill these.
+- **How it works with the host model:** `workspace` is a path *on a specific
+  host*, and hosts are user-owned machines/sandboxes that go online/offline.
+  Implications to design for:
+  - The project's default host may be **offline** at session-create time →
+    fall back to prompting for host, keep the workspace path as a hint.
+  - For **managed** hosts, the "workspace" is a git repo URL that provisions a
+    fresh sandbox per session — the project default is the repo URL + branch
+    policy, not a live path.
+  - Working directory remains **immutable per session** (existing constraint);
+    the project only seeds the *initial* value.
+  - **Proposed:** store project defaults as *hints*, never hard requirements —
+    the new-chat dialog pre-fills them and always lets the user override, and
+    silently drops any hint that isn't currently satisfiable (host offline).
+
+### 8.2 Project-level memory (owner-private)
+- **What:** a persistent memory store scoped to the project, readable/writable
+  across all its sessions, so learnings accumulate across sessions instead of
+  being lost per-session.
+- **Grounding:** no cross-session memory exists today; `session_state` is
+  per-conversation and policy-oriented. This is net-new.
+- **Owner-private:** memory belongs to the project owner and is **never** exposed
+  through a session shared individually with someone else (§9.4). This avoids
+  the leak where one shared session would expose learnings aggregated from *all*
+  the project's sessions — including ones never shared with that person.
+- **Design questions to resolve:**
+  - **Storage:** DB rows (project-scoped key/value or documents) vs. files in
+    the project's default workspace (like agent memory files). DB is
+    host-independent; files are natural for coding agents but tied to one
+    workspace/host. **Proposed:** DB-backed project memory (host-agnostic,
+    survives host churn), optionally surfaced to the agent as a virtual
+    file/tool.
+  - **How the agent reads/writes it:** injected into system context at session
+    start? Exposed as a tool (read/append/update)? Both?
+  - **Compaction interaction:** must survive conversation compaction — project
+    memory lives outside the conversation so it's inherently durable.
+
+### 8.3 Project-level context (owner-private)
+- **What:** reference material attached to the project (pinned docs, links,
+  instructions, files) that seeds every session's context.
+- **Relationship to memory:** *context* = user-curated inputs (I give the
+  project these docs/instructions); *memory* = agent-accumulated learnings (the
+  agent records what it discovered). Keep them as distinct surfaces even if
+  stored similarly. Both are owner-private.
+- **Design questions:** size/token budget when injecting into new sessions;
+  per-file include/exclude; whether context is copied into the session at start
+  (snapshot) or referenced live (updates propagate). **Proposed:** referenced
+  live with a snapshot-at-turn behavior, matching how instruction files work.
+
+## 9. Decision: no project-level sharing (per-session ACL only)
+
+**Decision: we do not add a project-level ACL.** Sharing stays per-session,
+exactly as it is today. A project is the **owner's private organizer**; its
+membership, memory, and context are the owner's private metadata and do not
+travel to other viewers.
+
+### 9.1 Why this is coherent
+Two principles point the same way:
+- Memory/context are **owner-private** (§8) — a project's learnings span multiple
+  sessions, so exposing them through a single shared session would leak content
+  from sessions never shared with that person.
+- **Shared sessions ignore project** — when a session is shared, the *session*
+  crosses the ACL boundary; its *project membership does not*.
+
+The reconciling rule:
+
+> A session's project membership is scoped to its **owner**. When a session is
+> shared, the session crosses the ACL boundary; its project membership,
+> memory, and context stay with the owner.
+
+### 9.2 How it looks
+
+```mermaid
+flowchart TD
+    subgraph Alice["Alice (owner)"]
+        PX["Project X<br/>(private: defaults + memory + context)"]
+        PX --> A["Session A"]
+        PX --> B["Session B"]
+        PX --> C["Session C"]
+    end
+
+    B -->|session ACL grant| BOB
+
+    subgraph Bob["Bob's view"]
+        SWM["Shared with me<br/>• Session B (ungrouped)"]
+        BOB --> SWM
+    end
+
+    PX -.->|project + memory/context<br/>never cross| Bob
+```
+
+- Alice files sessions A/B/C under Project X — only **Alice** sees them grouped.
+- Alice shares session B with Bob via the existing session ACL.
+- Bob sees session B in **"Shared with me"**, **ungrouped** — no project, no
+  memory, no context. Nothing leaks.
+
+### 9.3 What this buys us
+- No new `project_permissions` table, no inherited/computed grants, no
+  move-in/move-out ACL recomputation.
+- Requirements 1–4 (create, move, rename, defaults) — and the optional reorder —
+  need no ACL at all.
+- The existing per-`(user, conversation)` ACL does all sharing, unchanged.
+
+### 9.4 Consequence to enforce
+- Project memory/context access is gated by **ownership of the project**, never
+  by a session-level grant. A session shared individually must not unlock the
+  project's memory/context.
+
+### 9.5 Owner-scoped membership (Model A)
+Project membership is a single `project_id` owned by the session owner. A
+recipient of a shared session **cannot** file it into one of *their own*
+projects — shared sessions appear as a flat list in "Shared with me". Letting a
+viewer organize *shared* sessions into their own projects (per-viewer membership,
+"Model B") is a possible future extension and still needs **no** ACL, since each
+user's memberships would be their own private metadata.
+
+## 10. Priority 5 — What we do NOT support (intentional)
+
+- **Project-level sharing / ACL** — sharing stays per-session (§9).
+- **Nested projects / sub-projects.** One level only.
+- **A session in multiple projects.** Membership is single, owner-scoped.
+- **Per-viewer filing of shared sessions** ("Model B", §9.5) — deferred.
+- **Automatic/AI-driven grouping** — grouping stays user-defined (per #863).
+- **Org/team-owned projects** — no team entity exists; out of scope until one
+  does.
+- **Public (`__public__`) projects** — out of scope (follows from §9: projects
+  aren't shared at all).
+
+## 11. Phasing (proposed)
+
+- **Phase 0 — Grouping (v1, shipped on main):** label-based projects
+  (`omni_project`), sidebar sections, new-chat picker, kebab move. Per
+  `SESSION_PROJECTS_SIDEBAR.md`.
+- **Phase 1 — First-class entity:** `projects` table + CRUD, empty projects
+  (P1), move/create-in-project (P2), rename (P3), delete semantics. Reorder is
+  **optional** and, if added, client-only (§7.2). No label backfill here — the
+  server dual-reads (§13), so first-class projects work alongside existing
+  label-projects without migrating them. Shipped as three PRs: **1a** the project
+  container (table + store + CRUD), **1b** session membership (the `project_id`
+  column, conversation-store dual-read, and the session-move HTTP surfaces), and
+  the **web UI** (sidebar create/rename/delete/move against the first-class
+  entity, dual-reading label-projects) — see §12.
+- **Phase 2 — Project defaults (P4a):** default host/workspace/harness/model
+  seeded into the new-chat dialog when starting a session from within a project;
+  graceful degradation when host offline / not owned.
+- **Phase 3 — Memory & context (P4b/P4c):** owner-private project memory store +
+  curated context; agent read/write; injection into sessions.
+- **Phase 4 — Label consolidation (deferred, optional):** one-off backfill of
+  `omni_project` label-projects into `projects` rows, then (only if ever)
+  retiring the label path. Not required for the feature — dual-read makes it
+  opportunistic cleanup, not a milestone (§12, §13).
+
+## 12. Implementation status / TODO
+
+Tracks what has actually landed vs. what remains. Updated as work ships.
+
+### Done (Phase 1a — project container: entity + store + CRUD)
+Shipped: the project **container** — create, list, rename, and delete empty
+projects. Session→project membership landed separately in Phase 1b (below).
+- ✅ **`projects` table** — `SqlProject` (`db_models.py`): `id` (Uuid16),
+  `name`, `owner_user_id`, `created_at`, `updated_at`. Owner-scoped index; a
+  UNIQUE index on `(workspace_id, owner_user_id, name)` enforces per-owner name
+  uniqueness at the DB layer for non-NULL owners (the store's `_name_taken`
+  check guards NULL-owner / single-user rows, which SQL treats as distinct).
+  (No `config` column in Phase 1a — deferred so we didn't ship an unused
+  column; added in Phase 2 via migration `b3c4d5e6f7a8`, see the TODO below.)
+- ✅ **Migration** `b1c2d3e4f5a6` — creates the `projects` table only;
+  additive, no backfill. Chained after `d4f2a1b6c8e9`.
+- ✅ **Entity** — `Project` (`entities/project.py`).
+- ✅ **Store** — `ProjectStore` + `SqlAlchemyProjectStore` (create/get/list/
+  update/delete, owner-scoped; `IntegrityError` → `ALREADY_EXISTS` as the DB
+  backstop for the uniqueness race).
+- ✅ **API** — `POST/GET/PATCH/DELETE /v1/projects` (`routes/projects.py`),
+  request/response schemas, wired into `create_app` + CLI; `openapi.json`
+  regenerated. Every handler is owner-scoped (projects are owner-private).
+- ✅ Tests: store CRUD + owner isolation + name uniqueness (incl. DB backstop);
+  route CRUD (single- + multi-user header auth); entity.
+
+### Done (Phase 1b — session membership over HTTP)
+Links sessions to projects and exposes it, completing Phase 1.
+- ✅ **Membership column + migration** — nullable `project_id` (Uuid16) on
+  `SqlConversationMetadata` (no DB FK, Rule R032; `NULL` = unfiled) via
+  `c2d3e4f5a6b7`, an add-column migration chained after `b1c2d3e4f5a6`, plus
+  `ix_conversation_metadata_project_id` and `Conversation.project_id`.
+- ✅ **Conversation-store ops** — `set_conversation_project()` (file / move /
+  unfile by id) and a **name-based dual-read** `list_conversations(project=…)`
+  filter: a session is "in project `<name>`" if it has EITHER the first-class
+  membership (`metadata.project_id` → the caller's project of that name) OR the
+  legacy `omni_project` label with that value; `""` = unfiled. Cross-DB-safe;
+  the prefetch is bounded to the caller's permission-scoped ids so the `IN` /
+  `NOT IN` list can't grow past their own sessions. This is the §13 dual-read
+  made real, so there is no coexisting pair of filters to reconcile later.
+- ✅ **Session routes** — `PATCH /v1/sessions/{id}` files/unfiles by id
+  (owner-only; target-project ownership validated → 404 otherwise) and
+  `GET /v1/sessions?project=<name>` lists a project's sessions (owner-scoped);
+  `project_id` surfaced on `SessionResponse` / `SessionListItem`; `openapi.json`
+  regenerated.
+- ✅ Tests: store membership ops + name-based dual-read (incl. unfiled and the
+  cross-DB split-DB path); route move / unfile / list, single- and multi-user
+  ownership boundaries.
+
+### Done (Web UI — first-class projects in the sidebar)
+Wires the web app to the first-class entity, keeping the label path working via
+dual-read so no migration is forced. Folders are keyed by **name** (the union
+key that merges a first-class project and a like-named label-project into one
+folder), carrying the first-class `id` when one exists.
+- ✅ **List dual-read** — `GET /v1/sessions/projects` now returns the UNION of
+  first-class projects (`project_store.list`, incl. empty, with `id`) and legacy
+  label-projects (`id=None`), merged by name and sorted. Response shape changed
+  from `list[str]` to `list[{id, name}]`; owner-scoped as before.
+- ✅ **First-class CRUD client** — `web/src/lib/projectsApi.ts`
+  (`list/create/rename/delete` against `/v1/projects`); hooks `useCreateProject`,
+  `useRenameProject`, and a reworked `useDeleteProject`. `useProjects` now
+  returns `{id, name}[]`.
+- ✅ **Create empty project** — a "New project" control (`NewProjectButton`) in
+  the always-visible Projects section (My-sessions tab), even with zero
+  projects (§5.3). `POST /v1/projects`.
+- ✅ **Membership by `project_id`** — filing/moving a session (composer picker,
+  row kebab, drag-drop) PATCHes `project_id`, resolving the picked name to an id
+  and **creating the first-class row on demand** for a label-only folder. `""`
+  unfiles. Sidebar groups a folder's members by first-class id OR the legacy
+  label, and a row's "current project" dual-reads both (so pinned first-class
+  members keep their project flyout).
+- ✅ **Rename** — `PATCH /v1/projects/{id}` (O(1)); a label-only folder is
+  promoted on demand (create + re-file members). **Delete** — archives and
+  unfiles every member (clears `project_id` + `omni_project` label), then
+  deletes the container; sessions are never deleted (§5.3, §7).
+- ✅ Tests: `projectsApi` unit tests; reworked hook tests (resolve→file,
+  create-on-demand, archive+unfile+delete); sidebar/composer suites updated;
+  server union test. Empty folders read "No sessions".
+
+### Done (Benchmark — #3094)
+- ✅ **Latency journeys + corpus seeder.** Added `list_projects` (sidebar project
+  list, dual-read union) and `list_project_sessions` (`?project=` folder fetch)
+  latency journeys to `dev/benchmarks/omnigent`, mirroring the `list_sessions`
+  hot read path. The corpus seeder now also seeds first-class `projects` rows
+  and files a configurable fraction of sessions into them (`--projects`,
+  `--filed-fraction`) so the journeys measure a realistic sidebar instead of an
+  empty project set, and the PR benchmark regression check runs on
+  `dev/benchmarks/**` changes. CRUD writes remain unbenchmarked (infrequent
+  single-row ops).
+
+### Done (Phase 2 — project defaults, P4a)
+Complete, shipped across several PRs: default host/workspace/agent + an opt-in
+worktree stored on the project and seeded into the new-chat composer.
+  - ✅ **Backend `config` column.** Added a nullable `config` column to
+    `projects` (migration `b3c4d5e6f7a8`, additive with a clean downgrade) and
+    plumbed it through the store/entity/API. `config` is an **opaque JSON
+    object**, not a typed schema: the backend persists it whole and never
+    filters on it, so the key vocabulary (host/workspace/harness/model/
+    reasoning-effort/git base-branch, …) is owned by the client and can grow
+    without a schema change. Values are *hints* (§8.1). Store `update()`
+    distinguishes `config=None` (leave unchanged) from `config={}` (clear), so
+    a rename never wipes stored defaults. Exposed on `ProjectObject` /
+    `CreateProjectRequest` / `UpdateProjectRequest` (openapi regenerated).
+  - ✅ **Settings editor.** A "Project settings" dialog
+    (`web/src/shell/ProjectSettingsDialog.tsx`, reached from the project-folder
+    kebab menu) writes a project's `config`: host, working directory, default
+    agent, and an opt-in "Random worktree" toggle. The `config` shape the client
+    owns is `{ host_id?, workspace?, agent_id?, use_worktree? }`. Fields are
+    optional (an unset one stores no key); an all-default dialog clears to `{}`.
+    Worktrees are **opt-in** — the toggle defaults OFF and only an explicit ON is
+    stored as `use_worktree: true` (matching "worktrees are opt-in at create
+    time"). The host/agent pickers and filesystem browser reuse the composer's
+    components.
+  - ✅ **Seed defaults into the new-chat dialog.** The composer reads the stored
+    `config` and pre-fills host / working directory / agent, always overridable,
+    silently dropping any hint that isn't currently satisfiable (e.g. the default
+    host is offline, or the configured agent is no longer registered). An unset
+    field falls through to the composer's generic defaults (last host, recent
+    workspace, last-used agent). The prefill machine waits while the projects
+    list (name → id) or the config query is still loading, so a generic default
+    can't win the race. An opt-in worktree (`use_worktree: true`) generates a
+    fresh `worktree-<hex>` branch once the workspace is in place and confirmed a
+    git repo — including for empty projects, where the workspace comes from the
+    config or the home-fallback.
+  - ✅ **Backend `config` hardening (from the #3108 review).** Both landed in
+    `stores/project_store/sqlalchemy_store.py`: (a) `_encode_config` bounds the
+    serialized `config` at 64 KiB (`_CONFIG_MAX_SERIALIZED_LEN`) and raises
+    `INVALID_INPUT` past it — the value is persisted verbatim and reflected back,
+    so an unbounded blob is a mild storage/response-size amplifier; (b)
+    `_decode_config` coerces a non-dict blob (future writer / manual DB edit) back
+    to `{}` rather than returning it raw, so callers can always treat config as a
+    mapping.
+  - ✅ **Replaced the inference-based prefill (PR #2133).** That merged PR
+    prefilled the composer by *inferring* defaults from the project's newest
+    session (host/agent/repo + a fresh worktree branch) — an explicit non-goal
+    workaround for the absence of stored project defaults. Now that the dialog
+    reads the stored `config`, the inference path is retired: `projectPrefill.ts`
+    is collapsed to config-only seeding, and `useNewestProjectSession` (plus its
+    `["project-newest-session"]` cache invalidations) is removed. Stored config
+    is the single source of truth for a project's defaults; a project with no
+    config prefills nothing project-specific (just the generic defaults).
+
+### TODO
+**Postponed.** Phases 1–2 (first-class projects + defaults) are shipped. Phases 3
+and 4 below are **not scheduled**, each on a different trigger: Phase 3 waits for
+customer evidence that project memory/context is wanted; Phase 4 waits until
+telemetry shows most clients have migrated to a version that writes `project_id`
+(so retiring the label path is safe). Both are additive and independent, so either
+can start whenever its trigger lands.
+
+- ⏸️ **Phase 3 — memory & context (P4b/P4c)** — new `project_memory` /
+  `project_context` tables + agent read/write + injection (§8.2/§8.3). Postponed:
+  the largest remaining chunk and the one with open design questions (§14 Q5/Q6);
+  wait for customer evidence that cross-session project memory/context is wanted
+  before committing to a storage + agent-surface design.
+- ⏸️ **Phase 4 — label consolidation (postponed; not required for the feature).**
+  Because the server dual-reads (a session is "in project X" if it has *either* a
+  `project_id` *or* the `omni_project` label — see §13), the first-class feature
+  works end-to-end without touching the label path, so this whole phase is
+  deferred and may never be needed. Postponed until telemetry shows most clients
+  have migrated to a version that writes `project_id` — retiring the label path is
+  only safe once old label-writing clients are gone. Two steps, both optional:
+  - **Label → `project_id` backfill** — a **separate one-off command/migration**
+    converting existing `omni_project` label-projects (real production data) into
+    `projects` rows. Gives a clean single source of truth, but dual-read means it
+    is **not mandatory** — only needed if/when we decide to retire the label path.
+  - **Retire the label path** — remove the `omni_project` reads/writes and the
+    `?project=<name>` filter. This includes the one UI reader still on the label
+    path: the Settings archived-only project picker
+    (`fetchAllArchivedProjectNames`) derives its options from the `omni_project`
+    label. Last step, if ever; do only after the backfill has run and telemetry
+    shows no client still writes labels. Keeping the label path is cheap, so
+    treat retirement as opportunistic cleanup, not a milestone.
+
+## 13. Backwards compatibility (mixed server / client versions)
+
+Because deployments can run an old client against a new server (or vice versa)
+during a rollout, the design keeps every change additive:
+
+- **DB / old server code, new schema.** Migration `b1c2d3e4f5a6` only *adds* a
+  nullable column and a new table. An older server binary reading the migrated
+  DB simply ignores `project_id` and the `projects` table — no column it selects
+  disappears, no NOT NULL constraint is added. Rollback is a clean
+  `downgrade()` (drops the column + table) since no existing data was rewritten.
+- **New server, old client.** The `/v1/projects` routes and the `project_id`
+  filter are *new* endpoints/params; an old web client that doesn't call them
+  behaves exactly as before. `project_id` is an added field on the session
+  snapshot — old clients ignore unknown JSON fields.
+- **Old server, new client.** A new client may call `/v1/projects` or pass
+  `?project_id=`; against a server without the router mounted these 404 / are
+  ignored. The client must degrade gracefully (treat "no projects endpoint" as
+  "feature off") — a UI requirement to note, not a data risk.
+- **v1 label coexistence.** The label path (`omni_project`, `?project=<name>`)
+  is untouched and runs alongside the new `project_id` path, so a client still
+  on the label API keeps working through the transition. Neither path writes the
+  other's storage, so a mixed fleet can't corrupt state — at worst a session is
+  grouped by label on one client and unfiled by `project_id` on another until
+  the backfill runs.
+- **Server dual-reads to stay client-compatible.** Rather than forcing a client
+  cutover, the server treats a session as "in project X" if it has *either* a
+  `project_id` *or* the `omni_project` label. This keeps old web clients (which
+  still write labels) working indefinitely with no forced upgrade, and means the
+  label path can stay in place — retiring it is an optional, deferred cleanup
+  (§12), not a milestone. The backfill (§12) migrates existing label data into
+  rows for a clean single source of truth, but because of dual-read it is not a
+  correctness prerequisite. Only if the label path is ever removed must clients
+  first have shipped the `project_id` path.
+
+## 14. Open questions
+
+1. **§4** Confirm FK (`project_id`) over label-of-id for membership.
+   (Proposed: FK.)
+2. **§6.2 / §8.1** When starting a session from within a project, auto-fill
+   host/workspace/harness from project defaults (overridable)? (Proposed: yes.)
+3. **§7.1** Case-sensitive, per-owner-unique project names? Max length 100?
+4. **§8.1** Store project defaults as soft hints (drop when unsatisfiable) vs.
+   hard requirements? (Proposed: soft hints.)
+5. **§8.2** Project memory storage: DB vs. workspace files? (Proposed: DB.)
+6. **§8.2/8.3** How is memory/context surfaced to the agent — system-context
+   injection, a tool, or both?
+7. **§9.5** Do we ever want per-viewer filing of shared sessions (Model B), or
+   is a flat "Shared with me" list sufficient long-term?

designs/SANDBOX_CREDENTIAL_PROXY.md

@@ -106,6 +106,7 @@ swap-on-access:
 | `https_basic` | `Authorization: Basic b64(user:<real>)` | swap-on-access (optional `env:`) | Generic Basic auth; `username` defaults to `x-access-token`. |
 | `git_https` | `Authorization: Basic b64(user:<real>)` | swap-on-access | Preset for git-over-HTTPS; nothing in the sandbox. |
 | `gh_basic` | Basic for git host, `token` for api host | swap-on-access for git; `GH_TOKEN`/`GITHUB_TOKEN` env for api | Preset for GitHub CLI + git; defaults to `github.com` + `api.github.com`. |
+| `databricks_cli` | `Authorization: Bearer <real>` per workspace host | placeholder `.databrickscfg` file (one `oa_cred_*` per profile) | Preset for the Databricks CLI; takes `profiles` (+ optional `default`). See below. |
 
 Common fields: `target`/`targets` (host + optional path glob — only the
 host binds the credential; path scoping is delegated to `egress_rules`),
@@ -152,6 +153,54 @@ parser) that rejects unknown keys, enforces exactly one source key, and
 checks POSIX env-var names — then converts to the `CredentialSourceSpec`
 dataclass the runtime consumes.
 
+### `databricks_cli` — profile-keyed, refreshing, file-materialized
+
+The Databricks CLI is a fifth type that differs from the four host-keyed
+primitives above:
+
+- **Profile-keyed, not host-keyed.** It takes `profiles: [name, ...]`
+  (and optional `default`) instead of `target`/`targets`/`source`. The
+  workspace host behind each profile is only known once the parent
+  resolves it, so profiles are carried on `DatabricksProxySpec` rather
+  than in the host-keyed `entries` list. Only the listed profiles are
+  proxied; every other profile is invisible to the sandbox.
+- **File materialization, not env injection.** The CLI gates on a local
+  credential (like `gh`) and `DATABRICKS_HOST`/`DATABRICKS_TOKEN` carry
+  only one workspace, so per-profile selection needs a config file. The
+  parent writes a placeholder-only `.databrickscfg` into the sandbox
+  scratch dir — one `[profile]` section per profile with the real `host`
+  and a synthetic `token = oa_cred_*` — and points `DATABRICKS_CONFIG_FILE`
+  at it (and `DATABRICKS_CONFIG_PROFILE` when `default` is set). The CLI
+  emits `Authorization: Bearer oa_cred_*`, which the proxy swaps per host.
+- **Refreshing secret.** Databricks profiles are usually OAuth
+  (`auth_type = databricks-cli`) with a ~1h token, so the rewrite rule
+  holds a `DatabricksProfileTokenProvider` (via the SDK) instead of a
+  static secret. The proxy calls `rule.resolve_secret()` on each swap; the
+  provider re-mints via `Config.authenticate()` at most once per throttle
+  window (the SDK caches in-memory and only re-shells near expiry), so a
+  long session survives token expiry. The provider requires the
+  `databricks` extra and fails loud if it is missing.
+- **Egress is operator-listed.** Reaching a workspace requires its host in
+  `egress_rules` (`* <host>/**`), the same as every other credential-proxy
+  type. The proxy does not widen egress on its own — an earlier draft
+  auto-added resolved hosts, but that was dropped to keep egress behavior
+  consistent across types (the operator declares every reachable host).
+- **Linux only.** The `databricks` CLI is a Go binary and Go on macOS
+  ignores `SSL_CERT_FILE`, so `databricks_cli` is rejected on
+  `darwin_seatbelt` (same rationale as `gh_basic`); use `linux_bwrap`.
+
+```yaml
+os_env:
+  sandbox:
+    type: linux_bwrap
+    egress_rules:
+      - "* pypi.org/**"
+    credential_proxy:
+      - type: databricks_cli
+        profiles: [dbc-adb7b1a3-9097, oss]
+        default: dbc-adb7b1a3-9097
+```
+
 ## Internal model
 
 `omnigent/inner/datamodel.py`:
@@ -162,8 +211,11 @@ dataclass the runtime consumes.
   type compiles down to: `host`, `scheme` (`basic`/`bearer`/`token`),
   `source`, `username | None`, `inject_env: list[str]` (empty for
   swap-on-access; populated only by the opt-in `env` shim).
-- `CredentialProxySpec` — list of entries; attached to
+- `CredentialProxySpec` — list of entries plus an optional
+  `databricks: DatabricksProxySpec`; attached to
   `OSEnvSandboxSpec.credential_proxy`.
+- `DatabricksProxySpec` / `DatabricksProfileBinding` — the profile list
+  (+ `default`, `config_env`) for the `databricks_cli` type.
 
 The parser (`omnigent/spec/parser.py`, `_parse_credential_proxy`)
 validates each raw entry with a pydantic boundary model
@@ -186,9 +238,13 @@ backend allow-list, and the `gh_basic`-on-macOS guard.
   - `helper_env_updates` — synthetic values for each `inject_env` var
     (empty for swap-on-access entries),
   - `rewrites: list[CredentialRewriteRule]` — `(host, scheme,
-    real_secret, synthetic | None, username)` for the proxy. `synthetic`
-    is `None` for swap-on-access entries; it is minted (and the matching
-    placeholder injected) only when the entry sets `env`.
+    real_secret | secret_provider, synthetic | None, username)` for the
+    proxy. `synthetic` is `None` for swap-on-access entries; it is minted
+    (and the matching placeholder injected) only when the entry sets `env`
+    (or, for `databricks_cli`, per proxied profile). A rule carries either
+    a static `real_secret` or a refreshing `secret_provider` — the proxy
+    calls `rule.resolve_secret()` — plus, for `databricks_cli`,
+    `sandbox_files` (the placeholder `.databrickscfg`).
 
 The real secret lives **only** in the parent process and the proxy's
 in-memory rewrite table. It is never serialized into the

designs/harness-modular-registry-proposal.md

@@ -0,0 +1,487 @@
+# Native Harness Plugin Interface (Modular Registry Proposal)
+
+Status: draft
+Supersedes nothing; extends `designs/harness-plugin-interface.md`.
+
+## Problem
+
+Omnigent supports **headless / SDK harnesses** as community plugins today (see
+`designs/harness-plugin-interface.md`). A package like `omnigent-foo` declares a
+`HarnessContribution` entry point, fills `harness_modules` / `aliases` /
+`install_specs`, and core wires it in generically — because an SDK harness plugs
+in as *pure data*: one import-path string per harness, dispatched through
+`omnigent.runtime.harnesses._HARNESS_MODULES` and `runner/routing.py`.
+
+**Native (terminal / TUI) harnesses are not pluggable.** A native harness wraps
+a real vendor CLI (Claude Code, Codex, Cursor, Pi, Goose, …) in a tmux/PTY or
+local-server session, tails its transcript, mirrors output back into Omnigent,
+and mediates auth / permissions / resume / interrupt. Adding one today means
+editing core in ~10 places. The registry *rejects* any community contribution
+that sets `native_harnesses` or `native_agents`:
+
+```python
+# omnigent/harness_plugins.py:716
+if contribution.native_harnesses or contribution.native_agents:
+    return (
+        f"community harness plugin {entry_point_name!r} registers native terminal "
+        "metadata, but community native terminal harnesses are not supported yet"
+    )
+```
+
+`designs/harness-plugin-interface.md` § "Native TUI Harnesses" already names the
+blockers: *"the runner, chat-resume, CLI-command, interrupt/stop, and built-in
+agent seeding paths are not pluggable."* This proposal turns that list into a
+concrete plan.
+
+## What is already pluggable
+
+The **data model** is done. `NativeCodingAgent` is a frozen dataclass of stable
+wire metadata, contributions carry a tuple of them, and everything downstream
+reads them through registry accessors:
+
+- `omnigent/harness_plugins.py` — `NativeCodingAgent`, `HarnessContribution`
+  (fields `native_harnesses`, `native_agents`), `native_agents()`,
+  `native_harnesses()`.
+- `omnigent/native_coding_agents.py` — indexes the registry rows by
+  `agent_name` / `harness` / `wrapper_label` / `terminal_name`.
+- `omnigent/_wrapper_labels.py` — the canonical wrapper-label string constants.
+- `omnigent/harness_aliases.py` — canonicalization (`native-pi` → `pi-native`).
+
+Nothing in this proposal changes the *shape* of `NativeCodingAgent`; it adds a
+behavior side-channel and rewrites the dispatch that currently ignores it.
+
+## What is NOT pluggable — the coupling inventory
+
+Every blocker is **imperative per-harness dispatch** that branches on
+`harness_name == "<x>-native"` or `native_agent.key == "<x>"` and does an inline
+`import omnigent.<x>_native`. Grouped by hub:
+
+### 1. The runner — `omnigent/runner/app.py` (~10.1k lines) + `omnigent/runner/native/orchestration.py` (~6.5k) — the epicenter
+
+Phase 0 (#3148) moved the native *builders and mirrors* out of `app.py` into
+`omnigent/runner/native/orchestration.py` (re-exported through
+`omnigent/runner/native/__init__.py`), shrinking `app.py` from ~20.1k to
+~10.1k lines. The imperative per-harness *dispatch* still lives in `app.py`;
+it now calls the imported builders instead of locally-defined ones. The
+coupling left to untangle:
+
+- **Spawn-env dispatch** (`app.py`, 11 arms): `if harness_name ==
+  "<x>-native" and spawn_env is None: ... build_<x>_native_spawn_env`.
+- **Launch dispatch** (`app.py`, 11 arms) → `_auto_create_<x>_terminal(...)`.
+- **`_auto_create_<x>_terminal`** functions (11 of them) — now in
+  `runner/native/orchestration.py`; each imports its own `<x>_native_bridge` /
+  `<x>_native_forwarder` / `<x>_native_permissions` and wires the transcript
+  forwarder + permission/usage/compaction mirrors, alongside the
+  `_supervise_*_bridges` mirrors (`_supervise_cursor_native_bridges`,
+  `_supervise_goose_native_bridges`, `_supervise_hermes_native_bridges`,
+  `_supervise_qwen_native_bridges`). Still the dominant blocker — the split
+  gave it a home but the `if key ==` dispatch that reaches it is unchanged.
+- **Interrupt / stop dispatch** (`app.py`) → `_handle_<x>_native_interrupt` /
+  `_handle_<x>_native_stop` closures (kept in `app.py`, not extracted).
+- **Terminal-route dispatch** (`app.py`): `terminal_name == "<x>"` →
+  `_auto_create_<x>_terminal`.
+- Plus the 11 `*_NATIVE_TERMINAL_ROLE` imports and the cost-popup bridge-dir
+  dispatch (both in `app.py`).
+
+### 2. Native launch — `omnigent/cli.py` (~14.5k lines)
+
+Each native TUI is a hand-written `@cli.command` (`claude`, `codex`, `opencode`,
+`pi`, `cursor`, `kiro`, `goose`, `hermes`, `antigravity`, `qwen`, `kimi`), each
+importing `from omnigent.<x>_native import run_<x>_native` and calling
+`_reject_native_on_windows("<x>")` with a literal name. No registry indirection
+generates these.
+
+### 3. Resume / resume-redirect
+
+- `omnigent/resume_dispatch.py:216` (`_dispatch_wrapper`) — the canonical
+  11-branch `if native_agent.key == "<x>":` chain, each `import
+  run_<x>_native`. Used by `omnigent resume`.
+- `omnigent/chat.py:1057` (`_redirect_native_resume_if_needed`) — a parallel,
+  partially-covered (6 of 11) resume-redirect keyed on `native_agent.key`, with
+  hand-written `_run_<x>_native_resume_redirect` helpers.
+
+### 4. Built-in `*-native-ui` agent seeding — `omnigent/server/app.py`
+
+`_ensure_default_agents` calls 11 hardcoded `_ensure_default_<x>_agent(...)`,
+each paired with a `_build_<x>_native_bundle()` that imports
+`_materialize_<x>_agent_spec`. `omnigent/db/utils.py:builtin_agent_id` and
+`omnigent/session_import/local.py` depend on the fixed built-in names.
+
+### 5. Enumerations parallel to the registry (should *derive* from it)
+
+- `omnigent/spec/_omnigent_compat.py:88` — `OMNIGENT_HARNESSES` /
+  `OMNIGENT_HARNESS_ALIASES` frozensets re-list all native ids + `native-*`
+  aliases.
+- `omnigent/onboarding/harness_readiness.py` — per-family frozensets gating
+  readiness/auth.
+- `omnigent/onboarding/harness_install.py:219` — `_HARNESS_NAME_TO_KEY`.
+- `omnigent/model_override.py` / `omnigent/model_catalog.py` — `*_FAMILY` /
+  `_CURSOR_HARNESSES` frozensets.
+- `omnigent/server/routes/sessions.py` — `_FORK_HISTORY_NATIVE_HARNESSES`,
+  `_CURSOR_FORK_HISTORY_HARNESSES`, per-harness wrapper-label/model constants,
+  and fork/switch gating.
+- `omnigent/runner/resource_registry.py` — 11 `*_NATIVE_TERMINAL_ROLE`
+  constants + the native-role status set.
+- `omnigent/runtime/harnesses/__init__.py:36` — a **dead** `_HARNESS_MODULES`
+  literal listing every `<x>-native` module (overwritten at `:152`). Delete.
+
+### 6. The web mirror — `web/src/lib/`
+
+`nativeCodingAgents.ts` duplicates all 11 rows + aliases; `forkHarness.ts`,
+`AgentCard.tsx` (icon switch), and `sessionStop.ts` / `sessionCapabilities.ts` /
+`codexPlanMode.ts` hardcode wrapper-label literals. Truly community-contributable
+native harnesses need the web driven by `GET /v1/harnesses`, not literals.
+
+## Design: a `NativeHarnessProvider` behavior seam
+
+Mirror how SDK harnesses supply *one import path* (`harness_modules[id]`). A
+native harness supplies a small set of import paths for the lifecycle hooks the
+dispatch hubs currently hardcode. `NativeCodingAgent` stays a pure-data
+identity row; behavior lives in a sibling provider resolved lazily (respecting
+the plugin import rules — `get_contribution()` must stay import-light).
+
+```python
+# omnigent/harness_plugins.py (new)
+@dataclass(frozen=True)
+class NativeHarnessProvider:
+    """Import paths for a native harness's lifecycle hooks.
+
+    Every value is a dotted path resolved lazily at dispatch time, so
+    get_contribution() never imports the runner/CLI/provider stack.
+    """
+    key: str                       # matches NativeCodingAgent.key
+    run_native: str                # "...:run_<x>_native"  (CLI + resume launch)
+    auto_create_terminal: str      # "...:auto_create_<x>_terminal"  (runner)
+    spawn_env_builder: str | None = None   # "...:build_<x>_native_spawn_env"
+    interrupt_handler: str | None = None   # "...:handle_<x>_native_interrupt"
+    stop_handler: str | None = None        # "...:handle_<x>_native_stop"
+    materialize_agent_spec: str | None = None  # "...:_materialize_<x>_agent_spec"
+    bridge_dir: str | None = None          # "...:bridge_dir_for_session" (cost popup)
+```
+
+Add to `HarnessContribution`:
+
+```python
+    native_providers: tuple[NativeHarnessProvider, ...] = ()
+```
+
+And accessors in `omnigent/harness_plugins.py`:
+
+```python
+def native_providers() -> tuple[NativeHarnessProvider, ...]: ...
+def native_provider_for_key(key: str) -> NativeHarnessProvider | None: ...
+```
+
+A tiny resolver (new `omnigent/native_dispatch.py`) turns a dotted path into a
+callable with `importlib`, caching per path, so each hub calls
+`resolve(provider.run_native)(server=..., session_id=..., args=...)` instead of
+an `if/elif` arm. `run_native` must accept a uniform `(*, server, session_id,
+extra_args: tuple[str, ...])` signature — the per-harness `run_<x>_native`
+functions are near-uniform already, so this is mostly a keyword-arg
+normalization, not a rewrite.
+
+### Signature normalization
+
+The one real API change: today `run_claude_native(claude_args=...)`,
+`run_pi_native(pi_args=...)` each name their pass-through arg differently. The
+provider seam requires a single spelling (`extra_args`). Keep the existing
+functions, add thin `**kwargs`-tolerant wrappers, or rename the parameter with a
+back-compat alias for one release (per CLAUDE.md deprecation policy, note the
+target release).
+
+### Rewriting each hub
+
+| Hub | Today | After |
+|---|---|---|
+| `resume_dispatch.py` `_dispatch_wrapper` | 11 `if key ==` arms | `resolve(provider.run_native)(...)` |
+| `cli.py` native subcommands | 11 `@cli.command` funcs | loop over `native_agents()`, register one Click command each; `_reject_native_on_windows` reads the row |
+| `runner/app.py` launch + terminal-route | 11 arms → `_auto_create_<x>_terminal` | `resolve(provider.auto_create_terminal)(...)` |
+| `runner/app.py` spawn-env | 11 arms | `resolve(provider.spawn_env_builder)(...)` when set |
+| `runner/app.py` interrupt/stop | 11 arms each | `resolve(provider.interrupt_handler / stop_handler)(...)` |
+| `chat.py` resume-redirect | 6 arms | fold into the same provider `run_native`; delete the per-harness redirect helpers |
+| `server/app.py` seeding | 11 `_ensure_default_<x>_agent` | loop over `native_agents()`, materialize via `provider.materialize_agent_spec` |
+| enumerations (§5) | frozensets/dicts | derive from `native_agents()` / capability flags |
+
+### Capability-driven behavior (replace the ad-hoc frozensets)
+
+Several §5 sets encode *behavior*, not identity — e.g.
+`_FORK_HISTORY_NATIVE_HARNESSES` ("rebuilds fork transcript") and
+`_CURSOR_FORK_HISTORY_HARNESSES` ("replays history as a text preamble"). These
+should become fields on `HarnessCapabilities` (which already exists and is
+asserted in `tests/test_harness_capabilities.py`) — e.g. a `fork_history:
+Literal["none","rebuild","preamble"]` axis — so the server reads the capability
+instead of membership in a hand-maintained set. This also feeds `/v1/harnesses`
+so the web can stop hardcoding `forkHarness.ts`.
+
+### Validator flip
+
+Once the hubs resolve through the registry, replace the hard reject in
+`_validate_community_contribution` with positive validation:
+
+- every `native_agent.key` has a matching `native_provider.key`;
+- provider import paths start with `COMMUNITY_MODULE_PREFIX` (same rule as
+  `harness_modules`);
+- native-agent identity values don't collide with an existing contribution
+  (the `_native_agent_identity_values` check already exists — keep it);
+- `run_native` and `auto_create_terminal` are non-empty.
+
+## Phasing
+
+This is a **substantial refactor, not a small extension**. The realistic path
+is an internal refactor first (built-in native harnesses keep living in core but
+route through the generic seam), then a thin follow-up that opens it to
+community packages.
+
+### Phase 0 — Prep: split the oversized dispatch files
+
+The refactor is concentrated in files that are already too large to edit safely.
+The goal is **< 10k lines per file**. Before adding the seam, carve the
+native-specific code into cohesive modules so the provider rewrite touches small
+files with clear boundaries. This is behavior-preserving and independently
+reviewable/mergeable. Each extraction is a mechanical move + import fix, verified
+by the existing test suite and `pre-commit run --all-files`. No behavior change;
+no `if key ==` arm removed yet.
+
+Done:
+
+- **`cli.py`** ✅ (#3047) — native subcommand bodies moved into
+  `omnigent/cli_native.py` (they already delegate to `run_<x>_native`); `cli.py`
+  registers them. `cli.py` is now 9.6k lines; `cli_native.py` 1.3k.
+- **`server/routes/sessions.py`** ✅ (#3097) — split into a facade
+  (`sessions.py`, now 7.8k) that star-imports an impl package
+  (`omnigent/server/routes/_sessions/`: `common.py`, `helpers.py`,
+  `orchestration.py`). `create_sessions_router` stays in the facade.
+- **`runner/app.py`** ✅ (#3148) — the native builders and bridge mirrors
+  (`_auto_create_*_terminal`, `_supervise_*_bridges`, the transcript-forwarder
+  task registry, cost-popup repop tasks) moved into
+  `omnigent/runner/native/orchestration.py` (~6.5k lines), re-exported through
+  `omnigent/runner/native/__init__.py`; `app.py` imports them. `app.py` dropped
+  from ~20.1k to ~10.1k lines. Landed as a single `orchestration.py` rather than
+  the proposed `terminals.py` / `supervise.py` / `interrupt.py` three-way split —
+  a further sub-split can happen when the seam lands if the module stays hot.
+  The `if key ==` / `if harness_name ==` dispatch arms and the interrupt/stop
+  handler closures stayed in `app.py` (they are the entry points Phase 1
+  rewrites), so `app.py` is still marginally over the 10k target.
+- **`tests/runner/test_app_sessions_native.py`** ✅ (#3149) — the ~19.0k-line
+  monolith was split into nine concern-scoped modules
+  (`test_app_sessions_native_{events_lifecycle,events_options,supervision,
+  terminal_routing,terminals_autocreate,terminals_runtime,wake_forwarders,
+  workflow_init,workflow_messages}.py`) plus a shared `tests/runner/conftest.py`
+  (~0.7k) holding the scaffolding. Each new file is under 3k lines.
+
+Deferred (under the 10k target already; fold into Phase 1 when the seam lands):
+
+- **`chat.py`** (4.2k) → move the `_run_<x>_native_resume_redirect` helpers into
+  `resume_dispatch.py` (they duplicate its dispatch anyway) as the first step of
+  collapsing the two resume paths into one.
+
+### Current state (verified 2026-07-24, at `main` `59e6b70e`)
+
+Grounding the plan in the actual tree, not just the coupling inventory above:
+
+- **Data model is ready.** `NativeCodingAgent` (`harness_plugins.py:49`) is 11
+  frozen rows; `HarnessContribution` (`:70`) has `native_harnesses` /
+  `native_agents` but **no** `native_providers` field yet;
+  `native_coding_agents.py` already indexes rows by agent_name / harness /
+  wrapper_label / terminal_name. `HarnessCapabilities`
+  (`harness_capabilities.py:79`) exists with an optional-field extension
+  pattern (`steering`, `live_queue`, `images`, `compaction`) but **no**
+  `fork_history` axis.
+- **`run_<x>_native` is already near-uniform.** All 11 are `(*, server,
+  session_id, <x>_args, resume_picker=..., ...)`. The divergence is only the
+  pass-through arg *name* plus four harnesses carrying extra kwargs: claude
+  (`command`, `use_claude_config`), codex (`command`, `model`, `prompt`),
+  antigravity (`command`, `model`, `permission_mode`), opencode (`model`). So
+  signature normalization is a keyword-rename with a threaded `**extra`, not a
+  rewrite — lower risk than "Signature uniformity" under Risks suggested.
+- **Coverage is uneven across hubs** (a correctness smell the seam fixes):
+  `resume_dispatch._dispatch_wrapper` covers 10, `chat.py`
+  `_redirect_native_resume_if_needed` only 6 (missing opencode/goose/hermes/
+  antigravity/qwen), runner interrupt handlers 9, stop handlers 7. Routing
+  everything through one resolver *normalizes* coverage.
+- **The dead `_HARNESS_MODULES` literal still exists** (`runtime/harnesses/
+  __init__.py:36`, overwritten at `:152`) — not yet deleted.
+- **`harness_catalog()` (`harness_plugins.py:899`) does not emit native-agent
+  rows** — only `{id, label, capabilities?, setup_steps?}` per harness, no
+  `agent_name` / `wrapper_label` / icon. The web is still 100% literals.
+
+Roughly **60+ hardcoded duplication points across ~12 Python + 6 TS files**
+plus the five dispatch hubs remain.
+
+### Phase 1 — Internal provider seam (core-only)
+
+Built-ins keep living in core but route through the generic seam. The test bar
+for every PR here is **"every native harness behaves identically before/after"**
+— lean on the split native test suite (#3149) and the native e2e skills. The
+validator keeps rejecting community native metadata throughout Phase 1.
+
+| PR | Scope | Key files | Depends on | Risk | Est. |
+|---|---|---|---|---|---|
+| **1.1 Provider model + resolver** | Add `NativeHarnessProvider` (import-path strings), the `native_providers` field + accessors, and `omnigent/native_dispatch.py` (lazy `importlib` resolver, cached per path). Populate 11 built-in providers pointing at existing `omnigent.<x>_native` functions. Purely additive — no hub rewired yet. | `harness_plugins.py`, new `native_dispatch.py` | — | Low | 1–2d |
+| **1.2 Signature normalization** | Give `run_<x>_native` a uniform `extra_args` spelling with a back-compat `<x>_args` alias (one-release deprecation per CLAUDE.md — name the target release). Decide the `**extra` protocol for the four special-kwarg harnesses (claude/codex/antigravity/opencode). | 11 `omnigent/<x>_native.py`, `native_dispatch.py` | 1.1 | Low–Med (mechanical ×11) | 2–3d |
+| **1.3 Resume hubs** | Collapse `resume_dispatch._dispatch_wrapper` (10 arms) and the 6 `chat.py` `_run_<x>_native_resume_redirect` helpers into one `resolve(provider.run_native)(...)` path. Deletes the redirect helpers and normalizes the 10-vs-6 coverage gap. | `resume_dispatch.py`, `chat.py` | 1.1, 1.2 | Med | 2d |
+| **1.4 CLI subcommands** | Replace the 11 hand-written `@cli.command` funcs in `cli_native.py` with a loop over `native_agents()`, registering one Click command each; make `_reject_native_on_windows` a registry-driven guard. Wrinkle: per-command options (`--model`, `--command`) must come off provider/row metadata. | `cli_native.py`, `cli.py` | 1.1, 1.2 | Med | 2–3d |
+| **1.5a Runner spawn-env** | Collapse the spawn-env dispatch — **two** near-identical 11-arm blocks (`app.py` ~2720 and ~6236) — behind a uniform `build_spawn_env(session_id, *, server_client, labels)` provider hook. Absorbs the three shapes (bare / bridge-id-from-labels / hermes policy-hook write) behind that one signature. Self-contained; removes the duplication. The bounded first measurement of the runner. | `runner/app.py`, 11 `<x>_native_bridge.py` | 1.1, 1.2 | Med | 2–3d |
+| **1.5b Runner launch** | The epicenter. The launch arms (`app.py` ~2841–3316 + the ~6095 elif chain) do **not** share a signature — `_auto_create_<x>_terminal` has 11 divergent signatures (3 common params; claude carries 9 extras). Unify by passing a `NativeLaunchContext` dataclass to a uniform `provider.auto_create_terminal(ctx)` adapter, with explicit `pre_launch` hooks for the non-uniform arms (claude transfer-inbound + rebuild-on-switch, codex needs-terminal check, antigravity host-spawn + transfer, opencode cold-boot terminal-ensure on the turn path ~6329). **Preserve the `_supervise_*_bridges` forward-cursor / double-post invariants exactly.** | `runner/app.py`, `runner/native/orchestration.py` | 1.5a | **High** | 4–6d |
+| **1.5c Runner terminal-route** | Collapse the `terminal/attach` `ensure_native_terminal` dispatch (`app.py` ~7462–7908). 9/11 are a uniform check→create→return; codex + antigravity need an ownership-check + response-wrap hook (`_is_runner_owned_*`, `_codex_ensure_response_with_policy_notice`). Reuses 1.5b's context object. | `runner/app.py` | 1.5b | Med | 2d |
+| **1.6 Runner interrupt/stop** | Route interrupt/stop through the provider; fill the 9-interrupt / 7-stop coverage gaps so every native has both paths. **Not additive as first scoped:** every handler is a closure over app-scope state (`server_client`, `resource_registry`, `_publish_event`, the `_AUTO_FORWARDER_TASKS` / `_session_*` module dicts), so extracting to module-level provider functions requires threading those in as a dependency-injection context, not a plain move. | `runner/app.py`, `runner/native/orchestration.py` | 1.5b | Med–High | 3–4d |
+| **1.7 Seeding loop** | Replace the 26 `_ensure_default_<x>_agent` / `_build_<x>_native_bundle` touchpoints in `server/app.py` with a loop materializing via `provider.materialize_agent_spec`. **`builtin_agent_id` output must stay byte-identical** so redeploy doesn't orphan seeded agents — pin this with a test. | `server/app.py`, `db/utils.py` | 1.1 | Med | 2–3d |
+| **1.8 Derive enumerations** | Add a `fork_history: Literal["none","rebuild","preamble"]` axis to `HarnessCapabilities`; derive the §5 frozensets/dicts from `native_agents()` / capabilities (8 files, ~35 sets); delete the dead `_HARNESS_MODULES` literal. Also add optional `shell_tool_name` / `shell_tool_prompt` fields so the harness bench's tool-call probe can be driven off capabilities instead of its hardcoded `_NATIVE_TOOL_PROVOCATION` table (see "Harness bench compatibility" below). | `harness_capabilities.py`, `_omnigent_compat.py`, `harness_readiness.py`, `harness_install.py`, `model_override.py`, `model_catalog.py`, `_sessions/common.py`, `resource_registry.py`, `runtime/harnesses/__init__.py`, `tests/harness_bench/native_tui_driver.py`, `tests/test_harness_capabilities.py` | 1.1 | Med | 2–3d |
+
+After 1.1 + 1.2 land, PRs 1.3, 1.4, 1.7, 1.8 touch mostly disjoint hubs and can
+proceed in parallel. The runner sub-stack (1.5a → 1.5b → 1.5c → 1.6) is serial —
+each reuses the prior's context object — and is the critical path.
+**Phase 1 subtotal: ~20–29 engineer-days** (revised up from ~17–25 after the
+runner exploration split 1.5 into 1.5a/b/c and re-scoped 1.6; see below).
+
+### Phase 2 — Open to community packages
+
+Only starts once Phase 1 has every built-in running *through* the seam.
+
+| PR | Scope | Key files | Depends on | Risk | Est. |
+|---|---|---|---|---|---|
+| **2.1 Validator flip** | Replace the hard reject in `_validate_community_contribution` with positive validation: every `native_agent.key` has a matching `native_provider.key`; provider import paths start with `COMMUNITY_MODULE_PREFIX`; identity values don't collide (`_native_agent_identity_values` already checks this); `run_native` + `auto_create_terminal` are non-empty. | `harness_plugins.py` | 1.1 | Low–Med | 1d |
+| **2.2 `/v1/harnesses` native rows** | Extend `harness_catalog()` to emit native-agent rows + capabilities (`agent_name`, `wrapper_label`, `fork_history`, icon/label field), so the web has a server source of truth. | `harness_plugins.py`, `server/routes/harnesses.py` | 1.8 | Low | 2d |
+| **2.3 Web off the endpoint** | Delete the `nativeCodingAgents.ts` literals + `HARNESS_ALIASES`, the `forkHarness.ts` sets (`NATIVE_REBUILD_HARNESSES` / `PREAMBLE_FORK_HARNESSES` now come from `fork_history`), the `AgentCard` icon switch, and the wrapper-label literals in `sessionStop.ts` / `sessionCapabilities.ts` / `codexPlanMode.ts` — all driven by `/v1/harnesses`. Needs a **demo (screenshots/recording)** per CLAUDE.md; likely splits into 2.3a fork/capabilities data-plumb and 2.3b icon/label rendering. | `web/src/lib/*`, `web/src/components/AgentCard.tsx` | 2.2 | Med–High (largest FE) | 4–6d |
+| **2.4 Docs + example plugin** | Extend `designs/harness-plugin-interface.md` § "Native TUI Harnesses" with the native checklist, and ship an example native plugin (`examples/` or a sibling `omnigent-foo-native`) proving the contract end to end. **Acceptance criterion: the example plugin is benchable** — `python -m tests.harness_bench --harness <plugin> --live` runs green (selection + native-tui driver + provisioning), which is the honest end-to-end proof the contract holds. | `designs/harness-plugin-interface.md`, `examples/` | 2.1, 2.2 | Low–Med | 2–3d |
+
+**Phase 2 subtotal: ~9–12 engineer-days.**
+
+### Harness bench compatibility
+
+Does the harness bench (`tests/harness_bench/`, per
+`designs/harness-capabilities-bench-seam.md`) work with a community-contributed
+native plugin after this refactor? **Mostly yes, with no separate bench-migration
+PR — the bench's selection/driver layer is already registry-driven.** Verified
+against the current tree:
+
+- **Selection is already registry-driven.** `manifest.py` seeds
+  `OFFICIAL_PROFILES` from the 4 P0 SDK probes, then loops over
+  `harness_capabilities()` adding every harness whose `integration_mode is
+  NATIVE_TUI` (`_native_tui_harnesses()`), auto-generating a `BenchProfile` per
+  native via `_native_profile()`. Community harnesses also resolve through
+  `_registry_profile()` (`harness_modules()` / `harness_capabilities()`), and the
+  CLI accepts a `module:attr` `BenchProfile` reference. So a plugin declaring
+  `native_agents` + a `NATIVE_TUI` capability **enumerates and gets a profile with
+  zero bench edits**.
+- **The driver is already generic.** `transport.py`'s `driver_registry()` keys on
+  transport/integration-mode; a native profile auto-selects `NativeTuiDriver`,
+  which spawns a real server + runner and drives the vendor TUI through the
+  session API. No `if harness == "x"` in the driver path.
+- **Gap 1 — provisioning needs registry-driven seeding, which is PR 1.7.** The
+  native driver provisions a session against a pre-seeded `<harness>-ui` agent
+  (`native_tui_driver.py` → `_agent_id(vendor.agent_name)`). Today that agent
+  exists only because `server/app.py` hardcodes its seeding, so a community
+  plugin's agent isn't on the server and the run fails at provisioning. **PR 1.7
+  (registry-driven seeding loop) closes this for free** — no separate bench work.
+- **Gap 2 — tool-call probe metadata, folded into PR 1.8.** The tool/MCP probe
+  reads a hardcoded `_NATIVE_TOOL_PROVOCATION` table (the per-vendor "run this
+  shell tool" prompt); a plugin can't supply it, so those probes *skip*
+  (NOT_APPLICABLE — non-fatal; basic-turn / streaming / interrupt / reasoning
+  probes still run). The `shell_tool_name` / `shell_tool_prompt` capability fields
+  added in **1.8** let the bench read this off the registry instead.
+
+Net: **no new phase or standalone bench-migration PR.** Full provisioning falls
+out of 1.7; tool-call probes become plugin-drivable via a small 1.8 field; and
+2.4's example plugin carries a `--live` bench run as its acceptance criterion.
+
+### Effort summary
+
+- **Phase 1** (internal seam): ~20–29 engineer-days across 10 PRs (1.1–1.4,
+  1.5a/b/c, 1.6, 1.7, 1.8).
+- **Phase 2** (community + web): ~9–12 engineer-days across 4 PRs.
+- **Total: ~29–41 engineer-days** across ~14 PRs (2.3 may split further).
+  Folding in review cycles, CI, and runner e2e validation, that is realistically
+  **~2.5–3.5 calendar months** done alongside other work. The critical path is
+  1.1 → 1.2 → 1.5a → 1.5b → 1.5c → 1.6, then 2.2 → 2.3 (web); the risk center is
+  the **runner sub-stack (1.5b in particular)**, where the divergent
+  `_auto_create_*` signatures and the `_supervise_*_bridges` invariants live.
+
+### Calibration (updated 2026-07-27, after 1.1–1.3 landed + runner exploration)
+
+Grounding the estimates in built evidence rather than the original guesses:
+
+- **Additive/mechanical PRs come in under estimate.** 1.1 (provider model +
+  resolver) and 1.3 (resume-hub collapse, net −261 lines) each landed in ~½ day
+  of code vs. the 1–2d / 2d budgeted. 1.1 was cheap partly because the resolver
+  was ~90% pre-built (`load_object` already did dotted-path → callable). Expect
+  1.4, 2.1, 2.4 to likewise come in low.
+- **The real cost is test-shape churn, not the seam.** 1.3's core rewrite was
+  trivial; the time went into the tests that pin the exact call shape (kwarg
+  renames, a parametrized dispatch table, catching an over-reach where launch-
+  path expectations were flipped before their hub was migrated). This scales
+  with how many tests pin a hub — and the runner has the most (the ~19k-line
+  split native suite, #3149).
+- **The runner is bigger than the original single "1.5" line implied.** Reading
+  the code (not guessing) showed spawn-env, launch, and terminal-route each need
+  their own PR, `_auto_create_*` has 11 divergent signatures (so the seam needs
+  a `NativeLaunchContext`, not a uniform call), and interrupt/stop (1.6) closes
+  over app-scope state (needs DI, not a move). Hence 1.5 → 1.5a/b/c and 1.6
+  re-scoped upward.
+- **Net:** trim the additive PRs, **hold the runner sub-stack** until 1.5a is
+  measured. The back-loaded risk profile is confirmed, not softened, by the
+  three fast early PRs — 1.1–1.3 being fast is evidence the foundation is sound,
+  not that 1.5b will be. A 2-week compression of remaining Phase 1 is plausible
+  only if the runner sub-stack goes cleanly; that is the one unmeasured unknown.
+
+### Implementation progress
+
+Append-only ledger — one line per PR as it opens, updated to `landed` on merge.
+The plan tables above stay the stable target; this tracks what has actually
+shipped. **~14 PRs total** (Phase 1: 1.1–1.4, 1.5a/b/c, 1.6, 1.7, 1.8;
+Phase 2: 2.1–2.4).
+
+| PR | Status | Link |
+|---|---|---|
+| 1.1 Provider model + resolver | landed | #3239 |
+| 1.2 Signature normalization | landed | #3244 |
+| 1.3 Resume hubs | landed | #3314 |
+| 1.5a Runner spawn-env | landed | #3495 |
+| 1.5b-i Runner launch (scaffolding + 8 uniform arms) | in review | (this PR) |
+
+## Risks and open questions
+
+- **Runner extraction is the risk center.** The `_supervise_*_bridges` mirrors
+  hold subtle forward-cursor / restart / double-post invariants (see the
+  `_AUTO_FORWARDER_TASKS` transcript-forwarder registry, now in
+  `runner/native/orchestration.py`). Phase 0's move (#3148) preserved these
+  behaviorally — verified by the split native test suite (#3149) — so the
+  remaining risk shifts to Phase 1, where the dispatch that reaches these
+  mirrors gets rewritten. Lean on the existing native e2e skills
+  (`claude-native-ui:build-omnigent`, `pi-native-e2e-dev`, etc.).
+- **Signature uniformity — confirmed non-uniform (runner exploration).** The
+  `run_<x>_native` *launchers* normalized cleanly (1.2). The *runner* builders
+  did not: `_auto_create_<x>_terminal` has 11 divergent signatures (3 common
+  params; claude carries 9 extras — `bundle_dir`, `skills_filter`,
+  `auth_token_factory`, `resolve_launch_config`, …), and the launch arms carry
+  irreducible per-harness pre-call work (claude transfer/rebuild, codex/
+  antigravity needs+transfer checks, opencode turn-path cold-boot). The seam
+  therefore passes a `NativeLaunchContext` dataclass to a uniform
+  `provider.auto_create_terminal(ctx)` adapter with explicit `pre_launch` hooks —
+  not a single uniform positional call. Interrupt/stop handlers close over
+  app-scope state and need a DI context, not a plain extraction. This is why 1.5
+  became 1.5a/b/c and 1.6 was re-scoped upward.
+- **Windows.** `_reject_native_on_windows` must keep firing for contributed
+  natives — make it a registry-driven guard, not per-command.
+- **Import hygiene.** Providers hold *strings*; the resolver is the only place
+  that imports harness modules, and only at dispatch time — preserving the
+  plugin import rules from `harness-plugin-interface.md`.
+- **Capability axis scope.** Which of the §5 sets are genuinely
+  behavior-capabilities (belong on `HarnessCapabilities`) vs. pure identity
+  (derive from rows) needs a per-set decision; fork-history is the clearest
+  capability candidate.
+
+## Bottom line
+
+The data model is ready, Phase 0 (the file splits) has landed, and 1.1–1.3 are
+in review. The remaining work is untangling native orchestration from five
+`runner/app.py` chains and four other hubs into a `NativeHarnessProvider`
+behavior seam, then flipping the validator — sequenced as ~14 PRs (Phase 1:
+1.1–1.4, 1.5a/b/c, 1.6, 1.7, 1.8; Phase 2: 2.1–2.4), ~29–41 engineer-days total.
+The additive foundation (1.1) landed cheap and the additive/mechanical PRs are
+coming in under estimate; the estimate now lives almost entirely in the serial
+runner sub-stack (1.5a → 1.5b → 1.5c → 1.6), where the code — read, not guessed —
+shows divergent `_auto_create_*` signatures (needing a `NativeLaunchContext`),
+closure-bound interrupt/stop handlers (needing DI), and the `_supervise_*_bridges`
+invariants. Measure 1.5a (bounded spawn-env) before committing a runner
+timeline.

designs/server-dictation.md

@@ -0,0 +1,275 @@
+# Server-side streaming dictation
+
+## Problem
+
+The composer mic button (`web/src/components/ComposerMicButton.tsx`) relies on
+the browser Web Speech API. That API is only backed by a real recognizer in
+official Chrome/Safari builds (Google/Apple cloud speech); it is unavailable
+in Electron, Firefox, Chromium, and most self-hosted contexts. Today the
+button renders nothing (or "Dictation unavailable") in those environments —
+`web/electron/README.md` documents the gap and prescribes the fix: capture
+audio in the client and transcribe it on the Omnigent server.
+
+This design adds that path: a streaming speech-to-text WebSocket on the
+server, backed by a local [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx)
+model (CPU, no cloud, no per-request cost), with the mic button falling back
+to it whenever Web Speech is unavailable.
+
+## Goals
+
+- Dictation works in Electron, Firefox/Chromium, and the iOS/Android wrappers
+  (mic permissions are already wired in all three).
+- Audio never leaves the operator's infrastructure.
+- Live partial transcripts stream into the composer while the user speaks
+  (the Web Speech path today only inserts final utterances).
+- Zero new required dependencies: the STT engine ships as an optional extra
+  (`omnigent[dictation]`), imported lazily, mirroring the `s3`/`modal`/
+  `daytona` extras' posture. Servers without the extra (or without models)
+  report `available: false` and the web UI silently keeps its current
+  behavior.
+
+## Non-goals
+
+- Voice *conversations* (TTS replies, wake words, hands-free turn taking).
+- Replacing the Web Speech path where it works today.
+- Terminal REPL dictation (possible follow-up; shares the engine).
+- Speaker diarization, translation, non-English models beyond whatever
+  sherpa-onnx model the operator installs.
+
+## Server
+
+### Engine — `omnigent/server/dictation.py`
+
+A small engine layer isolates the recognizer behind a protocol so tests
+(and alternate backends, e.g. Whisper or an OpenAI-compatible
+transcription API) don't need the native dependency:
+
+```python
+class DictationStreamHandle(Protocol):
+    def feed_pcm16(self, data: bytes) -> DictationUpdate: ...  # decode a chunk
+    def finish(self) -> str: ...                              # flush tail, final text
+    def close(self) -> None: ...                              # release (client vanished)
+
+@dataclass(frozen=True)
+class DictationUpdate:
+    partial: str          # current in-progress utterance, display-ready (revisable)
+    finalized: str | None # utterance completed by endpointing, if any
+```
+
+Emitted text is **display-ready** — an engine that needs punctuation/casing
+applies it internally before returning, so the route and protocol stay
+engine-agnostic. Most modern models (Whisper, Parakeet) punctuate
+themselves; sherpa is the exception (see below).
+
+**Engine registry.** Engines are registered by name and selected via
+`OMNIGENT_DICTATION_ENGINE`:
+
+```python
+register_engine("sherpa", lambda: SherpaDictationEngine(...), available=_sherpa_available)
+register_engine("fake", FakeDictationEngine)
+```
+
+Adding an engine (Whisper, Parakeet, a hosted API) is one `register_engine`
+call with a factory and an optional availability probe — no edits to
+`get_engine` or `engine_availability`. Third-party engines register
+themselves on import. The default (unset env var) is `sherpa`.
+
+`SherpaDictationEngine` implements the protocol with a process-wide
+`OnlineRecognizer` (streaming transducer: `encoder/decoder/joiner + tokens`)
+shared across connections — the ~650 MB weights load once — plus one
+recognizer *stream* per WebSocket. Endpointing folds completed utterances
+into `finalized` and resets the stream, exactly the loop proven in pi-voice.
+An optional `OnlinePunctuation` model re-punctuates partials/finals
+(lowercase + strip punctuation before re-adding, throttled) so the live
+preview reads like a sentence. This punctuation is **internal** to the
+sherpa engine — the raw transducer emits lowercase, unpunctuated text, so
+the streams beautify before returning; it is not part of the protocol.
+
+Decode calls are CPU-bound → they run via `asyncio.to_thread`, serialized by
+a per-engine `threading.Lock` (sherpa recognizer streams are not documented
+thread-safe), with a module-level semaphore capping concurrent dictation
+connections (default 2, `OMNIGENT_DICTATION_MAX_STREAMS`).
+
+### Configuration
+
+| Env var | Default | Meaning |
+|---|---|---|
+| `OMNIGENT_DICTATION_MODEL_DIR` | `~/.omnigent/models/dictation/asr` | dir containing `encoder*.onnx`, `decoder*.onnx`, `joiner*.onnx`, `tokens.txt` |
+| `OMNIGENT_DICTATION_PUNCT_DIR` | `~/.omnigent/models/dictation/punct` | optional online-punctuation model dir (`model*.onnx` + `bpe.vocab`) |
+| `OMNIGENT_DICTATION_MAX_STREAMS` | `2` | concurrent dictation WebSockets |
+| `OMNIGENT_DICTATION_ENGINE` | unset (`sherpa`) | engine to use by registered name (`sherpa`, `remote`, `fake`) |
+| `OMNIGENT_DICTATION_REMOTE_URL` | unset | worker stream URL for the `remote` engine, e.g. `ws://venus:8100/v1/dictation/stream` |
+
+`scripts/fetch-dictation-models.sh` downloads a known-good pair (streaming
+Nemotron 0.6 B int8 + English online punctuation, both Apache-2.0 upstream)
+into the default locations. Availability is computed lazily and cached:
+extra installed **and** ASR model dir populated.
+
+**Hardware sizing.** Any sherpa-onnx streaming transducer directory works —
+point `OMNIGENT_DICTATION_MODEL_DIR` at it. Streaming dictation needs ≥1×
+realtime decode; measured with this engine loop (int8, 4 threads, 100 ms
+chunks):
+
+| Model | Apple M-series | Intel N95 (4 E-cores, loaded box) | RAM |
+|---|---|---|---|
+| Nemotron 0.6 B (fetch-script default) | ~9× realtime | 0.6–0.7× — **too slow** | ~1.0 GB |
+| `streaming-zipformer-en-2023-06-26` | — | 1.4–2.3× realtime | ~190 MB |
+| `streaming-zipformer-en-20M` | — | 3.6–4.9× realtime | ~130 MB |
+
+On N100/N95-class mini-PC servers, use the mid-size zipformer (accuracy held
+up in spot checks; the 20 M model audibly degrades) and consider
+`OMNIGENT_DICTATION_MAX_STREAMS=1`.
+
+**Other languages.** The engine is language-agnostic — dictation speaks
+whatever language the installed model was trained on. The
+[sherpa-onnx streaming-model catalog](https://k2-fsa.github.io/sherpa/onnx/pretrained_models/online-transducer/index.html)
+includes Chinese, Chinese/English bilingual
+(`sherpa-onnx-streaming-zipformer-bilingual-zh-en-2023-02-20`), French
+(`sherpa-onnx-streaming-zipformer-fr-2023-04-14`), Korean, and more; point
+`OMNIGENT_DICTATION_MODEL_DIR` at any of them. Two caveats: the fetch
+script's punctuation model is English-only, so leave
+`OMNIGENT_DICTATION_PUNCT_DIR` unpopulated for other languages (raw
+recognizer output is emitted as-is), and the mic button's `lang` prop only
+affects the Web Speech path — the server path's language is decided by the
+operator's model choice.
+
+### Remote worker
+
+Where a mini-PC server can't run the model an operator wants at realtime, the
+`remote` engine relays each take to a **dictation worker** on a beefier LAN
+box. The worker is just `create_dictation_router` served on its own — it
+speaks the exact same wire protocol the browser does (PCM frames up,
+transcript events down), so no new protocol or code path was needed. The
+browser never talks to the worker; the main server authenticates the user on
+its own route, then relays over a `websockets` client.
+
+Run the worker wherever the models live (it is **unauthenticated** — bind it
+to a trusted LAN/VPN only):
+
+```
+pip install omnigent[dictation] && scripts/fetch-dictation-models.sh
+python -m omnigent.server.dictation_worker --host 0.0.0.0 --port 8100
+```
+
+Then select the `remote` engine on the main server via env vars — no CLI
+integration is required:
+
+```
+OMNIGENT_DICTATION_ENGINE=remote \
+OMNIGENT_DICTATION_REMOTE_URL=ws://<worker-host>:8100/v1/dictation/stream \
+omnigent server ...
+```
+
+`RemoteDictationEngine` registers by name like every other engine (no changes
+to the route, protocol, or selection logic). `_RemoteStream` bridges the
+worker's async push events into the synchronous handle interface via a daemon
+reader thread, and `close()` releases the worker's capacity slot promptly.
+Fallback is per take: if the worker is unreachable and local models are
+installed, a lazily-built local sherpa engine serves the take instead (its
+weights cost no RAM until the worker actually goes down); each new take
+retries the worker first.
+
+Client timeouts (`web/src/lib/dictation.ts`) are widened to exceed the
+worker's cold-load budget (`_REMOTE_READY_TIMEOUT_S` / `_REMOTE_STOP_TIMEOUT_S`
+in `dictation.py`) so a relayed take doesn't time out on the browser side just
+as the worker finishes loading its model.
+
+### Routes — `omnigent/server/routes/dictation.py`
+
+`create_dictation_router(*, auth_provider=None, engine_provider=None)`,
+registered in `create_app` under `/v1` like every other router. Dictation is
+not session-scoped (the new-chat composer has no session yet), so auth is
+identity-level only: authenticated user required when an auth provider is
+configured, open in single-user/dev mode — the same posture as
+`GET /v1/harnesses`.
+
+Availability rides the existing boot-time capability probe —
+`dictation_available` on **`GET /v1/info`** — rather than a dedicated
+endpoint; the UI needs one boolean, once per page load.
+
+- **`WS /v1/dictation/stream`** — wire protocol (documented in the module
+  docstring, mirroring `terminal_attach.py`):
+  - **Client → server, binary frames**: raw 16 kHz mono s16le PCM.
+  - **Client → server, text frames**: JSON control messages.
+    `{"type": "stop"}` requests a flush; unknown shapes are ignored for
+    forward compatibility.
+  - **Server → client, text frames**: JSON events.
+    - `{"type": "ready"}` — sent once after accept; the client may start
+      streaming audio.
+    - `{"type": "partial", "text": ...}` — revisable in-progress utterance,
+      throttled to ~6 Hz.
+    - `{"type": "final", "text": ...}` — an utterance completed by
+      endpointing; the client appends it and clears the partial region.
+    - `{"type": "stopped", "text": ...}` — response to `stop`: the flushed
+      tail utterance (possibly empty). The server closes after sending it.
+    - `{"type": "error", "message": ...}` — fatal; server closes.
+
+The route holds no session state; a connection is one dictation take.
+
+## Web
+
+### Capture — `web/src/lib/dictation.ts`
+
+`DictationSession` owns the full client pipeline:
+`getUserMedia({audio})` → `AudioContext` → `AudioWorkletNode` (the worklet,
+inlined as a Blob module, downsamples from the context rate to 16 kHz and
+converts Float32 → Int16, posting 100 ms chunks) → binary WS frames via
+`resolveWebSocketUrl("/v1/dictation/stream")` (the same host seam the
+terminal-attach and session-updates sockets ride, so embed hosts and the
+Vite dev proxy keep working). Callbacks: `onPartial`, `onFinal`, `onError`;
+`stop()` sends `{"type":"stop"}`, resolves with the flushed tail, and
+releases the mic tracks and audio context.
+
+Availability comes from the existing `/v1/info` capability context
+(`useServerInfo().dictation_available`) — no extra request.
+
+### Mic button — `ComposerMicButton.tsx`
+
+Mode selection: **Web Speech when the browser has a working one, server
+dictation otherwise** — no behavior change for Chrome/Safari users;
+Electron, Firefox, and Chromium gain a working button. "Working" cannot be
+detected statically: Electron and plain Chromium expose the
+`SpeechRecognition` constructor but its cloud backend rejects them at
+runtime with a `network` error. So Web Speech stays primary whenever the
+constructor exists, and a take that dies with `network` falls back to the
+server **for that take** (retried immediately, so the user's click still
+lands); the next take tries Web Speech again, so a transient blip in real
+Chrome never permanently downgrades the page. With no constructor at all
+(Firefox), takes go to the server directly.
+
+New optional prop `onInterim?: (text: string) => void`. In server mode the
+button emits `onInterim` for partial frames and the existing
+`onTranscript` for finals. Both composers (`ChatPage`, `NewChatDialog`)
+share a small hook, `useDictationInsert(setValue)`, that appends finals and
+maintains a replaceable trailing interim region in the textarea value, so
+text forms live while speaking. When `onInterim` is absent (Web Speech
+mode), behavior is exactly today's.
+
+## Testing
+
+- **Server (pytest, `tests/server/routes/test_dictation.py`)**: drive the
+  real route with `TestClient.websocket_connect` and a fake engine injected
+  through `engine_provider` — no sherpa dependency in CI. Cases:
+  `/v1/info` availability (with and without an engine), ready→partial→final
+  →stopped flow, stop-flush, auth rejection with a no-identity provider,
+  stream-cap rejection.
+- **Engine unit tests** skip unless sherpa-onnx and models are present
+  (developer machines), keeping CI hermetic.
+- **Web (Vitest, `ComposerMicButton.test.tsx` + `dictation.test.ts`)**:
+  mode selection, partial/final callback flow against a mocked WebSocket and
+  mocked AudioWorklet capture.
+- **e2e (Playwright, `tests/e2e_ui/`)**: a fake engine selected via env
+  (`OMNIGENT_DICTATION_ENGINE=fake`, emits a scripted transcript) lets the
+  full browser→WS→server→composer loop run headless without a mic:
+  the test grants fake mic permissions, clicks the mic button, and asserts
+  the scripted text lands in the composer.
+
+## Rollout / compatibility
+
+- No schema changes, no migrations, no new required deps.
+- Servers without the extra: `/v1/info` reports `dictation_available: false`;
+  the web UI behaves exactly as today.
+- Old web clients against new servers: unaffected (new route + one new
+  `/v1/info` field only).
+- New web clients against old servers: `/v1/info` lacks the field → treated
+  as unavailable → today's behavior.

dev/benchmarks/omnigent/README.md

@@ -44,7 +44,8 @@ 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).
+(CI thresholds), `--network-delay-ms MS` (simulated client↔server latency,
+see *Network* below).
 
 ## Journeys
 
@@ -59,6 +60,8 @@ latency run), `--requests N` / `--concurrency N` (throughput), `--runs N`,
 | `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 |
+| `list_projects` | `GET /v1/sessions/projects` — sidebar project list (dual-read union) | project count |
+| `list_project_sessions` | `GET /v1/sessions?project=` — a project folder's sessions (dual-read filter) | sessions/project |
 
 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
@@ -81,23 +84,21 @@ 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 |
+| `session_cold_start` | Create a new host-bound session and time its fresh runner launch through the first token — the full new-conversation cold path |
+| `session_cold_restart` | With an existing session's runner stopped before the sample, post a user message and time the automatic runner relaunch to first token |
 | `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.
+The two cold journeys use a real `omni host` daemon. `session_cold_start`
+creates a new host-bound session per sample, while `session_cold_restart`
+creates one session up front and sends `stop_session` before each sample. That
+control event preserves the conversation but stops its runner; the timed user
+message then follows the production auto-relaunch path. In both cases the host
+spawns a fresh runner with its own binding token and reverse tunnel, so the
+latency includes process startup, tunnel registration, and first-token
+dispatch. The daemon reaps any remaining runners when the benchmark exits.
 
 `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
@@ -115,6 +116,89 @@ dispatch/streaming/cancel overhead, not model latency.
 Add a journey by registering a `Journey` in `journeys.py` (set `needs_runner`
 for full-turn journeys).
 
+## Network requests + simulated delay
+
+Two related knobs for reasoning about **network cost** — the round-trips a
+journey makes and what they'd cost over a real network, both of which loopback
+otherwise hides.
+
+### Requests-per-op (`http_requests` / `avg_http_requests_per_op`)
+
+Every run reports how many HTTP requests **the server handled** during its
+timed region, divided by successful ops → requests-per-op. This is the
+deterministic, noise-free signal: a change that adds or removes a round-trip
+moves the count directly, independent of timing jitter.
+
+The value is the *server-side* count, not just what the benchmark process
+issues — so for the full-turn (`needs_runner`) journeys it also captures the
+cross-process traffic a client-side hook can't see (runner → server callbacks,
+host → server). That's where the count is genuinely unknown and interesting; for
+the HTTP/API journeys it's known by construction (`list_sessions` = 1,
+`create_session` = 2 for the POST + inline DELETE, etc.).
+
+How it works, and why it never ships in production:
+
+- The server already tracks a cumulative request counter
+  (`ServerPerformanceMetrics.total_started`), but it lives in the server
+  subprocess's memory and is only pushed to OTel. The harness needs to *read*
+  it, so a tiny router (`debug_router.py`) exposes it at
+  `GET /debug/server-metrics`.
+- That router lives under `dev/`, which `pyproject.toml` excludes from the wheel
+  (`include = ["omnigent*"]`) — a production install can't even import it.
+- It's mounted only via the `debug_router_modules` config key, which mirrors the
+  existing `policy_modules` load-by-dotted-path seam (`create_app` →
+  `_load_debug_routers`). The harness's generated `server.yaml` sets it;
+  production config never does. A module that fails to import is logged and
+  skipped, so a stray key is a no-op where `dev/` is absent.
+- The harness (`environment.py`) reads the endpoint around each run's timed
+  region and diffs it (subtracting its own closing poll). Counting is
+  best-effort: if the endpoint is unreachable the run still reports latency,
+  just with `http_requests: null`.
+
+**Per-route appendix (`network_routes`).** Beyond the single per-op number, the
+endpoint also returns a per-route tally (keyed by the low-cardinality FastAPI
+template, e.g. `POST /v1/sessions`), so each journey's `summary` carries a
+`network_routes` breakdown — every endpoint the journey hit, its total request
+count, and per-op count, sorted chattiest-first. Since the count is near
+identical across runs, it's summed across the summary runs and grouped by route.
+This is what makes the count *actionable*: for `session_cold_start` it names
+which endpoints the ~12 requests/op are spread across (including the
+cross-process runner→server / host→server calls), not just the total. The
+harness's own counter-poll route is filtered out. The raw per-run map is in each
+run's `route_requests`.
+
+**Tunnel round-trips are not counted.** Steady-state server↔runner traffic is
+frames multiplexed over one long-lived WebSocket tunnel, not fresh HTTP requests
+— so neither this counter nor an HTTP hook sees them as "requests." Counting
+tunnel frames would need instrumenting the tunnel transport; it's out of scope
+for v1.
+
+### Simulated network delay (`--network-delay-ms`)
+
+Loopback has ~zero latency, so the benchmark can't tell a chatty journey (many
+round-trips) from a lean one on wall-clock alone. `--network-delay-ms MS`
+(default `0`) injects an artificial sleep before **every request the benchmark
+client sends**, via an httpx request event hook — modelling a real client↔server
+network hop. Combined with the per-op request count, `delay × requests-per-op`
+is the wall-clock cost those round-trips add, so the two features reinforce each
+other when testing a network optimization.
+
+**Scope note (v1):** the delay models the **client↔server** hop only — the hop
+the benchmark process owns. The cross-process server↔runner tunnel and
+server→mock-LLM hops are *not* delayed (they'd need injecting sleep into the
+runner's client / the tunnel transport, in separate processes). Documented
+follow-up. The nightly and PR workflows run at `0` for stable, comparable trend
+data; dispatch the workflow with a higher `network_delay_ms` when investigating
+a network optimization.
+
+**Mind the CI time budget.** The delay applies to *every* client→server
+request, so it multiplies across the full-turn journeys' round-trips — a cold
+start makes ~12 requests/op. A large delay across the whole default journey set
+can exceed the workflow's 30-min per-leg timeout (empirically, with the older
+poll-based turn driver `network_delay_ms=100` over all journeys timed out; `10`
+finishes in ~6 min). For a bigger delay, pair it with a `--journeys` subset of
+the HTTP journeys, where the count is 1–2/op.
+
 ## Seeding a realistic corpus
 
 `seed.py` writes a sizeable, deterministic corpus directly through the store
@@ -123,17 +207,26 @@ 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
+    --database-uri sqlite:////abs/path/bench.db --sessions 5000 --items-per-session 50 \
+    --projects 20 --filed-fraction 0.5
 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
+The corpus also seeds **first-class projects** and files a fraction of sessions
+into them, so `list_projects` / `list_project_sessions` measure a realistic
+sidebar instead of an empty project set. `--projects N` sets the folder count
+(0 = none) and `--filed-fraction F` the fraction of sessions filed (round-robin
+across the folders); the defaults (20 projects, 0.5) put ~1/40th of the corpus
+in each folder. Projects are owned by the reserved `"local"` user the loopback
+server resolves to, so the owner-scoped project reads see them.
+
+Seeding is **idempotent**: a matching corpus (same sessions/items/projects/
+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.
 
@@ -175,7 +268,7 @@ document without running the harness.
 
 ```jsonc
 {
-  "schema_version": 2,
+  "schema_version": 6,
   "generated_at": "<ISO-8601 UTC>",
   "git_sha": "<HEAD sha>",
   "git_branch": "<branch>",
@@ -183,7 +276,7 @@ document without running the harness.
   "harness": "http-only",
   "config": {"iterations": 100, "requests": 500, "concurrency": 1,
              "runs": 3, "warmup": 10, "with_runner": false,
-             "backend": "sqlite"},
+             "backend": "sqlite", "network_delay_ms": 0.0},
   "journeys": {
     "<journey name>": {
       "kind": "latency" | "throughput",
@@ -192,19 +285,47 @@ document without running the harness.
       "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": …}
+         "p99_ms": …, "max_ms": …, "rps": …,
+         "http_requests": N,          // server HTTP requests during the timed region; null if uncounted
+         "http_requests_per_op": …,   // http_requests / n_success; null if uncounted
+         "route_requests": {"POST /v1/sessions": N, ...}}  // per-route breakdown; {} if uncounted
       ],
-      "summary": {"avg_mean_ms": …, "avg_p50_ms": …, "avg_p95_ms": …,
-                  "avg_p99_ms": …, "avg_rps": …}    // averaged across runs
+      "summary": {"runs_total": 3, "runs_ok": 3,   // how many runs the averages cover
+                  "avg_mean_ms": …, "avg_p50_ms": …, "avg_p95_ms": …,
+                  "avg_p99_ms": …, "avg_rps": …,   // averaged over the runs_ok runs
+                  "avg_http_requests_per_op": …,   // present only when a run was counted
+                  "network_routes": [              // per-route appendix, sorted by per_op desc
+                    {"route": "POST /v1/sessions", "requests": N, "per_op": …}
+                  ]}                               // present only when a run recorded routes
     }
+    // A journey that errored out of measurement entirely instead carries:
+    //   {"kind", "backend", "needs_runner", "runs": [], "summary": {},
+    //    "skipped": true, "error": "HTTPStatusError: ..."}
   }
 }
 ```
 
+The `http_requests*` / `route_requests` / `network_routes` fields are the
+server-side request count and its per-endpoint breakdown (see *Network* above);
+`network_delay_ms` records the simulated client↔server latency the run used.
+
 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.
 
+**Failures never abort the run.** A per-operation error is recorded in that
+run's `failures` breakdown (keyed `HTTP 500` etc.); a run in which *every*
+operation failed keeps its per-run row but is excluded from the `summary`
+averages (`runs_ok` < `runs_total`) so a failed run can't masquerade as an
+infinitely fast one. A journey whose `setup` fails (e.g. a 500 resolving a
+target session — the exact crash this harness used to die on) records a single
+`setup: HTTP 500` failed run and moves on. Any other unexpected per-journey
+error is caught in `run.py`, recorded as `"skipped": true` with the `error`
+string, and the remaining journeys still run. Skips/all-failed journeys are
+non-fatal on their own, but if any CI threshold (`--max-p50-ms` etc.) is
+supplied, a journey with no successful sample fails the gate — the guarantee
+couldn't be verified.
+
 ## Layout
 
 | File | Role |
@@ -212,9 +333,10 @@ the same ETL flatten works — keyed by `journey` and `backend`. Bump
 | `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` |
+| `environment.py` | server (± runner + mock LLM) lifecycle; `--database-uri`; request-count read + network-delay hook |
 | `measure.py` | `RunResult`, percentile, aggregation, thresholds, tables |
 | `schema.py` | `SCHEMA_VERSION`, `build_report`, git/host metadata |
+| `debug_router.py` | CI-only `GET /debug/server-metrics` plugin router (never shipped in the wheel) |
 | `sample_output.json` | committed example of the JSON contract |
 
 The smoke test is `tests/benchmarks/test_benchmark_smoke.py` (boots the server
@@ -260,4 +382,15 @@ seeding.
 - **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.
+  `configure_mock` / `set_mock_fallback` seam if that's ever wanted. (Distinct
+  from `--network-delay-ms`, which models the *client↔server* hop — see
+  *Network* above.)
+- **Wider network-delay coverage.** `--network-delay-ms` v1 delays only the
+  client↔server hop (the one the benchmark process owns). Extending it to the
+  server↔runner tunnel and server→mock-LLM hops would need injecting the delay
+  into the runner's httpx client and the tunnel transport in their own
+  processes.
+- **Tunnel round-trip counting.** `http_requests` counts HTTP the server
+  handles, not frames on the persistent server↔runner WebSocket tunnel.
+  Counting those (for a true per-turn round-trip figure) would mean
+  instrumenting the tunnel transport's `RequestFrame` dispatch.

dev/benchmarks/omnigent/compare.py

@@ -33,6 +33,24 @@ def _fmt_delta(v: float | None) -> str:
     return f"{sign}{v * 100:.1f}%"
 
 
+def _fmt_req(row: dict) -> str:
+    """Format a journey's requests-per-op as ``base→cand`` (or a single value).
+
+    ``—`` when neither side counted; a bare value when only one side has it
+    (a new journey, or a baseline predating request counting). A change in the
+    count means a round-trip was added or removed — a deterministic signal
+    independent of the latency deltas.
+    """
+    b, c = row.get("b_req"), row.get("c_req")
+    if b is None and c is None:
+        return "—"
+    if b is None:
+        return f"{c:.1f}"
+    if c is None:
+        return f"{b:.1f}"
+    return f"{b:.1f}" if b == c else f"{b:.1f}→{c:.1f}"
+
+
 def compare_reports(
     baseline: dict,
     candidate: dict,
@@ -60,6 +78,28 @@ def compare_reports(
         c_p50 = c_summary.get("avg_p50_ms")
         c_p95 = c_summary.get("avg_p95_ms")
 
+        # A skipped journey (or one whose runs all failed) carries no metric
+        # keys. Report it as its own status instead of computing a delta off a
+        # missing value (which would read as a spurious -100% improvement).
+        c_req = c_summary.get("avg_http_requests_per_op")
+        if c_p50 is None:
+            b_j_summary = baseline_journeys.get(name, {}).get("summary", {})
+            rows.append(
+                {
+                    "journey": name,
+                    "status": "skipped",
+                    "b_p50": b_j_summary.get("avg_p50_ms"),
+                    "c_p50": None,
+                    "b_p95": b_j_summary.get("avg_p95_ms"),
+                    "c_p95": None,
+                    "delta_p50": None,
+                    "delta_p95": None,
+                    "b_req": b_j_summary.get("avg_http_requests_per_op"),
+                    "c_req": c_req,
+                }
+            )
+            continue
+
         if name not in baseline_journeys:
             rows.append(
                 {
@@ -71,6 +111,8 @@ def compare_reports(
                     "c_p95": c_p95,
                     "delta_p50": None,
                     "delta_p95": None,
+                    "b_req": None,
+                    "c_req": c_req,
                 }
             )
             continue
@@ -88,6 +130,8 @@ def compare_reports(
                     "c_p95": c_p95,
                     "delta_p50": None,
                     "delta_p95": None,
+                    "b_req": None,
+                    "c_req": c_req,
                 }
             )
             continue
@@ -95,6 +139,7 @@ def compare_reports(
         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)
+        b_req = b_summary.get("avg_http_requests_per_op")
 
         c_p50 = c_p50 or 0.0
         c_p95 = c_p95 or 0.0
@@ -115,6 +160,8 @@ def compare_reports(
                 "b_p95": b_p95,
                 "c_p95": c_p95,
                 "delta_p95": delta_p95,
+                "b_req": b_req,
+                "c_req": c_req,
             }
         )
 
@@ -122,7 +169,7 @@ def compare_reports(
 
 
 def _status_style(status: str) -> str:
-    return {"regression": "red", "new": "cyan", "ok": "green"}.get(status, "")
+    return {"regression": "red", "new": "cyan", "ok": "green", "skipped": "yellow"}.get(status, "")
 
 
 def print_table(rows: list[dict], threshold: float) -> None:
@@ -143,6 +190,7 @@ def print_table(rows: list[dict], threshold: float) -> None:
     table.add_column("Base P95 ms", justify="right")
     table.add_column("Cand P95 ms", justify="right")
     table.add_column("Δ P95", justify="right")
+    table.add_column("Req/op", justify="right")
 
     for row in rows:
         style = _status_style(row["status"])
@@ -164,6 +212,7 @@ def print_table(rows: list[dict], threshold: float) -> None:
             _fmt_ms(row["b_p95"]),
             _fmt_ms(row["c_p95"]),
             delta_p95_str,
+            _fmt_req(row),
         )
 
     console.print()
@@ -179,13 +228,13 @@ def build_markdown(rows: list[dict], threshold: float, passed: bool) -> str:
         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 |",
-        "| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: |",
+        " | Base P95 ms | Cand P95 ms | Δ P95 | Req/op |",
+        "| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |",
     ]
 
     for row in rows:
         status = row["status"]
-        emoji = {"regression": "🔴", "new": "🆕", "ok": "✅"}.get(status, status)
+        emoji = {"regression": "🔴", "new": "🆕", "ok": "✅", "skipped": "⚠️"}.get(status, status)
         b_p50 = _fmt_ms(row["b_p50"])
         c_p50 = _fmt_ms(row["c_p50"])
         d_p50 = _fmt_delta(row["delta_p50"])
@@ -195,7 +244,7 @@ def build_markdown(rows: list[dict], threshold: float, passed: bool) -> str:
         lines.append(
             f"| {row['journey']} | {emoji} {status} "
             f"| {b_p50} | {c_p50} | {d_p50} "
-            f"| {b_p95} | {c_p95} | {d_p95} |"
+            f"| {b_p95} | {c_p95} | {d_p95} | {_fmt_req(row)} |"
         )
 
     lines.append("")
@@ -252,11 +301,16 @@ def main(argv: list[str] | None = None) -> int:
 
     regressions = [r for r in rows if r["status"] == "regression"]
     new_journeys = [r for r in rows if r["status"] == "new"]
+    skipped = [r for r in rows if r["status"] == "skipped"]
 
     if new_journeys:
         names = ", ".join(r["journey"] for r in new_journeys)
         console.print(f"[cyan]New journeys (no baseline):[/cyan] {names}")
 
+    if skipped:
+        names = ", ".join(r["journey"] for r in skipped)
+        console.print(f"[yellow]Skipped (no candidate metrics):[/yellow] {names}")
+
     if regressions:
         console.print(
             f"[red bold]REGRESSION DETECTED[/red bold] in "

dev/benchmarks/omnigent/debug_router.py

@@ -0,0 +1,62 @@
+"""CI-only debug router exposing the server's request counter over HTTP.
+
+The benchmark harness runs the server as a subprocess, so it cannot read the
+in-process ``ServerPerformanceMetrics`` counter directly. This router surfaces
+that counter on ``GET /debug/server-metrics`` so the harness can diff it around
+each journey's timed region and report requests-per-op — including the
+cross-process traffic (runner → server callbacks, host → server) that a
+client-side hook in the benchmark process can't see.
+
+**This never reaches the production server.** Three independent reasons:
+
+1. The module lives under ``dev/``, which ``pyproject.toml`` excludes from the
+   wheel (``include = ["omnigent*"]``), so a production install cannot import it.
+2. It is loaded only via the ``debug_router_modules`` config key, which the
+   benchmark's generated ``server.yaml`` sets and production config never does.
+3. ``create_app`` loads the module tolerantly — an ``ImportError`` logs a
+   warning and skips, so even a stray config key is a no-op where ``dev/`` is
+   absent.
+
+``create_app`` reads the module-level ``DEBUG_ROUTERS`` list (mirroring the
+``POLICY_REGISTRY`` convention) and mounts each ``(router, prefix, tags)`` entry.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Request
+
+router = APIRouter()
+
+
+@router.get("/server-metrics")
+async def server_metrics(request: Request) -> dict[str, object]:
+    """Return the server's cumulative HTTP request counters.
+
+    Reads the process-local :class:`ServerPerformanceMetrics` tracker stashed on
+    ``app.state.server_metrics``. The counters are monotonic since process
+    start; the harness diffs two reads to get a journey's request volume.
+
+    ``route_counts`` additionally breaks the total down by low-cardinality
+    route template (``"METHOD /v1/sessions/{session_id}"`` → count), letting the
+    harness attribute a journey's requests to specific endpoints — including the
+    cross-process runner → server / host → server calls a client-side hook can't
+    see.
+
+    :param request: Incoming request, used to reach ``app.state``.
+    :returns: ``total_started`` / ``total_completed`` / ``total_failed`` /
+        ``in_flight`` plus a ``route_counts`` map from the current metrics.
+    """
+    metrics = request.app.state.server_metrics
+    snapshot = metrics.snapshot()
+    return {
+        "total_started": snapshot.total_started,
+        "total_completed": snapshot.total_completed,
+        "total_failed": snapshot.total_failed,
+        "in_flight": snapshot.in_flight,
+        "route_counts": metrics.route_counts(),
+    }
+
+
+# Consumed by ``create_app(debug_router_modules=...)``: each entry is mounted as
+# ``app.include_router(router, prefix=prefix, tags=tags)``.
+DEBUG_ROUTERS: list[tuple[APIRouter, str, list[str]]] = [(router, "/debug", ["debug"])]

dev/benchmarks/omnigent/environment.py

@@ -23,16 +23,18 @@ from __future__ import annotations
 import asyncio
 import contextlib
 import io
+import json
 import os
 import signal
 import socket
 import subprocess
 import sys
 import tarfile
+import threading
 import time
 import uuid
 from pathlib import Path
-from typing import IO
+from typing import IO, NamedTuple
 
 import httpx
 import yaml
@@ -55,10 +57,12 @@ _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
+# Budget for the host daemon (host-backed cold journeys) 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
+# Budget for a host-owned runner tunnel to disappear after ``stop_session``.
+_RUNNER_OFFLINE_TIMEOUT_S = 30.0
 
 # Terminal SSE events — if one arrives before any delta, the turn produced no
 # streamed text (a failure for the TTFT journey).
@@ -81,6 +85,49 @@ _DEFAULT_HARNESS = "openai-agents"
 _POLICY_LLM_KEY = "_policy_llm_"
 _POLICY_ALLOW = '{"action": "allow", "reason": ""}'
 
+# Dotted path to the CI-only debug router (under ``dev/``, never shipped in the
+# wheel). The server loads it via the ``debug_router_modules`` config key to
+# expose ``GET /debug/server-metrics`` for per-journey request counting.
+_DEBUG_ROUTER_MODULE = "dev.benchmarks.omnigent.debug_router"
+_SERVER_METRICS_PATH = "/debug/server-metrics"
+
+
+class ServerRequestSnapshot(NamedTuple):
+    """A point-in-time read of the server's cumulative request counters.
+
+    :param total: ``total_started`` — every HTTP request the server has handled
+        since process start.
+    :param routes: ``"METHOD /route/{template}"`` mapped to its cumulative
+        count, for attributing a journey's requests to specific endpoints.
+    """
+
+    total: int
+    routes: dict[str, int]
+
+
+def _sse_session_status(data: str) -> str | None:
+    """Extract the status from a ``session.status`` SSE ``data:`` payload.
+
+    Returns the status string (``"running"`` / ``"waiting"`` / ``"idle"`` /
+    ``"failed"``) for a ``session.status`` event, else ``None`` (a different
+    event, the ``[DONE]`` sentinel, or unparseable JSON). Tolerates both the
+    nested ``{"data": {"status": ...}}`` and flat ``{"status": ...}`` shapes.
+
+    :param data: The SSE ``data:`` line body, already stripped of the prefix.
+    :returns: The session status, or ``None`` when this isn't a status event.
+    """
+    if not data or data == "[DONE]":
+        return None
+    try:
+        payload = json.loads(data)
+    except (ValueError, TypeError):
+        return None
+    if not isinstance(payload, dict) or payload.get("type") != "session.status":
+        return None
+    inner = payload.get("data")
+    status = inner.get("status") if isinstance(inner, dict) else payload.get("status")
+    return status if isinstance(status, str) else None
+
 
 def _find_free_port() -> int:
     """Bind an ephemeral port and return it (races are tolerated by retries)."""
@@ -112,9 +159,8 @@ class BenchEnvironment:
     :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.
+        the cold-start and cold-restart journeys use host-bound sessions that
+        fire ``host.launch_runner`` and launch their own fresh runners.
     :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
@@ -124,6 +170,11 @@ class BenchEnvironment:
     :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.
+    :param network_delay_ms: Artificial latency in milliseconds injected before
+        every request the benchmark client sends to the server, modelling a
+        real client↔server network hop that loopback lacks. ``0`` (default)
+        adds no delay. Combined with per-op request counts, it turns each
+        journey's round-trip count into wall-clock cost.
     """
 
     def __init__(
@@ -134,6 +185,7 @@ class BenchEnvironment:
         database_uri: str | None = None,
         harness: str = _DEFAULT_HARNESS,
         model: str = _DEFAULT_MODEL,
+        network_delay_ms: float = 0.0,
     ) -> 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
@@ -143,6 +195,7 @@ class BenchEnvironment:
         self.database_uri = database_uri
         self.harness = harness
         self.model = model
+        self.network_delay_ms = network_delay_ms
         self.base_url = ""
         self.mock_url = ""
         self.runner_id = ""
@@ -160,16 +213,34 @@ class BenchEnvironment:
         self._runner_base_env: dict[str, str] = {}
         self._log_handles: list[IO[bytes]] = []
         self._agent_cache: dict[str, str] = {}
+        self._resource_samples: list[dict[str, float]] = []
+        self._sampler_stop: threading.Event = threading.Event()
+        self._sampler_thread: threading.Thread | None = None
 
     # ── lifecycle ────────────────────────────────────────────
 
     async def __aenter__(self) -> BenchEnvironment:
         await asyncio.to_thread(self._start)
+        # A request event hook injects the simulated client↔server network
+        # delay before each request leaves the benchmark process. Registered
+        # only when a delay is set so the zero-delay default path is untouched.
+        event_hooks: dict[str, list[object]] = {}
+        if self.network_delay_ms > 0:
+            delay_s = self.network_delay_ms / 1000.0
+
+            async def _delay_request(_request: httpx.Request) -> None:
+                await asyncio.sleep(delay_s)
+
+            event_hooks["request"] = [_delay_request]
         self.client = httpx.AsyncClient(
             base_url=self.base_url,
             timeout=300.0,
             headers={"Origin": OMNIGENT_INTERNAL_WS_ORIGIN},
+            event_hooks=event_hooks,  # type: ignore[arg-type]
         )
+        # Start background resource sampler (server CPU + memory).
+        self._sampler_thread = threading.Thread(target=self._sample_resources, daemon=True)
+        self._sampler_thread.start()
         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.
@@ -181,6 +252,9 @@ class BenchEnvironment:
     async def __aexit__(self, *exc: object) -> None:
         if self.client is not None:
             await self.client.aclose()
+        self._sampler_stop.set()
+        if self._sampler_thread is not None:
+            self._sampler_thread.join(timeout=5)
         await asyncio.to_thread(self._stop)
 
     def _start(self) -> None:
@@ -216,9 +290,8 @@ class BenchEnvironment:
             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.
+        # warm journeys; the daemon exists so host-backed cold journeys can
+        # launch their own runners on demand. The two never share a runner id.
         if self.with_host:
             self._host_proc = self._spawn_host(base_env)
             self._wait_host_online()
@@ -247,6 +320,98 @@ class BenchEnvironment:
 
         shutil.rmtree(self._tmp, ignore_errors=True)
 
+    def _sample_resources(self, interval: float = 1.0) -> None:
+        """Sample the server process's CPU and RSS memory at *interval*-second intervals.
+
+        Runs in a daemon thread; exits when ``_sampler_stop`` is set or the
+        process terminates. The first ``cpu_percent`` call always returns 0.0
+        (psutil baseline) — we discard it so only real measurements accumulate.
+        """
+        try:
+            import psutil
+        except ImportError:
+            return
+        if self._server_proc is None:
+            return
+        try:
+            proc = psutil.Process(self._server_proc.pid)
+            proc.cpu_percent()  # baseline; discard
+        except psutil.NoSuchProcess:
+            return
+        while not self._sampler_stop.is_set():
+            try:
+                cpu = proc.cpu_percent()
+                mem = proc.memory_info().rss
+                self._resource_samples.append({"cpu_pct": cpu, "rss_bytes": mem})
+            except psutil.NoSuchProcess:
+                break
+            self._sampler_stop.wait(timeout=interval)
+
+    @property
+    def resource_usage(self) -> dict[str, object]:
+        """Summarise sampled CPU% and RSS across the benchmark run.
+
+        :returns: A dict with ``cpu_pct`` and ``rss_bytes`` sub-dicts each
+            containing ``mean``, ``min``, ``max``, ``samples``. Empty dicts
+            when no samples were collected (psutil unavailable or server never
+            started).
+        """
+        if not self._resource_samples:
+            return {"cpu_pct": {}, "rss_bytes": {}}
+        cpu = [s["cpu_pct"] for s in self._resource_samples]
+        rss = [s["rss_bytes"] for s in self._resource_samples]
+        import statistics as _stats
+
+        return {
+            "cpu_pct": {
+                "mean": _stats.mean(cpu),
+                "min": min(cpu),
+                "max": max(cpu),
+                "samples": len(cpu),
+            },
+            "rss_bytes": {
+                "mean": _stats.mean(rss),
+                "min": min(rss),
+                "max": max(rss),
+                "samples": len(rss),
+            },
+        }
+
+    async def server_request_snapshot(self) -> ServerRequestSnapshot:
+        """Read the server's cumulative request counters (total + per-route).
+
+        Reads the CI-only ``GET /debug/server-metrics`` endpoint the server
+        mounts from ``debug_router_modules``. The counters are monotonic since
+        the server process started; callers diff two reads to get the requests
+        the server handled during a window — including cross-process traffic
+        (runner → server callbacks, host → server) invisible to a client-side
+        hook in the benchmark process.
+
+        The count-poll request itself hits the server, so it increments the
+        counters; the caller accounts for its own polls when computing per-op
+        volume. Uses a short-lived client so it never carries the simulated
+        network delay wired onto ``self.client``.
+
+        :returns: A :class:`ServerRequestSnapshot` of ``total_started`` and the
+            per-route breakdown.
+        :raises RuntimeError: If the debug endpoint is unreachable, which means
+            the debug router did not load (a benchmark misconfiguration).
+        """
+        try:
+            async with httpx.AsyncClient(base_url=self.base_url, timeout=10.0) as client:
+                resp = await client.get(_SERVER_METRICS_PATH)
+                resp.raise_for_status()
+        except httpx.HTTPError as exc:
+            raise RuntimeError(
+                f"server debug metrics endpoint {_SERVER_METRICS_PATH} unreachable "
+                f"({exc!r}); is the debug router loaded? logs in {self._tmp}"
+            ) from exc
+        body = resp.json()
+        return ServerRequestSnapshot(
+            total=int(body["total_started"]),
+            routes={str(k): int(v) for k, v in body.get("route_counts", {}).items()},
+        )
+
     # ── spawns ───────────────────────────────────────────────
 
     def _log(self, name: str) -> IO[bytes]:
@@ -284,27 +449,24 @@ class BenchEnvironment:
             str(artifact_dir),
         ]
         env = {**base_env}
+        # The server always boots with a config that loads the CI-only debug
+        # router (exposing its request counter over HTTP for per-journey network
+        # counting). In runner mode it additionally routes the server-side
+        # policy-classifier LLM at the mock, mirroring live_server — without
+        # that the classifier's client defaults to api.openai.com and errors.
+        server_config: dict[str, object] = {"debug_router_modules": [_DEBUG_ROUTER_MODULE]}
         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)])
+            server_config["llm"] = {
+                "model": _POLICY_LLM_KEY,
+                "connection": {
+                    "base_url": f"{self.mock_url}/v1",
+                    "api_key": "mock-key",
+                },
+            }
             env["OMNIGENT_RUNNER_TUNNEL_TOKEN"] = binding_token
+        server_cfg = self._tmp / "server.yaml"
+        server_cfg.write_text(yaml.safe_dump(server_config))
+        args.extend(["--config", str(server_cfg)])
         return subprocess.Popen(
             args,
             env=env,
@@ -340,10 +502,8 @@ class BenchEnvironment:
     ) -> 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
+        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).
         """
@@ -640,6 +800,33 @@ class BenchEnvironment:
         bound.raise_for_status()
         return session_id
 
+    async def stop_session_runner(
+        self, session_id: str, *, timeout: float = _RUNNER_OFFLINE_TIMEOUT_S
+    ) -> None:
+        """Stop a host-backed session's runner and wait until it is offline.
+
+        ``stop_session`` preserves the conversation and its host binding. The
+        next user message therefore exercises the production auto-relaunch
+        path instead of starting a new conversation.
+        """
+        assert self.client is not None
+        if not self.with_host:
+            raise RuntimeError("stop_session_runner requires with_host=True")
+        stopped = await self.client.post(
+            f"/v1/sessions/{session_id}/events",
+            json={"type": "stop_session", "data": {}},
+        )
+        stopped.raise_for_status()
+
+        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("runner_online") is False:
+                return
+            await asyncio.sleep(_POLL_INTERVAL_S)
+        raise RuntimeError(f"runner did not stop within {timeout}s (session {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.
 
@@ -677,7 +864,15 @@ class BenchEnvironment:
     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.
+        """Post a user message and await the turn's completion over SSE.
+
+        Subscribes to the session stream, posts the message, then returns when a
+        ``session.status`` event reports ``idle`` *after* the turn has been seen
+        ``running``/``waiting`` — the SSE equivalent of the old poll-to-idle
+        loop, but without hammering ``GET /v1/sessions/{id}`` every 200ms (which
+        polluted the per-journey request count, especially when a turn stalled).
+        The ``seen_running`` guard ensures a warm session's trailing ``idle``
+        from a *prior* turn can't end this wait early.
 
         :raises RuntimeError: If not in runner mode, the turn fails, or it does
             not settle within *timeout* seconds.
@@ -685,27 +880,64 @@ class BenchEnvironment:
         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})")
+        connected = asyncio.Event()
+        settled = asyncio.Event()
+        outcome: dict[str, str] = {}
+
+        async def _read_stream() -> None:
+            seen_running = False
+            try:
+                async with self.client.stream(  # type: ignore[union-attr]
+                    "GET", f"/v1/sessions/{session_id}/stream", timeout=timeout
+                ) as resp:
+                    # First line means the stream is live (server emits a ready
+                    # heartbeat on connect); post only once subscribed so no
+                    # status event for this turn can be missed.
+                    connected.set()
+                    async for line in resp.aiter_lines():
+                        if not line.startswith("data:"):
+                            continue
+                        status = _sse_session_status(line[len("data:") :].strip())
+                        if status is None:
+                            continue
+                        if status in ("running", "waiting"):
+                            seen_running = True
+                        elif status == "failed":
+                            outcome["failed"] = "turn failed"
+                            settled.set()
+                            return
+                        elif status == "idle" and seen_running:
+                            settled.set()
+                            return
+            except httpx.HTTPError as exc:
+                outcome["error"] = repr(exc)
+                connected.set()
+                settled.set()
+
+        reader = asyncio.create_task(_read_stream())
+        try:
+            await asyncio.wait_for(connected.wait(), timeout=timeout)
+            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()
+            try:
+                await asyncio.wait_for(settled.wait(), timeout=timeout)
+            except TimeoutError as exc:
+                raise RuntimeError(
+                    f"turn did not settle within {timeout}s (session {session_id})"
+                ) from exc
+            if "error" in outcome:
+                raise RuntimeError(f"stream error: {outcome['error']}")
+            if "failed" in outcome:
+                snap = await self.client.get(f"/v1/sessions/{session_id}")
+                last_error = snap.json().get("last_task_error") if snap.is_success else None
+                raise RuntimeError(f"turn failed: {last_error}")
+        finally:
+            reader.cancel()
 
     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)."""
@@ -742,9 +974,9 @@ class BenchEnvironment:
 
         :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.
+            turn's response (warm-session TTFT). ``False`` for a fresh session or
+            a stopped existing session — cold paths where polling for ``idle``
+            would either warm the runner or wait forever on its disconnected state.
         :raises RuntimeError: If not in runner mode, or no response / a terminal
             event arrives within *timeout*.
         """
@@ -845,6 +1077,19 @@ class BenchEnvironment:
             session_id, text, wait_idle_first=True, timeout=timeout
         )
 
+    async def cold_restart_first_delta(
+        self, session_id: str, text: str, *, timeout: float = _TURN_TIMEOUT_S
+    ) -> None:
+        """Post to a stopped existing session and await its first response.
+
+        A stopped session is marked failed rather than idle, so this deliberately
+        skips the warm-session idle poll. The POST itself triggers the host runner
+        relaunch whose latency this path measures.
+        """
+        await self._post_and_await_first_delta(
+            session_id, text, wait_idle_first=False, timeout=timeout
+        )
+
     async def cold_start_first_delta(
         self, agent_id: str, text: str, *, timeout: float = _TURN_TIMEOUT_S
     ) -> None: