feat: add Gemini CLI runner with polymorphic bridge and extensible registry (#788)

## Summary

- **Gemini CLI runner**: Full polymorphic bridge implementation that
wraps Google's Gemini CLI (`@google/gemini-cli`) as an AG-UI compatible
runner, alongside the existing Claude Agent SDK runner
- **Extensible agent registry**: Data-driven `AgentRuntimeSpec`
ConfigMap that replaces hardcoded runner configuration across operator,
backend, and frontend. Operator reads container image, resources, port,
state dir, and sandbox config from the registry
- **Unified `USE_VERTEX`**: Single environment variable replaces
`CLAUDE_CODE_USE_VERTEX` and `GEMINI_USE_VERTEX` with
backward-compatible deprecation warnings
- **Production hardening**: Subprocess timeouts, graceful
SIGTERM/SIGKILL shutdown, stderr streaming via deque ring buffer,
TTL-based worker eviction, MCP support for Gemini via
`.gemini/settings.json`
- **Frontend**: Runner type selection in create dialog, admin runtimes
page, loading/error states, Shadcn RadioGroup for settings, ARIA
accessibility
- **Feature flag auto-sync**: `runner.gemini-cli.enabled` in
`flags.json` for automatic Unleash provisioning

### Key architectural decisions
- All runners use sandbox mode (pod-per-session) with conditional
init/sidecar based on `sandbox.seed` and `sandbox.persistence` from
registry
- Capabilities come from the runner's `/capabilities` endpoint at
runtime, NOT from the registry
- Env var blocklist (not allowlist) for subprocess — user-defined vars
pass through automatically
- Session ID persisted to `.gemini/gemini_session_ids.json` for
`--resume` across pod restarts
- `GOOGLE_GENAI_USE_VERTEXAI=true` set in subprocess env for Vertex AI
mode

## Test plan
- [x] 165+ new Python tests (adapter, bridge, session, auth, registry)
- [x] Go backend tests (registry cache, routing, feature gates)
- [x] Go operator tests (conditional pod components, registry fallback)
- [x] Manual E2E: Gemini CLI sessions with API key auth on OpenShift
cluster
- [ ] Manual E2E: Vertex AI auth mode
- [ ] Manual E2E: MCP servers (Jira, GitHub) with Gemini CLI


Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Gkrumbach07

.claude/commands/jira.log.md

@@ -199,7 +199,7 @@ Steps:
 Expected: Session disappears from list
 Actual: Session remains until page refresh
 
-Repo: vTeam  
+Repo: vTeam
 Files: components/frontend/src/components/session-list/
 Browser: Chrome 120, Firefox 121
 
@@ -215,7 +215,7 @@ Current queries use deprecated `onSuccess` callbacks.
 Need to migrate to the new `select` and mutation patterns.
 
 Repo: vTeam
-Files: 
+Files:
 - components/frontend/src/services/queries/sessions.ts
 - components/frontend/src/hooks/
 
@@ -259,7 +259,7 @@ For a Jira to be immediately actionable by an agent, ensure:
 
 **✅ Good (agent can start immediately):**
 > "Fix login redirect loop on Safari"
-> 
+>
 > **Steps**: 1. Open Safari 2. Click Login 3. Observe infinite redirect
 > **Expected**: Redirect to dashboard
 > **Actual**: Loops back to login

.claude/commands/speckit.implement.md

@@ -104,7 +104,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 6. Execute implementation following the task plan:
    - **Phase-by-phase execution**: Complete each phase before moving to the next
-   - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together  
+   - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together
    - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
    - **File-based coordination**: Tasks affecting the same files must run sequentially
    - **Validation checkpoints**: Verify each phase completion before proceeding

.claude/commands/speckit.specify.md

@@ -29,27 +29,27 @@ Given that feature description, do this:
      - "Fix payment processing timeout bug" → "fix-payment-timeout"
 
 2. **Check for existing branches before creating new one**:
-   
+
    a. First, fetch all remote branches to ensure we have the latest information:
       ```bash
       git fetch --all --prune
       ```
-   
+
    b. Find the highest feature number across all sources for the short-name:
       - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'`
       - Local branches: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'`
       - Specs directories: Check for directories matching `specs/[0-9]+-<short-name>`
-   
+
    c. Determine the next available number:
       - Extract all numbers from all three sources
       - Find the highest number N
       - Use N+1 for the new branch number
-   
+
    d. Run the script `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"` with the calculated number and short-name:
       - Pass `--number N+1` and `--short-name "your-short-name"` along with the feature description
       - Bash example: `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" --json --number 5 --short-name "user-auth" "Add user authentication"`
       - PowerShell example: `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" -Json -Number 5 -ShortName "user-auth" "Add user authentication"`
-   
+
    **IMPORTANT**:
    - Check all three sources (remote branches, local branches, specs directories) to find the highest number
    - Only match branches/directories with the exact short-name pattern
@@ -95,20 +95,20 @@ Given that feature description, do this:
 
       ```markdown
       # Specification Quality Checklist: [FEATURE NAME]
-      
+
       **Purpose**: Validate specification completeness and quality before proceeding to planning
       **Created**: [DATE]
       **Feature**: [Link to spec.md]
-      
+
       ## Content Quality
-      
+
       - [ ] No implementation details (languages, frameworks, APIs)
       - [ ] Focused on user value and business needs
       - [ ] Written for non-technical stakeholders
       - [ ] All mandatory sections completed
-      
+
       ## Requirement Completeness
-      
+
       - [ ] No [NEEDS CLARIFICATION] markers remain
       - [ ] Requirements are testable and unambiguous
       - [ ] Success criteria are measurable
@@ -117,16 +117,16 @@ Given that feature description, do this:
       - [ ] Edge cases are identified
       - [ ] Scope is clearly bounded
       - [ ] Dependencies and assumptions identified
-      
+
       ## Feature Readiness
-      
+
       - [ ] All functional requirements have clear acceptance criteria
       - [ ] User scenarios cover primary flows
       - [ ] Feature meets measurable outcomes defined in Success Criteria
       - [ ] No implementation details leak into specification
-      
+
       ## Notes
-      
+
       - Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
       ```
 
@@ -151,20 +151,20 @@ Given that feature description, do this:
 
            ```markdown
            ## Question [N]: [Topic]
-           
+
            **Context**: [Quote relevant spec section]
-           
+
            **What we need to know**: [Specific question from NEEDS CLARIFICATION marker]
-           
+
            **Suggested Answers**:
-           
+
            | Option | Answer | Implications |
            |--------|--------|--------------|
            | A      | [First suggested answer] | [What this means for the feature] |
            | B      | [Second suggested answer] | [What this means for the feature] |
            | C      | [Third suggested answer] | [What this means for the feature] |
            | Custom | Provide your own answer | [Explain how to provide custom input] |
-           
+
            **Your choice**: _[Wait for user response]_
            ```
 

.claude/commands/speckit.tasks.md

@@ -77,7 +77,7 @@ Every task MUST strictly follow this format:
 4. **[Story] label**: REQUIRED for user story phase tasks only
    - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
    - Setup phase: NO story label
-   - Foundational phase: NO story label  
+   - Foundational phase: NO story label
    - User Story phases: MUST have story label
    - Polish phase: NO story label
 5. **Description**: Clear action with exact file path

.claude/skills/dev-cluster/README.md

@@ -110,7 +110,7 @@ The skill understands all platform components:
 | Backend | `components/backend` | `vteam_backend:latest` | API server |
 | Frontend | `components/frontend` | `vteam_frontend:latest` | Web UI |
 | Operator | `components/operator` | `vteam_operator:latest` | K8s operator |
-| Runner | `components/runners/claude-code-runner` | `vteam_claude_runner:latest` | Claude Code runner |
+| Runner | `components/runners/ambient-runner` | `vteam_claude_runner:latest` | Claude Code runner |
 | State Sync | `components/runners/state-sync` | `vteam_state_sync:latest` | S3 persistence |
 | Public API | `components/public-api` | `vteam_public_api:latest` | External API |
 

.claude/skills/dev-cluster/SKILL.md

@@ -24,7 +24,7 @@ The Ambient Code Platform consists of these containerized components:
 | **Backend** | `components/backend` | `vteam_backend:latest` | Go API for K8s CRD management |
 | **Frontend** | `components/frontend` | `vteam_frontend:latest` | NextJS web interface |
 | **Operator** | `components/operator` | `vteam_operator:latest` | Kubernetes operator (Go) |
-| **Runner** | `components/runners/claude-code-runner` | `vteam_claude_runner:latest` | Python Claude Code runner |
+| **Runner** | `components/runners/ambient-runner` | `vteam_claude_runner:latest` | Python Claude Code runner |
 | **State Sync** | `components/runners/state-sync` | `vteam_state_sync:latest` | S3 persistence service |
 | **Public API** | `components/public-api` | `vteam_public_api:latest` | External API gateway |
 
@@ -146,7 +146,7 @@ Determine which components are affected:
 - Changes in `components/backend/` → backend
 - Changes in `components/frontend/` → frontend
 - Changes in `components/operator/` → operator
-- Changes in `components/runners/claude-code-runner/` → runner
+- Changes in `components/runners/ambient-runner/` → runner
 - Changes in `components/runners/state-sync/` → state-sync
 - Changes in `components/public-api/` → public-api
 
@@ -655,4 +655,4 @@ This skill knows all the relevant Makefile targets in /workspace/repos/platform:
 - `make local-status` - Check pod status
 - `make local-logs-backend` - Follow backend logs
 - `make local-logs-frontend` - Follow frontend logs
-- `make local-logs-operator` - Follow operator logs
+- `make local-logs-operator` - Follow operator logs

.github/ISSUE_TEMPLATE/bug_report.md

@@ -68,4 +68,4 @@ If applicable, add screenshots to help explain your problem.
 <!-- Maintainers will add appropriate labels -->
 - **Priority:** [low/medium/high/critical]
 - **Complexity:** [trivial/easy/medium/hard]
-- **Component:** [frontend/backend/operator/tools/docs]
+- **Component:** [frontend/backend/operator/tools/docs]

.github/ISSUE_TEMPLATE/documentation.md

@@ -93,4 +93,4 @@ assignees: []
 - **Priority:** [low/medium/high]
 - **Effort:** [S/M/L]
 - **Type:** [new-docs/update-docs/fix-docs]
-- **Audience:** [user/developer/operator]
+- **Audience:** [user/developer/operator]

.github/ISSUE_TEMPLATE/epic.md

@@ -64,4 +64,4 @@ This epic will be implemented through the following stories:
 
 ## 📝 Notes
 
-[Technical notes, architectural decisions, or implementation details]
+[Technical notes, architectural decisions, or implementation details]

.github/ISSUE_TEMPLATE/feature_request.md

@@ -8,7 +8,7 @@ assignees: []
 
 ## 🚀 Feature Description
 
-**Is your feature request related to a problem?** 
+**Is your feature request related to a problem?**
 A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
 
 **Describe the solution you'd like**
@@ -79,4 +79,4 @@ How will we measure the success of this feature?
 - **Priority:** [low/medium/high]
 - **Effort:** [S/M/L/XL]
 - **Component:** [frontend/backend/operator/tools/docs]
-- **Type:** [new-feature/enhancement/improvement]
+- **Type:** [new-feature/enhancement/improvement]