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,6 +10,7 @@ dhruv0811
 Edwinhe03
 fanzeyi
 kerryspchang
+kunyuchen
 lisancao
 mahesh-venkatachalam
 mateiz

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

@@ -36,7 +36,7 @@ inputs:
   claude-code-version:
     description: "@anthropic-ai/claude-code npm version to install."
     required: false
-    default: 2.1.170
+    default: 2.1.212
 
 runs:
   using: composite
@@ -64,11 +64,15 @@ runs:
         CLAUDE_CODE_VERSION: ${{ inputs.claude-code-version }}
       run: |
         set -euo pipefail
-        mkdir -p "${GITHUB_WORKSPACE}/.cc-cli"
-        cd "${GITHUB_WORKSPACE}/.cc-cli"
+        # 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 "${GITHUB_WORKSPACE}/.cc-cli/node_modules/.bin" >> "$GITHUB_PATH"
+        echo "$CC_CLI_DIR/node_modules/.bin" >> "$GITHUB_PATH"
 
     - name: Write Omnigent provider config
       shell: bash

.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/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/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

@@ -33,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)"
@@ -63,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)"
@@ -80,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/benchmark-pr.yml

@@ -15,6 +15,7 @@ on:
     paths:
       - "omnigent/db/migrations/**"
       - "omnigent/stores/**"
+      - "dev/benchmarks/**"
       - ".github/workflows/benchmark-pr.yml"
 
 permissions:
@@ -157,12 +158,20 @@ jobs:
         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

.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

@@ -55,48 +55,27 @@ 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: Verify lockfile uses public registry
-        # Fail fast (in seconds, not minutes) if any package-lock.json
-        # resolved URL points at an internal proxy that public CI runners
-        # can't reach — e.g. npm-proxy.cloud.databricks.com. Without this
-        # guard, npm ci silently times out mid-install on Windows/Linux.
-        # Uses the shared normalize_package_lock_registry.py script (same
-        # one wired into pre-commit) so CI and local checks stay in sync.
-        working-directory: web/electron
-        shell: bash
-        run: |
-          python3 ../../scripts/normalize_package_lock_registry.py --check 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
-
-      # The shell-owned update overlay reuses the web UpdateBanner component; it
-      # is built from the web app into electron/overlay/ (gitignored) and shipped
-      # by electron-builder (build.files). The build:<platform> scripts run it
-      # automatically via their `prebuild:*` hook (see web/electron/package.json)
-      # — this step only needs to install the web app's deps so that hook works.
-      - name: Install web deps (for the update overlay build)
-        working-directory: web
-        run: npm ci --legacy-peer-deps --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
 
       # One artifact per platform bundling the COMPLETE electron-updater feed —
       # the installer(s), the .blockmap electron-updater needs for differential

.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,7 @@ 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]

.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

@@ -75,14 +75,14 @@ jobs:
           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

.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}"
@@ -647,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
@@ -657,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:
@@ -667,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/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.

.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
@@ -105,20 +112,6 @@ repos:
         files: ^uv\.lock$
         pass_filenames: true
 
-      # Local `npm install` rewrites every `resolved` URL in
-      # package-lock.json to whatever registry is configured on the
-      # developer's machine (e.g. the Databricks npm proxy via a global
-      # ~/.npmrc). This OSS repo must always commit the public npm registry
-      # (registry.npmjs.org), so normalize it back before it lands — a
-      # proxy URL would make `npm ci` time out on public CI runners. Fixer:
-      # re-stage if it changes. Mirrors normalize-uv-lock-registry above.
-      - id: normalize-package-lock-registry
-        name: normalize package-lock.json registry to npmjs.org
-        language: system
-        entry: .venv/bin/python scripts/normalize_package_lock_registry.py
-        files: ^(web|web/electron|editors/vscode)/package-lock\.json$
-        pass_filenames: true
-
       # Fail if routing.proto changed without regenerating the committed
       # bindings (or vice versa). Verify-only, not a fixer: regen needs
       # grpcio-tools, so CI's `uv sync --extra dev` enforces it (like ktlint).

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

CHANGELOG.md

@@ -5,6 +5,140 @@ 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

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.

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

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/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/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/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.

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 ─────────────────────────────────────────

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.
 
@@ -315,9 +334,56 @@ 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,

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/kubernetes/overlays/sandbox-runners/README.md

@@ -138,6 +138,38 @@ writing nothing to disk — use HTTPS repository URLs. Details by provider match
 | `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

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

@@ -45,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

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

@@ -46,19 +46,12 @@
 
 The Slack integration (`integrations/slack/`) is a standalone Socket-Mode
 process that calls each user's Omnigent server over HTTP + SSE
-(`OmnigentClient` / `OmnigentClientPool`). Today it sends **every request
-unauthenticated**: the pool is *"one unauthenticated client per server URL"*
-(`omnigent.py:337`), and any server with auth enabled returns 401, which the
-bot converts into a dead-end *"authentication … isn't supported yet"* setup
-error (`omnigent.py:23`, `setup.py:144`).
-
-So the bot only works against auth-disabled servers, and when it does work the
-server sees a single shared anonymous identity — it cannot tell one Slack user
-from another, cannot scope permissions, and cannot audit who did what.
-
-We want each Slack user's turns to reach the Omnigent server **as that user's
-own authenticated identity**, without the Slack process ever handling the
-user's Omnigent credentials.
+(`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
 
@@ -85,28 +78,25 @@ Role mapping:
 | Resource Owner           | The Slack user, authenticating in their browser |
 | Out-of-band channel      | Slack (delivers the verification link only)     |
 
-## What already exists (reused, not rebuilt)
+## Shared substrate (reused, not rebuilt)
 
-RFC 8628 primitives are absent (no `device_code` / `user_code` /
-`verification_uri` anywhere), but the substrate is all present:
+The device grant builds on existing server primitives:
 
-- **Poll-endpoint shape** — `POST /auth/cli-login` + `GET /auth/cli-poll` with
-  202-pending / 200-done / 410-expired semantics (`routes/auth.py:484`).
 - **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:329`). The new grant store copies
-  this pattern.
+  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:53`), HS256 with `sub`/`iat`/`exp`/`provider`.
-- **Bearer validation** — `UnifiedAuthProvider._check_cookie` already accepts
+  (`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:477`). Delegated access tokens validate through this path unchanged.
-- **Browser consent under accounts mode** — the `accounts` provider already
+  (`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:150`) is
-  reused for the post-login bounce back to the consent page.
+- **Open-redirect hardening** — `_sanitize_return_to` (`routes/auth.py`) guards
+  the post-login bounce back to the consent page.
 
 ## Design decisions (agreed)
 
@@ -120,14 +110,10 @@ RFC 8628 primitives are absent (no `device_code` / `user_code` /
    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).
-
-   *History:* the secret was implemented, removed, then reintroduced as
-   opt-in. It was removed when the Slack client accepted a **user-supplied**
-   server URL — shipping a shared secret to an arbitrary user-typed host was a
-   secret-exfiltration/SSRF path. That objection is now gone: the Slack socket
-   server's target is a **fixed operator config** (`OMNIGENT_SERVER_URL`), not
-   a user-supplied URL, so the secret only ever travels to the trusted server.
+   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
@@ -149,15 +135,21 @@ RFC 8628 primitives are absent (no `device_code` / `user_code` /
          verification_uri_complete,   # verification_uri?user_code=XYZ
          expires_in: 600, interval: 5 }
 
- 3. Slack server shows the verification link in the setup modal (initiator
-       only). The device_code is NOT included — it never leaves the server
-       pair; only the user_code (in verification_uri_complete) does.
+ 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).
-       Browser authenticates via the server's accounts provider.
-       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 login the user personally started.
+       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
@@ -197,9 +189,8 @@ 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 also **owns** `mint_delegated_token` and
-`DELEGATED_SCOPE` (moved here from `oidc.py`, which retains only
-`mint_session_token` / `mint_session_cookie`).
+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
@@ -275,9 +266,8 @@ HS256 shape (so `_check_cookie` accepts them) plus four delegated-only claims:
 
 ## Slack-side changes
 
-- **`oauth.py` (new)** — device-authorize → post ephemeral link → poll token
-  endpoint (respecting `interval` / `slow_down`) → store tokens. Replaces the
-  `AuthRequiredError` dead-end.
+- **`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
@@ -285,8 +275,8 @@ HS256 shape (so `_check_cookie` accepts them) plus four delegated-only claims:
 - **`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; auth-enabled servers become
-  supported rather than rejected.
+- **`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
@@ -294,7 +284,7 @@ HS256 shape (so `_check_cookie` accepts them) plus four delegated-only claims:
 | # | 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 page names the exact Omnigent identity the grant will act as and the requesting `client_id`, and warns to approve only a self-initiated login. |
+| 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. |
@@ -315,6 +305,17 @@ 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.
@@ -322,6 +323,11 @@ initiation is open — the defense is layered, not a gate:
   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,

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
@@ -113,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
@@ -121,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.
 
@@ -173,7 +268,7 @@ document without running the harness.
 
 ```jsonc
 {
-  "schema_version": 4,
+  "schema_version": 6,
   "generated_at": "<ISO-8601 UTC>",
   "git_sha": "<HEAD sha>",
   "git_branch": "<branch>",
@@ -181,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",
@@ -190,11 +285,18 @@ 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": {"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_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": {},
@@ -203,6 +305,10 @@ document without running the harness.
 }
 ```
 
+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.
@@ -227,9 +333,10 @@ couldn't be verified.
 | `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
@@ -275,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,
@@ -63,17 +81,21 @@ def compare_reports(
         # 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": baseline_journeys.get(name, {}).get("summary", {}).get("avg_p50_ms"),
+                    "b_p50": b_j_summary.get("avg_p50_ms"),
                     "c_p50": None,
-                    "b_p95": baseline_journeys.get(name, {}).get("summary", {}).get("avg_p95_ms"),
+                    "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
@@ -89,6 +111,8 @@ def compare_reports(
                     "c_p95": c_p95,
                     "delta_p50": None,
                     "delta_p95": None,
+                    "b_req": None,
+                    "c_req": c_req,
                 }
             )
             continue
@@ -106,6 +130,8 @@ def compare_reports(
                     "c_p95": c_p95,
                     "delta_p50": None,
                     "delta_p95": None,
+                    "b_req": None,
+                    "c_req": c_req,
                 }
             )
             continue
@@ -113,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
@@ -133,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,
             }
         )
 
@@ -161,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"])
@@ -182,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()
@@ -197,8 +228,8 @@ 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:
@@ -213,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("")

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,6 +23,7 @@ from __future__ import annotations
 import asyncio
 import contextlib
 import io
+import json
 import os
 import signal
 import socket
@@ -33,7 +34,7 @@ import threading
 import time
 import uuid
 from pathlib import Path
-from typing import IO
+from typing import IO, NamedTuple
 
 import httpx
 import yaml
@@ -84,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)."""
@@ -126,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__(
@@ -136,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
@@ -145,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 = ""
@@ -170,10 +221,22 @@ class BenchEnvironment:
 
     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)
@@ -314,6 +377,41 @@ class BenchEnvironment:
             },
         }
 
+    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]:
@@ -351,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,
@@ -769,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.
@@ -777,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)."""

dev/benchmarks/omnigent/journeys.py

@@ -15,6 +15,10 @@ v1 journeys are pure HTTP/API (server + DB, no runner, no LLM):
   ``external_conversation_item`` (see :meth:`BenchEnvironment.seed_items`).
 - ``fork_session`` — fork a session (deep-copy its items), then DELETE.
 - ``add_comment`` — create a review comment on a file (DB write).
+- ``list_projects`` — the sidebar project list (dual-read union of first-class
+  projects + legacy ``omni_project`` label-projects).
+- ``list_project_sessions`` — a project folder's session list, the
+  ``?project=`` dual-read filter behind clicking a project in the sidebar.
 
 ``read_runner_file`` needs a runner but no LLM turn: it plants a file in the
 runner environment (setup) and times the server → runner filesystem read proxy.
@@ -47,7 +51,7 @@ from typing import Literal, cast
 
 import httpx
 
-from .environment import BenchEnvironment
+from .environment import BenchEnvironment, ServerRequestSnapshot
 from .measure import RunResult
 
 # Per-journey context returned by ``setup`` and threaded to ``measure``. Its
@@ -149,7 +153,54 @@ def _setup_failed_result(exc: Exception) -> RunResult:
     return result
 
 
-# ── timed operation (shared by both runners) ─────────────────
+# ── server request counting (shared by both runners) ─────────
+
+# Route key for the harness's own counter-poll (see environment.py's debug
+# endpoint). Filtered out of the per-journey route appendix — it's
+# instrumentation overhead, not the journey's traffic.
+_METRICS_ROUTE_KEY = "GET /debug/server-metrics"
+
+
+async def _count_start(env: BenchEnvironment) -> ServerRequestSnapshot | None:
+    """Snapshot the server request counters before a run's timed region.
+
+    Returns ``None`` (counting disabled for the run) if the counter is
+    unreachable, so a benchmark against a server without the debug router still
+    produces latency numbers — it just omits the network block.
+    """
+    try:
+        return await env.server_request_snapshot()
+    except Exception:  # noqa: BLE001 — counting is best-effort, never fatal
+        return None
+
+
+async def _count_finish(
+    env: BenchEnvironment, start: ServerRequestSnapshot | None, result: RunResult
+) -> None:
+    """Record server HTTP requests handled during the run's timed region.
+
+    Diffs the counters against *start* and stores the total + per-route
+    breakdown on *result*. The closing poll itself hits the server and lands
+    inside the window, so subtract it (1) from the total to leave only the
+    journey's own requests plus any cross-process traffic (runner → server,
+    host → server). The poll targets the debug-metrics route, a bucket no
+    journey uses, so it never pollutes the per-route diff. A negative or
+    unavailable value leaves ``http_requests`` as ``None``.
+    """
+    if start is None:
+        return
+    end = await _count_start(env)
+    if end is None:
+        return
+    result.http_requests = max(0, end.total - start.total - 1)
+    result.route_requests = {
+        route: delta
+        for route, count in end.routes.items()
+        # Exclude the harness's own counter-poll route so the appendix reflects
+        # only the journey's traffic (the total above already backs it out).
+        if route != _METRICS_ROUTE_KEY
+        if (delta := count - start.routes.get(route, 0)) > 0
+    }
 
 
 async def _timed(
@@ -189,6 +240,7 @@ async def run_latency(
                 await journey.run_prepare(env, ctx)
                 await journey.measure(env, ctx)
         result = RunResult()
+        count_start = await _count_start(env)
         wall_start = time.perf_counter()
         for _ in range(iterations):
             try:
@@ -198,6 +250,7 @@ async def run_latency(
                 continue
             await _timed(journey, env, ctx, result)
         result.wall_time = time.perf_counter() - wall_start
+        await _count_finish(env, count_start, result)
         return result
     finally:
         with contextlib.suppress(Exception):  # teardown failure must not abort the suite
@@ -247,9 +300,11 @@ async def run_throughput(
             await asyncio.gather(*[_one(False, throwaway) for _ in range(warmup)])
 
         result = RunResult()
+        count_start = await _count_start(env)
         wall_start = time.perf_counter()
         await asyncio.gather(*[_one(True, result) for _ in range(requests)])
         result.wall_time = time.perf_counter() - wall_start
+        await _count_finish(env, count_start, result)
         return result
     finally:
         with contextlib.suppress(Exception):  # teardown failure must not abort the suite
@@ -338,6 +393,53 @@ async def _measure_load_history(env: BenchEnvironment, ctx: JourneyContext) -> N
     resp.raise_for_status()
 
 
+# Project name for the folder-fetch journey. Self-seeded when the corpus has no
+# project so the ``?project=`` filter has a real member to resolve and return.
+_BENCH_PROJECT_NAME = "bench-project"
+
+
+async def _setup_project_name(env: BenchEnvironment) -> str:
+    """Return a project name to fetch: an existing corpus project, else seed one.
+
+    Mirrors ``_setup_target_session``: real runs read a representative project
+    from the seeded corpus (``seed.py`` files a configurable fraction of sessions
+    into first-class projects), so the folder fetch resolves a realistically
+    populated project. When none exists (empty-DB smoke path) we file one session
+    under a fresh project so the ``?project=`` filter still exercises the real
+    dual-read path instead of an empty match.
+    """
+    assert env.client is not None
+    listing = await env.client.get("/v1/sessions/projects")
+    listing.raise_for_status()
+    projects = listing.json()
+    if projects:
+        return str(projects[0]["name"])
+    # Empty DB: create a first-class project and file one session into it.
+    name = await env.ensure_agent()
+    agent_id = await env.agent_id(name)
+    session_id = await env.create_session(agent_id)
+    created = await env.client.post("/v1/projects", json={"name": _BENCH_PROJECT_NAME})
+    created.raise_for_status()
+    filed = await env.client.patch(
+        f"/v1/sessions/{session_id}", json={"project_id": created.json()["id"]}
+    )
+    filed.raise_for_status()
+    return _BENCH_PROJECT_NAME
+
+
+async def _measure_list_projects(env: BenchEnvironment, _ctx: JourneyContext) -> None:
+    assert env.client is not None
+    resp = await env.client.get("/v1/sessions/projects")
+    resp.raise_for_status()
+
+
+async def _measure_list_project_sessions(env: BenchEnvironment, ctx: JourneyContext) -> None:
+    assert env.client is not None
+    project = cast(str, ctx)  # _setup_project_name
+    resp = await env.client.get("/v1/sessions", params={"limit": 20, "project": project})
+    resp.raise_for_status()
+
+
 @dataclass
 class _ForkContext:
     """Fork-journey context: the session to fork + the forks to clean up.
@@ -620,6 +722,21 @@ ALL_JOURNEYS: dict[str, Journey] = {
             concurrency_safe=True,
             description="GET /v1/sessions?search_query= — unindexed LIKE over titles + items.",
         ),
+        Journey(
+            name="list_projects",
+            kind="latency",
+            measure=_measure_list_projects,
+            concurrency_safe=True,
+            description="GET /v1/sessions/projects — sidebar project list (dual-read union).",
+        ),
+        Journey(
+            name="list_project_sessions",
+            kind="latency",
+            measure=_measure_list_project_sessions,
+            setup=_setup_project_name,
+            concurrency_safe=True,
+            description="GET /v1/sessions?project= — a project folder's sessions (dual-read).",
+        ),
         Journey(
             name="fork_session",
             kind="latency",

dev/benchmarks/omnigent/measure.py

@@ -11,12 +11,18 @@ from __future__ import annotations
 
 import math
 import statistics
+import sys
 from dataclasses import dataclass, field
 
 from rich.console import Console
 from rich.table import Table
 
-console = Console()
+# Rich auto-detects terminal width, but falls back to 80 columns when stdout is
+# not a TTY (CI logs, piped output) — which truncates the wider table columns
+# (e.g. ``HTTP/op`` → ``HTTP…``). Give the non-interactive path a comfortable
+# floor so every header renders in full; real terminals keep auto-detection.
+_NONINTERACTIVE_WIDTH = 160
+console = Console(width=None if sys.stdout.isatty() else _NONINTERACTIVE_WIDTH)
 
 
 @dataclass
@@ -28,11 +34,21 @@ class RunResult:
     :param failures: Failure reason (e.g. ``"HTTP 500"`` / an exception
         class name) mapped to how many times it occurred.
     :param wall_time: Total elapsed seconds for the run, used for throughput.
+    :param http_requests: Total HTTP requests the server handled during this
+        run's timed region (from the server-side counter, cross-process traffic
+        included), or ``None`` when the counter was unavailable. Divided by
+        successful ops to report requests-per-op.
+    :param route_requests: Per-route breakdown of ``http_requests`` —
+        ``"METHOD /route/{template}"`` mapped to how many the server handled
+        during the timed region. Empty when uncounted. Feeds the report's
+        per-journey network appendix.
     """
 
     latencies_ms: list[float] = field(default_factory=list)
     failures: dict[str, int] = field(default_factory=dict)
     wall_time: float = 0.0
+    http_requests: int | None = None
+    route_requests: dict[str, int] = field(default_factory=dict)
 
     @property
     def n_success(self) -> int:
@@ -74,6 +90,16 @@ class RunResult:
         """Maximum latency in ms, or ``0.0`` when no operation succeeded."""
         return max(self.latencies_ms) if self.latencies_ms else 0.0
 
+    def requests_per_op(self) -> float | None:
+        """Server HTTP requests per successful op, or ``None`` when uncounted.
+
+        ``None`` when the server counter was unavailable or no op succeeded, so
+        an uncounted run is distinguishable from a genuine zero.
+        """
+        if self.http_requests is None or self.n_success == 0:
+            return None
+        return self.http_requests / self.n_success
+
 
 def _run_to_dict(result: RunResult) -> dict[str, object]:
     """Flatten one :class:`RunResult` into a JSON-serializable per-run row."""
@@ -88,9 +114,40 @@ def _run_to_dict(result: RunResult) -> dict[str, object]:
         "p99_ms": result.percentile(99),
         "max_ms": result.max_ms(),
         "rps": result.throughput,
+        "http_requests": result.http_requests,
+        "http_requests_per_op": result.requests_per_op(),
+        "route_requests": dict(result.route_requests),
     }
 
 
+def _route_appendix(ok: list[RunResult]) -> list[dict[str, object]]:
+    """Per-route request breakdown across the counted summary runs.
+
+    Sums each route's requests over the runs that recorded a breakdown and
+    divides by those runs' successful ops, giving per-op counts grouped by
+    endpoint. Sorted by ``per_op`` descending (ties broken by route name) so
+    the chattiest endpoints lead. Empty when no run recorded routes.
+
+    :param ok: Summary-eligible runs (at least one success each).
+    :returns: ``[{"route", "requests", "per_op"}]`` rows, or ``[]`` when
+        uncounted.
+    """
+    counted = [r for r in ok if r.route_requests]
+    if not counted:
+        return []
+    totals: dict[str, int] = {}
+    for r in counted:
+        for route, count in r.route_requests.items():
+            totals[route] = totals.get(route, 0) + count
+    ops = sum(r.n_success for r in counted)
+    rows = [
+        {"route": route, "requests": count, "per_op": (count / ops if ops else 0.0)}
+        for route, count in totals.items()
+    ]
+    rows.sort(key=lambda row: (-float(row["per_op"]), str(row["route"])))
+    return rows
+
+
 def _summary_runs(results: list[RunResult]) -> list[RunResult]:
     """Runs eligible for the summary — those with at least one success.
 
@@ -133,6 +190,18 @@ def aggregate(results: list[RunResult]) -> dict[str, object]:
                 "avg_rps": statistics.mean(r.throughput for r in ok),
             }
         )
+        # Requests-per-op, averaged over the runs whose server counter was
+        # available. Only added when at least one such run exists, so journeys
+        # run without the counter (or before it loaded) carry no network key
+        # rather than a misleading zero.
+        per_op = [rpo for r in ok if (rpo := r.requests_per_op()) is not None]
+        if per_op:
+            summary["avg_http_requests_per_op"] = statistics.mean(per_op)
+        # Per-route appendix: which endpoints the journey's requests hit, per op.
+        # Grouped by route since the count is near-identical across runs.
+        appendix = _route_appendix(ok)
+        if appendix:
+            summary["network_routes"] = appendix
     return {"runs": runs, "summary": summary}
 
 
@@ -214,8 +283,13 @@ def print_results(journey_name: str, results: list[RunResult]) -> None:
     table.add_column("P99 ms", justify="right")
     table.add_column("Max ms", justify="right")
     table.add_column("Req/s", justify="right")
+    table.add_column("HTTP/op", justify="right")
     table.add_column("Failures", justify="right")
 
+    def _per_op_str(r: RunResult) -> str:
+        rpo = r.requests_per_op()
+        return f"{rpo:.1f}" if rpo is not None else "—"
+
     for i, r in enumerate(results):
         fail_str = f"[red]{r.n_failures}[/red]" if r.n_failures else "0"
         table.add_row(
@@ -226,6 +300,7 @@ def print_results(journey_name: str, results: list[RunResult]) -> None:
             f"{r.percentile(99):.1f}",
             f"{r.max_ms():.1f}",
             f"{r.throughput:.0f}",
+            _per_op_str(r),
             fail_str,
         )
 
@@ -234,6 +309,8 @@ def print_results(journey_name: str, results: list[RunResult]) -> None:
     # summary in aggregate()).
     ok = _summary_runs(results)
     if len(results) > 1 and ok:
+        per_op = [rpo for r in ok if (rpo := r.requests_per_op()) is not None]
+        per_op_avg = f"[bold]{statistics.mean(per_op):.1f}[/bold]" if per_op else "—"
         table.add_section()
         table.add_row(
             "[bold]avg[/bold]",
@@ -243,6 +320,7 @@ def print_results(journey_name: str, results: list[RunResult]) -> None:
             f"[bold]{statistics.mean(r.percentile(99) for r in ok):.1f}[/bold]",
             f"[bold]{statistics.mean(r.max_ms() for r in ok):.1f}[/bold]",
             f"[bold]{statistics.mean(r.throughput for r in ok):.0f}[/bold]",
+            per_op_avg,
             "",
         )
 

dev/benchmarks/omnigent/run.py

@@ -157,7 +157,10 @@ async def run_benchmark(args: argparse.Namespace) -> tuple[dict[str, object], bo
     harness = _RUNNER_HARNESS if with_runner else _HTTP_HARNESS
 
     async with BenchEnvironment(
-        with_runner=with_runner, with_host=with_host, database_uri=args.database_uri
+        with_runner=with_runner,
+        with_host=with_host,
+        database_uri=args.database_uri,
+        network_delay_ms=args.network_delay_ms,
     ) as env:
         for journey in journeys:
             console.print(f"\n[bold]Benchmarking[/bold] {journey.name} [dim]({backend})[/dim]")
@@ -206,6 +209,7 @@ async def run_benchmark(args: argparse.Namespace) -> tuple[dict[str, object], bo
         "warmup": args.warmup,
         "with_runner": with_runner,
         "backend": backend,
+        "network_delay_ms": args.network_delay_ms,
     }
     generated_at = datetime.datetime.now(datetime.timezone.utc).isoformat()
     report = build_report(
@@ -276,6 +280,16 @@ def _parse_args(argv: list[str]) -> argparse.Namespace:
         metavar="N",
         help="Warmup operations discarded before each run (default: 10).",
     )
+    parser.add_argument(
+        "--network-delay-ms",
+        type=float,
+        default=0.0,
+        metavar="MS",
+        help="Simulated client→server network latency, in ms, injected before "
+        "each request the benchmark sends (default: 0 = loopback speed). Models "
+        "a real network hop for testing network optimizations; per-op request "
+        "counts times this delay approximate the round-trip wall cost.",
+    )
     parser.add_argument(
         "--output",
         type=Path,

dev/benchmarks/omnigent/sample_output.json

@@ -1,5 +1,5 @@
 {
-  "schema_version": 4,
+  "schema_version": 6,
   "generated_at": "2026-07-08T18:30:00+00:00",
   "git_sha": "0000000000000000000000000000000000000000",
   "git_branch": "main",
@@ -16,7 +16,22 @@
     "runs": 3,
     "warmup": 10,
     "with_runner": false,
-    "backend": "sqlite"
+    "backend": "sqlite",
+    "network_delay_ms": 0.0
+  },
+  "resource_usage": {
+    "cpu_pct": {
+      "mean": 77.71818181818182,
+      "min": 0.0,
+      "max": 91.5,
+      "samples": 11
+    },
+    "rss_bytes": {
+      "mean": 178731566.54545453,
+      "min": 173686784,
+      "max": 180011008,
+      "samples": 11
+    }
   },
   "journeys": {
     "list_sessions": {
@@ -25,47 +40,70 @@
           "n_success": 100,
           "n_failures": 0,
           "failures": {},
-          "wall_time_s": 0.6587757079978473,
-          "mean_ms": 6.586994149838574,
-          "p50_ms": 6.261250004172325,
-          "p95_ms": 7.65325000975281,
-          "p99_ms": 7.9127089702524245,
-          "max_ms": 38.27937500318512,
-          "rps": 151.79673261468648
+          "wall_time_s": 0.14539083300041966,
+          "mean_ms": 1.4531342103146017,
+          "p50_ms": 1.3800830056425184,
+          "p95_ms": 1.9147919956594706,
+          "p99_ms": 2.307249989826232,
+          "max_ms": 2.3295840073842555,
+          "rps": 687.8012728609331,
+          "http_requests": 100,
+          "http_requests_per_op": 1.0,
+          "route_requests": {
+            "GET /v1/sessions": 100
+          }
         },
         {
           "n_success": 100,
           "n_failures": 0,
           "failures": {},
-          "wall_time_s": 0.6238234580378048,
-          "mean_ms": 6.237602901528589,
-          "p50_ms": 6.126708001829684,
-          "p95_ms": 7.152916979975998,
-          "p99_ms": 7.425624993629754,
-          "max_ms": 7.667875033803284,
-          "rps": 160.30176280087855
+          "wall_time_s": 0.14492745799361728,
+          "mean_ms": 1.4485845307353884,
+          "p50_ms": 1.3238340034149587,
+          "p95_ms": 1.99408401385881,
+          "p99_ms": 4.43670799722895,
+          "max_ms": 4.886500013526529,
+          "rps": 690.0003724925892,
+          "http_requests": 100,
+          "http_requests_per_op": 1.0,
+          "route_requests": {
+            "GET /v1/sessions": 100
+          }
         },
         {
           "n_success": 100,
           "n_failures": 0,
           "failures": {},
-          "wall_time_s": 0.5675292499945499,
-          "mean_ms": 5.674769564066082,
-          "p50_ms": 5.528832960408181,
-          "p95_ms": 6.237249996047467,
-          "p99_ms": 7.393250009045005,
-          "max_ms": 11.83562504593283,
-          "rps": 176.20237194992208
+          "wall_time_s": 0.13697420799871907,
+          "mean_ms": 1.368980410916265,
+          "p50_ms": 1.3387500075623393,
+          "p95_ms": 1.7172090010717511,
+          "p99_ms": 1.8671669822651893,
+          "max_ms": 1.9677499949466437,
+          "rps": 730.0644512646875,
+          "http_requests": 100,
+          "http_requests_per_op": 1.0,
+          "route_requests": {
+            "GET /v1/sessions": 100
+          }
         }
       ],
       "summary": {
         "runs_total": 3,
         "runs_ok": 3,
-        "avg_mean_ms": 6.166455538477749,
-        "avg_p50_ms": 5.972263655470063,
-        "avg_p95_ms": 7.014472328592092,
-        "avg_p99_ms": 7.577194657642394,
-        "avg_rps": 162.7669557884957
+        "avg_mean_ms": 1.4235663839887518,
+        "avg_p50_ms": 1.3475556722066055,
+        "avg_p95_ms": 1.8753616701966773,
+        "avg_p99_ms": 2.8703749897734574,
+        "avg_rps": 702.6220322060699,
+        "avg_http_requests_per_op": 1.0,
+        "network_routes": [
+          {
+            "route": "GET /v1/sessions",
+            "requests": 300,
+            "per_op": 1.0
+          }
+        ]
       },
       "kind": "latency",
       "backend": "sqlite",
@@ -77,47 +115,78 @@
           "n_success": 100,
           "n_failures": 0,
           "failures": {},
-          "wall_time_s": 2.4451411250047386,
-          "mean_ms": 24.450668342760764,
-          "p50_ms": 24.028874991927296,
-          "p95_ms": 27.25041698431596,
-          "p99_ms": 29.374166973866522,
-          "max_ms": 29.56758299842477,
-          "rps": 40.89743490769115
+          "wall_time_s": 1.6592429590236861,
+          "mean_ms": 16.59096085233614,
+          "p50_ms": 16.146292007761076,
+          "p95_ms": 19.581041007768363,
+          "p99_ms": 21.494417014764622,
+          "max_ms": 24.84037500107661,
+          "rps": 60.26844920821055,
+          "http_requests": 200,
+          "http_requests_per_op": 2.0,
+          "route_requests": {
+            "POST /v1/sessions": 100,
+            "DELETE /v1/sessions/{session_id}": 100
+          }
         },
         {
           "n_success": 100,
           "n_failures": 0,
           "failures": {},
-          "wall_time_s": 2.498600291030016,
-          "mean_ms": 24.985182073432952,
-          "p50_ms": 24.459875014144927,
-          "p95_ms": 28.391665953677148,
-          "p99_ms": 29.0600000298582,
-          "max_ms": 34.39550002804026,
-          "rps": 40.02240788932922
+          "wall_time_s": 1.675092332996428,
+          "mean_ms": 16.749450869683642,
+          "p50_ms": 16.362750000553206,
+          "p95_ms": 20.069208985660225,
+          "p99_ms": 22.160249995067716,
+          "max_ms": 22.810291993664578,
+          "rps": 59.69820172307674,
+          "http_requests": 200,
+          "http_requests_per_op": 2.0,
+          "route_requests": {
+            "POST /v1/sessions": 100,
+            "DELETE /v1/sessions/{session_id}": 100
+          }
         },
         {
           "n_success": 100,
           "n_failures": 0,
           "failures": {},
-          "wall_time_s": 2.455423459003214,
-          "mean_ms": 24.553418274153955,
-          "p50_ms": 24.073333013802767,
-          "p95_ms": 27.43383398046717,
-          "p99_ms": 29.375000041909516,
-          "max_ms": 29.430416005197912,
-          "rps": 40.72617276394162
+          "wall_time_s": 1.6948266669933219,
+          "mean_ms": 16.94665289745899,
+          "p50_ms": 16.35474999784492,
+          "p95_ms": 20.578667026711628,
+          "p99_ms": 21.13654199638404,
+          "max_ms": 21.60887501668185,
+          "rps": 59.00308388314617,
+          "http_requests": 200,
+          "http_requests_per_op": 2.0,
+          "route_requests": {
+            "POST /v1/sessions": 100,
+            "DELETE /v1/sessions/{session_id}": 100
+          }
         }
       ],
       "summary": {
         "runs_total": 3,
         "runs_ok": 3,
-        "avg_mean_ms": 24.663089563449223,
-        "avg_p50_ms": 24.187361006624997,
-        "avg_p95_ms": 27.691972306153428,
-        "avg_p99_ms": 29.269722348544747,
-        "avg_rps": 40.548671853654
+        "avg_mean_ms": 16.76235487315959,
+        "avg_p50_ms": 16.287930668719735,
+        "avg_p95_ms": 20.076305673380073,
+        "avg_p99_ms": 21.597069668738794,
+        "avg_rps": 59.65657827147782,
+        "avg_http_requests_per_op": 2.0,
+        "network_routes": [
+          {
+            "route": "DELETE /v1/sessions/{session_id}",
+            "requests": 300,
+            "per_op": 1.0
+          },
+          {
+            "route": "POST /v1/sessions",
+            "requests": 300,
+            "per_op": 1.0
+          }
+        ]
       },
       "kind": "latency",
       "backend": "sqlite",
@@ -129,47 +198,70 @@
           "n_success": 100,
           "n_failures": 0,
           "failures": {},
-          "wall_time_s": 0.5546917500323616,
-          "mean_ms": 5.5460037814918905,
-          "p50_ms": 5.360124981962144,
-          "p95_ms": 6.925499998033047,
-          "p99_ms": 7.144333969336003,
-          "max_ms": 7.331291970331222,
-          "rps": 180.28030882767922
+          "wall_time_s": 0.618162291997578,
+          "mean_ms": 6.180601690721232,
+          "p50_ms": 5.8322090189903975,
+          "p95_ms": 7.893667003372684,
+          "p99_ms": 8.871707977959886,
+          "max_ms": 9.131124999839813,
+          "rps": 161.76981562050992,
+          "http_requests": 100,
+          "http_requests_per_op": 1.0,
+          "route_requests": {
+            "GET /v1/sessions/{session_id}": 100
+          }
         },
         {
           "n_success": 100,
           "n_failures": 0,
           "failures": {},
-          "wall_time_s": 0.49645508296089247,
-          "mean_ms": 4.963922067545354,
-          "p50_ms": 4.782959003932774,
-          "p95_ms": 5.978292028885335,
-          "p99_ms": 6.7617910099215806,
-          "max_ms": 6.881375040393323,
-          "rps": 201.42809174919327
+          "wall_time_s": 0.6758431250054855,
+          "mean_ms": 6.7572175012901425,
+          "p50_ms": 6.478499999502674,
+          "p95_ms": 8.380832994589582,
+          "p99_ms": 8.837792003760114,
+          "max_ms": 8.995375013910234,
+          "rps": 147.96333098629708,
+          "http_requests": 100,
+          "http_requests_per_op": 1.0,
+          "route_requests": {
+            "GET /v1/sessions/{session_id}": 100
+          }
         },
         {
           "n_success": 100,
           "n_failures": 0,
           "failures": {},
-          "wall_time_s": 0.460644083970692,
-          "mean_ms": 4.605880451854318,
-          "p50_ms": 4.526541975792497,
-          "p95_ms": 5.18629199359566,
-          "p99_ms": 5.445250018965453,
-          "max_ms": 5.790999974124134,
-          "rps": 217.08734244020465
+          "wall_time_s": 0.6910586670273915,
+          "mean_ms": 6.909306258603465,
+          "p50_ms": 6.664832995738834,
+          "p95_ms": 8.377791004022583,
+          "p99_ms": 9.534541983157396,
+          "max_ms": 10.113791009644046,
+          "rps": 144.70551455515758,
+          "http_requests": 100,
+          "http_requests_per_op": 1.0,
+          "route_requests": {
+            "GET /v1/sessions/{session_id}": 100
+          }
         }
       ],
       "summary": {
         "runs_total": 3,
         "runs_ok": 3,
-        "avg_mean_ms": 5.0386021002971875,
-        "avg_p50_ms": 4.889875320562472,
-        "avg_p95_ms": 6.030028006838013,
-        "avg_p99_ms": 6.450458332741012,
-        "avg_rps": 199.59858100569238
+        "avg_mean_ms": 6.61570848353828,
+        "avg_p50_ms": 6.325180671410635,
+        "avg_p95_ms": 8.21743033399495,
+        "avg_p99_ms": 9.081347321625799,
+        "avg_rps": 151.47955372065485,
+        "avg_http_requests_per_op": 1.0,
+        "network_routes": [
+          {
+            "route": "GET /v1/sessions/{session_id}",
+            "requests": 300,
+            "per_op": 1.0
+          }
+        ]
       },
       "kind": "latency",
       "backend": "sqlite",
@@ -181,47 +273,70 @@
           "n_success": 100,
           "n_failures": 0,
           "failures": {},
-          "wall_time_s": 0.20811437495285645,
-          "mean_ms": 2.080691678565927,
-          "p50_ms": 2.037000027485192,
-          "p95_ms": 2.5742079596966505,
-          "p99_ms": 2.768124977592379,
-          "max_ms": 2.784749958664179,
-          "rps": 480.50501087516284
+          "wall_time_s": 0.25584779199562036,
+          "mean_ms": 2.5575782902888022,
+          "p50_ms": 2.469791012117639,
+          "p95_ms": 3.0598339799325913,
+          "p99_ms": 3.6600840103346854,
+          "max_ms": 5.426874995464459,
+          "rps": 390.85738915312515,
+          "http_requests": 100,
+          "http_requests_per_op": 1.0,
+          "route_requests": {
+            "GET /v1/sessions/{session_id}/items": 100
+          }
         },
         {
           "n_success": 100,
           "n_failures": 0,
           "failures": {},
-          "wall_time_s": 0.19513549999101087,
-          "mean_ms": 1.9509158097207546,
-          "p50_ms": 1.9018329912796617,
-          "p95_ms": 2.284207963384688,
-          "p99_ms": 2.4481670116074383,
-          "max_ms": 2.5021659675985575,
-          "rps": 512.4644157757384
+          "wall_time_s": 0.2574428749794606,
+          "mean_ms": 2.5735091799288057,
+          "p50_ms": 2.51016701804474,
+          "p95_ms": 3.0513330129906535,
+          "p99_ms": 3.5724999906960875,
+          "max_ms": 3.6185409990139306,
+          "rps": 388.43568697707497,
+          "http_requests": 100,
+          "http_requests_per_op": 1.0,
+          "route_requests": {
+            "GET /v1/sessions/{session_id}/items": 100
+          }
         },
         {
           "n_success": 100,
           "n_failures": 0,
           "failures": {},
-          "wall_time_s": 0.19278304203180596,
-          "mean_ms": 1.9274150469573215,
-          "p50_ms": 1.8819589749909937,
-          "p95_ms": 2.2150420118123293,
-          "p99_ms": 2.2878749878145754,
-          "max_ms": 2.316958038136363,
-          "rps": 518.7178236532945
+          "wall_time_s": 0.27459433299372904,
+          "mean_ms": 2.7449333196273074,
+          "p50_ms": 2.635875018313527,
+          "p95_ms": 3.485749999526888,
+          "p99_ms": 3.7029579980298877,
+          "max_ms": 3.9087080222088844,
+          "rps": 364.173575287454,
+          "http_requests": 100,
+          "http_requests_per_op": 1.0,
+          "route_requests": {
+            "GET /v1/sessions/{session_id}/items": 100
+          }
         }
       ],
       "summary": {
         "runs_total": 3,
         "runs_ok": 3,
-        "avg_mean_ms": 1.9863408450813342,
-        "avg_p50_ms": 1.9402639979186158,
-        "avg_p95_ms": 2.3578193116312227,
-        "avg_p99_ms": 2.5013889923381307,
-        "avg_rps": 503.8957501013986
+        "avg_mean_ms": 2.6253402632816383,
+        "avg_p50_ms": 2.5386110161586353,
+        "avg_p95_ms": 3.198972330816711,
+        "avg_p99_ms": 3.6451806663535535,
+        "avg_rps": 381.1555504725514,
+        "avg_http_requests_per_op": 1.0,
+        "network_routes": [
+          {
+            "route": "GET /v1/sessions/{session_id}/items",
+            "requests": 300,
+            "per_op": 1.0
+          }
+        ]
       },
       "kind": "latency",
       "backend": "sqlite",
@@ -233,47 +348,70 @@
           "n_success": 100,
           "n_failures": 0,
           "failures": {},
-          "wall_time_s": 8.150427000015043,
-          "mean_ms": 81.50338126753923,
-          "p50_ms": 80.11816703947261,
-          "p95_ms": 90.9090840141289,
-          "p99_ms": 94.67683301772922,
-          "max_ms": 96.44366696011275,
-          "rps": 12.26929582950874
+          "wall_time_s": 0.2137124160071835,
+          "mean_ms": 2.1360725004342385,
+          "p50_ms": 2.031207986874506,
+          "p95_ms": 2.719917014474049,
+          "p99_ms": 3.0205000075511634,
+          "max_ms": 3.032750013517216,
+          "rps": 467.9185321485426,
+          "http_requests": 100,
+          "http_requests_per_op": 1.0,
+          "route_requests": {
+            "GET /v1/sessions": 100
+          }
         },
         {
           "n_success": 100,
           "n_failures": 0,
           "failures": {},
-          "wall_time_s": 8.152122708968818,
-          "mean_ms": 81.5203430026304,
-          "p50_ms": 79.57212498877198,
-          "p95_ms": 95.20591603359208,
-          "p99_ms": 98.80137501750141,
-          "max_ms": 99.93629204109311,
-          "rps": 12.266743714490682
+          "wall_time_s": 0.17307583297952078,
+          "mean_ms": 1.7299287702189758,
+          "p50_ms": 1.677958993241191,
+          "p95_ms": 2.166459016734734,
+          "p99_ms": 2.794750005705282,
+          "max_ms": 3.016250004293397,
+          "rps": 577.7814168419026,
+          "http_requests": 100,
+          "http_requests_per_op": 1.0,
+          "route_requests": {
+            "GET /v1/sessions": 100
+          }
         },
         {
           "n_success": 100,
           "n_failures": 0,
           "failures": {},
-          "wall_time_s": 8.053999124967959,
-          "mean_ms": 80.53909589187242,
-          "p50_ms": 79.52124997973442,
-          "p95_ms": 91.39445802429691,
-          "p99_ms": 93.2748339837417,
-          "max_ms": 94.79766699951142,
-          "rps": 12.416192061654566
+          "wall_time_s": 0.15361558299628086,
+          "mean_ms": 1.5353992290329188,
+          "p50_ms": 1.4499580138362944,
+          "p95_ms": 1.987833995372057,
+          "p99_ms": 2.2785839973948896,
+          "max_ms": 2.3655000259168446,
+          "rps": 650.9756240186978,
+          "http_requests": 100,
+          "http_requests_per_op": 1.0,
+          "route_requests": {
+            "GET /v1/sessions": 100
+          }
         }
       ],
       "summary": {
         "runs_total": 3,
         "runs_ok": 3,
-        "avg_mean_ms": 81.18760672068068,
-        "avg_p50_ms": 79.73718066932634,
-        "avg_p95_ms": 92.50315269067262,
-        "avg_p99_ms": 95.58434733965744,
-        "avg_rps": 12.317410535217997
+        "avg_mean_ms": 1.800466833228711,
+        "avg_p50_ms": 1.7197083313173305,
+        "avg_p95_ms": 2.2914033421936133,
+        "avg_p99_ms": 2.6979446702171117,
+        "avg_rps": 565.558524336381,
+        "avg_http_requests_per_op": 1.0,
+        "network_routes": [
+          {
+            "route": "GET /v1/sessions",
+            "requests": 300,
+            "per_op": 1.0
+          }
+        ]
       },
       "kind": "latency",
       "backend": "sqlite",

dev/benchmarks/omnigent/schema.py

@@ -16,7 +16,16 @@ import subprocess
 # v4: per-journey ``summary`` gained ``runs_total`` / ``runs_ok`` (and omits the
 # metric keys when every run failed); a journey that errored out of measurement
 # entirely carries ``skipped: true`` + ``error`` with empty ``runs``/``summary``.
-SCHEMA_VERSION = 4
+# v5: each run row gained ``http_requests`` / ``http_requests_per_op`` (server
+# HTTP requests handled during the timed region, counted via the CI-only debug
+# endpoint; ``null`` when uncounted); ``summary`` gains
+# ``avg_http_requests_per_op`` when any run was counted; ``config`` gains
+# ``network_delay_ms``.
+# v6: each run row gained ``route_requests`` (per-route breakdown of
+# ``http_requests``, ``"METHOD /route" -> count``); ``summary`` gains a
+# ``network_routes`` appendix (``[{route, requests, per_op}]`` sorted by
+# ``per_op`` desc) when any run recorded a breakdown.
+SCHEMA_VERSION = 6
 
 
 def _git(*args: str) -> str:

dev/benchmarks/omnigent/seed.py

@@ -20,10 +20,16 @@ loopback server resolves every request to user ``"local"`` and
 2. ``permission_store.grant("local", sid, LEVEL_OWNER)`` — makes it listable.
 3. one batched ``append(sid, items)`` — user-role message items.
 
+Also seeds first-class projects (``projects`` rows owned by ``"local"``) and
+files a fraction of sessions into them, so the project read journeys
+(``list_projects`` / ``list_project_sessions``) measure a realistic sidebar —
+a folder count and per-folder depth — instead of an empty project set.
+
 Run standalone::
 
     uv run --no-sync dev/benchmarks/omnigent/seed.py \
-        --database-uri sqlite:///tmp/bench.db --sessions 5000 --items-per-session 50
+        --database-uri sqlite:///tmp/bench.db --sessions 5000 --items-per-session 50 \
+        --projects 20 --filed-fraction 0.5
 """
 
 from __future__ import annotations
@@ -49,6 +55,7 @@ from omnigent.db.db_models import (
     SqlConversationItem,
     SqlConversationLabel,
     SqlConversationMetadata,
+    SqlProject,
     SqlSessionPermission,
     SqlUser,
     current_workspace_id,
@@ -73,6 +80,7 @@ from omnigent.entities import MessageData, NewConversationItem
 from omnigent.server.auth import LEVEL_OWNER, RESERVED_USER_LOCAL
 from omnigent.stores.conversation_store.sqlalchemy_store import SqlAlchemyConversationStore
 from omnigent.stores.permission_store.sqlalchemy_store import SqlAlchemyPermissionStore
+from omnigent.stores.project_store.sqlalchemy_store import SqlAlchemyProjectStore
 
 # Label key stamped on the first seeded session recording the corpus config, so
 # a later run can detect an existing (and matching) seed and skip re-seeding.
@@ -85,6 +93,21 @@ _DEFAULT_SESSIONS = 5000
 _DEFAULT_ITEMS = 50
 _DEFAULT_RNG_SEED = 1234
 
+# First-class projects seeded into the corpus, and the fraction of sessions
+# filed into one (round-robin). Without these the project read journeys
+# (list_projects / list_project_sessions) would measure an empty project set —
+# a 0-folder union and a 0-member folder — which tests nothing. The defaults
+# give a realistic sidebar: 20 folders, each holding ~1/20th of the filed half
+# of the corpus (e.g. 5000 sessions × 0.5 / 20 = 125 sessions/project).
+_DEFAULT_PROJECTS = 20
+_DEFAULT_FILED_FRACTION = 0.5
+
+# Owner of every seeded project. The loopback bench server is single-user, so
+# it resolves each request to the reserved ``"local"`` user; the project list
+# and the ``?project=`` filter are owner-scoped, so a project owned by anyone
+# else would be invisible to the benchmark's reads.
+_PROJECT_OWNER = RESERVED_USER_LOCAL
+
 # A pool of realistic-ish message fragments; the RNG assembles item text from
 # these so search_text has lexical variety without external data.
 _FRAGMENTS = (
@@ -114,14 +137,56 @@ _FTS_INSERT_SQL = text(
 _CORE_ITEM_CHUNK = 100_000
 
 
-def _meta_value(sessions: int, items_per_session: int, rng_seed: int, head: str) -> str:
+def _meta_value(
+    sessions: int,
+    items_per_session: int,
+    rng_seed: int,
+    projects: int,
+    filed_fraction: float,
+    head: str,
+) -> str:
     """Serialize the corpus config into the seed-marker label value.
 
     Includes the Alembic *head* read at seed time, so a corpus seeded under an
     older schema auto-mismatches the current head and is reseeded — no
-    hand-maintained revision constant.
+    hand-maintained revision constant. The project knobs are part of the key so
+    a pre-existing corpus seeded without projects is reseeded once they're added.
     """
-    return f"sessions={sessions};items={items_per_session};rng={rng_seed};rev={head}"
+    return (
+        f"sessions={sessions};items={items_per_session};rng={rng_seed};"
+        f"projects={projects};filed={filed_fraction:g};rev={head}"
+    )
+
+
+def _project_id(index: int) -> str:
+    """Deterministic 32-char-hex project id for the ``index``-th seeded project.
+
+    Derived from the index (not random) so both write paths produce identical
+    project rows and a re-seed at the same config is byte-stable.
+    """
+    return hashlib.sha256(f"bench-project-{index}".encode()).hexdigest()[:32]
+
+
+def _project_plan(
+    sessions: int,
+    projects: int,
+    filed_fraction: float,
+) -> tuple[list[tuple[str, str]], dict[int, str]]:
+    """Plan the corpus's first-class projects and their session membership.
+
+    :returns: ``(project_specs, project_of_session)`` where ``project_specs`` is
+        ``[(id, name), …]`` for the ``projects`` rows to create, and
+        ``project_of_session`` maps a session index to the project id it is
+        filed under. The first ``round(sessions × filed_fraction)`` sessions are
+        filed, assigned round-robin across the projects so each folder holds a
+        realistic, even share; the rest stay unfiled.
+    """
+    if projects <= 0 or filed_fraction <= 0 or sessions <= 0:
+        return [], {}
+    specs = [(_project_id(p), f"bench project {p}") for p in range(projects)]
+    filed_count = min(sessions, round(sessions * filed_fraction))
+    project_of_session = {s: specs[s % projects][0] for s in range(filed_count)}
+    return specs, project_of_session
 
 
 def _existing_seed_meta(conv: SqlAlchemyConversationStore) -> str | None:
@@ -168,6 +233,8 @@ def seed(
     sessions: int = _DEFAULT_SESSIONS,
     items_per_session: int = _DEFAULT_ITEMS,
     rng_seed: int = _DEFAULT_RNG_SEED,
+    projects: int = _DEFAULT_PROJECTS,
+    filed_fraction: float = _DEFAULT_FILED_FRACTION,
     reseed: bool = False,
     _fast: bool | None = None,
 ) -> int:
@@ -183,6 +250,11 @@ def seed(
     :param sessions: Number of listable sessions to create.
     :param items_per_session: Conversation items appended to each session.
     :param rng_seed: Seed for the deterministic text RNG.
+    :param projects: Number of first-class ``projects`` rows to create (owned by
+        ``"local"``). ``0`` seeds no projects.
+    :param filed_fraction: Fraction of sessions filed into a project (round-robin
+        across the ``projects`` folders); the rest stay unfiled. Ignored when
+        ``projects`` is 0.
     :param reseed: Seed even when a matching corpus is already present.
     :param _fast: Override the write strategy. ``None`` (default) uses the
         bulk-insert Core fast path for SQLite and the store-API loop for every
@@ -203,7 +275,7 @@ def seed(
     # Read the current schema head at runtime (no DB contacted) and fold it into
     # the reuse marker, so a corpus from an older schema is auto-reseeded.
     head = _get_head_db_revision("sqlite:///:memory:")
-    want = _meta_value(sessions, items_per_session, rng_seed, head)
+    want = _meta_value(sessions, items_per_session, rng_seed, projects, filed_fraction, head)
     if not reseed:
         existing = _existing_seed_meta(conv)
         if existing == want:
@@ -213,6 +285,8 @@ def seed(
             print(f"seed: existing corpus differs ({existing!r} != {want!r}); pass --reseed")
             return 0
 
+    project_specs, project_of_session = _project_plan(sessions, projects, filed_fraction)
+
     if use_fast:
         n = _seed_via_core(
             db_uri,
@@ -220,6 +294,8 @@ def seed(
             items_per_session=items_per_session,
             rng_seed=rng_seed,
             want=want,
+            project_specs=project_specs,
+            project_of_session=project_of_session,
         )
     else:
         perms = SqlAlchemyPermissionStore(db_uri)
@@ -230,9 +306,14 @@ def seed(
             items_per_session=items_per_session,
             rng_seed=rng_seed,
             want=want,
+            project_specs=project_specs,
+            project_of_session=project_of_session,
         )
 
-    print(f"seed: created {n} sessions × {items_per_session} items ({want})")
+    print(
+        f"seed: created {n} sessions × {items_per_session} items, "
+        f"{len(project_specs)} projects, {len(project_of_session)} filed ({want})"
+    )
     return n
 
 
@@ -244,16 +325,24 @@ def _seed_via_store(
     items_per_session: int,
     rng_seed: int,
     want: str,
+    project_specs: list[tuple[str, str]],
+    project_of_session: dict[int, str],
 ) -> int:
     """Seed through the production store ORM API (one row/commit at a time).
 
     This is the original path and the only one used on non-SQLite dialects
     (e.g. the nightly Postgres benchmark). It is kept verbatim so behavior
-    there stays identical.
+    there stays identical, save for the added first-class projects.
     """
     perms.ensure_user(RESERVED_USER_LOCAL)
     rng = random.Random(rng_seed)
 
+    # First-class projects, owned by "local" so the owner-scoped project reads
+    # see them. Created before the sessions so membership can be set inline.
+    projects_store = SqlAlchemyProjectStore(conv.storage_location)
+    for project_id, name in project_specs:
+        projects_store.create(project_id, name, owner_user_id=_PROJECT_OWNER)
+
     last_sid = ""
     for s in range(sessions):
         created = conv.create_session_with_agent(
@@ -268,6 +357,9 @@ def _seed_via_store(
         perms.grant(RESERVED_USER_LOCAL, sid, LEVEL_OWNER)
         if items_per_session:
             conv.append(sid, _make_items(rng, items_per_session))
+        project_id = project_of_session.get(s)
+        if project_id is not None:
+            conv.set_conversation_project(sid, project_id)
         _progress(s, sessions)
 
     # Stamp the corpus config on the LAST (newest) session — that's the one
@@ -286,6 +378,8 @@ def _seed_via_core(
     items_per_session: int,
     rng_seed: int,
     want: str,
+    project_specs: list[tuple[str, str]],
+    project_of_session: dict[int, str],
 ) -> int:
     """Seed the entire corpus in one transaction via SQLAlchemy Core.
 
@@ -387,6 +481,7 @@ def _seed_via_core(
                     "runner_last_seen": None,
                     "live_status": None,
                     "pending_elicitation_count": None,
+                    "project_id": project_of_session.get(s),
                 }
             )
             perm_rows.append(
@@ -461,6 +556,27 @@ def _seed_via_core(
         conn.execute(SqlConversationMetadata.__table__.insert(), meta_rows)
         conn.execute(SqlSessionPermission.__table__.insert(), perm_rows)
 
+        # First-class projects, owned by "local" (the reserved single-user id
+        # the owner-scoped project reads resolve to). Membership already lives
+        # on each metadata row's ``project_id`` above. ``updated_at`` is NULL,
+        # matching a freshly created project (the store sets it only on rename).
+        if project_specs:
+            project_now = now_epoch()
+            conn.execute(
+                SqlProject.__table__.insert(),
+                [
+                    {
+                        "workspace_id": ws,
+                        "id": project_id,
+                        "name": name,
+                        "owner_user_id": _PROJECT_OWNER,
+                        "created_at": project_now,
+                        "updated_at": None,
+                    }
+                    for project_id, name in project_specs
+                ],
+            )
+
         # Stamp the corpus config on the LAST (newest) session, matching the
         # store path's ``set_labels`` upsert (clamped to LABEL_VALUE_MAX_LEN).
         if last_sid:
@@ -498,6 +614,22 @@ def _parse_args(argv: list[str]) -> argparse.Namespace:
     parser.add_argument("--sessions", type=int, default=_DEFAULT_SESSIONS, metavar="N")
     parser.add_argument("--items-per-session", type=int, default=_DEFAULT_ITEMS, metavar="N")
     parser.add_argument("--rng-seed", type=int, default=_DEFAULT_RNG_SEED, metavar="N")
+    parser.add_argument(
+        "--projects",
+        type=int,
+        default=_DEFAULT_PROJECTS,
+        metavar="N",
+        help="First-class projects to seed (0 = none). Filed sessions are "
+        "spread round-robin across them.",
+    )
+    parser.add_argument(
+        "--filed-fraction",
+        type=float,
+        default=_DEFAULT_FILED_FRACTION,
+        metavar="F",
+        help="Fraction of sessions filed into a project (0..1); the rest stay "
+        "unfiled. Ignored when --projects is 0.",
+    )
     parser.add_argument(
         "--reseed",
         action="store_true",
@@ -524,6 +656,8 @@ def main(argv: list[str] | None = None) -> int:
         sessions=args.sessions,
         items_per_session=args.items_per_session,
         rng_seed=args.rng_seed,
+        projects=args.projects,
+        filed_fraction=args.filed_fraction,
         reseed=args.reseed,
     )
     return 0

dev/lint/hardcoded_model_allowlist.txt

@@ -0,0 +1,62 @@
+# Curated baseline for dev/lint/lint_no_hardcoded_models.py.
+# Format: <path> <model-id> <allowed-count>
+# Keep counts minimal; new model pins should move behind provider/catalog resolution.
+.github/actions/integration-run/action.yml databricks-gpt-5-4-mini 1
+.github/actions/integration-run/action.yml databricks-gpt-5-5 1
+.github/actions/run-omnigent-agent/action.yml databricks-claude-opus-4-8 1
+.github/scripts/ci/backcompat-pairwise-matrix.sh databricks-gpt-5-4-mini 1
+.github/scripts/ci/integration-matrix.sh databricks-gpt-5-4-mini 1
+.github/workflows/auto-assign-reviewer.yml databricks-claude-sonnet-4-6 1
+.github/workflows/doc-sync.yml databricks-claude-opus-4-8 1
+.github/workflows/e2e-ui-required.yml databricks-gpt-5-4 1
+.github/workflows/feature-blog.yml databricks-gemini-3-pro-image 1
+.github/workflows/flake-stress-e2e.yml databricks-gpt-5-4-mini 1
+.github/workflows/flake-stress-e2e.yml databricks-gpt-5-5 1
+.github/workflows/issue-triage.yml databricks-claude-sonnet-4-6 1
+.github/workflows/polly-review.yml databricks-claude-opus-4-8 1
+.github/workflows/polly-review.yml databricks-gpt-5-5 1
+.github/workflows/security-triage.yml databricks-claude-sonnet-4-6 1
+.github/workflows/vscode-release-pr.yml databricks-claude-sonnet-4-6 1
+omnigent/cli_config.py claude-opus-4-5-20251101-v1:0 1
+omnigent/cursor_native.py claude-opus-4-5 1
+omnigent/cursor_native.py claude-opus-4-6 1
+omnigent/cursor_native.py claude-opus-4-7 1
+omnigent/cursor_native.py claude-opus-4-8 1
+omnigent/cursor_native.py claude-sonnet-4-5 1
+omnigent/cursor_native.py claude-sonnet-4-6 1
+omnigent/cursor_native.py gpt-5.2 1
+omnigent/cursor_native.py gpt-5.2-codex 1
+omnigent/cursor_native.py gpt-5.3-codex 1
+omnigent/cursor_native.py gpt-5.4 1
+omnigent/cursor_native.py gpt-5.5 1
+omnigent/inner/pi_executor.py databricks-claude-opus-4-8 1
+omnigent/inner/pi_executor.py databricks-claude-sonnet-4-5 1
+omnigent/inner/pi_executor.py databricks-claude-sonnet-4-6 1
+omnigent/inner/pi_executor.py databricks-gpt-5-4 1
+omnigent/inner/pi_executor.py databricks-gpt-5-4-mini 1
+omnigent/inner/pi_executor.py databricks-gpt-5-5 1
+omnigent/inner/pi_executor.py databricks-gpt-5-5-pro 1
+omnigent/llms/context_window.py o1 1
+omnigent/llms/context_window.py o3 1
+omnigent/llms/context_window.py o4 1
+omnigent/model_catalog.py claude-fable-5 1
+omnigent/model_catalog.py claude-haiku-4-5 1
+omnigent/model_catalog.py claude-opus-4-8 1
+omnigent/model_catalog.py claude-opus-5 1
+omnigent/model_catalog.py claude-sonnet-4-6 1
+omnigent/model_catalog.py claude-sonnet-5 1
+omnigent/model_catalog.py gpt-5.4 1
+omnigent/model_catalog.py gpt-5.4-mini 1
+omnigent/model_catalog.py gpt-5.5 1
+omnigent/onboarding/wizard.py databricks-gpt-5-4 1
+omnigent/onboarding/wizard.py gpt-4o 1
+omnigent/policies/builtins/routing.py databricks-claude-opus-4-6 1
+omnigent/policies/builtins/routing.py o3 1
+omnigent/server/smart_routing.py databricks-claude-haiku-4-5 1
+omnigent/server/smart_routing.py databricks-gpt-5-5 1
+omnigent/server/smart_routing.py databricks-gpt-5-5-pro 1
+omnigent/server/smart_routing.py databricks-gpt-5-6-luna 1
+omnigent/server/smart_routing.py databricks-gpt-5-6-sol 1
+omnigent/server/smart_routing.py databricks-gpt-5-6-terra 1
+omnigent/tools/builtins/spawn.py databricks-claude-opus-4-8 1
+omnigent/tools/builtins/spawn.py system.ai.glm-5-2 1

dev/lint/lint_no_hardcoded_models.py

@@ -0,0 +1,272 @@
+"""Flag new hardcoded LLM model ids outside tests.
+
+The codebase still has a curated baseline of model pins that predate this
+check. This hook requires every path/model count to exactly match
+``dev/lint/hardcoded_model_allowlist.txt`` so new pins fail and removed pins
+must ratchet the baseline down.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+import subprocess
+import sys
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+
+MODEL_ID_RE = re.compile(
+    r"""
+    \b(?:
+        databricks-(?:claude|gpt|gemini|llama|mistral|mixtral|deepseek|qwen|kimi|dbrx|grok|meta)-[a-z0-9][a-z0-9._:/-]*
+      | system\.ai\.[a-z0-9][a-z0-9._:/-]*
+      | (?:openai/)?gpt-(?:\d|oss)[a-z0-9._:/-]*
+      | o[134](?:-[a-z0-9][a-z0-9._:/-]*)?
+      | claude-(?:opus|sonnet|haiku|fable|\d)[a-z0-9._:/-]*
+      | gemini-\d[a-z0-9][a-z0-9._:/-]*
+      | kimi-k\d[a-z0-9._:/-]*
+      | qwen\d[a-z0-9][a-z0-9._:/-]*
+      | llama-\d[a-z0-9][a-z0-9._:/-]*
+      | mistral-[a-z0-9][a-z0-9._:/-]*
+      | deepseek-[a-z0-9][a-z0-9._:/-]*
+    )\b
+    """,
+    re.VERBOSE,
+)
+
+TEXT_EXTENSIONS = {".json", ".toml", ".yaml", ".yml", ".sh"}
+SOURCE_EXTENSIONS = {".py", *TEXT_EXTENSIONS}
+SCAN_ROOTS = (
+    Path("omnigent"),
+    Path("scripts"),
+    Path("examples"),
+    Path(".github"),
+    Path("dev/lint"),
+)
+SKIP_PARTS = {
+    ".git",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "node_modules",
+    "tests",
+}
+ALLOWLIST_PATH = Path("dev/lint/hardcoded_model_allowlist.txt")
+
+
+@dataclass(frozen=True)
+class Hit:
+    """One hardcoded model occurrence."""
+
+    path: Path
+    line: int
+    model: str
+
+
+def _repo_relative(path: Path) -> str:
+    """Return a stable repo-relative path when possible."""
+    try:
+        return path.resolve().relative_to(Path.cwd().resolve()).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+def _target_name(node: ast.expr) -> str:
+    """Return the user-visible name for an assignment target."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    if isinstance(node, ast.Subscript):
+        return _target_name(node.value)
+    if isinstance(node, ast.Starred):
+        return _target_name(node.value)
+    if isinstance(node, (ast.Tuple, ast.List)):
+        return " ".join(filter(None, (_target_name(item) for item in node.elts)))
+    return ""
+
+
+def _key_name(node: ast.expr | None) -> str:
+    """Return a literal dict key name when statically knowable."""
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    if isinstance(node, ast.Name):
+        return node.id
+    return ""
+
+
+def _is_model_context(node: ast.AST, parents: dict[ast.AST, ast.AST]) -> bool:
+    """Return True if a string literal lives in model-selection data."""
+    current = node
+    while current in parents:
+        parent = parents[current]
+        if isinstance(parent, ast.keyword) and parent.arg and "model" in parent.arg.lower():
+            return True
+        if isinstance(parent, ast.Assign):
+            if any("model" in _target_name(target).lower() for target in parent.targets):
+                return True
+        elif isinstance(parent, ast.AnnAssign):
+            if "model" in _target_name(parent.target).lower():
+                return True
+        elif isinstance(parent, ast.Dict):
+            for key, value in zip(parent.keys, parent.values, strict=True):
+                if value is current and "model" in _key_name(key).lower():
+                    return True
+        current = parent
+    return False
+
+
+def _extract_models(text: str) -> list[str]:
+    """Return hardcoded model ids in ``text``."""
+    return [match.group(0) for match in MODEL_ID_RE.finditer(text)]
+
+
+def _scan_python(path: Path) -> list[Hit]:
+    """Scan Python syntax-aware string literals in model contexts."""
+    try:
+        tree = ast.parse(path.read_text())
+    except (SyntaxError, UnicodeDecodeError):
+        return []
+
+    parents = {child: node for node in ast.walk(tree) for child in ast.iter_child_nodes(node)}
+    hits: list[Hit] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Constant) or not isinstance(node.value, str):
+            continue
+        if not _is_model_context(node, parents):
+            continue
+        hits.extend(Hit(path, node.lineno, model) for model in _extract_models(node.value))
+    return hits
+
+
+def _scan_text(path: Path) -> list[Hit]:
+    """Scan config/shell files for model-looking ids on model-looking lines."""
+    try:
+        lines = path.read_text().splitlines()
+    except UnicodeDecodeError:
+        return []
+
+    hits: list[Hit] = []
+    for line_number, line in enumerate(lines, start=1):
+        if line.lstrip().startswith("#"):
+            continue
+        if "model" not in line.lower():
+            continue
+        hits.extend(Hit(path, line_number, model) for model in _extract_models(line))
+    return hits
+
+
+def scan(path: Path) -> list[Hit]:
+    """Return hardcoded model hits in ``path``."""
+    if (
+        not path.is_file()
+        or path.suffix not in SOURCE_EXTENSIONS
+        or any(part in SKIP_PARTS for part in path.parts)
+    ):
+        return []
+    if path.suffix == ".py":
+        return _scan_python(path)
+    if path.suffix in TEXT_EXTENSIONS:
+        return _scan_text(path)
+    return []
+
+
+def _iter_scannable_paths() -> list[Path]:
+    """Return every tracked source/config file in the lint surface."""
+    output = subprocess.check_output(
+        ["git", "ls-files", "-z", "--", *(root.as_posix() for root in SCAN_ROOTS)],
+    )
+    return [
+        path
+        for raw_path in output.decode().split("\0")
+        if raw_path
+        if (path := Path(raw_path)).suffix in SOURCE_EXTENSIONS
+        if not any(part in SKIP_PARTS for part in path.parts)
+    ]
+
+
+def _load_allowlist(path: Path = ALLOWLIST_PATH) -> Counter[tuple[str, str]]:
+    """Load allowed ``(path, model)`` occurrence counts."""
+    allowed: Counter[tuple[str, str]] = Counter()
+    if not path.exists():
+        return allowed
+    for line_number, raw_line in enumerate(path.read_text().splitlines(), start=1):
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        parts = line.split()
+        if len(parts) != 3:
+            raise ValueError(f"{path}:{line_number}: expected: <path> <model> <count>")
+        rel_path, model, count_text = parts
+        key = (rel_path, model)
+        if key in allowed:
+            raise ValueError(
+                f"{path}:{line_number}: duplicate baseline entry for {rel_path} {model}"
+            )
+        try:
+            allowed[key] = int(count_text)
+        except ValueError as exc:
+            raise ValueError(
+                f"{path}:{line_number}: count must be an integer, got {count_text!r}"
+            ) from exc
+    return allowed
+
+
+def _find_new_hits(hits: list[Hit], allowed: Counter[tuple[str, str]]) -> list[Hit]:
+    """Return hits whose path/model count exceeds the curated baseline."""
+    seen: Counter[tuple[str, str]] = Counter()
+    new_hits: list[Hit] = []
+    for hit in hits:
+        key = (_repo_relative(hit.path), hit.model)
+        seen[key] += 1
+        if seen[key] > allowed[key]:
+            new_hits.append(hit)
+    return new_hits
+
+
+def _find_stale_allowances(
+    hits: list[Hit],
+    allowed: Counter[tuple[str, str]],
+) -> Counter[tuple[str, str]]:
+    """Return baseline counts that exceed the current scan results."""
+    actual = Counter((_repo_relative(hit.path), hit.model) for hit in hits)
+    return allowed - actual
+
+
+def main() -> int:
+    """Scan the full supported surface and require an exact baseline."""
+    paths = _iter_scannable_paths()
+    hits = [hit for path in paths for hit in scan(path)]
+    allowed = _load_allowlist()
+    new_hits = _find_new_hits(hits, allowed)
+    stale_allowances = _find_stale_allowances(hits, allowed)
+    if not new_hits and not stale_allowances:
+        return 0
+
+    for hit in new_hits:
+        sys.stdout.write(
+            f"{hit.path}:{hit.line}: hardcoded model id `{hit.model}`; "
+            "resolve from the configured provider/model catalog instead\n"
+        )
+    for (path, model), stale_count in sorted(stale_allowances.items()):
+        actual_count = allowed[(path, model)] - stale_count
+        sys.stdout.write(
+            f"{ALLOWLIST_PATH}: stale allowance for `{model}` in {path}: "
+            f"allows {allowed[(path, model)]}, found {actual_count}; "
+            "lower or remove the baseline entry\n"
+        )
+    sys.stdout.write(
+        "\nAvoid adding hardcoded model names outside tests. If this is an intentional "
+        "temporary pin, document why and update dev/lint/hardcoded_model_allowlist.txt "
+        "with the smallest path/model count.\n"
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dev/omnidev/README.md

@@ -1,18 +1,21 @@
 # omnidev
 
-Dev tooling for Omnigent, in one binary with two independent capabilities:
+Dev tooling for Omnigent, in one binary with three surfaces:
 
 1. A per-repo dev **pod supervisor** (bare `omnidev`) — the default.
-2. **Install management** (`omnidev install`/`update`/`check`) — install and
-   keep a git-based omnigent up to date. See
+2. **Install management** (`omnidev install`/`update`/`check`) — install
+   and keep a git-based omnigent up to date. See
    [Managing your omnigent install](#managing-your-omnigent-install). These
-   subcommands need no checkout and run anywhere.
+   need no checkout and run anywhere.
+3. **An omnigent passthrough** (`omnidev omnigent …`) — run any omnigent command
+   against the current checkout's pod, with the pod's isolated env applied.
+   See [Running omnigent commands](#running-omnigent-commands).
 
 ## Pod supervisor
 
 A per-repo dev **pod** supervisor, as a single long-running terminal UI. It
 replaces the three-terminal local dev flow (`omnigent server`, `omnigent host`,
-`npm run dev`) with one process that:
+`pnpm run dev`) with one process that:
 
 - runs each checkout in an **isolated pod** — its own state dir, database,
   artifacts, logs, and auto-allocated ports — so multiple worktrees never
@@ -28,7 +31,7 @@ replaces the three-terminal local dev flow (`omnigent server`, `omnigent host`,
 
 ## Build & run
 
-Requires the repo's usual dev prerequisites (`uv` for Python, `npm` for the
+Requires the repo's usual dev prerequisites (`uv` for Python, `pnpm` for the
 web UI) plus a Rust toolchain.
 
 ```bash
@@ -47,9 +50,9 @@ Run it from anywhere inside the checkout — it walks up to the repo root
 |---|---|---|
 | server | `uv run omnigent --log-to-stderr server --host 127.0.0.1 --port <p> --database-uri … --artifact-location …` | Waited on via `GET /health`. |
 | host   | `uv run omnigent --log-to-stderr host --server http://127.0.0.1:<p>` | Started once the server is healthy. |
-| vite   | `npm run dev -- --host <host> --port <p> --strictPort` (cwd `web/`) | `OMNIGENT_URL` points its proxy at the pod's server. |
+| vite   | `pnpm run dev -- --host <host> --port <p> --strictPort` (cwd `web/`) | `OMNIGENT_URL` points its proxy at the pod's server. |
 
-Before Vite starts (and on a manual Vite restart), omnidev runs `npm install`
+Before Vite starts (and on a manual Vite restart), omnidev runs `pnpm install`
 in `web/` when needed — `node_modules/` is missing, or `package.json` /
 `package-lock.json` is newer than it — so a fresh checkout or a new dependency
 doesn't make Vite fail its dependency scan. Output streams into the `vite` pane.
@@ -62,7 +65,7 @@ Only Omnigent's own state is isolated per pod — enough that concurrent pods
 never share a database, server pidfile, or `config.yaml` — via
 `OMNIGENT_DATA_DIR`, `OMNIGENT_DATABASE_URI`, `OMNIGENT_URL`, and
 `OMNIGENT_CONFIG_HOME`. Everything else (your real `HOME`, credentials, and
-uv/npm caches) is inherited, because the agents Omnigent runs need it. This is
+uv/pnpm caches) is inherited, because the agents Omnigent runs need it. This is
 deliberately lighter than the hermetic `scripts/backend-smoke.sh` sandbox,
 which repoints `HOME`/`XDG_*` to touch nothing real.
 
@@ -138,6 +141,34 @@ feel familiar.
 | `c` | Clear the focused pane |
 | `q` / `Ctrl-C` | Quit and tear down all processes |
 
+## Running omnigent commands
+
+`omnidev omnigent …` runs any omnigent command against the current checkout's
+pod, via `uv run omnigent …`, with the pod's isolated env applied
+(`OMNIGENT_DATA_DIR`, `OMNIGENT_DATABASE_URI`, `OMNIGENT_CONFIG_HOME`,
+`OMNIGENT_URL`). It resolves the same repo root and pod dir the supervisor
+uses, so a command talks to the pod's database and config — and `OMNIGENT_URL`
+points at a running supervisor's server when one is up.
+
+```bash
+omnidev omnigent agent run "fix the flaky test"
+omnidev omnigent config show
+omnidev --pod-dir /tmp/x omnigent agent list   # target a specific pod
+```
+
+Everything after the subcommand is forwarded verbatim to omnigent. It runs in
+the foreground (inheriting your stdio) and exits with omnigent's status code.
+It acquires **no** lock, so it coexists with a running supervisor — the common
+case: the server is up and you issue a command against it. Use `--` to pass
+flags that look like omnidev's own:
+
+```bash
+omnidev omnigent -- --verbose agent run …
+```
+
+Supervisor-only flags (`--server-port`, `--clean`, `--no-vite`, …) don't apply
+to the passthrough; only `--pod-dir` is shared.
+
 ## Managing your omnigent install
 
 For people who *run* omnigent (installed from git via `uv tool install`) rather
@@ -145,8 +176,8 @@ than develop it. This wraps the fiddly PEP 508 install syntax and adds a daily
 update check — filling a gap, since omnigent's own update notice only works for
 PyPI-wheel installs and skips git installs.
 
-These subcommands manage the global tool and work from **any directory** (no
-checkout needed).
+These subcommands manage the global tool and work from **any directory**
+(no checkout needed).
 
 ```
 omnidev install     # uv tool install omnigent from git (databricks extra, main)
@@ -161,9 +192,9 @@ omnidev shell-hook  # print the daily-check snippet for your shell rc
 extras), `--repo <url>`. The choice is saved to
 `${XDG_CONFIG_HOME:-~/.config}/omnidev/install.toml` so `update` reuses it.
 
-Installing from git **builds the web UI from source**, so Node 22+/npm must be
+Installing from git **builds the web UI from source**, so Node 22+/pnpm must be
 on PATH (the PyPI wheel ships the UI prebuilt; the git install does not).
-`omnidev install` fails early with a clear message if `uv` or `npm` is missing.
+`omnidev install` fails early with a clear message if `uv` or `pnpm` is missing.
 
 ### Daily update check
 
@@ -185,6 +216,6 @@ result (`${XDG_CACHE_HOME:-~/.cache}/omnidev/omnigent-check.json`) and, when
 stale (>24h), refreshes it in a detached background process — so shell startup
 never blocks on the network. When a newer commit is available it prints a notice
 and, on a terminal, prompts `Update omnigent now? [y/N]`; on yes it runs
-`omnidev update` in the foreground. Declining suppresses that same commit until a
-newer one lands. Set `OMNIGENT_NO_UPDATE_CHECK` in your environment if you want
+`omnidev update` in the foreground. Declining suppresses that same commit until
+a newer one lands. Set `OMNIGENT_NO_UPDATE_CHECK` in your environment if you want
 to silence omnigent's own separate notice.

dev/omnidev/src/install.rs

@@ -73,16 +73,17 @@ impl InstallConfig {
 }
 
 /// Fail early with a clear message if the toolchain a git install needs is
-/// missing. Installing from git builds the web UI from source (Node/npm),
+/// missing. Installing from git builds the web UI from source (Node/pnpm),
 /// unlike the PyPI wheel which ships it prebuilt.
 fn preflight() -> Result<()> {
     if which("uv").is_none() {
         bail!("`uv` is not on PATH. Install it first: https://docs.astral.sh/uv/");
     }
-    if which("npm").is_none() {
+    if which("pnpm").is_none() {
         bail!(
-            "`npm` is not on PATH. Installing omnigent from git builds the web UI \
-             from source and needs Node 22+/npm. Install Node, then retry."
+            "`pnpm` is not on PATH. Installing omnigent from git builds the web UI \
+             from source and needs Node 22+/pnpm. Install Node (pnpm is \
+             available via `corepack enable` or `npm install -g pnpm`), then retry."
         );
     }
     Ok(())

dev/omnidev/src/main.rs

@@ -1,12 +1,15 @@
 //! omnidev — dev tooling for Omnigent.
 //!
-//! Two independent capabilities in one binary:
+//! Three surfaces in one binary:
 //! - **pod supervisor** (bare `omnidev`): manages an isolated dev instance for
 //!   the current checkout — server/host/vite, restarting the backend on Python
 //!   changes while Vite handles frontend HMR.
 //! - **install management** (`omnidev install`/`update`/`check`/…): install and
 //!   keep a git-based omnigent up to date. These need no checkout and run
 //!   anywhere.
+//! - **omnigent passthrough** (`omnidev omnigent …`): run any omnigent command
+//!   against the current checkout's pod via `uv run omnigent …`, with the pod's
+//!   isolated env applied. Requires a checkout, like the supervisor.
 
 mod install;
 mod lan;
@@ -14,6 +17,7 @@ mod lock;
 mod logs;
 mod paths;
 mod pod;
+mod omnigent_cmd;
 mod ports;
 mod process;
 mod shellhook;
@@ -46,6 +50,50 @@ struct Args {
     run: RunArgs,
 }
 
+/// Top-level subcommands. Install management works anywhere; the `omnigent`
+/// passthrough requires a checkout (like the bare supervisor default).
+#[derive(Subcommand, Debug)]
+enum Command {
+    /// Install omnigent from git (defaults to the databricks extra, main).
+    Install {
+        /// Git ref (branch/tag/sha) to track.
+        #[arg(long, default_value = install::DEFAULT_REF)]
+        r#ref: String,
+        /// Extra to include (repeatable). Defaults to `databricks`.
+        #[arg(long = "extra")]
+        extras: Vec<String>,
+        /// Omit the default databricks extra (install with no extras).
+        #[arg(long)]
+        no_default_extra: bool,
+        /// Git repo URL.
+        #[arg(long, default_value = install::DEFAULT_REPO)]
+        repo: String,
+    },
+    /// Reinstall the latest of the tracked ref/extras.
+    Update,
+    /// Check for an omnigent update (the shell hook calls this).
+    Check {
+        /// Print nothing when already up to date.
+        #[arg(long)]
+        quiet: bool,
+    },
+    /// Refresh the update-check cache from the network (usually run detached).
+    Refresh,
+    /// Print a shell snippet to eval from .zshrc/.bashrc for daily checks.
+    ShellHook,
+    /// Run an omnigent command against this checkout's pod (`uv run omnigent …`).
+    ///
+    /// Everything after the subcommand is forwarded verbatim to omnigent. The
+    /// pod's isolated env (data dir, database, config, server URL) is applied,
+    /// so a command talks to the same pod the supervisor runs — and coexists
+    /// with a running supervisor. Use `--` to pass flags that look like
+    /// omnidev's own: `omnidev omnigent -- --verbose agent run …`.
+    Omnigent {
+        #[arg(num_args = 0.., trailing_var_arg = true, allow_hyphen_values = true)]
+        args: Vec<String>,
+    },
+}
+
 /// Flags for the default (no-subcommand) pod-supervisor run.
 #[derive(clap::Args, Debug)]
 struct RunArgs {
@@ -84,42 +132,12 @@ struct RunArgs {
     debug: bool,
 }
 
-#[derive(Subcommand, Debug)]
-enum Command {
-    /// Install omnigent from git (defaults to the databricks extra, main).
-    Install {
-        /// Git ref (branch/tag/sha) to track.
-        #[arg(long, default_value = install::DEFAULT_REF)]
-        r#ref: String,
-        /// Extra to include (repeatable). Defaults to `databricks`.
-        #[arg(long = "extra")]
-        extras: Vec<String>,
-        /// Omit the default databricks extra (install with no extras).
-        #[arg(long)]
-        no_default_extra: bool,
-        /// Git repo URL.
-        #[arg(long, default_value = install::DEFAULT_REPO)]
-        repo: String,
-    },
-    /// Reinstall the latest of the tracked ref/extras.
-    Update,
-    /// Check for an omnigent update (the shell hook calls this).
-    Check {
-        /// Print nothing when already up to date.
-        #[arg(long)]
-        quiet: bool,
-    },
-    /// Refresh the update-check cache from the network (usually run detached).
-    Refresh,
-    /// Print a shell snippet to eval from .zshrc/.bashrc for daily checks.
-    ShellHook,
-}
-
 fn main() -> Result<()> {
     let args = Args::parse();
 
     // Install-management subcommands manage a global tool and must work from
-    // anywhere — dispatch them before any checkout discovery.
+    // anywhere — dispatch them before any checkout discovery. `omnigent …` is
+    // the pod-wired passthrough. No subcommand runs the pod supervisor.
     match args.command {
         Some(Command::Install {
             r#ref,
@@ -148,10 +166,43 @@ fn main() -> Result<()> {
             shellhook::print();
             Ok(())
         }
+        Some(Command::Omnigent { args: passthrough }) => run_omnigent(args.run, passthrough),
         None => run_supervisor(args.run),
     }
 }
 
+/// `omnidev omnigent …` — run an arbitrary omnigent command against this
+/// checkout's pod via `uv run omnigent …`, with the pod's isolated env (data
+/// dir, database URI, config home, server URL) applied on top of the inherited
+/// parent env. Resolves the repo root and pod dir (same as the supervisor),
+/// ensures the pod tree exists, then spawns in the foreground inheriting stdio.
+/// Exits with omnigent's status code. Acquires no lock — it coexists with a
+/// running supervisor (the common case: server up, you run a command).
+fn run_omnigent(args: RunArgs, passthrough: Vec<String>) -> Result<()> {
+    let cwd = std::env::current_dir()?;
+    let repo_root = paths::find_repo_root(&cwd)?;
+    let pod_dir = match &args.pod_dir {
+        Some(p) => p.clone(),
+        None => paths::default_pod_dir(&repo_root)?,
+    };
+    std::fs::create_dir_all(&pod_dir)?;
+
+    // Read persisted ports so OMNIGENT_URL points at a running supervisor's
+    // server (if any). Supervisor-only flags don't apply to the passthrough, so
+    // never override — the pod stays in sync with whatever the supervisor set.
+    let ports = Ports::resolve(&pod_dir, None, None)?;
+    let pod = Pod::create(
+        repo_root,
+        pod_dir,
+        ports,
+        args.vite_host.clone(),
+        Vec::new(),
+    )?;
+
+    let cmd = omnigent_cmd::build(&pod, &passthrough);
+    omnigent_cmd::run(cmd)
+}
+
 /// Default path: the pod supervisor for the current checkout. This is the only
 /// path that requires an Omnigent checkout.
 #[tokio::main]

dev/omnidev/src/omnigent_cmd.rs

@@ -0,0 +1,148 @@
+//! `omnidev omnigent …` — run an arbitrary omnigent command against this
+//! checkout's pod via `uv run omnigent …`.
+//!
+//! Unlike the supervised `process::ProcSpec`s, this runs in the foreground
+//! (inheriting the user's stdio) and does *not* inject the log-mirror env
+//! (`OMNIGENT_LOG_TTY_FD` / `OMNIGENT_LOG_FORCE_COLOR`): the user has a real
+//! TTY, so omnigent's own terminal detection should win. The pod's isolation
+//! env (`OMNIGENT_DATA_DIR`, `OMNIGENT_DATABASE_URI`, `OMNIGENT_CONFIG_HOME`,
+//! `OMNIGENT_URL`) is applied on top of the inherited parent env, so a command
+//! talks to the same pod the supervisor runs.
+
+use std::path::PathBuf;
+
+use crate::pod::Pod;
+
+/// A resolved `uv run omnigent …` invocation for the passthrough subcommand.
+pub struct OmnigentCmd {
+    pub program: String,
+    pub args: Vec<String>,
+    pub env: Vec<(String, String)>,
+    pub cwd: PathBuf,
+}
+
+/// Build the command line + env for `uv run omnigent <passthrough…>` rooted at
+/// the pod's repo, with the pod's `OMNIGENT_*` overrides applied.
+pub fn build(pod: &Pod, passthrough: &[String]) -> OmnigentCmd {
+    let mut args = vec!["run".to_string(), "omnigent".to_string()];
+    args.extend_from_slice(passthrough);
+    OmnigentCmd {
+        program: "uv".into(),
+        args,
+        env: pod.env(),
+        cwd: pod.repo_root.clone(),
+    }
+}
+
+/// Spawn the command in the foreground, inheriting stdio, and exit with its
+/// status code. A spawn failure returns an error instead of exiting.
+pub fn run(cmd: OmnigentCmd) -> anyhow::Result<()> {
+    let mut command = std::process::Command::new(&cmd.program);
+    command.args(&cmd.args).current_dir(&cmd.cwd);
+    for (k, v) in &cmd.env {
+        command.env(k, v);
+    }
+    let status = command.status()?;
+    std::process::exit(status.code().unwrap_or(1));
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::ports::Ports;
+
+    fn tempdir() -> PathBuf {
+        let unique = format!(
+            "omnidev-omnigent-cmd-test-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        );
+        let dir = std::env::temp_dir().join(unique);
+        std::fs::create_dir_all(&dir).unwrap();
+        dir
+    }
+
+    fn make_pod() -> Pod {
+        Pod::create(
+            tempdir(),
+            tempdir(),
+            Ports {
+                server: 19191,
+                vite: 19292,
+            },
+            "127.0.0.1".into(),
+            Vec::new(),
+        )
+        .unwrap()
+    }
+
+    #[test]
+    fn forwards_passthrough_args_after_uv_run_omnigent() {
+        let pod = make_pod();
+        let cmd = build(
+            &pod,
+            &["agent".into(), "run".into(), "fix tests".into()],
+        );
+        assert_eq!(cmd.program, "uv");
+        assert_eq!(
+            cmd.args.iter().map(String::as_str).collect::<Vec<_>>(),
+            vec!["run", "omnigent", "agent", "run", "fix tests"]
+        );
+        assert_eq!(cmd.cwd, pod.repo_root);
+    }
+
+    #[test]
+    fn empty_passthrough_is_just_uv_run_omnigent() {
+        let pod = make_pod();
+        let cmd = build(&pod, &[]);
+        assert_eq!(
+            cmd.args.iter().map(String::as_str).collect::<Vec<_>>(),
+            vec!["run", "omnigent"]
+        );
+    }
+
+    #[test]
+    fn applies_pod_isolation_env() {
+        let pod = make_pod();
+        let cmd = build(&pod, &["config".into(), "show".into()]);
+
+        let data_dir = cmd
+            .env
+            .iter()
+            .find(|(k, _)| k == "OMNIGENT_DATA_DIR")
+            .map(|(_, v)| v.clone());
+        assert_eq!(
+            data_dir,
+            Some(pod.dir.join("data/omnigent").display().to_string())
+        );
+
+        let url = cmd
+            .env
+            .iter()
+            .find(|(k, _)| k == "OMNIGENT_URL")
+            .map(|(_, v)| v.clone());
+        assert_eq!(url, Some(pod.server_url()));
+
+        let db = cmd
+            .env
+            .iter()
+            .find(|(k, _)| k == "OMNIGENT_DATABASE_URI")
+            .map(|(_, v)| v.clone());
+        assert_eq!(db, Some(pod.db_uri()));
+    }
+
+    #[test]
+    fn omits_log_mirror_env() {
+        let pod = make_pod();
+        let cmd = build(&pod, &["host".into()]);
+        assert!(cmd.env.iter().find(|(k, _)| k == "OMNIGENT_LOG_TTY_FD").is_none());
+        assert!(cmd
+            .env
+            .iter()
+            .find(|(k, _)| k == "OMNIGENT_LOG_FORCE_COLOR")
+            .is_none());
+    }
+}

dev/omnidev/src/pod.rs

@@ -90,11 +90,11 @@ impl Pod {
         self.repo_root.join("web")
     }
 
-    /// Whether `web/` needs `npm install` before Vite can start: either
+    /// Whether `web/` needs `pnpm install` before Vite can start: either
     /// `node_modules/` is absent, or the lockfile / `package.json` is newer
     /// than the installed tree (a dependency was added/changed since the last
     /// install — the case that makes Vite's dependency scan fail).
-    pub fn needs_npm_install(&self) -> bool {
+    pub fn needs_pnpm_install(&self) -> bool {
         let web = self.web_dir();
         let modules = web.join("node_modules");
         if !modules.is_dir() {
@@ -105,7 +105,7 @@ impl Pod {
             return true;
         };
         // Reinstall if either manifest is newer than node_modules.
-        [web.join("package-lock.json"), web.join("package.json")]
+        [self.repo_root.join("pnpm-lock.yaml"), web.join("package.json")]
             .into_iter()
             .filter_map(mtime)
             .any(|t| t > installed)
@@ -123,7 +123,7 @@ impl Pod {
     /// The env overrides applied on top of the inherited parent env for every
     /// child. We isolate omnigent's own state — the DB, data dir, and config
     /// home — so concurrent pods don't share a database, pidfile, or
-    /// `config.yaml`. The rest (real `HOME`, credentials, uv/npm caches) is
+    /// `config.yaml`. The rest (real `HOME`, credentials, uv/pnpm caches) is
     /// inherited, since the agents omnigent runs need it. `OMNIGENT_URL` is the
     /// seam `web/vite.config.ts` reads to point its proxy at this pod's backend;
     /// `OMNIGENT_CONFIG_HOME` is where the server/host/runner read `config.yaml`.

dev/omnidev/src/process.rs

@@ -66,32 +66,22 @@ impl ProcSpec {
         }
     }
 
-    /// `npm install`, from `web/`. Run before Vite when deps are missing or
+    /// `pnpm install`, from `web/`. Run before Vite when deps are missing or
     /// stale so Vite's dependency scan doesn't fail on an unresolved import.
-    ///
-    /// `--loglevel http` makes npm emit a line per package fetch even when its
-    /// stdout is piped (its progress bar is TTY-only), so the pane streams real
-    /// progress. `--no-fund --no-audit` trims the trailing noise.
-    pub fn npm_install(pod: &Pod) -> ProcSpec {
+    pub fn pnpm_install(pod: &Pod) -> ProcSpec {
         ProcSpec {
-            program: "npm".into(),
-            args: vec![
-                "install".into(),
-                "--no-fund".into(),
-                "--no-audit".into(),
-                "--loglevel".into(),
-                "http".into(),
-            ],
+            program: "pnpm".into(),
+            args: vec!["install".into()],
             cwd: pod.web_dir(),
             extra_env: Vec::new(),
         }
     }
 
-    /// `npm run dev -- --host <host> --port <p> --strictPort`, from `web/`.
+    /// `pnpm run dev -- --host <host> --port <p> --strictPort`, from `web/`.
     /// `OMNIGENT_URL` (in the pod env) points Vite's proxy at this pod's backend.
     pub fn vite(pod: &Pod) -> ProcSpec {
         ProcSpec {
-            program: "npm".into(),
+            program: "pnpm".into(),
             args: vec![
                 "run".into(),
                 "dev".into(),

dev/omnidev/src/supervisor.rs

@@ -217,7 +217,7 @@ impl Supervisor {
             .stderr(Stdio::piped())
             .kill_on_drop(false);
         // Become a session/group leader so we can signal the whole tree
-        // (uvicorn workers, npm -> vite children) via the negative pgid.
+        // (uvicorn workers, pnpm -> vite children) via the negative pgid.
         unsafe {
             cmd.pre_exec(|| {
                 libc::setsid();
@@ -272,23 +272,23 @@ impl Supervisor {
         });
     }
 
-    /// Run `npm install` to completion before Vite starts, but only when deps
+    /// Run `pnpm install` to completion before Vite starts, but only when deps
     /// are missing or stale — otherwise Vite's dependency scan fails on an
     /// unresolved import (e.g. a dep added to package.json but not installed).
     /// Output streams into the Vite pane. A failed/absent install is logged but
-    /// non-fatal: we still let Vite try, so a transient npm hiccup doesn't block
+    /// non-fatal: we still let Vite try, so a transient pnpm hiccup doesn't block
     /// the whole session.
     async fn prepare_vite(&self) {
-        if !self.pod.needs_npm_install() {
+        if !self.pod.needs_pnpm_install() {
             return;
         }
         self.set_status(ProcId::Vite, ProcStatus::Starting);
         self.shared.lock().unwrap().log_proc(
             ProcId::Vite,
-            "web deps missing or stale — running npm install".into(),
+            "web deps missing or stale — running pnpm install".into(),
         );
 
-        let spec = ProcSpec::npm_install(&self.pod);
+        let spec = ProcSpec::pnpm_install(&self.pod);
         let mut cmd = Command::new(&spec.program);
         cmd.args(&spec.args)
             .current_dir(&spec.cwd)
@@ -304,7 +304,7 @@ impl Supervisor {
                 self.shared
                     .lock()
                     .unwrap()
-                    .log_proc(ProcId::Vite, format!("failed to run npm install: {e}"));
+                    .log_proc(ProcId::Vite, format!("failed to run pnpm install: {e}"));
                 return;
             }
         };
@@ -315,9 +315,7 @@ impl Supervisor {
             self.pump(ProcId::Vite, err);
         }
 
-        // `--loglevel http` streams a line per package fetch, but npm still
-        // goes quiet during the final tree-build/link phase. A slow heartbeat
-        // covers those gaps so the pane never looks frozen.
+        // A slow heartbeat covers quiet phases so the pane never looks frozen.
         let started = Instant::now();
         let mut heartbeat = tokio::time::interval(Duration::from_secs(5));
         heartbeat.tick().await; // the first tick fires immediately; skip it
@@ -329,17 +327,17 @@ impl Supervisor {
                     self.shared
                         .lock()
                         .unwrap()
-                        .log_proc(ProcId::Vite, format!("… npm install running ({secs}s)"));
+                        .log_proc(ProcId::Vite, format!("… pnpm install running ({secs}s)"));
                 }
             }
         };
         match status {
             Ok(s) if s.success() => self.event(format!(
-                "npm install complete ({}s)",
+                "pnpm install complete ({}s)",
                 started.elapsed().as_secs()
             )),
-            Ok(s) => self.event(format!("npm install exited {s} — starting Vite anyway")),
-            Err(e) => self.event(format!("npm install wait error: {e}")),
+            Ok(s) => self.event(format!("pnpm install exited {s} — starting Vite anyway")),
+            Err(e) => self.event(format!("pnpm install wait error: {e}")),
         }
     }
 

docs/AGENT_YAML_SPEC.md

@@ -203,6 +203,40 @@ same YAML works across platforms. For the full set of sandbox options, how to
 share one policy across `sys_os_*` and terminals, and how to set up network
 egress rules, see the `sandbox:` examples below and the sandbox source under `omnigent/inner/`.
 
+### Secretless credential proxy
+
+`sandbox.credential_proxy` lets sandboxed tools authenticate to external hosts
+without the real secret ever entering the sandbox: the mandatory L7 egress proxy
+attaches the credential on the way out. It requires `egress_rules` and a
+network-isolating backend (`linux_bwrap` or `darwin_seatbelt`). See
+`designs/SANDBOX_CREDENTIAL_PROXY.md` for the full type table.
+
+The `databricks_cli` type proxies the Databricks CLI. List the profiles to
+proxy; only those are materialized into the sandbox (with placeholder tokens)
+and swapped by the proxy. As with every other credential-proxy type, you must
+list each workspace host in `egress_rules` yourself — the proxy does not widen
+egress on its own. OAuth tokens are refreshed for the life of the session.
+Requires the `databricks` extra and `linux_bwrap` (the Go CLI ignores
+`SSL_CERT_FILE` on macOS, so `darwin_seatbelt` is rejected).
+
+```yaml
+os_env:
+  type: caller_process
+  cwd: .
+  sandbox:
+    type: linux_bwrap
+    egress_rules:
+      - "* pypi.org/**"                              # your other egress needs
+      - "* dbc-adb7b1a3-9097.cloud.databricks.com/**"  # the proxied workspace
+    credential_proxy:
+      - type: databricks_cli
+        profiles: [dbc-adb7b1a3-9097, oss]
+        default: dbc-adb7b1a3-9097   # optional; sets DATABRICKS_CONFIG_PROFILE
+```
+
+Inside the sandbox, `databricks --profile dbc-adb7b1a3-9097 current-user me`
+works; the sandbox holds only `oa_cred_*` placeholders, never a live token.
+
 ## Tools
 
 Tools are declared under `tools` by name.
@@ -260,11 +294,15 @@ Use `container_image` for new specs; `docker_image` remains accepted as a
 deprecated alias for backwards compatibility. Set `container_runtime: podman` to
 run the image with Podman instead of Docker.
 
+The runtime can also be set globally via the `OMNIGENT_CONTAINER_RUNTIME`
+environment variable (accepted values: `docker`, `podman`). The per-agent
+`container_runtime` YAML key takes precedence over the environment variable.
+
 ```yaml
 tools:
   sandbox:
     container_image: python:3.12-slim
-    container_runtime: podman  # optional; defaults to docker
+    container_runtime: podman  # optional; defaults to docker (or OMNIGENT_CONTAINER_RUNTIME)
 ```
 
 ### Sub-agent tool